Code Monkey home page Code Monkey logo

deps-try's Introduction

deps-try

Quickly try out Clojure and libraries on rebel-readline:

Screenshot 2023-02-09 at 13 37 09

Subscribe on Polar

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 ๐ŸŒธ

discuss at Clojurians-Zulip

Rationale

This tool 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 into 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.

Features

## Features
  • 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.
  • see what versions are resolved
  • 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)

Installation

Docker

The easiest way to start.

# latest stable
$ docker run -it --pull always ghcr.io/eval/deps-try

# unstable (i.e. master branch)
$ docker run -it --pull always ghcr.io/eval/deps-try:unstable

See -h or Usage for detailed options.

Homebrew (Linux and macOS)

Prerequisites

Ensure you have a Clojure compatible Java version.

Verify that the following commands work:

$ java -version
# example output
openjdk version "21.0.2" 2024-01-16 LTS
OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13-LTS, mixed mode)

Install

$ 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 (Windows, Linux and macOS)

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

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

Prerequisites

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 "21.0.2" 2024-01-16 LTS
OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13-LTS, mixed mode)
$ bbin --version
# example output
bbin 0.2.0

Install

$ 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

manual (Windows, Linux and macOS)

Prerequisites

Verify that the following commands work:

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

Install

#!/usr/bin/env sh

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

Usage

$ deps-try -h
A CLI to quickly try Clojure (libraries) on rebel-readline.

VERSION
  v0.12.0

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.

EXAMPLES
  ;; The latest version of malli from maven, and git-tag v1.3.894 of the next-jdbc repository
  $ deps-try metosin/malli io.github.seancorfield/next-jdbc v1.3.894

COMMANDS
  recipes    list built-in recipes (`recipes --refresh` to update)

More 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 from 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

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

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

Recipes

This feature was sponsored by Clojurists Together โœจ in Q3-2023.

Read all about recipes here.

Bindings

Binding Comment
TAB / Ctrl + I Indent or complete. deps-try-tab
Ctrl + X Ctrl + A Apropos. Search all public vars in loaded namespaces matching word before cursor. deps-try-apropos
Ctrl + X Ctrl + D Show doc of function (or namespace) using word before cursor. Screenshot 2023-04-04 at 15 38 12
Ctrl + X Ctrl + E Eval expression before cursor. deps-try-eval
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 in a position where Return would insert a newline). deps-try-force-accept
Ctrl + X Ctrl + S Show source of function using word before cursor. Screenshot 2023-04-04 at 17 26 47
Ctrl + X Ctrl + X Searches clojuredocs for examples using word before cursor. Screenshot 2023-04-04 at 15 32 26
Ctrl + R Search term Ctrl + R (backward) / Ctrl + S (forward) Searches history for commands containing Search term deps-try-search-history
Esc/Alt + Return Insert newline (where Return would otherwise submit line). deps-try-insert-newline
Code + โ†‘ Searches history for lines starting with Code (e.g. find all requires, defs etc). deps-try-arrow-up
Alt + p / Alt + n Step back-/forward through history without stepping through every line of a history item (as โ†‘/โ†“ do).

FAQ

How to use the vendored rebel-readline in isolation?

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

Credits

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).

LICENSE

Copyright (c) 2024 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.

deps-try's People

Contributors

angusiguess avatar arichiardi avatar aviflax avatar bhauman avatar borkdude avatar clashthebunny avatar enotchy avatar eval avatar gacelita avatar gws avatar heyarne avatar hospadar avatar i-blis avatar mbuczko avatar mdiin avatar schmee avatar shaunlebron avatar souenzzo avatar spinningarrow avatar trptcolin avatar viesti avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

deps-try's Issues

recipe-info

$ deps-try recipes:info deps-try/recipes

name: ,,,
dependencies: ,,,
description: ,,,
steps: 20

Same info would be shown when doing :recipe/info on REPL.

gist as recipe

Currently you need to append /raw to a gist-url to successfully load it as recipe.

Doesn't work:

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

Does work:

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

The former should be supported as well.

Quote of the day

No better way to start a REPL-session than a good quote.

Almost all new ideas
have a certain aspect of foolishness
when they are first produced

Alfred North Whitehead

second git-url treated as version of first

$ deps-try https://github.com/metosin/sieppari https://github.com/fixpoint-clojure/interceptors
Could not find branch or tag 'https://github.com/fixpoint-clojure/interceptors' in repository 'https://github.com/metosin/sieppari'.

recipe creation

$ deps-try recipes:create --ns recipes.clojure.intro 
(ns recipes.clojure.intro
  "Title here"
  {:deps-try.recipe/deps ["replace/me" "0.1.2"]})

;; step 1
(+ 1 2)


;; step 2
(/ 6 3)

Should be easy to create recipes based on last X steps in REPL-history:

# right after closed REPL-session
$ deps-try recipes:create --ns recipes.clojure.intro --include-history 10 

naming: include-history, history-items, last-history-items...

recipes

Not sure about the recipe name, but aiming for something like:

$ deps-try --recipe gist.github.com/some/gist

This seeds the history with the commands in the gist.
Behavior:

  • history (arrow up progresses down this list):
    • gist command 1
    • gist command 2
    • etc
    • latest command user's history
    • etc
  • run command:
    • put it in user's history
    • 'gist command 2' now top of history
  • commands are labeled in order to easily find them (for this session or when stored in user's history). Also needed to see what commands from recipe were run:
;; recipe.name/1
;; Introduction to malli...
;; Let's get the libraries needed for this recipe:
:deps/try metosin/malli
;; recipe.name/2
;; Let's require the namespaces we need:
(require '[malli.core :as m])

doc-at-point doesn't work on alias

(require '[clojure.set :as cset])
(clojure.set| ;; ^X^D works
(cset| ;; doesn't work

Will come in handy:

(compliment.utils/resolve-namespace 'cset *ns*)

No such var: fs/xdg-data-home when trying specific dep

Thank you for your work Gert! :)

Found a small issue with a specific repo that I wanted to try. I wanted to try Squint and I found a weird interaction with the babashka/fs dependency. A work around is to add the dep manually (deps-try babashka/fs io.github.squint-cljs/squint). I don't see yet what the cause is though. A shell session below.

(FYI, I installed deps-try via bbin install io.github.eval/deps-try, works fine, after finding the error I also tried the other ways, but that was not it).

Shell session:

โžœ bb version
babashka v1.3.184

โžœ deps-try -v
deps-try-dev v0.8.0

โžœ deps-try io.github.squint-cljs/squint
Syntax error compiling at (eval/deps_try/try.clj:115:30).
No such var: fs/xdg-data-home

Full report at:
/var/folders/2w/4mynsgjs28j637qzqkxt1lsr0000gn/T/clojure-8442043964243317078.edn

โžœ deps-try babashka/fs io.github.squint-cljs/squint

[Rebel readline] Type :repl/help for online help info
user=> (require 'squint.compiler)
WARNING: *repl* already refers to: #'clojure.core/*repl* in namespace: squint.compiler-common, being replaced by: #'squint.compiler-common/*repl*
nil
user=> (squint.compiler/compile-string (pr-str '(fn [e] "hello")))
"import * as squint_core from 'squint-cljs/core.js';\nfunction (e) {\nreturn \"hello\";\n};\n"
user=>

Error when trying dep without namespace

I tried deps-try amazonica "0.3.165" which results in an error Could not find path '***/amazonica'

I should have tried deps-try amazonica/amazonica "0.3.165" instead, and then things work as expected.

This might not be obvious for new users. I also had to think for a bit. And this would also not be obvious by reading the README of Amazonica where it is still [amazonica "0.3.165"].

When there is no namespace maybe if the directory doesn't exist (in this case amazonica), deps-try could try to resolve it as a dependency?

(*) tested with version deps-try-dev v0.8.0

take project deps into account

Currently deps.edn is ignored in order to make sessions as deterministic as possible.
It has value though to 'try' project-code.

directions

  • using :local/root (version possible?)
    pointing elsewhere: deps-try ../project
    at PWD: deps-try .
  • the latter case could be supported by a config setting as well: take ./deps.edn into account when present

dep/git: make trying PR/MR's easier

Both GitHub and GitLab support special refs for PR/MR's. Resp. refs/pull/123/head (and refs/pull/123/merge) and refs/merge-requests/123/head (and refs/merge-requests/123/merge). All of these refs currently work. But it would be nice to make these first-class-versions, e.g.:

$ deps-try com.github.metosin/malli pr/123 mr/123

docker image

It might feel safer for some users to always execute code (especially with recipes) in a sandbox.

$ docker run -it eval/deps-try metosin/malli

Upvote & Fund

  • We're using Polar.sh so you can upvote and help fund this issue.
  • We receive the funding once the issue is completed & confirmed by you.
  • Thank you in advance for helping prioritize & fund our backlog.
Fund with Polar

resolving library fails

Currently com.github.user/project is treated as a git/url, but it's also a format used for artifacts.
Failing examples:
com.github.kyleburton/clj-xpath (it exists on github but is not using tools-deps).

make installing simpler

Feedback from /r/clojure:

it'd be lovely to have a ready-to-use binary release instead of having to install bbin from a Homebrew (because that would be like third package manager I have on my Linux, which is two more than a reasonable amount).

Hanging after ^D

user=> :deps/try https://github.com/metosin/malli
user=> ^D
# hangs a minute before terminating

Seems due to threads that are still active. A simple (future (prn 1)) has the same issue.

shortcut for require?

The completer currently shows namespace suggestions based on files found on classpath, e.g. clojure.data.x becomes clojure.data.xml. Though adding a slash then and hitting TAB to dig deeper will however do nothing as clojure.data.xml is not required and so no var can be suggested.

A shortcut for require-at-point would allow for quick exploration of the namespace at hand.

Downside would be that the code that you end up with in e.g. the history is less useful: the user depended on separate actions to make the code work.

debug-flag

Following should be accepted:
$ deps-try -d/--debug

Together with a logical (announced?) place to store the file.

version-flag

$ deps-try -v/--version

directions

  • have version built-in
    cons:

    • double administration with tags

    pro:

    • easiest
  • trigger CI and bake version in
    cons:

    • more involved as CI needs to create a tagged commit

Deps needing prep

problem

This fails:

$ deps-try-dev io.github.yogthos/Selmer
[Rebel readline] Type :repl/help for online help info
user=> (require '[selmer.parser :as selmer])
Execution error (FileNotFoundException) at user/eval8200 (REPL:1).
Could not locate selmer/parser__init.class, selmer/parser.clj or selmer/parser.cljc on classpath.
user=>

because this fails:

~/projects/deps-try/deps-try (master *=)
$ clj -Sdeps '{:deps {io.github.yogthos/Selmer {:git/sha "d1a40e5114427d3176fb5269425780abcf461924"}}}'
Error building classpath. The following libs must be prepared before use: [io.github.yogthos/Selmer]

Needed: https://clojure.org/guides/deps_and_cli#prep_libs

directions

  • err
  • prep

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.