lib/meta.x

The compiler surface a meta function calls.

Primary API

Functions

type_base_suffix

List type_base_suffix(List type)

Returns the suffix of type that begins at its typedef name or base keyword, sharing type, or NULL when it has none.

Source: lib/meta.x:427

type_declaration_parts

List type_declaration_parts(List type)

Returns (base modifiers) for reconstructing a declaration of type. Function modifiers hold parameter syntax, and modifier order retains C declarator precedence.

Source: lib/meta.x:457

type_name_error

String type_name_error(List type)

Returns the diagnostic for a type that names its type with an Atom other than a C type keyword, as %(String) and %(* Point) do, or NULL. A type name is a String, as in %("String") and %(* "Point"); neither a short Symbol nor a long Atom supplies that representation.

Source: lib/meta.x:440

Public types

Code

typedef List Code

Captured code parsed from source or produced by a quotation.

Source: lib/meta.x:60

Macro

typedef List Macro

A macro as a value: called to build code, or used in a Match case to recognize code and capture its parameters.

Source: lib/meta.x:54

Source

typedef List Source

A meta parameter declared Source receives, at a $ call, captured syntax with the source text it came from: ((text T) (file F) (syntax S)). Code.source_text and x2c_embed_text read it directly.

Source: lib/meta.x:72

Type

typedef List Type

Semantic type syntax with canonical List-pool lifetime.

Source: lib/meta.x:57

TypeInfo

typedef List TypeInfo

A meta parameter declared TypeInfo receives, at a $ call, the description of its argument’s type: ((name N) (kind K) (type T) (fields F) (methods M)). Read a part with List.assoc.

Source: lib/meta.x:67

Design notes

A meta function runs inside the compiler, so it can ask the compiler questions and build syntax for it to bind. This module declares those operations in x2c; the macro values a meta function applies and recognizes are in macrovalue/macrovalue.x. Code builds code with quotations ($!( ... ), $!{ ... }, $!T{ ... }) and %(...) Lists, so the surface declares no constructors.

The operations on a value are methods of the value’s type: Code, captured code, and Type, a semantic type. The rest are x2c_ helpers that have no captured receiver: the identifier check, the invocation site, embedded text, ancestry and placement, diagnostics, and the definition hashes. Compile-time Lisp names a method Owner.member, as in Code.binding_spelling, and a helper with each _ of its name as ., as in x2c.invocation.line. The semantics are specified under “Compile-time Lisp and imports” in the language reference.

Each operation is a bodyless meta prototype the compiler supplies. A meta function that reaches one, directly or through another meta function, is compile-time only: the compiler emits no run-time form for it and diagnoses a run-time call where it is written.

Three operations let a macro contribute code beyond its result. x2c_enclosing answers the initialized declarator, block item, function, or unit around the invocation, and x2c_place puts code after that declarator or block item, on the exits of its block, at the entry of its function, among the unit’s support declarations, or in its initialization, under the expansion’s transaction. x2c_binding_fresh returns a new binding, so placed code can declare a name that the result also refers to. $auto is built on them.

The library builds it as an optional module, but the prelude’s varops.x includes it for its own meta rows, so every unit sees its declarations. Include it explicitly where meta functions are written. Shared compile-time definitions use ordinary source includes.

Tests and examples

make verify (meta-comptime-only-call, meta-builder-compiler-only, and meta-literal-arguments compiler fixtures).