rebel-readline.core — razum2um/rebel-readline 0.1.5

basic-line-reader clj

(basic-line-reader & opts)

create-buffered-repl-reader-fn clj

(create-buffered-repl-reader-fn create-buffered-reader-fn
                                has-remaining-pred
                                repl-read-fn)

ensure-terminal clj macro

(ensure-terminal & body)

Bind the rebel-readline.jline-api/terminal var to a new Jline terminal if needed, otherwise use the currently bound one.

Will throw a clojure.lang.ExceptionInfo with a data payload of {:type :rebel-readline.jline-api/bad-terminal} if JVM wasn't launched from a terminal process.

There should really only be one instance of a Jline terminal as it represents a "connection" to the terminal that launched JVM process.

---

IMPORTANT NOTE:

This function will attempt to manipulate the terminal that initiated the JVM process. For this reason it is important to start your JVM in a terminal.

That means launching your process using the

• the java command
• the Clojure clojure tool
• lein trampoline
• boot - would need to run in boot's worker pod

Launching from a process initiated by lein will not work and launching from a boot pod will not cut it either.

The underlying Terminal manipulation code is Jline3 and it makes every effort to be compatible with a wide array of terminals. It is entirely possible that your terminal is not well supported.

has-remaining? clj

(has-remaining? pbr)

Takes a PushbackReader and returns true if the next character is not negative. i.e not the end of the readers stream.

help-message clj

(help-message)

Returns a help message to print before enguaging the readline. Helpful for repl development.

read-line clj

(read-line & [command-executed])

Reads a line from the currently bound rebel-readline.jline-api/line-reader. If you supply the optional command-executed sentinal value, it will be returned when a repl command is executed, otherwise a blank string will be returned when a repl command is executed.

This function activates the rebel line reader which, in turn, will put the terminal that launched the jvm process into "raw mode" during the readline operation.

You can think of the readline operation as a launching of an editor for the brief period that the line is read.

If readline service value of :redirect-output is truthy (the default value) in the supplied rebel line reader service config this function will alter the root binding of the out var to prevent extraneous output from corrupting the read line editors output.

Once the reading is done it returns the terminal to its original settings.

read-line-opts clj

(read-line-opts &
                {prompt :prompt
                 mask :mask
                 buffer :buffer
                 command-executed :command-executed
                 :or {prompt nil buffer nil mask nil command-executed ""}})

Like read-line, but allows overriding of the LineReader prompt, buffer, and mask parameters.

:prompt Allows overriding with a cusom prompt :buffer The default value presented to the user to edit, may be null. :mask Should be set to a single character used by jline to bit-mask.
Characters will not be echoed if they mask to 0 Might do crazy stuff with rebel-readline, use with caution. defaults to nil (no mask) :command-executed sentinal value to be returned when a repl command is executed, otherwise a blank string will be returned when a repl command is executed.

repl-read-line clj

(repl-read-line request-prompt request-exit)

A readline function that converts the Exceptions normally thrown by org.jline.reader.impl.LineReaderImpl that signal user interrupt or the end of the parent stream into concrete sentinal objects that one can act on.

This follows the pattern established by clojure.main/repl-read

This function either returns the string read by this readline or the request-exit or request-prompt sentinal objects.

stream-read-line clj

(stream-read-line)

This function reads lines and returns them ready to be read by a java.io.Reader. This basically adds newlines at the end of readline results.

This function returns nil if it is end of the supplied readlines parent input stream or if a process exit is requested.

This function was designed to be supplied to a rebel-readline.io.calback-reader

Example:

;; this will create an input stream to be read from by a Clojure/Script REPL

(rebel-readline.io.calback-reader/callback-reader #(stream-read-line))

with-line-reader clj macro

(with-line-reader line-reader & body)

This macro take a line-reader and binds it. It is one of the primary ways to utilize this library. You can think of the rebel-readline.jline-api/line-reader binding as an alternative in source that the rebel-readline.core/read-line function reads from.

Example: (require '[rebel-readline.core :as rebel])

(rebel/with-line-reader (rebel-readline.clojure.line-reader/create (rebel-readline.clojure.service.local/create)) ;; optionally bind the output directly to the jline terminal ;; in such a way so that output won't corrupt the terminal ;; this is optional (binding [out (rebel-readline.jline-api/safe-terminal-writer)] (clojure.main/repl ;; this will create a fn that reads from the line-reader :read (rebel-readline.clojure.main/create-repl-read) :prompt (fn []))))

with-readline-in clj macro

(with-readline-in line-reader & body)

This macro takes a rebel readline service and binds in to an a clojure.lang.LineNumberingPushbackReader that is backed by the readline.

This is perhaps the easiest way to utilize this readline library.

The downside to using this method is if you are working in a REPL on something that reads from the in that wouldn't benefit from the features of this readline lib. In that case I would look at clj-repl-read where the readline is only engaged during the read portion of the REPL.

Examples:

(with-readline-in (rebel-readline.clojure.line-reader/create (rebel-readline.clojure.service.local/create {:prompt clojure.main/repl-prompt} )) (clojure.main/repl :prompt (fn[])))