From 79dee4b8fbc36e4d5f207e89ca501ba982b8e485 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sat, 25 Jun 2016 20:48:36 +0100 Subject: [PATCH 1/9] SIP - Trailing Commas --- .../_posts/2016-06-25-trailing-commas.md | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 sips/pending/_posts/2016-06-25-trailing-commas.md diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md new file mode 100644 index 0000000000..435a03f544 --- /dev/null +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -0,0 +1,121 @@ +--- +layout: sip +disqus: true +title: SIP-NN - Trailing Commas +--- + +# SIP-NN: Trailing Commas + +**By: Dale Wijnand** + +## History + +| Date | Version | +|---------------|---------------| +| Jun 25th 2016 | Initial Draft | + +## Motivation + +When using a comma-separated sequence of elements on multiple lines, such as: + +{% highlight scala %} +Seq( + foo, + bar, + baz +) +{% endhighlight %} + +It is quite inconvenient to remove or comment out any element because one has to think about the fact that the last element mustn't have a trailing comma: + +{% highlight scala %} +Map( + foo, + bar //, +// baz +) +{% endhighlight %} + +Secondly, it is quite inconvenient to re-order the sequence, for instance if you wanted `baz` before `bar` you need to micromanage which is followed by a comma and which isn't: + +{% highlight scala %} +val xs = Seq( + foo, + baz // This isn't going to work + bar, +) +{% endhighlight %} + +Additionally, this means that there is a lot of noise in diffs, such as: + +{% highlight diff %} +@@ -4,7 +4,8 @@ + Map( + foo, + bar, +- baz ++ baz, ++ quux + ) +{% endhighlight %} + +Also such feature would massively simplify generating Scala source code. + +There is an open ticket ([SI-4986][]) where this feature was requested, referencing the fact that it facilitates code generation by tools and allows for easier sorting of the values, initially in the context of import selectors but later also for other constructs in the syntax. + +Some real-world use-cases where elements of a sequence are typically added, removed or moved are: + +* invoking constructors or methods (such as `apply` or `copy`) which present a lot of options defined with default values +* `settings(...)` arguments or elements of `libraryDependencies`, `scalacOptions` or `javaOptions` sequences in sbt + +## Design Decisions + +There are a number of different elements of the Scala syntax that are comma separated, but instead of changing them all a subset of the more useful ones was chosen: + +* tuples +* argument and parameter groups, including for implicits, for functions, methods and constructors +* import selectors + +From the spec these are: + +* SimpleExpr1, ArgumentExprs via Exprs +* ParamClause, ParamClauses via Params +* ClassParamClause, ClassParamClauses via ClassParams +* ImportSelector + +The elements that have not changed are: + +* ValDcl, VarDcl, VarDef via ids +* Type via FunctionArgTypes +* SimpleType, TypeArgs via Types +* Expr, ResultExpr via Bindings +* SimplePattern via Patterns +* TypeParamClause, FunTypeParamClause +* ImportExp +* PatDef + +## Implementation + +The implementation is a simple change to the parser, allowing for a trailing comma, for the groups detailed above, and has been proposed in [scala/scala#5245][]. + +## Drawbacks/Trade-offs + +The drawback, or trade-off, to this change is that it adds another way in which it is possible to do something in Scala. But it is the opinion of this SIP that the pragmatic advantage of being able to have trailing commas is worth this drawback. + +Given that this is a change in syntax, another drawback is that it requires changing the existing tools, such as those that parse Scala: intellij-scala, scalariform, scala.meta and scalaparse. + +## Alternatives + +As an alternative, trailing commas support could be added universally to all the comma-separated elements of the syntax. This would mean changing more (but still only in the parser), but it would make it consistent. + +As an alternative to changing the language, there already exists today a compiler plugin called [scala-commas][] that provides this feature. It also provides evidence that people would even use unsupported compiler apis and reflection to add this functionality, even when such a plugin won't compose with other plugins well. + +## References + +1. [SI-4986][] +2. [scala/scala#5245][] +3. [scala-commas][] + +[SI-4986]: https://issues.scala-lang.org/browse/SI-4986 +[scala/scala#5245]: https://github.com/scala/scala/pull/524://github.com/scala/scala/pull/5245 +[scala-commas]: https://github.com/andyscott/scala-commas From 04503bfdd8fe149618eb7976d6d39993c89f1f6c Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Wed, 10 Aug 2016 15:29:13 +0100 Subject: [PATCH 2/9] Retrofit some history events from github comment timestamps --- sips/pending/_posts/2016-06-25-trailing-commas.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 435a03f544..9bee10ca24 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -10,9 +10,12 @@ title: SIP-NN - Trailing Commas ## History -| Date | Version | -|---------------|---------------| -| Jun 25th 2016 | Initial Draft | +| Date | Version | +| ---------------|---------------------------------------------| +| Jun 25th 2016 | Initial Draft | +| Jun 27th 2016 | Added drawback of changing existing tools | +| Jun 27th 2016 | Added motivation that it simplifies codegen | +| Jun 28th 2016 | Fixed a typo | ## Motivation From 5d443f88e869c7a5be1f4f972a75b6937ea3422f Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Wed, 10 Aug 2016 15:29:47 +0100 Subject: [PATCH 3/9] Rename from SIP-NN to SIP-27 --- sips/pending/_posts/2016-06-25-trailing-commas.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 9bee10ca24..0f7f5eede0 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -1,10 +1,10 @@ --- layout: sip disqus: true -title: SIP-NN - Trailing Commas +title: SIP-27 - Trailing Commas --- -# SIP-NN: Trailing Commas +# SIP-27: Trailing Commas **By: Dale Wijnand** @@ -16,6 +16,7 @@ title: SIP-NN - Trailing Commas | Jun 27th 2016 | Added drawback of changing existing tools | | Jun 27th 2016 | Added motivation that it simplifies codegen | | Jun 28th 2016 | Fixed a typo | +| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | ## Motivation From 1035e442a00d8ef77a626a6f9f3c6f301c3dc1ff Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Wed, 10 Aug 2016 15:30:08 +0100 Subject: [PATCH 4/9] Change the scala-commas URL (repo was moved) --- sips/pending/_posts/2016-06-25-trailing-commas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 0f7f5eede0..3d64fced9a 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -17,6 +17,7 @@ title: SIP-27 - Trailing Commas | Jun 27th 2016 | Added motivation that it simplifies codegen | | Jun 28th 2016 | Fixed a typo | | Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | +| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | ## Motivation @@ -122,4 +123,4 @@ As an alternative to changing the language, there already exists today a compile [SI-4986]: https://issues.scala-lang.org/browse/SI-4986 [scala/scala#5245]: https://github.com/scala/scala/pull/524://github.com/scala/scala/pull/5245 -[scala-commas]: https://github.com/andyscott/scala-commas +[scala-commas]: https://github.com/47deg/scala-commas From 70b9cc32951a92958e9e991c768c77f0a63b5191 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Wed, 10 Aug 2016 15:30:58 +0100 Subject: [PATCH 5/9] Dial back some of the language from review --- .../_posts/2016-06-25-trailing-commas.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 3d64fced9a..454cbb2e2f 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -10,14 +10,15 @@ title: SIP-27 - Trailing Commas ## History -| Date | Version | -| ---------------|---------------------------------------------| -| Jun 25th 2016 | Initial Draft | -| Jun 27th 2016 | Added drawback of changing existing tools | -| Jun 27th 2016 | Added motivation that it simplifies codegen | -| Jun 28th 2016 | Fixed a typo | -| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | -| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | +| Date | Version | +| ---------------|----------------------------------------------| +| Jun 25th 2016 | Initial Draft | +| Jun 27th 2016 | Added drawback of changing existing tools | +| Jun 27th 2016 | Added motivation that it simplifies codegen | +| Jun 28th 2016 | Fixed a typo | +| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | +| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | +| Aug 10th 2016 | Dialed back some of the language from review | ## Motivation @@ -64,7 +65,7 @@ Additionally, this means that there is a lot of noise in diffs, such as: ) {% endhighlight %} -Also such feature would massively simplify generating Scala source code. +Also such feature would simplify generating Scala source code. There is an open ticket ([SI-4986][]) where this feature was requested, referencing the fact that it facilitates code generation by tools and allows for easier sorting of the values, initially in the context of import selectors but later also for other constructs in the syntax. @@ -113,7 +114,7 @@ Given that this is a change in syntax, another drawback is that it requires chan As an alternative, trailing commas support could be added universally to all the comma-separated elements of the syntax. This would mean changing more (but still only in the parser), but it would make it consistent. -As an alternative to changing the language, there already exists today a compiler plugin called [scala-commas][] that provides this feature. It also provides evidence that people would even use unsupported compiler apis and reflection to add this functionality, even when such a plugin won't compose with other plugins well. +As an alternative to changing the language, there already exists today a compiler plugin called [scala-commas][] that provides this feature. It also provides some evidence that people would even use unsupported compiler apis and reflection to add this functionality, even when such a plugin won't compose with other plugins well, though arguably only weak evidence as it's a young and obscure plugin. ## References From 109700b39cc0cf867b7fd0a3d193d94c08cf60ac Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sun, 4 Sep 2016 17:23:50 +0100 Subject: [PATCH 6/9] Split the motivation into sections --- sips/pending/_posts/2016-06-25-trailing-commas.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 454cbb2e2f..71d5d971b7 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -19,9 +19,12 @@ title: SIP-27 - Trailing Commas | Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | | Aug 10th 2016 | Changed scala-commas URL (repo was moved) | | Aug 10th 2016 | Dialed back some of the language from review | +| Sep 04th 2016 | Split the motivation into sections | ## Motivation +### Easy to modify lists + When using a comma-separated sequence of elements on multiple lines, such as: {% highlight scala %} @@ -52,7 +55,9 @@ val xs = Seq( ) {% endhighlight %} -Additionally, this means that there is a lot of noise in diffs, such as: +### Reduce diff noise + +Allowing trailing commas also reduces a lot of noise in diffs, such as: {% highlight diff %} @@ -4,7 +4,8 @@ @@ -65,10 +70,16 @@ Additionally, this means that there is a lot of noise in diffs, such as: ) {% endhighlight %} -Also such feature would simplify generating Scala source code. +### Simplify code generation + +Such a feature would also simplify generating Scala source code. + +### Long standing ticket There is an open ticket ([SI-4986][]) where this feature was requested, referencing the fact that it facilitates code generation by tools and allows for easier sorting of the values, initially in the context of import selectors but later also for other constructs in the syntax. +### Real-world use-cases + Some real-world use-cases where elements of a sequence are typically added, removed or moved are: * invoking constructors or methods (such as `apply` or `copy`) which present a lot of options defined with default values From 7784fadd221a826b39b69f3e80e3b08544ed6100 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sun, 4 Sep 2016 17:24:33 +0100 Subject: [PATCH 7/9] Add VCS authorship attribution to motivation --- sips/pending/_posts/2016-06-25-trailing-commas.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 71d5d971b7..1a48be1301 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -20,6 +20,7 @@ title: SIP-27 - Trailing Commas | Aug 10th 2016 | Changed scala-commas URL (repo was moved) | | Aug 10th 2016 | Dialed back some of the language from review | | Sep 04th 2016 | Split the motivation into sections | +| Sep 04th 2016 | Add VCS authorship attribution to motivation | ## Motivation @@ -70,6 +71,10 @@ Allowing trailing commas also reduces a lot of noise in diffs, such as: ) {% endhighlight %} +### VCS authorship attribution + +Using the example above, the authorship of the `baz` line would be preserved, instead of becoming that of the author of the `quux` line. + ### Simplify code generation Such a feature would also simplify generating Scala source code. From 32a18b24455a435c4b57f0e04152004a727a2611 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sun, 4 Sep 2016 17:25:01 +0100 Subject: [PATCH 8/9] Add Cross building hinderance to drawbacks --- sips/pending/_posts/2016-06-25-trailing-commas.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index 1a48be1301..bfa6d601cb 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -21,6 +21,7 @@ title: SIP-27 - Trailing Commas | Aug 10th 2016 | Dialed back some of the language from review | | Sep 04th 2016 | Split the motivation into sections | | Sep 04th 2016 | Add VCS authorship attribution to motivation | +| Sep 04th 2016 | Add Cross building hinderance to drawbacks | ## Motivation @@ -126,6 +127,8 @@ The drawback, or trade-off, to this change is that it adds another way in which Given that this is a change in syntax, another drawback is that it requires changing the existing tools, such as those that parse Scala: intellij-scala, scalariform, scala.meta and scalaparse. +Another drawback is that for projects that cross build to previous versions of Scala they would have to take into account that this feature wouldn't be available for those versions (assuming this feature isn't backported). + ## Alternatives As an alternative, trailing commas support could be added universally to all the comma-separated elements of the syntax. This would mean changing more (but still only in the parser), but it would make it consistent. From b2ab0435a2f45c3601b0c8602a6f50919836b85f Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Mon, 12 Sep 2016 10:00:27 +0100 Subject: [PATCH 9/9] Remove Cross building hinderance from drawbacks --- .../_posts/2016-06-25-trailing-commas.md | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/sips/pending/_posts/2016-06-25-trailing-commas.md b/sips/pending/_posts/2016-06-25-trailing-commas.md index bfa6d601cb..15d5a87a00 100644 --- a/sips/pending/_posts/2016-06-25-trailing-commas.md +++ b/sips/pending/_posts/2016-06-25-trailing-commas.md @@ -10,18 +10,19 @@ title: SIP-27 - Trailing Commas ## History -| Date | Version | -| ---------------|----------------------------------------------| -| Jun 25th 2016 | Initial Draft | -| Jun 27th 2016 | Added drawback of changing existing tools | -| Jun 27th 2016 | Added motivation that it simplifies codegen | -| Jun 28th 2016 | Fixed a typo | -| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | -| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | -| Aug 10th 2016 | Dialed back some of the language from review | -| Sep 04th 2016 | Split the motivation into sections | -| Sep 04th 2016 | Add VCS authorship attribution to motivation | -| Sep 04th 2016 | Add Cross building hinderance to drawbacks | +| Date | Version | +| ---------------|-------------------------------------------------| +| Jun 25th 2016 | Initial Draft | +| Jun 27th 2016 | Added drawback of changing existing tools | +| Jun 27th 2016 | Added motivation that it simplifies codegen | +| Jun 28th 2016 | Fixed a typo | +| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | +| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | +| Aug 10th 2016 | Dialed back some of the language from review | +| Sep 04th 2016 | Split the motivation into sections | +| Sep 04th 2016 | Add VCS authorship attribution to motivation | +| Sep 04th 2016 | Add Cross building hinderance to drawbacks | +| Sep 12th 2016 | Remove Cross building hinderance from drawbacks | ## Motivation @@ -127,8 +128,6 @@ The drawback, or trade-off, to this change is that it adds another way in which Given that this is a change in syntax, another drawback is that it requires changing the existing tools, such as those that parse Scala: intellij-scala, scalariform, scala.meta and scalaparse. -Another drawback is that for projects that cross build to previous versions of Scala they would have to take into account that this feature wouldn't be available for those versions (assuming this feature isn't backported). - ## Alternatives As an alternative, trailing commas support could be added universally to all the comma-separated elements of the syntax. This would mean changing more (but still only in the parser), but it would make it consistent.