Struct VmScript 

pub struct VmScript { /* private fields */ }

One executable NCS script plus its VM runtime state.

Implementations

impl VmScript

pub fn from_bytes( bytes: &[u8], label: impl Into<String>, ) -> Result<Self, VmError>

Decodes one NCS V1.0 bytecode stream into a runnable script.

Errors

Returns VmError if the bytecode is malformed.

pub fn from_instructions( instructions: Vec<NcsInstruction>, label: impl Into<String>, ) -> Self

Builds a runnable script from decoded instructions.

pub fn attach_ndb(&mut self, ndb: &Ndb) -> Result<(), VmError>

Attaches one NDB debug table so the VM can recover user-function frame shapes.

Errors

Returns VmError if one function record uses unsupported stack metadata.

pub fn from_bytes_with_ndb( bytes: &[u8], label: impl Into<String>, ndb: &Ndb, ) -> Result<Self, VmError>

Decodes one NCS V1.0 bytecode stream and attaches one NDB debug table.

Errors

Returns VmError if the bytecode or attached debug metadata is malformed.

pub fn run(&mut self, vm: &Vm) -> Result<(), VmError>

Executes this script using the supplied VM command table.

Errors

Returns VmError if execution fails.

pub fn label(&self) -> &str

Returns the user-facing label associated with this script.

pub fn ip(&self) -> usize

Returns the current instruction pointer in code-section bytes.

pub fn sp(&self) -> usize

Returns the current stack pointer in stack cells.

pub fn bp(&self) -> usize

Returns the current base pointer in stack cells.

pub fn current_instruction(&self) -> Option<&NcsInstruction>

Returns the decoded instruction at the current instruction pointer.

pub fn instruction_at(&self, offset: usize) -> Option<&NcsInstruction>

Returns the decoded instruction at one byte offset, if present.

pub fn current_function(&self) -> Option<VmFunctionInfo>

Returns the attached debug function that contains the current instruction pointer.

pub fn function_at(&self, offset: usize) -> Option<VmFunctionInfo>

Returns the attached debug function that contains one byte offset.

pub fn current_source_location(&self) -> Option<VmSourceLocation>

Returns the attached source location for the current instruction pointer.

pub fn source_location_at(&self, offset: usize) -> Option<VmSourceLocation>

Returns the attached source location for one byte offset.

pub fn save_ip(&self) -> usize

Returns the instruction pointer saved by STOREIP or STORESTATE.

pub fn save_sp(&self) -> usize

Returns the stack pointer saved by STORESTATE.

pub fn save_bp(&self) -> usize

Returns the base pointer saved by STORESTATE.

pub fn stack(&self) -> &[VmValue]

Returns the current stack values.

pub fn stack_string(&self) -> String

Returns a compact debugger-oriented stack rendering with ^ at the base pointer and * at the top stack cell.

pub fn return_depth(&self) -> usize

Returns the current return-frame depth.

pub fn saved_situation(&self) -> Option<&VmSituation>

Returns the last deferred action snapshot captured by STORESTATE.

pub fn take_saved_situation(&mut self) -> Option<VmSituation>

Removes and returns the last deferred action snapshot captured by STORESTATE.

pub fn prepare_function_call( &mut self, ndb: &Ndb, name: &str, args: &[VmValue], ) -> Result<(), VmError>

Configures this script to call one named user function directly.

This bypasses the compiler-emitted loader.

If the script uses globals, the caller must initialize the loader/global frame first before invoking a named function directly.

Errors

Returns VmError if the function cannot be found or the argument types are unsupported.

pub fn function_return_value( &self, ndb: &Ndb, name: &str, ) -> Result<Option<VmValue>, VmError>

Reads one scalar/object/string/engine-structure return value after a direct function call.

Errors

Returns VmError if the function cannot be found or uses an unsupported return type.

pub fn abort(&mut self)

Requests that this script abort once control returns to the VM dispatcher.

pub fn aborted(&self) -> bool

Returns whether the last VM run terminated via abort().

pub fn push(&mut self, value: VmValue)

Pushes one raw stack value.

pub fn push_int(&mut self, value: i32)

Pushes one integer value.

pub fn push_float(&mut self, value: f32)

Pushes one floating-point value.

pub fn push_string(&mut self, value: impl Into<String>)

Pushes one string value.

pub fn push_object(&mut self, value: VmObjectId)

Pushes one object id.

pub fn push_engine_structure( &mut self, index: u8, value: VmEngineStructureValue, )

Pushes one engine-structure value.

pub fn push_vector(&mut self, value: [f32; 3])

Pushes one vector value as three stack cells in x, y, z order.

pub fn pop(&mut self) -> Result<VmValue, VmError>

Pops one raw stack value.

Errors

Returns VmError if the stack is empty.

pub fn pop_int(&mut self) -> Result<i32, VmError>

Pops one integer value.

Errors

Returns VmError if the stack top is not an integer.

pub fn pop_float(&mut self) -> Result<f32, VmError>

Pops one floating-point value.

Errors

Returns VmError if the stack top is not a float.

pub fn pop_string(&mut self) -> Result<String, VmError>

Pops one string value.

Errors

Returns VmError if the stack top is not a string.

pub fn pop_object(&mut self) -> Result<VmObjectId, VmError>

Pops one object id.

Errors

Returns VmError if the stack top is not an object.

pub fn pop_engine_structure( &mut self, ) -> Result<(u8, VmEngineStructureValue), VmError>

Pops one engine-structure value.

Errors

Returns VmError if the stack top is not an engine structure.

pub fn pop_engine_structure_index( &mut self, expected_index: u8, ) -> Result<VmEngineStructureValue, VmError>

Pops one engine-structure value and checks its engine-structure index.

Errors

Returns VmError if the stack top is not the requested engine structure.

pub fn pop_vector(&mut self) -> Result<[f32; 3], VmError>

Pops one vector value from three float stack cells.

Errors

Returns VmError if the top three cells are not floats.

Trait Implementations

impl Clone for VmScript

fn clone(&self) -> VmScript

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VmScript

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.