| commit | a85f11e1791df4cc7abf6ca26e4d6e19fa015c64 | [log] [tgz] |
|---|---|---|
| author | Eric Huss <eric@huss.org> | Sat Dec 20 12:03:40 2025 -0800 |
| committer | Eric Huss <eric@huss.org> | Sat Dec 20 12:03:40 2025 -0800 |
| tree | 0383d74ee32e421fcf4249262db6a0898dc5dd5d | |
| parent | 11f84ce150bed12af4331d2110c75590c7b46261 [diff] |
Clarify UNICODE_ESCAPE valid token value
This clarifies the UNICODE_ESCAPE rule that the hex value must be a
valid Unicode scalar value. This resolves the problem that a string like
`"\u{ffffff}"` is not a valid token, but the grammar did not reflect
that.
I don't see a practical way to define this with character ranges. The
resulting expression is huge.
Note that this restriction means that the UNICODE_ESCAPE rule will not
match an invalid value, and that all the places where UNICODE_ESCAPE is
used, the preceding character must *not* be `\`, which forces those
rules to fail their match. In turn the only rules that contain
UNICODE_ESCAPE have `'` or `"` characters, which won't match any other
rule in the grammar, forcing them to fail the parse.
If all those assumptions seem too fragile, then we can consider adding
the [cut operator](https://github.com/rust-lang/reference/pull/2104)
just after the `\u` so that the interpretation is clear that a failure
to match the part from the opening brace is an immediate parse failure.
This document is the primary reference for the Rust programming language.
There are several pages for those working on the reference:
To build the Reference, first clone the project:
git clone https://github.com/rust-lang/reference.git cd reference
(Alternatively, if you don't want to use git, download a ZIP file of the project, extract it using your preferred tool, and rename the top-level directory to reference.)
The Reference is built using mdbook.
First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests:
rustup toolchain install nightly rustup override set nightly
Now, ensure you have mdbook installed, as this is needed in order to build the Reference:
cargo install --locked mdbook
mdbook provides a variety of different commands and options to help you work on the book:
mdbook build --open: Build the book and open it in a web browser.mdbook serve --open: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser.The book contents are driven by a SUMMARY.md file, and every file must be linked there. See https://rust-lang.github.io/mdBook/ for its usage.
SPEC_RELATIVEThe SPEC_RELATIVE=0 environment variable makes links to the standard library go to https://doc.rust-lang.org/ instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library.
SPEC_RELATIVE=0 mdbook serve --open
The published site at https://doc.rust-lang.org/reference/ (or local docs using rustup doc) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in https://doc.rust-lang.org/1.81.0/reference/ will stay within the 1.81.0 directory).
SPEC_DENY_WARNINGSThe SPEC_DENY_WARNINGS=1 environment variable will turn all warnings generated by mdbook-spec to errors. This is used in CI to ensure that there aren't any problems with the book content.
SPEC_RUST_ROOTThe SPEC_RUST_ROOT can be used to point to the directory of a checkout of https://github.com/rust-lang/rust. This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked.
There are several different kinds of tests you can run (these are enforced on CI):
mdbook test: This will run the inline Rust codeblocks (internally it uses rustdoc to do this).cargo xtask style-check: This will validate some style checks (see authoring guide).cargo xtask linkcheck: This will validate that markdown links aren't broken.cargo xtask test-all: Runs all tests.The process for getting the reference content into a Rust release and on the website is: