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 437fee4a..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,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) 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/reserved-syntax.md b/src/rust-2024/reserved-syntax.md new file mode 100644 index 00000000..99e77e69 --- /dev/null +++ b/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 . + +## 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