WARNING: UNDER ACTIVE INITIAL DEVELOPMENT!!
This is a pre-release. That is being made available for comment and behavior verification.
A terminal readline library for Clojure Dialects
https://github.com/bhauman/rebel-readline/blob/master/rebel-readline/doc/intro.md
The line reader will attempt to manipulate the terminal that initiates the JVM process. For this reason it is important to start your JVM in a terminal.
That means you should launch your Java process using the
- the java command
- the Clojure
clojure
tool (without readline support) - lein trampoline
- boot - would need to run in boot's worker pod
Launching the terminal readline process from another Java process will not work.
It's best to not launch this readline behind other readline tools like rlwrap
.
If you want to try this really quickly install the Clojure CLI tools and then invoke this:
clojure -Sdeps "{:deps {rebel-readline {:mvn/version \"0.1.1-SNAPSHOT\"}}}" -m rebel-readline.main
That should start a Clojure REPL that takes its input from the Rebel readline editor.
Note that I am using the clojure
command and not the clj
command
because the latter wraps the process with another readline program (rlwrap).
Clone this repo and then from the rebel-readline
sub-directory
typing lein trampoline run
will get you into a Clojure REPL with the
readline editor working.
Note that lein run
will not work! See above.
You should look at rebel-readline.clojure.main
and rebel-readline.core
to give you top level usage information.
The core of the functionality is in
rebel-readline.clojure.line-reader
everything else is just support.
The main way to utililize this readline editor is to replace the
clojure.main/repl-read
behavior in clojure.main/repl
.
The advantage of doing this is that it won't interfere with the input
stream if you are working on something that needs to read from
*in*
. This is because the line-reader will only be engaged when the
REPL loop is reading.
Example:
(rebel-readline.core/with-line-reader
(rebel-readline.clojure.core/create
(rebel-readline.clojure.service.local/create))
(clojure.main/repl
:prompt (fn []) ;; prompt is handled by line-reader
:read (rebel-readline.clojure.main/create-repl-read)))
Another option is to just wrap a call you your REPL with
rebel-readline.core/with-readline-input-stream
this will bind *in*
to an input-stream that is supplied by the line reader.
(rebel-readline.core/with-readline-in
(rebel-readline.clojure.core/create
(rebel-readline.clojure.service.local/create))
(clojure.main/repl :prompt (fn[])))
Or with a fallback:
(try
(rebel-readline.core/with-readline-in
(rebel-readline.clojure.core/create
(rebel-readline.clojure.service.local/create))
(clojure.main/repl :prompt (fn[])))
(catch clojure.lang.ExceptionInfo e
(if (-> e ex-data :type (= :rebel-readline.jline-api/bad-terminal))
(do (println (.getMessage e))
(clojure.main/repl))
(throw e))))
The line reader provides features like completion, documentation, source, apropos, eval and more. The line reader needs a Service to provide this functionality.
When you create a rebel-readline.clojure.core/line-reader
you need to supply this service.
The mose common service is the
rebel-readline.services.clojure.local
which uses the
local clojure process to provide this functionality and its a good
example of how a service works.
In general, it's much better if the service is querying the Clojure process where the eventual repl eval takes place.
However, the service doesn't necessarily have to query the same environment that the REPL is using for evaluation. All the editing functionality that rebel readline provides works without an environment to query. And the apropos, doc and completion functionality is still sensible when you provide those abilities from the local clojure process.
This could be helpful when you have a Clojurey repl process and you
don't have a Service for it. In this case you can just use a
clojure.service.local
or a clojure.service.simple
service. If you
do this you can expect less than optimal results but multiline
editing, syntax highlighting, auto indenting will all work just fine.
Bindings of interest
-
Ctrl-C => aborts editing the current line
-
Ctrl-D at the start of a line => sends an end of stream message which in most cases should quit the REPL
-
TAB => word completion or code indent if the cursor is in the whitespace at the start of a line
-
Ctrl-X_Ctrl-D => Show documentation for word at point
-
Ctrl-X_Ctrl-S => Show source for word at point
-
Ctrl-X_Ctrl-A => Show apropos for word at point
-
Ctrl-X_Ctrl-E => Inline eval for SEXP before the point
You can examine the keybindings with the :repl/key-bindings
command.
There is a command system. If the line starts with a "repl" namespaced keyword then the line-reader will attempt to interpret it as a command.
Type :repl/help
or :repl
TAB to see a list of available commands.
You can add new commands by adding methods to the
rebel-readline.commands/command
multimethod. You can add
documentation for the command by adding a method to the
rebel-readline.commands/command-doc
multimethod.
See https://github.com/bhauman/rebel-readline/tree/master/rebel-readline-cljs
Services have not been written for these REPLs yet!!
But you can use the rebel-readline.clojure.service.simple
service in the meantime.
Please contribute!
I'm trying to mark issues with help wanted
for issues that I feel
are good opportunities for folks to help out. If you want to work on
one of these please mention it in the issue.
If you do contribute:
- if the change isn't small please file an issue before a PR.
- please put all PR changes into one commit
- make small grokable changes. Large changes are more likely to be ingored and or used as a starting issue for exploration.
- break larger solutions down into a logical series of small PRs
- mention it at the start, if you are filing a PR that is more of an exploration of an idea
I'm going to be more open to repairing current behavior than I will be to increasing the scope of rebel-readline.
I will have a preference for creating hooks so that additional functionality can be layered on with libraries.
If you are wanting to contribute but don't know what to work on reach out to me on the clojurians slack channel.
Copyright © 2018 Bruce Hauman
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.