3.7 Annotation Macros🔗ℹ

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

In addition to the option forms supported by expr.macro, annot.macro supports a ~context option, which declares an identifier be bound to context information. Context is represented by a annot_meta.Context object, which records argument names that can be referenced by Any.like, for example. Normally, when nested annotations are parsed directly via annot_meta.Parsed and similar, the same context object should be passed along.

> annot.macro 'two_of($ann)':     'matching(List(_ :: $ann, _ :: $ann))'

> [1, 2] :: two_of(Number)

[1, 2]

> [1, 2, 3] :: two_of(Number)

::: value does not satisfy annotation

value: [1, 2, 3]

annotation: two_of(Number)

> [1, "x"] :: two_of(Number)

::: value does not satisfy annotation

value: [1, "x"]

annotation: two_of(Number)

The annot_meta.is_predicate function determines whether a syntax object represents a parsed predicate annotation. This function and annot_meta.unpack_predicate are potentially useful on the result of matching annot_meta.Parsed.

The annot_meta.pack_predicate function packs an expression for a predicate with static information into an annotation form as a syntax object. When the resulting annotation is applied to a value, it checks the value using the predicate, and it also associates the static information in statinfo_stx with the value. The given statinfo_stx is in unpacked form (i.e., statinfo_meta.pack is applied automatically).

The annot_meta.unpack_predicate function is the inverse of annot_meta.pack_predicate, returning two values: an expression and unpacked static information.

See Annotations as Converters for more explanation and for examples.

The annot_meta.is_converter function determines whether a syntax object represents a parsed converter annotation. This function and annot_meta.unpack_converter are potentially useful on the result of matching annot_meta.Parsed.

The annot_meta.pack_converter function packs a binding, a body expression (that can refer to bindings), and static information into a converter annotation form as a syntax object. When the resulting annotation is applied to a value, it uses the binding to determine whether the value satisfies the predicate, and if so (and if the converted result is needed), the body expression is evaluated to obtain the converted value. It also associates the static information in statinfo_stx with the converted value. The given statinfo_stx is in unpacked form (i.e., statinfo_meta.pack is applied automatically).

The annot_meta.unpack_converter function is the inverse of annot_meta.pack_converter, returning three values: a binding, an expression, and unpacked static information. The annot_meta.unpack_converter function will also unpack a predicate annotation, automatically generalizing it to a converter annotation.

See Annotations as Converters for more explanation.

A convenience function that parses stx as an annotation and returns just its static-information component in packed form.

A completed delayed annotation need not be declared in the same module or definition context, which is why annot.delayed_complete allows an id_name. See Namespaces form more information on id_name.

If a value is tested against a delayed annotation id before it is completed via annot.delayed_complete at run time, then an exception is reported. At compile time, attempting to use the static information associated id throws a syntax error until it is completed via annot.delayed_complete.

These forms should be used as last resort, because they inherently involve a side effect, and because that effect is potentially across module boundaries. When a module uses an imported delayed annotation, the run-time component of that delayed annotation might be initialized as a side effect of requiring some other module, which potentially makes the reference fragile. Delayed annotations are suitable for use inside a library that is implemented by multiple private modules that are aggregated into a single library as the public interface.

> annot.delayed_declare Forward

> class Posn(x, y)

> Posn(1, 2) :: Forward

Forward: delayed annotation is not yet completed

> block:     use_static     fun (p :: Forward): p.x

Forward: annotation static information needed before completed

> annot.delayed_complete Forward: Posn

> Posn(1, 2) :: Forward

Posn(1, 2)

> block:     use_static     fun (p :: Forward): p.x

#<function:fun>

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

Unlike expr_meta.Parsed, an optional annot_meta.Context argument can supply context information—including argument names that can be referenced by Any.like, for example.

Like expr_meta.relative_precedence and expr_meta.ends_parse, but for annotation operators.

An annot_meta.Context object represents the syntactic context of an annotation form. The argument_names map is empty and this_position is #false in the default context annot_meta.Context.empty.

The keys of the argument_names map are identifiers. An identifier received by an annotation macro typically must be “unintroduced” by syntax_meta.flip_introduce to find it in the map.

Each value in the map or in the this_position field is a positions, one of the following:

• An integer: An index of a by-position argument.

• A keyword: The keyword of by-keyword argument.

• A 2-element list with #'repet and an integer: A repetition that starts after the indicated number of arguments.

• A 2-element list with #'splice and an integer: A by-position splice that starts after the indicated number of arguments.

• A list that starts #'keyword_splice followed by any number of keywords: A keyword-splice argument that will not include any of the listed keywords, because those keywords have separate arguments.

Note that a function form’s argument may not all have names that can be referenced, so annot_meta.Context object does not necessarily represent all arguments to a function.

An annot_meta.Context object represents static information for actual arguments of a function call as passed to a bridge function encoded in a statinfo_meta.dependent_result_key value by statinfo_meta.pack_dependent_result.

The arguments list holds static information for the by-position arguments—at least, up to the point that an argument repetition or splice (of an unknown length) is encountered.

The keyword_arguments list holds static information for the by-keyword arguments, not including any keywords supplied through a keyword-argument splice.

The has_more_arguments and has_more_keyword_arguments fields effectively report whether arguments and keyword_arguments are an incomplete enumeration of actual argument due to repetitions and splices.