Skip to content

Commit bb2e84b

Browse files
ehussehuss
committed
WIP
1 parent f8c39fe commit bb2e84b

8 files changed

+281
-0
lines changed

‎src/SUMMARY.md

+8
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,14 @@
103103

104104
- [Special types and traits](special-types-and-traits.md)
105105

106+
- [Name resolution](resolve/name-resolution.md)
107+
- [Namespaces](resolve/namespaces.md)
108+
- [Scopes](resolve/scopes.md)
109+
- [Definitions](resolve/definitions.md)
110+
- [Preludes](resolve/preludes.md)
111+
- [Paths](resolve/paths.md)
112+
- [Module and macro resolution](resolve/macros.md)
113+
106114
- [Memory model](memory-model.md)
107115
- [Memory allocation and lifetime](memory-allocation-and-lifetime.md)
108116
- [Memory ownership](memory-ownership.md)

‎src/resolve/definitions.md

+202
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Definitions
2+
3+
The definition of an element adds the element's name to its corresponding [namespace].
4+
The following is a list of elements that may introduce names:
5+
6+
7+
## Types
8+
### `mod`
9+
### `extern crate`
10+
### `struct`
11+
### `union`
12+
### `enum` (and variants)
13+
### `trait` definition
14+
### `type` alias
15+
### Associated type definition
16+
### Built-in types
17+
### Type parameters
18+
### `Self` type
19+
### Tool attribute modules
20+
extern crates will shadow tool modules.
21+
That is, a `clippy` crate will cause #[clippy::foo] to stop working (or only allow attributes from the crate).
22+
23+
## Values
24+
25+
### Function definitions
26+
### `const` definitions
27+
### `static` definitions
28+
### `struct` constructors
29+
### `enum` variant constructors
30+
### `Self` constructors
31+
### Method definitions
32+
### Associated const definitions
33+
### Local bindings
34+
#### `let`
35+
#### `if let`
36+
#### `while let`
37+
#### `for`
38+
#### `match` arms
39+
#### function parameters
40+
#### closure parameters
41+
### Captured closure variables
42+
### Loop labels
43+
44+
45+
## Macros
46+
- Invalid (reserved) names: `cfg`, `cfg_attr`, `derive` check_reserved_macro_name
47+
User cannot create:
48+
- macro_rules!
49+
- function-like procedural macro
50+
- attribute macro
51+
- derive macro
52+
- Note: helpers can define them, but they are ignored
53+
54+
55+
Invocation style influences text vs. path scope lookup:
56+
- Single segment path (`foo!`) — first textual, then path-based if not found.
57+
- Multi-segment path (`foo::bar!`) — path-based only
58+
59+
### `macro_rules!` macro
60+
See https://github.com/rust-lang/rust/issues/35896 for tons of info.
61+
May not be named `macro_rules`.
62+
Un-attributed macro_rules!:
63+
Enters (textual) scope at point of definition.
64+
Valid until end of current block (module, including nested across files `mod m;`, block-expr), including nested blocks.
65+
May shadow:
66+
- Previous macro_rules! macros.
67+
- Built-in function-like macros.
68+
- function-like proc-macro
69+
Does not shadow (somehow magically kept separate, TODO: figure out why)
70+
- built-in and proc-macro attributes, derive macros (and helpers)
71+
72+
`#[macro_use]` on `mod`:
73+
Extends textual scope of macros defined in that module to extend to the end of the parent module.
74+
TODO: This should be clarified in macros-by-example.md.
75+
76+
`#[macro_use]` on `extern crate`:
77+
Imports all macros annotated with `macro_export` into this crate's root module.
78+
(into the "prelude"? TODO: need to check which prelude)
79+
These can be shadowed by locally defined macro_rules! macros.
80+
May be used before, order doesn't matter, scope is entire crate.
81+
"in case of a conflict, the last macro imported wins."
82+
Cannot be used on `extern crate self as foo;`
83+
Can only be done in crate root.
84+
85+
86+
`#[macro_export]` on macro_rules!:
87+
Adds the macro to path-scope into the **crate root**.
88+
Order doesn't matter, may be used before defined.
89+
TODO: Note it is an error to export multiple macros of the same name. `duplicate_macro_exports`.
90+
https://github.com/rust-lang/rust/issues/35896
91+
Also clashes with proc-macro definitions.
92+
Makes it accessible from other crates (using paths).
93+
Can access within same crate from `crate::name` or `self::name` in root, etc.
94+
Interesting discussion of macro shadowing: https://github.com/rust-lang/rust/pull/50143
95+
TODO: Note that the order that they are added to the root is not defined? That probably doesn't matter since duplicates are not allowed.
96+
TODO: `use` vs exported macro of same name, probably not allowed?
97+
Cannot be the same name as a `#[proc_macro]` in the same crate.
98+
99+
100+
### Built-in macros
101+
Macros are defined in Resolve.builtin_macros.
102+
\_\_rust_unstable_column
103+
asm
104+
assert
105+
bench
106+
cfg
107+
column
108+
compile_error
109+
concat
110+
concat_idents
111+
env
112+
file
113+
format_args
114+
format_args_nl
115+
global_asm
116+
include
117+
include_bytes
118+
include_str
119+
line
120+
log_syntax
121+
module_path
122+
option_env
123+
stringify
124+
test
125+
test_case
126+
trace_macros
127+
Plus any plugins
128+
129+
130+
### Built-in derives
131+
Derives are defined in Resolve.builtin_macros.
132+
Clone
133+
Copy
134+
Debug
135+
Decodable
136+
Default
137+
Encodable
138+
Eq
139+
Hash
140+
Ord
141+
PartialEq
142+
PartialOrd
143+
RustcDecodable
144+
RustcEncodable
145+
Send
146+
Sync
147+
148+
149+
### Built-in attributes
150+
The complete list of built-in attributes are defined in BUILTIN_ATTRIBUTES.
151+
152+
### Tool attributes
153+
### Function-like procedural macros
154+
### Derive macros
155+
### Derive macro helpers
156+
### Attribute macros
157+
158+
159+
160+
# SCRATCH NOTES
161+
162+
`mod` adds the module name in the type namespace.
163+
`mod` name scope is ….
164+
165+
`struct` adds the struct name to the type namespace, the name of the struct
166+
as a constructor function to the value namespace, and the `Self` type to
167+
the type namespace.
168+
169+
170+
171+
- Type Namespace
172+
- [`mod`] definitions
173+
- [`struct`], [`union`], [`enum`], and [`enum` variant] definitions
174+
- [`trait`] definitions
175+
- [Type aliases]
176+
- [Associated type] definitions
177+
- [Built-in types]
178+
- [Type parameters]
179+
- [`Self` type]
180+
- [Tool attribute modules]
181+
- Value Namespace
182+
- [Function] definitions
183+
- [`const`] definitions
184+
- [`static`] definitions
185+
- [`struct` constructors]
186+
- [`enum` variant constructors]
187+
- [`Self` constructors]
188+
- [Method] definitions
189+
- [Associated const] definitions
190+
- Local bindings — [`let`], [`if let`], [`while let`], [`for`], [`match`]
191+
arms, [function] parameters, [closure] parameters
192+
- Captured [closure] variables
193+
- [Loop labels]
194+
- Macro Namespace
195+
- [`macro_rules`] definitions
196+
- [Built-in macros]
197+
- [Built-in attributes]
198+
- [Tool attributes]
199+
- [Function-like procedural macros]
200+
- [Derive macros]
201+
- [Derive macro helpers]
202+
- [Attribute macros]

‎src/resolve/macros.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Module and macro resolution

‎src/resolve/name-resolution.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Name resolution
2+
3+
Elements, such as some [item definitions] or [`let` bindings], declare a name
4+
to refer to that element. _Name resolution_ is the process of tying paths and
5+
other identifiers to the declarations of those elements. Names are segregated
6+
into different [namespaces], allowing elements in different namespaces to
7+
share the same name without conflict. Each name is valid within a [scope], or
8+
a region of source text where that name may be referenced. Access to certain
9+
names may be restricted based on their [visibility].
10+
11+
[`let` bindings]: ../statements.md#let-statements
12+
[item definitions]: ../items.md
13+
[namespaces]: namespaces.md
14+
[scope]: scopes.md
15+
[visibility]: ../visibility-and-privacy.md

‎src/resolve/namespaces.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Namespaces
2+
3+
Element names are segregated into separate _namespaces_. The usage of a name
4+
will look for the declaration of that name in different namespaces, based on
5+
the context. The following is a list of namespaces, with their corresponding
6+
elements:
7+
8+
- Type Namespace
9+
- [`mod`] definitions
10+
- [`extern crate`] definitions
11+
- [`struct`], [`union`], [`enum`], and [`enum` variant] definitions
12+
- [`trait`] definitions
13+
- [Type aliases]
14+
- [Associated type] definitions
15+
- [Built-in types]
16+
- [Type parameters]
17+
- [`Self` type]
18+
- [Tool attribute modules]
19+
- Value Namespace
20+
- [Function] definitions
21+
- [`const`] definitions
22+
- [`static`] definitions
23+
- [`struct` constructors]
24+
- [`enum` variant constructors]
25+
- [`Self` constructors]
26+
- [Method] definitions
27+
- [Associated const] definitions
28+
- Local bindings — [`let`], [`if let`], [`while let`], [`for`], [`match`]
29+
arms, [function] parameters, [closure] parameters
30+
- Captured [closure] variables
31+
- [Loop labels]
32+
- Macro Namespace
33+
- [`macro_rules`] definitions
34+
- [Built-in macros]
35+
- [Built-in attributes]
36+
- [Tool attributes]
37+
- [Function-like procedural macros]
38+
- [Derive macros]
39+
- [Derive macro helpers]
40+
- [Attribute macros]
41+
42+
43+
44+
# TODO
45+
- Add lifetimes? Or does "type parameters" cover it?
46+
- Should Lifetimes be in a separate namespace?
47+
- For each *use*, document which NS(es) are consulted.
48+
- How should implementations be documented.
49+
<S<i32>>::f() path to an impl item.
50+
Only in qualified paths?
51+
But otherwise the impl block cannot be referenced AFAIK.
52+
- Explain `Tool attribute modules` in more detail.

‎src/resolve/paths.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Paths

‎src/resolve/preludes.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Preludes

‎src/resolve/scopes.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Scopes

0 commit comments

Comments
 (0)