Merge pull request #3072 from gkepka/getting-started

Use scala-cli in Getting Started page

Author: sjrd

Diff for: _overviews/getting-started/install-scala.md

@@ -100,7 +100,8 @@ Run the following command in your terminal, following the on-screen instructions
 Check your setup with the command `scala -version`, which should output:
 ```bash
 $ scala -version
-Scala code runner version {{site.scala-3-version}} -- Copyright 2002-2022, LAMP/EPFL
+Scala code runner version: 1.4.3
+Scala version (default): {{site.scala-3-version}}
 ```
 {% endaltDetails %}
 <!-- end Alternative Detail -->
@@ -144,6 +145,146 @@ 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
+
+In a directory of your choice, which we will call `<project-dir>`, create a file named `hello.scala` with the following code:
+```scala
+//> using scala {{site.scala-3-version}}
+
+@main
+def hello(): Unit =
+  println("Hello, World!")
+```
+
+You can define a method with the `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 the `void` keyword found in other languages. The `println` method will print the `"Hello, World!"`
+string to standard output.
+
+To run the program, execute `scala run hello.scala` command from a terminal, within the `<project-dir>` directory. The file will be compiled and executed, with console output
+similar to following:
+```
+$ scala run hello.scala             
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, JVM (20))
+Hello, World!
+```
+
+### Handling command-line arguments
+
+Rewrite the `hello.scala` file so that the program greets the person running it.
+```scala
+//> using scala {{site.scala-3-version}}
+
+@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 the `name` argument.
+
+To pass the arguments when executing the program, put them after `--`:
+```
+$ scala run hello.scala -- Gabriel          
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, 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
+
+We now write a program that will count the files and directories present in its working directory.
+We use the [os-lib](https://github.com/com-lihaoyi/os-lib) library from the [Scala toolkit](toolkit/introduction.html)
+for that purpose. A dependency on the library can be added with the `//> using` directive. Put the following code in `counter.scala`.
+```scala
+//> using scala {{site.scala-3-version}}
+//> 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, `os.pwd` returns the current working directory. We pass it to `os.list`, which returns a sequence
+of paths directly within the directory passed as an argument. We use a `val` 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 run counter.scala       
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, 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 a part of Scala Toolkit, a collection of libraries recommended for tasks like testing,
+operating system interaction or handling JSONs. You can read more about the libraries included in the toolkit [here](/toolkit/introduction.html).
+To include the toolkit libraries, use the `//> using toolkit 0.5.0` directive:
+```scala
+//> using scala {{site.scala-3-version}}
+//> using toolkit 0.5.0
+
+@main
+def countFiles(): Unit =
+  val paths = os.list(os.pwd)
+  println(paths.length)
+```
+
+This program is identical to the one above. However, other toolkit libraries will also be available to use, should you need them.
+
+### Using the REPL
+
+You can execute code interactively using the REPL provided by the `scala` command. Execute `scala` in the console without any arguments.
+```
+$ scala
+Welcome to Scala {{site.scala-3-version}} (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).
+
 ## Create a "Hello World" project with sbt
 
 Once you have installed sbt, you are ready to create a Scala project, which
@@ -227,15 +368,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.

Diff for: _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 run Hello3.scala`
 
 
 

Diff for: _overviews/scala3-book/methods-main-methods.md

@@ -25,7 +25,7 @@ Scala 3 offers a new way to define programs that can be invoked from the command
 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`:
 
 ```bash
-$ scala Hello.scala
+$ scala 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 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 run happyBirthday.scala -- 22
 Illegal command line after first argument: more arguments expected
 
-$ scala happyBirthday sixty Fred
+$ scala 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`, as shown previously:
 
 ```bash
-$ scalac happyBirthday.scala
-
-$ scala happyBirthday 23 Lisa Peter
+$ scala run happyBirthday.scala -- 23 Lisa Peter
 Happy 23rd Birthday, Lisa and Peter!
 ```

Diff for: _overviews/scala3-book/taste-hello-world.md

@@ -47,53 +47,23 @@ object hello {
 {% endtabs %}
 <!-- End tabs -->
 
-Next, compile the code with `scalac`:
+Next, compile and run the code with `scala`:
 
 ```bash
-$ scalac hello.scala
+$ scala run hello.scala
 ```
 
-If you’re coming to Scala from Java, `scalac` is just like `javac`, so that command creates several files:
-
-<!-- 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 an output similar to:
 ```
-{% 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 {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, 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 +122,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`. 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 run helloInteractive.scala
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, 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 run helloInteractive.scala
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, JVM (20))
 Please enter your name:
 Alvin Alexander
 Hello, Alvin Alexander!

Diff for: _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 run HelloWorld.scala
+```
+
+The program will be automatically compiled (with compiled classes somewhere in the newly created `.scala-build` directory)
+and executed, producing an output similar to:
+```
+Compiling project (Scala {{site.scala-3-version}}, JVM (20))
+Compiled project (Scala {{site.scala-3-version}}, 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 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 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
 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 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 run --main-class HelloWorld -classpath . 
 Hello, World!
 ```
 

Diff for: _ru/getting-started/index.md

@@ -90,7 +90,8 @@ newcomer_resources:
 Проверьте корректность установки с помощью команды `scala -version`, которая должна вывести:
 ```bash
 $ scala -version
-Scala code runner version {{site.scala-3-version}} -- Copyright 2002-2022, LAMP/EPFL
+Scala code runner version: 1.4.3
+Scala version (default): {{site.scala-3-version}}
 ```
 Если сообщение не выдано, возможно, необходимо перезайти в терминал (или перезагрузиться), 
 чтобы изменения вступили в силу.