Language Reference

This chapter specifies x2c’s syntax, behavior, and current limitations.

The runtime API is described in the standard library overview, and advice about which construct to use is in idioms. Flags and the dump options that expose each phase are in compiler options. If you have not built the compiler yet, the website’s install page is the quickest route, and building the compiler covers the self-host stages behind it.

Source files and pragmas

An .x file combines declarations and definitions. Translation produces a header and a C source file.

A source file whose first line begins with #! is a script unit; every other file is an ordinary unit.

#pragma private marks the start of implementation-only content. Declarations before it may be emitted to the generated header. A function definition also begins source-private output, except that a typedef after it still belongs to the header when a later public prototype names it. Every translated header starts with #pragma once and also carries a conventional include guard, so .x programs do not need to write either one.

A file that includes another sees what that file’s header declares: everything above its #pragma private and the functions with external linkage it defines below it. Its private types, enumerators, objects, and static functions belong to that file, and naming one of them is an error in the including unit. A static function is private wherever it appears, above the boundary as well as below it, and the error names the file that defines it. A C header is not a unit, so the static inline functions it defines still belong to every file that includes it. An #include below #pragma private still splices, because the including file may call the functions it declares.

The advanced --cpp-symbols and --live-symbols modes run the host preprocessor over raw .x include graphs. A module used with those modes needs a source-level #pragma once only when its own .x includes form a cycle. Ordinary translation resolves includes itself and terminates cycles without it.

Every ordinary .x translation unit implicitly loads the x2c.x standard runtime prelude. The compiler also emits #include "x2c.h" in its generated header. An explicit #include "x2c.x" is also accepted; it does not change the semantic environment or generated runtime dependency.

Optional modules shipped with x2c are outside that prelude. They require an explicit source include, such as #include "typed-array.x". Third-party code uses the package import described below.

Script units

A script unit is a source file whose first line begins with #!, usually #!/usr/bin/env -S x2c script so that x2c script runs it. The compiler reads that first line as #include "scripting.x", which brings in args.x, diff.x, digest.x, path.x, process.x, and regex.x. Every other line keeps its line number.

A script unit takes one of two forms, chosen by whether it defines a function named main at file scope:

• With main, it is an ordinary program. Its declarations, including initialized ones such as int count = 0;, stay at file scope and main runs. Adding a shebang line turns a program into a script.
• Without main, its top-level statements run in order as the program.

A script unit that defines main and also has a top-level statement, such as an expression, control flow, a with block, or a statement macro, is an error.

In the second form these top-level forms stay at file scope:

• preprocessor lines, import, and protocol declarations and adoptions;
• macro and keyword definitions, top-level $(...) Lisp, and invocations of macros and keyword aliases whose result is file-scope syntax, including decorators of functions and types;
• typedef, static, and extern declarations and static assertions;
• type definitions such as struct Point { int x; }; and classes;
• function definitions, including expression-bodied ones, and prototypes, meaning declarations that end with a parameter list.

Every other top-level form is a statement, including declarations with an initializer or none, such as int total = 0; or Point p;. The statements, in source order, become the body of a function that the generated main calls with argc, argv, and args, a List of the argument Strings after argv[0]. Statements can call the script’s functions wherever they are defined, and those functions can call one another. The declarations among the statements are locals of that body, so functions cannot refer to them. Lambdas capture them as usual. Write static for a variable that functions share.

Falling off the end of the statements returns zero, and return among them sets the exit status. A <cmd-fail> that no statement catches prints the command and its status on standard error, and that status becomes the exit status. Any other uncaught Error prints its cause and details on standard error and exits with status 1. The --cpp-symbols and --live-symbols modes run the host preprocessor over the file as written, where the #! line is not C, so they report an error for a script unit.

#!/usr/bin/env -S x2c script
static String greeting(String name) => %"hello, $name";

String name = args ? args.car().string() : "world";
printf("%s\n", greeting(name));
if (!args) return 1;

Packages and import

A package is a directory whose name is a valid C identifier. Its entry unit is <dir>/src/<name>.x, or <dir>/<name>.x for a single-file package. The package is everything that entry unit includes. Everything above #pragma private is public. There is no manifest and no export list. --package-dir <root> registers a directory of packages; a target in x2c.toml may set package-dirs instead.

An import declaration names a package, binds a local alias, and may name individual members:

import "<package>" [as <alias>] [with <Name> [as <Local>] {, ...}] ;

import "geo";                 // alias: geo
import "geo" as g;            // alias: g
import "geo" with Vec, span;  // plus bare Vec and span
import "geo" with Vec as V;   // plus bare V
import "geo" as g with Vec;   // both spellings

The alias changes how names are written in x2c. g.Vec, g.Vec.new(2.0, 3.0), and g.span(p) all compile to the package’s C names, which carry the package prefix: geo__Vec, geo__Vec_new, geo__span. Two packages may therefore publish the same type or function name in one program. An existing local or file-scope binding takes precedence over an alias of the same name.

An import ... with name renames what you type, never the C symbol. Vec v = Vec.new(2.0, 3.0) emits geo__Vec and geo__Vec_new. Any public name the package exports may be listed, including free functions. The alias is registered either way, and the clause only adds shortcuts. A name the package does not export is an error at that name, and a local spelling that another binding or a declaration already owns is reported as package name 'V' is already bound or package name 'V' collides with a declared name. A declaration shadows a with name as it shadows an alias.

Names derived from a package type carry the prefix as well. A Var(T) participant’s tag is <geo__vec>, and its converters are geo__Vec_var and geo__Var_vec. A package’s own sources write all of these bare and let the compiler add the prefix. Only a Symbol literal, a global interned identity, is written out in full.

A package may publish a method on a type it does not define, such as Var.json, or on a type its own vendored header defines. At each receiver type, method lookup tries an ordinary method first, then a method from the imported packages, then a protocol method before continuing through typedef parents. The receiverless form Type.member(...) and protocol punctuation resolve through the same imported names, so a package that adopts one of its own protocols for a foreign type gives the consumer that operator. One imported match is callable. More than one is an error at the call, with the packages listed by name; imports that are never called do not conflict. An alias-qualified function call such as json.Var_json(value) selects one package explicitly.

A package’s own sources are <dir>/src/** and the single-file <dir>/<name>.x. Other files in the package directory, including its tests and examples, are ordinary consumers that reach it through import.

An import exposes:

• every public declaration, type, and aggregate above #pragma private;
• protocol declarations and adoptions the package makes; and
• any header or runtime module the package’s public part includes, such as a vendored foreign header it publishes.

It does not expose macros, .xmacro definitions, private declarations, or the package’s own imports. Packages have no re-exports or hierarchy. One program uses one version of a package.

Names from a C header remain unprefixed, as if the consumer included that header directly. A package renames what it declares, not what it includes.

An unprefixed public declaration from an x2c file outside the package directory would enter the consumer’s namespace unchanged. The compiler rejects it as package 'geo' exposes unprefixed top-level declaration '...'. Including that file below #pragma private keeps it out of the package’s surface, and a runtime module, like a C header, crosses unprefixed. A consumer that declares a name in an imported package’s geo__ space is reported as 'geo__x' is reserved for imported package 'geo'.

C foundation

x2c keeps C declarations, expressions, operators, functions, structs, unions, enums, pointers, arrays, and control flow. It adds language forms around that foundation and keeps C’s object model.

Member access uses . wherever x2c parsed the struct, whether the receiver is a value or a pointer, and whether the declaration came from x2c source or from a C header x2c reads. -> remains accepted and is required where the compiler cannot select the operator: a pointer to a struct whose layout x2c never sees, such as one declared in a system header or in a third-party header reached through an include x2c does not resolve; and a #define body, which is preprocessor text. A member of an anonymous union or struct belongs to its enclosing aggregate, and . reaches it through a pointer like any other member. . reaches through one pointer level, so a pointer to a pointer typedef keeps (*pointer).field. x2c also recognizes method-style calls such as list.len(). The namespaced function is selected from the static receiver type. When that function declares its first parameter T * and the receiver is an addressable T, the receiver’s address is passed, so rec.bump(4) reaches void Rec.bump(Rec *rec, int by) without an explicit &. A receiver that is a pointer to the declared parameter is one level too far and is a type error; write (*pointer).method(). Normal pointer conversion rules still apply, including preservation of const and other qualifiers. A qualifier on the receiver itself does not change which methods and operators the type has, so a const String answers len() and + the way an unqualified one does. Method syntax does not make every value dynamically dispatchable; only registered callbacks define custom behavior.

A method may use Self in its result and parameter types when it promises to preserve the receiver’s static typedef:

Self List.cdr(Self values);
Self List.append(Self left, Self right);
List List.map(List values, Func fn);

For a ListInt receiver, dotted lookup treats the first two signatures as ListInt -> ListInt and requires a ListInt second argument to append. Ordinary conversion still applies, so a plain List reaches the existing validating ListInt converter. map remains List -> List; x2c never infers covariance for an unmarked method.

Self is contextual syntax, valid only in a dotted method declaration or definition with a concrete owner and a compatible first parameter. It may be qualified or nested under pointers. Every occurrence is bound to the original static receiver typedef, even when lookup crosses several typedefs. A direct call to List_cdr retains the concrete List -> List signature, and generated C keeps that ABI. Prototypes and definitions must agree on both their concrete types and the positions marked Self.

Expression-bodied functions

A function that returns one expression may use =>:

typedef struct Pair { int left, right; } Pair;
static int twice(int value) => value * 2;

String Pair.describe(Pair pair) =>
  %"${pair.left}, ${pair.right}";

This is shorthand for a compound body containing one return statement. The expression uses the function’s parameter and body scopes and follows the same conversion, cleanup, and lifetime rules as return expression;. The semicolon terminates the body; nested compound literals, collection literals, and lambda bodies do not terminate it.

A void function has no value to return, so its expression body is the shorthand for a compound body containing one expression statement:

typedef struct Counter { int value; } Counter;
static void Counter.step(Counter *self) => self.value++;

An expression is required; =>; is invalid. The rules for writing return in a void function are unchanged. Use a compound body when a function needs declarations, several statements, or a comment inside the body.

Reference parameters

A function parameter declared T &name aliases an addressable T supplied by the caller. The parameter name is an ordinary T lvalue inside the function, so reading it reads the caller’s object and assigning it changes that object:

static void swap(int &left, int &right) {
  int temporary = left;
  left = right;
  right = temporary;
}

int main(void) {
  int first = 4, second = 9;
  swap(first, second);
  printf("%d %d\n", first, second);
  return 0;
}

The call does not write &; x2c takes each argument’s address. Passing a reference parameter to another reference parameter forwards the same object. The argument must be an addressable lvalue whose storage remains live for the call.

Generated C uses a pointer parameter and explicit address-taking and dereferencing. Reference parameters add no runtime representation or ownership behavior. The transparent & form is supported only on parameters; reference locals, globals, and return types are not language features.

Delegate fields

delegate marks a named struct or union field as a fallback for dotted method calls:

typedef struct Reader {
  int value;
} Reader;

typedef struct Document {
  delegate Reader reader;
} *Document;

int Reader.read(Reader reader);

If normal lookup finds no applicable Document.read, document.read() uses the field’s static type and emits the same direct call as document.reader.read(): Reader_read(document->reader). The original receiver expression occurs once. Pointer and value fields follow the ordinary rules for . or ->, addressability, qualifiers, conversions, and null values. Delegation emits the field access and direct call; it adds no wrapper, temporary, runtime check, symbol, or dispatch table.

Normal method lookup remains first, including direct methods, imported methods, protocol-selected methods, and typedef ancestors in their existing order. Delegate fields are searched only if those lookups fail. The search visits marked fields in source order to produce consistent diagnostics. One resolving path is used; two or more are an ambiguity error, regardless of field order. An explicit outer method therefore resolves an otherwise ambiguous pair.

Delegate fields may chain without a numeric depth limit. Lookup tracks the aggregate types on the current field path. A cycle is reported only when lookup needs that path and finds no valid candidate. One valid path is used even if another contains a cycle; multiple valid paths remain ambiguous.

The terminal field type determines method typing. Self parameters and results mean that field’s static type, never the outer aggregate, and a method returning Reader still returns Reader. Delegation does not make the outer type a subtype, adopt a protocol, acquire a conversion or Var identity, expose the field’s fields, or forward punctuation, indexing, operators, or receiverless calls. x2c.method.resolve is also direct-only. Its callee result cannot represent a projected receiver path.

threaded is x2c’s spelling of C’s thread-local storage class, and gives each thread its own copy of an object:

threaded int depth;
static threaded Scope current;

It pairs with static or extern, in either order, which is the only pairing C allows. _Thread_local and thread_local mean the same thing and are accepted, so C that already writes it either way passes through unchanged; all three emit _Thread_local.

Where C reports a pointer type mismatch as a warning, x2c reports an error: passing a struct Rec * to a parameter declared List, String, Map, or Array is cannot convert (* "Rec") to ("List"). Typedef spelling is not a mismatch, so Ast and List are the same type here. The rule applies only when both sides point at a named struct, union, or enum or at a builtin scalar; void *, function pointers, arrays, and types from system headers convert as C defines. A cast still allows the conversion.

Protocols

Protocols declare a compile-time relationship between a concrete base and explicit participant types. The grammar is:

protocol-declaration := protocol type-name ( identifier ) {
                          associated-declaration*
                          protocol-member*
                        }
protocol-adoption    := [ static ] protocol type-name ( identifier )
                        [ as type-name | tag symbol-literal ] ;
associated-declaration
                     := associated identifier = type-name ;
protocol-member      := type-name identifier . identifier
                        ( parameter-list ) [ = c-identifier ] ;

The identifier in a declaration body is a fresh type-variable binder. The identifier in a bodyless adoption must name an existing type:

protocol Var(T) {
  associated Key = Var;
  Value T.getindex(T, Key);
}

protocol Var(Array);

The optional as form applies only to Var and says that the participant uses an existing fixed runtime tag:

typedef List Row;
Var Row.var(Row);
Row Var.row(Var);
protocol Var(Row) as List;

Row retains its own typed conversions, methods, signatures, and protocol participation. Compatible List methods inherited through its typedef chain may satisfy Var(Row) without Row forwarding methods. A boxed Row carries <list> and uses List for dynamic dispatch. Runtime tests therefore cannot distinguish it from another list: value is Row and value is List test the same tag. The type after as must be a scalar, pointer, or fixed runtime class that already has a compiler-known Var tag.

The optional tag form also applies only to Var, but keeps a distinct descriptor under the supplied custom tag:

protocol Var(ArrayString) tag <arraystr>;

The tag must be a Symbol literal, cannot be built in, and must be unique across the process. The compiler retains the full lowercase participant name so two types cannot silently claim the same restricted Symbol. tag and as are mutually exclusive: use tag for a distinct runtime class and as for a typed view of an existing representation.

Both forms are top-level compiler declarations and emit no program object. Associated declarations precede members. A declaration binder that shadows a visible type receives a warning; use the bodyless form to adopt that type.

static applies only to a concrete adoption:

static protocol Prepared(LocalPlan);

That adoption applies only within the translation unit that declares it. It forces local generation even when the complete adoption is public. It is also valid when a private dependency already implies locality; it then records the same local relationship explicitly and does not change linkage.

An adoption is local when its protocol body, participant typedef, required converter, required native target, or adoption row is private. A protocol body below lexical #pragma private is legal; static protocol BASE(T) { ... } is not, because static applies only to concrete adoption. Local ordinary adapters are static inline, appear only in generated C, and are omitted from generated headers. Local native aliases and their signature checks are likewise source-only.

Descriptor-producing adoptions such as Var(T) may be local. Their converters and generated thunks remain internal, but descriptor registration is process-wide so boxed dispatch still works. The author must keep the derived lowercase or explicit tag unique across the process. Two independent private registrations of the same tag in different translation units are unsupported by convention. A Var(T) as R adoption emits no descriptor for T; boxed dispatch uses R’s existing descriptor.

One generated C method cannot have incompatible local and external linkage. The compiler reports that conflict at its source location. A protocol whose dependencies are all public retains its public behavior.

Participation must be declared; conversion names and matching typedefs do not imply it. The compiler then determines the adoption’s visibility. An adoption resolves in the unit that contains it, so the protocol, participant, required converters, native targets, and constraining participant members must be visible there. Ordinary runtime protocol bodies under lib/ belong in lib/protocols.x; native declarations and their adoptions sit beside the participant typedef.

A typedef descendant with no exact adoption may use the nearest visible ancestor’s resolved conformance. It reuses the ancestor’s methods, associated types, conversions, and representation without creating an adoption, adapter, native alias, descriptor, runtime tag, registration, or conformance output for the descendant. An exact descendant adoption resolves a new conformance and takes precedence. If that exact adoption is invalid, it is diagnosed and lookup does not fall back to an older ancestor. A local ancestor adoption is inherited only in translation units where that adoption is visible.

Common source forms are a plain adoption for public protocols and public participants, a plain protocol Var(PrivateType); for an internal type that crosses Var, and an explicit static protocol PrivateBase(PrivateType); for a fully private relationship. The latter would also be inferred local; static states it directly.

Each member resolves independently as implemented, native, an ordinary base default, missing, or a signature conflict. Dot syntax and punctuation accept implemented and native members plus ordinary base defaults reached through a total participant-to-base view. A missing Var member grants no static participant method; its descriptor slot carries another protocol’s generated owner when one exists, and is otherwise empty so dynamic boxed use takes the Var fallback directly. Signature conflicts are located errors at the adoption row.

An explicit adoption may resolve an ordinary implementation through the participant’s typedef chain. For example, typedef List Domain; protocol Iter(Domain); selects List.iter directly; it does not require a forwarding Domain.iter method. The participant’s own method wins, followed by the nearest inherited method, and then a protocol default. Reaching the protocol base uses that default path instead. Every parameter whose exact type is the method owner is viewed as the participant type. Concrete result types remain unchanged unless the method declares them as Self.

An ordinary Var(P) adoption does not search P’s typedef chain. When protocol Var(P) as R names an R that occurs in that chain, compatible methods owned by that exact representation may satisfy the adoption. No other ancestor is considered. Boxed dispatch already uses R’s descriptor.

Associated types unify from the participant’s declared member signatures and use their declared default only when unconstrained. A generated member has one owner. Incompatible generated signatures or two defaults conflict. A compatible participant implementation resolves the competition.

The normative protocols chapter specifies converter totality, adapter-derived conversion directions, punctuation, generated ownership, boxed dispatch, native aliases, and complete examples.

C initializers and static assertions

Array and aggregate initializers accept chained index and field designators. Positional values continue from the designated subobject using C’s ordinary brace-elision rules:

String labels[4] = {[1] = "first", "second"};
int grid[2][3] = {[0][1] = 7, 8, 9};
typedef struct Record { String names[2]; Var last; } Record;
Record record = {.names[1] = "second", "last"};

Each supplied value converts to its destination element or field type. After .names[1] = "second" above, the next value initializes last, including its ordinary conversion to Var. With .names = "first", "second", "last", brace elision fills both array elements before continuing to last. Explicit braces delimit a nested initializer. Typedefs and compound literals retain the ordinary destination conversions, including C literals to String. The native compiler owns index constant expressions, array dimensions, and bounds diagnostics.

_Static_assert(condition, "message"); is accepted at file scope, block scope, and within a struct or union. It emits an ordinary C static assertion and adds no field, binding, or runtime operation:

_Static_assert(sizeof(int) >= 2, "int is at least 16 bits");

The native compiler evaluates the condition and rejects a false or nonconstant assertion. Translation and source analysis alone do not perform that check.

Generic selection

_Generic(controlling, type: value, ..., default: value) is a C11 generic selection. x2c resolves the controlling expression and each value, then emits the selection unchanged. The native compiler chooses the association and reports constraint errors. The selection has no x2c type, so it works where C accepts the selected value directly:

int size = _Generic(sizeof(int), size_t: 1, default: 2);

A selection does not convert to Var or take part in method calls. A cast gives it a type: Var kind = (int)_Generic(text, char *: 1, default: 2);.

An association type is a type name of specifiers, qualifiers, and pointers. Name a function-pointer or array type through a typedef.

Mixed declaration rows

A semicolon-terminated declaration at file scope, block scope, or inside a struct or union may restart its declaration specifiers after a comma:

int i, float x, char c;
int first, second, const char *name, *alias;

Each fresh type starts a declaration with the same scope and source order as if it were on a separate row. Declarators that share a type keep the C spelling: first and second are int, while name and alias are const char * in the second example.

Valid C declarators retain their meaning. In particular, if T is a typedef, int i, T; still declares an int named T and hides the typedef. A spelling such as int i, T value; restarts at T, because the second identifier cannot continue the int declarator. Function parameter lists already give each parameter its own type; mixed rows do not extend for initializers, foreach binders, or macro Decl arguments.

Flat List destructuring

Declarations and assignment expressions may destructure the first elements of a List into flat identifier targets:

List values = %(1 2 3);
List numeric_values = %(0 10 2);

Var (a, b, c) = values;
int (start, stop, step) = numeric_values;
(int index, float weight, char code) = %(1 2.5 ${'x'});

Var first, second;
(first, second) = values;
(first) = values;
List copy = (first, second) = values;

The leading declaration specifier in int (start, stop, step) applies to every name. The parenthesized typed form gives each target a type, written as it would be in a parameter declaration. Both forms declare their names in the enclosing block. Storage classes and per-target initializers are not accepted inside the parentheses. Inside a %() List literal, use ${} to insert a C character expression because bare single-quote syntax belongs to the List reader.

The singleton assignment destructures. It assigns element zero; the left side is not a parenthesized scalar assignment.

The source expression is evaluated once. Elements are then assigned from left to right through the same conversions used by ordinary initialization or assignment. Extra source elements are ignored. If the List is short, List.getindex supplies void; a Var target receives it, while a typed target follows its existing Var conversion and failure behavior.

Assignment destructuring has the same static type, value, and identity as its right side, so it may appear in an initializer, argument, conditional arm, comma expression, return, or another destructuring right side. The right side is still evaluated only once; returning it does not copy the List.

The form is flat. Targets must be simple identifiers. Nested targets, members, indexed targets, dereferenced pointer targets, and rest captures are not supported.

Compile-time macros

Macros are explicitly invoked, hygienic compile-time code generators. They differ from C preprocessor macros. Holes bind parsed syntax, definitions use C-like x2c source, and every result is validated for its typed source position before C generation. They make no promise about the runtime semantics of the code they emit; for example, substituting an argument twice may evaluate it twice. A definition’s left side looks like its invocation, and its body is x2c with $hole markers:

macro Expression $twice($value) => ($value + $value)

int main(void) {
  printf("%d\n", $twice(21));
  return 0;
}

Global definitions are top-level items. A compound statement may instead contain a local definition whose name has no $. Both forms emit no runtime declaration. macro is a contextual introducer only when the surrounding grammar accepts a definition and a result kind and macro name follow it. It remains legal as an ordinary typedef, variable, parameter, field, or function name everywhere else. A definition ends with its parenthesized or braced body and has no trailing semicolon.

Ordinary global invocation is $qualified.name(arguments). A local macro is invoked as name(arguments). A source file may also give a visible global macro an identifier spelling through a keyword declaration, described under Decorators. Macro names are separate from C identifiers and global names may be qualified, as in $project.logging.trace. The x2c.* and lisp.* macro and Lisp namespaces are reserved for compiler-shipped facilities; $lisp.bind, $lisp.binding, and $lisp.install are the shipped native-binding macros.

Definitions and imports become visible in source order. A definition must precede its first use. A later same-file definition of the same name shadows the earlier definition for later invocations; it does not change expansions that already occurred. An imported definition may not collide with a definition already visible from the importing translation unit or another import.

Local definitions

A local definition uses one bare identifier and is a compound-statement item:

static int scaled_sum(int scale, int value) {
  macro Expression scaled(Expr $input) => ($input * scale)

  return scaled(value);
}

Its name becomes visible at the definition and remains visible to the end of that block and in nested blocks. An inner definition of the same name shadows it until the inner block ends. A later definition in the same block replaces it for following source. Fixed C and x2c keywords are not identifiers and cannot be local macro names; with is also reserved because it introduces the lexical with statement.

A bare name(...) selects the innermost local macro before a file-local keyword alias or an ordinary call or typedef-style cast. A bare name without parentheses remains an ordinary identifier. (name)(arguments) is an explicit ordinary call, while $name(arguments) selects only the global or imported macro namespace. A local and global definition may therefore share a name without ambiguity.

Literal references to function parameters and preceding local declarations retain their definition-site binding identities. A later same-spelled inner declaration is emitted under a private shadow name when necessary, so the template still reaches the captured declaration. Hole arguments retain their call-site identities. Declarations written in the body and names declared by using retain the ordinary hygiene rules described below.

Local Expression, Statement or Block, Field, Entry, and Enumerator results use their usual positions. A local decorator may target any syntax whose invocation position is reachable before the defining block ends. A local Unit result and a local decorator targeting Function or Unit syntax are rejected. Their invocation positions are outside that lifetime. A macro-generated local definition is published at block position with the same visibility, capture, and shadowing behavior as a direct one.

Compile-time Lisp remains one translation-unit session. A local definition may read or change that session, but Lisp definitions, imports, globals, and other effects do not disappear when the local macro name leaves scope.

Holes and sequences

A hole binds parsed syntax, not source tokens. Its kind is normally inferred from every position where it appears in the body: an operand needs an expression, a cast needs a type, and a declarator needs a name. If those uses do not imply exactly one kind, including when a hole appears only inside compile-time Lisp, the definition must annotate it in the invocation pattern.

These are the complete hole-kind annotations:

Because the definition is already known, an invocation parses each argument according to its hole kind. A type such as FILE * therefore works as an argument even though it is not an expression.

An Expr argument stays one operand. With the argument value > 0, the body !$condition means !(value > 0). The same holds for a macro’s own result: macro Expression $twice($value) => ($value + $value) makes $twice(21) * 2 mean (21 + 21) * 2. Generated C carries these parentheses only where C precedence would otherwise regroup the expression.

A Decl argument captures one declaration without a trailing semicolon. Its comma or closing parenthesis belongs to the macro invocation. The declaration may have an initializer or use flat destructuring with two or more simple identifier targets, but it may not contain multiple comma-separated declarators.

An expression hole may be the receiver of ordinary postfix syntax in the body, including $value.field, $value.method(), and $value[index]. The hole ends at its registered identifier; this does not shorten qualified macro names such as $project.logging.trace(). A singular Name hole may also appear after . or ->, as in $value.$member or $pointer->$member. It supplies the captured member spelling, not a hygienic generated name.

A registered Type hole may likewise supply the type name before . in a method declaration in a Unit template, as in inline Var $type.$method($type value). A literal registered type may use the same member form, as in Logger.$method. Both expansions use the Type_method declaration identity.

Repeated Unit-macro applications over Type holes are how x2c writes compile-time generic code. Every supplied type must already be a valid named C type, and every expansion produces separately typed declarations and definitions. There is no runtime type argument, erased element representation, or parameterized type spelling such as Box<T>. A macro generates named concrete families such as IntValue and DoubleValue.

During shallow symbol collection, the compiler expands file-scope unit macros that contain protocol declarations or adoptions. If expansion succeeds, it retains those and public declarations, then discards private declarations and function bodies. A public function definition may therefore follow its prototype inside the same expansion; importing translation units discover the retained signature.

Protocol declarations and adoption rows are collection-time compiler declarations rather than C declarations. A unit macro may emit them, and importing units receive the retained rows. Converters and public methods named by an adoption may have prototypes earlier in the same expansion and scope. The compiler uses them to resolve the adoption and make the functions visible to later code. Private declarations remain literal. Collection discards them with the generated bodies.

$name... is a sequence hole. It captures zero or more arguments of one element kind, must be the final argument, and $name... in the body is the splice point:

static int sum(int a, int b) {
  return a + b;
}

macro Expression $call(Expr $callee, Expr $arguments...) => (
  $callee($arguments...)
)

static int answer(void) {
  return $call(sum, 19, 23);
}

The element kind is inferred in the same way as a singular hole and may be overridden, for example Field $members.... Argument-hole names must be unique, and a name cannot be both singular and sequence-valued. Entry holes capture one key: value row; Entry $rows... captures and forwards zero or more complete rows.

Result kinds and invocation positions

A macro has one result kind as well as argument kinds:

The result kind is required between macro and the $ name. Statement is the canonical spelling for block-item results; Block remains a synonym in result and hole positions. Parenthesized bodies require Expression; braced bodies require Statement, Block, Field, Entry, Enumerator, Unit, or Declaration. Inside a compound statement, a Statement or Block macro may produce zero or more block items. Where the grammar requires one statement, such as an if, else, or loop body, the expansion must contain exactly one statement. An explicit { ... } or do { ... } while (0) in the production satisfies that requirement; the compiler does not add braces. The invocation must occur in the matching position:

#include "meta.x"
meta static List swap_type(List value) => x2c_syntax_type(value);

macro Statement $swap(Expr $left, Expr $right) using $temporary => {
  $swap_type($left) $temporary = $left;
  $left = $right;
  $right = $temporary;
}

macro Field $timestamps() => {
  long created_at;
  long updated_at;
}

static void reorder(void) {
  int first = 1, second = 2;
  $swap(first, second);
}

typedef struct Record {
  $timestamps();
} Record;

An Enumerator body contains zero or more enum members. Members may have explicit initializers, and commas separate literal members and sequence splices:

#include "meta.x"
meta static List public_name(String name) => x2c_ident(name);

macro Enumerator $status_values() => {
  private_start = 3,
  $public_name("STATUS_READY") = private_start + 1,
  $public_name("STATUS_DONE")
}

typedef enum Status {
  STATUS_UNKNOWN,
  $status_values(),
  STATUS_COUNT
} Status;

Literal names such as private_start are hygienic and may be referenced by later generated initializers in the same expansion. x2c_ident publishes the requested name through the generated-name slot. Generated members participate in enum ordering and automatic value assignment, and successful exact members are available to following source. Duplicate generated names and collisions with source members are rejected. A malformed or failed sequence publishes none of its provisional members.

An Entry body contains zero or more comma-separated Map rows:

macro Entry $handler(Literal $key, Expr $value) => {
  $key: $value
}

int main(void) {
  int open = 1, close = 2;
  Map handlers = {$handler("open", open), $handler("close", close)};
  return handlers.len() == 2 ? 0 : 1;
}

An entry invocation occupies one comma-delimited row position but may expand to any number of rows. In a bare {...} literal a direct or keyword-alias invocation is written as a row. In the quoted %{...} literal it must sit inside ${...}, which leaves the quoted Map syntax to parse x2c. Elsewhere in an entry macro body, ordinary expression grammar applies, so an expression macro may generate a key. $(form)... inserts a List of explicit (map-entry KEY VALUE) nodes; without ..., $(form): value constructs a generated key.

The semicolon belongs to the invocation context, not the definition. Enumerator and entry invocations occupy comma-delimited positions and have no semicolon. A result used in the wrong position is rejected at the invocation.

Decorators

A decorator is a macro whose required first parameter is supplied implicitly from the expression or source item following its application:

#include "meta.x"
meta static String trace_name(List fn) => x2c_function_name(fn);
meta static List trace_body(List fn) => x2c_function_body(fn);

macro Decorator $trace(
  Function $function,
  Expr $channel
) => {
  printf(
    "[%s] %s\n",
    $channel,
    $trace_name($function)
  );
  $trace_body($function)...
}

$trace("request")
static int answer(void) => 42;

The call supplies "request" to $channel; the compiler supplies the following function to $function. The first parameter must be named, singular, explicitly annotated, and one of:

Parameters after the target are explicit invocation arguments. using follows the complete parameter list, just as it does for other macros. A decorator application has no semicolon; that omission pairs it with the following target. Only whitespace and comments may separate them. When a statement decorator appears where one statement is required, its production must likewise yield exactly one statement. A compound statement may contain the captured target plus any additional block items without requiring braces at the invocation.

A Statement or Block decorator standing before a file-scope function definition decorates that function’s body. The body is parsed as usual, the decorator’s production replaces it, and the same function is rebuilt around the result, so parameters resolve inside the produced items and a return from within the body runs the decorator’s deferred cleanup before leaving:

#include "x2c.x"
$scope() static int total(List values, int bias) {
  int sum = bias;
  foreach (Var value, values) sum += value.int();
  return sum;
}
int main(void) { return total(%(1 2 3), 10) == 16 ? 0 : 1; }

An expression body works the same way. A decorator written this way before a declaration that is not a function definition is rejected.

Block items the production places after the captured target are ordinary statements, so a body that returns or that a cause transfers out of never reaches them. A decorator with work to do once the body is finished puts that work in a defer written before the target; $scope, $lock, and $time are all written this way.

A .x file may give a visible macro or decorator an identifier spelling:

keyword ALIAS $QUALIFIED_MACRO;

keyword is contextual at file scope. It starts this declaration only when followed by an identifier and a $ macro name, and remains an ordinary identifier elsewhere. ALIAS must be a C identifier. A fixed C or x2c keyword does not tokenize as an identifier and cannot be used.

The named definition must already be visible. A macro alias keeps the direct invocation’s parentheses, comma-separated typed arguments, sequence arguments, and terminator:

keyword swap $project.swap;

swap(left, right);

This is $project.swap(left, right);. Parentheses remain mandatory for a zero-argument macro: generate().

A decorator with explicit arguments places them before its following target:

keyword range $project.range;

range(index, 0, count) {
  consume(index);
}

This is $project.range(index, 0, count) TARGET. A decorator with no explicit arguments retains the shorter ALIAS TARGET spelling. If every explicit parameter is a sequence, ALIAS() TARGET supplies an empty sequence; the parentheses distinguish the argument list from a parenthesized target.

Aliases do not add a second argument grammar. Arguments remain comma-separated and are parsed by the macro’s existing Expr, Type, Decl, Function, Name, Literal, Param, Statement, Block, Field, Entry, Enumerator, or Unit parameters. An alias cannot introduce a semicolon-separated control header or capture arbitrary tokens.

The declaration captures the visible macro definition itself, so redefining the same macro name later does not retarget the alias. A later keyword declaration for the same alias replaces it only for following source.

Registration and use are source ordered. Expression, statement, field, entry, enumerator, and unit macro aliases retain their result positions. Decorator aliases retain their captured Expr, Function, Statement or Block, Field, or Unit target. An invocation in the wrong position receives the same result or target diagnostic as its direct spelling.

Aliases do not globally reserve their identifiers. A macro or a decorator with explicit arguments is recognized only when the next significant token is (. The same spelling remains available as a type, declaration, field, label, or function name, but a direct call or typedef-style cast has the invocation shape and is claimed by the alias. A zero-explicit-argument decorator has no parenthesized delimiter. Its spelling is therefore claimed at each parser position compatible with its target kind; a bare expression decorator can capture a same-named expression read, and a bare block or function decorator can overlap a declaration beginning with a same-named typedef.

Aliases are local to the .x file that declares them, including when that file is included or is a package source. One alias map spans that file’s include-separated segments, while a nested included .x file receives its own map. Aliases never leak into the including file.

An explicitly imported .xmacro file may contain macro definitions and keyword declarations. Its aliases become visible in the importing .x file at the import position. Every .x file that wants the spellings imports the pack itself; an included file’s import does not expose them to its caller, and no pack is loaded implicitly by x2c.x. Macro templates are parsed when defined, so a later alias does not reinterpret an earlier template; generated Lists and strings are not reparsed as alias-bearing source.

An alias changes spelling, not decorator capability. x2c’s current thread and lambda facilities cannot lift a local block with captured variables into a C callback. A decorator may wrap an existing callback or a noncapturing construct; captured thread blocks require a separate compiler feature.

An Expr decorator has a parenthesized body and is parsed as a prefix unary form. Its target is the following C cast expression, including primary and postfix expressions, unary expressions, and casts. It therefore binds before binary, conditional, assignment, and comma operators. Parentheses widen the target explicitly:

macro Decorator $nonzero(Expr $target) => ($target != 0)

int main(void) {
  int value = 1;
int left = $nonzero() value + 1;
int whole = $nonzero() (value + 1);
  return left && whole ? 0 : 1;
}

The first initializer applies $nonzero to value; the second applies it to the complete addition. The replacement is bound as one typed expression and remains parenthesized at its call site. Surrounding C precedence cannot change its meaning.

Decorators stack closest-first. The inner expansion must leave exactly one target of the required kind for the outer decorator:

#include "meta.x"
meta static List old_body(List fn) => x2c_function_body(fn);
macro Decorator $logged(Function $function) => {
  $old_body($function)...
}
macro Decorator $validated(Function $function) => {
  $old_body($function)...
}
$logged()
$validated()
int answer(int value) {
  return value * 2;
}

A Function decorator preserves the original name, storage, qualifiers, return type, parameters, binding, and method identity. It may splice the old body, replace it, or produce an empty body. A general Unit decorator can transform a complete function or declaration, but a public target must retain the same public binding and contract and cannot gain new public siblings. Private targets and hygienically private siblings may be rewritten freely.

Shallow declaration collection loads macro imports so imported unit macros can publish their declarations and protocol rows. It does not execute other top-level Lisp forms. Decorator-shaped adjacency still collects the unchanged source target. A public target’s captured source must participate in the decorator’s Match replacement, and dropping it makes the match fail. Imported decorators work without an extra prototype.

Hygiene and generated names

Captured syntax retains its call-site binding identity. Free identifiers written literally in a body resolve where the macro was defined, including parameters and preceding declarations captured by a local macro. A declaration written in a body receives a fresh binding identity and a private generated C spelling for each expansion.

The using clause declares one or more compiler-allocated name holes. Every occurrence of one such hole within an expansion receives the same binding; different expansions receive different bindings. A using name may not duplicate an argument hole or another using name. These holes are singular Name holes and take no kind annotation and no ....

Compile-time Lisp uses x2c.ident to mark an exact public spelling. In a declarator slot that spelling creates a declaration and is normally rejected if it is already bound in the same target scope. The one completion case is a function definition produced by a Unit macro after a same-scope prototype, including one earlier in that expansion. Canonical return and parameter types, qualifiers, linkage, and any method owner/member identity must match exactly. The definition reuses that prototype’s binding once; a mismatch, a second definition, or a collision with another binding kind is rejected at the invocation. A nested scope may still shadow an outer declaration normally. In an identifier expression x2c.ident resolves the existing spelling and rejects an unknown one. Use a macro using hole for a compiler-private name that cannot collide. A bare Lisp String does not become a name when returned into a name-capable position.

The compiler parses and types arguments before expanding a macro. It then matches syntax, evaluates compile-time Lisp, and binds the generated syntax. Generated declarations become visible to following source only if expansion succeeds; a failed expansion leaves no provisional symbols or bindings. Expansion is limited to 64 nested applications and 10,000 applications per translation unit; an identical recursive application is rejected immediately. Statements authored by a macro are attributed to the invocation site; captured statements retain their original source locations.

Operators in a macro expansion use the same protocol dispatch as operators written directly, including derived ==, !=, and relational operations. Generated enumerators are installed as they are constructed, so duplicate spellings fail before C generation.

Compile-time Lisp and imports

Use $helper(...) to execute an x2c meta function. The $(...) form enters compile-time Lisp for Lisp interoperability, imports and session setup. At top level its result is discarded. Inside a macro body, $name refers to the hole’s exact AST, and the result is inserted according to the recorded body position. A syntax List inserts syntax, a scalar becomes an expression literal, a semantic Type List fills a type slot, and a syntax sequence splices only at a sequence splice point. Strings are values, never source text to be reparsed.

Inside %(...) and %"...", $name and ${expression} are runtime literal unquote. To place a compile-time result there, the outer ${ first enters x2c expression grammar: ${$helper(...)} calls a meta function, while ${$(...)} enters Lisp.

$(import "helpers.xlisp")
$(import "project-macros.xmacro")

macro Expression $computed(Expr $value) => ($(car (list $value)))

.xlisp files execute in the translation unit’s Lisp session. .xmacro files may contain macro definitions, meta functions and top-level Lisp forms. Import paths are relative to the importing file, canonicalized, loaded once, and checked for cycles. Direct Lisp file operations remain available but are not tracked as compiler dependencies.

A free name in a lambda or macro body reads the definitions the body was written next to, and then the session’s globals. The environment the call was written in is not part of that chain, so a caller that binds the same name changes nothing about what the body reads. A lambda written inside a binding form reads that form’s bindings and keeps the values it was made with. A macro that needs a value from its caller takes it as an argument.

A let binding is not visible inside its own initializer. A lambda a let binds therefore cannot call itself by that name, and the self-call reports (unbound (name h)). Write such a helper as a defun.

(let ((h (lambda (n) (h n)))) (h 3))   error: (unbound (name h))
(defun h (n) (h n))                    reads its own name

The session that translates a unit inherits the compile-time library and cannot replace one of its definitions. def on an inherited name raises (bad-state (operation "def") (why "inherited") (name NAME)), which the compiler reports as a failed compile-time evaluation at the defining form. This covers defun and defmacro, which are def. The library defines many ordinary words, including filter, last, map, search, len and apply, so a macro file needs its own names for its own definitions. A unit’s own definitions live in its own session, so one unit never changes what another reads, and the compiler treats an inherited binding as final.

eval is an ordinary procedure. The form it is given is evaluated in the session’s globals, not in the bindings around the call, so (let ((z 7)) (eval (quote (add z 1)))) reports (unbound (name z)). Build the form with the value in it when a local has to reach eval.

Compile-time Lisp is trusted code. It runs with the compiler user’s authority, including the existing native bindings and file operations; there is no sandbox. Lisp may also construct canonical AST Lists directly, including static declarations. The compiler accepts a valid structure whether it came from the parser, a Match capture, a template, or handwritten Lisp. Shapes such as src and construct(src) are ordinary AST data.

The compiler does not verify every type or binding annotation in a constructed List or reject it because of its origin. This is deliberately unsafe metaprogramming, much as C permits unsafe pointer operations. Prefer literal templates and the contextual x2c.* operations when you want the compiler to construct syntax for you.

The compiler supplies these contextual Lisp operations:

(x2c.syntax.type syntax)
(x2c.binding.spelling syntax)
(x2c.source.text syntax)
(x2c.embed.text path)
(x2c.diagnostic.fail message notes)
(x2c.ident spelling)
(x2c.invocation.file)
(x2c.invocation.line)
(x2c.invocation.column)
(x2c.method.resolve type name)
(x2c.function.name function)
(x2c.function.parameter function name)
(x2c.function.body function)
(x2c.type.fields type)
(x2c.type.resolve type)
(x2c.type.layout type)
(x2c.type.value? type)
(x2c.type.tag-name name)
(x2c.type.reverse-name base participant)
(x2c.type.parts type)
(x2c.type.parameters type)
(x2c.type.return type)
(x2c.type.element type)
(x2c.type.integral? type)
(x2c.type.pointer? type)
(x2c.protocol.member participant base member)
(x2c.literal.value literal)
(x2c.type.members type)
(x2c.diagnostic.warn message notes)
(x2c.stmnt.make expression)
(x2c.stmnt.return expression)
(x2c.block.make items)
(x2c.decl.make type name initializer)
(x2c.param.make type name)
(x2c.expr.cast type expression)

A supported operation is spelled x2c.<noun>.<verb>. A name beginning _x2c. is a compiler internal with no compatibility promise.

x2c.syntax.type returns the canonical semantic Type for supported typed syntax.

x2c.binding.spelling accepts a name hole’s valid identifier String or compiler-issued identifier and binding syntax, and returns its source spelling without exposing the numeric identity. Unknown, malformed, and forged binding identities are rejected.

x2c.source.text returns the exact source spelling of one complete captured macro argument or decorator target, including its interior whitespace, comments, parentheses, newlines, and literal escapes. Imported macros still read the caller’s source, and syntax forwarded through another macro retains where it was written. Constructed syntax, derived subtrees, name values, and calls outside expansion are rejected. Standard Lisp repr renders a canonical AST rather than its source spelling.

x2c.diagnostic.fail reports a macro diagnostic at its source location with String notes and does not return.

x2c.ident returns the tagged name value described above and accepts a String that is a valid identifier spelling.

x2c.invocation.file, .line, and .column return the caller’s x2c source location while a macro body is expanding. Lines and columns are one-based; an imported macro still names its caller rather than its definition or generated C. For example, $(x2c.invocation.line) produces an integer expression for the invocation line.

The x2c.function.* operations inspect a decorator’s captured function. name returns its free-function or dotted method name as written in source, parameter resolves a named parameter to bound identifier syntax, and body returns the block-item sequence for an explicit ... splice. Use x2c.syntax.type on a resolved parameter when its canonical Type is needed. These operations do not construct or mutate functions.

x2c.method.resolve performs direct method lookup for a Type and identifier String. It returns the typed callee expression without invoking it, or nil when the method is absent; callers supply arguments according to the returned function Type. It does not search delegate fields. The returned callee cannot represent the receiver’s field access.

x2c.type.fields resolves a typedef or qualified Type to a complete struct or union and returns its named fields in source order as (("name" DECLARED_TYPE) ...). Unnamed fields are omitted; incomplete and non-aggregate Types are rejected. Each declared Type retains pointer, array, qualifier, and bitfield modifiers.

x2c.type.resolve follows the ordinary typedef chain and returns its canonical type representation. x2c.type.layout returns the ordered field records of that representation, including unnamed members and padding. Each record is (NAME DECLARED_TYPE); an unnamed field has an empty name. Use fields for named-member access and layout when every declared field affects a decision. x2c.type.parts separates a semantic type into its declaration base and declarator modifiers as (BASE MODIFIERS). x2c.type.parameters and x2c.type.return split a function type into its parameter types and its result. x2c.type.element returns a pointer or array element type, and x2c.type.integral? and x2c.type.pointer? classify a type without resolving it.

x2c.protocol.member looks up one member of a participant’s conformance to a base protocol and returns nil when the participant does not adopt it.

x2c.literal.value returns a captured literal’s value: a String, a number, or a Symbol, according to the literal. It is the inverse of x2c.literal.string, which builds a literal from a value. A literal whose text the parser has already consumed, such as a multi-line interpolated %"...", is rejected; read its spelling with x2c.source.text instead.

x2c.type.members returns an enum’s members in source order as (("NAME" VALUE) ...). VALUE is nil when the member takes its position’s value, the literal’s exact spelling as a String when the initializer is one literal, carrying its base, suffix, and character quotes, and otherwise the initializer’s expression node, which a generator can splice or walk. Test it with string? when both kinds can occur. A non-enum Type is rejected.

x2c.diagnostic.warn reports a macro warning at the invocation with String notes and returns, so expansion continues. x2c.diagnostic.fail does not return.

The statement and declaration constructors build one node each from operands that are themselves nodes, as the x2c.expr.* family does. x2c.block.make takes a List of block items; x2c.decl.make and x2c.param.make take a Type, a name value from x2c.ident, and for a declaration an optional initializer expression. x2c.expr.cast applies a Type to an expression, carrying that type’s declarator modifiers.

x2c.type.value? recognizes numeric scalars and enums, Symbol, Var, Atom, String, List, and their typedef aliases. Pointer-shaped runtime handles such as Array are not classified as values by this operation. x2c.type.tag-name returns a round-tripping compact Symbol from the full type-name String and the current owning source file, relative to the compiler root when applicable. This keeps private types with the same spelling in different files distinct. Descriptor registration still checks collisions and capacity; a compact tag does not establish type equality.

x2c.type.reverse-name returns the conventional reverse-converter spelling for base and participant name Strings, using the protocol registry’s package naming rules. For example, base "Var" and a registered package participant "geometry__Point" produce "geometry__Var_point".

The Lisp SDK also supplies operations for literals, parameters, and expressions:

• Literals and parameters: x2c.literal.string, x2c.literal.int, x2c.literal.symbol, x2c.embed.text, and x2c.parameters.arguments.
• Expression construction: x2c.expr.ident, x2c.expr.index, x2c.expr.field, x2c.expr.call, and x2c.expr.composite.

x2c.literal.string turns a compile-time String into a runtime String literal expression, and x2c.literal.int and x2c.literal.symbol do the same for a number and a Symbol. x2c.parameters.arguments accepts either a (params ...) node or a List of parameter nodes and returns their bound identifier expressions.

x2c.embed.text reads a regular text file exactly, returns its contents as a compile-time String, and records its canonical path as a translation dependency. It accepts either a Lisp String path, resolved relative to the file containing the Lisp form, or complete captured String-literal syntax, resolved relative to the caller file where the literal was written. Absolute paths remain absolute. A zero-byte file is valid. Invalid paths, non-regular files, read failures, embedded NUL bytes, and String size overflow are diagnosed. Runtime embedding remains explicit through x2c.literal.string.

The x2c.expr.* constructors build one expression each and take expression ASTs as their operands. A generator composes them instead of writing the node shapes by hand:

(x2c.expr.index (x2c.expr.ident (x2c.ident "lhs")) (x2c.literal.int 0))

x2c.expr.ident wraps a name value from x2c.ident or a String spelling. x2c.expr.field takes a receiver expression and identifier String and builds typed field access, selecting . or -> from the receiver Type. x2c.expr.call takes a callee expression and zero or more argument expressions. x2c.expr.composite takes a List of expressions and returns a comma-separated initializer. Compose a call to an existing spelling with x2c.expr.call, x2c.expr.ident, and x2c.ident.

Names under x2c.* or _x2c.* with a component beginning _ are private implementation details.

meta functions

A function definition may be marked meta. The marker precedes the whole declaration, ahead of any storage class:

meta int poly(int n) => n * n + 3 * n + 1;
meta static String label(String stem, int n) => %"$stem-$n";

int main(void) {
  printf("%d %s\n", $poly(7), $label("item", 2));
  return 0;
}

71 item-2

meta is contextual. It marks a function only when a function definition follows it, and is an ordinary identifier everywhere else, including as a file-scope name, an assignment target, and a struct field. A meta declaration without a body is diagnosed, because the compiler has nothing to run. meta marks a definition only.

Marking a function meta has three consequences.

• The compiler translates the body into a compile-time form and installs it in the translation unit’s macro session. It is then callable during translation, by $name(args) from an x2c body or from another executing meta function. Existing Lisp code can call the same function with $(name args). A construct with no compile-time form is diagnosed at the meta marker, with the reason.
• The function is also emitted as C and behaves as an ordinary function at run time, unless it reaches a compiler query, an explicit dollar-prefixed meta call or a source-template constructor, directly or through another meta function. Such a function has no runtime form and none is emitted for it.
• An ordinary call may be folded only for a locally installed eligible definition, available constant arguments matching the parameter types, and a representable scalar, String, Symbol, immutable List or boxed result. Mutable container, callable and native-address results remain calls. This optimization is separate from explicit evaluation and result insertion.

A dollar-prefixed function call requires compile-time evaluation. Arguments may compute values from other resolvable values and meta calls; unresolved runtime inputs are diagnosed. Visible macros retain precedence over meta functions with the same name. In a macro body, forwarding a captured hole directly passes its code rather than evaluating the future runtime expression.

A directly forwarded hole retains its declared capture kind, including Function, and complete captures retain their source text and path context. Inside a macro template, an explicit call can supply a type, generated name or syntax sequence as well as an expression; the ordinary slot binder checks the returned value for that position.

Inside meta bodies, Unit and Statement source macros used in expression positions construct deferred invocation Lists from computed arguments. Normal binding expands them when inserted into a program. Existing Expression macros still expand normally. See source templates.

The compile-time subset cuts across C and x2c constructs. Local mutation, represented collections, local address-taking/dereference, and resolved method calls are supported; native aggregate field access and operations without compile-time bindings are not. A supported type does not expose all of its runtime methods. See the guide’s capability and operation inventory.

Meta functions may pass and return represented values such as wide integers, floating values, Strings and collections during compile-time execution. Explicit $name(args) insertion, and the optional $(name args) Lisp form, accept numeric values with their native Var family, computed strings as C string literals, Symbols, identifiers and nonempty expression-code Lists. It does not directly materialize mutable collections, callable values or evaluator addresses. This boundary does not limit internal returns to int; see results.

Compile-time objects belong to the evaluator. Ordinary dual-form meta functions reject file-scope state because the program’s initializers and future mutable state are not available to them. Compiler-only functions reaching compiler operations are exempt from that rejection, but use separate per-unit compile-time state, not the program’s variables.

A meta declaration in an imported .xmacro installs its compile-time form in every consuming unit. The runtime forms are independent: a unit emits a definition only for those it reaches, and the storage class written on the declaration says what it emits. Importing the same file twice contributes one copy of each definition.

See Meta Functions for the authoring guide.

The same operations from x2c

Every public operation above is also declared in x2c, in the optional module lib/meta.x, so a meta function that includes it calls the compiler directly and a macro’s implementation does not have to be written in Lisp. The declarations are the signatures; the semantics are the ones described above.

The name is mechanical: each . becomes _. x2c.type.fields is x2c_type_fields, x2c.invocation.line is x2c_invocation_line, x2c.ident is x2c_ident. Two answers differ in shape because x2c has no spelling for the Lisp one:

• x2c_expr_call(List callee, List arguments) takes its arguments as one List rather than as a rest parameter.
• x2c_type_value(List value) returns int, 1 or 0, rather than a Lisp truth value.

x2c.comptime.lower has no x2c wrapper, because it runs the pass that translates the calling function.

The code builders have meta bodies in lib/meta.x, shared by the x2c and Lisp functions. The literal builders, identifier, index, call and composite builders, function-body reader and parameter-argument builder also run at runtime. The field and cast builders call compiler queries.

Operations declared without bodies exist only inside a compiler. A meta function that reaches one, directly or through another meta function, has no runtime form and none is emitted for it. The compiler infers this restriction; no additional annotation is needed. Explicit meta calls and source-template constructors also make their enclosing meta bodies compile-time-only. A call to one from a run-time body is diagnosed where it is written, naming the function and the reason.

Compiler facilities load before author imports, and macro code cannot redefine them.

Standard Lisp exposes the List matcher of Pattern Matching as six names. match tests a whole subject and returns association-list bindings, nil on failure, and truthy (()) for a match with no named binders; a pattern describes a List shape, so a subject that is not a List fails rather than raising. bound reads one binder out of that alist. search finds the first matching subtree. match-replace and search-replace rewrite the whole subject or the first matching subtree from a template. match-case tries each clause’s pattern in order and evaluates the first body whose pattern matched, with that pattern’s binders in scope as variables; a final (else body) clause runs when nothing matched.

(match-case form
  ((add ?a ?b) (+ ?a ?b))
  ((neg ?a)    (- 0 ?a))
  (else        0))

A clause’s pattern is quoted implicitly and written as List syntax, with the same ?binder and *binder spellings. A binder keeps its ? where the body reads it. Without an else clause an exhausted match-case is nil.

Compile-time Lisp also reaches the core value types directly. A Lisp value in a session is an x2c Var: a Lisp list is a List, a Lisp string is a String, and a quoted name is a Symbol. The operations below are the library’s own, so a macro and the program it generates compute with the same List, String, Map, and Array.

List.getindex  List.last     List.index    List.contains
List.get       List.assoc    List.array    List.sort

Array.new      Array.len     Array.push    Array.getindex  Array.setindex
Array.take_last Array.shift  Array.unshift Array.insert    Array.remove
Array.find     Array.contains Array.count  Array.join      Array.list

Map.new        Map.len       Map.get       Map.getindex    Map.setindex
Map.contains   Map.del       Map.getdefault Map.setdefault Map.list

String.len     String.find   String.rfind  String.count    String.contains
String.startswith String.endswith String.getindex String.getslice
String.add     String.lower  String.upper  String.capitalize
String.repeat  String.replace String.join  String.split    String.split_lines
String.partition String.rpartition String.find_all
String.remove_prefix String.remove_suffix String.escape String.unescape

Var.tag        Var.kind      Var.is        Var.parse       Var.convert
Var.integer    Var.floating  Var.is_null

Symbol.len     Symbol.str    Symbol.compare

Each name takes the arguments its library entry documents and behaves identically. Var.parse reads a String as an int, double, string, symbol, or char, and Var.convert changes a value’s numeric tag, which is how compile-time code narrows a double to an integer. Map.list returns a map’s entries as (key value) pairs, because a Map cursor has no Lisp representation.

The Lisp core keeps its own spellings for cons-cell and text work. car, cdr, cons, length, reverse, string-append, substring, lower, str, and repr are unchanged and reach the same code. Note that Lisp’s assoc returns the matching pair while List.assoc returns its second value, as the library documents.

An operation whose parameters or result have no Var representation is not available, which excludes Iter cursors, pointer out-parameters, variadic entry points, and char * parameters. A program embedding its own session loads the same names from etc/lisp-values.xlisp.

Macro-visible syntax

Lisp sees the canonical parsed, typed List AST used by --dump-ast, with source (at ID NODE) wrappers removed. Tags and semantic Types remain Lists. Binding records are visible so syntax can be preserved and compared, but their numeric IDs are opaque and must not be forged. Use x2c.binding.spelling when text is required.

The compiler records where syntax was written separately from its AST value. x2c.source.text exposes it only for a complete captured argument or decorator target; arbitrary AST Lists do not acquire source text by structural equality. Diagnostics retain the definition, invocation, import, and generated ancestry even after a macro returns a new List. Returned syntax must be valid for its expression, field, enumerator, block-item, or translation-unit position. Protocol declarations, macro definitions, preprocessor nodes, and other compile-time-only source items are retained at translation-unit position and apply their source-order effect. The compiler rejects forms that are malformed or invalid in that position. As with other constructed ASTs, it does not recursively verify annotations or check where a handwritten List came from.

Named types and declaration production

NamedType captures NAME TYPE; or the forward form NAME;. The name comes first, with no equals sign. { FIELDS } abbreviates a value struct; struct { FIELDS } * explicitly declares a pointer representation. Ordinary type and declarator grammar owns qualifiers, fields, arrays, and pointers. The name is reserved before its fields are parsed, and the complete definition supplies its representation. A forward declaration does not imply a pointer. Layout must be complete wherever the ordinary type rules require it.

The captured form is (named-type NAME TYPE), where NAME is a String and TYPE is the complete canonical type syntax; a forward uses an empty TYPE. This form is constructible by any macro or Lisp producer. Binding it publishes the same ordinary typedef and aggregate declarations as the captured source.

A Declaration macro, or a NamedType decorator, produces declarations once while the owning source’s public declarations are collected. Its result is retained for full binding; the producer is not evaluated again to obtain its bodies. Nested declaration producers share this rule. The source’s private boundary and ordinary dependency invalidation apply to the retained result. Imported and cached declarations publish the selected signatures of their owning source.

The canonical container is (declaration-bundle (rows ITEM ...)). Rows may include ordinary top-level syntax and these constructible forms:

• (default FUNCTION) supplies a function candidate. An ordinary declaration of that exact function in the owning source wins, including a later one. Only the selected body is bound. A candidate below #pragma private has static linkage. Two ordinary definitions still conflict.
• (declaration-recipe CALLBACK ARGUMENTS) defers a Lisp producer until the owning source’s declarations are available. It is evaluated once, and its declarations join the same bundle.
• (default-forward CHILD PARENT MEMBER FALLBACK) selects an ordinary parent method after signatures are collected and supplies a child forwarding method. FALLBACK is an optional function candidate when no parent applies.
• (syntax-recipe CALLBACK ARGUMENTS) supplies syntax when a retained body is bound, allowing it to use the selected method signatures.

These rows express declaration and binding positions, without authenticating which producer constructed them. Retained bodies also carry the usual macro bindings and source locations for diagnostics. A consumer cannot replace a provider’s exported default by defining another function with its name.

Class declarations

The shipped class keyword aliases the $class NamedType decorator. See Classes and System Macros for the complete default-method inventory, construction, and lifetime examples. A class preserves its explicit representation and ordinary typedef ancestry. It adds replaceable methods through declaration defaults. An explicit new suppresses its generated constructor and init requirement. Derived classes forward the nearest applicable constructor; variadic forwarding requires an explicit constructor.

Flat value fields produce positional constructors in declaration order, with unnamed bitfield padding omitted. Non-flat or resource-containing aggregates require void T.init(T *) for a value or void T.init(T) for a heap pointer, called on zero-initialized storage. Heap defaults allocate through Scope and provide early free; they do not recursively own fields. Scalar and derived aliases retain their ordinary Var representation. Heap classes box identity; aggregate values box a Scope-owned copy and require compatible equal/hash operations, generated for supported value fields.

str and repr are independently replaceable. Aggregate value str delegates to repr; heap str prints identity. Generated repr traverses printable fields and uses addresses for opaque pointers. Repeated identities on the active rendering path print their pointer form. Descriptor registration retains the runtime’s fixed capacity and worker-start freeze rules.

Managed-initializer syntax

(managed-init EXPR) is a constructible initializer form. $auto(value) produces it; an equivalent List built by another macro or compile-time Lisp has the same meaning. It may be wrapped in typed expr nodes and parentheses. Only the complete initializer of an initialized automatic declaration that is a compound-statement item consumes the form. The declaration keeps its type, binding identity, initialization conversions, and enclosing scope, followed by an ordinary deferred call to the type’s selected cleanup method.

The declared type must participate in Cleanup(T), whose member is void T.cleanup(T), directly or through its ordinary typedef ancestry. Initializers run once in source order. Each successful initializer registers its cleanup before the following initializer runs, including within a compound declaration. Cleanup observes the declared binding at exit; reassignment does not dispose the old value, and returning or storing an alias does not cancel cleanup.

Static, external, or threaded storage, field initializers, for-header declarations, assignments, returns, call arguments, and forms nested inside operators are outside this enclosing-block position. These are syntax-position rules, independent of the producer of the AST. There is no runtime expression helper or expression-exit cleanup.

Checked foreign aliases

The reserved target macro $x2c.foreign.alias binds one top-level X2C function name directly to an ABI-compatible C function:

$x2c.foreign.alias(fclose)
inline int File.close(File file);

The target must be one fixed-arity function declaration without a body or initializer, and the argument must be one direct C identifier. Static aliases remain private; non-static aliases are published in the generated header like any other declaration. The generated C uses _Static_assert and _Generic to check the exact function-pointer type before defining the lowered X2C name as the native name. Calls and address-taking therefore use the native function itself; no wrapper object, thunk, argument mapping, or initializer is emitted. Variadic aliases are rejected.

Typed callback adapters

The reserved expression macro $x2c.callback.adapt adapts one direct function to an explicitly named callback typedef:

typedef String (*StringCallback)(Var);

static StringCallback array_string =
  $x2c.callback.adapt(StringCallback, Array.str);

The target must name a fixed, non-variadic function-pointer typedef. The source must be a direct free-function or Type.method designator, not a function-pointer variable, lambda, bound receiver, or conditional expression. Target and source must have the same arity and exact non-void return type. Parameters may be exact, or a target Var parameter may be extracted to the pointer/typedef owner or Symbol required by the source. The adapter performs no numeric or general coercion and does not insert, drop, reorder, or default arguments.

The compiler emits one translation-unit-local, statically typed thunk for each source/target pair and reuses it within that translation unit. The thunk has a prototype before any file-scope initializer that references it, and no incompatible function-pointer cast is emitted. The expression therefore suits private descriptor tables and other fixed C callback positions.

Values and literals

The tagged value model specified here is introduced gradually in values and Var.

Array and Map literals

In operand position, a bare [ begins an Array literal. Its comma-separated elements are ordinary x2c expressions, each converted to Var, and a trailing comma is accepted:

int n = 4;
Array values = [1, n * 10, "text", <sym>, [n]];

A { whose first entry is a Map entry begins a Map literal. An entry is KEY: VALUE, or an Entry macro invocation. A key that is a bare identifier is an Atom, with the same spelling rules as a bare collection Atom. Every other key, and every value, is an ordinary x2c expression. Parenthesize an expression key that is a single identifier:

int n = 4;
String name = "ada";
Map ages = {ada: 36, grace: n + 41, "text": 1, <sym>: 2, (name): 3};

A Map entry is identified by its first : that is outside nested brackets and belongs to no ?: conditional. A brace without such an entry remains a C initializer. Inside an initializer, a bracketed index followed by =, ., or [ remains a designator; any other bracket is an Array literal. Both literals build a fresh object at each evaluation, as %[] and %{} do, and a declared typed Array or Map family builds its own representation. Nested [...] and {...} are evaluated literals of the same kinds; nested List data is written %(...).

[] is a fresh empty Array. The empty brace {} is a fresh empty Map when its destination is a Map, an alias of Map, or a type that converts from Map, and likewise for Array; for any other destination, including Var, it is the native zero initializer. An element or value of a bare [...] or {...} literal is the exception: there {} is an empty Map, so [{}] holds one Map. Outside a declaration initializer, a brace that remains an initializer becomes a compound literal of its destination, as an argument, a return value, an assignment, or a ?: arm: Map m = ready ? {} : NULL; builds a Map, Var v = ready ? {} : NULL; is Null either way, and return {3, 4}; in a function returning a struct builds that struct. An anonymous struct or union destination has no compound-literal spelling and is rejected.

The percent forms %[...] and %{...} below keep their quoted grammar. The bare forms differ only in evaluating elements, values, and non-identifier keys.

Percent literals, quote, and unquote

In operand position, % followed by a literal delimiter is the quoting sigil. The delimiter selects a literal grammar, which then decides how to read the contents. Quoting here means a parser-context change; it does not mean that every percent form contains unevaluated symbolic data. Binary % remains the modulo operator, and %! remains the lambda-literal prefix.

%", %[, and %<< open literals after any token. Modulo by a string literal is invalid C, and neither [ nor << begins an expression, so a cast may precede these literals: return (Path) %"$base/$name"; quotes. A cast may precede a bare [...] Array literal as well: (Var) [1, 2].

In %(, %{, and %! after an operand, including a closing parenthesis or brace, the % is the modulo operator, except where a statement begins:

• after the parenthesized condition of if, while, for, or switch, so if (dirty) %(git stash).job().run(); quotes;
• after the } of a compound statement or declaration body, so a %(...) statement may follow the closing brace of a foreach body.

A brace counts as a body when the token before its { is ;, :, {, }, ], an identifier, else, do, try, finally, or defer, or a ) that closes a control condition, a match subject, or a parenthesized list after an identifier, as in a function header, foreach, with, or a decorator. A compound literal or initializer brace follows an operator or a cast, so % after it stays modulo: (int){9} %(4) is 1.

The tokenizer has no type information, so it cannot distinguish a cast from a parenthesized operand. After any other ), %(, %{, and %! are modulo, as in (a) %(b). Parenthesize such a literal after a cast: (List) (%(echo done)).

The collection and string literal forms are:

The static type in that table is the default. The declared target may instead be one of the optional typed families: a packed Array from typed-array.x, a packed Map from typed-map.x, or a typed cons chain from typed-list.x. The literal then builds that representation directly, and an element that does not convert raises <no-convert>. A null source stays null.

The empty forms are %(), %<<>>, %[], %{}, and %"". Each %[] or %{} evaluation creates a fresh allocated object that can be mutated immediately; null is not an empty Array or Map.

Inside a List, Array, or Map, a bare spelling is a case-sensitive Atom. It is a compact Symbol when Symbol encoding reproduces the spelling exactly; otherwise it uses <lsym>. Consequently, %(name), %[name], and the key in %{name: 1} hold the same value as an explicit <name>, and the angles are redundant. Use angles when bare collection syntax would read the text as another value, as in <1> for the Symbol 1 rather than the integer 1, or when compact Symbol representation is required. The empty Symbol must likewise be written <""> because a bare Atom cannot be empty. An angle spelling that does not fit is rejected instead of falling back to <lsym>.

Integer, floating, signed numeric, and character literals retain their concrete types. Lowercase void remains the absence sentinel and is rejected if collection construction tries to store it.

$name inserts one identifier expression into a quoted collection. ${expression} inserts one arbitrary x2c expression, including calls, member and index expressions, operators, casts, compound literals, NULL, enum constants, and comma expressions. Each expression is evaluated once. @name and @{expression} splice a List into a surrounding List; Arrays and Maps have no splice form. The identifier forms are the short versions of the braced expression forms. The collections chapter walks through building and using each one.

For Lists that will be evaluated as Lisp, ', `, ,, and ,@ are the short forms of quote, quasiquote, unquote, and unquote-splicing. Each wraps the one element that follows it, wherever it appears, so %(...) and the Lisp reader construct the same List data from the same text. Reader punctuation also ends a bare Atom: %(a,b) is a followed by (unquote b). These spellings do not replace x2c’s $ and @: those still insert or splice x2c values while the List itself is being constructed. A @ followed by whitespace, ), or = is the ordinary @ or @= operator atom, so %(op @ a b) spells the same List the parser builds.

%<<...>> is an immutable ordered SymbolSet. Bare entries are compact Symbols rather than Atoms, and their source positions are their numeric indexes. Entries must be literal spellings; interpolation, splicing, and runtime expressions are not accepted. Every entry must survive compact Symbol encoding exactly. Duplicate encoded Symbols are a compile-time error. SymbolSet.index returns the source-order index or -1, contains tests membership, getindex performs the reverse mapping, and the Iter protocol traverses members in source order. The compiler emits the perfect hash and ordered membership table as static bytes, with no runtime construction or allocation.

Inside %(), %[], %{}, and %"", $ is the unquoting sigil. It leaves the selected literal grammar, parses and evaluates one x2c expression, inserts the converted result, and returns to the literal grammar. In %(), @ makes the same crossing but splices the evaluated List’s elements. Collection insertion converts to the representation required by the literal; String insertion accepts String, Symbol, declared converters, Var, aliases of Var, and supported numeric values under the existing conversion rules.

The braces belong to the unquote and contain one complete x2c expression, including nested calls, indexing, casts, assignments, conditionals, comma expressions, and nested literals. In a collection, $name(...) instead inserts $name and then reads (...) as a nested symbolic List. In %"", the parentheses after $name are text. A runtime call in any quoted form is therefore ${name(...)}.

Nested (...), [...], and {...} remain quoted List, Array, and Map data, and nested "..." selects the x2c String grammar with its interpolation and escape rules. None repeats the % sigil, because a bare % inside quoted collection data is an Atom: %(k %"txt") reads as the three elements k, %, and "txt". ${"text"} instead inserts an ordinary C string expression. Unescaped comma, colon, ], and } terminate collection Atoms; backslash escaping or angle syntax expresses those bytes as data. %<<...>> accepts literal Symbols only and permits no interpolation or splicing.

$(...) remains compile-time Lisp in ordinary x2c code. Inside a quoted collection, ${$(+ 40 2)} first unquotes into x2c and then enters compile-time Lisp. $name(...) remains a macro invocation in x2c. These parser contexts do not change Lisp quote or quasiquote.

Percent strings are byte strings: they may span physical lines and their \\x, \\u, and \\U escapes consume one or two hexadecimal digits. Ordinary C string and character literals instead follow C escape widths, including exactly four digits for \\u, eight for \\U, and one or more for \\x; an unescaped newline does not continue an ordinary C literal.

Adjacent ordinary C string literals form one expression, including across comments or newlines. Their separate escape boundaries are preserved: "\\x41" "B" contains A followed by B. The result keeps ordinary C string typing and converts to String when its context requires it. A context whose type is a class or typedef alias reaching String, such as class Path String;, requires the same conversion. A literal used as the receiver of a method with no char * definition converts to String first, so "hello".len() is 5. foreach iterates such a literal as that String, and a raise detail accepts it as an immutable String. In these three positions a parenthesized literal, a ?: whose arms are both literals, and an object-like macro defined to a string literal, #define NAME "x", are literals too, so (ready ? "on" : "off").len() and NAME.len() work. A macro name is a literal only while every definition it has is a string literal and no #undef has dropped it. A name written next to a literal is one of the adjacent words when it is such a macro or when this unit cannot resolve it, as a header’s PRId64 is, so printf("%" PRId64 "\n", count) works. This adjacency rule does not combine percent strings or change quoted collection syntax.

Immutable literal construction is cached for the process lifetime. This includes an ordinary C string literal when its context promotes it to String, as in String name = "x2c";; a dynamic char * or char[] value still converts when the expression is evaluated. The ordinary literal keeps its exact C escape spelling and decoding, and does not acquire percent-string escape rules.

Cached Strings, boxed Var values, and canonical List graphs are allocated eagerly during translation-unit initialization and retained for the process lifetime. A cached literal in a public inline function uses private storage in each C translation unit that includes the generated header; canonicalizers still make equal String and List values share their value identity. A guarded call on the inline entry is the fallback on hosts where eager constructors do not run. Consequently, an allocation failure may occur before main rather than at the source expression.

Caching does not change the other identity rules: Lists and non-empty Strings are canonical when constructed through their canonicalizers; Arrays and Maps are mutable identity-bearing objects and are constructed at each evaluation. Non-empty Array and Map literals use counted construction. Raw Null remains valid collection data, while a dynamic expression that evaluates to void reaches the collection owner and is rejected rather than ending construction.

File-static String, List, Array, and Map declarations may use their percent literals directly. A file-static Var may likewise use one of those literal values:

static String child = %"$root/child";
static String root = %"root";
static List names = %($root $child);
static Var literal_index = %{root: $root, child: $child};

The compiler leaves each C declaration zero-initialized and moves its runtime assignment into the translation unit’s guarded initializer. Literal caches run first, followed by the assignments in dependency order; a declaration may therefore depend on a later file-static declaration. Independent assignments retain source order. Every object referenced by one of these initializers must itself be file-static, and a dependency cycle is a compile-time error. Native initializer operands expand at the original source position: later macro definitions do not change them, __COUNTER__ keeps source order, and explicit inline tags remain visible at file scope. Native macro invocations retain their normal stringizing and token-pasting rules. Tags hidden inside an opaque native macro remain subject to native C scope.

A function-local static declaration with a runtime-valued initializer runs once when control first reaches it. This includes aggregates containing String or Var values, function calls, and values from function arguments. Concurrent calls wait for the initializing call to publish the whole object. If initialization raises an Error, a later call retries; side effects already performed by the initializer remain. Recursive initialization, including a cycle between initializing threads, raises bad-state rather than waiting forever. A static threaded declaration follows the same rule separately in each thread. Native constant initializers retain native C static storage.

Runtime-initialized local objects preserve their declared type, qualifiers, array shape, and address across calls. Their storage lasts until process shutdown, or thread teardown for threaded objects. This storage does not extend the lifetime of values it refers to: an initializer allocating a Map inside a temporary Scope still gives that Map the ordinary Scope lifetime. Use an owner that outlives every use of the stored value. Failed initialization retains the reserved address; the next attempt starts with zeroed storage. Only successful initialization publishes the value, and retry does not change referent ownership.

A goto or switch dispatch cannot bypass a runtime static declaration and enter its remaining block. Put the declaration before the switch, or put it inside a case’s own block. A nested switch reached after initialization is valid.

Native macro calls can be runtime initializers. A bare unknown native macro name, however, retains native C initializer rules: its expansion may be either a constant or a call, which x2c does not inspect. Use an explicit function call when a runtime expansion needs first-use initialization. Native macro bodies also cannot name a lowered local object implicitly; pass the object as a macro argument so its ordinary bound expression is preserved.

Symbols

<name> and <"punctuated name"> produce a 64-bit immediate Symbol. Symbols are encoded, not allocated or entered in an intern table.

The encoding is selected from the payload:

• the restricted 5-bit alphabet preserves at most ten characters;
• the general 7-bit encoding preserves at most seven characters.

A source literal is accepted only when decoding the encoded value reproduces its exact spelling. Case folding, _/- folding, and truncation are compile errors in literals. Symbol.new remains the runtime encoding API and truncates or normalizes dynamic input to the selected capacity. Symbol.try_new instead reports whether dynamic input has an exact compact representation and leaves its output untouched when it does not. Equality compares the encoded value.

Symbols also name outcomes and states. For example, Lisp.read returns <value> or <eof>. It raises <incomplete> or <malformed>, and neither returns to the call. Error causes such as <bad-sig>, <no-symbol>, <bad-arity>, <bad-types>, and <bad-result> are Symbols too. Numeric enums remain appropriate when their values are indexes, packed fields, arithmetic inputs, or external numeric encodings.

For Lisp input, <incomplete> means more source can complete the current form: an open list, string, block comment, or symbol literal, a reader prefix without its form, or an escape cut off by end of input. <malformed> means the bytes already prove the form invalid, such as a bad escape, raw string newline, malformed number, invalid closed symbol literal, or stray closing parenthesis. The shared Tokenizer classifies lexemes; Lisp.read checks structural form balance and preserves the form-start cursor on either failure.

Atoms

Atom is the canonical exact-name type used by List literals and Lisp. It is Var-shaped and has two representations:

• an immediate compact <symbol> when encoding and decoding reproduces the exact spelling bytes;
• a private <lsym> whose payload is the canonical String pointer otherwise.

Atom.intern is the only function that maps a spelling to a representation. Repeated construction of one spelling has identical Var bits. Long Atom equality therefore completes in the existing raw-Var fast path, and its hash is the String’s cached hash. Atom.str returns the exact bytes, and Atom representation escapes delimiters, numeric-looking prefixes, comment openers, whitespace, controls, and backslashes so both %() and Lisp.read recover the same value.

Long Atoms follow the canonical String pool lifetime, which is described in scopes and lifetime. Promoting a List also promotes long Atom payloads contained in it; a standalone long Atom that must escape a child String pool can promote its Atom.str before that pool is released.

For a side-by-side introduction to the two types, see symbols and atoms.

Var, Null, and void

Var is the tagged value used by heterogeneous collections and generic runtime APIs. Supported native source types round-trip through their matching Var tags. long, unsigned long, long long, unsigned long long, and long double use immutable scope-owned boxes while Var itself remains eight bytes. Their tags are <long>, <ulong>, <llong>, <ullong>, and <ldouble> respectively; the runtime derives their widths from those C types. Explicit i48/u48 tags complete the numeric family set. The same names with * or ** identify their pointer families.

Raw Null is the all-zero Var. A typed empty String and nil/List preserve their type tag when boxed. Arrays and Maps instead require allocated objects even when empty; boxing a null pointer with either value tag is an invariant violation. void is the all-ones terminal/tombstone value used by APIs for exhaustion or absence. Status-bearing Iter and Map APIs separate success from payload bits. Iter.next, Map.get, and Map.del use void for exhaustion or absence. Malformed representations, including null wide boxes and null Array or Map values, are rejected. Every accepted nonnull pointer must name a live object established by its constructor.

Lowercase void is contextual. In a type position it retains C’s no-result type, including function returns, (void) parameter lists, void *, casts, and sizeof(void). In an expression position it is a Var literal for the all-ones sentinel. Parentheses do not change that distinction: (void) is a parenthesized sentinel expression when it stands alone, while (void) call() and (void *) pointer are casts because an operand follows the complete type.

Two sentinel operands compare equal with == and identical with ===; != and !== are their exact inverses. A sentinel and any ordinary value compare unequal. Var.equal, Var.fallback_equal, Var.same, and the four equality and identity operations accepted by Var.binary follow those rules. Var.str, Var.repr, Var.write_str, and Var.write_repr all render the sentinel as lowercase void.

Hashing, ordering, truthiness, iteration, conversion, arithmetic, compound updates, and increment or decrement raise <void-op> when they receive it.

Membership with in

The contextual in operator tests membership in a collection. It is the operator spelling of the receiver’s contains member, selected through the Var(T) protocol, and it compiles to that same call:

Map ages = {ada: 36};
List names = %(ada grace);
Array counts = [1, 2, 3];
String text = "hello";

int keyed = <ada> in ages;
int element = <grace> in names;
int value = 2 in counts;
int substring = "ell" in text;

A Map tests its keys, a List or Array its elements, and a String a substring. The left operand converts to the member’s parameter type, so a Var holding the key works as well as a literal. A receiver whose type does not implement a contains member is rejected with operator 'in' requires an implemented contains member. The member comes from a protocol the receiver adopts: Var(T) declares one, and the one-member Contains(T) protocol gives membership to a type that holds members without boxing them, as SymbolSet does. There is no not in spelling; write !(name in ages).

in is a keyword only between two operands, so struct buffer *in and int in = 0 remain ordinary names.

Exact Var-tag tests with is and is not

The contextual is operator tests a Var value against a source type or an exact tag Symbol. Add not after is to invert the result without wrapping the test in !():

Var value = 42;

int integer = value is int;
int byte = value is u8;
int sequence = value is List;
int exact = value is <i32>;
int pointer = value is (Var *);
int absent = value is void;
int not_byte = value is not u8;
int present = value is not void;

The left operand must have static type Var or a file-scope alias of Var. The result is int. The operator has relational precedence, and its left operand is evaluated exactly once. A Symbol expression on the right is also evaluated exactly once. A type selector is compile-time syntax and is not evaluated. is not has the same precedence and evaluation rules, then logically negates the exact-tag result. is and not remain ordinary identifiers in all other positions, so existing variables with either name and calls such as value.is(<i32>) are unchanged.

The test compares exact Var tags. It does not test numeric convertibility, protocol ancestry, or C type identity. Qualifiers and aliases are resolved to the tag family used by boxing, which means source types that share one tag cannot be distinguished. For example, char and signed char both select <i8>, while int, int32_t, and i32 all select <i32>.

The right operand may be either a type or a Symbol expression. Accepted types include a supported scalar or system numeric typedef, a builtin runtime type such as String, List, Symbol, or Var, a visible type with a declared protocol Var(T) conversion, or a package-qualified form of one of those types. Supported pointer and double-pointer types are also accepted, but declarator-shaped types must be parenthesized:

static int pointer_tags(void) {
  int number = 0;
  int *pointer = &number;
  int **double_pointer = &pointer;
  Var pointer_value = pointer;
  Var double_pointer_value = double_pointer;
  return pointer_value is (int *) &&
         double_pointer_value is (int **);
}

An unparenthesized pointer selector is rejected with the parenthesized spelling. Arrays, function types, unsupported pointer depths, unknown types, and aggregates without a Var(T) adoption have no tag to select and are rejected. Enum selectors are rejected because enum values box as the shared <i32> family and retain no nominal enum identity.

A literal or computed Symbol is used directly as the exact tag selector:

Var value = 42;
Symbol wanted = <i32>;

int literal = value is <i32>;
int computed = value is wanted;

An unregistered Symbol cannot match a valid Var tag, so the result is false. No other expression type is accepted on the right: numeric, pointer, object, and Var-valued expressions do not stand for types.

Lowercase void is the one selector whose type spelling also names a value. It tests the all-ones absence sentinel through Var.is_void: void is void is true, while the sentinel does not match any ordinary tag or type. Raw Null has the pointer-family <p48> tag, so it matches (void *) and does not match void; there is no Null selector.

A Type hole or a Symbol-valued Expr hole in an Expression macro may occupy the selector position. An expanded type is resolved in the invocation context, including pointer types:

macro Expression $has_type(Expr $value, Type $T) => ($value is $T)
macro Expression $has_tag(Expr $value, Expr $tag) => ($value is $tag)

static int has_pointer_type(void) {
  int number = 0;
  int *pointer = &number;
  Var value = pointer;
  return $has_type(value, int *) && $has_tag(value, <i32*>);
}

Dynamic numeric conversion

The public numeric conversion domain contains all 15 Var families: i8/u8, i16/u16, i32/u32, i48/u48, long/ulong, llong/ullong, and f32/f64/ldouble. Var.convert(value, tag) returns the converted value and raises the specific Error cause when no conversion exists, the target is invalid, the value is out of range, or the Var encoding is invalid. None of those causes return to the call. Compiler-inserted Var-to-native numeric conversion passes through the same function before using the target extractor. The scalar-named readers Var.int, Var.double, and their siblings apply the same rules directly. A matching tag reads its payload, and any other numeric tag converts through Var.convert. The raw payload readers Var.integer and Var.floating and the wide *_value functions remain exact low-level decoders.

Integer-to-integer conversion never uses a floating intermediary. It retains the destination-width low bits; signed destinations interpret those bits as two’s-complement. Floating-to-integer conversion truncates toward zero when the truncated result is representable. NaN, infinities, and out-of-range results report <conv-range>. Integer-to-floating and floating narrowing use normal host floating-point behavior.

These numeric rules do not define conversions between nonnumeric tags. String, Symbol, collection, pointer, and custom-object values use their declared conversions. Numeric-to-String interpolation boxes through the verified numeric tags and renders with Var.str. A structurally valid nonnumeric Var may convert to its own tag unchanged; conversions to other tags must be defined separately.

A printf-family call with a static format can also format a Var. Numeric format specifiers convert it to the required promoted C type through Var.convert; %s uses Var.str. The recognized families are printf, fprintf, sprintf, snprintf, String.printf, File.printf, and Buffer.printf. A call with a Var variadic argument requires one direct static format literal. Automatic lowering covers numeric conversions, %c, %s, * width and precision, and the hh, h, l, ll, and L modifiers. Other modifiers, pointer and count conversions, wide strings and characters, and positional formats require explicit native arguments.

Dynamic truthiness and binary operators

When a condition has static type Var or a file-scope alias of Var, the compiler applies the Var.truth base member in if, while, do, classic for, ?:, and unary !. A static protocol participant uses its eligible truth member: an implementation, native alias, or base default. The compiler applies the member independently to operands of && and ||, leaving C’s short-circuit evaluation intact.

Truthiness is false for numeric or Symbol zero, Null and null pointers, canonical empty String/List, and empty Array, Map, Block, Bytes, or Buffer values. It is true for nonzero values, NaN, infinities, nonempty containers, and other nonnull objects. A nonnull Iter is true even when exhausted; the test does not probe its producer. void is outside the value domain, and a compiler-inserted Var.truth raises <void-op> for it. That raise does not return to the test.

If either operand of +, -, *, /, %, @, <<, >>, &, ^, or | has static Var identity and the other operand is Var or statically numeric, both operands convert to Var and the result is Var. A nonnumeric operand is rejected at compile time if its type is known statically, or at runtime if it is held in a Var. Native-only expressions remain native C. Integer operations promote their operands to a common integer type. Arithmetic and left shift retain the low bits that fit that type; signed results interpret those bits as two’s-complement. Signed right shift fills the sign bits. A negative shift count or a count at least the promoted left width fails, as does integer division or remainder by zero. String-tagged Var values additionally accept + with a String or raw C string operand. The result is a canonical String; no other runtime tag is stringified implicitly.

Floating operands support +, -, *, and / in the widest participating floating family. Host floating behavior includes infinities or NaN from floating division by zero. Remainder, shifts, and bitwise operators reject a floating operand. Direct Var lvalues support prefix and postfix ++/--; prefix returns the updated Var and postfix returns its original value. Unary - uses an eligible neg protocol member for a static participant or the Var base member for a dynamic value. Comparisons dispatch separately. ==/!= use an eligible equal member, relational punctuation derives from compare, and ===/!== remain unconditional identity tests. Eligible means implemented, native, or a base default. When the operands of a protocol operator are two different typedef names that share an ancestor, such as an alias of String and a String, or two aliases of String, the operator uses the eligible member of their nearest shared ancestor. Equality, identity, and total ordering do not become binary-arithmetic operations.

For ==, !=, <, >, <=, and >=, a C string literal opposite an operand of static type String, or an alias reaching String, converts to that type before ordinary protocol comparison. This applies in either operand order, through parentheses around the literal, and to a ?: whose arms are both literals. Other C pointer expressions, including variables and casts, retain their native comparison behavior. === and !== do not perform this literal conversion.

For +, when each operand is a String, an alias reaching String, a char array, a char *, or a const char *, both convert to String and the result is the String that String.add returns, so path + ".o" concatenates.

Direct runtime calls to Var.binary additionally accept comparisons and eager &&/||. The compiler does not use that eager logical path. It converts each Var operand at its original C short-circuit position.

Protocol-backed direct updates

A direct participant lvalue supports +=, -=, *=, /=, %=, or @= when its protocol-resolved add, sub, mul, div, mod, or matmul member has signature Participant member(Participant, RHS). The right operand is converted to RHS. Prefix and postfix ++/-- use add or sub with the integer 1 converted to RHS.

The lvalue is evaluated once. Its current value is passed to the member once, and the returned Participant is stored once. Compound assignment and prefix forms return the stored value; postfix forms return the original value. Plain = and the identity operators === and !== are not overloadable.

Dynamic compound assignment

Native-only compound assignment remains native C. If a numeric compound assignment involves Var, the compiler takes the address of an addressable lvalue once. The runtime loads its current value, performs the dynamic operation, converts the result to the declared target family, and stores once only after every step succeeds. The expression result is that converted value. A failed conversion, divide, remainder, or shift leaves the target unchanged.

This rule covers native scalar numeric and Var lvalues, including C indexing and member access. The compiler selects a typed adapter from the resolved storage family; plain char and signed char remain distinct storage types even though both box as <i8>. Enum and bitfield targets are excluded.

String-tagged Var values accept += with String or raw C string operands. Native String lvalues accept the same += spelling as concatenate-and-rebind. Concatenation finishes before the binding is changed.

Array and Map elements support all ten numeric compound operators and prefix/postfix ++/--. The runtime performs the element read, operation, stored-tag conversion, and write in one call. A missing Map key or out-of-range Array index fails without insertion, growth, or mutation. Numeric += is the Map exception. A missing destination key is inserted with the right-hand side as its initial value, as though the prior value were numeric zero, and the inserted value keeps the right-hand side’s numeric tag. The read, modify, and write happen in one call; that is not a thread-safety guarantee.

Additive initialization does not make void numeric. A missing or void right-hand side still fails, as do nonnumeric += and every other compound operator when the destination key is absent. Successful insertion is a structural Map change and may invalidate outstanding traversal state.

A direct, optionally parenthesized Array or Map indexed right-hand side uses one typed cross-container helper. The source value is captured before the destination is committed, including same-container and same-slot cases. A cast or larger expression reads the source and then performs one destination update. Each base, selector, and value expression is evaluated once, and C’s operand evaluation order remains unchanged.

Dynamic conversion, operators, and updates do not have parallel error-code APIs. A failure raises its specific cause through the ambient Error channel. When a handler consumes that Error, a value-producing operation returns its documented sentinel and an update leaves its target unchanged. The sentinel says that no result or mutation was produced and does not encode why. <alloc-fail> and <size-limit> are exceptions: they may transfer to a matching filtered catch, but never return a sentinel or continue the update.

The try_* prefix remains for status results whose payload alone cannot represent every successful result. Examples include Map.try_get for presence, Iter.try_next for exhaustion, String.try_long for parse success, and match/search operations for no-match. Those integer results answer whether a result exists or an operation applies. Failure causes still use the ambient Error channel rather than a status Symbol or error out-parameter.

Indexing and slicing

Native C arrays and pointers retain C indexing. Array, List, String, and Map also define indexed access.

• Array, List, and String accept negative indices.
• An out-of-range Array or List read returns void.
• An out-of-range String read returns -1; its indexed result is a byte represented as an int, not a one-byte String.
• A missing Map key returns void through get and bracket reads; Map.try_get reports presence separately.
• Array literal elements cannot be void; counted construction enforces the same invariant as Array.push.
• Map literal keys and values cannot be void; counted construction enforces the same invariant as Map.set.
• Array and Map indexed assignment are supported.
• Array and Map indexed compound assignment and prefix/postfix ++/-- are supported as single-call updates.
• Numeric map[key] += value initializes an absent key from value; other indexed updates require an existing destination.
• List indexed assignment is not supported.
• String indexed assignment is not supported: String is immutable, and an in-place write would corrupt every equal String sharing its canonical storage. Use the copy-producing String.withindex result, or bind a transient String.malloc buffer to a char * and write that natively.

The optional typed families have different indexing rules:

• A packed Array from typed-array.x has a raw bracket: reads, writes, and compound updates index a concrete element pointer with no null test, no bounds test, and no negative-index normalization. An index outside the elements is undefined as it is for the equivalent C pointer. try_get is the checked read, and it does normalize a negative index.
• A packed Map from typed-map.x adopts protocol Var, so its getindex, setindex, updateindex, and postfixindex members provide bracket reads, writes, compound updates, and numeric postfix updates. A typed cons chain from typed-list.x does not adopt protocol Var; use car and nth_cdr.

Array, List, and String support value[start:stop:step]. Bounds and step may be omitted. Negative bounds and reverse steps are normalized consistently. A zero step is invalid.

List indexed updates and String character updates remain unsupported. Array-level and Map-level += are also unsupported; update an element instead of the container binding.

Iterator destination omission

Iterator sources and lazy operations take a final Iter destination pointer. That argument may be omitted for calls nested in an iterator expression that is consumed immediately by try_next, next, done, list, array, foldl, any, all, find, count, sum, product, min, max, or foreach.

For every missing destination, x2c passes a distinct zero-initialized struct Iter compound literal. Its automatic lifetime is the enclosing block, so every source remains valid while the final consumer runs. Explicit final destinations are preserved, including a mixture of explicit and omitted destinations in one chain. Calls nested in iterator-valued arguments, such as both inputs to zip or map2, are completed recursively.

This is specific to iterator destinations, not general default-argument syntax. An iterator assigned to a local, returned from a function, boxed, or passed to an arbitrary call still requires explicit storage at every stage. unzip also remains explicit because its two result iterators share one caller-owned UnzipShared buffer.

Lambdas

The literal forms are %!(parameters) => expression and %!(parameters) => { statements }. An optional using &name, &other clause between the parameters and => captures those surrounding bindings by reference.

An expression body parses through assignment precedence. An unparenthesized comma separates arguments of an enclosing call; write (first, second) when the comma expression itself is the lambda body.

Current guarantees:

• an expression body produces its value; a native C void expression runs once and produces void;
• a block body accepts statements, including declarations, control flow, defer, and nested lambdas. return expression; converts the result to Var; bare return; and fallthrough produce void;
• bare parameters are Var values;
• nullary and multi-parameter forms work;
• unlisted automatic values referenced by the body become read-only snapshots when the lambda is created, provided their types convert to and from Var;
• assignment, updates, taking a captured binding’s address, and passing it by reference require using &name. Explicit readers and writers share the original binding; adding another lambda cannot change a snapshot;
• globals remain directly accessible.

int value = 1;
Func read = %!() => value;
Func bump = %!() using &value => ++value;
value = 2;
printf("snapshot=%ld shared=%ld\n", read().integer(), bump().integer());
// snapshot=1 shared=3

Clause names resolve in the surrounding scope. Parameters and local variables still shadow them. Repeated entries are redundant, and an entry unused by the body creates no capture.

Typed parameter syntax retains the complete parameter declarator. A parameter such as int &value aliases its caller’s lvalue just as it does in a function; a dynamic Func call checks the source type and qualifiers before passing the address to its generated adapter. Value parameters are evaluated once and boxed, while reference parameters take the lvalue’s address without first reading it.

A noncapturing lambda remains a generated C function and can adapt to a supported C callback type, including int (*)(int), in an initializer, assignment, argument, or return. A local typedef of the callback type has the same behavior. Parentheses around the lambda preserve this adaptation. Where a Func is expected, a fixed nonvariadic function or function-pointer value converts implicitly when the Func conversion supports its parameters and result. Value parameters and results need a lossless Var conversion, and reference parameters retain their typed lvalue address. A direct function or noncapturing lambda has one file-static Func handle that every conversion reuses. A function-pointer expression is evaluated once and its exact pointer is copied into a new Func; later assignment to the source pointer does not retarget it. A null function pointer instead produces null Func without allocating a binding. Variadic functions do not convert implicitly; use the advanced Func.new_rest API when a native operation consumes a rest List.

A capturing lambda has static type Func; calling it directly returns Var. The same is true after a noncapturing lambda converts to Func. Successful effect-only calls and explicit void results produce void through either route. Func.apply preserves that no-value result. A value parameter declared as Var may receive it; a concrete typed value parameter rejects it. Rest bindings reject it before constructing their argument List, since ordinary collections exclude void. A Func cannot be passed as a context-free C callback because that ABI has nowhere to carry its captured values. List, Array, String, and Iter higher-order methods accept Func instead, so they can use captured callbacks without a second API.

Each snapshot conversion executes once, in body first-use order, when the Func is constructed. A reference capture uses a shared typed cell allocated where the original binding is declared, preserving initializer order and single evaluation. Calling the Func allocates no capture storage.

A default capture of an outer reference parameter snapshots its current referent. using &name retains the caller’s alias without another cell. Reference captures retain the source’s qualifiers: capturing a const object by reference does not make it writable.

Nested lambdas capture from their enclosing lexical environment. Sharing an original variable requires using &name at every enclosing lambda. An inner reference clause cannot reach through an enclosing snapshot. A nested snapshot records the value when that inner lambda is constructed.

Capturing a pointer, Array, or Map copies its pointer value. The binding is read-only, but its pointed-to contents remain mutable; later rebinding the original variable does not retarget the capture. An aggregate without Var conversions cannot be captured by value; capture a pointer or explicitly capture the aggregate by reference.

Captured values and cells remain valid only as long as their owning Scope. Caller objects and pointer-backed contents keep their existing lifetimes; reference capture extends neither and adds no synchronization. Reused direct function handles have file-static lifetime.

Statements

C control flow

x2c accepts C-style if, switch, while, do, classic for, labels, goto, return, break, and continue statements.

System block decorators

The built-in macro pack installs $scope, $let, and $lock without a per-source import. They retain the normal runtime declaration requirements and macro collision policy. None has a bare keyword alias.

$scope() retains one region around its following statement and defers release inside an inner block containing that statement. $scope(pointer) evaluates the Scope-pointer expression once, pushes that destination, and uses the same inner-block placement for a deferred pop. Pop restores the previous destination without destroying the selected Scope. More than one argument is an invocation error. A decorator around a loop creates one region; a decorator around its body creates one per iteration.

$let(place, value) captures the address of the place once, saves its value, registers restoration, assigns the new value once, and runs its body. The place must be addressable and assignable, and its storage must outlive the body. Restoration uses the captured address even when later changes would cause the original expression to name different storage.

$lock(mutex) evaluates a Mutex expression once, calls lock, then defers unlock around its body. A failed acquisition registers no unlock. These forms add ordinary blocks and defers without hidden loops; break, continue, return, and error transfer retain their ordinary enclosing boundaries.

See Classes and System Macros for examples and expansions.

With

with expression [as name] { ... } gives an expression a short lexical name. The name defaults to _:

typedef struct Point { int x, y, z; } Point;
int main(void) {
Point point = { 0 };
with point {
  _.x = 1;
  _.y = 2;
  _.z = 3;
}
  return point.x == 1 && point.y == 2 && point.z == 3 ? 0 : 1;
}

The expression may be any x2c expression. Each use acts as a parenthesized copy of that expression. A call used twice is called twice, and an unused expression is not evaluated. with does not introduce a hidden runtime temporary or promise single evaluation.

The name is available only in the required braced body and only in expression positions. It does not replace field names, labels, declaration names, type syntax, or literal atoms. A declaration of the same name shadows it from that declaration onward.

with nests lexically. An inner use of the same name shadows the outer one, and the outer meaning resumes after the inner block. Naming the outer expression keeps it available through an inner default shorthand:

typedef struct Point { int x, y; } Point;
typedef struct Pair { Point left, right; } Pair;
int main(void) {
  Pair pair = { 0 };
with pair.left as left {
  with pair.right {
    _.x = left.x;
  }
}
  return 0;
}

At the beginning of a statement, with always introduces this construct. It remains a contextual identifier in declarations and other expression positions. A statement that calls a function named with uses the spelling (with)(arguments);.

Foreach

foreach(declaration, expression) statement evaluates the expression once and visits its elements. The declaration has no trailing semicolon and may bind one name or destructure a key and value:

int main(void) {
  List values = %(1 2 3);
  Map map = {1: 10, 2: 20};
  int total = 0;
foreach(int value, values) total += value;
foreach(int key, map.keys()) printf("%d\n", key);
foreach(Var (key, value), map)
  printf("%ld=%ld\n", key.integer(), value.integer());
  return total == 6 ? 0 : 1;
}

Cursor-backed collections use their typed try_next member directly. Other values convert to Iter, and each yielded Var converts to the declared loop type when that conversion exists. Iteration covers the loop forms and the Iter protocol in tutorial order.

Foreach uses Iter.try_next. Successful payloads exclude void, which is the terminal sentinel returned by Iter.next. A boxed Var without a registered iterator adapter produces an already-exhausted iterator. A receiver with a statically known type and no visible exact or inherited Iter conformance is rejected as not iterable.

Match

match (expression) { case pattern: statement ... default: statement } evaluates its subject once and executes the first matching case. Pattern matching introduces the pattern language with worked examples.

Patterns use List-literal notation. ? and * are anonymous wildcards. Named binders are ?IDENT and *IDENT, where IDENT is [A-Za-z_][A-Za-z0-9_]*. Binder keys are canonical Atoms, so long and case-sensitive identifiers work in recursive, prepared, and compiled match paths. A sigil-leading Atom with any other suffix is a malformed pattern: recursive matching fails, MatchPlan reports binder-name, and compiled match syntax reports a positioned diagnostic.

Match operators and predicate names are compact Symbols. The ?binder?, *binder?, and !op? spellings are reserved control vocabulary only in their !is predicate operand positions; they are not named binders. Nested List patterns, literal comparison, default selection, and the !not, !or, !and, !set, !quote, and !is forms are supported. break exits the match; continue targets an enclosing loop.

Runtime-built patterns may interpolate an interned Match operator in head position and retain the literal operator’s semantics. Source match arms require literal operators so the compiler can prove binder availability. Named binders under !not are not definitely assigned; binders under !or or membership-style !set must occur in every alternative; !quote is opaque. Arm binders are semantic Var or List locals and support method syntax.

?(Type name) declares a native typed capture. Its exact Var tag must match the tag tested by value is Type; mismatches fail the pattern without conversion. The type applies to every unquoted occurrence of that binder in the arm, including ?name and alternative branches. Repeated names retain their equality constraint. The shorthand lowers to existing !is predicates and ordinary local declarations; explicit !is captures remain Var locals. The opener ?( is adjacent; ? (String text) is a wildcard followed by a sublist pattern.

An arm may place if (expression) before its colon. The expression runs after matching, with captures visible, and uses ordinary truth conversion. False tries the next arm; errors propagate normally. A successful guard runs the body once. Capture scopes and the existing break, continue, and cleanup rules apply to guarded arms too.

Errors and cleanup

try requires a following filtered catch, finally, or both.

raise %(CODE (KEY VALUE)...); records one structured Error. CODE and every KEY are bare Symbols read by this syntax; each VALUE is one expression. Values are restricted recursively to Null/nil, numeric and enum values, Symbols, Atoms, Strings, and Lists of permitted values. void, pointers, mutable containers, resources, custom objects, and other identity-bearing values are invalid. Statically known violations are compiler errors; invalid contents supplied dynamically through Var reach Error’s <bad-types> raw floor. A try may have adjacent catch arms:

try block.reserve(n);
catch %(alloc-fail * (bytes ?count) *): return 0;
catch %(bad-arg *rest): report(rest);
catch: return -1;

The newest Error is matched as %(CODE @DETAIL). Filtered arms use the same pattern and binder rules as match; ?name declares a Var, *name declares a List, and the first matching arm runs. A bare catch: is the optional default and must be last. Every filter expression is evaluated once when the try is entered.

Selecting a filtered arm consumes the errors accumulated since that arm was registered and transfers through each intervening cleanup frame. Its finally and defer cleanup runs before the selected arm. A finally body may not define a label, because its statements are repeated on each path that leaves the region. The transferring registration is removed before the arm executes, so raising a replacement Error continues outward instead of re-entering the same arm. When no arm matches, the Error continues outward unchanged. Catch bindings are borrowed through the selected arm and must be copied with Error.snapshot to outlive it.

Every cause in the shared table never returns to its raising call. Error keeps their policies at <abort> and observing handlers cannot consume them; only a matching filtered catch transfers control. For a literal raise of one of them, generated C places __builtin_unreachable() after the runtime raise call so C control flow has the same rule. Errors and Cleanup lists the table.

The defer statement schedules the statement for the current block exit. Multiple defer statements unwind in last-in, first-out order. Cleanup runs for normal scope exit, return, goto, and Error transfer, all the way out to the function boundary. break and continue unwind cleanups only up to the innermost enclosing loop or switch (whichever the jump targets) and stop there; a defer or cleanup frame registered outside that boundary is left for a later normal exit, return, or Error transfer to reach. The errors and cleanup chapter shows how the two are combined.

A return expression is evaluated and saved before its cleanups run; the saved result is returned afterward. A goto within the same cleanup ancestry runs no cleanup. An outward goto runs every cleanup region it exits. A goto into a protected cleanup region, or into a sibling protected region, is rejected at compile time.

Generated Error transfer preserves the automatic locals and parameters a protected body modifies under the repository’s optimized build, whether the body assigns them by name or writes through a pointer it holds the address in. The compiler supplies the required volatile C representation for those values and for the transfer state its frames carry; source code does not need optimization-specific qualifiers for ordinary assignments in try, catch, or finally. Error transfer does not restore the process signal mask; code that changes a signal mask owns restoring it.

Type-owned initialization

A translation unit may define one top-level initializer with the exact signature void TYPE.initialize(void), where TYPE is a typedef name. The compiler calls it lazily at every non-static function boundary and guards it so direct or recursive calls still execute its body once. Static functions are internal helpers. They trust a non-static entry point or the initializer that called them and do not repeat the generated guard.

Compiler-owned literal and static-runtime initialization runs after the guard is set and before the method body. This makes calls from the initializer back into static helpers in the same translation unit safe. Translation units that need only literal caching retain a private synthetic initializer.

Other initialization statements and runtime-valued static assignments belong in the method body. Eligible file-static percent literals use the generated sequence described under Values and literals. Top-level decorators are rejected.

Type-owned shutdown

A translation unit may likewise define one top-level shutdown function with the exact signature void TYPE.shutdown(void). The compiler registers it once through Scope.shutdown_hook when that unit initializes. When the unit also defines TYPE.initialize, that guarded function registers it after its complete generated initialization sequence; otherwise the unit’s private synthetic initializer registers it.

Shutdown hooks run in reverse registration order. A type initializer that acquires process-lifetime resources therefore registers its matching shutdown only after acquisition succeeds. Calling TYPE.shutdown directly still passes through the unit’s initialization guard.

Types and conversions

x2c accepts normal C type forms plus runtime types such as Var, List, Array, Map, String, Symbol, and Iter.

Typedef declarations are supported at file scope and inside compound statements. Local aliases follow lexical scope and shadowing. Their uses are resolved while that scope is available, preserving the existing meaning of file-scope types, including their methods and converters. Local typedefs stay inside their C blocks and are not exported. A locally defined aggregate also stays in its block; it cannot supply a type to a lambda helper lifted outside that block.

Direct and chained file-scope aliases of Var behave like Var in boxing, extraction, initialization, assignment, function arguments, returns, and comparisons. Declarations and signatures retain the source alias. This rule is specific to Var; other file-scope typedefs gain only the methods and converters declared by their own ancestry.

A typedef and the type it names may substitute for each other in either direction. An Array can therefore be used as a Block, and an Ast as a List, without conversion. Two typedefs of a common type cannot substitute for each other this way: they may describe different contents despite sharing a C representation. Thus ArrayInt counts = someArrayDbl; is a type error that names the required converter. Declaring that converter, as lib/typed-array.x does for Array.arrayint, permits the conversion; a cast still permits reinterpretation.

The compiler warns with unnecessary conversion when source spells a conversion that its destination already performs. Translation continues.

A cast is reported when its operand already has the cast type, qualifiers included. The comparison uses the declared x2c type, so casts between a typedef and its underlying type, or between two typedefs of one C type, are not reported. Neither are (void) casts, or casts of an operand whose C type x2c does not track, such as a pointer difference or a character constant. A cast of a C string literal is not reported either: it is how source keeps the literal native where x2c would otherwise promote it to a String, so removing it changes what the surrounding operator does.

A converter call is reported when its destination would make the same call. A converter is a method that takes only its receiver and is named for its result, with str for String. The destinations are the value of an initializer, an assignment, a return, a declared call argument, an interpolation hole, and a Var value that a printf-family format consumes. So String name = sym.str();, f(x.var()), and printf("%s", v.str()) are reported. A printf-family value is a destination only where the format is a literal the compiler reads; a computed format, such as a const char * variable or a name an object macro defines, converts nothing. The destination makes the same call when either side is Var, both types share one C type, or the receiver declares the converter. A method receiver, an operator operand, and a parameter with a qualifier the result lacks, such as const char *, are not destinations.

These explicit calls differ from the implicit crossing and are not reported:

• .str() on a Var at a typed destination, and any other converter call on a Var in an interpolation hole or a printf-family value. Holes and formats render a Var through Var.str, which displays any value. The implicit crossing to String reads the String payload and yields an empty String for any other tag.
• A Var read into a numeric type other than Symbol, such as v.int() or v.integer(). The implicit crossing calls Var.convert and then reads the result. Var.int already converts, and Var.integer returns 0 where Var.convert raises.
• A reader other than str into String on another type, such as File.string. The implicit crossing calls the type’s str converter.
• A call bound from macro-constructed syntax, and a call inside the function that implements the crossing, such as value.list() inside Var.row for a List typedef Row.

Supported primitive C specifiers are order-independent and normalize to one compiler spelling. For example, double long becomes long double, and long unsigned long becomes unsigned long long. Invalid combinations such as long float are structured type errors at the original source token. Numeric literal radix, magnitude, and suffix determine the annotated native family; integer promotions and the usual arithmetic conversions then operate on that canonical identity. A literal beyond the supported native integer families is a structured type error rather than a mismatched variadic value.

Conversions remain context-sensitive outside the numeric domain. A source expression may be boxed to Var, converted through an established target conversion, or rejected. Scalar typedefs retain their declared annotation but use the underlying scalar family for arithmetic and conversion to or from Var.

A converter is the source method named for its target: Source.target for a plain target and Source.str for String. Lookup uses the source type’s exact converter when it declares one; otherwise it walks the source’s typedef chain and uses the nearest converter declaration. Thus a typedef List Row may be assigned or interpolated as a String through List.str without a forwarding Row.str. The generated call still names List_str, and direct C calls retain the converter’s declared ABI. Lookup stops without a call when the target itself occurs in the chain, since typedef identity already handles that crossing.

Type qualifiers take part in that decision. const, volatile, and restrict are retained on the declared type of a function result, a global object, a record field, and a local, including one imported from a C header. Handing such a value to a target that is the same type without one of those qualifiers is a structured type error, because that conversion passes the same address on unchanged. A conversion that copies through a converter is unaffected: const char * still becomes a String through String_new. A qualifier on the value being copied, as opposed to what it points at, is not part of the comparison, so char *const converts to char *.

A pointer to void is held to the same rule even though its base type differs from the source’s, because it also passes the same address on unchanged. void * therefore does not accept a const char *; const void * does.

Host preprocessing

When preprocessing is required, x2c passes the source pathname and every include directory to the host cc as separate argv elements. Spaces and shell metacharacters in paths are data, not command syntax. The host process receives the source path, so quoted includes and its diagnostics retain source-file context.

The active preprocessed stream is shallow-parsed only to establish the global environment. Full parsing, diagnostics, and emitted source still come from the original token stream. Directives remain AST nodes in source order at top level and inside compound statements. This includes a trailing directive before }; a directive between if (...), else, while (...), for (...), do, switch (...), defer, try, catch ...:, finally, a match arm’s :, or a statement macro such as foreach and the statement it governs; and a directive before the else, do-while while, catch, or finally that continues a statement. A conditional group opened there also takes the statement of each later arm and the closing directive, so foreach keeps a group of one statement per arm inside its loop. A later statement in the same arm follows the governed statement, as in C. Directives between match arms stay between those arms, so an arm inside a conditional group is present exactly when C compiles the branch that holds it.

An include that x2c cannot resolve remains in the emitted C. Translation without host preprocessing can therefore succeed with an active missing header; native compilation rejects it. Explicit host preprocessing also rejects an active missing header. A missing include in an inactive branch such as #if 0 does not prevent compilation.

This is not full preprocessing of x2c source: the original tokens must still form syntax that x2c can parse. Macro expansion that supplies grammar, or inactive branches containing otherwise unparseable source, can require adjustment even when the host C compiler accepts them.

A C source file renamed from .c to .x is an x2c translation unit. A C header stays a .h file reached with #include; x2c collects its declarations and the native compiler reads it from the generated C.

Every branch of a conditional is parsed except the branches C never compiles. x2c output is compiled as C by a GNU-style compiler, so the branch under #ifdef __cplusplus, #if defined(__cplusplus) alone or first in a && conjunction with no ||, and #ifdef _MSC_VER or #if defined(_MSC_VER) likewise, the #else branch of #ifndef __cplusplus or #if !defined(__cplusplus), and #if 0 are skipped: their tokens are trivia, and the directives around them stay in place and are emitted. A function defined in two arms of one conditional is one definition. At file scope, extern "C" { opens a linkage group and a } closes it; the group’s declarations belong to file scope, and its braces are not emitted. Any string literal is accepted as the linkage name. extern "C" before a single declaration is read as extern.

A unit or a collected header may place a macro before or among a declaration’s specifiers. The macro’s definition determines what the name contributes: nothing for an empty body or an attribute (#define RLAPI, #define WEAK __attribute__((weak))), its storage class for static, extern, or inline (#define JSMN_API static), builtin type words for a body such as signed int, and, for a body that is the name of another prefix macro, that macro’s reading. A function-like macro whose body is its parameter amid such prefixes wraps a type: in CJSON_PUBLIC(const char *) f(void); the type is the one inside the parentheses. A macro whose words are a storage class reads as that storage after the type as well, as in int LOCAL f(void). Where a name is defined differently in several conditional branches, a static definition takes precedence, then any prefix without a qualifier, then a prefix with one, such as zlib’s z_const, which is const in one branch and nothing in another. A name defined to any other text is a typedef name.

A GNU attribute or a function-like attribute macro after a declarator or parameter, int a __attribute__((unused)) = 1, b = 2; or int f(int x __attribute__((unused)));, is kept as text after that declarator and applies to it alone, as in C. An attribute on the prototype of a function the unit defines is written before the type on both the prototype and the definition x2c generates. Attributes are not part of the signature compared between a prototype and its definition. A definition without static after a static prototype keeps the prototype’s internal linkage. __inline, __inline__, __restrict, and __restrict__ are the standard keywords.

in and match are keywords only where their x2c forms can occur: in between two operands, and match as match (...) followed by case or {. Elsewhere both are identifiers. A field of a foreign struct whose type x2c cannot resolve can be indexed; the C compiler alone types the result.

A public struct tag { ... } name; publishes the tag body and extern struct tag name; in the header and defines name in the source. A public prototype that uses struct tag is preceded in the header by struct tag; when the header has not declared the tag. A function body that follows the declarations keeps the conditional arm it was written in. It is emitted before a later #undef and before any conditional group that contains one, so the macro definitions in effect where it was written apply to it.

A failed host preprocess prints its captured stderr, reports a structured x2c driver diagnostic at the first directive, and exits nonzero. Partial host stdout is never parsed after failure. --no-cpp bypasses this discovery pass; --dump-cpp-text exposes the successful host output.

Diagnostics

Command-line options, including the dump flags that expose an individual phase and the include and output directory switches, are listed in compiler options.

Translation stops a unit after 20 errors by default. Compiler diagnostics describes --max-errors and the line that reports the stop. Parsing recovers at top-level declarations. A rejected declaration is skipped whole and parsing resumes at the next one, so independent errors in separate declarations are reported together in source order, and one declaration contributes at most one error. Tokenization, symbol collection, transformation, generation, and emission stop at their first error. Warnings do not count toward the bound, and a report identical to an earlier one is not repeated. --diagnostics-file writes the same diagnostics as JSON Lines; the command-line reference describes the fields.

Locations retain file, one-based line and column, token length, and absolute byte position. The source renderer uses length for the caret width.

Region warnings

Three codes come from the region check described in Scopes and Lifetime. Each is a warning: translation continues and the program still compiles.

The check analyzes regions lexically and summarizes each function within its own unit, so a unit gets the same warnings whatever else is translated with it. For calls into another unit, the check uses only a fixed table of runtime operations. It does not cover storage from plain malloc or a C library, raw pointer arithmetic, values reached through a field of a stack struct, callbacks, or Context regions.