ion_core/
engine.rs

1use std::collections::HashMap;
2
3use crate::error::IonError;
4use crate::host_types::{HostEnumDef, HostStructDef, IonType, IonTypeDef};
5use crate::interpreter::{Interpreter, Limits};
6use crate::lexer::Lexer;
7use crate::module::Module;
8use crate::parser::Parser;
9use crate::value::Value;
10
11/// The public embedding API for the Ion interpreter.
12pub struct Engine {
13    interpreter: Interpreter,
14}
15
16impl Engine {
17    pub fn new() -> Self {
18        Self {
19            interpreter: Interpreter::new(),
20        }
21    }
22
23    /// Evaluate a script, returning the last expression's value.
24    pub fn eval(&mut self, source: &str) -> Result<Value, IonError> {
25        let mut lexer = Lexer::new(source);
26        let tokens = lexer.tokenize()?;
27        let mut parser = Parser::new(tokens);
28        let program = parser.parse_program()?;
29        self.interpreter.eval_program(&program)
30    }
31
32    /// Inject a value into the script scope.
33    pub fn set(&mut self, name: &str, value: Value) {
34        self.interpreter.env.define(name.to_string(), value, false);
35    }
36
37    /// Read a variable from the script scope.
38    pub fn get(&self, name: &str) -> Option<Value> {
39        self.interpreter.env.get(name).cloned()
40    }
41
42    /// Get all top-level bindings.
43    pub fn get_all(&self) -> HashMap<String, Value> {
44        self.interpreter.env.top_level()
45    }
46
47    /// Set execution limits.
48    pub fn set_limits(&mut self, limits: Limits) {
49        self.interpreter.limits = limits;
50    }
51
52    /// Register a built-in function.
53    pub fn register_fn(&mut self, name: &str, func: fn(&[Value]) -> Result<Value, String>) {
54        self.interpreter.env.define(
55            name.to_string(),
56            Value::BuiltinFn(name.to_string(), func),
57            false,
58        );
59    }
60
61    /// Register a built-in backed by a closure. Unlike `register_fn`,
62    /// this accepts any `Fn` — including closures that capture
63    /// host-side state such as a `tokio::runtime::Handle`, a database
64    /// pool, or shared counters. See `docs/concurrency.md` for the
65    /// tokio embedding pattern.
66    pub fn register_closure<F>(&mut self, name: &str, func: F)
67    where
68        F: Fn(&[Value]) -> Result<Value, String> + Send + Sync + 'static,
69    {
70        self.interpreter.env.define(
71            name.to_string(),
72            Value::BuiltinClosure(name.to_string(), crate::value::BuiltinClosureFn::new(func)),
73            false,
74        );
75    }
76
77    /// Register a host struct type that scripts can construct and match on.
78    pub fn register_struct(&mut self, def: HostStructDef) {
79        self.interpreter.types.register_struct(def);
80    }
81
82    /// Register a host enum type that scripts can construct and match on.
83    pub fn register_enum(&mut self, def: HostEnumDef) {
84        self.interpreter.types.register_enum(def);
85    }
86
87    /// Register a module that scripts can access via `module::name` or `use module::*`.
88    pub fn register_module(&mut self, module: Module) {
89        let name = module.name.clone();
90        let value = module.to_value();
91        self.interpreter.env.define(name, value, false);
92    }
93
94    /// Register a type via the IonType trait (used with `#[derive(IonType)]`).
95    pub fn register_type<T: IonType>(&mut self) {
96        match T::ion_type_def() {
97            IonTypeDef::Struct(def) => self.interpreter.types.register_struct(def),
98            IonTypeDef::Enum(def) => self.interpreter.types.register_enum(def),
99        }
100    }
101
102    /// Inject a typed Rust value into the script scope.
103    pub fn set_typed<T: IonType>(&mut self, name: &str, value: &T) {
104        self.interpreter
105            .env
106            .define(name.to_string(), value.to_ion(), false);
107    }
108
109    /// Extract a typed Rust value from the script scope.
110    pub fn get_typed<T: IonType>(&self, name: &str) -> Result<T, String> {
111        let val = self.interpreter.env.get(name).ok_or_else(|| {
112            format!(
113                "{}{}{}",
114                ion_str!("variable '"),
115                name,
116                ion_str!("' not found")
117            )
118        })?;
119        T::from_ion(val)
120    }
121
122    /// Evaluate a script via the bytecode VM. Falls back to tree-walk for
123    /// unsupported features (concurrency).
124    #[cfg(feature = "vm")]
125    pub fn vm_eval(&mut self, source: &str) -> Result<Value, IonError> {
126        let mut lexer = Lexer::new(source);
127        let tokens = lexer.tokenize()?;
128        let mut parser = Parser::new(tokens);
129        let program = parser.parse_program()?;
130
131        // Try the bytecode path first
132        let compiler = crate::compiler::Compiler::new();
133        match compiler.compile_program(&program) {
134            Ok((chunk, fn_chunks)) => {
135                let mut vm = crate::vm::Vm::with_env(std::mem::take(&mut self.interpreter.env));
136                // Pre-populate the VM's function cache with compiled chunks
137                vm.preload_fn_chunks(fn_chunks);
138                // Pass host type registry to VM
139                vm.set_types(self.interpreter.types.clone());
140                let result = vm.execute(&chunk);
141                // Restore env back to interpreter
142                self.interpreter.env = std::mem::take(vm.env_mut());
143                result
144            }
145            Err(_) => {
146                // Compilation failed (unsupported feature) — fall back to tree-walk
147                self.interpreter.eval_program(&program)
148            }
149        }
150    }
151}
152
153impl Default for Engine {
154    fn default() -> Self {
155        Self::new()
156    }
157}
ion_core/engine.rs

ion_core/
engine.rs
