toolchain/ast

Anything that can appear at the top level of a file.

What an import binds: a namespace alias, a modifier list, or nothing.

The three forms of SPEC §Modules: X :: import "p", import "p" { a as b }, and the bare import "p" wildcard.

Which of the three for shapes a loop is: for {}, for cond {}, for x in xs {}.

Any expression. Also serves as TypeExpr, see the note there.

One piece of a string literal: literal text, or an interpolated expression.

What follows an else: another if branch, or a final block.

Anything that can appear on the left of a match arm's ->.

What a :: / := binds: one name, a tuple destructure, _, or a rest binding.

One element of a [...] = value assignment: a place, _, or a ...rest tail.

Inside a struct pattern, what a field is matched against: a binding or a literal.

Right operand of ?? (null-coalescing). Either an ordinary value expression (must be assignable to the non-null result type) or a divergent statement (return / break / continue, typed never). The divergent forms are statements (not Expr variants) so they are carried here directly rather than through the Expr union.

A type AS WRITTEN: the same node set as Expr, deliberately.

Vader's type grammar is a subset of its expression grammar (i32, Foo<T>, A | B, fn(i32) -> bool, T[]), so the parser reuses the expression nodes rather than duplicating them. What counts as a type expression is decided by POSITION (the slot demanding a type) never by node shape; the alias exists to say so at each slot (StructField.ty: TypeExpr).

A reader must not assume an IdentExpr in type position denotes a type it can name: Id may be an alias, an imported struct or a distinct newtype, and only the resolver knows which.

Whether a declaration carries export.

One parsed source file.

module is null for a file with no module "..." header: an error the resolver reports rather than the parser.

The module "<name>" decl that opens every .vader file. Carries the validated module name + its source span (the module keyword itself lives in the node's overall span).

One entry of a [T: Bound = Default] list.

is_comptime_value marks a parameter that carries a VALUE rather than a type ([N: i64]), which the comptime engine substitutes.

An @name or @name(args) above a declaration.

An import statement, whatever its form, see ImportBinding.

name :: import "...": namespace binding ; members reached via name.X.

import "p" { x as y, z as _ }: a WILDCARD of p plus per-name modifiers: every listed source name is dropped from the wildcard ; x as y also rebinds it as y, z as _ is a pure exclusion. A plain name (no as) is an error (R2033): the wildcard already brings every export.

bare import "...", wildcard : every function of the module becomes callable (prefix + UFCS) ; binds no name.

One name or name as alias inside an import's modifier list.

alias is null for a bare name, which is R2033: a wildcard already brings it.

A function declaration, name :: fn(...) -> T { ... }.

Four flags mark functions the user did not write. sam_synthetic is a single-abstract-method lambda the parser desugared into an impl member; materialized a member declared for an impl from its trait (one it inherits, inherits, or an intrinsic stub); comptime_synthetic a declaration the comptime engine produced. And is_expression_bodied distinguishes f :: fn() = expr from a braced body, which the formatter needs and a generator emitting source should preserve.

Each is a plain bool defaulting to false, never bool | null (Vader has no optional fields) and the dumper emits one only when true.

One parameter of a function, lambda or trait method.

A struct declaration, Name :: struct { ... }.

The node a generator walks most: fields in declaration order, each carrying its written type. name_span covers the name alone, which is what a diagnostic about the struct itself should point at.

One field of a struct.

visibility is @internal: fields are public by default, so this is the opt-out. default backs T {} construction with the field omitted.

An enum declaration, Name :: enum(u8) { A, B } or Name :: enum(Info) { A { .f = 1 } }.

One variant of an enum, with its explicit value when the source gave one.

A trait declaration.

members are its methods, each an FnDecl; one with a body is a default method.

An implements block, or its one-method short form.

for_type is the implementing type as written, trait_name the trait, which is a bare string rather than a node because a trait is always named, never computed.

A type alias, Name :: SomeType.

A generator resolving a written type must expect to meet one of these: the alias and its target are indistinguishable in an IdentExpr.

A module-level constant, NAME :: value or the typed NAME: T: value.

comptime_body holds the unevaluated expression for a @comptime const, whose value is filled in by the comptime engine.

An @assert at the top level: a build-time invariant.

condition is evaluated by the comptime VM and the build fails with C4015 when it is false. Nothing is emitted at runtime.

A local binding, x :: e or x := e.

mutable is the := form. Style treats a := that is never reassigned as a defect, so a generator should emit :: unless it writes to the slot.

A local bound to one name: a leaf of the recursive binding tree, whose other leaf is WildcardBinding (ignores the slot) and whose only branch is TupleBinding (matches a tuple-typed value element-wise).

name_span covers the name alone: the precise target a rename needs, which the whole-binding span is too wide for.

A destructuring local, [a, b] :: pair.

A discarded local, _ :: e.

The ...rest tail of a destructuring local: collects every slot its sibling SimpleBindings did not consume into a fresh array.

Valid only as the LAST element of a TupleBinding whose source is array-typed.

An assignment to several existing places at once, [a, b] = pair.

Not an AssignStmt over a literal target: its elements are not expressions, _ and ...rest only mean something here.

A place written by a destructuring assignment: a name, a field or an index.

Any expression parses here; the typechecker refuses what is not a place.

A discarded element of a destructuring assignment, _.

The ...rest tail of a destructuring assignment: writes a fresh array of every element its siblings did not consume into place.

Valid only as the LAST target, over an array-typed source.

An assignment to an existing place, target = value.

lhs op= rhs parses to one too : value is lhs op rhs over the SAME lhs node as target, which compound_assign_op recognises.

An expression evaluated for its effect, its value discarded.

A return, with no value for a void function.

yield expr inside a generator fn body: emit one element and suspend. Always carries a value (unlike return, which may be bare); the empty / exhausted case is a bare return or falling off the end. value must coerce to the T of the generator's -> Iterator<T> return.

A loop in any of its three forms, see ForForm.

label is the loop-jump target of break <label> / continue <label>.

The for { ... } form: no condition, exited by break or return.

The for cond { ... } form.

The for x in xs { ... } form.

The loop variable of a for … in …. A union so the mutually exclusive shapes can't be miscombined and no sentinel / span-geometry heuristic is needed downstream: each pass matches on the variant. Kept structural on the AST (not desugared at parse) so vader fmt round-trips every sugar.

for x in …, and the explicit discard for _ in coll (name == "_").

for [k, v] in …: the leaves bind against the iterable's element type.

for <range>: no user variable is written (the iterable is the range itself). Also the lower-synthesised varless for <coll> (while→for sugar).

A break, optionally naming the loop to leave.

A continue, optionally naming the loop to resume.

A defer, running its body when the enclosing scope exits.

A defer deferring one statement.

A defer deferring a block.

Anything that can appear as a statement in a block.

Declared AFTER its variant structs, as DeferBody is: the resolver collects every decl name before resolving types, so either order works and this one reads top-down.

What a defer defers: one statement, or a block.

An integer literal.

Stored as u64 whatever the written base. The literal is FREE (it adopts the surrounding concrete numeric type) so its node carries no width.

A float literal.

true or false.

The null literal.

A character literal, stored as its codepoint.

Free like an integer literal: in an integer context it coerces to that width carrying the codepoint.

A string literal, as the sequence of its parts.

Always a part list, even with no interpolation, so a reader never has to handle two shapes. A generator emitting source must re-escape $, which opens an interpolation.

A run of literal text inside a string literal.

An interpolated ${...} inside a string literal.

A bare name, in value or type position.

implicit_dot marks the leading-dot spelling (.Variant), where resolution defers to the surrounding context. is_type_param_intro marks a dollar-prefixed name introducing a type parameter rather than referring to one.

Both are plain bools defaulting to false, and the dumper emits their JSON keys (implicitDot / isTypeParamIntro) only when true.

A call, callee(args).

callee is an arbitrary expression, so this covers f(x), a.f(x) (whose callee is a FieldExpr) and P.f(x) alike: UFCS is not distinguished here.

One argument of a call.

name is set for a named argument, spread for the ...xs form.

A member access, target.field.

is_numeric marks a tuple index (t.0), whose "field" is a position.

An index, target[index].

Which prefix operator a UnaryExpr applies.

A prefix operator applied to one operand.

Which infix operator a BinaryExpr applies.

An infix operator applied to two operands.

Null-coalescing left ?? fallback. left must be typed T | null ; the expression yields T (null subtracted). fallback supplies the value when left is null : either a value expression assignable to T, or a divergent statement (return / break / continue, typed never). Lowers to _t :: left ; if _t is null { fallback } else { _t }, so the existing narrowing engine refines the result to T.

An if, in statement or value position.

One node for both: in value position the blocks' trailing expressions are the result, so a generator emitting a conditional value writes this.

An else if, holding the next branch.

A final else block.

A match over a scrutinee.

partial is @partial: the match is knowingly non-exhaustive; unreachable is @unreachable: the uncovered variants are impossible and trap if reached.

One arm of a match, with its optional if guard.

A braced block.

trailing is the block's value when it ends in an expression rather than a statement, which is what makes a block usable in value position.

A lambda, (x: i32) -> x + 1.

A struct literal, Point { .x = 1 }.

items mixes fields and spreads in SOURCE order, which a generator must preserve: a later field overrides an earlier spread.

One entry of a struct literal: a field, or a spread.

A .name = value entry of a struct literal.

A ...expr entry of a struct literal.

An array or tuple literal, [a, b, c].

One node for both: the parser does not commit to array or tuple, and the typechecker decides from context.

A range, a..<b or a..=b.

await e: suspend the enclosing async fn until e's async result is ready, then produce it. A single-operand prefix wrapper; carries no error semantics of its own.

An explicit conversion, T(value).

Only a genuine width or representation change needs one: a free literal adopts its context, so a cast around one is a style defect.

A generic type with its arguments written, Box<i32> : in a type, as a struct literal's name, as the owner of a static member call (Bag<T>.make()). A call's own type arguments are CallExpr.type_args.

A call to a compiler intrinsic: @size_of(T), @type_name(T).

name is the intrinsic ident WITHOUT the leading @. The recognised set lives in vader/front/parser/intrinsics.vader, and the parser mints this node only for a known name: an unknown @name(...) in expression position raises P1014.

A bare .Variant, whose enum type comes from context.

A type test in a pattern, is T. inner nests a further pattern.

Binds nothing: the arm reads the scrutinee, narrowed in place, or the name the match header gives it (MatchExpr.binding).

A struct destructuring pattern.

One field of a struct pattern.

A struct-pattern field bound to a name.

A struct-pattern field matched against a literal.

The _ pattern.

On a closed union this silences the exhaustiveness check, which is why the style guide forbids it in value position there.

A pattern matching one enum variant, .Variant.

Match a literal value : 'a' -> …, 42 -> …, "ok" -> …, etc. The inner value is the parsed literal as an Expr ; the lowerer emits scrutinee == value as the arm predicate.

Range pattern : 'a'..='z' -> …, 0..<10 -> …. Matches when a scalar scrutinee falls in the range. inclusive = ..= (upper bound included), else ..< (excluded). The bounds are literal scalar exprs (char / int) of the scrutinee's type ; the lowerer emits scrutinee >= lower && scrutinee <(=) upper. Binds nothing, and (like a literal pattern over an open scalar domain) exhausts nothing.

Or-pattern : .A | .B -> …, 1 | 2 | 3 -> …. Matches when ANY alternative matches. Parsed from pipe-separated patterns in a match arm. The is A | B form does NOT produce this: there the type parser folds A | B into a single union IsPattern (equivalent narrowing + exhaustiveness). The alternatives are value-level (enum variants / literals) and bind nothing.

A function type as written, fn(i32) -> bool: type-only, with no value-side counterpart.

An array type as written, T[]: type-only.

The bracketed form [T1, T2] parses as a SeqLitExpr (tuple type) instead.

The /// lines written right above a declaration, a struct field or an enum variant: its vaderdoc.

Only a parse that asks for docs fills one (parse_source_with_docs in vader/front/parser): the parse_source a build runs leaves every doc null, so a build pays nothing for comments it never reads. A plain // or /* */ comment between the lines and the declaration detaches them; blank lines do not.

One /// line of a DocComment.

A vaderdoc split by its tags.

What one @param says.

A line of an example, as a reader sees it.

Any node inspect hands its visitor: a declaration, an expression (a type expression included, TypeExpr being the same union), a statement or a pattern.

What the visitor of inspect answers for the node it was handed.

The value expression a read-only expression walker should descend into for a ?? fallback : the fallback expression itself, the value of a return <expr>, or null for a bare return / break / continue. Passes that also need to visit the statement node itself (id assignment, typecheck, formatting) destructure CoalesceFallback directly instead.

The places a destructuring assignment writes, in order: every target but _.

For the walkers that visit a statement's sub-expressions and have no use for each element's kind.

Whether decs carries the decorator called name.

Here rather than in each pass: six modules open-coded this loop, and a decorator's presence is a question about the AST, which is what this module owns.

The decorator called name among decs, the first when several are.

The C type a @c_type("…") among decs names, or "" when none does or its argument is not one plain string.

The C symbol an @extern declaration binds: the last argument of its @extern (@extern("c_name"), @extern(LIBRARY, "c_name")), else the name the declaration declares.

The header an @extern declaration's own @c_header names, verbatim with its brackets, or "" when it carries none.

The header that owns the prototype of an @extern declaration: its own @c_header, else the header of the library it names. "" when none does.

The backend INCLUDES that header instead of synthesising a prototype: the header already has the real one, and a synthesised one that differs is a conflicting declaration the C compiler refuses outright.

The C type a struct declaration mirrors, or "" when it carries no @c_struct.

A bare @c_struct names the C type after the struct, read as a typedef name: Color mirrors Color. The argument spells a C type whose name differs (@c_struct("struct pollfd")). An argument that is not one plain string reads as ""; the parser reports it (P1032, P1033).

The span of the name decl declares.

The decorators written above decl.

Whether decl carries export.

The declaration whose body fd runs: for a member an impl inherits, the trait's member (inherits), whose default body it is ; fd itself otherwise. A reader of a member's body goes through it, or sees an inherited member as bodyless.

The operator of a compound assignment lhs op= rhs, or null for a plain one.

target and value.left are one node, so they carry one span ; a hand-written a = a + 1 reads an a of its own, at another position. A pass that evaluates lhs's operands once, or prints the op= back, keys on this, and a pass that copies an assignment keeps the two sides one node.

Whether op is an arithmetic operator a compound assignment spells : + - * / %, and the wrapping +% -% *%.

The value of an integer literal as an i64: a magnitude past i64 as its bits, the least i64 from its magnitude 2^63.

An integer literal in decimal, signed as written: -128, 300.

The text of e when it is a string literal of one run of text, with no interpolation: what a name spelled out at build time reads (@field(x, "n")).

The operator as the source spells it, "+" for Add : what a diagnostic quotes and the formatter prints.

The operator as the source spells it, "-" for Neg.

Flatten a T | U | V | … BitOr BinaryExpr chain into its variant list, in source order. Non-BitOr expressions are returned as a single-element list. Used by vader/tools/fmt and vader/front/typecheck to avoid hand-rolling the same recursion on each side.

The text of doc: its lines joined by \n, each without its /// and the one space that usually follows.

The vaderdoc written above decl.

Split the vaderdoc text by its tags.

A tag opens a line and runs until the next tag or a blank line: the lines under it join its text, wherever they are indented. A non-tag line after a blank one is prose again. @example runs to the end, and text on its own line is the example's first line.

The vaderdoc tag line opens, or "": @param, @return, @error or @example, followed by a blank or the end of the line, so @params opens none.

The parameter a @param names: the identifier its text opens with, "" when it opens with none.

The example of sections as a reader sees it: without the lines that open with # , which set it up so that it compiles, and without the indentation the shown lines share.

The lines of the example of sections, hidden ones included, without the blank lines around them.

Walk n and every node under it, root first, children in source order.

Every child is reached: type positions (a parameter's type, a cast's target, an is pattern's type), decorator arguments, lambda and defer bodies, the statement a ?? falls back to. A node shared with another field is reached once: the place of a compound assignment x op= y is the left operand of its value, and a @comptime const leaves its comptime_body and its type to the helper fn the parser synthesised, which holds both. What is not a node (a binding, a field name) is for the visitor to read on the node that carries it.

Sentinel id on a node the parser has just minted.

Node ids are assigned in a later pass (vader/front/parser::assign_program_ids), which replaces this with a fresh unique value (≥ 1), so a freshly parsed tree carries the sentinel everywhere. A generator reading a typechecked tree sees real ids; one building nodes by hand leaves them at the default: it is every node's .id default, so a construction may omit the field.