Merge pull request #3978 from VirtusLab/stable

Back port of documentation changes to main
- #3975

Author: Gedochao

website/docs/commands/repl.md

@@ -119,20 +119,47 @@ scala>
 
 </ChainedSnippets>
 
+- via a using directive, treating them as Scala compiler options:
+
+<ChainedSnippets>
+
+```scala compile title=repl-options.scala
+//> using toolkit default
+//> using options --repl-init-script "import os.*; println(pwd)"
+```
+
+```bash ignore
+scala repl repl-options.scala
+```
+
+```
+/current/directory/path
+Welcome to Scala 3.7.4 (17, Java OpenJDK 64-Bit Server VM).
+Type in expressions for evaluation. Or try :help.
+                                                                         
+scala> pwd
+val res0: os.Path = /current/directory/path
+scala> :quit
+```
+
+</ChainedSnippets>
+
 - directly, as a Scala CLI option (do note that newly added options from an RC version or a snapshot may not be supported this way just yet):
 
 <ChainedSnippets>
 
 ```bash ignore
-scala repl -S 3.6.4-RC1 --repl-init-script 'println("Hello")'
+scala repl --repl-init-script 'println("Hello")'
 ```
 
 ```
 Hello
 Welcome to Scala 3.6.4-RC1 (23.0.1, Java OpenJDK 64-Bit Server VM).
 Type in expressions for evaluation. Or try :help.
-                                                                                                                 
-scala> 
+                                                                         
+scala> pwd
+val res0: os.Path = /current/directory/path
+scala> :quit
 ```
 
 </ChainedSnippets>
@@ -147,20 +174,54 @@ scala-cli repl --toolkit default
 ```
 
 ```text
-Welcome to Scala 3.3.1 (17, Java OpenJDK 64-Bit Server VM).
+Welcome to Scala 3.7.4 (17, Java OpenJDK 64-Bit Server VM).
 Type in expressions for evaluation. Or try :help.
                                                                                 
-scala> import os._
+scala> import os.*
                                                                                 
 scala> os.pwd
-val res0: os.Path = /Users/yadukrishnan/test
+val res0: os.Path = /current/directory/path
 scala> :quit
 
 ```
 </ChainedSnippets>
 
 Since we started the repl with toolkit enabled, we can use the libraries included in the toolkit directly. In the above example, the `os-lib` library from the toolkit is used to print the current path. 
 
+### Running snippets directly via the REPL
+It is possible to run code snippets via the REPL, with all the internal quirks of the REPL, rather than using standard runner execution.
+While the difference is subtle and should generally be invisible to users, it is useful for investigating REPL behavior.
+The key to doing that is to use the both `--repl-init-script` and `--repl-quit-after-init` options together.
+
+<ChainedSnippets>
+
+
+```bash
+scala repl --repl-init-script 'println(42)' --repl-quit-after-init # runs in the REPL and quits immediately
+```
+
+```
+42
+```
+
+```bash
+scala repl -e '//> using options --repl-init-script "println(42)" --repl-quit-after-init' # same, but via using directive
+```
+
+```
+42
+```
+
+```bash
+scala -e 'println(42)' # standard runner equivalent
+```
+
+```
+42
+```
+
+</ChainedSnippets>
+
 ## Inject code as JAR file in class path
 
 If your application inspects its class path, and requires only JAR files in it, use `--as-jar` to