Use scala-cli

Author: gkepka

_overviews/getting-started/index.md

@@ -145,6 +145,144 @@ To install them manually:
    or [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Refer to [JDK Compatibility](/overviews/jdk-compatibility/overview.html) for Scala/Java compatibility detail.
 1. Install [sbt](https://www.scala-sbt.org/download.html)
 
+## Using the scala-cli command
+
+Create a file named `hello.scala` with following code:
+```scala
+@main
+def hello(): Unit =
+  println("Hello, World!")
+```
+
+You can define a method with `def` keyword and mark it as a "main" method with the `@main` annotation, designating it as
+the entry point in program execution. The method's type is `Unit`, which means it does not return a value. `Unit`
+can be thought of as an analogue to `void` keyword found in other languages. The `println` method will print the `"Hello World!"`
+string to standard output.
+
+To run the program, execute `scala-cli run hello.scala` command. The file will be compiled and executed, with console output
+similar to following:
+```
+$ scala-cli run hello.scala             
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
+Hello, World!
+```
+
+### Handling command-line arguments
+
+Let's rewrite the `hello.scala` file so that the program greets the person running it.
+```scala
+@main
+def hello(name: String): Unit =
+  println(s"Hello, $name!")
+```
+
+The `name` argument is expected to be provided when executing the program and if it's not found, the execution will fail.
+The `println` method receives an interpolated string, as indicated by the `s` letter preceding its content. `$name` will be substituted by
+the content of `name` argument.
+
+To pass the arguments when executing the program, put them after `--`:
+```
+$ scala-cli run hello.scala -- Gabriel          
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
+Hello, Gabriel!
+```
+
+You can read more about [main methods](/scala3/book/methods-main-methods.html) and [string interpolation]((/scala3/book/string-interpolation.html)) in the Scala Book.
+
+### Adding dependencies
+
+Let's write a program that will count the files and directories present in its working directory. While in Scala you have full access to Java API for
+filesystem interaction, the [os-lib](https://github.com/com-lihaoyi/os-lib) library by Li Haoyi is much more convenient to use. A dependency on the library can
+be added with `//> using` directive. Put the following code in `counter.scala`.
+```scala
+//> using dep "com.lihaoyi::os-lib:0.10.7"
+
+@main
+def countFiles(): Unit =
+    val paths = os.list(os.pwd)
+    println(paths.length)
+```
+
+In the code above, the `os.pwd` returns current working directory, which then is passed to `os.list`, which returns a sequence
+of paths directly within the directory passed as argument. `val` is used to declare an immutable value, in this example storing the
+sequence of paths.
+
+Execute the program. The dependency will be automatically downloaded. The execution should result in a similar output:
+```
+$ scala-cli run counter.scala       
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
+4
+```
+The printed number should be 4: `hello.scala`, `counter.scala` and two hidden directories created automatically when a program is executed:
+`.bsp` containing information about project used by IDEs, and `.scala-build` containing the results of compilation.
+
+As it turns out, the `os-lib` library is part of Scala Toolkit, a collection of libraries recommended for tasks like testing,
+operating system interaction or handling JSONs. You can read more about libraries included in the toolkit [here](/toolkit/introduction.html).
+To include the toolkit libraries, use `//> using toolkit default` directive:
+```scala
+//> using toolkit default
+
+@main
+def countFiles(): Unit =
+    val paths = os.list(os.pwd)
+    println(paths.length)
+```
+
+This program is identical to the one above with the only difference being that other toolkit libraries will also be available to use
+and their downloaded versions, instead of being specified by hand, will be the newest ones included in toolkit.
+
+### Using scala-cli REPL
+
+You can execute code interactively using REPL provided by `scala-cli` command. Execute `scala-cli` in console without any arguments.
+```
+$ scala-cli
+Welcome to Scala 3.4.2 (20-ea, Java OpenJDK 64-Bit Server VM).
+Type in expressions for evaluation. Or try :help.
+                                                                                                                                                                            
+scala> 
+```
+
+Write a line of code to be executed and press enter.
+```
+scala> println("Hello, World!")
+Hello, World!
+                                                                                                                                                                            
+scala> 
+```
+
+The result will be printed immediately after executing the line. You can declare values:
+```
+scala> val i = 1
+val i: Int = 1
+                                                                                                                                                                            
+scala> 
+```
+
+A new value of type `Int` has been created. If you provide an expression that can be evaluated, its result will be stored in an automatically created value.
+```
+scala> i + 3
+val res0: Int = 4
+                                                                                                                                                                            
+scala> 
+```
+You can exit the REPL with `:exit`.
+
+### Next steps
+
+Now that you have tasted a little bit of Scala, you can either explore the language itself, or learn how to set up a project using the
+sbt and an IDE using the tutorials below. If you want to familiarize yourself with the language more, consider checking out:
+
+* [The Scala Book](/scala3/book/introduction.html) (see the Scala 2 version [here](/overviews/scala-book/introduction.html)), which provides a set of short lessons introducing Scala’s main features.
+* [The Tour of Scala](/tour/tour-of-scala.html) for bite-sized introductions to Scala's features.
+* [Learning Resources](/learn.html), which includes online interactive tutorials and courses.
+* [Our list of some popular Scala books](/books.html).
+* [The migration guide](/scala3/guides/migration/compatibility-intro.html) helps you to migrate your existing Scala 2 code base to Scala 3.
+
+The [Scala CLI documentation](https://scala-cli.virtuslab.org/) describes the available sub-commands and how to integrate the tool with an IDE of choice.
+
 ## Create a "Hello World" project with sbt
 
 Once you have installed sbt, you are ready to create a Scala project, which
@@ -229,15 +367,5 @@ Otherwise, you can run the application from a terminal with these steps:
 When you’re finished experimenting with this project, press `[Enter]` to interrupt the `run` command.
 Then type `exit` or press `[Ctrl+D]` to exit sbt and return to your command line prompt.
 
-## Next Steps
-
-Once you've finished the above tutorials, consider checking out:
-
-* [The Scala Book](/scala3/book/introduction.html) (see the Scala 2 version [here](/overviews/scala-book/introduction.html)), which provides a set of short lessons introducing Scala’s main features.
-* [The Tour of Scala](/tour/tour-of-scala.html) for bite-sized introductions to Scala's features.
-* [Learning Resources](/learn.html), which includes online interactive tutorials and courses.
-* [Our list of some popular Scala books](/books.html).
-* [The migration guide](/scala3/guides/migration/compatibility-intro.html) helps you to migrate your existing Scala 2 code base to Scala 3.
-
 ## Getting Help
 There are a multitude of mailing lists and real-time chat rooms in case you want to quickly connect with other Scala users. Check out our [community](https://scala-lang.org/community/) page for a list of these resources, and for where to reach out for help.

_overviews/scala-book/two-types-variables.md

@@ -94,8 +94,7 @@ object Hello3 extends App {
 As before:
 
 - Save that code in a file named *Hello3.scala*
-- Compile it with `scalac Hello3.scala`
-- Run it with `scala Hello3`
+- Compile and run it with `scala-cli run Hello3.scala`
 
 
 

_overviews/scala3-book/methods-main-methods.md

@@ -22,10 +22,10 @@ Scala 3 offers a new way to define programs that can be invoked from the command
 {% endtab %}
 {% endtabs %}
 
-To run this program, save the line of code in a file named as e.g. *Hello.scala*---the filename doesn’t have to match the method name---and run it with `scala`:
+To run this program, save the line of code in a file named as e.g. *Hello.scala*---the filename doesn’t have to match the method name---and run it with `scala-cli`:
 
 ```bash
-$ scala Hello.scala
+$ scala-cli run Hello.scala
 Hello, World
 ```
 
@@ -64,10 +64,10 @@ For example, given this `@main` method that takes an `Int`, a `String`, and a va
 {% endtab %}
 {% endtabs %}
 
-When you compile that code, it creates a main program named `happyBirthday` that’s called like this:
+Pass the arguments after `--`:
 
 ```
-$ scala happyBirthday 23 Lisa Peter
+$ scala-cli run happyBirthday.scala -- 23 Lisa Peter
 Happy 23rd Birthday, Lisa and Peter!
 ```
 
@@ -79,10 +79,10 @@ The program implemented from an `@main` method checks that there are enough argu
 If a check fails, the program is terminated with an error message:
 
 ```
-$ scala happyBirthday 22
+$ scala-cli run happyBirthday.scala -- 22
 Illegal command line after first argument: more arguments expected
 
-$ scala happyBirthday sixty Fred
+$ scala-cli run happyBirthday.scala -- sixty Fred
 Illegal command line: java.lang.NumberFormatException: For input string: "sixty"
 ```
 
@@ -176,11 +176,9 @@ object happyBirthday {
 {% endtab %}
 {% endtabs %}
 
-If you place that code in a file named *happyBirthday.scala*, you can then compile it with `scalac` and run it with `scala`, as shown previously:
+If you place that code in a file named *happyBirthday.scala*, you can then compile and run it with `scala-cli`, as shown previously:
 
 ```bash
-$ scalac happyBirthday.scala
-
-$ scala happyBirthday 23 Lisa Peter
+$ scala-cli run happyBirthday.scala -- 23 Lisa Peter
 Happy 23rd Birthday, Lisa and Peter!
 ```

_overviews/scala3-book/taste-hello-world.md

@@ -47,53 +47,27 @@ object hello {
 {% endtabs %}
 <!-- End tabs -->
 
-Next, compile the code with `scalac`:
+Next, compile and run the code with `scala-cli`:
 
 ```bash
-$ scalac hello.scala
+$ scala-cli run hello.scala
 ```
 
-If you’re coming to Scala from Java, `scalac` is just like `javac`, so that command creates several files:
+When you run the command for the first time, two hidden directories will be created: `.bsp` and `.scala-build`. The first
+one contains the [Build Server Protocol](https://build-server-protocol.github.io/) information for IDEs, the second one contains the results
+of compilation.
 
-<!-- Display Hello World compiled outputs for each Scala Version -->
-{% tabs hello-world-outputs class=tabs-scala-version %}
-
-{% tab 'Scala 2' for=hello-world-outputs %}
-```bash
-$ ls -1
-hello$.class
-hello.class
-hello.scala
+The command should produce similar output:
 ```
-{% endtab %}
-
-{% tab 'Scala 3' for=hello-world-outputs %}
-```bash
-$ ls -1
-hello$package$.class
-hello$package.class
-hello$package.tasty
-hello.scala
-hello.class
-hello.tasty
-```
-{% endtab %}
-
-{% endtabs %}
-<!-- End tabs -->
-
-Like Java, the _.class_ files are bytecode files, and they’re ready to run in the JVM.
-
-Now you can run the `hello` method with the `scala` command:
-
-```bash
-$ scala hello
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
 Hello, World!
 ```
 
 Assuming that worked, congratulations, you just compiled and ran your first Scala application.
 
 > More information about sbt and other tools that make Scala development easier can be found in the [Scala Tools][scala_tools] chapter.
+> The Scala CLI documentation can be found [here](https://scala-cli.virtuslab.org/).
 
 ## Ask For User Input
 
@@ -152,24 +126,23 @@ use the `+` operator on strings to join `"Hello, "` with `name` and `"!"`, makin
 
 > You can learn more about using `val` by reading [Variables and Data Types](/scala3/book/taste-vars-data-types.html).
 
-Then compile the code with `scalac`:
-
-```bash
-$ scalac helloInteractive.scala
-```
-Then run it with `scala helloInteractive`, this time the program will pause after asking for your name,
+Then run the code with `scala-cli`. This time the program will pause after asking for your name,
 and wait until you type a name and press return on the keyboard, looking like this:
 
 ```bash
-$ scala helloInteractive
+$ scala-cli run helloInteractive.scala
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
 Please enter your name:
 ▌
 ```
 
 When you enter your name at the prompt, the final interaction should look like this:
 
 ```bash
-$ scala helloInteractive
+$ scala-cli run helloInteractive.scala
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
 Please enter your name:
 Alvin Alexander
 Hello, Alvin Alexander!

_overviews/tutorials/scala-for-java-programmers.md

@@ -160,38 +160,49 @@ package, so can be accessed from anywhere in a program.
 
 > **Note:** The following assumes you are using Scala on the command line
 
+If we save the above program in a file called
+`HelloWorld.scala`, we can run it by issuing the following
+command (the greater-than sign `>` represents the shell prompt
+and should not be typed):
+
+```shell
+> scala-cli run HelloWorld.scala
+```
+
+The program will be automatically compiled (with compiled classes somewhere in the newly created `.scala-build` directory)
+and executed, producing a similar output:
+```
+Compiling project (Scala 3.4.2, JVM (20))
+Compiled project (Scala 3.4.2, JVM (20))
+Hello, World!
+```
+
 #### Compiling From the Command Line
 
-To compile the example, we use `scalac`, the Scala compiler. `scalac`
+To compile the example, we use `scala-cli compile` command, which will invoke the Scala compiler, `scalac`. `scalac`
 works like most compilers: it takes a source file as argument, maybe
 some options, and produces one or several output files. The outputs
 it produces are standard Java class files.
 
-If we save the above program in a file called
-`HelloWorld.scala`, we can compile it by issuing the following
-command (the greater-than sign `>` represents the shell prompt
-and should not be typed):
-
 ```shell
-> scalac HelloWorld.scala
+> scala-cli compile HelloWorld.scala -d .
 ```
 
-This will generate a few class files in the current directory. One of
+This will generate a few class files in the current directory (`-d .` option sets the compilation output directory). One of
 them will be called `HelloWorld.class`, and contains a class
-which can be directly executed using the `scala` command, as the
+which can be directly executed using the `scala-cli` command, as the
 following section shows.
 
 #### Running From the Command Line
 
-Once compiled, a Scala program can be run using the `scala` command.
+Once compiled, the program can be run using the `scala-cli run` command.
 Its usage is very similar to the `java` command used to run Java
-programs, and accepts the same options. The above example can be
+programs, and accepts similar options. The above example can be
 executed using the following command, which produces the expected
 output:
 
 ```shell
-> scala -classpath . HelloWorld
-
+> scala-cli run --main-class HelloWorld -classpath . 
 Hello, World!
 ```