You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## srp: scala-repl-pp (or even longer: Scala REPL PlusPlus)
4
-
srp wraps the stock Scala 3 REPL and adds many features inspired by ammonite and scala-cli. srp has only one (direct) dependency: the scala3-compiler[(*)](#fineprint).
4
+
When you read `srp` think "syrup" - full of goodness, glues things together :slightly_smiling_face:
5
5
6
-
This is (also) a breeding ground for improvements to the stock Scala REPL: we're forking parts of the REPL to later bring the changes back into the dotty codebase.
6
+
`srp` enhances the stock Scala 3 REPL with features such as adding dependencies via maven coordinates and scripting. Plus: you can add it as a library dependency to your project, empowering it with a customizable REPL and scripting functionality.
*`srp` is published with the full scala version suffix (e.g. `_3.6.4` instead of just `_3`) because the stock Scala REPL often has binary incompatible changes between minor version changes - different Scala patch versions typically work though, e.g. if your build uses Scala 3.6.3 you can use `scala-repl-pp_3.6.4`
23
+
*`srp` has only one direct dependency: the scala3-compiler[(*)](#fineprint)
20
24
21
-
## TOC
25
+
## Table of contents
22
26
<!-- generated with:
23
-
markdown-toc --maxdepth 3 README.md|tail -n +4
27
+
markdown-toc --maxdepth 3 README.md|tail -n +5
24
28
-->
25
-
-[Benefits over / comparison with](#benefits-over--comparison-with)
26
-
*[Regular Scala REPL](#regular-scala-repl)
27
-
*[Ammonite](#ammonite)
28
-
*[scala-cli](#scala-cli)
29
-
-[Prerequisite for all of the below: run `sbt stage` or download the latest release](#prerequisite-for-all-of-the-below-run-sbt-stage-or-download-the-latest-release)
30
29
-[Usage](#usage)
31
30
*[run with defaults](#run-with-defaults)
32
31
*[execute code at the start with `--runBefore`](#execute-code-at-the-start-with---runbefore)
*[Why do we ship a shaded copy of other libraries and not use dependencies?](#why-do-we-ship-a-shaded-copy-of-other-libraries-and-not-use-dependencies)
60
59
*[Where's the cache located on disk?](#wheres-the-cache-located-on-disk)
61
60
*[Why am I getting an AssertionError re `class module-info$` on first tab completion?](#why-am-i-getting-an-assertionerror-re-class-module-info-on-first-tab-completion)
*[How can I build/stage a local version?](#how-can-i-buildstage-a-local-version)
64
67
*[How can I get a new binary (bootstrapped) release?](#how-can-i-get-a-new-binary-bootstrapped-release)
65
68
*[Adding support for a new Scala version](#adding-support-for-a-new-scala-version)
66
69
*[Updating the shaded libraries](#updating-the-shaded-libraries)
67
70
-[Fineprint](#fineprint)
68
71
69
-
## Benefits over / comparison with
70
-
71
-
### Regular Scala REPL
72
-
* add runtime dependencies on startup with maven coordinates - automatically handles all downstream dependencies via [coursier](https://get-coursier.io/)
73
-
*`#>`, `#>>` and `#|` operators to redirect output to file and pipe to external command
74
-
* customize greeting, prompt and shutdown code
75
-
* multiple @main with named arguments (regular Scala REPL only allows an argument list)
76
-
* predef code - i.e. run custom code before starting the REPL - via string and scripts
77
-
* server mode: REPL runs embedded
78
-
* easily embeddable into your own build
79
-
* structured rendering including product labels and type information:<br/>
* Ammonite's Scala 3 support is far from complete - e.g. autocompletion for extension methods has [many shortcomings](https://github.com/com-lihaoyi/Ammonite/issues/1297). In comparison: srp uses the regular Scala3/dotty ReplDriver.
89
-
* Ammonite has some Scala2 dependencies intermixed, leading to downstream build problems like [this](https://github.com/com-lihaoyi/Ammonite/issues/1241). It's no longer easy to embed Ammonite into your own build.
90
-
* Note: Ammonite allows to add dependencies dynamically even in the middle of the REPL session - that's not supported by srp currently. You need to know which dependencies you want on startup.
91
-
92
-
### [scala-cli](https://scala-cli.virtuslab.org/)
93
-
* srp has a 66.6% shorter name :slightly_smiling_face:
94
-
scala-cli wraps and invokes the regular Scala REPL (by default; or optionally Ammonite). It doesn't modify/fix the REPL itself, i.e. the above mentioned differences between srp and the stock scala repl (or alternatively Ammonite) apply, with the exception of dependencies: scala-cli does let you add them on startup as well.
95
72
96
-
## Prerequisite for all of the below: run `sbt stage` or download the latest release
97
73
98
74
## Usage
99
75
The below features are all demonstrated using the REPL but also work when running scripts.
Note: if your dependencies are not hosted on maven central, you can [specify additional resolvers](#additional-dependency-resolvers-and-credentials) - including those that require authentication)
234
210
235
-
Implementation note: srp uses [coursier](https://get-coursier.io/) to fetch the dependencies. We invoke it in a subprocess via the coursier java launcher, in order to give our users maximum control over the classpath.
211
+
Implementation note: `srp` uses [coursier](https://get-coursier.io/) to fetch the dependencies. We invoke it in a subprocess via the coursier java launcher, in order to give our users maximum control over the classpath.
Unlike the stock Scala REPL, srp does _not_ truncate the output by default. You can optionally specify the maxHeight parameter though:
260
+
Unlike the stock Scala REPL, `srp` does _not_ truncate the output by default. You can optionally specify the maxHeight parameter though:
285
261
```
286
262
./srp --maxHeight 5
287
263
scala> (1 to 100000).toSeq
@@ -293,7 +269,7 @@ val res0: scala.collection.immutable.Range.Inclusive = Range(
293
269
```
294
270
295
271
### Exiting the REPL
296
-
Famously one of the most popular question on stackoverflow is about how to exit `vim` - fortunately you can apply the answer as-is to exit srp :slightly_smiling_face:
272
+
Famously one of the most popular question on stackoverflow is about how to exit `vim` - fortunately you can apply the answer as-is to exit `srp`:slightly_smiling_face:
297
273
```
298
274
// all of the following exit the REPL
299
275
:exit
@@ -429,7 +405,7 @@ otherone.username=j
429
405
otherone.password=imj
430
406
otherone.host=nexus.other.com
431
407
```
432
-
The prefix is arbitrary and is only used to specify several credentials in a single file. srp uses [coursier](https://get-coursier.io) to resolve dependencies.
408
+
The prefix is arbitrary and is only used to specify several credentials in a single file. `srp` uses [coursier](https://get-coursier.io) to resolve dependencies.
433
409
434
410
### Attach a debugger (remote jvm debug)
435
411
For the REPL itself:
@@ -446,7 +422,7 @@ If you want to debug a script, it's slightly different. Scripts are executed in
446
422
```
447
423
448
424
## Server mode
449
-
Note: srp-server isn't currently available as a bootstrapped binary, so you have to [stage it locally](#how-can-i-buildstage-a-local-version) first using `sbt stage`.
425
+
Note: `srp-server` isn't currently available as a bootstrapped binary, so you have to [stage it locally](#how-can-i-buildstage-a-local-version) first using `sbt stage`.
# {"success":true,"stdout":"val res0: Int = 1\n",...}%
503
479
```
504
480
505
-
srp-server can be used in an asynchronous mode:
481
+
`srp-server` can be used in an asynchronous mode:
506
482
```
507
483
./srp-server
508
484
@@ -542,7 +518,7 @@ If verbose mode is enabled, you'll get additional information about classpaths a
542
518
To enable it, you can either pass `--verbose` or set the environment variable `SCALA_REPL_PP_VERBOSE=true`.
543
519
544
520
## Inherited classpath
545
-
srp comes with it's own classpath dependencies, and depending on how you invoke it there are different requirements for controlling the inherited classpath. E.g. if you add `srp` as a dependency to your project and want to simply use all dependencies from that same project, you can configure `--cpinherit` (or programatically `replpp.Config.classpathConfig.inheritClasspath`). You can also include or exclude dependencies via regex expressions.
521
+
`srp` comes with it's own classpath dependencies, and depending on how you invoke it there are different requirements for controlling the inherited classpath. E.g. if you add `srp` as a dependency to your project and want to simply use all dependencies from that same project, you can configure `--cpinherit` (or programatically `replpp.Config.classpathConfig.inheritClasspath`). You can also include or exclude dependencies via regex expressions.
546
522
547
523
## Parameters cheat sheet: the most important ones
548
524
Here's only the most important ones - run `srp --help` for all parameters.
@@ -560,12 +536,12 @@ Here's only the most important ones - run `srp --help` for all parameters.
560
536
561
537
### Is this an extension of the stock REPL or a fork?
562
538
Technically it is a fork, i.e. we copied parts of the ReplDriver to make some adjustments.
563
-
However, semantically, srp can be considered an extension of the stock repl. We don't want to create and maintain a competing REPL implementation,
539
+
However, semantically, `srp` can be considered an extension of the stock repl. We don't want to create and maintain a competing REPL implementation,
564
540
instead the idea is to provide a space for exploring new ideas and bringing them back into the dotty codebase.
565
541
[When we forked](https://github.com/mpollmeier/scala-repl-pp/commit/eb2bf9a3bed681bffa945f657ada14781c6a7a14) the stock ReplDriver, we made sure to separate the commits into bitesized chunks so we can easily rebase. The changes are clearly marked, and whenever there's a new dotty version we're bringing in the relevant changes here (`git diff 3.3.0-RC5..3.3.0-RC6 compiler/src/dotty/tools/repl/`).
566
542
567
543
### Why do we ship a shaded copy of other libraries and not use dependencies?
568
-
srp includes some small libraries (e.g. most of the com-haoyili universe) that have been copied as-is, but then moved into the `replpp.shaded` namespace. We didn't include them as regular dependencies, because repl users may want to use a different version of them, which may be incompatible with the version the repl uses. Thankfully their license is very permissive - a big thanks to the original authors! The instructions of how to (re-) import then and which versions were used are available in [import-instructions.md](shaded-libs/import-instructions.md).
544
+
`srp` includes some small libraries (e.g. most of the com-haoyili universe) that have been copied as-is, but then moved into the `replpp.shaded` namespace. We didn't include them as regular dependencies, because repl users may want to use a different version of them, which may be incompatible with the version the repl uses. Thankfully their license is very permissive - a big thanks to the original authors! The instructions of how to (re-) import then and which versions were used are available in [import-instructions.md](shaded-libs/import-instructions.md).
Many features of `srp` were shaped by ammonite and scala-cli - thank you! I would have preferred to use those projects instead of creating `srp`, but they lacked certain features that I needed - most importantly I needed the relative maturity of the stock Scala REPL with the ability to include it as a library. Here's a rough overview of the differences between `srp` and other options:
586
+
587
+
### Stock Scala REPL
588
+
`srp` allows you to:
589
+
* use it as a library with minimal dependencies in your own build
590
+
* add runtime dependencies on startup with maven coordinates - it automatically handles all downstream dependencies via [coursier](https://get-coursier.io/)
591
+
* use `#>`, `#>>` and `#|` operators to redirect output to file and pipe to external command
592
+
* customize the greeting, prompt and shutdown code
593
+
* multiple @main with named arguments (regular Scala REPL only allows an argument list)
594
+
* import additional files with directives and parameters
595
+
* run code on startup and shutdown
596
+
* server mode: REPL runs embedded
597
+
* structured rendering including product labels and type information:<br/>
*`srp` allows you to use it as a library with minimal dependencies in your own build
606
+
* scala-cli wraps and invokes the regular Scala REPL (by default; or optionally Ammonite). It doesn't modify/fix the REPL itself, i.e. most differences between `srp` and the stock scala repl from above apply, with the exception of e.g. dependencies: scala-cli does let you add them on startup as well.
607
+
*`srp` has a 66.6% shorter name :slightly_smiling_face:
608
+
609
+
### [Ammonite](http://ammonite.io)
610
+
*`srp` allows you to use it as a library with minimal dependencies in your own build
611
+
* Ammonite's Scala 3 support is far from complete - e.g. autocompletion for extension methods has [many shortcomings](https://github.com/com-lihaoyi/Ammonite/issues/1297). In comparison: `srp` uses the regular Scala3/dotty ReplDriver.
612
+
* Ammonite has some Scala2 dependencies intermixed, leading to downstream build problems like [this](https://github.com/com-lihaoyi/Ammonite/issues/1241). It's no longer easy to embed Ammonite into your own build.
613
+
* Note: Ammonite allows to add dependencies dynamically even in the middle of the REPL session - that's not supported by `srp` currently. You need to know which dependencies you want on startup.
614
+
615
+
616
+
608
617
## Contribution guidelines
609
618
610
619
### How can I build/stage a local version?
@@ -633,6 +642,6 @@ If there's any binary incompatible changes (which is typically the case between
633
642
See [import-instructions.md](shaded-libs/import-instructions.md).
634
643
635
644
## Fineprint
636
-
(*) To keep our codebase concise we do use libraries, most importantly the [com.lihaoyi](https://github.com/com-lihaoyi/) stack. We want to ensure that users can freely use their own dependencies without clashing with the srp classpath though, so we [copied them into our build](shaded-libs/src/main/scala/replpp/shaded) and [changed the namespace](shaded-libs/import-instructions) to `replpp.shaded`. Many thanks to the original authors, also for choosing permissive licenses.
645
+
(*) To keep our codebase concise we do use libraries, most importantly the [com.lihaoyi](https://github.com/com-lihaoyi/) stack. We want to ensure that users can freely use their own dependencies without clashing with the `srp` classpath though, so we [copied them into our build](shaded-libs/src/main/scala/replpp/shaded) and [changed the namespace](shaded-libs/import-instructions) to `replpp.shaded`. Many thanks to the original authors, also for choosing permissive licenses.
0 commit comments