Stabilize $$ in Rust 1.63.0

[c410-f3r]

Stabilization proposal

This PR proposes the stabilization of a subset of #![feature(macro_metavar_expr)] or more specifically, the stabilization of dollar-dollar ($$).

Tracking issue: #83527
Version: 1.63 (2022-06-28 => beta, 2022-08-11 => stable).

What is stabilized

macro_rules! foo {
    () => {
        macro_rules! bar {
            ( $$( $$any:tt )* ) => { $$( $$any )* };
        }
    };
}

fn main() {
    foo!();
}

Motivation

For more examples, see the RFC.

Users must currently resort to a tricky and not so well-known hack to declare nested macros with repetitions.

macro_rules! foo {
    ($dollar:tt) => {
        macro_rules! bar {
            ( $dollar ( $any:tt )* ) => { $dollar ( $any )* };
        }
    };
}
fn main() {
    foo!($);
}

As seen above, such hack is fragile and makes work with declarative macros much more unpleasant. Dollar-dollar ($$), on the other hand, makes nested macros more intuitive.

What isn't stabilized

count, ignore, index and length are not being stabilized due to the lack of consensus.

History

• 2021-02-22, RFC: Declarative macro metavariable expressions
• 2021-03-26, Tracking Issue for RFC 3086: macro metavariable expressions
• 2022-02-01, Implement macro meta-variable expressions
• 2022-02-25, [1/2] Implement macro meta-variable expressions
• 2022-03-11, [2/2] Implement macro meta-variable expressions
• 2022-03-12, Fix remaining meta-variable expression TODOs
• 2019-03-21, [macro-metavar-expr] Fix generated tokens hygiene
• 2022-04-07, Kickstart the inner usage of macro_metavar_expr
• 2022-04-07, [macro_metavar_expr] Add tests to ensure the feature requirement

Non-stabilized expressions

#83527 lists several concerns about some characteristics of count, index and length that effectively make their stabilization unfeasible. $$ and ignore, however, are not part of any discussion and thus are suitable for stabilization.

It is not in the scope of this PR to detail each concern or suggest any possible converging solution. Such thing should be restrained in this tracking issue.

Tests

This list is a subset of https://github.com/rust-lang/rust/tree/master/src/test/ui/macros/rfc-3086-metavar-expr

• Ensures that nested macros have correct behavior

• Compares produced tokens to assert expected outputs

• Checks the declarations of the features

• Verifies all possible errors that can occur due to incorrect user input

Possible future work

Once consensus is achieved, other nightly expressions can be stabilized.

Thanks @markbt for creating the RFC and thanks to @petrochenkov and @mark-i-m for reviewing the implementations.

[rust-highfive]

r? @michaelwoerister

(rust-highfive has picked a reviewer for you, use r? to override)

[joshtriplett]

Looks reasonable to me!

The stabilization report seems to cover everything.

Shall we stabilize $$ and $ignore?

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @cramertj
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm

Concerns:

• argument-dollar-or-no-dollar (Stabilize $$ in Rust 1.63.0 #95860 (comment))
• doc-pr resolved by Stabilize $$ in Rust 1.63.0 #95860 (comment)
• multi-level-nesting-of-dollar resolved by Stabilize $$ in Rust 1.63.0 #95860 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[michaelwoerister]

r? @joshtriplett, unless compiler team input is required here (in which case someone with more knowledge about macros would be a better fit than me).

[m-ou-se]

Nested macro declarations ($$)

Does this grow linearly or exponentially at deeper levels? In other words, are the next levels $$$ and $$$$, or $$$$ and $$$$$$$$?

[nikomatsakis]

@rfcbot concern doc-pr

[nikomatsakis]

Can we get a PR against the reference, @c410-f3r ?

Thanks for pursuing this!

[nikomatsakis]

@rfcbot reviewed

[joshtriplett]

@rfcbot concern multi-level-nesting-of-dollar

On behalf of @m-ou-se. We should document this. Consensus in the @rust-lang/lang meeting just now was that escaping each $ as $$ (so $$$$ two levels deep) would be simpler.

[c410-f3r]

Nested macro declarations ($$)

Does this grow linearly or exponentially at deeper levels? In other words, are the next levels $$$ and $$$$, or $$$$ and $$$$$$$$?

$$ expands to $ regardless of the declared level as specified in the RFC. So "deeper" levels have to be $$$$, $$$$$$, $$$$$$$$ and so on.

Here is a test demonstrating such scenario -> https://github.com/rust-lang/rust/blob/master/src/test/ui/macros/rfc-3086-metavar-expr/dollar-dollar-has-correct-behavior.rs

[c410-f3r]

@rfcbot concern multi-level-nesting-of-dollar

On behalf of @m-ou-se. We should document this. Consensus in the @rust-lang/lang meeting just now was that escaping each $ as $$ (so $$$$ two levels deep) would be simpler.

I am assuming that this documentation should be restrained in https://github.com/rust-lang/reference. If not, then feel free to indicate other places

[markbt]

Nested macro declarations ($$)

Does this grow linearly or exponentially at deeper levels? In other words, are the next levels $$$ and $$$$, or $$$$ and $$$$$$$$?

$$ expands to $ regardless of the declared level as specified in the RFC. So "deeper" levels have to be $$$$, $$$$$$, $$$$$$$$ and so on.

Here is a test demonstrating such scenario -> https://github.com/rust-lang/rust/blob/master/src/test/ui/macros/rfc-3086-metavar-expr/dollar-dollar-has-correct-behavior.rs

Note that this is also necessary to be fully featured, so that you can specify names of metavariables using other metavariables at each nesting level:

$foo          => bar      => bar    // Evaluate foo at level 1
$$foo         => $foo     => bar    // Evaluate foo at level 2
$$$foo        => $bar     => baz    // Evaluate foo at level 1, and use that as a name at level 2
$$$$foo       => $$foo    => $foo   // Evaluate foo at level 3
$$$$$foo      => $$bar    => $bar   // Evaluate foo at level 1, and use that as a name at level 3
$$$$$$foo     => $$$foo   => $bar   // Evaluate foo at level 2, and use that as a name at level 3
$$$$$$$foo    => $$$bar   => $baz   // Evaluate foo at level 1, use that at level 2, and then use *that* at level 3

[c410-f3r]

A PR addressing the concerns has been submitted > rust-lang/reference#1192

[c410-f3r]

Done. Thank you for allowing the stabilization of $$.

[joshtriplett]

@bors r+

[bors]

📌 Commit 9edaa76 has been approved by joshtriplett

[CAD97]

Further discussion around metafunctions can take place on Zulip: https://rust-lang.zulipchat.com/#narrow/stream/213817-t-lang/topic/macro.20metafunctions.20vs.20eager.20expansion

[blueglyph]

For future references, one of the links in the first post is broken:

• Checks the declarations of the feature

Small typo in the URL (missing 's' on 'features'):

https://github.com/rust-lang/rust/blob/master/src/test/ui/macros/rfc-3086-metavar-expr/required-features.rs

=>

• Checks the declarations of the feature

[CAD97]

What is the expected behavior of $$crate? Surely I would suppose that it should behave differently from $crate... #99035