You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -10,54 +10,117 @@ without conflict. Each name is valid within a [scope], or a region of source
10
10
text where that name may be referenced. Access to certain names may be
11
11
restricted based on their [visibility].
12
12
13
-
* Names are resolved at three different stages of compilation.
14
-
*[Macros] and [use declarations] are resolved during macro expansion.
15
-
* This stage of resolution is known as "Early Resolution".
16
-
*`Type::assoc_item`, `<Type>::assoc_item`, `<Enum>::Variant` and `EnumTyAlias::Variant` are resolved during type checking
17
-
*`Trait::assoc_item`, `<Type as Trait>::assoc_item` and `Enum::Variant` are resolved during late resolution
18
-
* This stage of resolution is known as type-relative resolution.
19
-
* in reality this is never talked about so I doubt it has a name yet.
20
-
* All other names are resolved during AST lowering.
21
-
* This stage of resolution is known as "Late Resolution".
22
-
* Note, late resolution occurs before type dependent resolution.
13
+
Name resolution is split into three stages throughout the compilation process.
14
+
The first stage, Expansion-time resolution, resolves all [use declarations] and
15
+
[macro invocations]. The second stage, Primary resolution, resolves all names
16
+
that have not yet been resolved that do not depend on type information to
17
+
resolve. The last stage, Type-relative resolution, resolves the remaining names
18
+
once type information is available.
19
+
20
+
> Note
21
+
>
22
+
> * Expansion-time resolution is also known as "Early Resolution"
23
+
> * Primary resolution is also known as "Late Resolution"
24
+
25
+
r[names.resolution.expansion]
26
+
## Expansion-time name resolution
27
+
28
+
r[names.resolution.expansion.intro]
29
+
30
+
Expansion-time name resolution is the stage of name resolution necessary to
31
+
complete macro expansion and fully generate a crate's AST. This stage requires
32
+
the resolution of macro invocations and use declarations. Resolving use
33
+
declarations is required to resolve [path-based scope] macro invocations.
34
+
Resolving macro invocations is required in order to expand them.
35
+
36
+
The expansion process is iterative, alternately resolving imports, resolving
37
+
and expanding macro invocations, then repeating until there are no further
38
+
macros invocations to resolve. Once this process is completed all the imports
39
+
are resolved again to ensure that the macro expansion process did not introduce
40
+
any new ambiguious imports.
41
+
42
+
TODO: do we want to talk about this? feels like an implementation detail but
43
+
also really helps to understand certain kinds of ambiguity errors that users
44
+
can run into.
45
+
46
+
> Note
47
+
>
48
+
> This causes so called time traveling ambiguities, such as when a glob import introduces an item that is ambiguous with its own base path.
49
+
>
50
+
```rust
51
+
macro_rules!m {
52
+
() => { modbar {} }
53
+
}
54
+
55
+
modbar {
56
+
pub(crate) use m;
57
+
}
58
+
59
+
fnf() {
60
+
// * initially speculatively resolve bar to the module in the crate root
61
+
// * expansion of m introduces a second bar module inside the body of f
62
+
// * expansion-time resolution finalizes resolutions by re-resolving all
63
+
// imports and macro invocations, sees the introduced ambiguity
64
+
// and reports it as an error
65
+
bar::m!(); // ERROR `bar` is ambiguous
66
+
}
67
+
```
68
+
69
+
TODO I would like to be able to link to a path-based scope section that
70
+
discusses the various kinds of macros that can be invoked via path-based scope.
71
+
Right now the section I know of off of the top of my head lives in the macros
72
+
by example chapter.
23
73
24
-
r[names.resolution.early]
25
-
## Early name resolution
74
+
r[names.resolution.expansion.imports]
26
75
27
-
r[names.resolution.early.intro]
76
+
All use declarations are fully resolved during this stage of resolution.
77
+
Type-relative paths cannot be resolved at this stage of compilation and will
78
+
produce an error.
28
79
29
-
* early name resolution is the part of name resolution that happens during macro expansion
30
-
* early name resolution includes the resolution of imports and macros
31
-
* early name resolution is the minimum amount of resolution required to resolve macro invocations so they can be expanded.
32
-
* resolving imports is necessary to resolve macro invocations
33
-
* specifically for path-based scope macro resolutions, this can occur
34
-
either because of a `#[macro_export]`, a proc macro definition, or a
35
-
reexport of a macro in 2018 or later code.
36
-
* resolving macro invocations and tying them to macro declarations is necessary so they can be expanded
37
-
* this process is iterative and repeats until there are no remaining unexpanded macro invocations (fixed point algorithm)
38
-
* Post expansion these resolutions are checked again to ensure no new ambiguities were introduced by the expansion process
39
-
* This causes so called time traveling ambiguities, such as when a glob import introduces an item that is ambiguous with its own base path.
80
+
*`Type::assoc_item`, `<Type>::assoc_item`, `<Enum>::Variant` and `EnumTyAlias::Variant` are resolved during type checking
81
+
*`Trait::assoc_item`, `<Type as Trait>::assoc_item` and `Enum::Variant` are resolved during late resolution
40
82
41
-
TODO Document some time traveling ambiguitie examples, place in relevant ambiguity section
83
+
```rust
84
+
modmy_mod {
85
+
pubconstConst: () = ();
42
86
43
-
r[names.resolution.early.imports]
87
+
pubenumMyEnum {
88
+
MyVariant
89
+
}
44
90
45
-
* All imports are fully resolved at this point.
46
-
* imports of names that cannot be fully resolved during macro expansion, such as those depending on type information, are not supported and will produce an error.
91
+
implMyEnum {
92
+
pubconstConst: () = ();
93
+
}
47
94
48
-
TODO example of unsupported type dependent import
95
+
pubtypeTypeAlias=MyEnum;
96
+
}
49
97
50
-
r[names.resolution.early.imports.shadowing]
98
+
fnfoo() {
99
+
usemy_mod::MyEnum; // OK
100
+
usemy_mod::MyEnum::MyVariant; // OK
101
+
usemy_mod::TypeAlias; // OK
102
+
usemy_mod::TypeAlias::MyVariant; // Doesn't work
103
+
usemy_mod::MyEnum::Const; // Doesn't work
104
+
usemy_mod::Const; // OK
105
+
let_=my_mod::TypeAlias::MyVariant; // OK
106
+
let_=my_mod::MyEnum::Const; // OK
107
+
}
108
+
```
109
+
110
+
r[names.resolution.expansion.imports.shadowing]
51
111
52
112
The following is a list of situations where shadowing of use declarations is permitted:
* shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
120
+
TODO shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
121
+
122
+
The following is a list of situations where shadowing of use declarations is
123
+
_NOT_ permitted, otherwise known as ambiguity errors:
61
124
62
125
* Builtin Attributes
63
126
* Derive Helpers
@@ -74,19 +137,26 @@ r[items.use.ambiguities]
74
137
> This section is incomplete.
75
138
76
139
r[items.use.ambiguities.intro]
77
-
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.
140
+
Some situations are an error when there is an ambiguity as to which name a
141
+
`use` declaration refers. This happens when there are two name candidates that
142
+
do not resolve to the same entity where neither import is
143
+
[permitted](names.resolution.expansion.imports.shadowing) to shadow the other.
* it is an error to name an item through ambiguous use declarations
82
-
* two globs imports which both have an item matching that name where the items are different
83
-
* this is still an error even if there is a third non glob binding resolution to an item with the same name
147
+
* two globs imports which both have an item matching that name where the items are different
148
+
* this is still an error even if there is a third non glob binding resolution to an item with the same name
84
149
* it is not an error to have two glob imports which include items which would be ambiguous so long as you do not name one of those items through the ambiguous glob imports
85
150
86
151
r[items.use.ambiguities.glob]
87
152
Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used.
88
153
For example:
89
154
155
+
TODO: move this section? It's documenting a situation that _isnt_ an ambiguity
156
+
error. I've been working off of a pattern I think I saw in a few other
157
+
locations, where we have specific error sections that document all of the
158
+
reference relevant error cases associated with an some part of the language.
* macros are split into two subnamespaces, one for bang macros, and the other for attributes and derives. Resolution candidates from the incorrect subnamespace are ignored
0 commit comments