5.1 Syntax Objects in Macros🔗ℹ

Throws a syntax-error message concerning in_stx. If who is #false, it is inferred from in_stx. If message is not provided, the message is "bad syntax". If at_stx is provided, it should be something like an enclosed form of in_stx to provide extra context. Alternatively, at_stx can be a list of syntax objects, in which case all syntax objects provide extra contexts, least-specific to most-specific.

Returns the compile-time value of name, if available, in the space specified by in_space. If no compile-time value is available, then fail is called if it is a function of 0 arguments, otherwise fail is returned.

The default fail is a function that throws an exception.

Checks whether stx1 at phase phase1 refers to the same binding as stx2 at phase2 within the space reflected by in_space.

Checks whether stx1 and stx2 have the same name (as returned by Syntax.unwrap on an identifier, for example) and the same scopes at phase.

When stx1 or stx2 is a dotted name, then both must be dotted names where each dotted component has the same name and scopes.

Returns a symbol that corresponds to the binding of stx in space in_space and at phase phase. The result does not uniquely identify a binding, but two names that refer to the same binding will have the same symbol result.

Returns a syntax object like stx, but where scopes indicating that the syntax object is macro-introduced are flipped. The result is stx unmodified when not during the expansion of a macro.

Macro-introduction is detected by flipping scopes to the input of a macro, then flipping scopes on the macro’s result, so that the two flip operations cancel for any part of the macro’s input that is used in the macro’s output.

A macro can flip introduction to implement a non-hygienic expansion for an introduced identifier, but generally Syntax.make_id is more reliable for this purpose, because there can be extra scopes that differentiate macro-definition and use sites. Flipping introduction may also be helpful when a syntax object from the macro’s input is preserved through side channels, so that the added scope is canceled, or in unusual cases when checking for the originalness of a term with Syntax.is_original.

The syntax_meta.lift_expr_to_before function adjusts the current expansion so that expr_stx is added to a top-level definition before the current expression. Expansion of the new expression is forced immediately, and the result is an identifier that is generated for the definition and that will be bound to the value produced by the expression.

The syntax_meta.lift_expr_to_before function can be called only during expansion. The syntax_meta.can_lift_expr_to_before function reports whether an expansion is currently in process so that syntax_meta.lift_expr_to_before can be used.

The syntax_meta.lift_expr_to_module_end function adjusts the current expansion so that expr_stx is added as an expression to the end of the module being expanded. The expression is not immediately expanded, and it will be expanded when the expansion process reaches the lifted expression at the (current) end of the module.

The syntax_meta.lift_expr_to_module_end function can be called only during expansion of a module. The syntax_meta.can_lift_expr_to_module_end function reports whether a module expansion is currently in process so that syntax_meta.lift_expr_to_module_end can be used.

The syntax_meta.make_definition_context function creates a definition context to hold expansion-time definitions:

• The syntax_meta.DefinitionContext.add_definitions method accepts a syntax object with definition forms, and it adds those definitions to the context.

  Only definitions that bind expansion-time values are allowed, such as macro, expr.macro, and meta.bridge. Definitions for run-time values, such as def or let, are not allowed.

• The syntax_meta.DefinitionContext.add_scopes method accepts a syntax object and adds the definition context’s scopes to the object, returning the new syntax object with those scopes added.

• The syntax_meta.DefinitionContext.track_origin method transfers gathered Syntax.track_origin-like expansion information to the given syntax object, where information is gathered during each syntax_meta.DefinitionContext.add_definitions call.

• The syntax_meta.DefinitionContext.call_using method makes the definition context active for expansion while calling thunk. Making the definition context active includes changing the effect of syntax_meta.flip_introduce to reflect a fresh expansion context. Consider using syntax_meta.DefinitionContext.call_to_expand_using, instead.

• The syntax_meta.DefinitionContext.call_to_expand_using method is like syntax_meta.DefinitionContext.call_using, but it takes a syntax object to flip out of the current expansion context and into the fresh expansion context (in the sense of syntax_meta.flip_introduce), and it also adds the internal definition’s scopes like syntax_meta.DefinitionContext.add_scopes. The resulting syntax object is passed to proc, which must return a new syntax object; that result is flipped out of the fresh scope and back into the enclosing scope, and syntax_meta.DefinitionContext.track_origin is also applied to it. The final result syntax object is the result of syntax_meta.DefinitionContext.call_to_expand_using.

Check whether the identifier #%dynamism using the scopes of stx is bound to indicate static mode. See use_static for more information.

Returns an identifier that has the same binding as name in space, and it also has a binding for #%dynamism to indicate dynamic or static mode, depending on as_static.

See use_static for more information about dynamic versus static mode.

Matches an integer or #false.

A phase-level integer corresponds to a phase of evaluation, especially relative to the main body of a module. Phase level 0 corresponds to a module’s run time, 1 corresponds to expansion time for run-time forms, and so on. A phase level of #false corresponds to the label phase, like meta_label.

Returns the phase of expression forms currently being expanded, or 0 if no expansion is in progress.

Unquote binding operator for use with $. It matches a syntax object for an identifier or operator, where the identifier or operator’s binding is the same as op_or_id_name in the SpaceMeta reflected by space_expr (e.g., expr_meta.space).