Specify and describe new indentation rules

odersky · odersky · commit fc76dc87792a · 2020-01-18T12:22:35.000+01:00
diff --git a/docs/docs/internals/syntax.md b/docs/docs/internals/syntax.md
@@ -83,6 +83,7 @@ comment          ::=  ‘/*’ “any sequence of characters; nested comments ar
 
 nl               ::=  “new line character”
 semi             ::=  ‘;’ |  nl {nl}
+colonEol         ::=  ": at end of line that can start a tenmplate body"
 ```
 
 ## Keywords
@@ -149,7 +150,7 @@ FunArgTypes       ::=  InfixType
 TypedFunParam     ::=  id ‘:’ Type
 MatchType         ::=  InfixType `match` ‘{’ TypeCaseClauses ‘}’
 InfixType         ::=  RefinedType {id [nl] RefinedType}                        InfixOp(t1, op, t2)
-RefinedType       ::=  WithType {[nl] Refinement}                               RefinedTypeTree(t, ds)
+RefinedType       ::=  WithType {[nl | colonEol] Refinement}                    RefinedTypeTree(t, ds)
 WithType          ::=  AnnotType {‘with’ AnnotType}                             (deprecated)
 AnnotType         ::=  SimpleType {Annotation}                                  Annotated(t, annot)
 SimpleType        ::=  SimpleType TypeArgs                                      AppliedTypeTree(t, args)
@@ -402,7 +403,8 @@ ConstrExpr        ::=  SelfInvocation
                     |  ‘{’ SelfInvocation {semi BlockStat} ‘}’
 SelfInvocation    ::=  ‘this’ ArgumentExprs {ArgumentExprs}
 
-TemplateBody      ::=  [nl] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’      (self, stats)
+TemplateBody      ::=  [nl | colonEol]
+                       ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’      (self, stats)
 TemplateStat      ::=  Import
                     |  Export
                     |  {Annotation [nl]} {Modifier} Def
@@ -412,7 +414,8 @@ TemplateStat      ::=  Import
 SelfType          ::=  id [‘:’ InfixType] ‘=>’                                  ValDef(_, name, tpt, _)
                     |  ‘this’ ‘:’ InfixType ‘=>’
 
-EnumBody          ::=  [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
+EnumBody          ::=  [nl | colonEol]
+                       ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
 EnumStat          ::=  TemplateStat
                     |  {Annotation [nl]} {Modifier} EnumCase
 EnumCase          ::=  ‘case’ (id ClassConstr [‘extends’ ConstrApps]] | ids)
@@ -424,7 +427,7 @@ TopStat           ::=  Import
                     |  Packaging
                     |  PackageObject
                     |
-Packaging         ::=  ‘package’ QualId [nl] ‘{’ TopStatSeq ‘}’                 Package(qid, stats)
+Packaging         ::=  ‘package’ QualId [nl | colonEol] ‘{’ TopStatSeq ‘}’      Package(qid, stats)
 PackageObject     ::=  ‘package’ ‘object’ ObjectDef                             object with package in mods.
 
 CompilationUnit   ::=  {‘package’ QualId semi} TopStatSeq                       Package(qid, stats)
diff --git a/docs/docs/reference/other-new-features/indentation-new.md b/docs/docs/reference/other-new-features/indentation-new.md
@@ -58,10 +58,10 @@ There are two rules:
     An indentation region can start
 
      - after the condition of an `if-else`, or
-     - after the leading parameter(s) of a given extension method clause, or
+     - after a ": at end of line" token (see below)
      - after one of the following tokens:
     ```
-    =  =>  <-  :  if  then  else  while  do  try  catch  finally  for  yield  match  return
+    =  =>  <-  if  then  else  while  do  try  catch  finally  for  yield  match  return
     ```
     If an `<indent>` is inserted, the indentation width of the token on the next line
     is pushed onto `IW`, which makes it the new current indentation width.
@@ -90,65 +90,57 @@ if x < 0
 Indentation tokens are only inserted in regions where newline statement separators are also inferred:
 at the toplevel, inside braces `{...}`, but not inside parentheses `(...)`, patterns or types.
 
-### New Role of With
+### Optional Braces Around Template Bodies
 
-To make bracews optional for constructs like class bodies, the syntax of the language is changed so that a class body or similar construct may optionally be prefixed with `with`. Since `with` can start an indentation region, this means that all of the following syntaxes are allowed and are equivalent:
-```scala
-trait A {
-  def f: Any
-}
-class C(x: Int) extends A {
-  def f = x
-}
-type T = A {
-  def f: Int
-}
-```
----
-```scala
-trait A: {
-  def f: Int
-}
-class C(x: Int) extends A: {
-  def f = x
-}
-type T = A: {
-  def f: Int
-}
-```
----
+The Scala grammar uses the term _template body_ for the definitions of a class, trait, object, given instance or extension that are normally enclosed in braces. The braces around a template body can also be omitted by means of the following rule:
+
+If at the point where a template body can start there is a `:` that occurs at the end
+of a line, and that is followed by at least one indented statement, the recognized
+token is changed from ":" to ": at end of line". The latter token is one of the tokens
+that can start an indentation region. The Scala grammar is changed so an optional ": at end of line" is allowed in front of a template body.
+
+Analogous rules apply for enum bodies, type refinements, definitions in an instance creation expressions, and local packages containing nested definitions.
+
+With these new rules, the following constructs are all valid:
 ```scala
-trait A
+trait A:
   def f: Int
 
-class C(x: Int) extends A with
+class C(x: Int) extends A:
   def f = x
 
-type T = A with
+object O:
+  def f = 3
+
+enum Color:
+  case Red, Green, Blue
+
+type T = A:
   def f: Int
-```
 
-The syntax changes allowing this are as follows:
-```
-TemplateBody ::=  [‘with’] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’
-EnumBody     ::=  [‘with’] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
-Packaging    ::=  ‘package’ QualId [‘with’] ‘{’ TopStatSeq ‘}’
-RefinedType  ::=  AnnotType {[‘with’] Refinement}
-```
-It is assumed here that braces following a `with` can be transparently replaced by an
-indentation region.
+given [T] with Ord[T] as Ord[List[T]]:
+  def compare(x: List[T], y: List[T]) = ???
 
-With the new indentation rules, the previously allowed syntax
-```
-class A extends B with
-                C
+extension on (xs: List[Int]):
+  def second: Int = xs.tail.head
+
+new A:
+  def f = 3
+
+package p:
+  def a = 1
+package q:
+  def b = 2
 ```
-becomes illegal since `C` above would be terated as a nested statement inside `A`. More generally, a `with` that separates parent constructors cannot be at the end of a line. One has to write
+
+The syntax changes allowing this are as follows:
 ```
-class A extends B
-           with C
+TemplateBody ::=  [colonEol] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’
+EnumBody     ::=  [colonEol] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
+Packaging    ::=  ‘package’ QualId [colonEol] ‘{’ TopStatSeq ‘}’
+RefinedType  ::=  AnnotType {[colonEol] Refinement}
 ```
-instead (or replace the "`with`" by a "`,`"). When compiling in Scala-2 mode, a migration warning is issued for the illegal syntax and a (manual) rewrite is suggested.
+Here, `colonEol` stands for ": at end of line", as described above.
 
 ### Spaces vs Tabs
 
diff --git a/docs/docs/reference/other-new-features/indentation.md b/docs/docs/reference/other-new-features/indentation.md
@@ -4,7 +4,7 @@ title: Optional Braces
 ---
 
 **Note** The syntax described in this section is currently under revision.
-[Here is the new version which will be implemented in Dotty 0.20](./indentation-new.html).
+[Here is the new version which will be implemented in Dotty 0.22](./indentation-new.html).
 
 As an experimental feature, Scala 3 treats indentation as significant and allows
 some occurrences of braces `{...}` to be optional.
