diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 9bdb93fce..b2552054d 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -134,7 +134,7 @@ Valid fragment specifiers are: * `block`: a [BlockExpression] * `expr`: an [Expression] * `expr_2021`: an [Expression] except [UnderscoreExpression] and [ConstBlockExpression] (see [macro.decl.meta.edition2024]) - * `ident`: an [IDENTIFIER_OR_KEYWORD] or [RAW_IDENTIFIER] + * `ident`: an [IDENTIFIER_OR_KEYWORD], [RAW_IDENTIFIER], or [`$crate`] * `item`: an [Item] * `lifetime`: a [LIFETIME_TOKEN] * `literal`: matches `-`?[LiteralExpression] @@ -151,10 +151,10 @@ r[macro.decl.meta.transcription] In the transcriber, metavariables are referred to simply by `$`_name_, since the fragment kind is specified in the matcher. Metavariables are replaced with the syntax element that matched them. +Metavariables can be transcribed more than once or not at all. r[macro.decl.meta.dollar-crate] -The keyword metavariable `$crate` can be used to refer to the current crate; see [Hygiene] below. Metavariables can be -transcribed more than once or not at all. +The keyword metavariable [`$crate`] can be used to refer to the current crate. r[macro.decl.meta.edition2021] > [!EDITION-2021] @@ -594,3 +594,4 @@ For more detail, see the [formal specification]. [Metavariables]: #metavariables [Repetitions]: #repetitions [token]: tokens.md +[`$crate`]: macro.decl.hygiene.crate diff --git a/src/paths.md b/src/paths.md index afa5b82ec..edccdf72c 100644 --- a/src/paths.md +++ b/src/paths.md @@ -368,11 +368,11 @@ r[paths.qualifiers.macro-crate] ### `$crate` r[paths.qualifiers.macro-crate.allowed-positions] -`$crate` is only used within [macro transcribers], and can only be used as the first +[`$crate`] is only used within [macro transcribers], and can only be used as the first segment, without a preceding `::`. r[paths.qualifiers.macro-crate.hygiene] -`$crate` will expand to a path to access items from the +[`$crate`] will expand to a path to access items from the top level of the crate where the macro is defined, regardless of which crate the macro is invoked. @@ -472,6 +472,7 @@ mod without { // crate::without # fn main() {} ``` +[`$crate`]: macro.decl.hygiene.crate [implementations]: items/implementations.md [items]: items.md [literal]: expressions/literal-expr.md diff --git a/src/procedural-macros.md b/src/procedural-macros.md index d47ce2a24..d5e1cc946 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -350,8 +350,9 @@ r[macro.proc.token.conversion.to-proc_macro] When passed to a proc-macro - All multi-character operators are broken into single characters. - Lifetimes are broken into a `'` character and an identifier. -- All metavariable substitutions are represented as their underlying token - streams. +- The keyword metavariable [`$crate`] is passed as a single identifier. +- All other metavariable substitutions are represented as their underlying + token streams. - Such token streams may be wrapped into delimited groups ([`Group`]) with implicit delimiters ([`Delimiter::None`]) when it's necessary for preserving parsing priorities. @@ -376,6 +377,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros. [Cargo's build scripts]: ../cargo/reference/build-scripts.html [Derive macros]: #derive-macros [Function-like macros]: #function-like-procedural-macros +[`$crate`]: macro.decl.hygiene.crate [`Delimiter::None`]: proc_macro::Delimiter::None [`Group`]: proc_macro::Group [`TokenStream`]: proc_macro::TokenStream