64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 🪸 ReefVM
|
|
|
|
It's where Shrimp live.
|
|
|
|
## Quickstart
|
|
|
|
bun install
|
|
bun test
|
|
|
|
## Use it
|
|
|
|
Execute text bytecode:
|
|
|
|
./bin/reef examples/loop.reef
|
|
|
|
Validate bytecode:
|
|
|
|
./bin/validate examples/loop.reef
|
|
|
|
Run the simple debugger to see what the instructions are doing:
|
|
|
|
./bin/debug examples/loop.reef
|
|
./bin/debug -h examples/loop.reef
|
|
|
|
Interactive REPL for exploring instructions:
|
|
|
|
./bin/repl
|
|
|
|
Type opcodes interactively and see the stack and variables update in real-time.
|
|
|
|
Commands: `clear`, `reset`, `exit`.
|
|
|
|
## Features
|
|
|
|
- Stack operations (PUSH, POP, DUP)
|
|
- Arithmetic operations (ADD, SUB, MUL, DIV, MOD)
|
|
- Comparison operations (EQ, NEQ, LT, GT, LTE, GTE)
|
|
- Logical operations (NOT, AND/OR patterns with short-circuiting)
|
|
- Variable operations (LOAD, STORE) with **emoji and Unicode support** (💎 = 5)
|
|
- Control flow with **relative jumps** (JUMP, JUMP_IF_FALSE, JUMP_IF_TRUE, BREAK, CONTINUE)
|
|
- Array operations (MAKE_ARRAY, ARRAY_GET, ARRAY_SET, ARRAY_PUSH, ARRAY_LEN)
|
|
- Dictionary operations (MAKE_DICT, DICT_GET, DICT_SET, DICT_HAS)
|
|
- Function operations (MAKE_FUNCTION, CALL, TAIL_CALL, RETURN) with parameter binding
|
|
- Variadic functions with positional rest parameters (`...rest`)
|
|
- Named arguments (named) that collect unmatched named args into a dict (`@named`)
|
|
- Mixed positional and named arguments with proper priority binding
|
|
- Default parameter values with null-triggering: passing `null` explicitly uses the default value
|
|
- Tail call optimization with unbounded recursion (10,000+ iterations without stack overflow)
|
|
- Exception handling (PUSH_TRY, PUSH_FINALLY, POP_TRY, THROW) with nested try/finally blocks and call stack unwinding
|
|
- Native function interop with auto-wrapping for native TypeScript types
|
|
- Native functions stored in scope, called via LOAD + CALL
|
|
- Native functions support `atXxx` parameters (e.g., `atOptions`) to collect unmatched named args
|
|
- Pass functions directly to `run(bytecode, { fnName: fn })` or `new VM(bytecode, { fnName: fn })`
|
|
- Call Reef functions from TypeScript with `vm.call(name, ...args)` with automatic type conversion
|
|
|
|
## Design Decisions
|
|
|
|
- Relative jumps: All JUMP instructions use PC-relative offsets instead of absolute addresses, making bytecode position-independent
|
|
- Truthiness: Only `null` and `false` are falsy (unlike JavaScript where `0`, `""`, etc. are also falsy)
|
|
- Short-circuiting via compiler: No AND/OR opcodes—compilers use JUMP patterns for proper short-circuit evaluation
|
|
- Variadic parameters: Functions can collect remaining positional arguments into an array using `...rest` syntax
|
|
- Named parameters: Functions can collect unmatched named arguments into a dict using `@named` syntax
|
|
- Argument binding priority: Named args bind to regular params first, with unmatched ones going to `@named`
|
|
- Null triggers defaults: Passing `null` to a parameter with a default value explicitly uses that default (applies to both ReefVM and native functions) |