{"id":13491301,"url":"https://github.com/bhauman/rebel-readline","last_synced_at":"2025-05-16T10:07:46.671Z","repository":{"id":29269817,"uuid":"117266450","full_name":"bhauman/rebel-readline","owner":"bhauman","description":"Terminal readline library for Clojure dialects","archived":false,"fork":false,"pushed_at":"2025-05-12T15:18:55.000Z","size":411,"stargazers_count":700,"open_issues_count":70,"forks_count":38,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-12T16:33:40.068Z","etag":null,"topics":["clojure","clojure-library","clojurescript","readline-library","repl"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bhauman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["bhauman"]}},"created_at":"2018-01-12T16:56:51.000Z","updated_at":"2025-05-12T15:18:59.000Z","dependencies_parsed_at":"2024-06-18T22:33:28.036Z","dependency_job_id":"37882478-c9c9-4283-9cb6-cc7ae1e70aac","html_url":"https://github.com/bhauman/rebel-readline","commit_stats":{"total_commits":306,"total_committers":20,"mean_commits":15.3,"dds":0.07189542483660127,"last_synced_commit":"6c314f8fe1cb44bde3a0511bf14d48157f89f6d7"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhauman%2Frebel-readline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhauman%2Frebel-readline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhauman%2Frebel-readline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhauman%2Frebel-readline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bhauman","download_url":"https://codeload.github.com/bhauman/rebel-readline/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509476,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","clojure-library","clojurescript","readline-library","repl"],"created_at":"2024-07-31T19:00:55.382Z","updated_at":"2025-05-16T10:07:41.653Z","avatar_url":"https://github.com/bhauman.png","language":"Clojure","funding_links":["https://github.com/sponsors/bhauman"],"categories":["Clojure","Libraries"],"sub_categories":[],"readme":"# Rebel Readline\n\n[![Clojars Project](https://img.shields.io/clojars/v/com.bhauman/rebel-readline.svg)](https://clojars.org/com.bhauman/rebel-readline)\n[![Clojars Project](https://img.shields.io/clojars/v/com.bhauman/rebel-readline-cljs.svg)](https://clojars.org/com.bhauman/rebel-readline-cljs)\n[![Clojars Project](https://img.shields.io/clojars/v/com.bhauman/rebel-readline-nrepl.svg)](https://clojars.org/com.bhauman/rebel-readline-nrepl)\n\nWelcome to **Rebel Readline** – the snazzy terminal REPL for Clojure!\n\n![asciicast](https://asciinema.org/a/160597.png)\n\n## Features\n\nRebel Readline offers a Clojure REPL with:\n\n- Easy multi-line editing\n- Auto-indentation\n- TAB completion\n- Argument documentation displayed after typing a function name\n- Inline evaluation, allowing you to evaluate code without pressing enter\n- Quick access to documentation, source, and apropos for the symbol under the cursor\n- Familiar terminal key bindings, including history search, etc.\n\nRebel Readline is also a library that provides a line reader for Clojure dialects.\n\n## Purpose\n\nLearn more about the motivations behind creating this terminal readline library [here](https://github.com/bhauman/rebel-readline/blob/master/rebel-readline/doc/intro.md).\n\n## nREPL Support\n\nRecent updates include nREPL support. For details, refer to [rebel-readline-nrepl](./rebel-readline-nrepl).\n\n## Important Note\n\nThe line reader requires direct terminal access. Therefore, do not launch Rebel Readline using `clj` or any other readline processes (like `rlwrap`) to avoid conflicts. Use one of the following options to start the JVM:\n\n- The java command\n- The Clojure `clojure` tool (without readline support)\n- `lein trampoline`\n- `boot` (must run in Boot's worker pod)\n\n## Quick Start\n\nTo quickly try Rebel Readline, [install the Clojure CLI tools](https://clojure.org/guides/getting_started) and execute:\n\n```shell\nclojure -Sdeps \"{:deps {com.bhauman/rebel-readline {:mvn/version \\\"0.1.5\\\"}}}\" -M -m rebel-readline.main\n```\n\n## Usage\n\n### Key Bindings in the REPL\n\nRebel Readline defaults to Emacs-style key bindings, which can be configured. \n\n#### Notable Key Bindings:\n\n- **Ctrl-C**: Abort the current line\n- **Ctrl-D** at line start: Send an end-of-stream signal (usually quits the REPL)\n- **TAB**: Word completion or code indentation \n- **Ctrl-X Ctrl-D**: Show documentation for the current symbol\n- **Ctrl-X Ctrl-S**: Show source code for the current symbol\n- **Ctrl-X Ctrl-A**: Show apropos information for the current symbol\n- **Ctrl-X Ctrl-E**: Inline evaluation for SEXP\n\nYou can explore additional key bindings with the `:repl/key-bindings` command.\n\n### Commands in the REPL\n\nCommands start with the `:repl/...` keyword. For available commands, type `:repl/help` or `:repl` followed by TAB.\n\nYou can add new commands by implementing methods for the `rebel-readline.commands/command` multimethod and documenting them using `rebel-readline.commands/command-doc`.\n\n## Installation\n\nAdd Rebel Readline as a tool within your `~/.clojure/deps.edn`:\n\n```clojure\n{\n ...\n :aliases {:rebel {:extra-deps {com.bhauman/rebel-readline {:mvn/version \"0.1.5\"}}\n                   :exec-fn rebel-readline.tool/repl\n                   :exec-args {}\n                   :main-opts [\"-m\" \"rebel-readline.main\"]}}\n ...\n}\n```\n\nYou can then launch the REPL in your project directory with:\n\n```shell\nclojure -Xrebel \n```\nRemember to use `clojure` instead of `clj` to avoid interference from other readline tools.\n\nAlternatively, run it as a standalone tool:\n\n```shell\nclojure -T:rebel \n```\n\n## CLI Parameters\n\nYou can pass [Configurable Parameters](#config) when launching the REPL:\n\n```shell\nclojure -Xrebel :highlight false \n```\n\nIt's also possible to specify parameters in the `:exec-args` key of your `~/.clojure/deps.edn`.\n\n## CLI Usage with `rebel-readline.main`\n\nYou can also launch with the `rebel-readline.main` CLI. With the\nconfiguration above you can use:\n\n```shell\nclojure -Mrebel --no-highlight\n```\n\n```shell\nOptions:\n  -h, --help                                       Display help\n  -k, --key-map KEYMAP         :emacs              Choose between :viins or :emacs\n  -t, --color-theme THEME      :dark-screen-theme  :(light, dark, or neutral)-screen-theme\n      --no-highlight                               Disable syntax highlighting\n      --no-completion                              Disable code completion\n      --no-eldoc                                   Disable function documentation display\n      --no-indent                                  Disable auto indentation\n      --no-redirect-output                         Disable output redirection\n  -b, --key-bindings BINDINGS                      Specify custom key bindings\n  -c, --config CONFIG                              Path to a config file\n```\n\n## Installing with Leiningen\n\nAdd the dependency to your `project.clj`:\n\n```clojure\n[com.bhauman/rebel-readline \"0.1.5\"]\n```\n\nStart the REPL with:\n\n```shell\nlein trampoline run -m rebel-readline.main\n```\n\nYou can also add it to `$HOME/.lein/profiles.clj` so you don't have to\nadd it to individual projects.\n\nTo simplify REPL launches, create an alias in `project.clj`:\n\n```clojure\n:aliases {\"rebl\" [\"trampoline\" \"run\" \"-m\" \"rebel-readline.main\"]}\n```\n\nThis lets you start the REPL using `lein rebl`.\n\n## Boot Integration\n\nStart Rebel Readline using Boot with:\n\n```shell\nboot -d com.bhauman/rebel-readline call -f rebel-readline.main/-main\n```\n\n## Default to vi Bindings\n\nYou can set vi key bindings either in your `deps.edn` or in `~/.clojure/rebel_readline.edn`:\n\n```clojure\n{:key-map :viins}\n```\n\n## Configuration\n\nYou can provide various configurable options in your `deps.edn` or `~/.clojure/rebel_readline.edn`:\n\n```clojure\n:config          - path to an edn configuration file\n\n:key-map         - :viins or :emacs (default: :emacs)\n\n:color-theme     - (:light, :dark or :neutral)-screen-theme\n\n:highlight       - (boolean) enable syntax highlighting (default: true)\n\n:completion      - (boolean) enable code completion (default: true)\n\n:eldoc           - (boolean) enable function documentation display (default: true)\n\n:indent          - (boolean) enable auto indentation (default: true)\n\n:redirect-output - (boolean) rebinds output during read (default: true)\n\n:key-bindings    - map of key bindings to apply after others\n```\n\n### Key Binding Configuration\n\nTo configure key bindings, use your configuration file. Ensure correct\nserialization of key names.\n\n## Using Rebel Readline as a Readline Library\n\nRebel Readline can replace the `clojure.main/repl-read` behavior:\n\n```clojure\n(rebel-readline.core/with-line-reader\n  (rebel-readline.clojure.line-reader/create\n    (rebel-readline.clojure.service.local/create {:highlight false}))\n  (clojure.main/repl\n     :prompt (fn []) ;; prompt is handled by line-reader\n     :read (rebel-readline.clojure.main/create-repl-read)))\n```\n\nYou can also use `rebel-readline.core/with-readline-in` for easier wrapping:\n\n```clojure\n(rebel-readline.core/with-readline-in\n  (rebel-readline.clojure.line-reader/create\n    (rebel-readline.clojure.service.local/create))\n  (clojure.main/repl :prompt (fn [])))\n```\n\n## Services\n\nThe line reader provides capabilities like completion, documentation, and evaluation through a service. The common service is `rebel-readline.services.clojure.local`, which queries the local Clojure process.\n\nFor environments without a suitable service, you could use `clojure.service.local` or `clojure.service.simple`, though with less optimal results.\n\n## CLJS Support\n\nFor ClojureScript, visit [this repository section](https://github.com/bhauman/rebel-readline/tree/master/rebel-readline-cljs).\n\n## SocketREPL and pREPL Support\n\nCurrently, services for SocketREPL and pREPL are not available.\n\n## Contributing\n\nWe welcome contributions! Look for issues marked `help wanted` for good starting points. \n\nWhen contributing:\n\n- File an issue for non-trivial changes before creating a PR.\n- Consolidate PR changes into one commit.\n- Make changes small and easy to understand; this allows for better review.\n- Break larger solutions into manageable PRs.\n- Communicate if a PR represents more exploratory efforts.\n\nIf you need assistance on what to work on, feel free to reach out on the Clojurians Slack channel.\n\n## License\n\nCopyright © 2018 Bruce Hauman\n\nDistributed under the Eclipse Public License, version 1.0 or (at your option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhauman%2Frebel-readline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbhauman%2Frebel-readline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhauman%2Frebel-readline/lists"}