From 36639bc8b9888110c84a6b34e7a14840533a3c0d Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Thu, 3 Nov 2022 11:53:02 +0100 Subject: [PATCH 1/3] Fix docs on the default sub-command behaviour --- website/docs/commands/basics.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/website/docs/commands/basics.md b/website/docs/commands/basics.md index 186d609911..36d35f9be5 100644 --- a/website/docs/commands/basics.md +++ b/website/docs/commands/basics.md @@ -3,9 +3,9 @@ title: Basics sidebar_position: 3 --- -Scala CLI is a command line tool that executes a given command on the inputs it’s provided with, using a given [configuration](../guides/configuration.md) to produce a result. +Scala CLI is a command line tool that executes a given sub-command on the inputs it’s provided with, using a given [configuration](../guides/configuration.md) to produce a result. -The most important commands are: +The most important sub-commands are: - [compile](./compile.md) compiles your code (excluding tests) - [run](./run.md) runs your code using the provided arguments (it’s also used when no other command is provided) @@ -14,7 +14,15 @@ The most important commands are: - [repl](./repl.md) / [console](./repl.md) runs the interactive Scala shell - [fmt](./fmt.md) formats your code -When Scala CLI is run without any commands, it defaults to the `run` command, so
`scala-cli a.scala` runs your `a.scala` file. +Scala CLI can also be run without passing any explicit sub-command, +in which case it defaults to one of the sub-commands based on context: + - if the `--version` option is passed, it prints the `version` command output (unmodified by any other options) + - if any inputs were passed, it defaults to the `run` sub-command + - and so, `scala-cli a.scala` runs your `a.scala` file + - additionally, when no inputs were passed, it defaults to the `run` sub-command in the following scenarios: + - if a snippet was passed with `--execute-script`, `--execute-scala` or `--execute-java` + - if a main class was passed with the `--main-class` option alongside an extra `--classpath` + - otherwise if no inputs were passed, it defaults to the `repl` sub-command ## Input formats From 833cca6d710ec8e490ff1e53d39eb07434d13f52 Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Thu, 3 Nov 2022 12:00:31 +0100 Subject: [PATCH 2/3] Fill in some missing details in the Basics doc --- website/docs/commands/basics.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/commands/basics.md b/website/docs/commands/basics.md index 36d35f9be5..7c681f524b 100644 --- a/website/docs/commands/basics.md +++ b/website/docs/commands/basics.md @@ -40,8 +40,10 @@ Note that all of these input formats can be used alongside each other. Scala CLI accepts the following types of source code: - `.scala` files, containing Scala code -- `.sc` files, containing Scala scripts (see more in [Scripts guide](../guides/scripts.md)) +- `.sc` files, containing Scala scripts (see more in the [Scripts guide](../guides/scripts.md)) - `.java` files, containing Java code +- `.md` files, containing Markdown code (experimental, see more in the [Markdown guide](../guides/scripts.md)) +- `.c` and `.h` files, containing C code (only as resources for Scala Native, see more in the [Scala Native guide](../guides/scala-native.md)) The following example shows the simplest input format. First, create a source file: @@ -53,7 +55,7 @@ object Hello { } ``` -The run it by passing it to `scala-cli`: +Then run it by passing it to `scala-cli`: ```bash scala-cli Hello.scala From 575aacecdf805b20186ac51f20bdab518c1300f2 Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Thu, 3 Nov 2022 12:01:03 +0100 Subject: [PATCH 3/3] NIT fix formatting in the basics doc --- website/docs/commands/basics.md | 43 +++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/website/docs/commands/basics.md b/website/docs/commands/basics.md index 7c681f524b..d4499af1a6 100644 --- a/website/docs/commands/basics.md +++ b/website/docs/commands/basics.md @@ -3,26 +3,28 @@ title: Basics sidebar_position: 3 --- -Scala CLI is a command line tool that executes a given sub-command on the inputs it’s provided with, using a given [configuration](../guides/configuration.md) to produce a result. +Scala CLI is a command line tool that executes a given sub-command on the inputs it’s provided with, using a +given [configuration](../guides/configuration.md) to produce a result. The most important sub-commands are: - - [compile](./compile.md) compiles your code (excluding tests) - - [run](./run.md) runs your code using the provided arguments (it’s also used when no other command is provided) - - [test](./test.md) compiles and runs the tests defined in your code - - [package](./package.md) packages your code into a jar or other format - - [repl](./repl.md) / [console](./repl.md) runs the interactive Scala shell - - [fmt](./fmt.md) formats your code +- [compile](./compile.md) compiles your code (excluding tests) +- [run](./run.md) runs your code using the provided arguments (it’s also used when no other command is provided) +- [test](./test.md) compiles and runs the tests defined in your code +- [package](./package.md) packages your code into a jar or other format +- [repl](./repl.md) / [console](./repl.md) runs the interactive Scala shell +- [fmt](./fmt.md) formats your code Scala CLI can also be run without passing any explicit sub-command, in which case it defaults to one of the sub-commands based on context: - - if the `--version` option is passed, it prints the `version` command output (unmodified by any other options) - - if any inputs were passed, it defaults to the `run` sub-command + +- if the `--version` option is passed, it prints the `version` command output (unmodified by any other options) +- if any inputs were passed, it defaults to the `run` sub-command - and so, `scala-cli a.scala` runs your `a.scala` file - - additionally, when no inputs were passed, it defaults to the `run` sub-command in the following scenarios: +- additionally, when no inputs were passed, it defaults to the `run` sub-command in the following scenarios: - if a snippet was passed with `--execute-script`, `--execute-scala` or `--execute-java` - if a main class was passed with the `--main-class` option alongside an extra `--classpath` - - otherwise if no inputs were passed, it defaults to the `repl` sub-command +- otherwise if no inputs were passed, it defaults to the `repl` sub-command ## Input formats @@ -43,7 +45,8 @@ Scala CLI accepts the following types of source code: - `.sc` files, containing Scala scripts (see more in the [Scripts guide](../guides/scripts.md)) - `.java` files, containing Java code - `.md` files, containing Markdown code (experimental, see more in the [Markdown guide](../guides/scripts.md)) -- `.c` and `.h` files, containing C code (only as resources for Scala Native, see more in the [Scala Native guide](../guides/scala-native.md)) +- `.c` and `.h` files, containing C code (only as resources for Scala Native, see more in + the [Scala Native guide](../guides/scala-native.md)) The following example shows the simplest input format. First, create a source file: @@ -95,15 +98,16 @@ scala-cli Hello.scala compilation will fail. `scala-cli` compiles only the files it’s given. ::: -While this is *very* convenient for projects with just a few files, passing many files this way can be cumbersome and error-prone. +While this is *very* convenient for projects with just a few files, passing many files this way can be cumbersome and +error-prone. In the case of larger projects, passing whole directories can help. - ## Directories `scala-cli` accepts whole directories as input. -This is convenient when you have many `.scala` files, and passing them all one-by-one on the command line isn't practical: +This is convenient when you have many `.scala` files, and passing them all one-by-one on the command line isn't +practical: ```scala title=my-app/Messages.scala object Messages { @@ -137,7 +141,8 @@ Such directories needs to be explicitly provided as inputs. ## URLs :::warning -Running unverified code from the internet can be very handy for *trusted* sources, but it can also be really dangerous, since Scala CLI does not provide any sandboxing at this moment. +Running unverified code from the internet can be very handy for *trusted* sources, but it can also be really dangerous, +since Scala CLI does not provide any sandboxing at this moment. Make sure that you trust the code that you are about to run. ::: @@ -170,6 +175,7 @@ object Hello extends App { println("Hello") } ``` + ```bash ignore unzip -l hello.zip # Archive: hello.zip @@ -185,6 +191,7 @@ scala-cli hello.zip ## Piping You can also pipe code to `scala-cli` for execution: + - scripts ```bash echo 'println("Hello")' | scala-cli _.sc @@ -200,6 +207,7 @@ You can also pipe code to `scala-cli` for execution: echo 'class Hello { public static void main(String args[]) { System.out.println("Hello"); } }' | scala-cli _.java # Hello ``` + More details in the [Piping guide](../guides/piping.md). ## Scala CLI version @@ -227,8 +235,6 @@ scala-cli --cli-version nightly about # Scala CLI version 0.1.3-8-g431cc15f-SNAPSHOT ``` - - ## Process substitution Lastly, `scala-cli` also accepts input via shell process substitution: @@ -237,6 +243,7 @@ Lastly, `scala-cli` also accepts input via shell process substitution: scala-cli <(echo 'println("Hello")') # Hello ``` +