radiance · Radiance self-hosting compiler

agent/opaque-records
f6905c51 compiler: Initialize decoded operands through exact storage Alexis Sellier 6 days ago
Clone
compiler/ lib/ examples/ std/ arch/ char/ collections/ lang/ alloc/ ast/ gen/ il/ module/ parser/ resolver/ scanner/ alloc.rad 7.1 KiB ast.rad 26.7 KiB gen.rad 513 B il.rad 20.3 KiB lower.rad 315.6 KiB module.rad 14.9 KiB package.rad 1.3 KiB parser.rad 91.2 KiB resolver.rad 452.9 KiB scanner.rad 17.9 KiB sexpr.rad 6.7 KiB strings.rad 2.2 KiB types.rad 1.6 KiB sys/ arch.rad 68 B char.rad 855 B collections.rad 39 B fmt.rad 8.3 KiB intrinsics.rad 467 B io.rad 1.7 KiB lang.rad 276 B mem.rad 2.3 KiB sys.rad 179 B testing.rad 2.4 KiB tests.rad 15.7 KiB vec.rad 3.2 KiB std.rad 281 B scripts/ seed/ sublime/ test/ vim/ .gitignore 336 B .gitsigners 112 B CONTRIBUTING 2.1 KiB LICENSE 1.1 KiB Makefile 5.4 KiB README 2.5 KiB STYLE 2.5 KiB std.lib 1.5 KiB std.lib.test 662 B
lib/std/lang/ast.rad 26.7 KiB raw
//! Radiance AST modules.
export mod printer;

use std::io;
use std::fmt;
use std::lang::alloc;

/// Ownership and safety qualifier written in a pointer type.
/// Named reference regions are separate `TypeSig::RegionRef` nodes.
export union PointerClass: Copy {
    /// Owned pointer introduced by `*`.
    Owned,
    /// Borrowed reference introduced by `&`.
    Ref,
    /// Raw pointer introduced by `*unsafe`.
    Unsafe,
}

/// Maximum number of trait methods.
export constant MAX_TRAIT_METHODS: u32 = 8;

/// Arena for all parser allocations.
///
/// Uses a bump allocator for both AST nodes and node pointer arrays.
export record NodeArena {
    /// Bump allocator for all allocations.
    arena: alloc::Arena,
    /// Next node ID to assign. Incremented on each node allocation.
    nextId: u32,
}

/// Initialize a node arena backed by the given byte slice.
export fn nodeArena(data: *mut [u8]) -> NodeArena {
    return NodeArena {
        arena: alloc::new(data),
        nextId: 0,
    };
}

/// Create an empty `*mut [*Node]` slice with the given capacity.
export unsafe fn nodeSlice(arena: &mut NodeArena, capacity: u32) -> *mut [*Node] {
    if capacity == 0 {
        return &mut [];
    }
    let ptr = try! alloc::allocSlice(&mut arena.arena, @sizeOf(*Node), @alignOf(*Node), capacity);

    let nodes = ptr as *mut [*Node];
    return &mut nodes[..0];
}

/// Attribute bit set applied to declarations or fields.
export union Attribute: Copy {
    /// Public visibility attribute.
    Export = 0b1,
    /// Default implementation attribute.
    Default = 0b10,
    /// Extern linkage attribute.
    Extern = 0b100,
    /// Test-only declaration attribute.
    Test = 0b1000,
    /// Compiler intrinsic attribute.
    Intrinsic = 0b10000,
    /// Declaration may perform unsafe pointer operations.
    Unsafe = 0b100000,
}

/// Ordered collection of attribute nodes applied to a declaration.
export record Attributes: Copy {
    /// Attribute nodes in declaration order.
    list: *[*Node],
}

/// Check if an attributes list contains an attribute.
export fn attributesContains(self: &Attributes, attr: Attribute) -> bool {
    for node in self.list {
        if let case NodeValue::Attribute(a) = node.value; a == attr {
            return true;
        }
    }
    return false;
}

/// Check if an attribute set includes the given attribute.
export fn hasAttribute(attrs: u32, attr: Attribute) -> bool {
    return (attrs & (attr as u32)) <> 0;
}

/// Signedness of an integer type.
export union Signedness: Copy {
    /// Signed, eg. `i8`.
    Signed,
    /// Unsigned, eg. `u32`.
    Unsigned,
}

/// Binary operator kinds used in numeric expressions.
export union BinaryOp: Copy {
    /// Addition (`+`).
    Add,
    /// Subtraction (`-`).
    Sub,
    /// Multiplication (`*`).
    Mul,
    /// Division (`/`).
    Div,
    /// Remainder (`%`).
    Mod,
    /// Bitwise AND (`&`).
    BitAnd,
    /// Bitwise OR (`|`).
    BitOr,
    /// Bitwise XOR (`^`).
    BitXor,
    /// Left shift (`<<`).
    Shl,
    /// Right shift (`>>`).
    Shr,

    /// Equality comparison (`==`).
    Eq,
    /// Inequality comparison (`<>`).
    Ne,
    /// Less-than comparison (`<`).
    Lt,
    /// Greater-than comparison (`>`).
    Gt,
    /// Less-than-or-equal comparison (`<=`).
    Lte,
    /// Greater-than-or-equal comparison (`>=`).
    Gte,

    /// Logical conjunction (`and`).
    And,
    /// Logical disjunction (`or`).
    Or,
    /// Logical exclusive disjunction (`xor`).
    Xor,
}

/// Unary operator kinds used in expressions.
export union UnaryOp: Copy {
    /// Logical negation (`not`).
    Not,
    /// Arithmetic negation (`-`).
    Neg,
    /// Bitwise NOT (`~`).
    BitNot,
}

/// Builtin function kind.
export union Builtin: Copy {
    /// Size of type in bytes (`@sizeOf`).
    SizeOf,
    /// Alignment requirement of type (`@alignOf`).
    AlignOf,
    /// Construct a slice from pointer, length, and optional capacity (`@sliceOf`).
    SliceOf,
}

/// Source extent for a node measured in bytes.
export record Span: Copy {
    /// Byte offset from the start of the source file.
    offset: u32,
    /// Length of the node in bytes.
    length: u32,
}

/// Type signature node.
export union TypeSig: Copy {
    /// Absence of type.
    Void,
    /// A function return type with no possible value.
    Never,
    /// Opaque type.
    Opaque,
    /// Boolean type.
    Bool,
    /// Integer type.
    Integer {
        /// Size of values, in bytes.
        width: u8,
        /// Signedness of values.
        sign: Signedness,
    },
    /// Fixed-size array type, eg. `[i32; 16]`.
    Array {
        /// Array element type.
        itemType: *Node,
        /// Expression that evaluates to the array length.
        length: *Node,
    },
    /// Slice type, eg. `*[i32]`, `&[i32]`, or `*unsafe [i32]`.
    Slice {
        /// Ownership and safety class.
        class: PointerClass,
        /// Slice element type.
        itemType: *Node,
        /// Whether the slice is mutable.
        mutable: bool,
    },
    /// Pointer type, eg. `*i32`, `&i32`, or `*unsafe i32`.
    Pointer {
        /// Ownership and safety class.
        class: PointerClass,
        /// Pointer target type.
        valueType: *Node,
        /// Whether the pointer is mutable.
        mutable: bool,
    },
    /// Optional, eg. `?i32`.
    Optional {
        /// Underlying type.
        valueType: *Node,
    },
    /// Shared cell pointer with value access to its payload.
    Cell {
        /// Storage lifetime and ownership class.
        class: PointerClass,
        /// Copy payload type.
        payload: *Node,
    },
    /// Nominal type, points to identifier node.
    Nominal(*Node),
    /// Reference qualified by a lexical region.
    RegionRef {
        /// Region name node.
        region: *Node,
        /// Reference type node.
        type: *Node,
    },
    /// Nominal type with invariant region arguments.
    Applied {
        /// Nominal type path.
        name: *Node,
        /// Region arguments in declaration order.
        regions: *[*Node],
    },
    /// Inline record type for union variant payloads.
    Record {
        /// Field declaration nodes.
        fields: *[*Node],
        /// Whether this record has labeled fields.
        labeled: bool,
    },
    /// Anonymous function type.
    Fn {
        /// Parameter, return, and error types.
        sig: FnSig,
        /// Whether a call requires an unsafe function body.
        isUnsafe: bool,
    },
    /// Trait object type, eg. `*opaque Allocator`, `&opaque Allocator`, or
    /// `*unsafe opaque Allocator`.
    TraitObject {
        /// Ownership and safety class.
        class: PointerClass,
        /// Trait name identifier.
        traitName: *Node,
        /// Whether the pointer is mutable.
        mutable: bool,
    },
}

/// Function signature.
export record FnSig: Copy {
    /// Parameter type nodes in declaration order.
    params: *[*Node],
    /// Optional return type node.
    returnType: ?*Node,
    /// Throwable type nodes declared in the signature.
    throwList: *[*Node],
}

/// Access provided by an address-of expression.
export union AddressKind: Copy {
    /// Shared access to an immutable value.
    Shared,
    /// Exclusive access to a mutable value.
    Mutable,
    /// Shared access to a mutable Copy payload.
    Cell,
}

/// Address-of expression metadata.
export record AddressOf: Copy {
    /// Target expression being referenced.
    target: *Node,
    /// Access provided by the resulting pointer.
    kind: AddressKind,
}

/// Return whether creating an address requires exclusive source access.
export fn isExclusiveAddress(address: AddressOf) -> bool {
    return address.kind <> AddressKind::Shared;
}

/// Compound statement block with optional dedicated scope.
export record Block: Copy {
    /// Statements that belong to this block.
    statements: *[*Node],
    /// Whether this block permits unsafe operations.
    isUnsafe: bool,
}

/// Function call expression.
export record Call: Copy {
    /// Callee expression.
    callee: *Node,
    /// Argument expressions in source order.
    args: *[*Node],
}

/// Single argument to a function or record literal, optionally labeled.
export record Arg: Copy {
    /// Optional label applied to the argument.
    label: ?*Node,
    /// Expression supplying the argument value.
    value: *Node,
}

/// Assignment expression connecting a target and value.
export record Assign: Copy {
    /// Expression representing the assignment target.
    left: *Node,
    /// Expression providing the value being assigned.
    right: *Node,
}

/// While loop with an optional alternate branch.
export record While: Copy {
    /// Condition evaluated before each iteration.
    condition: *Node,
    /// Loop body executed while `condition` is true.
    body: *Node,
    /// Optional branch executed when the condition is false at entry.
    elseBranch: ?*Node,
}

/// `while let` loop binding metadata.
export record WhileLet: Copy {
    /// Pattern matching structure.
    pattern: PatternMatch,
    /// Loop body executed when the pattern matches.
    body: *Node,
    /// Optional branch executed when the match fails immediately.
    elseBranch: ?*Node,
}

/// Try expression metadata.
export record Try: Copy {
    /// Expression evaluated with implicit error propagation.
    expr: *Node,
    /// Catch clauses. Empty for propagation (`try`), `try!`, or `try?`.
    catches: *[*Node],
    /// Whether the try should panic instead of returning an error.
    shouldPanic: bool,
    /// Whether the try should return an optional instead of propagating error.
    returnsOptional: bool,
}

/// A single catch clause in a `try ... catch` expression.
export record CatchClause: Copy {
    /// Optional identifier binding for the error value (eg. `e`).
    binding: ?*Node,
    /// Optional type annotation after `as` (eg. `IoError`).
    typeNode: ?*Node,
    /// Block body executed when this clause matches.
    body: *Node,
}

/// `for` loop metadata.
export record For: Copy {
    /// Loop variable binding.
    binding: *Node,
    /// Optional index binding for enumeration loops.
    index: ?*Node,
    /// Expression producing the iterable value.
    iterable: *Node,
    /// Body executed for each element.
    body: *Node,
    /// Optional branch executed when the loop body never runs.
    elseBranch: ?*Node,
}

/// Conditional `if` statement metadata.
export record If: Copy {
    /// Condition controlling the branch.
    condition: *Node,
    /// Branch executed when `condition` is true.
    thenBranch: *Node,
    /// Optional branch executed when `condition` is false.
    elseBranch: ?*Node,
}

/// Conditional expression (`<true> if <condition> else <false>`).
export record CondExpr: Copy {
    /// Condition controlling which branch is evaluated.
    condition: *Node,
    /// Expression evaluated when `condition` is true.
    thenExpr: *Node,
    /// Expression evaluated when `condition` is false.
    elseExpr: *Node,
}

/// Classification of pattern matches (if-let, while-let, let-else).
export union PatternKind: Copy {
    /// Case pattern match.
    Case,
    /// Binding pattern match.
    Binding,
}

/// Prong arm.
export union ProngArm: Copy {
    /// Case arm with pattern list.
    Case(*[*Node]),
    /// Binding arm with single identifier or placeholder.
    Binding(*Node),
    /// Else arm.
    Else,
}

/// Common pattern matching structure used by `if let`, `while let`, and `let-else`.
export record PatternMatch: Copy {
    /// Pattern or binding to match against.
    pattern: *Node,
    /// Scrutinee expression to match against.
    scrutinee: *Node,
    /// Optional guard that must evaluate to `true`.
    guard: ?*Node,
    /// Whether this is a case pattern or binding.
    kind: PatternKind,
    /// Whether the binding is mutable.
    mutable: bool,
}

/// `if let` conditional binding metadata.
export record IfLet: Copy {
    /// Pattern matching structure.
    pattern: PatternMatch,
    /// Branch executed when the pattern matches.
    thenBranch: *Node,
    /// Optional branch executed when the match fails.
    elseBranch: ?*Node,
}

/// `let-else` statement metadata.
export record LetElse: Copy {
    /// Pattern matching structure.
    pattern: PatternMatch,
    /// Else branch executed if match fails (must diverge).
    elseBranch: *Node,
}

/// `match` statement metadata.
export record Match: Copy {
    /// Expression whose value controls the match.
    subject: *Node,
    /// Prong nodes evaluated in order.
    prongs: *[*Node],
}

/// `match` prong metadata.
export record MatchProng: Copy {
    /// Prong arm.
    arm: ProngArm,
    /// Optional guard that must evaluate to `true`.
    guard: ?*Node,
    /// Body executed when patterns match and guard passes.
    body: *Node,
}

/// `let` binding.
export record Let: Copy {
    /// Identifier bound by the declaration.
    ident: *Node,
    /// Declared type annotation.
    type: ?*Node,
    /// Initializer expression.
    value: *Node,
    /// Storage alignment.
    alignment: ?*Node,
    /// Whether the variable is mutable.
    mutable: bool,
}

/// Constant declaration.
export record ConstDecl: Copy {
    /// Identifier bound by the declaration.
    ident: *Node,
    /// Declared type annotation.
    type: *Node,
    /// Constant initializer expression.
    value: *Node,
    /// Optional attribute list applied to the constant.
    attrs: ?Attributes,
}

/// Static storage declaration.
export record StaticDecl: Copy {
    /// Identifier bound by the declaration.
    ident: *Node,
    /// Declared storage type.
    type: *Node,
    /// Initialization expression.
    value: *Node,
    /// Optional attribute list applied to the static.
    attrs: ?Attributes,
}

/// Function parameter declaration.
export record FnParam: Copy {
    /// Parameter identifier.
    name: *Node,
    /// Parameter type annotation.
    type: *Node,
}

/// Record literal expression metadata.
export record RecordLit: Copy {
    /// Type name associated with the literal.
    /// If `nil`, it's an anonymous record literal.
    typeName: ?*Node,
    /// Field initializer nodes.
    fields: *[*Node],
    /// When true, remaining fields are discarded (`{ x, .. }`).
    ignoreRest: bool,
}

/// Record declaration.
export record RecordDecl: Copy {
    /// Identifier naming the record.
    name: *Node,
    /// Field declaration nodes.
    fields: *[*Node],
    /// Optional attribute list applied to the record.
    attrs: ?Attributes,
    /// Region parameters in declaration order.
    regions: *[*Node],
    /// Ownership trait derivations attached to the record.
    derives: *[*Node],
    /// Whether this record has labeled fields.
    labeled: bool,
}

/// Union declarations.
export record UnionDecl: Copy {
    /// Identifier naming the union.
    name: *Node,
    /// Variant nodes making up the union.
    variants: *[*Node],
    /// Optional attribute list applied to the union.
    attrs: ?Attributes,
    /// Region parameters in declaration order.
    regions: *[*Node],
    /// Ownership trait derivations attached to the union.
    derives: *[*Node],
}

/// Union variant declaration.
export record UnionDeclVariant: Copy {
    /// Identifier naming the variant.
    name: *Node,
    /// Variant index.
    index: u32,
    /// Explicit discriminant value, if provided.
    value: ?*Node,
    /// Optional payload type.
    type: ?*Node,
}

/// Function declaration.
export record FnDecl: Copy {
    /// Identifier naming the function.
    name: *Node,
    /// Region parameters in declaration order.
    regions: *[*Node],
    /// Function type signature.
    sig: FnSig,
    /// Optional function body (`nil` for extern functions).
    body: ?*Node,
    /// Optional attribute list applied to the function.
    attrs: ?Attributes,
}

/// Method declaration modifiers.
export record MethodModifiers: Copy {
    /// Region parameters in declaration order.
    regions: *[*Node],
    /// Optional attribute list.
    attrs: ?Attributes,
}

/// Array repeat literal metadata.
export record ArrayRepeatLit: Copy {
    /// Expression providing the repeated value.
    item: *Node,
    /// Expression providing the repetition count.
    count: *Node,
}

/// Module declaration.
export record Mod: Copy {
    /// Identifier naming the module.
    name: *Node,
    /// Optional attribute list applied to the module.
    attrs: ?Attributes,
}

/// Use declaration for importing modules.
export record Use: Copy {
    /// Access node identifying the imported module.
    path: *Node,
    /// Whether this is a wildcard import (e.g. `use ast::*`).
    wildcard: bool,
    /// Optional attribute list applied to the use declaration.
    attrs: ?Attributes,
}

/// Access expression used for field, scope, and index lookups.
export record Access: Copy {
    /// Expression providing the container or namespace.
    parent: *Node,
    /// Expression identifying the member, scope element, or index.
    child: *Node,
}

/// `as` cast expression metadata.
export record As: Copy {
    /// Expression being coerced.
    value: *Node,
    /// Target type annotation.
    type: *Node,
}

/// Range expression metadata.
export record Range: Copy {
    /// Optional inclusive start expression.
    start: ?*Node,
    /// Optional exclusive end expression.
    end: ?*Node,
}

/// Binary operation expression, eg. `x * y`.
export record BinOp: Copy {
    /// Operator applied to the operands.
    op: BinaryOp,
    /// Left-hand operand.
    left: *Node,
    /// Right-hand operand.
    right: *Node,
}

/// Unary operation expression, eg. `-x`.
export record UnOp: Copy {
    /// Operator applied to the operand.
    op: UnaryOp,
    /// Operand expression.
    value: *Node,
}

/// Tagged union describing every possible AST node payload.
export union NodeValue: Copy {
    /// Placeholder `_` expression.
    Placeholder,
    /// Nil literal (`nil`).
    Nil,
    /// Undefined literal (`undefined`).
    Undef,
    /// Boolean literal (`true` or `false`).
    Bool(bool),
    /// Character literal like `'x'`.
    Char(u8),
    /// String literal like `"Hello World!"`.
    String(*[u8]),
    /// Identifier expression.
    Ident(*[u8]),
    /// Lexical region name, including its apostrophe prefix.
    Region {
        /// Source name.
        name: *[u8],
        /// Declared parent for a region parameter.
        parent: ?*Node,
    },
    /// Function or nominal constructor applied to explicit region arguments.
    RegionApply {
        /// Function or constructor expression.
        value: *Node,
        /// Region argument nodes in declaration order.
        regions: *[*Node],
    },
    /// Named source place for a lexical region binding.
    RegionBinding(Arg),
    /// Block with explicit storage bindings for a concrete region.
    RegionBlock {
        /// Region name introduced by this block.
        region: *Node,
        /// Binding nodes with address expressions as initializers.
        bindings: *[*Node],
        /// Statements within the region.
        body: *Node,
        /// Whether a `use` block supplies an allocation interface.
        isSession: bool,
    },
    /// Numeric literal such as `42` or `0xFF`.
    Number(fmt::IntLiteral),
    /// Range expression such as `0..10` or `..`.
    Range(Range),
    /// Array literal expression.
    ArrayLit(*[*Node]),
    /// Array repeat literal expression.
    ArrayRepeatLit(ArrayRepeatLit),
    /// Array subscript expression.
    Subscript {
        /// Array or slice.
        container: *Node,
        /// Index expression.
        index: *Node
    },
    /// Binary operator expression.
    BinOp(BinOp),
    /// Unary operator expression.
    UnOp(UnOp),
    /// Builtin function call (e.g. `@sizeOf(T)`).
    BuiltinCall {
        /// Builtin function kind.
        kind: Builtin,
        /// Argument list.
        args: *[*Node],
    },
    /// Block expression or statement body.
    Block(Block),
    /// Call expression, eg. `f(x)`.
    Call(Call),
    /// Field access expression (e.g. `foo.bar`).
    FieldAccess(Access),
    /// Scope access expression (e.g. `foo::bar`).
    ScopeAccess(Access),
    /// Address of expression (e.g. `&mut x`).
    AddressOf(AddressOf),
    /// Dereference expression (e.g. `*ptr`).
    Deref(*Node),
    /// Cast expression using `as`.
    As(As),
    /// While loop statement.
    While(While),
    /// `while let` loop statement.
    WhileLet(WhileLet),
    /// `for` loop statement.
    For(For),
    /// Infinite loop statement.
    Loop {
        /// Body executed each iteration.
        body: *Node,
    },
    /// Break statement.
    Break,
    /// Continue statement.
    Continue,
    /// Return statement.
    Return {
        /// Expression returned by this statement, if any.
        value: ?*Node,
    },
    /// Throw statement.
    Throw {
        /// Expression to throw.
        expr: *Node,
    },
    /// Panic statement.
    Panic {
        /// Optional panic message expression.
        message: ?*Node,
    },
    /// Assert statement.
    Assert {
        /// Condition expression that must be true.
        condition: *Node,
        /// Optional assertion failure message.
        message: ?*Node,
    },
    /// Conditional statement.
    If(If),
    /// Conditional expression.
    CondExpr(CondExpr),
    /// `if let` conditional binding.
    IfLet(IfLet),
    /// `let-else` statement.
    LetElse(LetElse),
    /// Try expression.
    Try(Try),
    /// Match statement.
    Match(Match),
    /// Match prong.
    MatchProng(MatchProng),
    /// Function declaration.
    FnDecl(FnDecl),
    /// Function parameter declaration.
    FnParam(FnParam),
    /// `let binding.
    Let(Let),
    /// Constant declaration.
    ConstDecl(ConstDecl),
    /// Static storage declaration.
    StaticDecl(StaticDecl),
    /// Type signature node.
    TypeSig(TypeSig),
    /// Assignment statement.
    Assign(Assign),
    /// Expression statement.
    ExprStmt(*Node),
    /// Module declaration (`mod`).
    Mod(Mod),
    /// Parent module reference.
    Super,
    /// Module use declaration.
    Use(Use),
    /// Union type declaration.
    UnionDecl(UnionDecl),
    /// Union variant declaration.
    UnionDeclVariant(UnionDeclVariant),
    /// Attribute node.
    Attribute(Attribute),
    /// Record type declaration.
    RecordDecl(RecordDecl),
    /// Record field declaration.
    RecordField {
        /// Identifier bound by the declaration.
        field: ?*Node,
        /// Declared type annotation.
        type: *Node,
        /// Optional initializer expression.
        value: ?*Node,
    },
    /// Record literal expression.
    RecordLit(RecordLit),
    /// Record literal field initializer.
    RecordLitField(Arg),
    /// Alignment specifier.
    Align {
        /// Alignment value.
        value: *Node,
    },
    /// Catch clause within a try expression.
    CatchClause(CatchClause),
    /// Trait declaration.
    TraitDecl {
        /// Trait name identifier.
        name: *Node,
        /// Supertrait name nodes.
        supertraits: *[*Node],
        /// Method signature nodes ([`TraitMethodSig`]).
        methods: *[*Node],
        /// Optional attributes.
        attrs: ?Attributes,
    },
    /// Method signature inside a trait declaration.
    TraitMethodSig {
        /// Method name identifier.
        name: *Node,
        /// Region parameters and attributes.
        modifiers: *MethodModifiers,
        /// Receiver type node (eg. `*mut Allocator`).
        receiver: *Node,
        /// Function signature.
        sig: FnSig,
    },
    /// Instance block.
    InstanceDecl {
        /// Trait name identifier.
        traitName: *Node,
        /// Target type identifier.
        targetType: *Node,
        /// Region parameters in declaration order.
        regions: *[*Node],
        /// Method definition nodes ([`MethodDecl`]).
        methods: *[*Node],
    },
    /// Method definition with a receiver.
    /// Used both inside `instance` blocks and as standalone methods.
    MethodDecl {
        /// Method name identifier.
        name: *Node,
        /// Region parameters and attributes.
        modifiers: *MethodModifiers,
        /// Receiver binding name ([`Ident`] node).
        receiverName: *Node,
        /// Receiver type node (eg. `*mut Arena`).
        receiverType: *Node,
        /// Function signature.
        sig: FnSig,
        /// Method body.
        body: *Node,
    },
}

/// Full AST node with shared metadata and variant-specific payload.
export record Node: Copy {
    /// Unique identifier for this node.
    id: u32,
    /// Source span describing where the node originated.
    span: Span,
    /// Variant-specific payload for the node.
    value: NodeValue,
}

/// Check whether a node is a place expression.
///
/// Place expressions have persistent storage and can appear on the left side
/// of `set` assignments.
export fn isPlaceExpr(node: *Node) -> bool {
    match node.value {
        case NodeValue::Ident(_),
             NodeValue::ScopeAccess(_),
             NodeValue::FieldAccess(_),
             NodeValue::Subscript { .. },
             NodeValue::Deref(_) => return true,
        else => return false,
    }
}

/// Allocate a new AST node from the arena with the given span and value.
export unsafe fn allocNode(arena: &mut NodeArena, span: Span, value: NodeValue) -> *Node {
    let p = try! alloc::alloc(&mut arena.arena, @sizeOf(Node), @alignOf(Node));
    let node = p as *mut Node;
    let nodeId = arena.nextId;
    set arena.nextId = nodeId + 1;

    set *node = Node { id: nodeId, span, value };

    return node;
}

/// Allocate a synthetic AST node with a zero-length span.
export unsafe fn synthNode(arena: &mut NodeArena, value: NodeValue) -> *Node {
    return allocNode(arena, Span { offset: 0, length: 0 }, value);
}

/// Synthetic module with a single function in it.
record SynthFnMod: Copy {
    /// The module block.
    modBody: *Node,
    /// The function block.
    fnBody: *Node
}

/// Synthesize a module with a function in it with the given name and statements.
export unsafe fn synthFnModule(
    arena: &mut NodeArena, name: *[u8], bodyStmts: *[*Node]
) -> SynthFnMod {
    let a = alloc::arenaAllocator(&mut arena.arena);
    let fnName = synthNode(arena, NodeValue::Ident(name));
    let params: *[*Node] = &[];
    let throwList: *[*Node] = &[];
    let fnSig = FnSig { params, returnType: nil, throwList };
    let fnBody: *Node = synthNode(arena, NodeValue::Block(Block { statements: bodyStmts, isUnsafe: false }));
    let fnDecl = synthNode(arena, NodeValue::FnDecl(FnDecl {
        name: fnName, regions: &[], sig: fnSig, body: fnBody, attrs: nil,
    }));
    let mut rootStmts: *mut [*Node] = &mut [];
    rootStmts.append(fnDecl, a);
    let modBody = synthNode(arena, NodeValue::Block(Block { statements: rootStmts, isUnsafe: false }));

    return SynthFnMod { modBody, fnBody };
}

/// Describe the immutable binding introduced by a lexical region header.
export fn borrowBinding(binding: Arg) -> Let {
    let ident = binding.label else panic "borrowBinding: missing name";
    return Let { ident, type: nil, value: binding.value, alignment: nil, mutable: false };
}