ast

type AssignStatement ¶

type AssignStatement struct {
	BaseNode
	Targets []Expression
	Values  []Expression
}

AssignStatement is `varlist = explist`. Each Target must be an Identifier (global/local reference) or an IndexExpression.

func (a *AssignStatement) String() string

func (a *AssignStatement) TokenLiteral() string

type BaseNode ¶

type BaseNode struct {
	Token token.Token
}

BaseNode carries the location and lexeme that every AST node tracks.

It is embedded by value (not as *BaseNode): nodes are always handled through pointers, so the pointer-receiver Line() still promotes, and value embedding saves one heap allocation per node during parsing (~30% fewer parse-phase allocations). Do not change this to *BaseNode.

func (b *BaseNode) Line() int

type BinaryExpression ¶

type BinaryExpression struct {
	BaseNode
	Op    string
	Left  Expression
	Right Expression
}

BinaryExpression covers every Lua 5.4 binary operator:

• - * / // % ^ .. == ~= < > <= >= and or & | ~ << >>

func (be *BinaryExpression) String() string

func (be *BinaryExpression) TokenLiteral() string

type BindingPattern ¶

type BindingPattern struct {
	BaseNode
	Name *Identifier
}

BindingPattern matches anything and binds it to Name in the arm body (and in any guard). Prefer WildcardPattern when no binding is needed — a leading-underscore name is still a binding, not a wildcard.

func (bp *BindingPattern) String() string

func (bp *BindingPattern) TokenLiteral() string

type Block ¶

type Block struct {
	BaseNode
	Statements []Statement
	Return     *ReturnStatement
}

Block is a sequence of statements optionally terminated by a return. Lua's grammar requires `return` to be the last statement of a block, so we model it as a separate field rather than as just another Statement.

func (b *Block) IsEmpty() bool

func (b *Block) String() string

func (b *Block) TokenLiteral() string

type BooleanLiteral ¶

type BooleanLiteral struct {
	BaseNode
	Value bool
}

BooleanLiteral represents `true` or `false`.

func (b *BooleanLiteral) String() string

func (b *BooleanLiteral) TokenLiteral() string

type BreakStatement ¶

type BreakStatement struct {
	BaseNode
}

BreakStatement is `break`.

func (*BreakStatement) String() string

func (b *BreakStatement) TokenLiteral() string

type CallExpression ¶

type CallExpression struct {
	BaseNode
	Func Expression
	Args []Expression
}

CallExpression is `f(args)`. The parser also folds `f"str"` and `f{tbl}` into this shape with a single-element Args slice.

func (ce *CallExpression) String() string

func (ce *CallExpression) TokenLiteral() string

type ContinueStatement ¶

type ContinueStatement struct {
	BaseNode
}

ContinueStatement is `continue` — jump to the next iteration of the innermost enclosing loop. `continue` is a *contextual* keyword (like `type` and `struct`, matching Luau): it is only recognised in statement position when the following token cannot extend it into an expression, so existing code using `continue` as a variable name keeps compiling.

func (*ContinueStatement) String() string

func (c *ContinueStatement) TokenLiteral() string

type DeferStatement ¶

type DeferStatement struct {
	BaseNode
	Call Expression
}

DeferStatement is `defer <call>` — the call runs when the enclosing function unwinds (normal return, fall-off-end, or an error caught by pcall), in last-in-first-out order. Call is the bare function/method call expression; the bytecode generator wraps it in a zero-arg closure so it executes lazily at frame teardown.

func (ds *DeferStatement) String() string

func (ds *DeferStatement) TokenLiteral() string

type DoStatement ¶

type DoStatement struct {
	BaseNode
	Body *Block
}

DoStatement is `do block end` — a bare scoping block.

func (d *DoStatement) String() string

func (d *DoStatement) TokenLiteral() string

type EnumStatement ¶

type EnumStatement struct {
	BaseNode
	Name     *Identifier
	Variants []*EnumVariantDef
}

EnumStatement: enum Color

RED,
GREEN,
BLUE

END

func (es *EnumStatement) IsTagged() bool

func (es *EnumStatement) String() string

func (es *EnumStatement) TokenLiteral() string

type EnumVariantDef ¶

type EnumVariantDef struct {
	Name string
	// Payload holds the positional field types of a *tagged* variant, e.g.
	// `Circle(number)` → one entry, `Rect(number, number)` → two. Empty
	// (nil) for a bare variant. Any variant carrying a payload promotes the
	// whole enum to a tagged (sum-type) enum; see EnumStatement.IsTagged.
	Payload []TypeNode
}

type Expression ¶

type Expression interface {
	// contains filtered or unexported methods
}

Expression is any node that appears in an expression position.

type ExpressionStatement ¶

type ExpressionStatement struct {
	BaseNode
	Expression Expression
}

ExpressionStatement wraps a top-level expression. The Lua grammar only permits function and method calls in this position; the parser is responsible for rejecting anything else.

func (es *ExpressionStatement) String() string

func (es *ExpressionStatement) TokenLiteral() string

type FloatLiteral ¶

type FloatLiteral struct {
	BaseNode
	Value float64
}

FloatLiteral represents a Lua float subtype value.

func (fl *FloatLiteral) String() string

func (fl *FloatLiteral) TokenLiteral() string

type FunctionDeclaration ¶

type FunctionDeclaration struct {
	BaseNode
	Name         *Identifier
	DottedFields []string
	MethodName   string
	Func         *FunctionExpression
}

FunctionDeclaration is `function funcname funcbody`. funcname has the form

Name {`.` Name} [`:` Name]

modeled here as a base Identifier, zero-or-more dotted fields, and an optional MethodName for the colon form (`function t.a.b:m()`). When MethodName != "" the implicit `self` parameter is conventionally inserted at codegen time.

func (fd *FunctionDeclaration) String() string

func (fd *FunctionDeclaration) TokenLiteral() string

type FunctionExpression ¶

type FunctionExpression struct {
	BaseNode
	TypeParams  []string // generic parameters `<T, U>`; empty for a non-generic function
	Params      []TypedParam
	IsVararg    bool
	VarargType  TypeNode
	ReturnTypes []TypeNode
	Body        *Block
}

FunctionExpression is `function(params) body end`. IsVararg is true when the parameter list ends in `...`. ReturnTypes carries the optional `: T` / `: (T1, T2)` annotation between `)` and the body. VarargType is the optional `...: T` annotation. All type fields are nil-safe.

func (fe *FunctionExpression) String() string

func (fe *FunctionExpression) TokenLiteral() string

type GenericForStatement ¶

type GenericForStatement struct {
	BaseNode
	Names []string
	Exprs []Expression
	Body  *Block
}

GenericForStatement is `for namelist in explist do block end`.

func (f *GenericForStatement) String() string

func (f *GenericForStatement) TokenLiteral() string

type GotoStatement ¶

type GotoStatement struct {
	BaseNode
	Label string
}

GotoStatement is `goto Name` (Lua 5.2+).

func (g *GotoStatement) String() string

func (g *GotoStatement) TokenLiteral() string

type Identifier ¶

type Identifier struct {
	BaseNode
	Name string
}

Identifier names a local, global, or parameter.

func (i *Identifier) String() string

func (i *Identifier) TokenLiteral() string

type IfClause ¶

type IfClause struct {
	Condition Expression
	Body      *Block
}

IfClause is one `if` or `elseif` branch.

type IfExprClause ¶

type IfExprClause struct {
	Condition Expression
	Value     Expression
}

IfExprClause is one `if`/`elseif` branch of an IfExpression: a condition and the single value the expression yields when the condition is truthy.

type IfExpression ¶

type IfExpression struct {
	BaseNode
	Clauses []IfExprClause // at least one; first is `if`, rest are `elseif`
	Else    Expression
}

IfExpression is the Luau-style conditional expression

if c1 then v1 [elseif c2 then v2 ...] else v3

Unlike the if *statement* there is no terminating `end`, the branches are single expressions rather than blocks, and the `else` arm is mandatory (the expression must always produce a value). Every branch is adjusted to exactly one value.

func (ie *IfExpression) String() string

func (ie *IfExpression) TokenLiteral() string

type IfStatement ¶

type IfStatement struct {
	BaseNode
	Clauses []IfClause
	Else    *Block
}

IfStatement is `if c then ... {elseif c then ...} [else ...] end`.

func (i *IfStatement) String() string

func (i *IfStatement) TokenLiteral() string

type IndexExpression ¶

type IndexExpression struct {
	BaseNode
	Object Expression
	Index  Expression
	IsDot  bool
}

IndexExpression is `obj[index]` or, when IsDot is true, `obj.name` — in the dot form Index is a *StringLiteral whose Value is the field name.

func (ie *IndexExpression) String() string

func (ie *IndexExpression) TokenLiteral() string

type IntegerLiteral ¶

type IntegerLiteral struct {
	BaseNode
	Value int64
}

IntegerLiteral represents a Lua 5.3+ integer subtype value.

func (il *IntegerLiteral) String() string

func (il *IntegerLiteral) TokenLiteral() string

type LabelStatement ¶

type LabelStatement struct {
	BaseNode
	Name string
}

LabelStatement is `::Name::` — a goto target.

func (l *LabelStatement) String() string

func (l *LabelStatement) TokenLiteral() string

type LiteralPattern ¶

type LiteralPattern struct {
	BaseNode
	Value Expression
}

LiteralPattern matches by structural equality against a constant. Value must be one of *NilLiteral, *BooleanLiteral, *IntegerLiteral, *FloatLiteral, *StringLiteral — the parser is responsible for that constraint; the AST does not enforce it via the type system to avoid inventing a duplicate "literal expression" interface.

func (lp *LiteralPattern) String() string

func (lp *LiteralPattern) TokenLiteral() string

type LocalFunctionStatement ¶

type LocalFunctionStatement struct {
	BaseNode
	Name string
	Func *FunctionExpression
}

LocalFunctionStatement is `local function Name funcbody`.

func (lf *LocalFunctionStatement) String() string

func (lf *LocalFunctionStatement) TokenLiteral() string

type LocalName ¶

type LocalName struct {
	Name   string
	Attrib string
	Type   TypeNode
}

LocalName is one entry in a `local` declaration. Attrib is "" for a plain local, or "const" / "close" for the Lua 5.4 attributes (`<const>`, `<close>`). Type is the optional Luau-style annotation (`local x: number`); nil if unannotated.

type LocalStatement ¶

type LocalStatement struct {
	BaseNode
	Names  []LocalName
	Values []Expression
}

LocalStatement is `local namelist [= explist]`.

func (ls *LocalStatement) String() string

func (ls *LocalStatement) TokenLiteral() string

type MatchArm ¶

type MatchArm struct {
	BaseNode
	Pattern Pattern
	Guard   Expression // optional `if expr` between pattern and `->`; nil when absent
	Body    Expression
}

MatchArm is one `pattern [if guard] -> body` clause. Token points at the first token of the pattern so the typechecker can report arm-specific errors (non-exhaustive, unreachable, type mismatch).

type MatchExpression ¶

type MatchExpression struct {
	BaseNode
	Subject Expression
	Arms    []MatchArm
}

MatchExpression is `match subject { p1 -> e1, p2 if g -> e2, _ -> e3 }`. It is exhaustive: every possible value of Subject must be covered by some arm (a trailing `_ -> ...` is the usual way to satisfy that).

func (me *MatchExpression) String() string

func (me *MatchExpression) TokenLiteral() string

type MatchFieldBind ¶

type MatchFieldBind struct {
	Field string
	Bind  string
}

MatchFieldBind is one `field = binder` entry of a named destructure. Bind == "_" matches the field without binding it.

type MatchPattern ¶

type MatchPattern struct {
	Kind       MatchPatternKind
	Values     []Expression     // MatchValue: one or more alternatives
	Bind       string           // MatchTyped: binder name ("" / "_" = none)
	Type       TypeNode         // MatchTyped
	Tag        string           // destructures: variant/struct name (last path segment)
	PosBinds   []string         // MatchDestructurePos: binders ("_" = skip)
	NamedBinds []MatchFieldBind // MatchDestructureNamed
}

MatchPattern is the pattern of one match-statement arm. Kind selects which of the remaining fields are meaningful (see the per-kind comments above).

func (mp *MatchPattern) Binders() []string

func (mp *MatchPattern) String() string

type MatchPatternKind ¶

type MatchPatternKind int

MatchPatternKind tags the shape of a match-statement arm pattern.

const (
	// MatchValue compares the scrutinee with `==` against each entry of
	// Values (comma-separated alternatives OR together).
	MatchValue MatchPatternKind = iota
	// MatchWildcard is `_` — matches anything, binds nothing.
	MatchWildcard
	// MatchTyped is `name : Type` — matches when the runtime type matches,
	// binding name to the scrutinee (`_ : T` tests without binding).
	MatchTyped
	// MatchDestructurePos is `Variant(a, b, _)` — positional destructure of
	// a payload-carrying tagged-enum variant.
	MatchDestructurePos
	// MatchDestructureNamed is `Struct{ f = a }` — named destructure of a
	// struct instance.
	MatchDestructureNamed
)

type MatchStatement ¶

type MatchStatement struct {
	BaseNode
	Subject Expression
	Arms    []MatchStmtArm
}

MatchStatement is the first-class `match <expr> do <arm>... end` statement. Arms are tried in order; the first whose pattern matches (and whose guard, if any, is truthy) runs. It is NOT exhaustive — when no arm matches, the statement is a no-op. The scrutinee is evaluated exactly once.

func (ms *MatchStatement) String() string

func (ms *MatchStatement) TokenLiteral() string

type MatchStmtArm ¶

type MatchStmtArm struct {
	BaseNode
	Pattern MatchPattern
	Guard   Expression // optional `if expr` between pattern and `->`; nil when absent
	Body    Statement  // exactly one statement (wrap several in `do ... end`)
}

MatchStmtArm is one `pattern [if guard] -> body` clause of a match statement. Token points at the first token of the pattern so later passes can report arm-specific errors.

type MethodCallExpression ¶

type MethodCallExpression struct {
	BaseNode
	Object Expression
	Method string
	Args   []Expression
}

MethodCallExpression is `obj:method(args)` — distinct from CallExpression because the colon form passes `obj` as an implicit first argument.

func (mc *MethodCallExpression) String() string

func (mc *MethodCallExpression) TokenLiteral() string

type NilLiteral ¶

type NilLiteral struct {
	BaseNode
}

NilLiteral represents the `nil` keyword used as an expression.

func (*NilLiteral) String() string

func (n *NilLiteral) TokenLiteral() string

type NumericForStatement ¶

type NumericForStatement struct {
	BaseNode
	Name  string
	Start Expression
	Limit Expression
	Step  Expression
	Body  *Block
}

NumericForStatement is `for Name = e1, e2 [, e3] do block end`. Step is nil when omitted.

func (f *NumericForStatement) String() string

func (f *NumericForStatement) TokenLiteral() string

type ParenExpression ¶

type ParenExpression struct {
	BaseNode
	Inner Expression
}

ParenExpression is a parenthesized expression. In Lua this is semantically meaningful: it adjusts a multi-value result down to exactly one value.

func (pe *ParenExpression) String() string

func (pe *ParenExpression) TokenLiteral() string

type Pattern ¶

type Pattern interface {
	// contains filtered or unexported methods
}

type Program ¶

type Program struct {
	Block *Block
}

Program is the root node — a Lua chunk is a single block.

func (p *Program) Line() int

func (p *Program) String() string

func (p *Program) TokenLiteral() string

type RepeatStatement ¶

type RepeatStatement struct {
	BaseNode
	Body      *Block
	Condition Expression
}

RepeatStatement is `repeat block until cond`. Note: `cond` is evaluated in the scope of locals declared in `Body`.

func (r *RepeatStatement) String() string

func (r *RepeatStatement) TokenLiteral() string

type ReturnStatement ¶

type ReturnStatement struct {
	BaseNode
	Values []Expression
}

ReturnStatement is `return [explist] [;]`. Lua only allows it as the last statement of a block; see Block.Return.

func (rs *ReturnStatement) String() string

func (rs *ReturnStatement) TokenLiteral() string

type Statement ¶

type Statement interface {
	// contains filtered or unexported methods
}

Statement is any node that appears in a statement position.

type StringLiteral ¶

type StringLiteral struct {
	BaseNode
	Value  string
	IsLong bool
}

StringLiteral represents a string literal. IsLong is true when the source used the `[[ ... ]]` long-bracket form.

func (sl *StringLiteral) String() string

func (sl *StringLiteral) TokenLiteral() string

type StructField ¶

type StructField struct {
	Name string
	Type TypeNode
}

StructField is one named field in a StructStatement: `name: T`. Type is never nil — the parser requires an annotation on every struct field (that annotation is the whole point of a struct: a fixed, typed shape).

type StructStatement ¶

type StructStatement struct {
	BaseNode
	Name       *Identifier
	TypeParams []string
	Fields     []StructField
}

StructStatement is a nominal product type declaration:

struct Point {
    x: number,
    y: number,
}

It lowers (in the bytecode generator) to a constructor value bound to `Name`, and registers `Name` both as a type alias for the structural table `{ field: T, ... }` and as a constructor function in the type environment. TypeParams carries the optional `<T, U>` generic parameter list (empty for a non-generic struct).

func (ss *StructStatement) String() string

func (ss *StructStatement) TokenLiteral() string

type TableConstructor ¶

type TableConstructor struct {
	BaseNode
	Fields []TableField
}

TableConstructor is `{ ... }` — Lua's only aggregate literal.

func (tc *TableConstructor) String() string

func (tc *TableConstructor) TokenLiteral() string

type TableField ¶

type TableField struct {
	Key         Expression
	Value       Expression
	IsBracketed bool
}

TableField is a single entry in a TableConstructor.

Key == nil                              -> array entry  ({ v })
Key is *Identifier && !IsBracketed       -> record entry ({ name = v })
IsBracketed                             -> keyed entry  ({ [expr] = v })

type ThrowStatement ¶

type ThrowStatement struct {
	BaseNode
	Value Expression
}

ThrowStatement is `throw <expr>` — raise Value as an error. Any Lua value may be thrown, not just a string.

func (ts *ThrowStatement) String() string

func (ts *ThrowStatement) TokenLiteral() string

type TryCatchStatement ¶

type TryCatchStatement struct {
	BaseNode
	Try      *Block
	CatchVar *Identifier // nil when the handler discards the error value
	Catch    *Block
}

TryCatchStatement is `try <body> catch [err] do <handler> end`. If any statement in Try raises — via `throw`, `error`, or a runtime fault — control transfers to Catch with the raised value bound to CatchVar. Reaching the end of Try normally skips Catch entirely.

The protected region is a real block in the enclosing function, not a closure: `return`, `break`, and `continue` inside Try act on the function or loop that encloses the whole try/catch.

func (tc *TryCatchStatement) String() string

func (tc *TryCatchStatement) TokenLiteral() string

type TypeAliasStatement ¶

type TypeAliasStatement struct {
	BaseNode
	Name       string
	TypeParams []string // generic parameters `<T, U>`; empty for a plain alias
	Target     TypeNode
}

TypeAliasStatement is `type Name = T`. Aliases are top-level (Luau allows them only at chunk scope; we follow the same restriction in later phases by report-and-skip in the checker — the parser is permissive).

func (s *TypeAliasStatement) String() string

func (s *TypeAliasStatement) TokenLiteral() string

type TypeApplication ¶

type TypeApplication struct {
	BaseNode
	Name string
	Args []TypeNode
}

TypeApplication is a generic instantiation `Name<A, B>` — a reference to a generic type alias or struct with concrete type arguments. Resolution (substituting Args for the alias's type parameters) is the checker's job.

func (t *TypeApplication) String() string

func (t *TypeApplication) TokenLiteral() string

type TypeAssertionExpression ¶

type TypeAssertionExpression struct {
	BaseNode
	Expr Expression
	Type TypeNode
}

TypeAssertionExpression is `expr :: T` — a programmer-controlled cast. The runtime is a no-op; the bytecode generator emits the inner Expr's code unchanged. The type checker treats the result as the asserted T.

func (e *TypeAssertionExpression) String() string

func (e *TypeAssertionExpression) TokenLiteral() string

type TypeFunction ¶

type TypeFunction struct {
	BaseNode
	ParamNames []string
	Params     []TypeNode
	Returns    []TypeNode
	IsVararg   bool
	VarargType TypeNode
}

TypeFunction is a function type: `(P1, P2) -> R` or `(P) -> (R1, R2)`. IsVararg+VarargType model `...: T` at the parameter list's tail. ParamNames is parallel to Params and may contain "" for unnamed slots.

func (t *TypeFunction) String() string

func (t *TypeFunction) TokenLiteral() string

type TypeIndexer ¶

type TypeIndexer struct {
	Key   TypeNode
	Value TypeNode
}

TypeIndexer models `{[K]: V}` — a homogeneous map-like indexer.

type TypeName ¶

type TypeName struct {
	BaseNode
	Name string
}

TypeName references a user-defined type alias by name. Resolution is the type checker's job — the parser only records the name.

func (t *TypeName) String() string

func (t *TypeName) TokenLiteral() string

type TypeNode ¶

type TypeNode interface {
	// contains filtered or unexported methods
}

TypeNode is the AST shape of a parsed type expression. These nodes appear only as annotations attached to declarations (`local x: T`, parameters, return types, type aliases) and as the right-hand side of a type assertion (`expr :: T`). They never produce bytecode — the type checker is the sole consumer; the bytecode generator ignores them entirely.

String() on every TypeNode renders Luau-syntax-faithful source so the AST round-trips through `Program.String()` for debugging and tests.

type TypeOptional ¶

type TypeOptional struct {
	BaseNode
	Inner TypeNode
}

TypeOptional is the postfix-`?` sugar: `T?` ≡ `T | nil`. Kept distinct from TypeUnion so source round-trips and error messages preserve the programmer's notation.

func (t *TypeOptional) String() string

func (t *TypeOptional) TokenLiteral() string

type TypePrimitive ¶

type TypePrimitive struct {
	BaseNode
	Name string
}

TypePrimitive names a built-in type: number, string, boolean, nil, any, unknown. The set is fixed; unknown identifiers in type position are parsed as TypeName instead.

func (t *TypePrimitive) String() string

func (t *TypePrimitive) TokenLiteral() string

type TypeTable ¶

type TypeTable struct {
	BaseNode
	Fields  []TypeTableField
	Indexer *TypeIndexer
}

TypeTable is a structural table type: `{ x: number, y: number }` or `{[string]: number}`. Either Fields or Indexer (or both) may be set.

func (t *TypeTable) String() string

func (t *TypeTable) TokenLiteral() string

type TypeTableField ¶

type TypeTableField struct {
	Key   string
	Value TypeNode
}

TypeTableField is one named entry in a TypeTable: `name: T`.

type TypeUnion ¶

type TypeUnion struct {
	BaseNode
	Members []TypeNode
}

TypeUnion is `A | B | C`. Always two or more members; single-member "unions" are flattened to the bare member at parse time.

func (t *TypeUnion) String() string

func (t *TypeUnion) TokenLiteral() string

type TypedParam ¶

type TypedParam struct {
	Name    *Identifier
	Type    TypeNode
	Default Expression
}

TypedParam is one entry in a FunctionExpression's parameter list. Type is nil for unannotated parameters; the type checker treats those as `any` in gradual mode and as an implicit-any error in strict mode. Default is the optional `= expr` default value (nil when absent): at runtime the function prologue fills the parameter with Default when the caller passed nil (or nothing) for it. Earlier parameters are in scope inside Default.

type UnaryExpression ¶

type UnaryExpression struct {
	BaseNode
	Op      string
	Operand Expression
}

UnaryExpression covers `-`, `not`, `#`, `~`.

func (ue *UnaryExpression) String() string

func (ue *UnaryExpression) TokenLiteral() string

type VarargExpression ¶

type VarargExpression struct {
	BaseNode
}

VarargExpression represents the `...` expression inside a vararg function.

func (*VarargExpression) String() string

func (v *VarargExpression) TokenLiteral() string

type WhileStatement ¶

type WhileStatement struct {
	BaseNode
	Condition Expression
	Body      *Block
}

WhileStatement is `while cond do block end`.

func (w *WhileStatement) String() string

func (w *WhileStatement) TokenLiteral() string

type WildcardPattern ¶

type WildcardPattern struct {
	BaseNode
}

WildcardPattern is `_` — matches anything, binds nothing. It is an error for any arm after a wildcard to be reachable.

func (*WildcardPattern) String() string

func (w *WildcardPattern) TokenLiteral() string