std.syntax

The syntax tree as values: what a program can write, as enums and structs a comptime function or a macro reads, builds and writes back. The main types are Expr, Stmt, Decl, Type and Pattern, with Node for any of them and Span for where one stands. parseExpr(s), parseStmts(s), parseDecls(s) read source; toSource() writes a node as the formatter would; children() and walk(f) go over a tree; Ident.fresh(hint) names what a quote binds; error(at, msg) ends a macro's expansion with an error. The enums are @NonExhaustive: a match over them outside std writes a _, and a form the compiler has that this module has not - the rounds of a comptime for over fields and variants among them - is refused where it is read (LYR-CT0005).

A node built here, not read, has a Span of nothing: file "", line and column 0.

Examples

import std.io { println };
import std.syntax { parseExpr };

fn main(): void {
    println(comptime parseExpr("1+2 *  3").toSource());
}

1 + 2 * 3

Types

Span struct — Where a node stands: a file as the diagnostics name it, a line and a column from 1; "" and 0 where the node was built, not read.

Ident struct — A name as written, with where it was written.

Visibility enum — The word in front of a declaration: none, private, internal, pub.

Literal enum — A literal as written: an integer with its suffix (u8, i32, ... or none), a float with its, a string, a byte string, a character, a bool, null.

UnaryOp enum

PostfixOp enum

BinaryOp enum

LambdaForm enum — How a lambda was written: (x) => e, x => e, or as a trailing block f { ... }.

TryKind enum — The mark on a try: try e, try? e, try! e.

Segment enum — A piece of an f-string: text as written, or a hole with its expression and its format spec.

Arg struct — An argument of a call: its value, the name it was written with, if any, and whether it is spread (xs...).

FieldInit struct — A field of an initializer, name = value, or name alone (isShorthand, the value the read of the name); an attribute's one positional argument has the name "".

WithField struct — A field of a with, a.b.c = value.

LambdaParam struct — A parameter of a lambda: its name, its type if written, a pattern instead of a name (((k, v)) => ...), whether it is a place (&n), whether it is a trailing block's it.

Body enum — A lambda's or an arm's body: an expression, or a block.

Arm struct — An arm of a match: its pattern, its guard, its body.

Catch struct — A catch clause: the binding's name, its type (catch (e: T)) or its set (catch (e in [A, B])), the body - written bare after a try expression when isExpr.

Expr enum — An expression, each form a variant.

Stmt enum — A statement, each form a variant.

Block struct — A block: its statements, in order.

FieldPattern struct — A field of a struct pattern, name or name = pattern.

Pattern enum — A pattern, each form a variant.

Type enum — A written type, each form a variant: a name with its arguments (and the names of the arguments that bind an associated type, "" where positional, none when none is named; then the module a quote wrote the name in, or null), ?T, T[] and T[N], a tuple with its labels ("" where none), a function type with its thrown set and which parameters take a place, a throwing type.

Attribute struct — An attribute as written: its path and its fields.

GenericParam struct — A type parameter, T, T :: [I, J], T = Self.

Param struct — A parameter of a function: name: T, &name: T, name: T = default, name: T....

FnDecl struct — A function or a method, free or a member.

FieldDecl struct — A field of a struct or a class.

LetDecl struct — A let or var at module level, or a static let in a type.

AssocType struct — An associated type: type Item;, type Item :: [I];, type Item = int;.

StructDecl struct — A struct.

ClassDecl struct — A class, shaped as a struct is.

Variant struct — A variant of an enum: a unit, a tuple payload, or a struct payload.

EnumDecl struct

InterfaceDecl struct

ExtendDecl struct

AliasDecl struct

ImportDecl struct — An import: import a.b;, import a.b { x, y as z } (names with renames by index, "" where a name keeps its own), import a.b as c;.

Decl enum — A declaration, each kind a variant.

Node enum — Any node, for a walk over a tree: what children() gives and walk(f) visits.

Functions

pub fn parseExpr(s: string): Expr

Parses the expression a text holds, as the compiler parses it. A text that is no expression is an error at the call (LYR-CT0001, with the parser's message).

pub fn parseStmts(s: string): Stmt[]

Parses the statements a text holds, as a block body would.

pub fn parseDecls(s: string): Decl[]

Parses the declarations a text holds, as a module would.

pub fn error(at: Span, msg: string): never

Reports a macro's own error and ends the expansion: the message at at, a node of the site - error(e.span(), "...") - and a note at the site's !.