17.9 Annotation Macros🔗ℹ

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

> 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 and Static Information 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.