Skip to main content

mirascript_vm/
lib.rs

1#![doc = include_str!("../README.md")]
2#![warn(missing_docs)]
3
4extern crate self as mirascript_vm;
5
6mod bytecode;
7mod compile;
8mod error;
9mod interpreter;
10mod operations;
11mod runtime_providers;
12mod standard_library;
13mod value;
14
15use std::{rc::Rc, time::Duration};
16
17pub use core::{CompileConfig, DiagnosticPositionEncoding, InputMode};
18pub use mirascript_core as core;
19pub use mirascript_vm_derive::{MiraArray, MiraRecord, mira};
20
21use bytecode::Program;
22pub use compile::{MiraScript, ScriptId};
23pub use error::*;
24pub use interpreter::Runtime;
25pub use runtime_providers::{RuntimeProviders, default_runtime_providers};
26pub(crate) use value::MiraValueKind;
27pub use value::{
28    MiraArray, MiraExtern, MiraFunction, MiraHandle, MiraManageable, MiraModule, MiraNativeFn,
29    MiraRecord, MiraShapedArray, MiraShapedRecord, MiraType, MiraValue, TryFromMira,
30};
31
32/// Limits and injectable providers used for each Runtime execution.
33#[derive(Clone)]
34pub struct RunOptions {
35    /// Maximum wall-clock time allowed for one execution.
36    pub timeout: Duration,
37    /// Number of interpreter checkpoints between timeout-provider checks.
38    pub checkpoint_interval: u32,
39    /// Maximum nested script and native call depth.
40    pub max_call_depth: u32,
41    /// Maximum number of elements created by bounded array operations.
42    pub max_array_len: usize,
43    /// Host implementation for random numbers, time, and debug output.
44    pub providers: Rc<dyn RuntimeProviders>,
45}
46
47impl Default for RunOptions {
48    fn default() -> Self {
49        Self {
50            timeout: Duration::from_millis(100),
51            checkpoint_interval: 100,
52            max_call_depth: 128,
53            max_array_len: 0x100_0000,
54            providers: default_runtime_providers(),
55        }
56    }
57}
58
59/// Compile source with the default compiler configuration.
60///
61/// ```
62/// use mirascript_vm::{MiraValue, Runtime, compile};
63///
64/// let script = compile("6 * 7")?;
65/// let mut runtime = Runtime::new();
66/// assert_eq!(runtime.run(&script)?, MiraValue::number(42.0));
67/// # Ok::<(), Box<mirascript_vm::MiraError>>(())
68/// ```
69pub fn compile(source: &str) -> Result<MiraScript> {
70    compile_with(source, &CompileConfig::default())
71}
72
73/// Compile source with an explicit [`CompileConfig`].
74///
75/// ```
76/// use mirascript_vm::{MiraValue, Runtime, CompileConfig, InputMode, compile_with};
77///
78/// let mut config = CompileConfig::new();
79/// config.input_mode = InputMode::Template;
80/// let script = compile_with("Hello, $name!", &config)?;
81/// let mut runtime = Runtime::new();
82/// runtime.insert_global("name", &"Alice")?;
83/// assert_eq!(runtime.run(&script)?.as_str(&runtime)?.unwrap(), "Hello, Alice!");
84/// # Ok::<(), Box<mirascript_vm::MiraError>>(())
85/// ```
86pub fn compile_with(source: &str, config: &CompileConfig) -> Result<MiraScript> {
87    let (chunk, diagnostics) = core::Compiler::compile(source, config);
88    let chunk = chunk.ok_or_else(|| MiraError::compile(&diagnostics))?;
89    Ok(MiraScript::new(Program::decode(&chunk)?))
90}
91
92/// Items used by the derive macros. They are not a stable user-facing API.
93#[doc(hidden)]
94pub mod __private {
95    pub use crate::{MiraError, MiraManageable, MiraValue, Result};
96
97    pub use crate::value::types::field::{
98        MiraField, MiraFieldGetter, array_from_array, array_from_record, shaped_array_from_array,
99        shaped_array_from_record, shaped_record_from_array, shaped_record_from_record,
100    };
101
102    pub use crate::value::types::function::{
103        MiraFunction, MiraNativeFn,
104        helper::{native_argument, native_argument_optional, native_result},
105    };
106}