Start Date: 2014-06-12
RFC PR #: https://github.com/rust-lang/rfcs/pull/116
Rust Issue #: https://github.com/rust-lang/rust/issues/16464

Summary

Remove or feature gate the shadowing of view items on the same scope level, in order to have less complicated semantic and be more future proof for module system changes or experiments.

This means the names brought in scope by extern crate and use may never collide with each other, nor with any other item (unless they live in different namespaces). Eg, this will no longer work:

extern crate foo;
use foo::bar::foo; // ERROR: There is already a module `foo` in scope

Shadowing would still be allowed in case of lexical scoping, so this continues to work:

extern crate foo;

fn bar() {
    use foo::bar::foo; // Shadows the outer foo

    foo::baz();
}

Definitions

Due to a certain lack of official, clearly defined semantics and terminology, a list of relevant definitions is included:

Scope A scope in Rust is basically defined by a block, following the rules of lexical scoping:
```
scope 1 (visible: scope 1)
{
      scope 1-1 (visible: scope 1, scope 1-1)
      {
          scope 1-1-1 (visible: scope 1, scope 1-1, scope 1-1-1)
      }
      scope 1-1
      {
          scope 1-1-2
      }
      scope 1-1
}
scope 1
```
Blocks include block expressions, fn items and mod items, but not things like extern, enum or struct. Additionally, mod is special in that it isolates itself from parent scopes.
Scope Level Anything with the same name in the example above is on the same scope level. In a scope level, all names defined in parent scopes are visible, but can be shadowed by a new definition with the same name, which will be in scope for that scope itself and all its child scopes.
Namespace Rust has different namespaces, and the scoping rules apply to each one separately. The exact number of different namespaces is not well defined, but they are roughly
- types (enum Foo {})
- modules (mod foo {})
- item values (static FOO: uint = 0;)
- local values (let foo = 0;)
- lifetimes (impl<'a> ...)
- macros (macro_rules! foo {...})
Definition Item Declarations that create new entities in a crate are called (by the author) definition items. They include struct, enum, mod, fn, etc. Each of them creates a name in the type, module, item value or macro namespace in the same scope level they are written in.
View Item Declarations that just create aliases to existing declarations in a crate are called view items. They include use and extern crate, and also create a name in the type, module, item value or macro namespace in the same scope level they are written in.
Item Both definition items and view items together are collectively called items.
Shadowing While the principle of shadowing exists in all namespaces, there are different forms of it:
- item-style: Declarations shadow names from outer scopes, and are visible everywhere in their own, including lexically before their own definition. This requires there to be only one definition with the same name and namespace per scope level. Types, modules, item values and lifetimes fall under these rules.
- sequentially: Declarations shadow names that are lexically before them, both in parent scopes and their own. This means you can reuse the same name in the same scope, but a definition will not be visibly before itself. This is how local values and macros work. (Due to sequential code execution and parsing, respectively)
- view item: A special case exists with view items; In the same scope level, extern crate creates entries in the module namespace, which are shadowable by names created with use, which are shadowable with any definition item. The singular goal of this RFC is to remove this shadowing behavior of view items

Motivation

As explained above, what is currently visible under which namespace in a given scope is determined by a somewhat complicated three step process:

First, every extern crate item creates a name in the module namespace.
Then, every use can create a name in any namespace, shadowing the extern crate ones.
Lastly, any definition item can shadow any name brought in scope by both extern crate and use.

These rules have developed mostly in response to the older, more complicated import system, and the existence of wildcard imports (use foo::*). In the case of wildcard imports, this shadowing behavior prevents local code from breaking if the source module gets updated to include new names that happen to be defined locally.

However, wildcard imports are now feature gated, and name conflicts in general can be resolved by using the renaming feature of extern crate and use, so in the current non-gated state of the language there is no need for this shadowing behavior.

Gating it off opens the door to remove it altogether in a backwards compatible way, or to re-enable it in case wildcard imports are officially supported again.

It also makes the mental model around items simpler: Any shadowing of items happens through lexical scoping only, and every item can be considered unordered and mutually recursive.

If this RFC gets accepted, a possible next step would be a RFC to lift the ordering restriction between extern crate, use and definition items, which would make them truly behave the same in regard to shadowing and the ability to be reordered. It would also lift the weirdness of use foo::bar; mod foo;.

Implementing this RFC would also not change anything about how name resolution works, as its just a tightening of the existing rules.

Drawbacks

Feature gating import shadowing might break some code using #[feature(globs)].
The behavior of libstds prelude becomes more magical if it still allows shadowing, but this could be de-magified again by a new feature, see below in unresolved questions.
Or the utility of libstds prelude becomes more restricted if it doesn’t allow shadowing.

Detailed design

A new feature gate import_shadowing gets created.

During the name resolution phase of compilation, every time the compiler detects a shadowing between extern crate, use and definition items in the same scope level, it bails out unless the feature gate got enabled. This amounts to two rules:

Items in the same scope level and either the type, module, item value or lifetime namespace may not shadow each other in the respective namespace.
Items may shadow names from outer scopes in any namespace.

Just like for the globs feature, the libstd prelude import would be preempt from this, and still be allowed to be shadowed.

Alternatives

The alternative is to do nothing, and risk running into a backwards compatibility hazard, or committing to make a final design decision around the whole module system before 1.0 gets released.

Unresolved questions

It is unclear how the libstd preludes fits into this.

On the one hand, it basically acts like a hidden use std::prelude::*; import which ignores the globs feature, so it could simply also ignore the import_shadowing feature as well, and the rule becomes that the prelude is a magic compiler feature that injects imports into every module but doesn’t prevent the user from taking the same names.

On the other hand, it is also thinkable to simply forbid shadowing of prelude items as well, as defining things with the same name as std exports is not recommended anyway, and this would nicely enforce that. It would however mean that the prelude can not change without breaking backwards compatibility, which might be too restricting.

A compromise would be to specialize wildcard imports into a new prelude use feature, which has the explicit properties of being shadow-able and using a wildcard import. libstds prelude could then simply use that, and users could define and use their own preludes as well. But that’s a somewhat orthogonal feature, and should be discussed in its own RFC.
Interaction with overlapping imports.

Right now its legal to write this:

fn main() { use Bar = std::result::Result; use Bar = std::option::Option; let x: Bar = None; }

where the latter `use` shadows the former. This would have to be forbidden as well,
however the current semantic seems like a accident anyway.