1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
//! 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`](https://docs.rs/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:
//!
//! ```
//! # use nybl::{NyblError, NyblHost, NyblLimits, Value};
//! # struct Host;
//! # impl NyblHost for Host {
//! # fn call(&mut self, _: &str, _: &[Value], _: u32)
//! # -> Option<Result<Value, NyblError>> { None }
//! # }
//! 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.
//!
//! ```
//! # use nybl::{NyblError, NyblHost, NyblLimits, Value};
//! # struct Host;
//! # impl NyblHost for Host {
//! # fn call(&mut self, _: &str, _: &[Value], _: u32)
//! # -> Option<Result<Value, NyblError>> { None }
//! # }
//! 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](https://nybl-lang.com/docs/functions/reference-parameters/) 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](https://nybl-lang.com/docs/embedding/) and
//! [stateful instance guide](https://nybl-lang.com/docs/embedding/instances/)
//! for lifecycle, limits, callback affinity, and engine-selection details.
extern crate alloc;
// A genuine no_std unit-test build still uses Rust's standard test harness;
// make that test-only dependency explicit.
extern crate std;
pub use ;
pub use compile;
pub use disassemble;
pub use validate_chunk;
pub use ;