Syntax Tree

The shape of the tree a macro reads and returns - one type per construct on Syntax, each with the methods it's read through. A macro gets a tree when its input is typed as one of these - an Ast.Expression or Ast.Block for a body, the definition itself for a derive or attribute macro, the whole Ast.Program for a program macro - and #comptime.program() hands the same tree to any macro or #comptime(...) code. See Writing macros for how they're used.

Nodes are grouped by unions - Ast.Statement, Ast.Expression, Ast.Definition, ... - and told apart with match, as in case Ast.If as node then .... Every node also has the methods of Ast.Node: its span(), its children(), toSource(), and from Typecheck on, typeOf(). Comments, whitespace and grouping parentheses aren't in the tree - a macro that needs them takes Tokens instead.

Every node

Ast.Node

#ast-node
Every node

What every node has, whatever its kind: where it is, the nodes directly under it and every one below, itself written back out as source, and - from Typecheck on - its type.

Ast

#ast
Every node

Building trees: parse reads source as a node of the kind asked for, literal turns a value into the expression that writes it, and splitPlaceholders cuts a string macro's text at its #{ } placeholders.

Ast.Piece

#ast-piece
Every node

One piece of a string macro's text, from Ast.splitPlaceholders: plain text, or a placeholder's expression.

SyntaxString Macro

Span

#span
Every node

A stretch of source - where a node, token or macro use is. An error's with value can be one, to point the compile error there.

Groups

Ast.Definition

#ast-definition
Groups

Every kind of definition, and what they all have: a name, attributes, whether it's local or global, and from Analyze on, its type.

SyntaxDefine, Inline Definition

One ofAst.Statement

MembersAst.Function, Ast.Method, Ast.Struct, Ast.Enum, Ast.Union, Ast.Interface, Ast.Const, Ast.TypeAlias, Ast.Macro, Ast.ContextDeclaration

Ast.Statement

#ast-statement
Groups

Everything a block can hold - definitions, implement blocks and plain expressions included - and the attributes written above it.

SyntaxStatement

MembersAst.Let, Ast.Set, Ast.Inject, Ast.Reject, Ast.If, Ast.For, Ast.Match, Ast.Break, Ast.Continue, Ast.Yield, Ast.Return, Ast.Defer, Ast.Error, Ast.Definition, Ast.Implement, Ast.Expression

Ast.Expression

#ast-expression
Groups

Everything that gives a value. A type is an expression too - a parameter's : Type is an Ast.Expression, parsed the same way.

SyntaxValue Expression, Type Expression, Condition Expression

One ofAst.Statement

MembersAst.Word, Ast.Number, Ast.String, Ast.Boolean, Ast.Path, Ast.Symbol, Ast.Context, Ast.MacroInvocation, Ast.MacroWithBody, Ast.StringMacro, Ast.Binary, Ast.Prefix, Ast.Postfix, Ast.Chain, Ast.Call, Ast.Index, Ast.BraceCall, Ast.GenericInstantiation, Ast.Lambda, Ast.InlineIf, Ast.Match, Ast.Root, Ast.Tuple, Ast.List, Ast.Block

Ast.Pattern

#ast-pattern
Groups

What a parameter or let binds its value to: a name, or the pieces of a struct, tuple or list.

SyntaxArgument Destructuring

MembersAst.NamePattern, Ast.StructPattern, Ast.TuplePattern, Ast.ListPattern

Ast.MatchPattern

#ast-matchpattern
Groups

What a match case tests its subject against.

SyntaxMatch Case

MembersAst.WildcardPattern, Ast.NamePattern, Ast.LiteralPattern, Ast.TypePattern, Ast.CasePattern, Ast.ErrorPattern

The program

Ast.Program

#ast-program
The program

The whole program - what a program macro takes and #comptime.program() returns. find<Kind>(where) is how a macro picks what to work on.

Ast.File

#ast-file
The program

One source file: its definitions and its implement blocks.

SyntaxFile

Ast.Attribute

#ast-attribute
The program

One @name(...) above a definition, statement, parameter or match case.

SyntaxAttributes

Definitions

Ast.Visibility

#ast-visibility
Definitions

The local or global in front of a top-level definition, if any.

SyntaxDefine

Ast.Function

#ast-function
Definitions

A function, with its body. withBody gives the same function with another body - what an attribute macro wrapping a function returns.

SyntaxFunction Definition, Function Declaration

One ofAst.Definition

Ast.Method

#ast-method
Definitions

A method - a function with the type it's for.

SyntaxMethod Definition, Method Declaration

One ofAst.Definition

Ast.Struct

#ast-struct
Definitions

A struct: the fields and consts written in it, and the structs it combines with &&.

SyntaxStruct Definition

One ofAst.Definition

Ast.Field

#ast-field
Definitions

One field of a struct or of a struct-shaped enum case.

SyntaxField Definition

Ast.Enum

#ast-enum
Definitions

An enum: the cases written in it, and the enums it combines with ||.

SyntaxEnum Definition

One ofAst.Definition

Ast.EnumCase

#ast-enumcase
Definitions

One case of an enum - empty, carrying values, or carrying fields.

SyntaxEnum Definition

Ast.Union

#ast-union
Definitions

An untagged union and its member types.

SyntaxUnion Definition

One ofAst.Definition

Ast.Interface

#ast-interface
Definitions

An interface and the signatures it declares.

SyntaxInterface Definition

One ofAst.Definition

Ast.Declaration

#ast-declaration
Definitions

A function or method signature with no body - what an interface lists.

SyntaxFunction Declaration, Method Declaration

Ast.Const

#ast-const
Definitions

A named constant - at the top level, inside a block, or inside a struct.

SyntaxConst Definition

One ofAst.Definition

Ast.ContextDeclaration

#ast-contextdeclaration
Definitions

A context name: Type - the type of a context value, and its default if it has one. Only at the top of a file.

SyntaxContext Definition

One ofAst.Definition

Ast.TypeAlias

#ast-typealias
Definitions

A type Name := ... - a new name for a type expression.

SyntaxType Definition

One ofAst.Definition

Ast.Macro

#ast-macro
Definitions

An implement macro - its kind and phase are in its attributes.

SyntaxImplement a Macro

One ofAst.Definition

Ast.Implement

#ast-implement
Definitions

An implement Interface for Target block and the functions and methods in it.

SyntaxImplement an Interface, Implement Statement

One ofAst.Statement

Parameters and patterns

Ast.Parameter

#ast-parameter
Parameters and patterns

One parameter, or one generic parameter between < >.

SyntaxArguments Declaration

Ast.NamePattern

#ast-namepattern
Parameters and patterns

A plain name - binds the whole value.

SyntaxArgument Destructuring, Match Case

One ofAst.Pattern, Ast.MatchPattern

Ast.PatternElement

#ast-patternelement
Parameters and patterns

One element of a struct, tuple or list pattern - x, or x as y.

SyntaxArgument Destructuring

Ast.StructPattern

#ast-structpattern
Parameters and patterns

{x, y as py} - binds fields by name, with at most one ...rest for the remaining fields.

SyntaxArgument Destructuring

One ofAst.Pattern

Ast.TuplePattern

#ast-tuplepattern
Parameters and patterns

(a, b) - binds a tuple's elements by position, with at most one ...rest.

SyntaxArgument Destructuring

One ofAst.Pattern

Ast.ListPattern

#ast-listpattern
Parameters and patterns

[first, ...rest] - binds a list's elements by position, with at most one ...rest.

SyntaxArgument Destructuring

One ofAst.Pattern

Ast.WildcardPattern

#ast-wildcardpattern
Parameters and patterns

_ - matches anything, binds nothing.

SyntaxMatch Case

One ofAst.MatchPattern

Ast.LiteralPattern

#ast-literalpattern
Parameters and patterns

A value to compare the subject with, like case 404.

SyntaxMatch Case

One ofAst.MatchPattern

Ast.TypePattern

#ast-typepattern
Parameters and patterns

case Todo as todo - matches by type, and binds the value as that type.

SyntaxMatch Case

One ofAst.MatchPattern

Ast.CasePattern

#ast-casepattern
Parameters and patterns

An enum case or struct, with patterns for what it carries - case Text(t), case Circle{radius}.

SyntaxMatch Case

One ofAst.MatchPattern

Ast.ErrorPattern

#ast-errorpattern
Parameters and patterns

case Error(e) with detail - matches an errored value.

SyntaxMatch Case

One ofAst.MatchPattern

Statements

Ast.Block

#ast-block
Statements

Statements in { } - a body, a branch, or an expression of its own.

SyntaxBlock

One ofAst.Expression

Ast.Let

#ast-let
Statements

A new local, bound to a name or a pattern.

SyntaxLet

One ofAst.Statement

Ast.Set

#ast-set
Statements

Reassigning something that exists - set x := v, or a compound set x += v.

SyntaxSet

One ofAst.Statement

Ast.Inject

#ast-inject
Statements

Injects a value under a name for the rest of the block.

SyntaxInject

One ofAst.Statement

Ast.Reject

#ast-reject
Statements

Removes this block's own injected value for a name.

SyntaxReject

One ofAst.Statement

Ast.If

#ast-if
Statements

A condition and one or two branches - an else if's else branch is another Ast.If.

SyntaxIf

One ofAst.Statement

Ast.For

#ast-for
Statements

A loop over an iterable, with its modifiers.

SyntaxFor

One ofAst.Statement

Ast.LoopModifier

#ast-loopmodifier
Statements

One of a loop's while, until, if or skipping conditions.

SyntaxFor

Ast.Match

#ast-match
Statements

A subject and the cases it's tried against, in order - a statement, or an expression where a value is wanted.

SyntaxMatch

One ofAst.Statement, Ast.Expression

Ast.MatchCase

#ast-matchcase
Statements

One case: a pattern, an optional guard, and what runs.

SyntaxMatch Case

Ast.Break

#ast-break
Statements

Leaves the loop named by its item.

SyntaxBreak

One ofAst.Statement

Ast.Continue

#ast-continue
Statements

Skips to the next iteration of the loop named by its item.

SyntaxContinue

One ofAst.Statement

Ast.Yield

#ast-yield
Statements

Hands a generator's next value over.

SyntaxYield

One ofAst.Statement

Ast.Return

#ast-return
Statements

Leaves the function with a value.

SyntaxReturn

One ofAst.Statement

Ast.Defer

#ast-defer
Statements

An expression to run when the block ends.

SyntaxDefer

One ofAst.Statement

Ast.Error

#ast-error
Statements

Leaves the function with an error, and optionally a value with it.

SyntaxError

One ofAst.Statement

Expressions

Ast.Word

#ast-word
Expressions

A name - a bare one, or a backtick-quoted one like `adds two numbers`, without its backticks.

SyntaxWord Reference

One ofAst.Expression

Ast.Number

#ast-number
Expressions

A number, as written and as the value it's worth.

SyntaxNumber Literal

One ofAst.Expression

Ast.String

#ast-string
Expressions

A string, as written and as the text it stands for.

SyntaxString Literal

One ofAst.Expression

Ast.Boolean

#ast-boolean
Expressions

true or false.

SyntaxBoolean Literal

One ofAst.Expression

Ast.Path

#ast-path
Expressions

A path in backticks - `/folder/name`, `../folder/name`. A backtick-quoted name that isn't one is an Ast.Word.

SyntaxPath Reference

One ofAst.Expression

Ast.Symbol

#ast-symbol
Expressions

An operator as a value, like (+).

SyntaxSymbol Literal

One ofAst.Expression

Ast.Context

#ast-context
Expressions

An injected value read by name, like &env.

SyntaxContext Reference

One ofAst.Expression

Ast.MacroInvocation

#ast-macroinvocation
Expressions

A macro used with no body, like #line.

SyntaxMacro Invocation

One ofAst.Expression

Ast.MacroWithBody

#ast-macrowithbody
Expressions

A macro with a {{{ }}} body, like #SQL. Before its macro runs; after, the tree holds what it returned.

SyntaxMacro With Body

One ofAst.Expression

Ast.StringMacro

#ast-stringmacro
Expressions

A macro applied to a string, like #format"...". Before its macro runs; after, the tree holds what it returned.

SyntaxString Macro

One ofAst.Expression

Ast.Binary

#ast-binary
Expressions

Two operands and the infix operator between them - member access a.b included.

SyntaxBinary Operation

One ofAst.Expression

Ast.Prefix

#ast-prefix
Expressions

An operator before its operand, like -x.

SyntaxPrefix Operation

One ofAst.Expression

Ast.Postfix

#ast-postfix
Expressions

An operator after its operand, like x!.

SyntaxPostfix Operation

One ofAst.Expression

Ast.Chain

#ast-chain
Expressions

Chained comparisons like a < b < c, kept as one node.

SyntaxOperator Chain

One ofAst.Expression

Ast.Call

#ast-call
Expressions

A call, with its type arguments and guard if written.

SyntaxCall

One ofAst.Expression

Ast.Index

#ast-index
Expressions

An index, in brackets or as a subscript.

SyntaxIndex Access

One ofAst.Expression

Ast.Guard

#ast-guard
Expressions

The ?, ! or !? between a callee and its ( or [.

SyntaxCall, Index Access

Ast.BraceCall

#ast-bracecall
Expressions

Constructing a struct, like Point{1, 2}.

SyntaxBrace Call

One ofAst.Expression

Ast.GenericInstantiation

#ast-genericinstantiation
Expressions

Type arguments with no call after them, like Array<Int>.

SyntaxGeneric Instantiation

One ofAst.Expression

Ast.Argument

#ast-argument
Expressions

One argument at a call site - by position, or by name.

SyntaxCall Arguments

Ast.Lambda

#ast-lambda
Expressions

An inline function.

SyntaxLambda

One ofAst.Expression

Ast.InlineIf

#ast-inlineif
Expressions

if condition then a else b written where a value is wanted.

SyntaxInline If

One ofAst.Expression

Ast.Root

#ast-root
Expressions

A root, of degree 2 unless a subscript says otherwise.

SyntaxRoot

One ofAst.Expression

Ast.Tuple

#ast-tuple
Expressions

A tuple literal.

SyntaxTuple Literal

One ofAst.Expression

Ast.List

#ast-list
Expressions

A list literal.

SyntaxList Literal

One ofAst.Expression

Ast.Elision

#ast-elision
Expressions

A bare ... standing for the elements left out of a list.

SyntaxList Literal