bytecode

const (
	Program     = "ProgramStart" // top-level chunk
	FunctionDef = "Function"     // any function body, including the main chunk's
)

const (
	// --- constants & literals ---
	LoadNil    uint8 = iota // params: count               ; pushes `count` nils
	LoadTrue                // pushes true
	LoadFalse               // pushes false
	LoadInt                 // params: int64               ; pushes integer
	LoadFloat               // params: float64             ; pushes float
	LoadString              // params: string              ; pushes string
	LoadVararg              // params: count (-1 = all)    ; expands current frame's `...`
	Closure                 // params: protoIndex          ; pushes closure built from FunctionProto[i]

	// --- variables ---
	GetLocal   // params: slot
	SetLocal   // params: slot
	GetUpvalue // params: index
	SetUpvalue // params: index
	GetGlobal  // params: name
	SetGlobal  // params: name

	// --- tables ---
	NewTable // params: arrayHint, hashHint  ; pushes new empty table
	GetTable // pops key, table              ; pushes table[key]
	SetTable // pops value, key, table       ; table[key]=value
	GetField // params: key (string)         ; pops table; pushes table[key]
	SetField // params: key (string)         ; pops value, table; table[key]=value
	Self     // params: key (string)         ; for `obj:m`. pops obj; pushes obj[key], obj
	SetList  // params: count, offset        ; bulk-fill array part of a table built below the values

	// --- arithmetic ---
	Add
	Sub
	Mul
	Div
	FloorDiv
	Mod
	Pow
	Neg // unary -

	// --- bitwise (Lua 5.3+) ---
	BitAnd
	BitOr
	BitXor
	Shl
	Shr
	BitNot // unary ~

	// --- string / length ---
	Concat // params: count                ; concatenates top `count` values
	Len    // unary #

	// --- comparison ---
	Eq
	NotEq
	Lt
	Le
	Gt
	Ge

	// --- logical ---
	Not // unary not

	// --- control flow ---
	Jump            // params: targetLine
	JumpIfFalse     // params: targetLine ; pops; jump if falsy
	JumpIfTrue      // params: targetLine ; pops; jump if truthy
	JumpIfFalseKeep // params: targetLine ; peeks; if falsy keep & jump, else pop & continue (for `and`)
	JumpIfTrueKeep  // params: targetLine ; peeks; if truthy keep & jump, else pop & continue (for `or`)

	// --- calls / returns ---
	Call   // params: nargs, nresults (-1 = all)
	Return // params: count (-1 = all from base to top)

	// --- numeric for ---
	// baseSlot..baseSlot+2 are hidden control slots (index, limit, step);
	// baseSlot+3 is the visible loop variable, which both opcodes refresh from
	// the hidden index at the top of each iteration. Keeping the counter hidden
	// is what makes assigning to the loop variable inside the body harmless.
	ForPrep // params: baseSlot, targetLine ; uses 3 stack values: start, limit, step
	ForLoop // params: baseSlot, targetLine

	// --- generic for ---
	TForCall // params: baseSlot, nresults
	TForLoop // params: baseSlot, targetLine

	// --- stack utility ---
	Pop // params: count
	Dup // duplicates top of stack

	// --- frame ---
	Leave // ends instruction set (REPL friendly fallback / chunk terminator)

	// MarkArgs records the current stack height onto the VM's call-mark
	// stack. Emitted by compileCall/compileMethodCall ONLY when the call
	// has a multi-value last argument (call, methodcall, or vararg in
	// last position). The matching Call opcode encoded with nargs=-1
	// pops the mark to recover the args base — needed because the spread
	// length isn't known until runtime.
	MarkArgs

	// Defer pops a closure off the stack and registers it on the current
	// frame's deferred list. The VM runs a frame's deferred closures in
	// last-in-first-out order when the frame unwinds (normal return,
	// fall-off-end, or an error caught by pcall). No params.
	Defer

	// CloseUpvalues closes every open upvalue whose slot is at or above the
	// local slot in param A (relative to the current frame base). Emitted at
	// the end of a loop iteration whose body captured a local in a closure, so
	// each iteration's variables are captured independently (Lua 5.4 gives
	// every iteration a fresh loop variable). No stack effect.
	CloseUpvalues

	// Try installs an error handler on the current frame: param A is the
	// instruction index of the matching catch clause. If any error is raised
	// while the handler is installed, the VM unwinds back to this frame,
	// truncates the stack to the height Try observed, pushes the error value,
	// and resumes at A. Handlers nest — the innermost one wins. No stack
	// effect.
	Try

	// EndTry pops the innermost `count` (param A) handlers off the current
	// frame without running them. Emitted on every path that leaves a
	// protected region other than by raising: the fall-through end of a `try`
	// body, and any `break`/`continue` that jumps out of one. No stack effect.
	//
	// A `return` out of a `try` needs no EndTry — handlers live on the frame,
	// so unwinding the frame discards them.
	EndTry

	// Throw pops a value and raises it as a Lua error, identical to what the
	// `error` builtin does (which propagates its argument verbatim, with no
	// position prefix). It is an opcode rather than a lowering to a call so
	// that `throw` cannot be re-pointed by shadowing the name `error`.
	Throw

	InstructionCount
)

const SerialVersion = 2