From 468b213d308ac6efa675c899d9c1a49e28348196 Mon Sep 17 00:00:00 2001 From: Daniel Bloom <7810950-Daniel.Aaron.Bloom@users.noreply.gitlab.com> Date: Wed, 7 May 2025 20:06:30 -0700 Subject: [PATCH 1/2] Minor fixes to `$crate` behavior --- src/macros-by-example.md | 2 +- src/procedural-macros.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 9bdb93fce..e164f5717 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] diff --git a/src/procedural-macros.md b/src/procedural-macros.md index d47ce2a24..c5975ad48 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. From 4f386db33450b20c2ecce014864c734637f8279f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 31 May 2025 13:02:25 -0700 Subject: [PATCH 2/2] Linkify $crate --- src/macros-by-example.md | 7 ++++--- src/paths.md | 5 +++-- src/procedural-macros.md | 3 ++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/macros-by-example.md b/src/macros-by-example.md index e164f5717..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], [RAW_IDENTIFIER], or `$crate` + * `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 c5975ad48..d5e1cc946 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -350,7 +350,7 @@ 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. -- The keyword metavariable `$crate` is passed as a single identifier. +- 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 @@ -377,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