pub struct Engine { /* private fields */ }
Expand description
Start here! An execution engine. Contains information about things like globals, registered types, etc.
Implementations
sourceimpl Engine
impl Engine
sourcepub fn new(stdlib: impl StandardLibrary) -> Self
pub fn new(stdlib: impl StandardLibrary) -> Self
Creates a new engine.
sourcepub fn with_debug_options(
stdlib: impl StandardLibrary,
debug_options: DebugOptions
) -> Self
pub fn with_debug_options(
stdlib: impl StandardLibrary,
debug_options: DebugOptions
) -> Self
Creates a new engine with specific debug options.
Engine::new
creates an engine with Default
debug options, and should generally be
preferred unless you’re debugging the language’s internals.
Constructing the engine can fail if the standard library defines way too many methods.
sourcepub fn compile(
&mut self,
filename: impl AsRef<str>,
source: impl Into<String>
) -> Result<Script<'_>, Error>
pub fn compile(
&mut self,
filename: impl AsRef<str>,
source: impl Into<String>
) -> Result<Script<'_>, Error>
sourcepub fn start(
&mut self,
filename: impl AsRef<str>,
source: impl Into<String>
) -> Result<Fiber<'_>, Error>
pub fn start(
&mut self,
filename: impl AsRef<str>,
source: impl Into<String>
) -> Result<Fiber<'_>, Error>
sourcepub fn call<T>(
&mut self,
function: Value,
arguments: impl IntoIterator<Item = Value>
) -> Result<T, Error>where
T: TryFromValue,
pub fn call<T>(
&mut self,
function: Value,
arguments: impl IntoIterator<Item = Value>
) -> Result<T, Error>where
T: TryFromValue,
Calls the provided function with the given arguments.
Errors
Error::Runtime
- if a runtime error occurs -function
isn’t callable or an error is raised during executionError::TooManyArguments
- if more arguments than the implementation can support is passed to the function
sourcepub fn method_id(
&mut self,
signature: impl MethodSignature
) -> Result<MethodId, Error>
pub fn method_id(
&mut self,
signature: impl MethodSignature
) -> Result<MethodId, Error>
Returns the unique ID of a method with a given name and arity.
Note that there can only exist about 65 thousand unique method signatures. This is usually not a problem as method names often repeat. Also note that unlike functions, a method can only accept up to 256 arguments. Which, to be quite frankly honest, should be enough for anyone.
Errors
Error::TooManyMethods
- raised when too many unique method signatures exist at once
sourcepub fn call_method<T>(
&mut self,
receiver: Value,
signature: impl MethodSignature,
arguments: impl IntoIterator<Item = Value>
) -> Result<T, Error>where
T: TryFromValue,
pub fn call_method<T>(
&mut self,
receiver: Value,
signature: impl MethodSignature,
arguments: impl IntoIterator<Item = Value>
) -> Result<T, Error>where
T: TryFromValue,
Calls a method on a receiver with the given arguments.
Note that if you’re calling a method often, it’s cheaper to precompute the method signature
into a MethodId
by using the method_id
function, compared to
passing a name+arity pair every single time.
Errors
Error::Runtime
- if a runtime error occurs -function
isn’t callable or an error is raised during executionError::TooManyArguments
- if more arguments than the implementation can support is passed to the functionError::TooManyMethods
- if too many methods with different signatures exist at the same timeError::ArgumentCount
- ifarguments.count()
does not match the argument count of the signature
sourcepub fn global_id(&mut self, name: impl GlobalName) -> Result<GlobalId, Error>
pub fn global_id(&mut self, name: impl GlobalName) -> Result<GlobalId, Error>
Returns the unique global ID for the global with the given name, or an error if there are too many globals in scope.
The maximum amount of globals is about 16 million, so you shouldn’t worry too much about hitting that limit unless you’re stress-testing the VM or accepting untrusted input as globals.
Errors
Error::TooManyGlobals
- Too many globals with unique names were created
sourcepub fn set<G, T>(&mut self, id: G, value: T) -> Result<(), Error>where
G: GlobalName,
T: Into<Value>,
pub fn set<G, T>(&mut self, id: G, value: T) -> Result<(), Error>where
G: GlobalName,
T: Into<Value>,
Sets a global variable that’ll be available to scripts executed by the engine.
The id
parameter can be either an &str
or a prefetched global_id
.
Errors
Error::TooManyGlobals
- Too many globals with unique names were created
sourcepub fn get<G, T>(&self, id: G) -> Result<T, Error>where
G: OptionalGlobalName,
T: TryFromValue,
pub fn get<G, T>(&self, id: G) -> Result<T, Error>where
G: OptionalGlobalName,
T: TryFromValue,
Returns the value of a global variable, or nil
if it’s not set.
The id
parameter can be either an &str
or a prefetched global_id
.
Errors
Error::TooManyGlobals
- Too many globals with unique names were createdError::TypeMismatch
- The type of the value is not convertible toT
sourcepub fn add_raw_function(
&mut self,
name: &str,
parameter_count: impl Into<Option<u16>>,
f: FunctionKind
) -> Result<(), Error>
pub fn add_raw_function(
&mut self,
name: &str,
parameter_count: impl Into<Option<u16>>,
f: FunctionKind
) -> Result<(), Error>
Declares a “raw” function in the global scope. Raw functions do not perform any type checks by default and accept a variable number of arguments.
You should generally prefer add_function
instead of this.
Note that this cannot accept GlobalId
s, because a name is required to create the function
and global IDs have their name erased.
parameter_count
should reflect the parameter count of the function. Pass None
if the
function accepts a variable number of arguments. Note that because this function omits type
checks you may receive a different amount of arguments than specified.
Errors
Error::TooManyGlobals
- Too many globals with unique names were createdError::TooManyFunctions
- Too many functions were registered into the engine
sourcepub fn add_function<F, V>(&mut self, name: &str, f: F) -> Result<(), Error>where
V: Bare,
F: ForeignFunction<V>,
pub fn add_function<F, V>(&mut self, name: &str, f: F) -> Result<(), Error>where
V: Bare,
F: ForeignFunction<V>,
sourcepub fn add_type<T>(&mut self, builder: TypeBuilder<T>) -> Result<(), Error>where
T: Any + UserData,
pub fn add_type<T>(&mut self, builder: TypeBuilder<T>) -> Result<(), Error>where
T: Any + UserData,
Declares a type in the global scope.
Errors
Error::TooManyGlobals
- Too many globals with unique names were createdError::TooManyFunctions
- Too many functions were registered into the engineError::TooManyMethods
- Too many unique method signatures were created
sourcepub fn build_trait(&mut self, name: &str) -> Result<TraitBuilder<'_>, Error>
pub fn build_trait(&mut self, name: &str) -> Result<TraitBuilder<'_>, Error>
Starts building a new trait.