Update the RFC with discussion from the comment thread

Author: nrc

text/0000-name-resolution.md

@@ -36,9 +36,112 @@ At the same time, we should be able to accept more Rust programs by tweaking the
 current rules around imports and name shadowing. This should make programming
 using imports easier.
 
+
+## Some issues in Rust's name resolution
+
+Whilst name resolution is sometimes considered a simple part of the compiler,
+there are some details in Rust which make it tricky to properly specify and
+implement. Some of these may seem obvious, but the distinctions will be
+important later.
+
+* Imported vs declared names - a name can be imported (e.g., `use foo;`) or
+  declared (e.g., `fn foo ...`).
+* Single vs glob imports - a name can be explicitly (e.g., `use a::foo;`) or
+  implicitly imported (e.g., `use a::*;` where `foo` is declared in `a`).
+* Public vs private names - the visibility of names is somewhat tied up with
+  name resolution, for example in current Rust `use a::*;` only imports the
+  public names from `a`.
+* Lexical scoping - a name can be inherited from a surrounding scope, rather
+  than being declared in the current one, e.g., `let foo = ...; { foo(); }`.
+* There are different kinds of scopes - at the item level, names are not
+  inherited from outer modules into inner modules. Items may also be declared
+  inside functions and blocks within functions, with different rules from modules.
+  At the expression level, blocks (`{...}`) give explicit scope, however, from
+  the point of view of macro hygiene and region inference, each `let` statement
+  starts a new implicit scope.
+* Explicitly declared vs macro generated names - a name can be declared
+  explicitly in the source text, or could be declared as the result of expanding
+  a macro.
+* Rust has multiple namespaces - types, values, and macros exist in separate
+  namespaces (some items produce names in multiple namespaces). Imports
+  refer (implictly) to one or more names in different namespaces.
+
+  Note that all top-level (i.e., not parameters, etc.) path segments in a path
+  other than the last must be in the type namespace, e.g., in `a::b::c`, `a` and
+  `b` are assumed to be in the type namespace, and `c` may be in any namespace.
+* Rust has an implicit prelude - the prelude defines a set of names which are
+  always (unless explicitly opted-out) nameable. The prelude includes macros.
+  Names in the prelude can be shadowed by any other names.
+
+
 # Detailed design
 [design]: #detailed-design
 
+## Guiding principles
+
+We would like the following principles to hold. There may be edge cases where
+they do not, but we would like these to be as small as possible (and prefer they
+don't exist at all).
+
+#### Avoid 'time-travel' ambiguities, or different results of resolution if names
+are resolved in different orders.
+
+Due to macro expansion, it is possible for a name to be resolved and then to
+become ambiguous, or (with rules formulated in a certain way) for a name to be
+resolved, then to be amiguous, then to be resolvable again (possibly to
+different bindings).
+
+Furthermore, there is some flexibility in the order in which macros can be
+expanded. How a name resolves should be consistent under any ordering.
+
+The strongest form of this principle, I believe, is that at any stage of
+macro expansion, and under any ordering of expansions, if a name resolves to a
+binding then it should always (i.e., at any other stage of any other expansion
+series) resolve to that binding, and if resolving a name produces an error
+(n.b., distinct from not being able to resolve), it should always produce an
+error.
+
+
+#### Avoid errors due to the resolver being stuck.
+
+Errors with concrete causes and explanations are easier for the user to
+understand and to correct. If an error is caused by name resolution getting
+stuck, rather than by a concrete problem, this is hard to explain or correct.
+
+For example, if we support a rule that means that a certain glob can't be
+expanded before a macro is, but the macro can only be named via that glob
+import, then there is an obvious resolution that can't be reached due to our
+ordering constraints.
+
+
+#### The order of declarations of items should be irrelevant.
+
+I.e., names should be able to be used before they are declared. Note that this
+clearly does not hold for declarations of variables in statements inside
+function bodies.
+
+
+#### Macros should be manually expandable.
+
+Compiling a program should have the same result before and after expanding a
+macro 'by hand', so long as hygiene is accounted for.
+
+
+#### Glob imports should be manually expandable.
+
+A programmer should be able to replace a glob import with a list import that
+imports any names imported by the glob and used in the current scope, without
+changing name resolution behaviour.
+
+
+#### Visibility should not affect name resolution.
+
+Clearly, visibility affects whether a name can be used or not. However, it
+should not affect the mechanics of name resolution. I.e., changing a name from
+public to private (or vice versa), should not cause more or fewer name
+resolution errors (it may of course cause more or fewer accessibility errors).
+
+
 ## Changes to name resolution rules
 
 ### Multiple unused imports
@@ -142,9 +245,12 @@ Note that in combination with the above rule, this means non-public imports are
 imported by globs where they are private but accessible.
 
 
-### Globs and explicit names
+### Explicit names may shadow implicit names
 
-An explicit name may shadow a glob imported name without causing a name
+Here, an implicit name means a name imported via a glob or inherited from an
+outer scope (as opposed to being declared or imported directly in an inner scope).
+
+An explicit name may shadow an implicit name without causing a name
 resolution error. E.g.,
 
 ```
@@ -168,6 +274,19 @@ mod boz {
 }
 ```
 
+or
+
+```
+fn main() {
+    struct Foo; // 1.
+    {
+        struct Foo; // 2.
+
+        let x = Foo; // Ok and refers to declaration 2.
+    }
+}
+```
+
 Note that shadowing is namespace specific. I believe this is consistent with our
 general approach to name spaces. E.g.,
 
@@ -218,7 +337,61 @@ the name will continue to be valid, or there will be an error. Without this
 caveat, a name could be valid, and then after further expansion, become shadowed
 by a higher priority name.
 
-This change is discussed in [issue 31337](https://github.com/rust-lang/rust/issues/31337).
+An error is reported if there is an ambiguity between names due to the lack of
+shadowing, e.g., (this example assumes modularised macros),
+
+```
+macro_rules! foo {
+    () => {
+        macro! bar { ... }
+    }
+}
+
+mod a {
+    macro! bar { ... }
+}
+
+mod b {
+    use a::*;
+
+    foo!(); // Expands to `macro! bar { ... }`.
+
+    bar!(); // ERROR: bar is ambiguous.
+}
+```
+
+Note on the caveat: there will only be an error emitted if an ambiguous name is
+used directly or indirectly in a macro use. I.e., is the name of a macro that is
+used, or is the name of a module that is used to name a macro either in a macro
+use or in an import.
+
+Alternatives: we could emit an error even if the ambiguous name is not used, or
+as a compromise between these two, we could emit an error if the name is in the
+type or macro namespace (a name in the value namespace can never cause problems).
+
+This change is discussed in [issue 31337](https://github.com/rust-lang/rust/issues/31337)
+and on this RFC PR's comment thread.
+
+
+### Re-exports, namespaces, and visibility.
+
+(This is something of a clarification point, rather than explicitly new behaviour.
+See also discussion on [issue 31783](https://github.com/rust-lang/rust/issues/31783)).
+
+An import (`use`) or re-export (`pub use`) imports a name in all available
+namespaces. E.g., `use a::foo;` will import `foo` in the type and value
+namespaces if it is declared in those namespaces in `a`.
+
+For a name to be re-exported, it must be public, e.g, `pub use a::foo;` requires
+that `foo` is declared publicly in `a`. This is complicated by namespaces. The
+following behaviour should be followed for a re-export of `foo`:
+
+* `foo` is private in all namespaces in which it is declared - emit an error.
+* `foo` is public in all namespaces in which it is declared - `foo` is
+  re-exported in all namespaces.
+* `foo` is mixed public/private - `foo` is re-exported in the namespaces in which
+  it is declared publicly and imported but not re-exported in namespaces in which
+  it is declared privately.
 
 
 ## Changes to the implementation
@@ -243,11 +416,11 @@ the supplying module, we can add it for the importing module.
 
 We then loop over the work list and try to lookup names. If a name has exactly
 one best binding then we use it (and record the binding on a list of resolved
-names). If there are zero, or more than one possible binding, then we put it
-back on the work list. When we reach a fixed point, i.e., the work list no
-longer changes, then we are done. If the work list is empty, then
-expansion/import resolution succeeded, otherwise there are names not found, or
-ambiguous names, and we failed.
+names). If there are zero then we put it back on the work list. If there is more
+than one binding, then we record an ambiguity error. When we reach a fixed
+point, i.e., the work list no longer changes, then we are done. If the work list
+is empty, then expansion/import resolution succeeded, otherwise there are names
+not found, or ambiguous names, and we failed.
 
 As we are looking up names, we record the resolutions in the binding table. If
 the name we are looking up is for a glob import, we add bindings for every
@@ -270,8 +443,8 @@ In pseudo-code:
 // pass.
 fn parse_expand_and_resolve() {
     loop until fixed point {
+        process_names()
         loop until fixed point {
-            process_names()
             process_work_list()
         }
         expand_macros()
@@ -337,6 +510,24 @@ naming, also the macro namespace), and that we must record whether a name is due
 to macro expansion or not to abide by the caveat to the 'explicit names shadow
 glob names' rule.
 
+If Rust had a single namespace (or had some other properties), we would not have
+to distinguish between failed and unresolved imports. However, it does and we
+must. This is not clear from the pseudo-code because it elides namespaces, but
+consider the following small example:
+
+```
+use a::foo; // foo exists in the value namespace of a.
+use b::*;   // foo exists in the type namespace of b.
+```
+
+Can we resolve a use fo `foo` in type position to the import from `b`? That
+depends on whether `foo` exists in the type namespace in `a`. If we can prove
+that it does not (i.e., resolution fails) then we can use the glob import. If we
+cannot (i.e., the name is unresolved but we can't prove it will not resolve
+later), then it is not safe to use the glob import because it may be shadowed by
+the explicit import. (Note, since `foo` exists in at least the value namespace
+in `a`, there will be no error due to a bad import).
+
 In order to keep macro expansion comprehensible to programmers, we must enforce
 that all macro uses resolve to the same binding at the end of resolution as they
 do when they were resolved.
@@ -358,6 +549,10 @@ If import resolution succeeds, then we check our record of name resolutions. We
 re-resolve and check we get the same result. We can also check for un-used
 macros at this point.
 
+Note that the rules in the previous section have been carefully formulated to
+ensure that this check is sufficient to prevent temporal ambiguities. There are
+many slight variations for which this check would not be enough.
+
 ### Privacy
 
 In order to resolve imports (and in the future for macro privacy), we must be