Struct ExecutableModule

pub struct ExecutableModule<'a, T> { /* private fields */ }

Executable module together with its imports.

An ExecutableModule is a result of compiling a Block of statements. A module can import Values, such as commonly used functions. Importing is performed when building the module.

After the module is created, it can be run. If the last statement of the block is an expression (that is, not terminated with a ;), it is the result of the execution; otherwise, the result is Value::void(). It is possible to run a module multiple times and to change imports by using Self::set_import().

In some cases (e.g., when building a REPL) it is useful to get not only the outcome of the module execution, but the intermediate results as well. Use Self::run_in_env() for such cases.

ExecutableModules are generic with respect to the primitive value type, just like Value. The lifetime of a module depends on the lifetime of the code, but this dependency can be eliminated via StripCode implementation.

Examples

Basic usage

use arithmetic_parser::grammars::{F32Grammar, Parse, Untyped};
use arithmetic_eval::{fns, Comparisons, ExecutableModule, Prelude, Value};

let module = Untyped::<F32Grammar>::parse_statements("xs.fold(-INFINITY, max)")?;
let mut module = ExecutableModule::builder("test", &module)?
    .with_imports_from(&Prelude)
    .with_imports_from(&Comparisons)
    .with_import("INFINITY", Value::Prim(f32::INFINITY))
    // Set remaining imports to a fixed value.
    .set_imports(|_| Value::void());

// With the original imports, the returned value is `-INFINITY`.
assert_eq!(module.run()?, Value::Prim(f32::NEG_INFINITY));

// Imports can be changed. Let's check that `xs` is indeed an import.
assert!(module.imports().contains("xs"));
// ...or even
assert!(module.imports()["fold"].is_function());
// It's possible to iterate over imports, too.
let imports = module.imports().iter()
    .map(|(name, _)| name)
    .collect::<HashSet<_>>();
assert!(imports.is_superset(&HashSet::from_iter(vec!["max", "fold"])));

// Change the `xs` import and run the module again.
let array = [1.0, -3.0, 2.0, 0.5].iter().copied()
    .map(Value::Prim)
    .collect();
module.set_import("xs", Value::Tuple(array));
assert_eq!(module.run()?, Value::Prim(2.0));

Reusing a module

The same module can be run with multiple imports:

let block = Untyped::<F32Grammar>::parse_statements("x + y")?;
let mut module = ExecutableModule::builder("test", &block)?
    .with_import("x", Value::Prim(3.0))
    .with_import("y", Value::Prim(5.0))
    .build();
assert_eq!(module.run()?, Value::Prim(8.0));

let mut env = Environment::from_iter(module.imports());
env.insert("x", Value::Prim(-1.0));
assert_eq!(module.run_in_env(&mut env)?, Value::Prim(4.0));

Behavior on errors

run_in_env modifies the environment even if an error occurs during execution:

let module = Untyped::<F32Grammar>::parse_statements("x = 5; assert_eq(x, 4);")?;
let module = ExecutableModule::builder("test", &module)?
    .with_imports_from(&Assertions)
    .build();

let mut env = Environment::from_iter(module.imports());
assert!(module.run_in_env(&mut env).is_err());
assert_eq!(env["x"], Value::Prim(5.0));

Implementations

impl<'a, T> ExecutableModule<'a, T>

pub fn id(&self) -> &dyn ModuleId

Gets the identifier of this module.

pub fn set_import(&mut self, name: &str, value: Value<'a, T>) -> &mut Self

Sets the value of an imported variable.

Panics

Panics if the variable with the specified name is not an import. Check that the import exists beforehand via imports().contains() if this is unknown at compile time.

pub fn imports(&self) -> &ModuleImports<'a, T>

Returns shared reference to imports of this module.

pub fn with_arithmetic<'s>( &'s self, arithmetic: &'s dyn OrdArithmetic<T>, ) -> WithArithmetic<'s, 'a, T>

Combines this module with the specified arithmetic.

impl<'a, T: Clone + Debug> ExecutableModule<'a, T>

pub fn builder<G, Id>( id: Id, block: &Block<'a, G>, ) -> Result<ExecutableModuleBuilder<'a, T>, Error<'a>>

where Id: ModuleId, G: Grammar<'a, Lit = T>,

Starts building a new module.

impl<'a, T: Clone + Debug> ExecutableModule<'a, T>

where StdArithmetic: OrdArithmetic<T>,

pub fn run(&self) -> Result<Value<'a, T>, ErrorWithBacktrace<'a>>

Runs the module with the current values of imports. This is a read-only operation; neither the imports, nor other module state are modified by it.

pub fn run_in_env( &self, env: &mut Environment<'a, T>, ) -> Result<Value<'a, T>, ErrorWithBacktrace<'a>>

Runs the module with the specified Environment. The environment may contain some of module imports; they will be used to override imports defined in the module.

On execution, the environment is modified to reflect assignments in the topmost scope of the module. The modification takes place regardless of whether or not the execution succeeds. That is, if an error occurs, all preceding assignments in the topmost scope still take place. See the relevant example.

Trait Implementations

impl<T: Clone> Clone for ExecutableModule<'_, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, T: Debug> Debug for ExecutableModule<'a, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: 'static + Clone> StripCode for ExecutableModule<'_, T>

type Stripped = ExecutableModule<'static, T>

Resulting type after code stripping.

fn strip_code(self) -> Self::Stripped

Strips references to code fragments in this type.