18.8 Binding Macros🔗ℹ

A compile-time value that identifies the same space as bind. See also SpaceMeta.

See Binding Low-Level Protocol for examples using the low-level protocol.

Packs binding information that is represented by a syntax object with two parts: infoer_id and data, combined in the form

'(infoer_id, data)'

The infoer_id identifier must be bound to a transformer with bind.infoer, and data is propagated to that transformer to get initial binding information and further “continuations” for generating matching and variable-defining forms.

The representation of packed information as a syntax object is unspecified and meant to be opaque.

See Binding Low-Level Protocol for more explanation and for examples.

The inverse of bind_meta.pack, normally used only internally in the expander.

See Binding Low-Level Protocol for more explanation and for examples.

Packs binding information that specific to a use of a binding form, which means that “upward” has been provided to an infoer, and the infoer converts that to initial information about bindings plus “continuations” to generate the matching expression and variable definitions.

The syntax object stx must have the following shape:

'(ann_string,

name_id,

((static_key, static_value), ...),

((defined_id,

[var_use, ...],

((var_static_key, var_static_value), ...)),

...),

matcher_id,

evidence_id_tree,

committer_id,

binder_id,

data)'

The ann_string term is for error reporting when a value fails to match the binding. It describes the binder’s match requires in the form of an annotation.

The name_id term is for error reporting and reflection in the sense that it is used as the inferred name for a value matched to the binder, in case such a name is relevant.

The static_key–static_value pairs describe “upward” static information for anything that successfully matches the binding. The “upward” information can be useful to an enclosing binding form.

The defined_ids are the identifiers that are ultimately bound by the binding form. Each identifier to be defined has associated uses through var_use values, and each identifier has “downward” static information through the var_static_key–var_static_value pairs. Like var_static_keys, the meaning of var_uses is up to cooperating parts in general, but two shapes are recognized by built-in forms:

• ~repet (sequencer, ...) indicates that the variable can be used as repetition at a depth corresponding to the number of sequencers, and also as an expression if the number sequencers is zero;

• ~no_let indicates that the variable’s is not compatible with let, because it needs to be bound early (such as through when); and

• ~extends ns_id indicates that the variable is bound as an extension of the namespace ns_id.

The matcher_id, committer_id, and binder_id identifiers provide the “continuation” of the binder’s expansion to generate a matching expression and a definition sequence. Each identifier in evidence_id_tree should be defined in the output of match_id; a tree with the same shape as evidence_id_tree, but with each identifier potentially replaced by a different one, is provided as input to committer_id and binder_id.

The data term is propagated to the use of matcher_id, committer_id, and binder_id, providing a communication channel from an infoer to a matcher and binder.

The representation of packed information as a syntax object is unspecified and meant to be opaque.

See Binding Low-Level Protocol for more explanation and for examples.

The inverse of bind_meta.pack_info, which is useful for unpacking information about the expansion of nested binding forms as produced by bind_meta.get_info.

Initiates the expansion of the binding form represented by bind_stx in a context that supplies the “upward” static information represented by static_info.

Static information is represented by a syntax object that has the following shape:

'((key_id, val), ...)'

The result is a syntax object that represents the initial expansion of the binding form as a packed syntax object, whose form is unspecified and intended to be opaque. Use bind_meta.unpack_info to convert the packed syntax object and expose information about the binding’s expansion.

See Binding Low-Level Protocol for an example.

Takes the initialized binding-form expansion produced by bind_meta.get_info and reports whether the binding is immediate in the same sense as just a variable: the binding always matches, and no work is required to convert or unpack the matched value.

When using a matcher unpacked via bind_meta.unpack_info, the group given for success_pattern can be an immediate block formed with : (without a preceding term), and in that case, the groups of the block are spliced into a definition context where the binding is used.

See Binding Low-Level Protocol for more explanation and for examples.

The definitions produced by a committer should not use identifiers supplied by a user of the binding form, because those names will not be adjusted by let. Instead, those definitions should be deferred to the binder function’s result.

See Binding Low-Level Protocol for more explanation and for examples.

The definitions produced by a binder should not refer to each other, because they may be adjusted by let expansion. Bindings that need to be referenced by generated bindings should be in the committer function’s output.

See Binding Low-Level Protocol for more explanation and for examples.

Analogous to expr_meta.Parsed, etc., but for bindings.

Matches forms that combine a binding with an optional keyword and optional default-value expression, like bind_maybe_kw_opt for fun.

• The parsed field holds a parsed binding form.

• The maybe_keyword field is #false if no keyword is present, otherwise it is a keyword syntax object.

• The maybe_expr field is #false if no default-value expression is provided, otherwise it is a group syntax object for the expression.

Matches a sequence of terms (possibly empty) for a result annotation, like maybe_res_annot for fun.

• The count field holds an integer for the number of expected results, or #false if no annotation is declared (i.e., any number of results is expected).

• The is_predicate field is #true if all annotations are predicate annotations, or #false if at least one of them is a converter annotation.

• The maybe_converter field is #false if no annotation is declared or if it is unchecked, otherwise it is a syntax object for a function expression; the resulting function expects count plus two arguments: each original result followed by a success function of count arguments and a failure function of zero arguments.

• The static_info field holds static information for the result (in unpacked form; see statinfo_meta.pack); when count is not 1, then static_info has a single key statinfo_meta.values_key whose value is (packed) static information for each value (see statinfo_meta.pack_group).

• The annotation_string field describes the annotation, which is useful for raising an exception when conversion fails.