Toolkit: MUnit, os-lib, sttp and upickle tutorials

Gemfile.lock

@@ -219,6 +219,8 @@ GEM
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.18.0)
+    nokogiri (1.14.2-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.14.2-x86_64-linux)
       racc (~> 1.4)
     octokit (4.25.1)
@@ -263,6 +265,7 @@ GEM
     zeitwerk (2.6.7)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-linux
 
 DEPENDENCIES

_config.yml

@@ -192,6 +192,14 @@ defaults:
       overview-name: "Scaladoc"
       layout: multipage-overview
       permalink: "/scala3/guides/scaladoc/:title.html"
+  -
+    scope:
+      path: "_overviews/toolkit"
+    values:
+      partof: toolkit
+      overview-name: "The Scala Toolkit"
+      layout: multipage-overview
+      permalink: "/toolkit/:title.html"
   -
     scope:
       path: "scala3"
@@ -203,6 +211,6 @@ highlighter: rouge
 permalink: /:categories/:title.html:output_ext
 baseurl:
 scala3ref: "https://docs.scala-lang.org/scala3/reference"
-exclude: ["vendor"]
+exclude: ["vendor", ".metals"]
 plugins:
   - jekyll-redirect-from

_includes/_markdown/install-munit.md

@@ -0,0 +1,42 @@
+{% altDetails install-info-box 'Getting MUnit' %}
+
+{% tabs munit-unit-test-1 class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit "latest"
+```
+
+Alternatively, you can require a specific version of MUnit:
+```scala
+//> using lib "org.scalameta::munit:1.0.0-M6"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency to the MUnit library:
+```scala
+lazy val example = project.in(file("example"))
+  .settings(
+    scalaVersion := "3.2.1",
+    libraryDependencies += "org.scalameta" %% "munit" % "1.0.0-M6" % Test
+  )
+```
+Here the `Test` configuration means that this dependency is only used by the source files in the `example/src/test` directory.
+This is where you can put your test suites.
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add a `test` object extending `Tests` and `TestModule.Munit`:
+```scala
+object example extends ScalaModule {
+  def scalaVersion = "3.2.1"
+  object test extends Tests with TestModule.Munit {
+    def ivyDeps =
+      Agg(
+        ivy"org.scalameta::munit::1.0.0-M6"
+      )
+  }
+}
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-os-lib.md

@@ -0,0 +1,30 @@
+{% altDetails require-info-box 'Getting OS-Lib' %}
+
+{% tabs oslib-install class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit "latest"
+```
+
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+//> using dep "com.lihaoyi::os-lib:0.9.1"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In our `build.sbt` file, we add the dependency on OS-Lib:
+```scala
+libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.9.1"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In our `build.sc` file, we add the dependency on OS-Lib:
+```scala
+def ivyDeps = Agg(
+  ivy"com.lihaoyi::os-lib:0.9.1"
+)
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-sttp.md

@@ -0,0 +1,38 @@
+{% altDetails install-info-box 'Getting sttp' %}
+
+{% tabs sttp-install-methods class=tabs-build-tool%}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit "latest"
+```
+
+Alternatively, you can require a specific version of sttp:
+```scala
+//> using lib "com.softwaremill.sttp.client4::core:4.0.0-M1"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency to the sttp library:
+```scala
+lazy val example = project.in(file("example"))
+  .settings(
+    scalaVersion := "3.2.1",
+    libraryDependencies += "com.softwaremill.sttp.client4" %% "core" % "4.0.0-M1"
+  )
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add the dependency to the sttp library:
+```scala
+object example extends ScalaModule {
+  def scalaVersion = "3.2.1"
+  def ivyDeps =
+    Agg(
+      ivy"com.softwaremill.sttp.client4::core:4.0.0-M1"
+    )
+}
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/_markdown/install-upickle.md

@@ -0,0 +1,38 @@
+{% altDetails install-info-box 'Getting upickle' %}
+
+{% tabs upickle-install-methods class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+Using Scala CLI, you can require the entire toolkit in a single line:
+```scala
+//> using toolkit "latest"
+```
+
+Alternatively, you can require a specific version of upickle:
+```scala
+//> using lib "com.lihaoyi::upickle:1.6.0"
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency to the upickle library:
+```scala
+lazy val example = project.in(file("example"))
+  .settings(
+    scalaVersion := "3.2.1",
+    libraryDependencies += "com.lihaoyi" %% "upickle" % "1.6.0"
+  )
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add the dependency to the upickle library:
+```scala
+object example extends ScalaModule {
+  def scalaVersion = "3.2.1"
+  def ivyDeps =
+    Agg(
+      ivy"com.lihaoyi::upickle:1.6.0"
+    )
+}
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}

_includes/markdown.html

@@ -0,0 +1,3 @@
+{%if include.selector%}<{{include.selector}} {%if include.classes%}class="{{include.classes}}"{%endif%} {%if include.id%}id="{{include.id}}{%endif%}">{%endif%}
+  {% capture markdown %}{% include {{include.path}} %}{% endcapture %}{{ markdown | markdownify }}
+{%if include.selector%}</{{include.selector}}>{%endif%}

_overviews/toolkit/OrderedListOfMdFiles

@@ -0,0 +1,29 @@
+introduction.md
+munit-intro.md
+munit-tests.md
+munit-run.md
+munit-run-only.md
+munit-exceptions.md
+munit-asynchronous-tests.md
+munit-resources.md
+munit-what-else.md
+oslib-intro.md
+oslib-read-directory.md
+oslib-read-file.md
+oslib-write-file.md
+oslib-run-process.md
+oslib-what-else.md
+upickle-intro.md
+upickle-parse-json.md
+upickle-modify-json.md
+upickle-deserialize.md
+upickle-serialize.md
+upickle-files.md
+upickle-what-else.md
+sttp-intro.md
+sttp-request.md
+sttp-uris.md
+sttp-request-body.md
+sttp-json.md
+sttp-upload-file.md
+sttp-what-else.md

_overviews/toolkit/introduction.md

@@ -0,0 +1,60 @@
+---
+title: Introduction
+type: chapter
+description: Introducing the Scala Toolkit tutorials
+num: 1
+previous-page: 
+next-page: munit-intro
+---
+
+## What is the Scala Toolkit?
+
+The Scala Toolkit is a set of libraries designed to make common programming tasks simple and efficient. It supports working with files and processes, parsing JSON, sending HTTP requests, and unit testing.
+
+The Toolkit supports:
+* Scripts and applications
+* Scala 3 and Scala 2
+* JVM, Scala.js, and Scala Native
+
+Use cases for the toolkit include:
+
+- backend scripts that run on JVM, to scrape a website, to collect and transform data, or to fetch and process some files,
+- frontend scripts that run on the browser and power your websites,
+- command-line scripts
+- command-line tools packaged as native binaries for instant startup
+
+## What are these tutorials?
+
+This series of tutorials focuses on short code examples, to help you get started quickly.
+
+If you need more in-depth information, the tutorials include links to further documentation for all of the libraries in the toolkit.
+
+## How to run the code?
+
+You can follow the tutorials regardless of how you choose to run your
+Scala code. The tutorials focus on the code itself, not on the process
+of running it.
+
+Ways to run Scala code include:
+* in your **browser** with [Scastie](https://scastie.scala-lang.org)
+    * pros: zero installation, online sharing
+    * cons: single-file only, online-only
+* interactively in the Scala **REPL** (Read/Eval/Print Loop)
+    * pros: interactive exploration in the terminal
+    * cons: doesn't save your code anywhere
+* interactively in a **worksheet** in your IDE such as [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) or [Metals](http://scalameta.org/metals/)
+    * pros: interactive exploration in a GUI
+    * cons: requires worksheet environment to run
+* in **scripts**, using [Scala CLI](https://scala-cli.virtuslab.com)
+    * pros: terminal-based workflow with little setup
+    * cons: may not be suitable for large projects
+* using a **build tool** (such as [sbt](https://www.scala-sbt.org) or [mill](https://com-lihaoyi.github.io/mill/))
+    * pros: terminal-based workflow for projects of any size
+    * cons: requires some additional setup and learning
+* using an **IDE** such as [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) or [Metals](http://scalameta.org/metals/)
+    * pros: GUI based workflow for projects of any size
+    * cons: requires some additional setup and learning
+
+These choices, with their pros and cons, are common to most programing
+languages.
+Feel free to use whichever option you're most comfortable with.

_overviews/toolkit/munit-asynchronous-tests.md

@@ -0,0 +1,85 @@
+---
+title: How to write asynchronous tests?
+type: section
+description: Writing asynchronous tests using MUnit
+num: 7
+previous-page: munit-exceptions
+next-page: munit-resources
+---
+
+{% include markdown.html path="_markdown/install-munit.md" %}
+
+## Asynchronous tests
+
+In Scala, it's common for an *asynchronous* method to return a `Future`.
+MUnit offers special support for `Future`s.
+
+For example, consider an asynchronous variant of a `square` method:
+
+{% tabs 'async-1' class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import scala.concurrent.{ExecutionContext, Future}
+
+object AsyncMathLib {
+  def square(x: Int)(using ExecutionContext): Future[Int] =
+    Future(x * x)
+}
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+import scala.concurrent.{ExecutionContext, Future}
+
+object AsyncMathLib:
+  def square(x: Int)(implicit ec: ExecutionContext): Future[Int] =
+    Future(x * x)
+```
+{% endtab %}
+{% endtabs %}
+
+A test itself can return a `Future[Unit]`.
+MUnit will wait behind the scenes for the resulting `Future` to complete, failing the test if any assertion fails.
+
+You can therefore write the test as follows:
+
+{% tabs 'async-3' class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+// Import the global execution context, required to call async methods
+import scala.concurrent.ExecutionContext.Implicits.global
+
+class AsyncMathLibTests extends munit.FunSuite:
+  test("square") {
+    for
+      squareOf3 <- AsyncMathLib.square(3)
+      squareOfMinus4 <- AsyncMathLib.square(-4)
+    yield
+      assertEquals(squareOf3, 9)
+      assertEquals(squareOfMinus4, 16)
+  }
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+// Import the global execution context, required to call async methods
+import scala.concurrent.ExecutionContext.Implicits.global
+
+class AsyncMathLibTests extends munit.FunSuite:
+  test("square"):
+    for
+      squareOf3 <- AsyncMathLib.square(3)
+      squareOfMinus4 <- AsyncMathLib.square(-4)
+    yield
+      assertEquals(squareOf3, 9)
+      assertEquals(squareOfMinus4, 16)
+```
+{% endtab %}
+{% endtabs %}
+
+The test first asynchronously computes `square(3)` and `square(-4)`.
+Once both computations are completed, and if they are both successful, it proceeds with the calls to `assertEquals`.
+If any of the assertion fails, the resulting `Future[Unit]` fails, and MUnit will cause the test to fail.
+
+You may read more about asynchronous tests [in the MUnit documentation](https://scalameta.org/munit/docs/tests.html#declare-async-test).
+It shows how to use other asynchronous types besides `Future`.