From 469da7b412fbb3d1ae4c032bcec11d9cdc980405 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 10 Jul 2024 14:33:10 -0700 Subject: [PATCH 1/2] 2024: Add macro-fragment-specifiers. --- src/rust-2024/macro-fragment-specifiers.md | 53 +++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/src/rust-2024/macro-fragment-specifiers.md b/src/rust-2024/macro-fragment-specifiers.md index 39ea3d5..263c320 100644 --- a/src/rust-2024/macro-fragment-specifiers.md +++ b/src/rust-2024/macro-fragment-specifiers.md @@ -1,3 +1,54 @@ # Macro Fragment Specifiers -This is a stub. Help us to improve it by creating a pull request! +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". +More information may be found in the tracking issue at . + +## Summary + +- The `expr` [fragment specifier] now also supports `const` and `_` expressions. + - The `expr_2021` fragment specifier has been added for backwards compatibility. + +[fragment specifier]: ../../reference/macros-by-example.html#metavariables + +## Details + +As new syntax is added to Rust, existing `macro_rules` fragment specifiers are sometimes not allowed to match on the new syntax in order to retain backwards compatibility. Supporting the new syntax in the old fragment specifiers is sometimes deferred until the next Edition, which provides an opportunity to update them. + +Indeed this happened with [`const` expressions] added in 1.79 and [`_` expressions] added in 1.59. In the 2021 Edition and earlier, the `expr` fragment specifier does *not* match those expressions. This is because you may have a scenario like: + +```rust,edition2021 +macro_rules! example { + ($e:expr) => { println!("first rule"); }; + (const $e:expr) => { println!("second rule"); }; +} + +fn main() { + example!(const { 1 + 1 }); +} +``` + +Here, in the 2021 Edition, the macro will match the *second* rule. If earlier editions had changed `expr` to match the newly introduced `const` expressions, then it would match the *first* rule, which would be a breaking change. + +In the 2024 Edition, `expr` specifiers now also match `const` and `_` expressions. To support the old behavior, the `expr_2021` fragment specifier has been added which does *not* match the new expressions. + +[`const` expressions]: ../../reference/expressions/block-expr.html#const-blocks +[`_` expressions]: ../../reference/expressions/underscore-expr.html + +## Migration + +The [`edition_2024_expr_fragment_specifier`] lint will change all uses of the `expr` specifier to `expr_2021` to ensure that the behavior of existing macros does not change. The lint is part of the `rust-2024-compatibility` lint group which is included in the automatic edition migration. In order to migrate your code to be Rust 2024 Edition compatible, run: + +```sh +cargo fix --edition +``` + +In *most* cases, you will likely want to keep the `expr` specifier instead, in order to support the new expressions. You will need to review your macro to determine if there are other rules that would otherwise match with `const` or `_` and determine if there is a conflict. If you want the new behavior, just revert any changes made by the lint. + +Alternatively, you can manually enable the lint to find macros where you may need to update the `expr` specifier. + +```rust +// Add this to the root of your crate to do a manual migration. +#![warn(edition_2024_expr_fragment_specifier)] +``` + +[`edition_2024_expr_fragment_specifier`]: ../../rustc/lints/listing/allowed-by-default.html#edition-2024-expr-fragment-specifier From dbc3ebe06fbb99c3c8cb4f972365963adb42f703 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 16 Aug 2024 04:45:31 +0000 Subject: [PATCH 2/2] Make some editorial tweaks --- src/rust-2024/macro-fragment-specifiers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rust-2024/macro-fragment-specifiers.md b/src/rust-2024/macro-fragment-specifiers.md index 263c320..d97b82e 100644 --- a/src/rust-2024/macro-fragment-specifiers.md +++ b/src/rust-2024/macro-fragment-specifiers.md @@ -6,13 +6,13 @@ More information may be found in the tracking issue at