Documentation

Main Dispatcher Function: Compiles any AST node.

@args - ast: The AST node to compile.

@details This is the central router of the compiler. It pattern-matches on the AST constructors and delegates to the appropriate specific compilation function. It passes itself (compileAst) recursively to handle nested expressions.

@return Unit value wrapped in CompilerMonad.

Compiles a conditional expression (If-Then-Else).

@args - compileFn: The recursive compilation function. - cond: The condition AST. - thenBranch: The AST for the True branch. - elseBranch: The AST for the False branch.

@details Generates labels for the Else block and the End. Emits JumpIfFalse to skip the Then block if appropriate, and an unconditional Jump to skip the Else block after executing Then.

@return Unit value wrapped in CompilerMonad.

Compiles a For loop.

@args - compileFn: The recursive compilation function. - initAst: The initialization AST (executed once). - cond: The loop condition AST. - updateAst: The update/increment AST (executed after each iteration). - body: The loop body AST.

@details Compiles the initialization step first. Then uses compileLoop for the condition and body. Finally, compiles the update step before jumping back.

@return Unit value wrapped in CompilerMonad.

Compiles a While loop.

@args - compileFn: The recursive compilation function. - cond: The loop condition AST. - body: The loop body AST.

@details Generates start and end labels. Uses compileLoop for the core logic and handles the looping jump back to start.

@return Unit value wrapped in CompilerMonad.

Compiles a variable definition.

@args - compileFn: The recursive compilation function. - name: The name of the variable to define. - body: The expression to evaluate.

@details Compiles the body to push the value onto the stack, allocates a new global symbol index, and emits a StoreGlobal instruction.

@return Unit value wrapped in CompilerMonad.

Compiles a structure instantiation.

@args - compileFn: The recursive compilation function. - name: The name of the structure to instantiate. - assignedFields: The list of (Field Name, Value AST) pairs.

@details Retrieves the structure definition from CompilerState using getStructDefinition. Reorders the provided values to match the definition order, compiles them (pushing to stack), and emits a BuildStruct instruction. Returns an error if the struct is undefined or fields mismatch.

@return Unit value wrapped in CompilerMonad.

Compiles a named function definition.

@args - compileFn: The recursive compilation function. - name: The function name. - args: The list of parameter names. - body: The function body AST.

@details Generates a label for the function and compiles the body within an isolated function scope. Arguments are registered as ScopeLocal symbols (indices 0 to N-1). The compiled code is stored in csFuncs.

@return Unit value wrapped in CompilerMonad.

Compiles a lambda definition.

@args - compileFn: The main compilation function (recursion). - params: List of parameter names. - body: The body of the lambda.

@details 1. Identifies free variables (captures). 2. Emits code to push captures onto the stack. 3. Generates a unique label for the lambda body. 4. Compiles the body in an isolated scope. 5. Emits MakeClosure to create the closure object at runtime.

Registers a structure definition.

@args - name: The name of the structure. - fields: The list of (Field Name, Field Type) pairs.

@details Updates the CompilerState to store the list of field names in order. No bytecode is emitted for a structure definition (it is a compile-time metadata operation).

@return Unit value wrapped in CompilerMonad.

Helper function for Tail Call Optimization

@args - compileFn: The standard compilation function for non-tail expressions. - ast: The AST node to compile in tail position.

@details Detects if the expression is a function call. If so, emits TailCallLabel (TCO). If it is a control structure (If, List), it propagates the tail context recursively. Otherwise, compiles normally and emits Ret.

Helper function to compile the common logic of loops.

@args - compileFn: The recursive compilation function. - cond: The condition AST. - body: The body AST. - lEnd: The label to jump to if the condition is false.

@details Compiles the condition, emits the jump-if-false check, and compiles the body. This sequence is shared between While and For loops.

Compiles a struct field access.

@details 1. Infers the type of the object being accessed (e.g., Player). 2. Looks up the field index in the struct definition. 3. Emits the code for the object followed by GET_STRUCT_FIELD.

Analyzes an AST node to find free variables (variables used but not defined locally).

@args - node: The AST node to analyze.

@details Recursively traverses the AST to compute the set of free variables. For a Lambda, free vars are (body_free_vars - parameters). For a Define, the defined name is excluded from the body's free vars. This function is critical for determining closure captures. Built-in operators (like +, -, *) are excluded from free variables.

@return A Set of Text representing the names of free variables.

Infers the type of an AST expression.

@details - ASymbol: Look up the variable in the symbol table. - AAccessStruct: Recursively infer the parent object's type, then look up the field's type.