Struct Engine 

pub struct Engine { /* private fields */ }

The persistent embedding entry point. Holds the table of registered host functions and compiles scripts into reusable Programs.

This is the library analogue of the one-shot [crate::candela_run]: it does not run a script and hand back stdout, it keeps compiler + VM state resident so the host can call into the script repeatedly.

Implementations

impl Engine

pub fn new() -> Self

pub fn with_lib_dir(self, dir: impl Into<PathBuf>) -> Self

Points library imports at dir instead of the directory the toolchain installed.

dir is the one that holds std/, so import "std/string"; reads dir/std/string.cdl. A host that ships the standard library inside its own application directory names it here, and the scripts it compiles find it wherever the application was installed.

let engine = candela::Engine::new().with_lib_dir("/opt/myapp/libs");

pub fn with_cfg(self, cfg: Cfg) -> Self

Sets the flags @cfg(...) attributes test in the scripts this engine compiles.

Code under a @cfg whose condition is false is dropped before names resolve, so it may import a module or call a function that does not exist here. A flag the configuration does not enable is false.

let engine = candela::Engine::new().with_cfg(candela::Cfg::from_iter(["web"]));

pub fn with_import_root(self, name: &str, dir: impl Into<PathBuf>) -> Self

Makes dir the root of the package a script imports as name.

The package is entered through the file its candela.toml names as entry, or src/main.cdl when the manifest names none or there is no manifest. import "shapes"; then reads that file, and import "shapes/circle"; reads circle.cdl from the entry’s directory. dir is searched for native libraries too, so a package that ships a shared library under its root binds a dylib import with no further setup.

let engine = candela::Engine::new().with_import_root("shapes", "/cache/shapes/1.2.3");

pub fn register_host_fn<Marker, F>(&mut self, namespace: &str, name: &str, f: F)

where F: IntoHostFn<Marker>,

Registers a typed host function under namespace::name.

The closure may take any combination of i64/i32, f64, bool, String (or a single &str) arguments and return one of those or (). The declared types are checked against the script’s host block when Engine::compile runs; a mismatch is a clean Diagnostic, never a panic.

A closure that can fail returns Result<T, HostError> instead of T, and the error is raised at the call site in the script:

use candela::HostError;

let mut engine = candela::Engine::new();
engine.register_host_fn("fs", "read", |path: &str| {
    std::fs::read_to_string(path).map_err(HostError::new)
});

The type checked against the declaration is the T inside the Result, so both spellings bind to the same host signature.

pub fn register_host_fn_typed<F>( &mut self, namespace: &str, name: &str, arg_types: Vec<HostType>, ret_type: HostType, f: F, )

where F: Fn(&[Value]) -> Result<Value, HostError> + 'static,

Registers a host function whose signature is given as data rather than derived from a Rust closure’s types.

The closure takes the arguments as a &[Value] slice, and arg_types / ret_type say what the script may pass and expect. The binding is checked against the host block exactly as Engine::register_host_fn is, so a declaration that disagrees is a Diagnostic at Engine::compile time, and the declaration must not use ....

use candela::{HostType, Value};

let mut engine = candela::Engine::new();
engine.register_host_fn_typed(
    "gpio",
    "read",
    vec![HostType::Int],
    HostType::Int,
    |args: &[Value]| Ok(Value::Int(args[0].as_i64().unwrap_or(0))),
);

Use it when the signature is only known at run time: a plugin table, a generated binding, anything with no Rust signature to read the types from.

pub fn register_host_fn_variadic<F>( &mut self, namespace: &str, name: &str, f: F, )

where F: Fn(&[Value]) -> Result<Value, HostError> + 'static,

Registers a variadic host function under namespace::name.

Unlike Engine::register_host_fn, the closure receives every argument as a &[Value] slice of any length and returns a single Value (or a HostError to raise in the script), so arguments of mixed / dynamically-typed shape can cross the boundary without a fixed Rust signature. The host block must declare the function with a ... argument list:

host "app" {
    log(...);
}

No arity or per-argument type checking is performed at the call site; the closure interprets the slice it is handed. A non-variadic declaration bound to a variadic closure (or vice versa) is a clean Diagnostic at Engine::compile time.

pub fn register_macro<F>(&mut self, name: &str, expander: F)

where F: Fn(&str) -> Result<String, MacroError> + 'static,

Registers the expander for name!( ... ) invocations in the scripts this engine compiles.

The expander receives the raw text between the parentheses, which candela does not interpret, and returns candela source for one expression that is parsed in its place. A MacroError it returns instead becomes a compile error at the macro, at the byte offset into the region the error names.

use candela::macros::MacroError;

let mut engine = candela::Engine::new();
engine.register_macro("rows", |body: &str| {
    Ok::<String, MacroError>(body.lines().count().to_string())
});

pub const fn allow_unknown_macros(&mut self, allow: bool)

Sets what a macro with no registered expander does: fail the compile naming it (the default), or, when allow is true, compile as null.

Tooling that reads scripts written for a host it is not part of turns this on, so the host’s macros do not read as errors.

pub fn check( &self, src: &str, filename: &str, ) -> Result<Vec<Diagnostic>, Diagnostic>

Type-checks src the way Engine::compile does, without producing a program, and returns the warnings the compile raised.

Every function whose parameters are all annotated is checked at those types, and a function a host would call with a bare parameter is checked with it typed any, as compile does. What this leaves out is everything a check does not need: a dylib block binds the signatures it declares without opening its library, so a script whose C library a build step has not produced yet still checks; host blocks are not matched against registered closures; main is not required and nothing runs.

Errors

Returns the Diagnostic of the first error: a parse or type error, a body that does not compile at its declared parameter types, or a dylib signature naming a type C cannot represent.

pub fn compile(&self, src: &str, filename: &str) -> Result<Program, Diagnostic>

Compiles src into a reusable Program, binding every host function it declares to the matching registered closure.

Every function in src whose parameters are all annotated is compiled at those declared types, whether or not anything calls it, so an error in the body of a function main never calls comes back from here rather than from the first Program::call. A function with a bare parameter that nothing in the script calls is checked with that parameter typed any, and warned about; the warnings come back on Program::warnings. A function an import brought in stays lazy.

main is executed once here (module instantiation), so any top-level setup runs before the host makes its first Program::call. The entry-point check runs first, so a broken body is reported before any top-level side effect.

Errors

Returns a Diagnostic if the script fails to parse/type-check, if the body of an annotated function does not compile at its declared parameter types, if the script declares no main, if a declared host function has no registered closure, if a registered closure’s arity/types disagree with the host block, or if running main raises a runtime error.

Trait Implementations

impl Default for Engine

fn default() -> Engine

Returns the “default value” for a type.