Struct mica_hl::Engine

pub struct Engine { /* private fields */ }

Start here! An execution engine. Contains information about things like globals, registered types, etc.

Implementations

impl Engine

pub fn new(stdlib: impl StandardLibrary) -> Self

Creates a new engine.

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.

pub fn compile(
    &mut self,
    filename: impl AsRef<str>,
    source: impl Into<String>
) -> Result<Script<'_>, Error>

Compiles a script.

Errors

• Error::Compile - Syntax or semantic error

pub fn start(
    &mut self,
    filename: impl AsRef<str>,
    source: impl Into<String>
) -> Result<Fiber<'_>, Error>

Compiles and starts running a script.

This can be used as a shorthand if you don’t intend to reuse the compiled bytecode.

Errors

See compile.

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 execution
• Error::TooManyArguments - if more arguments than the implementation can support is passed to the function

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

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 execution
• Error::TooManyArguments - if more arguments than the implementation can support is passed to the function
• Error::TooManyMethods - if too many methods with different signatures exist at the same time
• Error::ArgumentCount - if arguments.count() does not match the argument count of the signature

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

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

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 created
• Error::TypeMismatch - The type of the value is not convertible to T

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 GlobalIds, 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 created
• Error::TooManyFunctions - Too many functions were registered into the engine

pub fn add_function<F, V>(&mut self, name: &str, f: F) -> Result<(), Error>where
    V: Bare,
    F: ForeignFunction<V>,

Declares a function in the global scope.

Errors

See add_raw_function.

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 created
• Error::TooManyFunctions - Too many functions were registered into the engine
• Error::TooManyMethods - Too many unique method signatures were created

pub fn build_trait(&mut self, name: &str) -> Result<TraitBuilder<'_>, Error>

Starts building a new trait.