Skip to content

Update the Preludes chapter for the 2021 edition changes to the standard library prelude #1136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 24, 2022
Merged

Update the Preludes chapter for the 2021 edition changes to the standard library prelude #1136

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dfc94ed
Update for 2021 edition standard library prelude changes
mattheww Jan 15, 2022
0181f23
2021 edition standard library prelude changes: address review comments
mattheww Jan 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions src/names/preludes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,22 @@ There are several different preludes:

## Standard library prelude

The standard library prelude includes names from the [`std::prelude::v1`]
module. If the [`no_std` attribute] is used, then it instead uses the names
from the [`core::prelude::v1`] module.
Each crate has a standard library prelude, which consists of the names from a single standard library module. The module used depends on the crate's edition, and on whether the [`no_std` attribute] is applied to the crate:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you split sentences with newlines so that each sentence is on a line of its own?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


Edition | `no_std` not applied | `no_std` applied
--------| --------------------------- | ----------------------------
2015 | [`std::prelude::rust_2015`] | [`core::prelude::rust_2015`]
2018 | [`std::prelude::rust_2018`] | [`core::prelude::rust_2018`]
2021 | [`std::prelude::rust_2021`] | [`core::prelude::rust_2021`]

This choice of prelude is in effect throughout the crate, including code generated by macros defined in crates with a different edition or `no_std` attribute.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm having a bit of trouble fully understanding what this sentence is trying to say. Might I suggest to just remove it? The start of this chapter describes how every prelude is part of name resolution for every module. Also, there isn't anything special about the standard library prelude with respect to macros.

In the future, once Name Resolution is filled out, it might become more clear how names from preludes are resolved. Also, I think the Hygiene section explains how names are resolved in macros.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed it



> **Note**:
>
> [`std::prelude::rust_2015`] and [`std::prelude::rust_2018`] have the same contents as [`std::prelude::v1`].
>
> [`core::prelude::rust_2015`] and [`core::prelude::rust_2018`] have the same contents as [`core::prelude::v1`].

## Extern prelude

Expand Down Expand Up @@ -63,15 +76,13 @@ By default, the standard library is automatically included in the crate root
module. The [`std`] crate is added to the root, along with an implicit
[`macro_use` attribute] pulling in all macros exported from `std` into the
[`macro_use` prelude]. Both [`core`] and [`std`] are added to the [extern
prelude]. The [standard library prelude] includes everything from the
[`std::prelude::v1`] module.
prelude].

The *`no_std` [attribute]* may be applied at the crate level to prevent the
[`std`] crate from being automatically added into scope. It does three things:

* Prevents `std` from being added to the [extern prelude](#extern-prelude).
* Uses [`core::prelude::v1`] in the [standard library prelude] instead of
[`std::prelude::v1`].
* Affects which module is used to make up the [standard library prelude] (as described above).
* Injects the [`core`] crate into the crate root instead of [`std`], and pulls
in all macros exported from `core` in the [`macro_use` prelude].

Expand Down Expand Up @@ -130,13 +141,19 @@ This attribute does not affect the [language prelude].
[`alloc`]: ../../alloc/index.html
[`Box`]: ../../std/boxed/struct.Box.html
[`core::prelude::v1`]: ../../core/prelude/index.html
[`core::prelude::rust_2015`]: ../../core/prelude/index.html
[`core::prelude::rust_2018`]: ../../core/prelude/index.html
[`core::prelude::rust_2021`]: ../../core/prelude/index.html
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a particular reason not to link the to the specific modules? For example, rust_2021 precisely shows what is exported from the module.

I realize the original v1 links went to the top-level module, but I honestly don't remember why I did that (I think linking to v1 would also be more clear).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've changed them, including v1

[`core`]: ../../core/index.html
[`extern crate`]: ../items/extern-crates.md
[`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute
[`macro_use` prelude]: #macro_use-prelude
[`no_std` attribute]: #the-no_std-attribute
[`no_std` attribute]: #the-no_std-attribute
[`std::prelude::v1`]: ../../std/prelude/index.html
[`std::prelude::rust_2015`]: ../../std/prelude/index.html
[`std::prelude::rust_2018`]: ../../std/prelude/index.html
[`std::prelude::rust_2021`]: ../../std/prelude/index.html
[`std`]: ../../std/index.html
[`test`]: ../../test/index.html
[attribute]: ../attributes.md
Expand Down