Spec: Syntax of imports.

This already includes `given` imports, although the rest of
contextual abstractions are not there yet.

Author: sjrd

docs/_spec/02-identifiers-names-and-scopes.md

@@ -74,11 +74,11 @@ The compiler supplies imports in a preamble to every source file.
 This preamble conceptually has the following form, where braces indicate nested scopes:
 
 ```scala
-import java.lang._
+import java.lang.*
 {
-  import scala._
+  import scala.*
   {
-    import Predef._
+    import Predef.*
     { /* source */ }
   }
 }
@@ -95,8 +95,8 @@ This allows redundant type aliases to be imported without introducing an ambigui
 object X { type T = annotation.tailrec }
 object Y { type T = annotation.tailrec }
 object Z {
-  import X._, Y._, annotation.{tailrec => T}  // OK, all T mean tailrec
-  @T def f: Int = { f ; 42 }                  // error, f is not tail recursive
+  import X.*, Y.*, annotation.tailrec as T  // OK, all T mean tailrec
+  @T def f: Int = { f ; 42 }                // error, f is not tail recursive
 }
 ```
 
@@ -107,7 +107,7 @@ Similarly, imported aliases of names introduced by package statements are allowe
 package p { class C }
 
 // xy.scala
-import p._
+import p.*
 package p { class X extends C }
 package q { class Y extends C }
 ```
@@ -132,27 +132,32 @@ package q {
 The following program illustrates different kinds of bindings and precedences between them.
 
 ```scala
-package p {                   // `X' bound by package clause
-import Console._              // `println' bound by wildcard import
-object Y {
-  println(s"L4: $X")          // `X' refers to `p.X' here
-  locally {
-    import q._                // `X' bound by wildcard import
-    println(s"L7: $X")        // `X' refers to `q.X' here
-    import X._                // `x' and `y' bound by wildcard import
-    println(s"L9: $x")        // `x' refers to `q.X.x' here
+package p {                     // `X' bound by package clause
+  import Console.*              // `println' bound by wildcard import
+  object Y {
+    println(s"L4: $X")          // `X' refers to `p.X' here
     locally {
-      val x = 3               // `x' bound by local definition
-      println(s"L12: $x")     // `x' refers to constant `3' here
+      import q.*                // `X' bound by wildcard import
+      println(s"L7: $X")        // `X' refers to `q.X' here
+      import X.*                // `x' and `y' bound by wildcard import
+      println(s"L9: $x")        // `x' refers to `q.X.x' here
       locally {
-        import q.X._          // `x' and `y' bound by wildcard import
-//      println(s"L15: $x")   // reference to `x' is ambiguous here
-        import X.y            // `y' bound by explicit import
-        println(s"L17: $y")   // `y' refers to `q.X.y' here
+        val x = 3               // `x' bound by local definition
+        println(s"L12: $x")     // `x' refers to constant `3' here
         locally {
-          val x = "abc"       // `x' bound by local definition
-          import p.X._        // `x' and `y' bound by wildcard import
-//        println(s"L21: $y") // reference to `y' is ambiguous here
-          println(s"L22: $x") // `x' refers to string "abc" here
-}}}}}}
+          import q.X.*          // `x' and `y' bound by wildcard import
+//        println(s"L15: $x")   // reference to `x' is ambiguous here
+          import X.y            // `y' bound by explicit import
+          println(s"L17: $y")   // `y' refers to `q.X.y' here
+          locally {
+            val x = "abc"       // `x' bound by local definition
+            import p.X.*        // `x' and `y' bound by wildcard import
+//          println(s"L21: $y") // reference to `y' is ambiguous here
+            println(s"L22: $x") // `x' refers to string "abc" here
+          }
+        }
+      }
+    }
+  }
+}
 ```

docs/_spec/04-basic-declarations-and-definitions.md

@@ -248,7 +248,7 @@ type ´t´ >: Nothing
 type ´t´ >: [´\mathit{tps'}\,´] =>> ´L´
        <: [´\mathit{tps'}\,´] =>> ´U´
   ```
-  
+
 If at least one of the ´\mathit{tps}´ contains an explicit variance annotation, then ´\mathit{tps'} = \mathit{tps}´, otherwise we infer the variance of each type parameter as with the user-written type lambda `[´\mathit{tps}\,´] =>> ´U´`.
 
 The same desugaring applies to type parameters. For instance,
@@ -695,64 +695,86 @@ completely.  It is an error if the types of two alternatives ´T_i´ and
 
 ## Import Clauses
 
-```ebnf
-Import          ::= ‘import’ ImportExpr {‘,’ ImportExpr}
-ImportExpr      ::= StableId ‘.’ (id | ‘_’ | ImportSelectors)
-ImportSelectors ::= ‘{’ {ImportSelector ‘,’}
-                    (ImportSelector | ‘_’) ‘}’
-ImportSelector  ::= id [‘=>’ id | ‘=>’ ‘_’]
 ```
+Import            ::=  ‘import’ ImportExpr {‘,’ ImportExpr}
+ImportExpr        ::= SimpleRef {‘.’ id} ‘.’ ImportSpecifier
+                    | SimpleRef `as` id
+ImportSpecifier   ::=  NamedSelector
+                    |  WildcardSelector
+                    | ‘{’ ImportSelectors ‘}’
+NamedSelector     ::=  id [(‘as’ | ’=>’) (id | ‘_’)]
+WildcardSelector  ::=  ‘*’ | ’_’ | ‘given’ [InfixType]
+ImportSelectors   ::=  NamedSelector [‘,’ ImportSelectors]
+                    |  WildCardSelector {‘,’ WildcardSelector}
+```
+
+- In a `NamedSelector`, `=>` can only be used when inside an `ImportSelectors` and is then equivalent to `as`, to be deprecated in the future.
+- In a `WildcardSelector`, `_` is equivalent to `*`, to be deprecated in the future.
+
+An `ImportSpecifier` that is a single `NamedSelector` or `WildcardSelector` is equivalent to an `‘{‘ ImportSelectors ‘}‘` list with that single selector.
+
+An import clause with multiple import expressions `import ´p_1´.´I_1, ..., p_n´.´I_n´` is interpreted as a sequence of import clauses `import ´p_1´.´I_1´; ...; import ´p_n´.´I_n´`.
 
-An import clause has the form `import ´p´.´I´` where ´p´ is a [stable identifier](03-types.html#paths) and ´I´ is an import expression.
-The import expression determines a set of names of importable members of ´p´ which are made available without qualification.
+An import clause with a single import expression has the form `import ´p´.´I´` where ´p´ is a [prefix](03-types.html#designator-types) and ´I´ is an import specifier.
+The import specifier determines a set of names of importable members of ´p´ which are made available without qualification as well as a set of importable `given` members which are made available in the implicit scope.
 A member ´m´ of ´p´ is _importable_ if it is [accessible](05-classes-and-objects.html#modifiers).
-The most general form of an import expression is a list of _import selectors_
+The most general form of an import specifier is a list of _import selectors_
 
 ```scala
-{ ´x_1´ => ´y_1, ..., x_n´ => ´y_n´, _ }
+{ ´x_1´ as ´y_1, ..., x_n´ as ´y_n´, *, given ´T_1´, ..., given ´T_m´, given }
 ```
 
-for ´n \geq 0´, where the final wildcard `‘_’` may be absent.
-It makes available each importable member `´p´.´x_i´` under the unqualified name ´y_i´. I.e. every import selector `´x_i´ => ´y_i´` renames `´p´.´x_i´` to
-´y_i´.
-If a final wildcard is present, all importable members ´z´ of ´p´ other than `´x_1, ..., x_n,y_1, ..., y_n´` are also made available under their own unqualified names.
+for ´n \geq 0´ and ´m \geq 0´, where the wildcards `‘*’` and `’given’` may be absent.
+They are decomposed into non-given selectors and given selectors.
 
-Import selectors work in the same way for type and term members.
-For instance, an import clause `import ´p´.{´x´ => ´y\,´}` renames the term
-name `´p´.´x´` to the term name ´y´ and the type name `´p´.´x´` to the type name ´y´.
+### Non-given Imports
+
+Non-given selectors make available each importable member `´p´.´x_i´` under the unqualified name ´y_i´.
+In other words, every import selector `´x_i´ as ´y_i´` renames `´p´.´x_i´` to ´y_i´.
+When `as ´y_i´` is omitted, ´y_i´ is assumed to be ´x_i´.
+If a final wildcard `‘*’` is present, all non-`given` importable members ´z´ of ´p´ other than `´x_1, ..., x_n, y_1, ..., y_n´` are also made available under their own unqualified names.
+
+Non-given import selectors work in the same way for type and term members.
+For instance, an import clause `import ´p´.{´x´ => ´y´}` renames the term name `´p´.´x´` to the term name ´y´ and the type name `´p´.´x´` to the type name ´y´.
 At least one of these two names must reference an importable member of ´p´.
 
-If the target in an import selector is a wildcard, the import selector hides access to the source member.
-For instance, the import selector `´x´ => _` “renames” ´x´ to the wildcard symbol (which is unaccessible as a name in user programs), and thereby effectively prevents unqualified access to ´x´.
+If the target in an import selector is an underscore `as _`, the import selector hides access to the source member instead of importing it.
+For instance, the import selector `´x´ as _` “renames” ´x´ to the underscore symbol (which is not accessible as a name in user programs), and thereby effectively prevents unqualified access to ´x´.
 This is useful if there is a final wildcard in the same import selector list, which imports all members not mentioned in previous import selectors.
 
-The scope of a binding introduced by an import-clause starts immediately after the import clause and extends to the end of the enclosing block, template, package clause, or compilation unit, whichever comes first.
+The scope of a binding introduced by a non-given import clause starts immediately after the import clause and extends to the end of the enclosing block, template, package clause, or compilation unit, whichever comes first.
 
-Several shorthands exist. An import selector may be just a simple name ´x´.
-In this case, ´x´ is imported without renaming, so the import selector is equivalent to `´x´ => ´x´`.
-Furthermore, it is possible to replace the whole import selector list by a single identifier or wildcard.
-The import clause `import ´p´.´x´` is equivalent to `import ´p´.{´x\,´}`, i.e. it makes available without qualification the member ´x´ of ´p´. The import clause `import ´p´._` is equivalent to `import ´p´.{_}`, i.e. it makes available without qualification all members of ´p´ (this is analogous to `import ´p´.*` in Java).
+### Given Imports
 
-An import clause with multiple import expressions `import ´p_1´.´I_1, ..., p_n´.´I_n´` is interpreted as a sequence of import clauses `import ´p_1´.´I_1´; ...; import ´p_n´.´I_n´`.
+Given selectors make available in the implicit scope all the importable `given` and `implicit` members `´p´.´x´` such that `´p.x´` is a subtype of ´T_i´.
+A bare `given` selector without type is equivalent to `given scala.Any`.
+
+The names of the given members are irrelevant for the selection, and are not made available in the normal scope of unqualified names.
 
 ###### Example
 Consider the object definition:
 
 ```scala
 object M {
-  def z = 0, one = 1
+  def z = 0
+  def one = 1
   def add(x: Int, y: Int): Int = x + y
 }
 ```
 
 Then the block
 
 ```scala
-{ import M.{one, z => zero, _}; add(zero, one) }
+{
+  import M.{one, z as zero, *}
+  add(zero, one)
+}
 ```
 
 is equivalent to the block
 
 ```scala
-{ M.add(M.z, M.one) }
+{
+  M.add(M.z, M.one)
+}
 ```