https://github.com/deanwampler/programming-scala-book-code-examples

The code examples used in Programming Scala, 2nd and 3rd Editions (O'Reilly)
https://github.com/deanwampler/programming-scala-book-code-examples

programming-scala repl sbt scala scala-metals scala3

Last synced: about 1 month ago
JSON representation

The code examples used in Programming Scala, 2nd and 3rd Editions (O'Reilly)

Host: GitHub
URL: https://github.com/deanwampler/programming-scala-book-code-examples
Owner: deanwampler
License: other
Created: 2014-06-20T16:17:57.000Z (over 11 years ago)
Default Branch: main
Last Pushed: 2025-04-30T14:29:02.000Z (10 months ago)
Last Synced: 2025-05-12T21:52:19.646Z (9 months ago)
Topics: programming-scala, repl, sbt, scala, scala-metals, scala3
Language: Scala
Homepage:
Size: 23.9 MB
Stars: 652
Watchers: 51
Forks: 408
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# "Programming Scala, 3rd Edition" Code Examples

[![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)

* [Dean Wampler](mailto:programming.scala@gmail.com)
* Dean Wampler's [Bluesky](https://bsky.app/profile/deanwampler.bsky.social), [Mastodon](https://discuss.systems/@deanwampler), and [LinkedIn](https://www.linkedin.com/in/deanwampler/) accounts.
* [Repo discussions](https://github.com/deanwampler/programming-scala-book-code-examples/discussions)
* [My Book Page](http://programming-scala.org)
* [Blog about Scala 3](https://medium.com/scala-3)

This repo contains all the code examples in O'Reilly's [Programming Scala, Third Edition](http://programming-scala.org). (The second edition is [available here](http://shop.oreilly.com/product/0636920033073.do).) There are also many code files in this distribution that aren't included in the book.

The `master` branch and the `3.X.Y` tag releases are for the third edition. The code examples for the second edition are still available. [Download the release tagged 2.1.0](https://github.com/deanwampler/programming-scala-book-code-examples/releases/tag/2.1.0) or check out the `release-2.1.0` branch. While the second edition was published for 2.11. The latest `2.1.0` release and `release-2.1.0` are updated for 2.12 and 2.13. (No more `release-2.X.Y` releases are planned.)

> [!WARNING]
> Scala 3 is evolving, as are the tools that support it. I try to keep the `main` branch up to date with the latest versions, including changing the examples as required to handle new and changed features (see, e.g., [issue #131](https://github.com/deanwampler/programming-scala-book-code-examples/issues/131)). Hence, sometimes an example (or how to run it) will be different from what you see in the book. So, if you are reading the book and want the examples exactly as they appear there, with the same tool versions used at that time, then grab the [`3.0.0-final`](https://github.com/deanwampler/programming-scala-book-code-examples/tree/3.0.0-final) release.

In particular, running a `scala` command-line program has changed as of version 3.5.0. So, for example, at the top of page 12 of the book, this command is shown for running a program at the shell prompt:

```
$ cp="target/scala-3.0.0/classes/"
$ scala -classpath $cp progscala3.introscala.Hello2 Hello Scala World!
```

Instead, use the following, where the latest Scala version (at the time of this writing...) is `3.7.4`:

```
$ cp="target/scala-3.7.4/classes/"
$ scala -classpath $cp --main-class progscala3.introscala.Hello2 -- Hello Scala World!
```

Note the required `--main-class` (or `-M`) flag before the “`main`” class `progscala3.introscala.Hello2` and the `--` to separate `scala` command arguments from your program's arguments. Change all other command-line examples in the book the same way.

However, it appears that `sbt` syntax has **not** changed when using `runMain` at the SBT prompt. So, for example, the following still works as documented in the book:

```
runMain progscala3.introscala.Hello2 Hello Scala World!
```
(Use of `sbt` is discussed further below.)

> [!TIP]
> Several sections offer troubleshooting tips if you encounter problems.

## How the Code Is Used in the Book

In the book's text, when an example corresponds to a file in this repo, the listing begins with a path in a comment with the following format:

```scala
// src/main/scala/progscala3.introscala.UpperMain1
```

Following the usual conventions, tests are in `src/test/...`.

Use these comments shown in the book to find the corresponding source file in the repo. The repo also contains *MUnit* and *ScalaCheck* unit tests to validate some of the code.

## Naming Conventions

The examples include "scripts" that are intended for interactive use in the `scala` command-line "REPL" (read, eval, print loop), for example using `sbt console` (where [`sbt`](http://www.scala-sbt.org/release/docs/Getting-Started/Setup.html) is the de facto build tool for Scala that I use). Other files are compiled.

To keep these different kinds of files straight and to support building with `sbt`, the following conventions are used for the files:

- `src/main/scala/.../*.scala` - All Scala 3 source files built with `sbt`.
- `src/test/.../*.scala` - All Scala 3 test source files built and executed with `sbt`.
- `src/script/.../*.scala` - "Script" files that won't compile with `scalac`, but can be interpreted with the `scala` REPL or used as a worksheet (see below).
- `src/*/scala-2/.../*.scala` - Some Scala 2 source files that won't compile with Scala 3. They are not built with `sbt`.

## Other Notes about the Code

You won't find many comments in the code, except of the form `// <1>`, which get converted into markers corresponding to notes in the book. All the descriptions of the code are in the book, so they aren't repeated as code comments.

Some files have sections marked like this:

```scala
// tag::section1[]
// end::section1[]
```

These are used to mark sections that are selectively included in the book. Sometimes the whole file is included in sections, while other times the file has extra bonus content that doesn't appear in the book.

## Required and Optional Tools

To build and run the examples, all you need is a recent version of the the Java SDK and [`sbt`](http://www.scala-sbt.org/release/docs/Getting-Started/Setup.html). When you run `sbt`, it will bootstrap itself with the correct version of itself, Scala, and project dependencies, which are specified in the `build.sbt` file in the root directory and other build files in the `project` directory.

Follow these [`sbt` installation instructions](http://www.scala-sbt.org/release/docs/Getting-Started/Setup.html).

If you want to install Scala separately and Scala's *Scaladocs*, go to the [scala-lang.org _Getting Started_ guide](https://docs.scala-lang.org/scala3/getting-started.html) for details. However, this isn't required.

If you want to play with the Spark example, `src/script/scala-2/progscala3/bigdata/SparkWordCount.scala`, you'll need to download a Spark distribution from [spark.apache.org](https://spark.apache.org). Assuming that `$SPARK_HOME` refers to the root directory of your Spark installation, run the following command in the root directory of this repo to start the Scala REPL with Spark enabled:

```shell
$ $SPARK_HOME/bin/spark-shell
...
scala>
```

Then copy and paste the content of `src/script/scala-2/progscala3/bigdata/SparkWordCount.scala` at the prompt. After it runs, there will be a new directory, `README.md.wordcount` with the _partition_ files of the output.

> **Tip:** For more on Spark, see my free tutorial on GitHub, [spark-scala-tutorial](https://github.com/deanwampler/spark-scala-tutorial).

### Editors, IntelliJ, Visual Studio Code, and Other IDEs

Most editors and IDEs now have some sort of Scala 3 support, either "natively" or through optional plugins:

* [IntelliJ](https://www.jetbrains.com/idea/): Either the Community or Ultimate additions will work. Install the Scala plugin, which has built-in support for `sbt`.
* [Visual Studio Code](https://code.visualstudio.com/): Use the new [Scala Metals](https://scalameta.org/metals/) plugin instead of older plugins.
* [Eclipse Scala IDE](http://scala-ide.org): Old, no longer recommended.

For other IDEs and text editors, try [Scala Metals](https://scalameta.org/metals/) first (I've used it with [Sublime Text](https://www.sublimetext.com/), for example) or the older [ENSIME](http://ensime.github.io/) project. You may also need additional, third-party tools for syntax highlighting, etc.

After installing the required plugins, load this project in your IDE, which should detect and use the `sbt` project automatically. For eclipse, run the `sbt eclipse` task to generate project files, then import them.

### Troubleshooting with IntelliJ

One reader reported a problem when trying to run examples in IntelliJ: `scalac: Flag -encoding set repeatedly`. I confirmed this problem (at the time; it may no longer be an issue...) and I fixed it as follows:

1. Open the preferences ("cmd-," on MacOS)
2. Search for "scala"
3. Select "Build, Execution, Deployment > Compiler > Scala Compiler"
4. Select the "sbt" configuration in the list of Scala build configurations.
5. Select "Additional compiler options:".
6. Remove `-encoding utf-8` from the text, since it is already in the `build.sbt` file.

After that, you should be able to select a type with a `main` and run it.

The same reader also reported errors where multiple occurrences of the same name in a `@targetName` annotation collided. I believe this happens if you use `sbt` in a terminal to compile and then allow IntelliJ to do its own build. There are probably two copies of the class files on the resulting runtime classpath. For example, I saw this error when attempting to run `sbt console` in IntelliJ's `sbt shell`, but not when I used `sbt` in a terminal window.

So, what worked for me was to only use the terminal to run `sbt clean`, then let IntelliJ build the software itself, but when I need to use `sbt console`, I use a terminal window.

### Using Scala Worksheets

If you like working with _Scala worksheets_ in your IDE or editor, you may be able to load any of the REPL "script" files under `src/script` as a worksheet. If your environment is more restrictive, for example about the file extension used, then run the included `bash` script `./make-worksheets.sh` to copy all the REPL "script" examples to worksheet files. This command copies the tree `src/script` to `src/worksheet` and changes the `.scala` extension for all the files to `.worksheet.sc`, the VSCode convention. These behaviors are configurable. Use the `--help` option to see the details. If you are using Windows and you don't have `bash` available, e.g., through the Linux subsystem, then modify individual files as you see fit.

See this [Dotty documentation page](https://dotty.epfl.ch/docs/usage/worksheet-mode.html) for more information about worksheets.

## Building the Code Examples

After installing `sbt`, open a command/terminal window and run the `sbt test` command.

You'll see lots of output as it downloads all the dependencies, compiles the code and runs the tests. You should see `[success]` messages at the end.

`sbt` is discussed in more detail in the book and the [`sbt` website](https://www.scala-sbt.org/), but a few useful commands are worth mentioning here.

If you start `sbt` without any arguments, it puts you into an interactive mode where you can type commands. Use control-D to exit this mode. Once at the `sbt` prompt (`sbt:programming-scala-3rd-ed-code-examples>`), try the following commands, where each `#` starts a comment; don't type those!

```
help # help on tasks and settings
clean # delete all build outputs
compile # compile the source, but not test code
test # compile source and test code, if necessary and run the tests.
~test # continuously compile and test when source changes are saved.
console # run the Scala REPL; dependencies and code are on the CLASSPATH
tasks # show the most common tasks (commands).
tasks -V # REALLY show ALL tasks
```

The `~` prefix causes the task to be run continuously each time source code changes are saved. This promotes continuous TDD (test-driven development) and is one of my favorite features!

Outside of `sbt`, you could, in principle, run the REPL and load the script files manually at the prompt, for example:

```shell
$ scala
scala> :load src/script/scala/progscala3/introscala/Upper1.scala
```

However, it's easier to run most of the scripts using `sbt console`, because `sbt` will configure the `CLASSPATH` with the third-party libraries and compiled code examples that a script file might use.

Also, new for the Scala 3 REPL, for those `src/main/...` files that define one (and only one) _entry point_, meaning a `main` method (Scala 2 compatible) or annotated with `@main` (new Scala 3 technique), you can compile and run them in one step, for example:

```shell
$ scala src/main/scala/progscala3/introscala/UpperMain2.scala -- Hello World!
HELLO WORLD!
$
```

> [!NOTE]
> The `--` argument separator is required for Scala 3.5.0 and later. It is not used for Scala 3.4.X and earlier.

### Testing the Scala Scripts and "Mains"

There are a lot of _script_ files under `src/script/scala/...`, which are used in the book as suggestions to try in the console as you are reading the book. However, they are hard to test in the usual way. Similarly, there are many `@main` routines and they are also not covered by tests. So, to "semi-automate" testing them, try the following two `zsh` scripts, both of which take a long time to run:

```shell
check-scripts.sh
check-mains.sh
```

Both have `--help` options to see what options they accept. Both do their best to check that the output is expected, but a complication is the fact that many of the Scala scripts and "mains" have deliberate errors for illustrative purposes. The `check-*.sh` scripts attempt to compensate for this, for example by knowing which scripts should fail and allowing them to fail "successfully", but to be _absolutely certain_ all the examples are running correctly, it is really necessary to visually inspect the saved output from the runs (as described in console output of the `check-*.sh`) to see if the results _look_ correct.

## Feedback

I welcome feedback on the Book and these examples. Please post comments, corrections, etc. to one of the following places:

* This GitHub repo's [discussion forum](https://github.com/deanwampler/programming-scala-book-code-examples/discussions) or [post an issue](https://github.com/deanwampler/programming-scala-book-code-examples/issues).
* The [O'Reilly book page](https://oreil.ly/programming-scala-3) and the [errata page](https://www.oreilly.com/catalog/errata.csp?isbn=9781492077893).
* Dean Wampler's [Bluesky](https://bsky.app/profile/deanwampler.bsky.social), [Mastodon](https://discuss.systems/@deanwampler), or [LinkedIn](https://www.linkedin.com/in/deanwampler/) accounts.

There is also my dedicated site for the book where occasional updates, clarifications, corrections, and lame excuses will be posted: [programming-scala.org](http://programming-scala.org).

## A Little History

Some milestones (but probably not all of them...).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/deanwampler/programming-scala-book-code-examples

Awesome Lists containing this project

README