Make given clauses come last

We now forbid given clauses followed by normal parameter clauses.
besides the syntactic awkwardness, there's also  the problem
of eta expansion. Example:
```
  trait Universe { type T }
  def f given (u: Universe) (x: u.T)
```
How should we tea expand `f`? The usual algorithm would give:
```
  (x: u.T) => (f given the[Universe])(x)
```
but that's ill typed, since `u` is not defined on the outside.

Author: odersky

compiler/src/dotty/tools/dotc/parsing/Parsers.scala

@@ -2114,15 +2114,16 @@ object Parsers {
     def typeParamClauseOpt(ownerKind: ParamOwner.Value): List[TypeDef] =
       if (in.token == LBRACKET) typeParamClause(ownerKind) else Nil
 
-    /** ClsParamClause    ::=  [nl] [‘erased’] ‘(’ [ClsParams] ‘)’
-     *                      |  ‘given’ [‘erased’] (‘(’ ClsParams ‘)’ | GivenTypes)
-     *  ClsParams         ::=  ClsParam {`' ClsParam}
-     *  ClsParam          ::=  {Annotation} [{ParamModifier} (`val' | `var') | `inline'] Param
-     *  DefParamClause    ::=  [nl] [‘erased’] ‘(’ [DefParams] ‘)’ | GivenParamClause
+    /** ClsParamClause    ::=  [‘erased’] (‘(’ ClsParams ‘)’
+     *  GivenClsParamClause::= ‘given’ [‘erased’] (‘(’ ClsParams ‘)’ | GivenTypes)
+     *  ClsParams         ::=  ClsParam {‘,’ ClsParam}
+     *  ClsParam          ::=  {Annotation}
+     *
+     *  DefParamClause    ::=  [‘erased’] (‘(’ DefParams ‘)’
      *  GivenParamClause  ::=  ‘given’ [‘erased’] (‘(’ DefParams ‘)’ | GivenTypes)
-     *  GivenTypes        ::=  RefinedType {`,' RefinedType}
-     *  DefParams         ::=  DefParam {`,' DefParam}
-     *  DefParam          ::=  {Annotation} [`inline'] Param
+     *  DefParams         ::=  DefParam {‘,’ DefParam}
+     *  DefParam          ::=  {Annotation} [‘inline’] Param
+     *
      *  Param             ::=  id `:' ParamType [`=' Expr]
      *
      *  @return   the list of parameter definitions
@@ -2204,14 +2205,16 @@ object Parsers {
     }
 
     /** ClsParamClauses   ::=  {ClsParamClause} [[nl] ‘(’ [‘implicit’] ClsParams ‘)’]
+     *                      |  {ClsParamClause} {GivenClsParamClause}
      *  DefParamClauses   ::=  {DefParamClause} [[nl] ‘(’ [‘implicit’] DefParams ‘)’]
+     *                      |  {DefParamClause} {GivenParamClause}
      *
      *  @return  The parameter definitions
      */
     def paramClauses(ofClass: Boolean = false,
                      ofCaseClass: Boolean = false,
                      ofInstance: Boolean = false): List[List[ValDef]] = {
-      def recur(firstClause: Boolean, nparams: Int): List[List[ValDef]] = {
+      def recur(firstClause: Boolean, nparams: Int, contextualOnly: Boolean): List[List[ValDef]] = {
         var initialMods = EmptyModifiers
         if (in.token == GIVEN) {
           in.nextToken()
@@ -2236,28 +2239,29 @@ object Parsers {
             }
           }
         if (in.token == LPAREN && isParamClause) {
-          if (ofInstance && !isContextual)
-            syntaxError(em"parameters of instance definitions must come after `given'")
+          if (contextualOnly && !isContextual)
+            if (ofInstance) syntaxError(em"parameters of instance definitions must come after `given'")
+            else syntaxError(em"normal parameters cannot come after `given' clauses")
           val params = paramClause(
               ofClass = ofClass,
               ofCaseClass = ofCaseClass,
               firstClause = firstClause,
               initialMods = initialMods)
           val lastClause =
             params.nonEmpty && params.head.mods.flags.is(Implicit, butNot = Given)
-          params :: (if (lastClause) Nil else recur(firstClause = false, nparams + params.length))
+          params :: (if (lastClause) Nil else recur(firstClause = false, nparams + params.length, isContextual))
         }
         else if (isContextual) {
           val tps = commaSeparated(() => annotType())
           var counter = nparams
           def nextIdx = { counter += 1; counter }
           val paramFlags = if (ofClass) Private | Local | ParamAccessor else Param
           val params = tps.map(makeSyntheticParameter(nextIdx, _, paramFlags | Synthetic | Given | Implicit))
-          params :: recur(firstClause = false, nparams + params.length)
+          params :: recur(firstClause = false, nparams + params.length, isContextual)
         }
         else Nil
       }
-      recur(firstClause = true, 0)
+      recur(firstClause = true, 0, ofInstance)
     }
 
 /* -------- DEFS ------------------------------------------- */

docs/docs/internals/syntax.md

@@ -292,16 +292,18 @@ HkTypeParam       ::=  {Annotation} [‘+’ | ‘-’] (Id[HkTypeParamClause] |
                        SubtypeBounds
 
 ClsParamClauses   ::=  {ClsParamClause} [[nl] ‘(’ [‘implicit’] ClsParams ‘)’]
-ClsParamClause    ::=  [nl] [‘erased’] ‘(’ [ClsParams] ‘)’
-                    |  ‘given’ [‘erased’] (‘(’ ClsParams ‘)’ | GivenTypes)
+                    |  {ClsParamClause} {GivenClsParamClause}
+ClsParamClause    ::=  [‘erased’] (‘(’ ClsParams ‘)’
+GivenClsParamClause::= ‘given’ [‘erased’] (‘(’ ClsParams ‘)’ | GivenTypes)
 ClsParams         ::=  ClsParam {‘,’ ClsParam}
 ClsParam          ::=  {Annotation}                                             ValDef(mods, id, tpe, expr) -- point of mods on val/var
                        [{Modifier} (‘val’ | ‘var’) | ‘inline’] Param
 Param             ::=  id ‘:’ ParamType [‘=’ Expr]
                     |  INT
 
 DefParamClauses   ::=  {DefParamClause} [[nl] ‘(’ [‘implicit’] DefParams ‘)’]
-DefParamClause    ::=  [nl] [‘erased’] ‘(’ [DefParams] ‘)’ | GivenParamClause
+                    |  {DefParamClause} {GivenParamClause}
+DefParamClause    ::=  [‘erased’] (‘(’ DefParams ‘)’
 GivenParamClause  ::=  ‘given’ [‘erased’] (‘(’ DefParams ‘)’ | GivenTypes)
 DefParams         ::=  DefParam {‘,’ DefParam}
 DefParam          ::=  {Annotation} [‘inline’] Param                            ValDef(mods, id, tpe, expr) -- point of mods at id.

docs/docs/reference/contextual/inferable-params.md

@@ -64,24 +64,25 @@ maximum(xs) given (descending given ListOrd)
 maximum(xs) given (descending given (ListOrd given IntOrd))
 ```
 
-## Mixing Given Clauses And Normal Parameters
+## Multiple Given Clauses
 
-Given clauses can be freely mixed with normal parameters.
-A given clause may be followed by a normal parameter and _vice versa_.
 There can be several given clauses in a definition. Example:
 ```scala
-def f given (u: Universe) (x: u.T) given Context = ...
-
-implied global for Universe { type T = String ... }
-implied ctx for Context { ... }
+def f given (u: Universe) given (x: u.Context) = ...
+```
+However, all `given` clauses in a definition must come after any normal parameter clauses.
+Multiple given clauses are matched left-to-right in applications. Example:
+```scala
+implied global for Universe { type Context = ... }
+implied ctx for global.Context { ... }
 ```
 Then the following calls are all valid (and normalize to the last one)
 ```scala
-f("abc")
-(f given global)("abc")
-f("abc") given ctx
-(f given global)("abc") given ctx
+f
+(f given global)
+(f given global) given ctx
 ```
+But `f given ctx` would give a type error.
 
 ## Summoning Implied Instances
 
@@ -100,13 +101,14 @@ Functions like `the` that have only context parameters are also called _context
 
 Here is the new syntax of parameters and arguments seen as a delta from the [standard context free syntax of Scala 3](http://dotty.epfl.ch/docs/internals/syntax.html).
 ```
-ClsParamClause    ::=  ...
-                    |  ‘given’ (‘(’ [ClsParams] ‘)’ | GivenTypes)
-DefParamClause    ::=  ...
-                    |  GivenParamClause
-GivenParamClause  ::=  ‘given’ (‘(’ DefParams ‘)’ | GivenTypes)
-GivenTypes        ::=  AnnotType {‘,’ AnnotType}
-
-InfixExpr         ::=  ...
-                    |  InfixExpr ‘given’ (InfixExpr | ParArgumentExprs)
+ClsParamClauses     ::=  ...
+                      |  {ClsParamClause} {GivenClsParamClause}
+GivenClsParamClause ::=  ‘given’ [‘erased’] (‘(’ ClsParams ‘)’ | GivenTypes)
+DefParamClauses     ::=  ...
+                      |  {DefParamClause} {GivenParamClause}
+GivenParamClause    ::=  ‘given’ [‘erased’] (‘(’ DefParams ‘)’ | GivenTypes)
+GivenTypes          ::=  AnnotType {‘,’ AnnotType}
+
+InfixExpr           ::=  ...
+                      |  InfixExpr ‘given’ (InfixExpr | ParArgumentExprs)
 ```

tests/neg/implicit-params.scala

@@ -1,24 +1,28 @@
 object Test {
 
   case class C(x: Int)
+  case class D(x: Int)
 
   def f(x: Int) given (c: C) = x + c.x
 
-  def g(x: Int) given (c: C) (y: Int) = x + c.x + y
+  def g0(x: Int) given (c: C) (y: Int) = x + c.x + y  // error
+
+  def g(x: Int) given (c: C) given D = x + c.x + the[D].x  // OK
 
   def h(x: Int) given () = x // error
 
-  implicit object C extends C(11)
+  implied C for C(11)
+  implied D for D(11)
 
   f(1)
   f(1) given C
   f given 2  // error
   f(1)(C)   // error
 
-  g(1)(2) // OK
-  (g(1) given C)(2) // OK
-  g(1) given 2 // error
-  g(1) given C given 2 // error
-  g(1)(C)(2) // error
-  g(1)(C) given 2 // error
+  g(1)    // OK
+  g(1) given C   // OK
+  g(1) given C given D(0) // OK
+  g(1) given D // error
+  g(1)(D) // error
+  g(1)(C)(D) // error
 }