Opaque, category-indexed syntax values for procedural macros.
Syntax keeps token boundaries, source trivia, provenance, and hygiene contexts. Quotation marks written identifiers with definition-site plus fresh expansion scopes. Antiquotation ($name) embeds an existing syntax value without changing its use-site context. Parsing validates categories from canonical tokens; it never re-lexes rendered text.
API Reference
Structs
struct SyntaxScope
One opaque hygiene-scope identity.
struct SyntaxContext
A set of lexical scopes. Its representation is private so identifiers can acquire context only through explicit syntax operations, never from text.
struct QuoteContext
The contexts applied to identifiers introduced by one quotation.
struct Syntax<Category>
Opaque, category-indexed macro syntax with token provenance and hygiene.
struct SyntaxSplice<Category>
A named antiquotation value awaiting insertion into a quote.
struct SyntaxFailure
A stable procedural-syntax failure suitable for crossing the macro-service ABI.
struct SyntaxResult<Category>
A category-checked syntax value or its construction failure.
struct SyntaxIdentifier
An identifier's spelling, source provenance, and hygienic resolution context.
struct MaterializedIdentifier
One identifier in the virtual source parsed for expansion. span and lexeme index that virtual source; source_* point back to the token from which the syntax object was captured or quoted.
struct MaterializedSyntax<Category>
The virtual source, canonical tokens, AST, and provenance produced from syntax.
struct MaterializedResult<Category>
A successful materialization or the parse failure that rejected it.
struct SyntaxScopeRecord
ABI-facing hygiene records keep generic Range fields flattened. Macro services return this envelope beside their category-specific parse result.
struct SyntaxIdentifierRecord
A flattened SyntaxIdentifier suitable for the macro-service ABI.
struct SyntaxMetadataOutput
Flattened identifier metadata returned across the procedural-macro service boundary.
struct ExprMacroOutput
The service boundary for expression procedural macros. A successful value carries the already-parsed canonical outcome; Rust adapts it directly and does not parse or lex the materialized source again.
struct DeclWrapperOutput
The service boundary for declaration wrapper macros. A replacement carries the already-parsed canonical outcome, exactly like ExprMacroOutput; removed reports the intentional no-declaration result distinctly from failure.
struct DeclView
A token-preserving lens over a declaration's name and optional body.
Enums
enum SyntaxOrigin
Determines which hygiene context an identifier receives during expansion.
enum SyntaxScopeKind
Scope identities are allocated by the macro driver. The pair keeps scope ordinals local to one deterministic compilation namespace.
enum DeclContext
The declaration context a wrapper's target appeared in. Tags match parse_decl_tokens_in: file, block, then the nominal bodies.
enum DeclWrapperResult
A wrapper macro's single explicit result: replace the target with one declaration, intentionally emit no declaration, or report a diagnostic.
enum DeclShape
The grammatical shape a viewed declaration parsed as. Functions, methods, and initializers report a body; every shape reports a name when the grammar declares one.
Functions
func lexical_scope(file_id: Int, node_id: Int) -> SyntaxScope
Creates a lexical hygiene scope for a source node.
func expansion_scope(namespace: Int, ordinal: Int) -> SyntaxScope
Creates a hygiene scope for one macro expansion.
func module_scope(module_id: Int) -> SyntaxScope
Creates a hygiene scope for a module.
func empty_syntax_context() -> SyntaxContext
Returns a syntax context containing no scopes.
func syntax_context_with_scope(context: SyntaxContext, scope: SyntaxScope) -> SyntaxContext
Returns a context with the scope appended once.
func same_syntax_context(a: &SyntaxContext, b: &SyntaxContext) -> Bool
Returns whether both contexts contain the same scope identities.
func quote_context(definition_site: SyntaxContext, expansion_scope: SyntaxScope) -> QuoteContext
Combines a macro definition's context with the fresh scope for one expansion.
func copy_syntax_context(context: &SyntaxContext) -> SyntaxContext
Copies the ordered scope set so it can cross an ownership boundary.
func copy_quote_context(context: &QuoteContext) -> QuoteContext
Copies a quote context, including an owned copy of its definition-site scopes.
func splice<Category>(name: String, consume syntax: Syntax<Category>) -> SyntaxSplice<Category>
Binds category-checked syntax to an antiquotation name for one quote operation.
func ungrouped_expr_splice(consume syntax: Syntax<Expr>) -> Syntax<Expr>
Disables the parentheses normally added around an expression splice.
func pattern_expr_fragment(consume syntax: Syntax<Pattern>) -> Syntax<Expr>
These fragments are valid only inside an expression quotation at the corresponding grammar position. The completed quotation is parsed before it can escape, so a pattern or type can never materialize as a standalone expression result.
func type_expr_fragment(consume syntax: Syntax<TypeAnnotation>) -> Syntax<Expr>
Reclassifies type tokens for a type-shaped position inside an expression quote.
func expr_decl_fragment(consume syntax: Syntax<Expr>) -> Syntax<Decl>
These fragments are valid only inside a declaration quotation at the corresponding grammar position; the completed quotation is still parsed as one declaration before it can escape the wrapper service boundary.
func type_decl_fragment(consume syntax: Syntax<TypeAnnotation>) -> Syntax<Decl>
Reclassifies type tokens for a type-shaped position inside a declaration quote.
func build_match_expr(consume subject: Syntax<Expr>, consume patterns: [Syntax<Pattern>], consume bodies: [Syntax<Expr>], source_id: Int, source_span: Range<Int>, context: &QuoteContext) -> SyntaxResult<Expr>
Build one match expression from heterogeneous, already-validated syntax categories. This keeps all arms in one match so ordinary exhaustiveness and ownership checking see the same structure the author wrote.
func string_literal_expr(value: String, source_id: Int, source_span: Range<Int>, context: &QuoteContext) -> Syntax<Expr>
Construct a category-checked string literal without routing generated text through the lexer. This is intentionally a literal-only constructor: macro authors still cannot manufacture identifiers or their syntax contexts from strings. The generated token points back to the source syntax that caused the literal so diagnostics retain useful provenance.
func capture_expr(source_id: Int, source: String, input: TokenRange, context: &SyntaxContext) -> SyntaxResult<Expr>
Validates input as exactly one expression and captures its canonical tokens.
func capture_pattern(source_id: Int, source: String, input: TokenRange, context: &SyntaxContext) -> SyntaxResult<Pattern>
Validates input as exactly one pattern and captures it with use-site hygiene.
func capture_type(source_id: Int, source: String, input: TokenRange, context: &SyntaxContext) -> SyntaxResult<TypeAnnotation>
Validates input as exactly one type annotation with use-site hygiene.
func capture_decl(source_id: Int, source: String, input: TokenRange, context: &SyntaxContext) -> SyntaxResult<Decl>
Validates input as one top-level declaration with use-site hygiene.
func no_macro_input() -> MacroInput?
Optional constructors for the generated wrapper ABI entry points, which deliberately avoid naming MacroInput so their generated text can never collide with a macro unit's own imports.
func some_macro_input(consume input: MacroInput) -> MacroInput?
Wraps captured macro input in an optional value.
func decl_context_from_tag(tag: Int) -> DeclContext
Decodes the wrapper-service declaration-context ABI.
func decl_wrapper_failure(code: String, message: String, span: Range<Int>) -> DeclWrapperOutput
Builds the flattened wrapper-service representation of a failure.
func capture_decl_in(source_id: Int, source: String, input: TokenRange, context_tag: Int, context: &SyntaxContext) -> SyntaxResult<Decl>
The declaration category parsed in the target's declaration context, so a captured or replaced member means what it meant where the marker appeared.
func capture_wrapper_target(source_id: Int, source: String, encoded: String, context_tag: Int, context: &SyntaxContext) -> SyntaxResult<Decl>
Capture a wrapper's target declaration. The first application in a chain supplies the parser-recorded canonical tokens; a chained application supplies the previous replacement's rendered source instead, which scans deterministically because it was materialized from canonical tokens.
func materialize_decl_syntax_in(syntax: &Syntax<Decl>, context_tag: Int) -> MaterializedResult<Decl>
The declaration category parse at the wrapper service boundary, in the declaration context the replacement will occupy.
func materialize_decl_wrapper_result(consume result: DeclWrapperResult, context_tag: Int) -> DeclWrapperOutput
Turn the wrapper author's result into the flattened service output consumed by the Rust expansion driver.
func quote_expr(input: MacroInput, splices: [SyntaxSplice<Expr>], context: &QuoteContext) -> SyntaxResult<Expr>
Quotes expression tokens and resolves named antiquotations.
func quote_expr_encoded(source_id: Int, source: String, encoded: String, splices: [SyntaxSplice<Expr>], context: &QuoteContext) -> SyntaxResult<Expr>
Lowering target for quote { ... }: canonical parser tokens are embedded in the macro service image and decoded without scanning source text.
func quote_pattern(input: MacroInput, splices: [SyntaxSplice<Pattern>], context: &QuoteContext) -> SyntaxResult<Pattern>
Quotes pattern tokens, applies hygiene, and validates the completed pattern.
func quote_type(input: MacroInput, splices: [SyntaxSplice<TypeAnnotation>], context: &QuoteContext) -> SyntaxResult<TypeAnnotation>
Quotes type tokens, applies hygiene, and validates the completed annotation.
func quote_decl(input: MacroInput, splices: [SyntaxSplice<Decl>], context: &QuoteContext) -> SyntaxResult<Decl>
Quotes declaration tokens while preserving token provenance and hygiene.
func quote_decl_encoded(source_id: Int, source: String, encoded: String, splices: [SyntaxSplice<Decl>], context: &QuoteContext) -> SyntaxResult<Decl>
Lowering target for quote decl { ... } (ADR 0026 wrapper macros).
func materialize_expr_syntax(syntax: &Syntax<Expr>) -> MaterializedResult<Expr>
Materializes expression syntax into virtual source, tokens, AST, and metadata.
func materialize_pattern_syntax(syntax: &Syntax<Pattern>) -> MaterializedResult<Pattern>
Materializes and validates pattern syntax through the canonical pattern parser.
func materialize_type_syntax(syntax: &Syntax<TypeAnnotation>) -> MaterializedResult<TypeAnnotation>
Materializes and validates type syntax through the canonical type parser.
func materialize_decl_syntax(syntax: &Syntax<Decl>) -> MaterializedResult<Decl>
Materializes declaration syntax using top-level declaration grammar.
func syntax_metadata_output<Category>(materialized: &MaterializedSyntax<Category>) -> SyntaxMetadataOutput
Serializes materialized syntax metadata for the macro host.
func expr_macro_failure(code: String, message: String, span: Range<Int>) -> ExprMacroOutput
Builds the flattened expression-macro representation of a failure.
func materialize_expr_macro_result(consume result: SyntaxResult<Expr>) -> ExprMacroOutput
Turn the macro author's category-checked result into the single flattened service output consumed by the Rust expansion driver.
func decl_context_tag(context: &DeclContext) -> Int
Encodes a declaration context using the wrapper-service ABI tags 0 through 5.
func view_decl(target: &Syntax<Decl>, declaration: &DeclContext) -> DeclView?
Build a structural view of a declaration in the context it occupies. .none reports syntax the declaration grammar rejects, which a wrapper target can only be when a previous rebuild produced it.
func view_shape(view: &DeclView) -> DeclShape
Returns the declaration category recognized by view_decl.
func view_name(view: &DeclView) -> String?
Returns the declared name when this grammar form has one.
func view_body(view: &DeclView) -> Syntax<Expr>?
The body block as expression syntax (braces included), preserving each token's provenance and hygiene context, so it can be spliced into an expression quotation.
func view_with_body(view: &DeclView, consume body: Syntax<Expr>, context: &QuoteContext) -> SyntaxResult<Decl>
Rebuild the declaration with a new body block containing the given expression: a block expression re-embeds wholesale, anything else becomes the new body's trailing expression.
func view_with_name(view: &DeclView, name: String, context: &QuoteContext) -> SyntaxResult<Decl>
Rebuild the declaration with a fresh, hygienically introduced name: the binder carries the definition site plus the expansion scope, so it neither captures caller names nor leaks into caller scope.
func view_with_name_token(view: &DeclView, source_id: Int, source: String, token: Token, use_site: &SyntaxContext) -> SyntaxResult<Decl>
Rebuild the declaration with a caller-provided identifier as the binder (ADR 0026's intentional exposure path). The token must come from use-site syntax — typically the wrapper's argument tree — and keeps its use-site context, so callers can see the rebuilt name.
func syntax_text<Category>(syntax: &Syntax<Category>) -> String
Materializes the syntax's tokens and trivia as source text without reparsing.
func syntax_identifiers<Category>(syntax: &Syntax<Category>) -> [SyntaxIdentifier]
Flattens identifier-like tokens from this syntax and all nested splices.