Merge pull request #1547 from ehuss/blockquote-styling
Remove custom blockquote styling
diff --git a/mdbook-spec/src/std_links.rs b/mdbook-spec/src/std_links.rs
index cede9f3..0c7860b 100644
--- a/mdbook-spec/src/std_links.rs
+++ b/mdbook-spec/src/std_links.rs
@@ -12,7 +12,7 @@
/// the standard library using rustdoc's intra-doc notation.
const STD_LINK: &str = r"(?: [a-z]+@ )?
(?: std|core|alloc|proc_macro|test )
- (?: ::[A-Za-z0-9_!:<>{}()\[\]]+ )?";
+ (?: ::[A-Za-z0-9_!,:<>{}()\[\]]+ )?";
/// The Regex for a markdown link that might be a link to the standard library.
static STD_LINK_RE: Lazy<Regex> = Lazy::new(|| {
diff --git a/src/attributes.md b/src/attributes.md
index 08b6c06..a56e276 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -174,7 +174,7 @@
## Tool attributes
The compiler may allow attributes for external tools where each tool resides
-in its own namespace in the [tool prelude]. The first segment of the attribute
+in its own module 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.
diff --git a/src/items/constant-items.md b/src/items/constant-items.md
index 9d48762..9fb2185 100644
--- a/src/items/constant-items.md
+++ b/src/items/constant-items.md
@@ -11,6 +11,8 @@
non-[`Copy`] types. References to the same constant are not necessarily
guaranteed to refer to the same memory address.
+The constant declaration defines the constant value in the [value namespace] of the module or block where it is located.
+
Constants must be explicitly typed. The type must have a `'static` lifetime: any
references in the initializer must have `'static` lifetimes.
@@ -115,3 +117,4 @@
[_Type_]: ../types.md#type-expressions
[_Expression_]: ../expressions.md
[`Copy`]: ../special-types-and-traits.md#copy
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/enumerations.md b/src/items/enumerations.md
index 0d42bfd..5f00846 100644
--- a/src/items/enumerations.md
+++ b/src/items/enumerations.md
@@ -30,6 +30,7 @@
to create or pattern-match values of the corresponding enumerated type.
Enumerations are declared with the keyword `enum`.
+The `enum` declaration defines the enumeration type in the [type namespace] of the module or block where it is located.
An example of an `enum` item and its use:
@@ -80,6 +81,30 @@
}
```
+Variant constructors are similar to [struct] definitions, and can be referenced by a path from the enumeration name, including in [use declarations].
+Each variant defines its type in the [type namespace], though that type cannot be used as a type specifier.
+Tuple-like and unit-like variants also define a constructor in the [value namespace].
+
+A struct-like variant can be instantiated with a [struct expression].
+A tuple-like variant can be instantiated with a [call expression] or a [struct expression].
+A unit-like variant can be instantiated with a [path expression] or a [struct expression].
+For example:
+
+```rust
+enum Examples {
+ UnitLike,
+ TupleLike(i32),
+ StructLike { value: i32 },
+}
+
+use Examples::*; // Creates aliases to all variants.
+let x = UnitLike; // Path expression of the const item.
+let x = UnitLike {}; // Struct expression.
+let y = TupleLike(123); // Call expression.
+let y = TupleLike { 0: 123 }; // Struct expression using integer field names.
+let z = StructLike { value: 123 }; // Struct expression.
+```
+
<span id="custom-discriminant-values-for-fieldless-enumerations"></span>
## Discriminants
@@ -299,20 +324,27 @@
}
```
-[IDENTIFIER]: ../identifiers.md
-[_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
[_Expression_]: ../expressions.md
-[_TupleFields_]: structs.md
+[_GenericParams_]: generics.md
[_StructFields_]: structs.md
+[_TupleFields_]: structs.md
[_Visibility_]: ../visibility-and-privacy.md
-[enumerated type]: ../types/enum.md
+[_WhereClause_]: generics.md#where-clauses
+[`C` representation]: ../type-layout.md#the-c-representation
[`mem::discriminant`]: ../../std/mem/fn.discriminant.html
-[never type]: ../types/never.md
-[unit-only]: #unit-only-enum
-[numeric cast]: ../expressions/operator-expr.md#semantics
+[call expression]: ../expressions/call-expr.md
[constant expression]: ../const_eval.md#constant-expressions
[default representation]: ../type-layout.md#the-default-representation
-[primitive representation]: ../type-layout.md#primitive-representations
-[`C` representation]: ../type-layout.md#the-c-representation
+[enumerated type]: ../types/enum.md
[Field-less enums]: #field-less-enum
+[IDENTIFIER]: ../identifiers.md
+[never type]: ../types/never.md
+[numeric cast]: ../expressions/operator-expr.md#semantics
+[path expression]: ../expressions/path-expr.md
+[primitive representation]: ../type-layout.md#primitive-representations
+[struct expression]: ../expressions/struct-expr.md
+[struct]: structs.md
+[type namespace]: ../names/namespaces.md
+[unit-only]: #unit-only-enum
+[use declarations]: use-declarations.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md
index 9dd6a5e..523e972 100644
--- a/src/items/extern-crates.md
+++ b/src/items/extern-crates.md
@@ -11,11 +11,9 @@
> `as` ( [IDENTIFIER] | `_` )
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. 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 then bound into the declaring scope as the given [identifier] in the [type namespace].
+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
@@ -74,6 +72,7 @@
[extern prelude]: ../names/preludes.md#extern-prelude
[`macro_use` prelude]: ../names/preludes.md#macro_use-prelude
[`crate_name` attributes]: ../crates-and-source-files.md#the-crate_name-attribute
+[type namespace]: ../names/namespaces.md
<script>
(function() {
diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md
index efbd082..9abce3f 100644
--- a/src/items/external-blocks.md
+++ b/src/items/external-blocks.md
@@ -21,6 +21,8 @@
[statics]. Calling functions or accessing statics that are declared in external
blocks is only allowed in an `unsafe` context.
+The external block defines its functions and statics in the [value namespace] of the module or block where it is located.
+
The `unsafe` keyword is syntactically allowed to appear before the `extern`
keyword, but it is rejected at a semantic level. This allows macros to consume
the syntax and make use of the `unsafe` keyword, before removing it from the
@@ -342,3 +344,4 @@
[`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
[`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib
[PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/functions.md b/src/items/functions.md
index 47059ad..ae698fb 100644
--- a/src/items/functions.md
+++ b/src/items/functions.md
@@ -45,7 +45,7 @@
A _function_ consists of a [block] (that's the _body_ of the function),
along with a name, a set of parameters, and an output type.
Other than a name, all these are optional.
-Functions are declared with the keyword `fn`.
+Functions are declared with the keyword `fn` which defines the given name in the [value namespace] of the module or block where it is located.
Functions may declare a set of *input* [*variables*][variables] as parameters, through which the caller passes arguments into the function, and the *output* [*type*][type] of the value the function will return to its caller on completion.
If the output type is not explicitly stated, it is the [unit type].
@@ -413,4 +413,5 @@
[method]: associated-items.md#methods
[associated function]: associated-items.md#associated-functions-and-methods
[implementation]: implementations.md
+[value namespace]: ../names/namespaces.md
[variadic function]: external-blocks.md#variadic-functions
diff --git a/src/items/generics.md b/src/items/generics.md
index 65f17bd..9b75659 100644
--- a/src/items/generics.md
+++ b/src/items/generics.md
@@ -48,12 +48,8 @@
### Const generics
-*Const generic parameters* allow items to be generic over constant values. The
-const identifier introduces a name for the constant parameter, and all
-instances of the item must be instantiated with a value of the given type.
-
-<!-- TODO: update above to say "introduces a name in the [value namespace]"
- once namespaces are added. -->
+*Const generic parameters* allow items to be generic over constant values.
+The const identifier introduces a name in the [value namespace] for the constant parameter, and all instances of the item must be instantiated with a value of the given type.
The only allowed types of const parameters are `u8`, `u16`, `u32`, `u64`, `u128`, `usize`,
`i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `char` and `bool`.
@@ -282,6 +278,7 @@
[slices]: ../types/slice.md
[associated const]: associated-items.md#associated-constants
[associated type]: associated-items.md#associated-types
+[attributes]: ../attributes.md
[block]: ../expressions/block-expr.md
[const contexts]: ../const_eval.md#const-context
[const expression]: ../const_eval.md#constant-expressions
@@ -307,4 +304,4 @@
[type aliases]: type-aliases.md
[type]: ../types.md
[unions]: unions.md
-[attributes]: ../attributes.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/modules.md b/src/items/modules.md
index 2a0ad55..e709f52 100644
--- a/src/items/modules.md
+++ b/src/items/modules.md
@@ -34,11 +34,9 @@
}
```
-Modules and types share the same namespace. Declaring a named type with the
-same name as a module in scope is forbidden: that is, a type definition, trait,
-struct, enumeration, union, type parameter or crate can't shadow the name of a
-module in scope, or vice versa. Items brought into scope with `use` also have
-this restriction.
+Modules are defined in the [type namespace] of the module or block where they are located.
+It is an error to define multiple items with the same name in the same namespace within a module.
+See the [scopes chapter] for more details on restrictions and shadowing behavior.
The `unsafe` keyword is syntactically allowed to appear before the `mod`
keyword, but it is rejected at a semantic level. This allows macros to consume
@@ -149,7 +147,9 @@
[attribute]: ../attributes.md
[items]: ../items.md
[module path]: ../paths.md
+[scopes chapter]: ../names/scopes.md
[the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
+[type namespace]: ../names/namespaces.md
<script>
(function() {
diff --git a/src/items/static-items.md b/src/items/static-items.md
index d1e4618..343d30c 100644
--- a/src/items/static-items.md
+++ b/src/items/static-items.md
@@ -11,6 +11,8 @@
other lifetimes in a Rust program. Static items do not call [`drop`] at the
end of the program.
+The static declaration defines a static value in the [value namespace] of the module or block where it is located.
+
The static initializer is a [constant expression] evaluated at compile time.
Static initializers may refer to other statics.
@@ -136,3 +138,4 @@
[IDENTIFIER]: ../identifiers.md
[_Type_]: ../types.md#type-expressions
[_Expression_]: ../expressions.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/structs.md b/src/items/structs.md
index 9523e7b..e59d7e9 100644
--- a/src/items/structs.md
+++ b/src/items/structs.md
@@ -37,6 +37,7 @@
> [_Type_]
A _struct_ is a nominal [struct type] defined with the keyword `struct`.
+A struct declaration defines the given name in the [type namespace] of the module or block where it is located.
An example of a `struct` item and its use:
@@ -46,11 +47,10 @@
let px: i32 = p.x;
```
-A _tuple struct_ is a nominal [tuple type], also defined with the keyword
-`struct`. For example:
-
-[struct type]: ../types/struct.md
-[tuple type]: ../types/tuple.md
+A _tuple struct_ is a nominal [tuple type], and is also defined with the keyword `struct`.
+In addition to defining a type, it also defines a constructor of the same name in the [value namespace].
+The constructor is a function which can be called to create a new instance of the struct.
+For example:
```rust
struct Point(i32, i32);
@@ -59,7 +59,7 @@
```
A _unit-like struct_ is a struct without any fields, defined by leaving off the
-list of fields entirely. Such a struct implicitly defines a constant of its
+list of fields entirely. Such a struct implicitly defines a [constant] of its
type with the same name. For example:
```rust
@@ -78,11 +78,15 @@
The precise memory layout of a struct is not specified. One can specify a
particular layout using the [`repr` attribute].
-[`repr` attribute]: ../type-layout.md#representations
-
-[_OuterAttribute_]: ../attributes.md
-[IDENTIFIER]: ../identifiers.md
[_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
-[_Visibility_]: ../visibility-and-privacy.md
+[_OuterAttribute_]: ../attributes.md
[_Type_]: ../types.md#type-expressions
+[_Visibility_]: ../visibility-and-privacy.md
+[_WhereClause_]: generics.md#where-clauses
+[`repr` attribute]: ../type-layout.md#representations
+[IDENTIFIER]: ../identifiers.md
+[constant]: constant-items.md
+[struct type]: ../types/struct.md
+[tuple type]: ../types/tuple.md
+[type namespace]: ../names/namespaces.md
+[value namespace]: ../names/namespaces.md
diff --git a/src/items/traits.md b/src/items/traits.md
index a74d7cb..cb6c6f9 100644
--- a/src/items/traits.md
+++ b/src/items/traits.md
@@ -17,6 +17,9 @@
- [types](associated-items.md#associated-types)
- [constants](associated-items.md#associated-constants)
+The trait declaration defines a trait in the [type namespace] of the module or block where it is located.
+Associated items are defined as members of the trait within their respective namespaces. Associated types are defined in the type namespace. Associated constants and associated functions are defined in the value namespace.
+
All traits define an implicit type parameter `Self` that refers to "the type
that is implementing this interface". Traits may also contain additional type
parameters. These type parameters, including `Self`, may be constrained by
@@ -345,3 +348,4 @@
[`Rc<Self>`]: ../special-types-and-traits.md#rct
[`async`]: functions.md#async-functions
[`const`]: functions.md#const-functions
+[type namespace]: ../names/namespaces.md
diff --git a/src/items/type-aliases.md b/src/items/type-aliases.md
index 24c6f4e..ef3e6fc 100644
--- a/src/items/type-aliases.md
+++ b/src/items/type-aliases.md
@@ -6,10 +6,9 @@
> ( `:` [_TypeParamBounds_] )<sup>?</sup>
> [_WhereClause_]<sup>?</sup> ( `=` [_Type_] [_WhereClause_]<sup>?</sup>)<sup>?</sup> `;`
-A _type alias_ defines a new name for an existing [type]. Type aliases are
-declared with the keyword `type`. Every value has a single, specific type, but
-may implement several different traits, or be compatible with several different
-type constraints.
+A _type alias_ defines a new name for an existing [type] in the [type namespace] of the module or block where it is located.
+Type aliases are declared with the keyword `type`.
+Every value has a single, specific type, but may implement several different traits, and may be compatible with several different type constraints.
For example, the following defines the type `Point` as a synonym for the type
`(u8, u8)`, the type of pairs of unsigned 8 bit integers:
@@ -53,3 +52,4 @@
[trait]: traits.md
[type]: ../types.md
[trait impl]: implementations.md#trait-implementations
+[type namespace]: ../names/namespaces.md
diff --git a/src/items/unions.md b/src/items/unions.md
index 049564f..ed3ba5a 100644
--- a/src/items/unions.md
+++ b/src/items/unions.md
@@ -7,6 +7,7 @@
A union declaration uses the same syntax as a struct declaration, except with
`union` in place of `struct`.
+A union declaration defines the given name in the [type namespace] of the module or block where it is located.
```rust
#[repr(C)]
@@ -179,4 +180,5 @@
[boolean type]: ../types/boolean.md
[ManuallyDrop]: ../../std/mem/struct.ManuallyDrop.html
[the C representation]: ../type-layout.md#reprc-unions
+[type namespace]: ../names/namespaces.md
[undefined behavior]: ../behavior-considered-undefined.html
diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index e2e2027..4e10960 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -13,6 +13,7 @@
some other [path]. Usually a `use` declaration is used to shorten the path
required to refer to a module item. These declarations may appear in [modules]
and [blocks], usually at the top.
+A `use` declaration is also sometimes called an _import_, or, if it is public, a _re-export_.
[path]: ../paths.md
[modules]: modules.md
@@ -21,7 +22,7 @@
Use declarations support a number of convenient shortcuts:
* Simultaneously binding a list of paths with a common prefix, using the
- glob-like brace syntax `use a::b::{c, d, e::f, g::h::i};`
+ brace syntax `use a::b::{c, d, e::f, g::h::i};`
* Simultaneously binding a list of paths with a common prefix and their common
parent module, using the `self` keyword, such as `use a::b::{self, c, d::e};`
* Rebinding the target name as a new local name, using the syntax `use p::q::r
@@ -87,75 +88,191 @@
## `use` Paths
-> **Note**: This section is incomplete.
+The [paths] that are allowed in a `use` item follow the [_SimplePath_] grammar and are similar to the paths that may be used in an expression.
+They may create bindings for:
-Some examples of what will and will not work for `use` items:
-<!-- Note: This example works as-is in either 2015 or 2018. -->
+* Nameable [items]
+* [Enum variants]
+* [Built-in types]
+* [Attributes]
+* [Derive macros]
+
+They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below.
+
+`use` will create bindings for all [namespaces] from the imported entities, with the exception that a `self` import will only import from the type namespace (as described below).
+For example, the following illustrates creating bindings for the same name in two namespaces:
```rust
-# #![allow(unused_imports)]
-use std::path::{self, Path, PathBuf}; // good: std is a crate name
-use crate::foo::baz::foobaz; // good: foo is at the root of the crate
-
-mod foo {
-
- pub mod example {
- pub mod iter {}
- }
-
- use crate::foo::example::iter; // good: foo is at crate root
-// use example::iter; // bad in 2015 edition: relative paths are not allowed without `self`; good in 2018 edition
- use self::baz::foobaz; // good: self refers to module 'foo'
- use crate::foo::bar::foobar; // good: foo is at crate root
-
- pub mod bar {
- pub fn foobar() { }
- }
-
- pub mod baz {
- use super::bar::foobar; // good: super refers to module 'foo'
- pub fn foobaz() { }
- }
+mod stuff {
+ pub struct Foo(pub i32);
}
-fn main() {}
+// Imports the `Foo` type and the `Foo` constructor.
+use stuff::Foo;
+
+fn example() {
+ let ctor = Foo; // Uses `Foo` from the value namespace.
+ let x: Foo = ctor(123); // Uses `Foo` From the type namespace.
+}
```
-> **Edition Differences**: In the 2015 edition, `use` paths also allow
-> accessing items in the crate root. Using the example above, the following
-> `use` paths work in 2015 but not 2018:
+> **Edition differences**: In the 2015 edition, `use` paths are relative to the crate root.
+> For example:
>
> ```rust,edition2015
-> # mod foo {
-> # pub mod example { pub mod iter {} }
-> # pub mod baz { pub fn foobaz() {} }
-> # }
-> use foo::example::iter;
-> use ::foo::baz::foobaz;
+> mod foo {
+> pub mod example { pub mod iter {} }
+> pub mod baz { pub fn foobaz() {} }
+> }
+> mod bar {
+> // Resolves `foo` from the crate root.
+> use foo::example::iter;
+> // The `::` prefix explicitly resolves `foo`
+> // from the crate root.
+> use ::foo::baz::foobaz;
+> }
+>
> # fn main() {}
> ```
>
> The 2015 edition does not allow use declarations to reference the [extern prelude].
-> Thus [`extern crate`] declarations are still required in 2015 to
-> reference an external crate in a use declaration. Beginning with the 2018
-> edition, use declarations can specify an external crate dependency the same
-> way `extern crate` can.
->
-> In the 2018 edition, if an in-scope item has the same name as an external
-> crate, then `use` of that crate name requires a leading `::` to
-> unambiguously select the crate name. This is to retain compatibility with
-> potential future changes. <!-- uniform_paths future-proofing -->
->
-> ```rust
-> // use std::fs; // Error, this is ambiguous.
-> use ::std::fs; // Imports from the `std` crate, not the module below.
-> use self::std::fs as self_fs; // Imports the module below.
->
-> mod std {
-> pub mod fs {}
-> }
-> # fn main() {}
-> ```
+> Thus, [`extern crate`] declarations are still required in 2015 to reference an external crate in a `use` declaration.
+> Beginning with the 2018 edition, `use` declarations can specify an external crate dependency the same way `extern crate` can.
+
+## `as` renames
+
+The `as` keyword can be used to change the name of an imported entity.
+For example:
+
+```rust
+// Creates a non-public alias `bar` for the function `foo`.
+use inner::foo as bar;
+
+mod inner {
+ pub fn foo() {}
+}
+```
+
+## Brace syntax
+
+Braces can be used in the last segment of the path to import multiple entities from the previous segment, or, if there are no previous segments, from the current scope.
+Braces can be nested, creating a tree of paths, where each grouping of segments is logically combined with its parent to create a full path.
+
+```rust
+// Creates bindings to:
+// - `std::collections::BTreeSet`
+// - `std::collections::hash_map`
+// - `std::collections::hash_map::HashMap`
+use std::collections::{BTreeSet, hash_map::{self, HashMap}};
+```
+
+An empty brace does not import anything, though the leading path is validated that it is accessible.
+<!-- This is slightly wrong, see: https://github.com/rust-lang/rust/issues/61826 -->
+
+> **Edition differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use {foo, bar};` will import the names `foo` and `bar` from the crate root, whereas starting in 2018, those names are relative to the current scope.
+
+## `self` imports
+
+The keyword `self` may be used within [brace syntax](#brace-syntax) to create a binding of the parent entity under its own name.
+
+```rust
+mod stuff {
+ pub fn foo() {}
+ pub fn bar() {}
+}
+mod example {
+ // Creates a binding for `stuff` and `foo`.
+ use crate::stuff::{self, foo};
+ pub fn baz() {
+ foo();
+ stuff::bar();
+ }
+}
+# fn main() {}
+```
+
+`self` only creates a binding from the [type namespace] of the parent entity.
+For example, in the following, only the `foo` mod is imported:
+
+```rust,compile_fail
+mod bar {
+ pub mod foo {}
+ pub fn foo() {}
+}
+
+// This only imports the module `foo`. The function `foo` lives in
+// the value namespace and is not imported.
+use bar::foo::{self};
+
+fn main() {
+ foo(); //~ ERROR `foo` is a module
+}
+```
+
+> **Note**: `self` may also be used as the first segment of a path.
+> The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment.
+> See [`self`] in the paths chapter for more information on the meaning of a leading `self`.
+
+## Glob imports
+
+The `*` character may be used as the last segment of a `use` path to import all importable entities from the entity of the preceding segment.
+For example:
+
+```rust
+// Creates a non-public alias to `bar`.
+use foo::*;
+
+mod foo {
+ fn i_am_private() {}
+ enum Example {
+ V1,
+ V2,
+ }
+ pub fn bar() {
+ // Creates local aliases to `V1` and `V2`
+ // of the `Example` enum.
+ use Example::*;
+ let x = V1;
+ }
+}
+```
+
+Items and named imports are allowed to shadow names from glob imports in the same [namespace].
+That is, if there is a name already defined by another item in the same namespace, the glob import will be shadowed.
+For example:
+
+```rust
+// This creates a binding to the `clashing::Foo` tuple struct
+// constructor, but does not import its type because that would
+// conflict with the `Foo` struct defined here.
+//
+// Note that the order of definition here is unimportant.
+use clashing::*;
+struct Foo {
+ field: f32,
+}
+
+fn do_stuff() {
+ // Uses the constructor from `clashing::Foo`.
+ let f1 = Foo(123);
+ // The struct expression uses the type from
+ // the `Foo` struct defined above.
+ let f2 = Foo { field: 1.0 };
+ // `Bar` is also in scope due to the glob import.
+ let z = Bar {};
+}
+
+mod clashing {
+ pub struct Foo(pub i32);
+ pub struct Bar {}
+}
+```
+
+`*` cannot be used as the first or intermediate segments.
+`*` cannot be used to import a module's contents into itself (such as `use self::*;`).
+
+> **Edition differences**: In the 2015 edition, paths are relative to the crate root, so an import such as `use *;` is valid, and it means to import everything from the crate root.
+> This cannot be used in the crate root itself.
## Underscore Imports
@@ -201,8 +318,91 @@
// use std as _;
```
-[IDENTIFIER]: ../identifiers.md
+## Restrictions
+
+The following are restrictions for valid `use` declarations:
+
+* `use crate;` must use `as` to define the name to which to bind the crate root.
+* `use {self};` is an error; there must be a leading segment when using `self`.
+* As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block.
+* `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion.
+* `use` paths cannot refer to enum variants through a [type alias]. For example:
+ ```rust,compile_fail
+ enum MyEnum {
+ MyVariant
+ }
+ type TypeAlias = MyEnum;
+
+ use MyEnum::MyVariant; //~ OK
+ use TypeAlias::MyVariant; //~ ERROR
+ ```
+
+## Ambiguities
+
+> **Note**: This section is incomplete.
+
+Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity.
+
+Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used.
+For example:
+
+```rust
+mod foo {
+ pub struct Qux;
+}
+
+mod bar {
+ pub struct Qux;
+}
+
+use foo::*;
+use bar::*; //~ OK, no name conflict.
+
+fn main() {
+ // This would be an error, due to the ambiguity.
+ //let x = Qux;
+}
+```
+
+Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example:
+
+```rust
+mod foo {
+ pub struct Qux;
+}
+
+mod bar {
+ pub use super::foo::Qux;
+}
+
+// These both import the same `Qux`. The visibility of `Qux`
+// is `pub` because that is the maximum visibility between
+// these two `use` declarations.
+pub use bar::*;
+use foo::*;
+
+fn main() {
+ let _: Qux = Qux;
+}
+```
+
[_SimplePath_]: ../paths.md#simple-paths
[`extern crate`]: extern-crates.md
+[`macro_rules`]: ../macros-by-example.md
+[`self`]: ../paths.md#self
+[associated items]: associated-items.md
+[Attributes]: ../attributes.md
+[Built-in types]: ../types.md
+[Derive macros]: ../procedural-macros.md#derive-macros
+[Enum variants]: enumerations.md
[extern prelude]: ../names/preludes.md#extern-prelude
-[path qualifiers]: ../paths.md#path-qualifiers
+[generic parameters]: generics.md
+[IDENTIFIER]: ../identifiers.md
+[items]: ../items.md
+[local variables]: ../variables.md
+[namespace]: ../names/namespaces.md
+[namespaces]: ../names/namespaces.md
+[paths]: ../paths.md
+[tool attributes]: ../attributes.md#tool-attributes
+[type alias]: type-aliases.md
+[type namespace]: ../names/namespaces.md
diff --git a/src/names/namespaces.md b/src/names/namespaces.md
index 36b2e10..b27511e 100644
--- a/src/names/namespaces.md
+++ b/src/names/namespaces.md
@@ -5,9 +5,6 @@
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.
-
There are several different namespaces that each contain different kinds of
entities. The usage of a name will look for the declaration of that name in
different namespaces, based on the context, as described in the [name
@@ -103,8 +100,6 @@
introduce aliases into multiple namespaces, depending on the item kind being
imported.
-<!-- TODO: describe how `use` works on the use-declarations page, and link to it here. -->
-
## Sub-namespaces
The macro namespace is split into two sub-namespaces: one for [bang-style macros] and one for [attributes].
diff --git a/src/paths.md b/src/paths.md
index dbc73c4..525a325 100644
--- a/src/paths.md
+++ b/src/paths.md
@@ -1,10 +1,7 @@
# Paths
-A *path* is a sequence of one or more path segments _logically_ separated by
-a namespace <span class="parenthetical">qualifier (`::`)</span>. If a path
-consists of only one segment, it refers to either an [item] or a [variable] in
-a local control scope. If a path has multiple segments, it always refers to an
-item.
+A *path* is a sequence of one or more path segments separated by `::` tokens.
+Paths are used to refer to [items], values, [types], [macros], and [attributes].
Two examples of simple paths consisting of only identifier segments:
@@ -25,8 +22,8 @@
> _SimplePathSegment_ :\
> [IDENTIFIER] | `super` | `self` | `crate` | `$crate`
-Simple paths are used in [visibility] markers, [attributes], [macros], and [`use`] items.
-Examples:
+Simple paths are used in [visibility] markers, [attributes], [macros][mbe], and [`use`] items.
+For example:
```rust
use std::io::{self, Write};
@@ -224,10 +221,18 @@
### `Self`
-`Self`, with a capital "S", is used to refer to the implementing type within
-[traits] and [implementations].
+`Self`, with a capital "S", is used to refer to the current type being implemented or defined. It may be used in the following situations:
+
+* In a [trait] definition, it refers to the type implementing the trait.
+* In an [implementation], it refers to the type being implemented.
+ When implementing a tuple or unit [struct], it also refers to the constructor in the [value namespace].
+* In the definition of a [struct], [enumeration], or [union], it refers to the type being defined.
+ The definition is not allowed to be infinitely recursive (there must be an indirection).
+
+The scope of `Self` behaves similarly to a generic parameter; see the [`Self` scope] section for more details.
`Self` can only be used as the first segment, without a preceding `::`.
+The `Self` path cannot include generic arguments (as in `Self::<i32>`).
```rust
trait T {
@@ -249,6 +254,22 @@
Self::C // `Self::C` is the constant value `9`.
}
}
+
+// `Self` is in scope within the generics of a trait definition,
+// to refer to the type being defined.
+trait Add<Rhs = Self> {
+ type Output;
+ // `Self` can also reference associated items of the
+ // type being implemented.
+ fn add(self, rhs: Rhs) -> Self::Output;
+}
+
+struct NonEmptyList<T> {
+ head: T,
+ // A struct can reference itself (as long as it is not
+ // infinitely recursive).
+ tail: Option<Box<Self>>,
+}
```
### `super`
@@ -400,19 +421,27 @@
[_Type_]: types.md#type-expressions
[_TypeNoBounds_]: types.md#type-expressions
[_TypeParamBounds_]: trait-bounds.md
-[literal]: expressions/literal-expr.md
-[item]: items.md
-[variable]: variables.md
[implementations]: items/implementations.md
+[items]: items.md
+[literal]: expressions/literal-expr.md
[use declarations]: items/use-declarations.md
[IDENTIFIER]: identifiers.md
+[`Self` scope]: names/scopes.md#self-scope
[`use`]: items/use-declarations.md
[attributes]: attributes.md
+[enumeration]: items/enumerations.md
[expressions]: expressions.md
[extern prelude]: names/preludes.md#extern-prelude
+[implementation]: items/implementations.md
[macro transcribers]: macros-by-example.md
-[macros]: macros-by-example.md
+[macros]: macros.md
+[mbe]: macros-by-example.md
[patterns]: patterns.md
+[struct]: items/structs.md
[trait implementations]: items/implementations.md#trait-implementations
+[trait]: items/traits.md
[traits]: items/traits.md
+[types]: types.md
+[union]: items/unions.md
+[value namespace]: names/namespaces.md
[visibility]: visibility-and-privacy.md
diff --git a/src/patterns.md b/src/patterns.md
index a8b09a9..0f186bf 100644
--- a/src/patterns.md
+++ b/src/patterns.md
@@ -171,7 +171,7 @@
> _IdentifierPattern_ :\
> `ref`<sup>?</sup> `mut`<sup>?</sup> [IDENTIFIER] (`@` [_PatternNoTopAlt_] ) <sup>?</sup>
-Identifier patterns bind the value they match to a variable.
+Identifier patterns bind the value they match to a variable in the [value namespace].
The identifier must be unique within the pattern.
The variable will shadow any variables of the same name in scope.
The [scope] of the new binding depends on the context of where the pattern is used (such as a `let` binding or a `match` arm).
@@ -888,3 +888,4 @@
[tuples]: types/tuple.md
[scrutinee]: glossary.md#scrutinee
[type coercions]: type-coercions.md
+[value namespace]: names/namespaces.md
diff --git a/src/procedural-macros.md b/src/procedural-macros.md
index 32b847c..c5af448 100644
--- a/src/procedural-macros.md
+++ b/src/procedural-macros.md
@@ -11,8 +11,9 @@
syntax, both consuming and producing Rust syntax. You can sort of think of
procedural macros as functions from an AST to another AST.
-Procedural macros must be defined in a crate with the [crate type] of
+Procedural macros must be defined in the root of a crate with the [crate type] of
`proc-macro`.
+The macros may not be used from the crate where they are defined, and can only be used when imported in another crate.
> **Note**: When using Cargo, Procedural macro crates are defined with the
> `proc-macro` key in your manifest:
@@ -77,6 +78,7 @@
[attribute] and a signature of `(TokenStream) -> TokenStream`. The input
[`TokenStream`] is what is inside the delimiters of the macro invocation and the
output [`TokenStream`] replaces the entire macro invocation.
+The `proc_macro` attribute defines the macro in the [macro namespace] in the root of the crate.
For example, the following macro definition ignores its input and outputs a
function `answer` into its scope.
@@ -120,6 +122,7 @@
Custom derive macros are defined by a [public] [function] with the
`proc_macro_derive` attribute and a signature of `(TokenStream) -> TokenStream`.
+The `proc_macro_derive` attribute defines the custom derive in the [macro namespace] in the root of the crate.
The input [`TokenStream`] is the token stream of the item that has the `derive`
attribute on it. The output [`TokenStream`] must be a set of items that are
@@ -206,6 +209,7 @@
[`TokenStream`] is empty. The second [`TokenStream`] is the rest of the [item]
including other [attributes] on the [item]. The returned [`TokenStream`]
replaces the [item] with an arbitrary number of [items].
+The `proc_macro_attribute` attribute defines the attribute in the [macro namespace] in the root of the crate.
For example, this attribute macro takes the input stream and returns it as is,
effectively being the no-op of attributes.
@@ -356,6 +360,7 @@
[inert]: attributes.md#active-and-inert-attributes
[item]: items.md
[items]: items.md
+[macro namespace]: names/namespaces.md
[module]: items/modules.md
[patterns]: patterns.md
[public]: visibility-and-privacy.md
