john/cell
1
0
Fork 0
Code Issues 31 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

more correct syntax and AI instructions

Browse Source
This commit is contained in:
John Alanbrook
2026-02-09 11:00:23 -06:00
parent d0c68d7a7d
commit 872cd6ab51
28 changed files with 998 additions and 453 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
docs/spec/bytecode.md
View File

@@ -1,118 +0,0 @@
---
title: "Bytecode VM"
description: "Stack-based virtual machine"
---
## Overview
The bytecode VM is a stack-based virtual machine. Instructions operate on an implicit operand stack, pushing and popping values. This is the original execution backend for ƿit.
## Compilation Pipeline
```
Source → Tokenize → Parse (AST) → Bytecode → Link → Execute
```
The compiler emits `JSFunctionBytecode` objects containing opcode sequences, constant pools, and debug information.
## Instruction Categories
### Value Loading
| Opcode | Description |
|--------|-------------|
| `push_i32` | Push a 32-bit immediate integer |
| `push_const` | Push a value from the constant pool |
| `null` | Push null |
| `push_false` | Push false |
| `push_true` | Push true |
### Stack Manipulation
| Opcode | Description |
|--------|-------------|
| `drop` | Remove top of stack |
| `dup` | Duplicate top of stack |
| `dup1` / `dup2` / `dup3` | Duplicate item at depth |
| `swap` | Swap top two items |
| `rot3l` / `rot3r` | Rotate top three items |
| `insert2` / `insert3` | Insert top item deeper |
| `nip` | Remove second item |
### Variable Access
| Opcode | Description |
|--------|-------------|
| `get_var` | Load variable by name (pre-link) |
| `put_var` | Store variable by name (pre-link) |
| `get_loc` / `put_loc` | Access local variable by index |
| `get_arg` / `put_arg` | Access function argument by index |
| `get_env_slot` / `set_env_slot` | Access closure variable (post-link) |
| `get_global_slot` / `set_global_slot` | Access global variable (post-link) |
Variable access opcodes are patched during linking. `get_var` instructions are rewritten to `get_loc`, `get_env_slot`, or `get_global_slot` depending on where the variable is resolved.
### Arithmetic
| Opcode | Description |
|--------|-------------|
| `add` / `sub` / `mul` / `div` | Basic arithmetic |
| `mod` / `pow` | Modulo and power |
| `neg` / `inc` / `dec` | Unary operations |
| `add_loc` / `inc_loc` / `dec_loc` | Optimized local variable update |
### Comparison and Logic
| Opcode | Description |
|--------|-------------|
| `strict_eq` / `strict_neq` | Equality (ƿit uses strict only) |
| `lt` / `lte` / `gt` / `gte` | Ordered comparison |
| `not` / `lnot` | Logical / bitwise not |
| `and` / `or` / `xor` | Bitwise operations |
### Control Flow
| Opcode | Description |
|--------|-------------|
| `goto` | Unconditional jump |
| `if_true` / `if_false` | Conditional jump |
| `goto8` / `goto16` | Short jumps (size-optimized) |
| `if_true8` / `if_false8` | Short conditional jumps |
| `catch` | Set exception handler |
### Function Calls
| Opcode | Description |
|--------|-------------|
| `call` | Call function with N arguments |
| `tail_call` | Tail-call optimization |
| `call_method` | Call method on object |
| `return` | Return value from function |
| `return_undef` | Return null from function |
| `throw` | Throw exception (disrupt) |
### Property Access
| Opcode | Description |
|--------|-------------|
| `get_field` | Get named property |
| `put_field` | Set named property |
| `get_array_el` | Get computed property |
| `put_array_el` | Set computed property |
| `define_field` | Define property during object literal |
### Object Creation
| Opcode | Description |
|--------|-------------|
| `object` | Create new empty object |
| `array_from` | Create array from stack values |
## Bytecode Patching
During the link/integrate phase, symbolic variable references are resolved to concrete access instructions. This is a critical optimization — the interpreter does not perform name lookups at runtime.
A `get_var "x"` instruction becomes:
- `get_loc 3` — if x is local variable at index 3
- `get_env_slot 1, 5` — if x is captured from outer scope (depth 1, slot 5)
- `get_global_slot 7` — if x is a global

2
docs/spec/gc.md
View File

@@ -50,7 +50,7 @@ The collector traces from these root sources:
- **Class prototypes** — built-in type prototypes
- **Exception** — the current exception value
- **Value stack** — all values on the operand stack
- **Frame stack** — all stack frames (bytecode and register VM)
- **Frame stack** — all stack frames (register VM and mcode)
- **GC reference stack** — manually registered roots (via `JS_PUSH_VALUE` / `JS_POP_VALUE`)
- **Parser constant pool** — during compilation, constants being built

9
docs/spec/objects.md
View File

@@ -19,8 +19,8 @@ Every heap-allocated object begins with a 64-bit header word (`objhdr_t`):
| 1 | `OBJ_BLOB` | Binary data (bits) |
| 2 | `OBJ_TEXT` | Unicode text string |
| 3 | `OBJ_RECORD` | Key-value object with prototype chain |
| 4 | `OBJ_FUNCTION` | Function (C, bytecode, register, or mcode) |
| 5 | `OBJ_CODE` | Compiled bytecode |
| 4 | `OBJ_FUNCTION` | Function (C, register, or mcode) |
| 5 | `OBJ_CODE` | Compiled code |
| 6 | `OBJ_FRAME` | Stack frame for closures |
| 7 | `OBJ_FORWARD` | Forwarding pointer (GC) |
@@ -93,17 +93,16 @@ struct JSFunction {
objhdr_t header; // type=4
JSValue name; // function name
int16_t length; // arity (-1 for variadic)
uint8_t kind; // C, bytecode, register, or mcode
uint8_t kind; // C, register, or mcode
union {
struct { ... } cfunc; // C function pointer
struct { ... } bytecode; // bytecode + frame
struct { ... } regvm; // register VM code
struct { ... } mcode; // mcode IR
} u;
};
```
The kind field selects which union variant is active. Functions can be implemented in C (native), bytecode (stack VM), register code (mach VM), or mcode (JSON interpreter).
The kind field selects which union variant is active. Functions can be implemented in C (native), register code (mach VM), or mcode (JSON interpreter).
## Frame