Merge pull request #937 from ehuss/names

Start documenting name resolution.

Author: Havvy

src/SUMMARY.md

@@ -11,7 +11,6 @@
     - [Comments](comments.md)
     - [Whitespace](whitespace.md)
     - [Tokens](tokens.md)
-    - [Paths](paths.md)
 
 - [Macros](macros.md)
     - [Macros By Example](macros-by-example.md)
@@ -37,7 +36,6 @@
     - [External blocks](items/external-blocks.md)
     - [Generic parameters](items/generics.md)
     - [Associated Items](items/associated-items.md)
-    - [Visibility and Privacy](visibility-and-privacy.md)
 
 - [Attributes](attributes.md)
     - [Testing](attributes/testing.md)
@@ -103,6 +101,14 @@
 
 - [Special types and traits](special-types-and-traits.md)
 
+- [Names](names.md)
+    - [Namespaces](names/namespaces.md)
+    - [Scopes](names/scopes.md)
+    - [Preludes](names/preludes.md)
+    - [Paths](paths.md)
+    - [Name resolution](names/name-resolution.md)
+    - [Visibility and privacy](visibility-and-privacy.md)
+
 - [Memory model](memory-model.md)
     - [Memory allocation and lifetime](memory-allocation-and-lifetime.md)
     - [Memory ownership](memory-ownership.md)

src/attributes.md

@@ -150,9 +150,9 @@ active. All other attributes are inert.
 ## Tool attributes
 
 The compiler may allow attributes for external tools where each tool resides
-in its own namespace. The first segment of the attribute path is the name of
-the tool, with one or more additional segments whose interpretation is up to
-the tool.
+in its own namespace in the [tool prelude]. The first segment of the attribute
+path is the name of the tool, with one or more additional segments whose
+interpretation is up to the tool.
 
 When a tool is not in use, the tool's attributes are accepted without a
 warning. When the tool is in use, the tool is responsible for processing and
@@ -279,11 +279,11 @@ The following is an index of all built-in attributes.
 [`macro_use`]: macros-by-example.md#the-macro_use-attribute
 [`must_use`]: attributes/diagnostics.md#the-must_use-attribute
 [`no_builtins`]: attributes/codegen.md#the-no_builtins-attribute
-[`no_implicit_prelude`]: items/modules.md#prelude-items
+[`no_implicit_prelude`]: names/preludes.md#the-no_implicit_prelude-attribute
 [`no_link`]: items/extern-crates.md#the-no_link-attribute
 [`no_main`]: crates-and-source-files.md#the-no_main-attribute
 [`no_mangle`]: abi.md#the-no_mangle-attribute
-[`no_std`]: crates-and-source-files.md#preludes-and-no_std
+[`no_std`]: names/preludes.md#the-no_std-attribute
 [`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute
 [`panic_handler`]: runtime.md#the-panic_handler-attribute
 [`path`]: items/modules.md#the-path-attribute
@@ -315,6 +315,7 @@ The following is an index of all built-in attributes.
 [modules]: items/modules.md
 [statements]: statements.md
 [struct]: items/structs.md
+[tool prelude]: names/preludes.md#tool-prelude
 [union]: items/unions.md
 [closure]: expressions/closure-expr.md
 [function pointer]: types/function-pointer.md

src/crates-and-source-files.md

@@ -95,27 +95,8 @@ not treated as a shebang, but instead as the start of an attribute.
 
 ## Preludes and `no_std`
 
-All crates have a *prelude* that automatically inserts names from a specific
-module, the *prelude module*, into scope of each [module] and an [`extern
-crate`] into the crate root module. By default, the *standard prelude* is used.
-The linked crate is [`std`] and the prelude module is [`std::prelude::v1`].
-
-The prelude can be changed to the *core prelude* by using the `no_std`
-[attribute] on the root crate module. The linked crate is [`core`] and the
-prelude module is [`core::prelude::v1`]. Using the core prelude over the
-standard prelude is useful when either the crate is targeting a platform that
-does not support the standard library or is purposefully not using the
-capabilities of the standard library. Those capabilities are mainly dynamic
-memory allocation (e.g. `Box` and `Vec`) and file and network capabilities (e.g.
-`std::fs` and `std::io`).
-
-<div class="warning">
-
-Warning: Using `no_std` does not prevent the standard library from being linked
-in. It is still valid to put `extern crate std;` into the crate and dependencies
-can also link it in.
-
-</div>
+This section has been moved to the [Preludes chapter](names/preludes.md).
+<!-- this is to appease the linkchecker, will remove once other books are updated -->
 
 ## Main Functions
 
@@ -168,11 +149,6 @@ or `-` (U+002D) characters.
 [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
 [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
 [`Termination`]: ../std/process/trait.Termination.html
-[`core`]: ../core/index.html
-[`core::prelude::v1`]: ../core/prelude/index.html
-[`extern crate`]: items/extern-crates.md
-[`std`]: ../std/index.html
-[`std::prelude::v1`]: ../std/prelude/index.html
 [attribute]: attributes.md
 [attributes]: attributes.md
 [comments]: comments.md
@@ -182,3 +158,17 @@ or `-` (U+002D) characters.
 [trait or lifetime bounds]: trait-bounds.md
 [where clauses]: items/generics.md#where-clauses
 [whitespace]: whitespace.md
+
+<script>
+(function() {
+    var fragments = {
+        "#preludes-and-no_std": "names/preludes.html",
+    };
+    var target = fragments[window.location.hash];
+    if (target) {
+        var url = window.location.toString();
+        var base = url.substring(0, url.lastIndexOf('/'));
+        window.location.replace(base + "/" + target);
+    }
+})();
+</script>

src/glossary.md

@@ -61,6 +61,13 @@ through a mechanism called ‘trait objects’.
 
 A dynamically sized type (DST) is a type without a statically known size or alignment.
 
+### Entity
+
+An [*entity*] is a language construct that can be referred to in some way
+within the source program, usually via a [path][paths]. Entities include
+[types], [items], [generic parameters], [variable bindings], [loop labels],
+[lifetimes], [fields], [attributes], and [lints].
+
 ### Expression
 
 An expression is a combination of values, constants, variables, operators
@@ -123,6 +130,28 @@ This is not affected by applied type arguments. `struct Foo` is considered local
 `Vec<Foo>` is not. `LocalType<ForeignType>` is local. Type aliases do not
 affect locality.
 
+### Name
+
+A [*name*] is an [identifier] or [lifetime or loop label] that refers to an
+[entity](#entity). A *name binding* is when an entity declaration introduces
+an identifier or label associated with that entity. [Paths],
+identifiers, and labels are used to refer to an entity.
+
+### Name resolution
+
+[*Name resolution*] is the compile-time process of tying [paths],
+[identifiers], and [labels] to [entity](#entity) declarations.
+
+### Namespace
+
+A *namespace* is a logical grouping of declared [names](#name) based on the
+kind of [entity](#entity) the name refers to. Namespaces allow the occurrence
+of a name in one namespace to not conflict with the same name in another
+namespace.
+
+Within a namespace, names are organized in a hierarchy, where each level of
+the hierarchy has its own collection of named entities.
+
 ### Nominal types
 
 Types that can be referred to by a path directly. Specifically [enums],
@@ -133,11 +162,22 @@ Types that can be referred to by a path directly. Specifically [enums],
 [Traits] that can be used as [trait objects]. Only traits that follow specific
 [rules][object safety] are object safe.
 
+### Path
+
+A [*path*] is a sequence of one or more path segments used to refer to an
+[entity](#entity) in the current scope or other levels of a
+[namespace](#namespace) hierarchy.
+
 ### Prelude
 
 Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
 imported into every module of every crate. The traits in the prelude are pervasive.
 
+### Scope
+
+A [*scope*] is the region of source text where a named [entity](#entity) may
+be referenced with that name.
+
 ### Scrutinee
 
 A scrutinee is the expression that is matched on in `match` expressions and
@@ -216,17 +256,37 @@ example of an uninhabited type is the [never type] `!`, or an enum with no varia
 
 [alignment]: type-layout.md#size-and-alignment
 [associated item]: #associated-item
+[attributes]: attributes.md
+[*entity*]: names.md
 [enums]: items/enumerations.md
+[fields]: expressions/field-expr.md
 [free item]: #free-item
+[generic parameters]: items/generics.md
+[identifier]: identifiers.md
+[identifiers]: identifiers.md
 [implementation]: items/implementations.md
 [implementations]: items/implementations.md
 [inherent implementation]: items/implementations.md#inherent-implementations
 [item]: items.md
+[items]: items.md
+[labels]: tokens.md#lifetimes-and-loop-labels
+[lifetime or loop label]: tokens.md#lifetimes-and-loop-labels
+[lifetimes]: tokens.md#lifetimes-and-loop-labels
+[lints]: attributes/diagnostics.md#lint-check-attributes
+[loop labels]: tokens.md#lifetimes-and-loop-labels
 [method]: items/associated-items.md#methods
+[*Name resolution*]: names/name-resolution.md
+[*name*]: names.md
+[*namespace*]: names/namespaces.md
 [never type]: types/never.md
 [object safety]: items/traits.md#object-safety
+[*path*]: paths.md
+[Paths]: paths.md
+[*scope*]: names/scopes.md
 [structs]: items/structs.md
 [trait objects]: types/trait-object.md
 [traits]: items/traits.md
+[types]: types.md
 [undefined-behavior]: behavior-considered-undefined.md
 [unions]: items/unions.md
+[variable bindings]: patterns.md

src/items/extern-crates.md

@@ -12,8 +12,10 @@
 
 An _`extern crate` declaration_ specifies a dependency on an external crate.
 The external crate is then bound into the declaring scope as the [identifier]
-provided in the `extern crate` declaration. The `as` clause can be used to
-bind the imported crate to a different name.
+provided in the `extern crate` declaration. Additionally, if the `extern
+crate` appears in the crate root, then the crate name is also added to the
+[extern prelude], making it automatically in scope in all modules. The `as`
+clause can be used to bind the imported crate to a different name.
 
 The external crate is resolved to a specific `soname` at compile time, and a
 runtime linkage requirement to that `soname` is passed to the linker for
@@ -52,39 +54,8 @@ extern crate hello_world; // hyphen replaced with an underscore
 
 ## Extern Prelude
 
-External crates imported with `extern crate` in the root module or provided to
-the compiler (as with the `--extern` flag with `rustc`) are added to the
-"extern prelude". Crates in the extern prelude are in scope in the entire
-crate, including inner modules. If imported with `extern crate orig_name as
-new_name`, then the symbol `new_name` is instead added to the prelude.
-
-The `core` crate is always added to the extern prelude. The `std` crate
-is added as long as the [`no_std`] attribute is not specified in the crate root.
-
-The [`no_implicit_prelude`] attribute can be used on a module to disable
-prelude lookups within that module.
-
-> **Edition Differences**: In the 2015 edition, crates in the extern prelude
-> cannot be referenced via [use declarations], so it is generally standard
-> practice to include `extern crate` declarations to bring them into scope.
->
-> Beginning in the 2018 edition, [use declarations] can reference crates in
-> the extern prelude, so it is considered unidiomatic to use `extern crate`.
-
-> **Note**: Additional crates that ship with `rustc`, such as [`alloc`], and
-> [`test`], are not automatically included with the `--extern` flag when using
-> Cargo. They must be brought into scope with an `extern crate` declaration,
-> even in the 2018 edition.
->
-> ```rust
-> extern crate alloc;
-> use alloc::rc::Rc;
-> ```
-
-<!--
-See https://github.com/rust-lang/rust/issues/57288 for more about the
-alloc/test limitation.
--->
+This section has been moved to [Preludes — Extern Prelude](../names/preludes.md#extern-prelude).
+<!-- this is to appease the linkchecker, will remove once other books are updated -->
 
 ## Underscore Imports
 
@@ -94,7 +65,7 @@ useful for crates that only need to be linked, but are never referenced, and
 will avoid being reported as unused.
 
 The [`macro_use` attribute] works as usual and import the macro names
-into the macro-use prelude.
+into the [`macro_use` prelude].
 
 ## The `no_link` attribute
 
@@ -105,8 +76,19 @@ crate to access only its macros.
 [IDENTIFIER]: ../identifiers.md
 [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
 [`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute
-[`alloc`]: https://doc.rust-lang.org/alloc/
-[`no_implicit_prelude`]: modules.md#prelude-items
-[`no_std`]: ../crates-and-source-files.md#preludes-and-no_std
-[`test`]: https://doc.rust-lang.org/test/
-[use declarations]: use-declarations.md
+[extern prelude]: ../names/preludes.md#extern-prelude
+[`macro_use` prelude]: ../names/preludes.md#macro_use-prelude
+
+<script>
+(function() {
+    var fragments = {
+        "#extern-prelude": "../names/preludes.html#extern-prelude",
+    };
+    var target = fragments[window.location.hash];
+    if (target) {
+        var url = window.location.toString();
+        var base = url.substring(0, url.lastIndexOf('/'));
+        window.location.replace(base + "/" + target);
+    }
+})();
+</script>

src/items/modules.md

@@ -128,34 +128,39 @@ mod thread {
 }
 ```
 
-## Prelude Items
-
-Modules implicitly have some names in scope. These name are to built-in types,
-macros imported with [`#[macro_use]`][macro_use] on an extern crate, and by the crate's
-[prelude]. These names are all made of a single identifier. These names are not
-part of the module, so for example, any name `name`, `self::name` is not a
-valid path. The names added by the [prelude] can be removed by placing the
-`no_implicit_prelude` [attribute] onto the module or one of its ancestor modules.
-
 ## Attributes on Modules
 
 Modules, like all items, accept outer attributes. They also accept inner
 attributes: either after `{` for a module with a body, or at the beginning of the
 source file, after the optional BOM and shebang.
 
 The built-in attributes that have meaning on a module are [`cfg`],
-[`deprecated`], [`doc`], [the lint check attributes], `path`, and
-`no_implicit_prelude`. Modules also accept macro attributes.
+[`deprecated`], [`doc`], [the lint check attributes], [`path`], and
+[`no_implicit_prelude`]. Modules also accept macro attributes.
 
 [_InnerAttribute_]: ../attributes.md
 [_Item_]: ../items.md
-[macro_use]: ../macros-by-example.md#the-macro_use-attribute
 [`cfg`]: ../conditional-compilation.md
 [`deprecated`]: ../attributes/diagnostics.md#the-deprecated-attribute
 [`doc`]: ../../rustdoc/the-doc-attribute.html
+[`no_implicit_prelude`]: ../names/preludes.md#the-no_implicit_prelude-attribute
+[`path`]: #the-path-attribute
 [IDENTIFIER]: ../identifiers.md
 [attribute]: ../attributes.md
 [items]: ../items.md
 [module path]: ../paths.md
-[prelude]: ../crates-and-source-files.md#preludes-and-no_std
 [the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
+
+<script>
+(function() {
+    var fragments = {
+        "#prelude-items": "../names/preludes.html",
+    };
+    var target = fragments[window.location.hash];
+    if (target) {
+        var url = window.location.toString();
+        var base = url.substring(0, url.lastIndexOf('/'));
+        window.location.replace(base + "/" + target);
+    }
+})();
+</script>

src/items/use-declarations.md

@@ -202,5 +202,5 @@ m!(use std as _;);
 [IDENTIFIER]: ../identifiers.md
 [_SimplePath_]: ../paths.md#simple-paths
 [`extern crate`]: extern-crates.md
-[extern prelude]: extern-crates.md#extern-prelude
+[extern prelude]: ../names/preludes.md#extern-prelude
 [path qualifiers]: ../paths.md#path-qualifiers

src/keywords.md

@@ -97,8 +97,8 @@ is possible to declare a variable or method with the name `union`.
 
 * `union` is used to declare a [union] and is only a keyword when used in a
   union declaration.
-* `'static` is used for the static lifetime and cannot be used as a generic
-  lifetime parameter
+* `'static` is used for the static lifetime and cannot be used as a [generic
+  lifetime parameter] or [loop label]
 
   ```compile_fail
   // error[E0262]: invalid lifetime parameter name: `'static`
@@ -127,3 +127,5 @@ is possible to declare a variable or method with the name `union`.
 [union]: items/unions.md
 [variants]: items/enumerations.md
 [`dyn`]: types/trait-object.md
+[loop label]: expressions/loop-expr.md#loop-labels
+[generic lifetime parameter]: items/generics.md