Forward-port the content of the Scala 2 book into the Scala 3 book

[julienrf]

In an effort to unify the Scala 2 and Scala 3 documentation, we would like the current Scala 3 Book to become a complete documentation of Scala, describing the whole language and detailing the specificities of Scala 2 and Scala 3 when needed. Ultimately, it will be renamed to just “Scala Book”.

To get there, we must carefully read every page of the Scala 2 book and check that its content is fully covered by its corresponding page in the Scala 3 book. If something is missing, that should be added to the Scala 3 book. And if there is no corresponding page in the Scala 3 book, it should be added to it (possibly marked as Scala 2 specific if needed).

See also #2481 for a similar issue on the unification of the Scala 2 and Scala 3 documentation.

---

Here is a checklist that tracks our progress.

• Introduction
• Prelude꞉ A Taste of Scala
• Preliminaries
• Scala Features
• Hello, World
• Hello, World - Version 2
• The Scala REPL
• Two Types of Variables
• The Type is Optional
• A Few Built-In Types
• Two Notes About Strings
• Command-Line I/O
• Control Structures
• The if/then/else Construct
• for Loops
• for Expressions
• match Expressions
• try/catch/finally Expressions
• Scala Classes
• Auxiliary Class Constructors
• Supplying Default Values for Constructor Parameters
• A First Look at Scala Methods
• Enumerations (and a Complete Pizza Class)
• Scala Traits and Abstract Classes
• Using Scala Traits as Interfaces
• Using Scala Traits Like Abstract Classes
• Abstract Classes
• Scala Collections
• The ArrayBuffer Class
• The List Class
• The Vector Class
• The Map Class
• The Set Class
• Anonymous Functions
• Common Sequence Methods
• Common Map Methods
• A Few Miscellaneous Items
• Tuples
• An OOP Example
• sbt and ScalaTest
• The most used scala build tool (sbt)
• Using ScalaTest with sbt
• Writing BDD Style Tests with ScalaTest and sbt
• Functional Programming
• Pure Functions
• Passing Functions Around
• No Null Values
• Companion Objects
• Case Classes
• Case Objects
• Functional Error Handling in Scala
• Concurrency
• Scala Futures
• Where To Go Next

[adpi2]

Prelude: A Taste of Scala

• Overview -> https://docs.scala-lang.org/scala3/book/scala-features.html#high-level-features
• Hello, world -> https://docs.scala-lang.org/scala3/book/taste-hello-world.html
• The Scala REPL -> https://docs.scala-lang.org/scala3/book/taste-repl.html
• Two types of variables -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#two-types-of-variables
• Declaring variable types -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#declaring-variable-types
• Control structures -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html
• if/else -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#ifelse
• match expressions -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#match-expressions
• try/catch -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#trycatchfinally
• for loops and expressions -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#for-loops-and-expressions
• while and do/while -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#while-loops
• Classes -> https://docs.scala-lang.org/scala3/book/taste-modeling.html#classes
• Scala methods -> https://docs.scala-lang.org/scala3/book/taste-methods.html
• Traits -> https://docs.scala-lang.org/scala3/book/taste-modeling.html#traits
• Collections classes -> https://docs.scala-lang.org/scala3/book/taste-collections.html
• Populating lists -> https://docs.scala-lang.org/scala3/book/taste-collections.html#creating-lists
• Sequence methods -> https://docs.scala-lang.org/scala3/book/taste-collections.html#list-methods
• Tuples -> https://docs.scala-lang.org/scala3/book/taste-collections.html#tuples
• What we haven’t shown: not there but I don't think we really need it
• A bit of background: Mostly historical information: it could go to introduction

[adpi2]

• Preliminaries
  • Installing Scala -> https://docs.scala-lang.org/scala3/book/taste-intro.html
  • Comments: only in Scala for the Python Developer
  • IDEs: missing in the Scala 3 book but it is here in the Tutorials
  • Naming conventions: missing in the Scala 3 book but it is here in the Style Guide
• Scala Features -> https://docs.scala-lang.org/scala3/book/why-scala-3.html
• Hello, World -> https://docs.scala-lang.org/scala3/book/taste-hello-world.html
• Hello, World - Version 2: another page just for this -> https://docs.scala-lang.org/scala3/book/methods-main-methods.html
• The Scala REPL -> https://docs.scala-lang.org/scala3/book/taste-repl.html
• Two Types of Variables -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html
• The Type is Optional -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#declaring-variable-types
• A Few Built-In Types -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#built-in-data-types
• Two Notes About Strings -> https://docs.scala-lang.org/scala3/book/first-look-at-types.html#strings and https://docs.scala-lang.org/scala3/book/string-interpolation.html
• Command-Line I/O -> https://docs.scala-lang.org/scala3/book/taste-hello-world.html#ask-for-user-input

[gkepka]

Control Structures - Scala 3 Book and Control Structures - Scala 2 Book:

• Scala 2 version: mention in the for section that for can also be used with List[String],
• Scala 2 version: there is a subsection on the foreach method and an example of using case syntax,
• Scala 2 version: match-case example shows how to place the right side of the => in a block,
• Scala 3 version: multiple features not present in Scala 2 mentioned: for with multiple generators, guards in for, while loops, different types of patterns in match-case etc.

[sjrd]

The classes stuff is in "Domain modeling -> Tools": https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html

• Scala Classes
  • Mostly covered at https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html, but:
  • https://docs.scala-lang.org/overviews/scala-book/classes.html#val-makes-fields-read-only : there is talk about val fields in the Scala 3 book, but no real example
  • https://docs.scala-lang.org/overviews/scala-book/classes.html#class-constructors : there is a section of secondary constructors in the Scala 3 book, but no explanation of the primary constructor with the body of the class (only a tiny mention in https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#fields-and-methods)
• Auxiliary Class Constructors -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#auxiliary-constructors
• Supplying Default Values for Constructor Parameters -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#default-parameter-values
• A First Look at Scala Methods -> https://docs.scala-lang.org/scala3/book/methods-most.html
• Enumerations (and a Complete Pizza Class) -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#Enums_Scala_3_only (although there isn't a "complete Pizza class")
• Scala Traits and Abstract Classes -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#traits
• Using Scala Traits as Interfaces -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#traits
• Using Scala Traits Like Abstract Classes
  • Basics: covered in the above
  • Overriding a method: kind of https://docs.scala-lang.org/scala3/book/methods-most.html#controlling-visibility-in-classes but mostly missing
  • Mixing in multiple traits that have behaviors: missing
• Abstract Classes -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#abstract-classes (I guess good enough)

[sjrd]

• Companion Objects -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#companion-objects but a lot fewer details; mostly fine I believe, except no mention of unapply, which TBH should go to a section on pattern matching anyway
• Case Classes -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#case-classes but there are a lot fewer details
• Case Objects -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#case-objects likewise, but here it's probably good enough (we don't need case objects as enumerations, since we have enums)

[sjrd]

• sbt and ScalaTest
• The most used scala build tool (sbt) -> https://docs.scala-lang.org/scala3/book/tools-sbt.html
• Using ScalaTest with sbt
• Writing BDD Style Tests with ScalaTest and sbt

I don't think we want any of that in the Scala 3 book. For testing, we have https://docs.scala-lang.org/toolkit/testing-intro.html

[gkepka]

• Scala Collections
  • listed in https://docs.scala-lang.org/scala3/book/collections-classes.html#common-collections
• The ArrayBuffer Class
  • the description is much more compehensive than in Scala 3 version, but most is done - https://docs.scala-lang.org/scala3/book/collections-classes.html#arraybuffer
• The List Class
  • included in https://docs.scala-lang.org/scala3/book/collections-classes.html#list
• The Vector Class
  • included in https://docs.scala-lang.org/scala3/book/collections-classes.html#vector
• The Map Class
  • Scala 3 version covers the immutable Map, while Scala 2 version covers the mutable one
• The Set Class
  • Scala 3 version covers the immutable Set, while Scala 2 version covers the mutable one

[adpi2]

• Concurrency
• Scala Futures -> https://docs.scala-lang.org/scala3/book/concurrency.html

[adpi2]

• A Few Miscellaneous Items
• Tuples: I could not find anything except in the Taste of Scala > Collections > Tuples (and I don't think we should treat it as a collection). It should be under Data Types instead.
• An OOP Example -> https://docs.scala-lang.org/scala3/book/domain-modeling-fp.html#creating-a-pizzaservice-interface

[gkepka]

• Functional Programming
  • https://docs.scala-lang.org/scala3/book/fp-what-is-fp.html
• Pure Functions
  • https://docs.scala-lang.org/scala3/book/fp-pure-functions.html
• Passing Functions Around
  • https://docs.scala-lang.org/scala3/book/fp-functions-are-values.html not identical, covers the same material
• No Null Values
  • https://docs.scala-lang.org/scala3/book/fp-functional-error-handling.html
• Companion Objects
  • https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#companion-objects no example for unapply, maybe it's hidden somewhere else

[adpi2]

Functional Error Handling in Scala -> https://docs.scala-lang.org/scala3/book/fp-functional-error-handling.html

[gkepka]

Anonymous Functions -> https://docs.scala-lang.org/scala3/book/fun-anonymous-functions.html on how to define anonymous functions and https://docs.scala-lang.org/scala3/book/collections-methods.html on how to use them in collection methods
Common Sequence Methods -> https://docs.scala-lang.org/scala3/book/collections-methods.html
Common Map Methods - no corresponding page in Scala 3 version, but examples for Map methods use are in https://docs.scala-lang.org/scala3/book/collections-classes.html#maps