Improve description of ident fragment matcher, and $crate metavariable#2214
Open
steffahn wants to merge 1 commit intorust-lang:masterfrom
Open
Improve description of ident fragment matcher, and $crate metavariable#2214steffahn wants to merge 1 commit intorust-lang:masterfrom
ident fragment matcher, and $crate metavariable#2214steffahn wants to merge 1 commit intorust-lang:masterfrom
Conversation
I am initially coming to work on this due to the line > an IDENTIFIER_OR_KEYWORD except _, RAW_IDENTIFIER, or $crate being unfortunately very ambiguous, since this can be read as “_, RAW_IDENTIFIER, or $crate” all belonging to the “except” listing. My best fix for that is to add parentheses around the “except _”. This seems to read more nicely than alternatives I have tried, for instance > either an IDENTIFIER_OR_KEYWORD except _, or a RAW_IDENTIFIER, or "$crate" (which still seems ambiguous) And the exception for “_” seems minor enough (previously it had been missing completely for a while) that parentheses also seem sensible semantically, IMHO. The meaning of accepting `$crate` was confusing to me though; and apparently a known issue, so this closes rust-lang#588. To achieve this, I have written a new section to the reference description of `$crate`, and worded the concept as `$crate` being "initially replaced". The verb "replace" is for consistency with the wording of other metavariables, which are being "replaced" during expansion; the qualifier "initially" is added to emphasize the important difference of this process from *macro expansion*. And also where I'm linking to it, the phrasing "replaced $crate" can easily be misunderstood for people to think that "$crate" has already been replaced by the name of the crate it's referring to, even though that's not at all how this process works!
rustbot
added
the
S-waiting-on-review
ehuss
reviewed
Apr 14, 2026
| ``` | ||
|
|
||
| r[macro.decl.hygiene.crate.replaced] | ||
| The raw syntax of `$crate` consists of two tokens (`$` followed by `crate`). When used as a metavariable within a macro definition, this syntax is initially replaced with a single token (also called "`$crate`"), which can be used an identifier. |
Contributor
There was a problem hiding this comment.
Can you say why this has an ?
| fn foo() {} | ||
| ``` | ||
|
|
||
| However, the crate being referred to does *not* itself need to be visible from the invocation site as a directly declared dependency. A main purpose of `$crate` is to offer a way of reliably naming crates (and their public items) in macro-generated code, even if the only exists as a transitive dependency (i.e. "dependency of a dependency") from the invocation site. |
Contributor
There was a problem hiding this comment.
I think this is what was intended?
Suggested change
| However, the crate being referred to does *not* itself need to be visible from the invocation site as a directly declared dependency. A main purpose of `$crate` is to offer a way of reliably naming crates (and their public items) in macro-generated code, even if the only exists as a transitive dependency (i.e. "dependency of a dependency") from the invocation site. | |
| However, the crate being referred to does *not* itself need to be visible from the invocation site as a directly declared dependency. A main purpose of `$crate` is to offer a way of reliably naming crates (and their public items) in macro-generated code, even if it only exists as a transitive dependency (i.e. "dependency of a dependency") from the invocation site. |
Contributor
|
Just for clarity, I also wanted to link to rust-lang/rust#155121 as there are active changes happening in this area. I don't think that affects this PR. I'm not sure if you're already aware of those changes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I am initially coming to work on this due to the line
being unfortunately very ambiguous, since this can be read as “
_, RAW_IDENTIFIER, or$crate” all belongingto the “except” listing.
My best fix for that is to add parentheses around the “except
_”.This seems to read more nicely than alternatives I have tried, for instance
(which still seems ambiguous)
And the exception for “
_” seems minor enough (previously it had been missing completely for a while) that parentheses also seem sensible semantically, IMHO.The meaning of accepting
$cratewas confusing to me though; and apparently a known issue, so this closes #588. (I think. Unless that issue wants even more information; or information in some particular other place?)To achieve this, I have written a new section to the reference description of
$crate, and worded the concept as$cratebeing “initially replaced”.$crate” can easily be misunderstood for people to think that “$crate” has already been replaced by the name of the crate it’s referring to, even though that’s not at all how this process works!