lib/macrovalue/macrovalue.x

Macros as values that build and recognize code.

Primary API

Functions

Macro_apply

List Macro_apply(Macro t, List values)

Applies a macro value to code values. The result is a pending invocation; inserting it into a program expands and binds it there.

Source: lib/macrovalue/construction.x:12

Macro_case_capture_at

int Macro_case_capture_at( MacroCaseSite *site, List code, Macro t, List names, MatchCaptureBuffer *published)

Recognizes code built by t for the case whose site is site, which may be NULL, and publishes the captures under names. A pattern that does not depend on the current call’s subject is prepared once and kept in the site; generated match code calls this for a macro-valued case.

Source: lib/macrovalue/recognition.x:27

Macro_case_enter

inline int Macro_case_enter(Var value, List *cursor)

Stores in *cursor the List a macro-valued case examines for value, beneath its source wrappers, and returns whether there is one. A List headed by another Symbol than a wrapper or expr is its own view.

Source: lib/macrovalue/macrovalue.x:95

Macro_case_own

inline int Macro_case_own(Var content)

Whether an expr node whose content is content is its own view: the content is not a List headed by an Atom, as a retained invocation’s is, or by the expr a template shell holds.

Source: lib/macrovalue/macrovalue.x:78

Macro_case_pattern

List Macro_case_pattern(Macro t, List names)

The pattern a macro-valued case compiles to; the compiler lowers a call of this to Macro_case_capture_at over the match subject.

Source: lib/macrovalue/recognition.x:12

Macro_case_root

int Macro_case_root( List code, Macro t, List names, int statement, List *cursor, MatchCaptureBuffer *published)

Starts a macro-valued case whose derived pattern generated match code tests in place. Returns 1 when code is a retained invocation of t and its arguments captured under names into published, 0 when code cannot match, and 2 after storing in *cursor the List the pattern tests: the view of code or, for a statement body, of the one statement a seq holds.

Source: lib/macrovalue/recognition.x:45

Macro_case_shape

List Macro_case_shape(Macro t, List names, List shape)

The pattern a macro-valued case compiles to when the compiler derived shape, the pattern the case tests, while compiling it. Generated match code tests shape in place through Macro_case_root when it can, and otherwise lowers a call of this as it lowers Macro_case_pattern.

Source: lib/macrovalue/recognition.x:19

Macro_case_start

inline int Macro_case_start(List code, Symbol head, List *cursor)

Starts a macro-valued case without Macro_case_root when code is its own view. head, the Symbol heading the derived pattern, is not a source wrapper or seq. Returns 2 after storing code in *cursor for a subject headed by head, 0 for an empty subject or one headed by another Symbol than a wrapper, expr, or seq, which cannot match, and -1 when Macro_case_root must decide.

Source: lib/macrovalue/macrovalue.x:64

Macro_case_symbol

inline Symbol Macro_case_symbol(Var value)

The short Symbol value holds, or 0 for any other value.

Source: lib/macrovalue/macrovalue.x:86

Macro_case_view

int Macro_case_view(Var value, List *cursor)

Macro_case_enter for a value that may be wrapped or may hold no List.

Source: lib/macrovalue/recognition.x:63

Macro_close

Macro Macro_close(Macro value, List captures)

Records the Macro values an anonymous macro captured where it was created, so applying it later applies the same children.

Source: lib/macrovalue/construction.x:7

Macro_pattern

List Macro_pattern(Macro t, List names)

Derives the Match pattern that recognizes code this macro builds, capturing each parameter under the given binder.

Source: lib/macrovalue/patterns.x:44

Macro

Macro.declared

Var Macro.declared(Var value)

Returns the name a typed quotation declares with a Name hole whose local holds value: the name form of an x2c_ident spelling or a String, or a binding as it is.

Source: lib/macrovalue/construction.x:66

Macro.inserted

Var Macro.inserted(Var value, int lifts, int expression)

Returns what a typed quotation inserts for one use of a hole whose local holds value, as a rebuild inserts it. An expression hole (lifts) takes a number, String, or Symbol as its literal. Where the code takes an expression (expression), a binding, an x2c_ident spelling, or a Name hole’s String becomes an identifier expression; in a Name hole’s member position, an x2c_ident spelling is its String.

Source: lib/macrovalue/construction.x:53

Macro.inserted_items

List Macro.inserted_items(List values)

Returns the items a typed quotation splices for an expression sequence hole whose local holds values: each number, String, or Symbol becomes its literal, as a spliced data List’s items do.

Source: lib/macrovalue/construction.x:74

Macro.matcher

MacroMatcher Macro.matcher(Macro shape, List holes)

Prepares repeated recognition without retaining subject-specific bindings.

Source: lib/macrovalue/recognition.x:72

Macro.matches

int Macro.matches(Macro t, List code, List holes)

Tests complete code against a macro and its hole patterns. Repeated recognition can retain Macro.matcher so the pattern is derived once.

Source: lib/macrovalue/recognition.x:97

Macro.number_literal

List Macro.number_literal(List result, List type, Var value)

Returns the literal expression of type result that holds value, a number of the scalar type type. An int value is its decimal literal; another number is its exact bits cast to type.

Source: lib/macrovalue/construction.x:137

Macro.number_type

List Macro.number_type(Var value)

Returns the C type of a number’s Var family, or NULL when value is not a number. An untyped integer is an int when it fits one.

Source: lib/macrovalue/construction.x:111

Macro.subject

Var Macro.subject(void)

Returns the table Macro.use_subject last set, or void.

Source: lib/macrovalue/patterns.x:14

Macro.typed

List Macro.typed(List type, Var value)

Returns what a typed quotation builds when its code is one hole whose local holds value: the inserted expression with the type type. A String typed String is a String literal.

Source: lib/macrovalue/construction.x:79

Macro.use_subject

void Macro.use_subject(Var rows)

Sets the (SPELLING BINDING) rows for global references and the (source-spelling BINDING SPELLING) rows for renamed local bindings in a compile-time call’s syntax arguments. A macro value’s free reference recognizes only the recorded global binding; with void it recognizes any binding of its spelling. The compiler sets these rows for each meta call and carries them through the helper.

Source: lib/macrovalue/patterns.x:22

MacroMatcher

MacroMatcher.matches

int MacroMatcher.matches(MacroMatcher &m, List code)

Tests code with the same source views and identity rules as a macro case.

Source: lib/macrovalue/recognition.x:83

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Macro

Macro.binder

Atom Macro.binder(Var binder, String projection, int sequence)

Returns the binder that captures one projection of the template hole whose binder is binder. Splice and construction projections are always sequences; return, declarator, and member projections never are; source, value, and expression follow the hole’s sequence.

Source: lib/macrovalue/patterns.x:109

Public types

MacroCaseSite

typedef struct MacroCaseSite { MatchCaptureSite match; MacroFixedSlots policy; MacroPublishing route; int ready; } MacroCaseSite

Holds one macro-valued case site’s prepared recognition for the process: the plan Match keeps, the slots of the macro’s fixed locals, and where each binder reads its capture. The compiler emits one zero-initialized static site per case.

Source: lib/macrovalue/macrovalue.x:41

MacroFixedSlots

typedef struct MacroFixedSlots { int count, slots[MACHINE_BINDER_MAX]; int names, name_slots[MACHINE_BINDER_MAX]; } MacroFixedSlots

Records fixed-local slots for distinct-identity checks and Name slots for member-spelling comparisons during recognition.

Source: lib/macrovalue/macrovalue.x:20

MacroMatcher

typedef struct MacroMatcher { Macro shape; List holes, pattern; } MacroMatcher

Retains a macro and hole patterns for repeated recognition. A pattern independent of subject bindings is derived once; contextual references are resolved against each subject. The caller keeps the source values alive as long as this record. Match plans use the active Match cache.

Source: lib/macrovalue/macrovalue.x:108

MacroPublishing

typedef struct MacroPublishing { int from[MACHINE_BINDER_MAX], fallback[MACHINE_BINDER_MAX]; int to[MACHINE_BINDER_MAX]; int count, binders, complete; unsigned long definite; } MacroPublishing

Records where each of a case‘s binders reads its capture: the slot of its internal binder in the pattern that captured, and its own slot in the case, which need not share the parameters’ order.

Source: lib/macrovalue/macrovalue.x:29

Design notes

A Macro is the canonical macrodef record of a definition. $name selects one and macro Kind(...) => ... creates one. Applying it returns a pending invocation the compiler expands and binds at the insertion site; naming it in a case derives a Match pattern from the same body. Generated code calls these operations by name, so the module is part of the prelude.

Tests and examples

make verify (macro-values, macro-sequence-case, and macro-slot-recognition compiler fixtures).