Bytecode

Kong Bytecode Specification

This document describes the bytecode format and data structures used by Kong, as defined in the DataStruct.Bytecode modules.

---

🧩 Value Representation

Value

Represents a runtime value handled by the Kong virtual machine.

Constructor	Description
VNumber Number	A numerical value (integer, float, bool, etc.)
VList (Vector Value)	A list (vector) of Values
VStruct (Map String Value)	A structured object with named fields
VFunction [String] (Vector Instr)	A user-defined function with parameters and instructions
VRef HeapAddr	A reference to a heap address
VEmpty	An empty value

MemoryCell

Defines where a value is stored.

Variant	Description
THEAP	Heap-allocated value
TSTACK	Stack-allocated value

Env is defined as a mapping of variable names to (Value, MemoryCell).

---

⚙️ Instructions

Instr

Represents a single bytecode instruction executed by the Kong VM.

Stack Manipulation

Instruction	Description
Push Value	Push a constant value to the stack
PushEnv String	Push a variable from the environment
Call	Call a function (function : arg1 : arg2 : …)
Ret	Return from a function
Nop	No operation

Assignments

Instruction	Description
SetVar String	Assign a variable (value : xs)
SetList	Assign an element in a list (list : index : value : xs)
SetStruct String	Assign a field in a struct (struct : value : xs)

List Management

Instruction	Description
ListPush	Push a value to a list (list : value : xs)
ListPop	Pop a value from a list (list : xs)

Access

Instruction	Description
GetList	Access a list element (list : index : xs)
GetStruct String	Access a struct field (struct : xs)

Creation

Instruction	Description
CreateList Int	Create a list of N values (e.g. value1 : value2 : xs)
CreateStruct [String]	Create a struct from a list of fields

Jumps / Flow Control

Instruction	Description
Jump Int	Add the value of the int to the instruction pointer
JumpIfFalse Int	Jump if top of stack is false
JumpIfTrue Int	Jump if top of stack is true

Operations

Instruction	Description
DoOp Op	Perform a native operation (+, -, etc.)
Cast NumberType	Cast a number into another numeric type
Length	Get the length of a list on top of the stack

Heap Management

Instruction	Description
Alloc	Allocate memory on the heap
LoadRef	Load a value from a reference
StoreRef	Store a value into a reference (addr : value : xs)

System Calls

Instruction	Description
Syscall Syscall	Perform a system call (I/O, exit, etc.)

---

🧮 Numeric Values

Number

Represents any numerical or primitive value.

Variant	Description
VInt Int32	32-bit signed integer
VBool Bool	Boolean value
VChar Char	Character
VFloat Double	Floating point number
VLong Int64	64-bit signed integer
VUInt Word32	32-bit unsigned integer

NumberType

Defines the target type for casts.

Variant	Description
NTInt	Integer
NTBool	Boolean
NTChar	Character
NTFloat	Float
NTLong	Long
NTUInt	Unsigned Integer

---

🔢 Operators

Op

Represents a built-in binary or unary operation.

Operator	Symbol	Description
Add	+	Addition
Sub	-	Subtraction
Mul	*	Multiplication
Div	/	Division
Equal	==	Equality
Lt	<	Less than
Gt	>	Greater than
Le	<=	Less than or equal
Ge	>=	Greater than or equal
Ne	!=	Not equal
Mod	%	Modulo
And	&&	Logical AND
Or	`
Not	!	Logical NOT

---

🖥️ Syscalls

Syscall

Represents low-level system calls available to the VM.

Syscall	Description
Exit	Exit the program
Print Int	Print a value from the stack (argument = file descriptor)
Read	Read input
Write	Write output
Open	Open a file
Close	Close a file
GetArgv	Retrieve program arguments

---

📦 Serialization

All structures implement the Binary typeclass, meaning they can be serialized (put) and deserialized (get) for storage or execution by the VM.

Each constructor is encoded as a Word8 tag followed by its serialized data.

---

Modules Defined:

• DataStruct.Bytecode.Value
• DataStruct.Bytecode.Number
• DataStruct.Bytecode.Op
• DataStruct.Bytecode.Syscall

here is some sample of bytecode

(i++) function for exemple

SetVar "i"
PushEnv "i"
LoadRef
SetVar "tmp"
PushEnv "i"
LoadRef
Push (VNumber (VInt 1))
DoOp Add
PushEnv "i"
StoreRef
PushEnv "tmp"
Ret