Crate budvm

A safe, dynamically-typed virtual machine

This crate provides a stack-based virtual machine that can be used to implement dynamically typed languages. Bud is the language that this crate was originally designed for.

Safety

This crate uses #[forbid(unsafe_code)] and has no external dependencies. The only unsafe code blocks are located within Rust’s standard library. Any panics encountered should be considered a bug and reported.

How to use

Bud can be used as a complete example of how to build a language and REPL with this crate. There are two simpler examples demonstrating a recursive fibonacci number function:

• fib-vm: Implemented using virtual machine instructions.
• fib-ir: Implemented using intermediate representation (IR) with conveniences like variable management and labels.

In all cases, the VirtualMachine type is used to execute instructions. Its documentation goes into detail how it operates.

Modules

• budmap
  A HashMap implementation that provides a defined iteration order.
• ir
  An intermediate representation of virtual machine instructions.
• lexer_util
  Utilities shared between Bud Assembly and Bud.

Structs

• Budgeted
  An Environment that allows executing an amount of instructions before pausing the virtual machine.
• CodeBlock
  A block of code that can be executed on the virtual machine.
• CodeBlockDisplay
  Displays a CodeBlock with optional indentation.
• Dynamic
  A Rust value that has been wrapped for use in the virtual machine.
• DynamicFault
  A Fault that arose from a Dynamic value.
• Fault
  An unexpected event occurred while executing the virtual machine.
• FaultStackFrame
  A stack frame entry of a Fault.
• Function
  A virtual machine function.
• HashMap
  A wrapper for std::collections::HashMap<Value,Value> that prevents using a Value that does not support hashing by returning an error.
• List
  A List type for Bud, which wraps a VecDeque<Value>.
• Noop
  An intrinsic that does nothing.
• PausedExecution
  A paused code execution.
• PoppedValues
  An iterator over a sequence of values being removed from the top of a Stack.
• Stack
  A stack of Values.
• StringLiteralDisplay
  A Display implementor that converts a string value to its literal form including wrapping double quotes.
• Symbol
  A String-like type that ensures only one instance of each Symbol exists per value, enabling quicker lookups by not requiring string comparisons.
• VirtualMachine
  A Bud virtual machine instance.

Enums

• CompareAction
  An action to take during an Instruction::Compare.
• Comparison
  A method for comparing Values.
• Destination
  A destination for a value.
• Error
  All errors that can be encountered executing Bud code.
• ExecutionBehavior
  The virtual machine behavior returned from Environment::step().
• FaultKind
  An unexpected event within the virtual machine.
• FaultOrPause
  A reason for a virtual machine Fault.
• Instruction
  A virtual machine instruction.
• Instructions
  A collection of Instructions that may be borrowed.
• Value
  A virtual machine value.
• ValueKind
  All primitive Value kinds.
• ValueOrSource
  A value or a location of a value
• ValueSource
  The source of a value.

Traits

• DynamicValue
  A type that can be used in the virtual machine using Value::dynamic.
• Environment
  Customizes the behavior of a virtual machine instance.
• FromStack
  A type that can be constructed from popping from the virtual machine stack.
• NativeFunction
  A native function for Bud.