Skip to main content

Crate nybl_vm

Crate nybl_vm 

Source
Expand description

Bytecode compiler and stack VM for the Nybl programming language.

nybl-vm implements the same language, host interface, values, limits, and diagnostics as the tree-walker in nybl-lang, while compiling source to reusable bytecode. It is the usual choice for scripts that run hot loops or are executed repeatedly at runtime.

§One-shot execution

run parses, compiles, validates, and executes one isolated program:

use nybl::{NyblError, NyblHost, NyblLimits, Value};

struct Host;
impl NyblHost for Host {
    fn call(
        &mut self,
        _: &str,
        _: &[Value],
        _: u32,
    ) -> Option<Result<Value, NyblError>> {
        None
    }

    fn on_print(&mut self, message: &str) {
        assert_eq!(message, "42");
    }
}

let mut host = Host;
nybl_vm::run(
    "print(6 * 7)",
    &mut host,
    &NyblLimits::standard(),
).unwrap();

§Compile once, execute with fresh state

Use compile and execute when the bytecode should be reused but each run should start with fresh globals:

let statements = nybl::parse("let answer = 6 * 7").unwrap();
let chunk = nybl_vm::compile(&statements).unwrap();
nybl_vm::validate_chunk(&chunk).unwrap();

let mut host = Host;
nybl_vm::execute(
    chunk,
    &mut host,
    &NyblLimits::standard(),
).unwrap();

validate_chunk rejects malformed control flow, operands, pool indices, and nested chunks before execution. disassemble provides a readable representation for tooling and diagnostics.

§Persistent programs

NyblInstance loads and compiles once, then retains globals, modules, functions, types, methods, callbacks, and random-number state across host calls. Root-level pub fn declarations define the callable ABI.

let mut host = Host;
let mut instance = nybl_vm::NyblInstance::load(
    "let count = 0\npub fn next() { count += 1; return count }",
    &mut host,
    &NyblLimits::standard(),
).unwrap();
assert_eq!(
    instance.call("next", &[], &mut host).unwrap().inspect(),
    "1",
);

§Reference parameters

The VM implements Nybl’s explicit ref parameters with the same transactional copy-in/copy-out semantics as the tree-walker and AOT engine. Mutable plain-variable targets commit together after a normal return and roll back together on runtime or resource errors. Parameter modes remain attached to first-class callable values.

Rust NyblInstance::call and NyblInstance::call_value arguments are value-only and reject ref-bearing callables before execution. See the reference-parameters guide for the complete target, forwarding, evaluation-order, and method rules. User-defined ref self receivers use the same transactional commit and rollback path as explicit reference arguments; ordinary self is read-only.

§Features

  • std (default) retains Rust standard-library host behavior and forwards to nybl-lang/std.
  • nybl-std (default) forwards to nybl-lang/nybl-std so hosts can resolve the bundled std.* modules.
  • no_std forwards to nybl-lang/no_std; combine it with default-features = false for bare-metal or wasm32-unknown-unknown builds. If Cargo unifies std and no_std, std wins.

See the embedding guide and stateful instance guide for lifecycle, limits, callback affinity, and engine-selection details.

Re-exports§

pub use chunk::Chunk;
pub use chunk::CodeOffset;
pub use chunk::ConstIdx;
pub use chunk::Constant;
pub use chunk::EnumConstructShape;
pub use chunk::EnumDef;
pub use chunk::EnumIdx;
pub use chunk::EnumVariantDef;
pub use chunk::EnumVariantShape;
pub use chunk::FnDef;
pub use chunk::FnIdx;
pub use chunk::Instr;
pub use chunk::InterpIdx;
pub use chunk::InterpPart;
pub use chunk::InterpRecipe;
pub use chunk::LoopStateKind;
pub use chunk::NameIdx;
pub use chunk::StructDef;
pub use chunk::StructIdx;
pub use compiler::compile;
pub use disasm::disassemble;
pub use validate::validate_chunk;
pub use vm::CompiledScript;
pub use vm::NyblInstance;
pub use vm::PreparedEntry;
pub use vm::Vm;
pub use vm::execute;
pub use vm::run;

Modules§

chunk
Bytecode chunk layout: instructions, constants, and nested function bodies. See the crate root for the textual description of the instruction set.
compiler
AST → bytecode compilation. See crate docs for the instruction set overview.
disasm
Human-readable rendering of a Chunk for debugging and tests.
validate
Structural validation for public, hand-built bytecode chunks.
vm
Bytecode VM execution.