Quickly try out Clojure and libraries on rebel-readline:

This README is aimed at people starting their Clojure journey as well as Clojure experts. If anything is not clear, or you learned something that might help other starters, please open an issue or start a new discussion 🌸

This tools targets both Clojure newcomers as well as Clojure experts.

Trying out Clojure is easier when you have code completion, syntax highlighting and function documentation and examples nearby. deps-try provides a REPL with exactly these IDE functionalities (and some more).
This means there's no need to install or configure any Clojure plugins/extensions for your editor. Also you don't need to setup a project this way, so instead of diving in the nitty gritty details of a deps.edn configuration file, you can start writing Clojure.

Adding maven/git/local-libraries can be done using a convenient notation:

$ deps-try some-maven/library com.github.user/a-git-project ~/some/local/project

# add additional libraries during a REPL-session (no restart needed)
users=> :deps/try another/library "https://github.com/seancorfield/next-jdbc" "../other/local/project"

Again, no need to setup or adjust a project, or type out the full configuration at the command line.

• always use the latest release of Clojure.
• conveniently use dependencies from maven/clojars, various git-hostings or local projects.
• add dependencies without restarting the REPL.
• recipes
  • seed the REPL-history with steps from a file.
• dependencies are resolved in isolation (as much as possible)
  • ...ignoring global, project or project deps.edn.
• rebel-readline provides:
  • syntax highlighting and indentation
  • code completion
  • see the docstring and source of a function
• deps-try extends rebel-readline with:
  • show examples of a function from clojuredocs.org
  • pprint results with syntax highlighting
  • interrupt operations without quiting the REPL
  • easier copy/paste of multiline code
  • improved support for eval-at-point (e.g. set and list literals, var quote, deref)
  • eval&tap-at-point
    • like eval-at-point and it taps the result.
    • taps the last result/exception on an empty line.
  • improved suggestions
    • more shown
    • different colors for fns and vars, private vars/fns and deprecated vars.
• toggle Clojure settings
  • clojure.core/*print-meta*
  • clojure.core/*print-namespace-maps* (default off)

• Install Clojure
• Install babashka

Verify that the following commands work:

$ clj
# REPL starts successfully, ergo Clojure and Java are correctly configured.
$ bb --version
babashka v1.3.176

• Download the latest stable bb-jar.
• Put an executable wrapper-script on $PATH. For example (for Linux and macOS):

#!/usr/bin/env sh

exec bb /absolute/path/to/deps-try-bb.jar "$@"

Ensure you have a Clojure compatible Java version.

Verify that the following commands work:

$ java -version
# example output
openjdk version "17.0.2" 2022-01-18
OpenJDK Runtime Environment Temurin-17.0.2+8 (build 17.0.2+8)
OpenJDK 64-Bit Server VM Temurin-17.0.2+8 (build 17.0.2+8, mixed mode)

$ brew install eval/brew/deps-try
# For future upgrades do:
$ brew update && brew upgrade deps-try

There's also the unstable releases (the latest master):

$ brew install --head eval/brew/deps-try
# For future upgrades do:
$ brew update && brew reinstall deps-try

bbin allows for easy installation of Babashka scripts (such as deps-try).

It's currently the only way to install deps-try on Windows.

Ensure you have a Clojure compatible Java version.

Also: install bbin (make sure to adjust $PATH).

Verify that the following commands work:

$ java -version
# example output
openjdk version "17.0.2" 2022-01-18
OpenJDK Runtime Environment Temurin-17.0.2+8 (build 17.0.2+8)
OpenJDK 64-Bit Server VM Temurin-17.0.2+8 (build 17.0.2+8, mixed mode)
$ bbin --version
# example output
bbin 0.1.12

$ bbin install https://github.com/eval/deps-try/releases/download/stable/deps-try-bb.jar --as deps-try
# or the unstable version (latest master)
$ bbin install https://github.com/eval/deps-try/releases/download/unstable/deps-try-bb.jar --as deps-try-unstable

# Check version
$ deps-try -v

# Re-run the install command to upgrade

USAGE
  $ deps-try [dep-name [dep-version] [dep2-name ...] ...] [--recipe[-ns] recipe]

OPTIONS
  dep-name
    dependency from maven (e.g. `metosin/malli`, `org.clojure/cache`),
    git (e.g. `com.github.user/project`, `ht.sr.user/project`,
    `https://github.com/user/project`, `https://anything.org/user/project.git`),
    or a local folder containing a file `deps.edn` (e.g. `.`,
    `~/projects/my-project`, `./path/to/project`).

  dep-version (optional)
    A maven version (e.g. `1.2.3`, `LATEST`) or git ref (e.g. `some-branch`,
    `v1.2.3`).
    The id of a PR or MR is also an acceptable version for git deps (e.g. `^123`).
    When not provided, `LATEST` is implied for maven deps and the latest SHA
    of the default-branch for git deps.

  --recipe, --recipe-ns
    Name of recipe (see recipes command) or a path or url to a Clojure file.
    The REPL-history will be seeded with the (ns-)steps from the recipe.

COMMANDS
  recipes  show list of recipes

Examples:
# A REPL using the latest Clojure version
$ deps-try

# A REPL with specific dependencies (latest version implied)
$ deps-try metosin/malli criterium/criterium

# ...specific version
$ deps-try metosin/malli 0.9.2

# Dependency from GitHub/GitLab/SourceHut (gets you the latest SHA from the default branch)
$ deps-try https://github.com/metosin/malli

# ...a specific branch/tag/SHA
$ deps-try https://github.com/metosin/malli some-branch-tag-or-sha

# ...using the 'infer' notation, e.g.
# com.github.<user>/<project>, com.gitlab.<user>/<project>, ht.sr.~<user>/<project>
$ deps-try com.github.metosin/malli
# testdriving some PR (or MR on gitlab):
$ deps-try com.github.metosin/malli ^123

# A local project
$ deps-try . ~/some/project ../some/other/project

# Loading a recipe
# ...built-in recipe (to learn more about recipes)
$ deps-try --recipe deps-try/recipes

# ...external
$ deps-try --recipe https://gist.github.com/eval/ee80ebddaa120a7732396cea8cfc96da/raw

During a REPL-session:
# add additional dependencies
user=> :deps/try dev.weavejester/medley "~/some/project"

# see help for all options
user=> :repl/help

This feature was sponsored by Clojurists Together ✨ in Q3-2023.

Recipes are normal Clojure files (local or online) that are split up in steps (i.e. a block of code separated by two empty lines). When you load a recipe these steps are then first in REPL-history until a step is submitted, walking you through the recipe as it were.
Recipes can be used as tutorials, bug reports, walkthroughs, or just function as a snippet that contains dependencies, requires and helper-functions to get you started quickly in some domain.

There's a couple of built-in recipes (sources):

# showing built-in recipes
$ deps-try recipes
name                    title
──────────────────────  ─────────────────────────────────────────────────────────────────────────────────────
deps-try/recipes        Introducing recipes
malli/malli-select      Introduction to malli-select, a library for spec2-inspired selection of Malli-schemas
next-jdbc/intro-sqlite  A next-jdbc introduction using SQLite
portal/intro            Introduction to portal, a Clojure tool to navigate data

# loading
$ deps-try --recipe deps-try/recipes

# online recipe
$ deps-try --recipe https://gist.github.com/eval/ee80ebddaa120a7732396cea8cfc96da/raw

# local recipe
$ deps-try --recipe ./path/to/recipe.clj

If you have suggestions for (new) recipes: PRs are welcome!

Binding	Comment
TAB / Ctrl + I	Indent or complete.
Ctrl + X Ctrl + A	Apropos. Search all public vars in loaded namespaces matching word for cursor.
Ctrl + X Ctrl + D	Show doc of function (or namespace) using word before cursor.
Ctrl + X Ctrl + E	Eval expression before cursor.
Ctrl + X Ctrl + T	Eval expression before cursor and tap> the result (taps the last result/exception on empty line).
Ctrl + X Ctrl + M	Force accept line (when cursor is a position where Return would insert a newline).
Ctrl + X Ctrl + S	Show source of function using word before cursor.
Ctrl + X Ctrl + X	Searches clojuredocs for examples using word before cursor.
Ctrl + R Search term Ctrl + R (backward) / Ctrl + S (forward)	Searches history for commands containing Search term
Esc/Alt + Return	Insert newline (where Return would otherwise submit line).
Code + ↑	Searches history for lines starting with Code (e.g. find all requires, defs etc).
Alt + p / Alt + n	Step back-/forward through history without stepping through every line of a history item (as ↑/↓ do).

I got you:

$ clojure -Sdeps '{:deps {com.github.eval/deps-try {:deps/root "vendor/rebel-readline/rebel-readline" :git/sha "3781e67c3afae3b51f414db1b12abe5ff33d480b"}}}' -m rebel-readline.main

Big thanks to Bruce Hauman and contributors for creating rebel-readline 🌸.
While the GitHub contributors page now only shows a meager 1 commit from Bruce Hauman, this couldn't be farther from the truth obviously.
Big thanks to Avery Quinn for coming up with lein-try which inspired the creation of this project (once tools-deps came out).

Copyright (c) 2023 Gert Goet, ThinkCreate. Distributed under the MIT license. See LICENSE.

Code in vendor/rebel-readline originates from rebel-readline which is covered by the Eclipse Public License either version 1.0 or (at your option) any later version.