docs

src/opcode.ts

@@ -1,65 +1,65 @@
 export enum OpCode {
   // stack
-  PUSH,  // operand: constant index (number)
+  PUSH,  // operand: constant index (number) | stack: [] → [value]
-  POP,   // operand: none
+  POP,   // operand: none | stack: [value] → []
-  DUP,   // operand: none
+  DUP,   // operand: none | stack: [value] → [value, value]
 
   // variables
-  LOAD,  // operand: variable name (string)
+  LOAD,  // operand: variable name (identifier) | stack: [] → [value]
-  STORE, // operand: variable name (string)
+  STORE, // operand: variable name (identifier) | stack: [value] → []
 
-  // math
+  // math (coerce to number, pop 2, push result)
-  ADD,
+  ADD,   // operand: none | stack: [a, b] → [a + b]
-  SUB,
+  SUB,   // operand: none | stack: [a, b] → [a - b]
-  MUL,
+  MUL,   // operand: none | stack: [a, b] → [a * b]
-  DIV,
+  DIV,   // operand: none | stack: [a, b] → [a / b]
-  MOD,
+  MOD,   // operand: none | stack: [a, b] → [a % b]
 
-  // comparison
+  // comparison (pop 2, push boolean)
-  EQ,
+  EQ,    // operand: none | stack: [a, b] → [a == b] (deep equality)
-  NEQ,
+  NEQ,   // operand: none | stack: [a, b] → [a != b]
-  LT,
+  LT,    // operand: none | stack: [a, b] → [a < b] (numeric)
-  GT,
+  GT,    // operand: none | stack: [a, b] → [a > b] (numeric)
-  LTE,
+  LTE,   // operand: none | stack: [a, b] → [a <= b] (numeric)
-  GTE,
+  GTE,   // operand: none | stack: [a, b] → [a >= b] (numeric)
 
   // logical
-  NOT,
+  NOT,   // operand: none | stack: [a] → [!isTrue(a)]
 
   // control flow
-  JUMP,
+  JUMP,           // operand: relative offset (number) | PC-relative jump
-  JUMP_IF_FALSE,
+  JUMP_IF_FALSE,  // operand: relative offset (number) | stack: [condition] → [] | jump if falsy
-  JUMP_IF_TRUE,
+  JUMP_IF_TRUE,   // operand: relative offset (number) | stack: [condition] → [] | jump if truthy
-  BREAK,
+  BREAK,          // operand: none | unwind call stack to break target
 
   // exception handling
-  PUSH_TRY,
+  PUSH_TRY,      // operand: absolute catch address (number) | register exception handler
-  PUSH_FINALLY,
+  PUSH_FINALLY,  // operand: absolute finally address (number) | add finally to current handler
-  POP_TRY,
+  POP_TRY,       // operand: none | remove exception handler (try completed successfully)
-  THROW,
+  THROW,         // operand: none | stack: [error] → (unwound) | throw exception
 
   // functions
-  MAKE_FUNCTION,
+  MAKE_FUNCTION, // operand: function def index (number) | stack: [] → [function] | captures scope
-  CALL,
+  CALL,          // operand: none | stack: [fn, ...args, posCount, namedCount] → [result] | marks break target
-  TAIL_CALL,
+  TAIL_CALL,     // operand: none | stack: [fn, ...args, posCount, namedCount] → [result] | reuses frame
-  RETURN,
+  RETURN,        // operand: none | stack: [value] → (restored with value) | return from function
 
   // arrays
-  MAKE_ARRAY,
+  MAKE_ARRAY,  // operand: item count (number) | stack: [item1, ..., itemN] → [array]
-  ARRAY_GET,
+  ARRAY_GET,   // operand: none | stack: [array, index] → [value]
-  ARRAY_SET,
+  ARRAY_SET,   // operand: none | stack: [array, index, value] → [] | mutates array
-  ARRAY_PUSH,
+  ARRAY_PUSH,  // operand: none | stack: [array, value] → [] | mutates array
-  ARRAY_LEN,
+  ARRAY_LEN,   // operand: none | stack: [array] → [length]
 
   // dicts
-  MAKE_DICT,
+  MAKE_DICT,   // operand: pair count (number) | stack: [key1, val1, ..., keyN, valN] → [dict]
-  DICT_GET,
+  DICT_GET,    // operand: none | stack: [dict, key] → [value] | returns null if missing
-  DICT_SET,
+  DICT_SET,    // operand: none | stack: [dict, key, value] → [] | mutates dict
-  DICT_HAS,
+  DICT_HAS,    // operand: none | stack: [dict, key] → [boolean]
 
   // typescript interop
-  CALL_NATIVE,
+  CALL_NATIVE, // operand: function name (identifier) | stack: [...args] → [result] | consumes entire stack
 
   // special
-  HALT
+  HALT         // operand: none | stop execution
 }