Merge pull request #326 from ehuss/2024-unprefixed-guarded-string

2024: Add reserved syntax

Author: ehuss

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"

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,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)
+  - [Reserved syntax](rust-2024/reserved-syntax.md)

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

src/rust-2021/reserving-syntax.md renamed to src/rust-2021/reserved-syntax.md

@@ -1,4 +1,4 @@
-# Reserving syntax
+# Reserved syntax
 
 ## Summary
 

src/rust-2024/reserved-syntax.md

@@ -0,0 +1,66 @@
+# 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 <https://github.com/rust-lang/rust/issues/123735>.
+
+## 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 make room for possible 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 `#` characters immediately followed by a [string literal].
+- Two or more `#` characters in a row (not separated by whitespace).
+
+This reservation is done across an edition boundary because of interactions with tokenization and macros. For example, consider this 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/reserved-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 the tokens continue to be parsed separately.
+
+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