7.13.10 Entry Point Macros
space |
definition | ||||||||||||||||||
| ||||||||||||||||||
|
An entry-point macro works in two modes, where the symbol provided as mode_id indicates the mode:
#'arity: gets an encoding of the arity that the generated function will have, not counting any extra arguments that might be added through an adjustment. The encoding for an arity is explained below. The adj_id specified by ~adjustment is bound to #false. This mode of expansion is sometimes used before the #'function mode.
#'function: gets a function to implement the entry point. The result can be another entry point, or it can be a procedure 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 shuld 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.
entry_point.macro 'identity':
~mode mode
~adjustment adj
match mode
| #'arity:
[2, [], []]
| #'function:
)
class | |||||
|
Represents an adjustment to an entry point to add extra arguments and 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.
function |
|
function |
|
function |
fun entry_point_meta.pack_arity(arity :: False || Int || List) :: Syntax |
|
function |
fun entry_point_meta.unpack_arity(stx :: Syntax) :: False || Int || List |
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_arity and entry_point_meta.unpack_arity functions similarly handle encodings of entry-point arity results. An entry point macro should not explicitly pack its result with entry_point_meta.pack_arity, but these functions can be useful when using the entry_point_meta.Arity syntax class.
Analogous to expr_meta.Parsed, but for entry points to run in either #'function mode with entry_point_meta.Parsed or #'arity mode via entry_point_meta.Arity.