diff --git a/website/docs/commands/basics.md b/website/docs/commands/basics.md index d4499af1a6..ab12c95416 100644 --- a/website/docs/commands/basics.md +++ b/website/docs/commands/basics.md @@ -3,6 +3,8 @@ title: Basics sidebar_position: 3 --- +import {ChainedSnippets} from "../../src/components/MarkdownComponents.js"; + 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. @@ -22,7 +24,7 @@ in which case it defaults to one of the sub-commands based on context: - 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 snippet was passed with `-e`, `--execute-script`, `--execute-scala`, `--execute-java` or `--execute-markdown` - 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 @@ -60,11 +62,18 @@ object Hello { Then run it by passing it to `scala-cli`: + + ```bash scala-cli Hello.scala -# Hello from Scala ``` +```text +Hello from Scala +``` + + + You can also split your code into multiple files: ```scala title=Messages.scala @@ -82,11 +91,18 @@ object Hello { and the run them with `scala-cli`: + + ```bash scala-cli Hello.scala Messages.scala -# Hello from Scala ``` +```text +Hello from Scala +``` + + + :::note Scala CLI compiles only the provided inputs. For example, if we provide only one of the files above: @@ -124,11 +140,18 @@ object Hello { In this case, you can run all the source code files in `my-app` by supplying the directory name: + + ```bash scala-cli my-app -# Hello from Scala ``` +```text +Hello from Scala +``` + + + In our experience, `scala-cli .` is the most used command; it compiles and runs all sources in the current directory. :::note @@ -160,11 +183,20 @@ scala-cli https://gist.github.com/alexarchambault/f972d941bc4a502d70267cfbbc4d63 `scala-cli` accepts input via Github Gist’s urls. It downloads the gist zip archive and runs it: + + ```bash scala-cli https://gist.github.com/alexarchambault/7b4ec20c4033690dd750ffd601e540ec -# Hello ``` +```text +Hello +``` + + + +More details in the [GitHub gists cookbook](../cookbooks/gists.md). + ### Zip archive `scala-cli` accepts inputs via a `zip` archive path. @@ -176,38 +208,94 @@ object Hello extends App { } ``` + + ```bash ignore unzip -l hello.zip -# Archive: hello.zip -# Length Date Time Name -# --------- ---------- ----- ---- -# 49 12-07-2021 00:06 Hello.scala -# --------- ------- -# 49 1 file +``` + +```text +Archive: hello.zip + Length Date Time Name +--------- ---------- ----- ---- + 49 12-07-2021 00:06 Hello.scala +--------- ------- + 49 1 file +``` + +```bash ignore scala-cli hello.zip -# Hello ``` +```text +Hello +``` + + + ## Piping You can also pipe code to `scala-cli` for execution: - scripts + + + ```bash echo 'println("Hello")' | scala-cli _.sc - # Hello ``` + + ```text + Hello + ``` + + + - Scala code + + + ```bash echo '@main def hello() = println("Hello")' | scala-cli _.scala - # Hello ``` + + ```text + Hello + ``` + + + - Java code + + + ```bash echo 'class Hello { public static void main(String args[]) { System.out.println("Hello"); } }' | scala-cli _.java - # Hello + ``` + + ```text + Hello + ``` + + + +- Markdown code (experimental) + + + + ```bash + echo '# Example Snippet + ```scala + println("Hello") + ```' | scala-cli _.md + ``` + + ```text + Hello ``` + + More details in the [Piping guide](../guides/piping.md). ## Scala CLI version @@ -219,31 +307,56 @@ Running another Scala CLI version might be slower because it uses JVM-based Scal To run another Scala CLI version, specify it with `--cli-version` before any other argument: + + ```bash -scala-cli --cli-version 0.1.3-51-g4d314eee-SNAPSHOT about -# Scala CLI version 0.1.3-51-g4d314eee-SNAPSHOT +scala-cli --cli-version 0.1.17-62-g21e1cf44-SNAPSHOT about ``` +```text +Scala CLI version: 0.1.17-62-g21e1cf44-SNAPSHOT +Scala version (default): 3.2.1 +``` + + + To use the latest Scala CLI nightly build, pass `nightly` to `--cli-version` parameter: + + ```bash scala-cli --cli-version nightly about -# Scala CLI version 0.1.3-8-g431cc15f-SNAPSHOT ``` +```text +Fetching Scala CLI 0.1.17-62-g21e1cf44-SNAPSHOT +Scala CLI version: 0.1.17-62-g21e1cf44-SNAPSHOT +Scala version (default): 3.2.1 +``` + + + ## Process substitution Lastly, `scala-cli` also accepts input via shell process substitution: + + ```bash scala-cli <(echo 'println("Hello")') -# Hello ``` +```text +Hello +``` + + + diff --git a/website/docs/cookbooks/gists.md b/website/docs/cookbooks/gists.md index 687f30f446..b0b59dd7b3 100644 --- a/website/docs/cookbooks/gists.md +++ b/website/docs/cookbooks/gists.md @@ -3,6 +3,8 @@ title: Sharing and testing code with GitHub gists sidebar_position: 6 --- +import {ChainedSnippets} from "../../src/components/MarkdownComponents.js"; + ## Running code from gists `scala-cli` lets you run Scala code straight from GitHub gists, without the need to manually download them first. @@ -62,6 +64,7 @@ object Hello extends App { println(inputs.mkString(",")) } ``` + ```scala title=input 1 2 @@ -70,12 +73,47 @@ object Hello extends App { ``` and run them: + + + ```bash scala-cli https://gist.github.com/lwronski/7ee12fa4b8b8bac3211841273df82080 -# 1,2,3,4 ``` + +```text +1,2,3,4 +``` + + + -it will print `1,2,3,4` to the standard output. \ No newline at end of file +it will print `1,2,3,4` to the standard output. + +## Gists and Markdown code + +:::note +This feature is a work in progress and should currently be treated as experimental. +Markdown sources are ignored by default unless passed explicitly as inputs. +You can enable including non-explicit `.md` inputs by passing the `--enable-markdown` option. +::: + +It is possible to run markdown sources from a GitHub gist. +The gist is technically treated as a zipped archive (which it is downloaded as), so it is necessary to pass +the `--enable-markdown` option alongside the gist URL to run any contained Markdown sources. + + + +```bash +scala-cli https://gist.github.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839 --enable-markdown +``` + +```text +Hello +``` + + + +You can find more information on working with Markdown in the [Markdown guide](../guides/markdown.md). diff --git a/website/docs/guides/markdown.md b/website/docs/guides/markdown.md index be06bf6fd5..09701bf9d7 100644 --- a/website/docs/guides/markdown.md +++ b/website/docs/guides/markdown.md @@ -13,7 +13,123 @@ Markdown sources are ignored by default unless passed explicitly as inputs. You can enable including non-explicit `.md` inputs by passing the `--enable-markdown` option. ::: -## Plain `scala` snippets +## Markdown inputs + +### On-disk markdown sources + +You can pass local `.md` inputs by passing their path to Scala CLI (as you would for any other kind of input). + +```bash ignore +scala-cli hello.md +``` + +`.md` sources inside of directories are ignored by default, unless the `--enable-markdown` option is passed. + +```bash ignore +scala-cli dir-with-markdown --enable-markdown +``` + +### Zipped archives + +Scala CLI can run `.md` sources inside a `.zip` archive. +Same as with directories, `.md` sources inside zipped archives are ignored by default, unless +the `--enable-markdown` option is passed. + +```bash ignore +scala-cli archive-with-markdown.zip --enable-markdown +``` + +### Remote inputs + +:::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. + +Make sure that you trust the code that you are about to run. +::: + +#### URLs + +You can also pass a URL pointing to a `.md` file to run it with Scala CLI. + + + +```bash +scala-cli https://gist.githubusercontent.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839/raw/4c5ce7593e19f1390555221e0d076f4b02f4b4fd/example.md +``` + +```text +Hello +``` + + + +#### Github Gist + +Scala CLI accepts GitHub Gist URLs. +The gist is technically treated as a zipped archive (which it is downloaded as), so it is necessary to pass +the `--enable-markdown` option alongside the gist URL to run any contained Markdown sources. + + + +```bash +scala-cli https://gist.github.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839 --enable-markdown +``` + +```text +Hello +``` + + + +You can find more information on running GitHub Gists in the [gists cookbook](../cookbooks/gists.md). + +### Piped Markdown code + +Instead of passing paths to your Markdown sources, you can also pipe your code via standard input: + + + +```bash +echo '# Example Snippet +```scala +println("Hello") +```' | scala-cli _.md +``` + +```text +Hello +``` + + + +You can find more information on piped sources in the [piping guide](./piping.md). + +### Markdown code as a command line snippet + +It is also possible to pass Markdown code as a snippet directly from the command line. + + + +````bash +scala-cli run --markdown-snippet '# Markdown snippet +with a code block +```scala +println("Hello") +```' +```` + +```text +Hello +``` + + + +You can find more information on command line snippets in the [snippets guide](./snippets.md). + +## Markdown code blocks + +### Plain `scala` snippets ````markdown title=Example.md # Example @@ -85,7 +201,7 @@ Example1_md Example2_md -## `scala raw` snippets +### `scala raw` snippets You can mark a `scala` code block with the `raw` keyword, indicating that this snippet should not be wrapped as a script and should instead be treated as is. This is the equivalent of code in a `.scala` file. For a `raw` snippet to be @@ -116,7 +232,7 @@ Hello from Markdown -## `scala test` snippets +### `scala test` snippets It is possible to run tests from `scala` code blocks marked as `test`. This is similar to `raw` snippets in that the code is not wrapped and is treated as is. @@ -150,7 +266,7 @@ Test: -## `reset` scope for `scala` snippets +### `reset` scope for `scala` snippets When multiple plain `scala` snippets are used in a single `.md` file, by default they are actually treated as a single script. They share context and when run, are executed one after another, as if they were all in a single `.sc` file. @@ -199,11 +315,94 @@ world +## `using` directives and markdown code blocks + +It is possible to define `using` directives at the beginning of a `scala` code block inside a markdown input. +This is supported for all `scala` code block flavours. + +````markdown title=UsingDirectives.md +# Using directives in `.md` inputs + +## `scala raw` example +```scala raw +//> using lib "com.lihaoyi::pprint:0.8.0" +object Printer { + def printHello(): Unit = pprint.pprintln("Hello") +} +``` + +## Plain `scala` example +```scala +//> using lib "com.lihaoyi::os-lib:0.8.1" +println(os.pwd) +``` + +## `scala test` example +```scala test +//> using lib "org.scalameta::munit:0.7.29" + +class Test extends munit.FunSuite { + test("foo") { + assert(true) + println("Hello from tests") + } +} +``` +## Relying on directives from other snippets +Directives from other snippets apply to the whole context. +As a result, nothing really stops you from using a dependency +from an earlier code block. +```scala +Printer.printHello() +pprint.pprintln("world") +``` +```` + +:::note +`scala` snippets inside of a Markdown input are not isolated. Each `using` directive applies to the whole project's +context. A directive defined in a later snippet within the same source may override another defined in an earlier one. + +````markdown title="OverriddenDirective.md" +## 1 + +```scala +//> using scala "2.12.17" +println(util.Properties.versionNumberString) +``` + +## 2 + +```scala +//> using scala "2.13.10" +println(util.Properties.versionNumberString) +``` +```` + +In this example, the directive from the second `scala` snippet will override the previous one and Scala `2.13.10` will +be used for both. + + + +```bash ignore +scala-cli OverriddenDirective.md +``` + +```text +Compiling project (Scala 2.13.10, JVM) +Compiled project (Scala 2.13.10, JVM) +2.13.10 +2.13.10 +``` + + + +::: + ## Referring to code from Markdown ### Plain `scala` code blocks -Referring to code from plain `scala` snippets in Markdown requires using their package name. +Referring to code from plain `scala` snippets in markdown requires using their package name. Similarly to scripts, the package is inferred based on the relative path to the source file in your project. You also have to point to the Scope under which the code is located. diff --git a/website/docs/guides/piping.md b/website/docs/guides/piping.md index 68c8d6eb0e..966621e6cb 100644 --- a/website/docs/guides/piping.md +++ b/website/docs/guides/piping.md @@ -29,7 +29,8 @@ The available options are as follows: - for standard Scala code use `_`, `_.scala` or `-.scala`; - for Scala scripts use `-`, `_.sc` or `-.sc`; -- for Java code use `_.java` or `-.java`. +- for Java code use `_.java` or `-.java`; +- for Markdown code use `_.md` or `-.md`. ## Examples @@ -75,6 +76,23 @@ Hello +- Markdown code (experimental) + + + +```bash +echo '# Example Snippet +```scala +println("Hello") +```' | scala-cli _.md +``` + +```text +Hello +``` + + + ## Mixing piped sources with on-disk ones It is also possible to pipe some code via standard input, while the rest of your code is on-disk.