From d882e1a5bd08b6df824373b955421352e41cfc42 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 12 Oct 2024 08:35:26 -0700 Subject: [PATCH 1/3] 2024: Add reserved syntax --- src/SUMMARY.md | 1 + src/rust-2024/reserving-syntax.md | 63 +++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 src/rust-2024/reserving-syntax.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 437fee4a..d271ffa9 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -55,3 +55,4 @@ - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md) - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) + - [Reserving syntax](rust-2024/reserving-syntax.md) diff --git a/src/rust-2024/reserving-syntax.md b/src/rust-2024/reserving-syntax.md new file mode 100644 index 00000000..d5fccfcf --- /dev/null +++ b/src/rust-2024/reserving-syntax.md @@ -0,0 +1,63 @@ +# Reserving syntax + +🚧 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 + +- Unprefixed guarded strings of the form `#"foo"#` are reserved for future use. +- Two or more `#` characters are reserved for future use. + +## Details + +[RFC 3593] reserved syntax in the 2024 Edition for guarded string literals that do not have a prefix to future-proof against future language changes. The 2021 Edition [reserved syntax][2021] for guarded strings with a prefix, such as `ident##"foo"##`. The 2024 Edition extends that to also reserve strings without the `ident` prefix. + +There are two reserved syntaxes: One or more `#` immediately followed by a [string literal], and two or more `#` characters in a row. + +This reservation is done across an edition boundary because of interactions with tokenization and macros. For example, with the following macro: + +```rust +macro_rules! demo { + ( $a:tt ) => { println!("one token") }; + ( $a:tt $b:tt $c:tt ) => { println!("three tokens") }; +} + +demo!("foo"); +demo!(r#"foo"#); +demo!(#"foo"#); +demo!(###) +``` + +Prior to the 2024 Edition, this produces: + +```text +one token +one token +three tokens +three tokens +``` + +Starting in the 2024 Edition, the `#"foo"#` line and the `###` line now generates a compile error because those forms are now reserved. + +[2021]: ../rust-2021/reserving-syntax.md +[string literal]: ../../reference/tokens.html#string-literals +[RFC 3593]: https://rust-lang.github.io/rfcs/3593-unprefixed-guarded-strings.html + +## Migration + +The [`rust_2024_guarded_string_incompatible_syntax`] lint will identify any tokens that match the reserved syntax, and will suggest a modification to insert spaces where necessary to ensure it continues to be parsed as separate tokens. + +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 +``` + +Alternatively, you can manually enable the lint to find macro calls where you may need to update the tokens: + +```rust +// Add this to the root of your crate to do a manual migration. +#![warn(rust_2024_guarded_string_incompatible_syntax)] +``` + +[`rust_2024_guarded_string_incompatible_syntax`]: ../../rustc/lints/listing/allowed-by-default.html#rust-2024-guarded-string-incompatible-syntax From 91e1efc3605ddb581ba050d4d3c3ad9523daebc4 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 18 Oct 2024 19:29:57 +0000 Subject: [PATCH 2/3] Say "reserved" rather than "reserving" in title Since all other chapter titles are either noun phrases (e.g. "additions to...", "X change", etc.) or verb phrases in imperative mood (e.g. "remove...", "reject...", "combine..."), it would be odd to have a stray chapter title in the present continuous tense ("reserving..."). Staying with a noun sounds better to my ear than an imperative verb phrase here, so let's do that. This "reserving..." chapter title was also used in the Rust 2021 guide. For consistency, let's change that title and URL also, and add a redirect. --- book.toml | 1 + src/SUMMARY.md | 4 ++-- src/rust-2021/c-string-literals.md | 2 +- src/rust-2021/{reserving-syntax.md => reserved-syntax.md} | 2 +- src/rust-2024/{reserving-syntax.md => reserved-syntax.md} | 4 ++-- 5 files changed, 7 insertions(+), 6 deletions(-) rename src/rust-2021/{reserving-syntax.md => reserved-syntax.md} (99%) rename src/rust-2024/{reserving-syntax.md => reserved-syntax.md} (97%) diff --git a/book.toml b/book.toml index 77867ae1..998a8177 100644 --- a/book.toml +++ b/book.toml @@ -80,6 +80,7 @@ search.use-boolean-and = true "/rust-2018/platform-and-target-support/msvc-toolchain-support.html" = "../../../rustc/platform-support.html" "/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html" = "../../../rustc/platform-support.html" "/rust-2018/platform-and-target-support/cdylib-crates-for-c-interoperability.html" = "https://github.com/rust-lang/rfcs/blob/master/text/1510-cdylib.md" +"/rust-2021/reserving-syntax.html" = "reserved-syntax.html" "/rust-next/index.html" = "../rust-2021/index.html" "/rust-next/edition-changes.html" = "../rust-2021/index.html" "/rust-next/dbg-macro.html" = "../../std/macro.dbg.html" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d271ffa9..0d43098d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -30,7 +30,7 @@ - [IntoIterator for arrays](rust-2021/IntoIterator-for-arrays.md) - [Disjoint capture in closures](rust-2021/disjoint-capture-in-closures.md) - [Panic macro consistency](rust-2021/panic-macro-consistency.md) - - [Reserving syntax](rust-2021/reserving-syntax.md) + - [Reserved syntax](rust-2021/reserved-syntax.md) - [Warnings promoted to errors](rust-2021/warnings-promoted-to-error.md) - [Or patterns in macro-rules](rust-2021/or-patterns-macro-rules.md) - [C-string literals](rust-2021/c-string-literals.md) @@ -55,4 +55,4 @@ - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md) - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) - - [Reserving syntax](rust-2024/reserving-syntax.md) + - [Reserved syntax](rust-2024/reserved-syntax.md) diff --git a/src/rust-2021/c-string-literals.md b/src/rust-2021/c-string-literals.md index 570794ac..6a34b32d 100644 --- a/src/rust-2021/c-string-literals.md +++ b/src/rust-2021/c-string-literals.md @@ -69,4 +69,4 @@ Migration is only necessary for macros which may have been assuming a sequence o As part of the [syntax reservation] for the 2021 edition, any macro input which may run into this issue should issue a warning from the `rust_2021_prefixes_incompatible_syntax` migration lint. See that chapter for more detail. -[syntax reservation]: reserving-syntax.md +[syntax reservation]: reserved-syntax.md diff --git a/src/rust-2021/reserving-syntax.md b/src/rust-2021/reserved-syntax.md similarity index 99% rename from src/rust-2021/reserving-syntax.md rename to src/rust-2021/reserved-syntax.md index 15e7b1f5..04c2b21c 100644 --- a/src/rust-2021/reserving-syntax.md +++ b/src/rust-2021/reserved-syntax.md @@ -1,4 +1,4 @@ -# Reserving syntax +# Reserved syntax ## Summary diff --git a/src/rust-2024/reserving-syntax.md b/src/rust-2024/reserved-syntax.md similarity index 97% rename from src/rust-2024/reserving-syntax.md rename to src/rust-2024/reserved-syntax.md index d5fccfcf..a1570b14 100644 --- a/src/rust-2024/reserving-syntax.md +++ b/src/rust-2024/reserved-syntax.md @@ -1,4 +1,4 @@ -# Reserving syntax +# Reserved syntax 🚧 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 . @@ -39,7 +39,7 @@ three tokens Starting in the 2024 Edition, the `#"foo"#` line and the `###` line now generates a compile error because those forms are now reserved. -[2021]: ../rust-2021/reserving-syntax.md +[2021]: ../rust-2021/reserved-syntax.md [string literal]: ../../reference/tokens.html#string-literals [RFC 3593]: https://rust-lang.github.io/rfcs/3593-unprefixed-guarded-strings.html From dceaaca744d1d68266a70f9ae4d4552583c7fc91 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 18 Oct 2024 22:04:29 +0000 Subject: [PATCH 3/3] Make some editorial tweaks --- src/rust-2024/reserved-syntax.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/rust-2024/reserved-syntax.md b/src/rust-2024/reserved-syntax.md index a1570b14..99e77e69 100644 --- a/src/rust-2024/reserved-syntax.md +++ b/src/rust-2024/reserved-syntax.md @@ -10,11 +10,14 @@ More information may be found in the tracking issue at