17.14.10 Entry Point Macros🔗ℹ

An entry-point macro works in two modes, where the symbol provided as mode_id indicates the mode:

• #'shape: gets an encoding of information about the to-be-generated function as a map. The adj_id specified by ~adjustment is bound to #false. This mode of expansion is sometimes used before the #'function mode.

  The map can have any or all of the following keys:

  • #'arity: The arity of the generated function, not counting any extra arguments that might be added through an adjustment. The encoding for an arity is explained below.

  • #'name: A symbol for the function’s name for error reporting and other run-time purposes.

• #'function: gets a function to implement the entry point. The result can be another entry point, or it can be a function implementation that is packed via entry_point_meta.pack. In the latter case, the function should be potentially adjusted with extra leading arguments and a wrapper for the body, where the adjustments are provided via a entry_point_meta.Adjustment value for adj_id. Adjustments might add a “self” argument for a method, for example, and wrap a body to bind names for direct access to object fields and methods.

The result of expansion in #'arity mode must be either #false, an integer, or a list of three elements. A #false means that the arity is not statically known. An integer value is an arity mask; for every bit set in the mask, the function can receives that many by-position arguments. A list value starts with an arity for by-position arguments, but also has a list of keywords that are allowed and a list of keywords that are required; the list of allowed keywords can be #false to indicate that any keyword is allowed. The context of an entry point may constrain the acceptable arities or use arity information for a more efficient expansion.

When the rule of expansion in #'function mode is packed via entry_point_meta.pack, the generated function should accept extra initial by-position arguments as listed in entry_point_meta.Adjustment.prefix_arguments(adj_id), and each result body (where the function may have multiple bodies in multiple cases) should be wrapped with entry_point_meta.Adjustment.wrap_body(adj_id). The wrapping function expects an arity encoding that is like the result for #'arity mode expansion, but specific to the body’s case within a multi-case function.

Represents an adjustment to an entry point to potentially specify a name (to be used for run-time reporting), to add extra arguments, and to wrap the generated function’s body. The wrap_body function expects an arity encoding (see entry_point.macro) and a syntax object, and it produces a syntax object. The is_method field indicates whether the existence of a leading argument should be hidden in error messages.

The entry_point_meta.pack function packs an expression for a function as a result for a entry_point.macro expansion, distinguishing it from an unpacked syntax objects that represents expansion to another entry point form. The entry_point_meta.unpack function is the inverse of entry_point_meta.pack.

The entry_point_meta.pack_shape and entry_point_meta.unpack_shape functions similarly handle encodings of entry-point shape results. An entry point macro should not explicitly pack its result with entry_point_meta.pack_shape, but these functions can be useful when using the entry_point_meta.Shape syntax class.

Analogous to expr_meta.Parsed, but for entry points to run in either #'function mode with entry_point_meta.Parsed or #'shape mode via entry_point_meta.Shape.