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.

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

[adpi2]

Prelude: A Taste of Scala

• [x] Overview -> https://docs.scala-lang.org/scala3/book/scala-features.html#high-level-features
• [x] Hello, world -> https://docs.scala-lang.org/scala3/book/taste-hello-world.html
• [x] The Scala REPL -> https://docs.scala-lang.org/scala3/book/taste-repl.html
• [x] Two types of variables -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#two-types-of-variables
• [x] Declaring variable types -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#declaring-variable-types
• [x] Control structures -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html
• [x] if/else -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#ifelse
• [x] match expressions -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#match-expressions
• [x] try/catch -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#trycatchfinally
• [x] for loops and expressions -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#for-loops-and-expressions
• [x] while and do/while -> https://docs.scala-lang.org/scala3/book/taste-control-structures.html#while-loops
• [x] Classes -> https://docs.scala-lang.org/scala3/book/taste-modeling.html#classes
• [x] Scala methods -> https://docs.scala-lang.org/scala3/book/taste-methods.html
• [x] Traits -> https://docs.scala-lang.org/scala3/book/taste-modeling.html#traits
• [x] Collections classes -> https://docs.scala-lang.org/scala3/book/taste-collections.html
• [x] Populating lists -> https://docs.scala-lang.org/scala3/book/taste-collections.html#creating-lists
• [x] Sequence methods -> https://docs.scala-lang.org/scala3/book/taste-collections.html#list-methods
• [x] 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
  • [x] 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
• [x] Scala Features -> https://docs.scala-lang.org/scala3/book/why-scala-3.html
• [x] Hello, World -> https://docs.scala-lang.org/scala3/book/taste-hello-world.html
• [x] Hello, World - Version 2: another page just for this -> https://docs.scala-lang.org/scala3/book/methods-main-methods.html
• [x] The Scala REPL -> https://docs.scala-lang.org/scala3/book/taste-repl.html
• [x] Two Types of Variables -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html
• [x] The Type is Optional -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#declaring-variable-types
• [x] A Few Built-In Types -> https://docs.scala-lang.org/scala3/book/taste-vars-data-types.html#built-in-data-types
• [x] 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
• [x] 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)
• [x] Auxiliary Class Constructors -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#auxiliary-constructors
• [x] Supplying Default Values for Constructor Parameters -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#default-parameter-values
• [x] A First Look at Scala Methods -> https://docs.scala-lang.org/scala3/book/methods-most.html
• [x] 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")
• [x] Scala Traits and Abstract Classes -> https://docs.scala-lang.org/scala3/book/domain-modeling-tools.html#traits
• [x] 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
• [x] 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
• [x] 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]

• [x] 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
• [x] The List Class
  • included in https://docs.scala-lang.org/scala3/book/collections-classes.html#list
• [x] 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]

• [x] Concurrency
• [x] 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.
• [x] An OOP Example -> https://docs.scala-lang.org/scala3/book/domain-modeling-fp.html#creating-a-pizzaservice-interface

[gkepka]

• [x] Functional Programming
  • https://docs.scala-lang.org/scala3/book/fp-what-is-fp.html
• [x] Pure Functions
  • https://docs.scala-lang.org/scala3/book/fp-pure-functions.html
• [x] Passing Functions Around
  • https://docs.scala-lang.org/scala3/book/fp-functions-are-values.html not identical, covers the same material
• [x] 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