client

Usage: (client transport response-timeout)

Returns a fn of zero and one argument, both of which return the current head of a single
response-seq being read off of the given client-side transport.  The one-arg arity will
send a given message on the transport before returning the seq.

Most REPL interactions are best performed via `message` and `client-session` on top of
a client fn returned from this fn.

client-session

Usage: (client-session client & {:keys [session clone]})

Returns a function of one argument.  Accepts a message that is sent via the
client provided with a fixed :session id added to it.  Returns the
head of the client's response seq, filtered to include only
messages related to the :session id that will terminate when the session is
closed.

code

Usage: (code & body)

Expands into a string consisting of the macro's body's forms
(literally, no interpolation/quasiquoting of locals or other
references), suitable for use in an :eval message, e.g.:

{:op :eval, :code (code (+ 1 1) (slurp "foo.txt"))}

code*

Usage: (code* & expressions)

Returns a single string containing the pr-str'd representations
of the given expressions.

combine-responses

Usage: (combine-responses responses)

Combines the provided seq of response messages into a single response map.

Certain message slots are combined in special ways:

  - only the last :ns is retained
  - :value is accumulated into an ordered collection
  - :status and :session are accumulated into a set
  - string values (associated with e.g. :out and :err) are concatenated

connect

Usage: (connect & {:keys [port host transport-fn], :or {transport-fn bencode, host localhost}})

Connects to a socket-based REPL at the given host (defaults to localhost) and port,
returning the Transport (by default clojure.tools.nrepl.transport/bencode)
for that connection.

Transports are most easily used with `client`, `client-session`, and
`message`, depending on the semantics desired.

message

Usage: (message client {:keys [id], :as msg, :or {id (uuid)}})

Sends a message via [client] with a fixed message :id added to it.
Returns the head of the client's response seq, filtered to include only
messages related to the message :id that will terminate upon receipt of a
"done" :status.

new-session

Usage: (new-session client & {:keys [clone]})

Provokes the creation and retention of a new session, optionally as a clone
of an existing retained session, the id of which must be provided as a :clone
kwarg.  Returns the new session's id.

read-response-value

Usage: (read-response-value {:keys [value], :as msg})

Returns the provided response message, replacing its :value string with
the result of (read)ing it.  Returns the message unchanged if the :value
slot is empty or not a string.

response-seq

Usage: (response-seq transport)
       (response-seq transport timeout)

Returns a lazy seq of messages received via the given Transport.
Called with no further arguments, will block waiting for each message.
The seq will end only when the underlying Transport is closed (i.e.
returns nil from `recv`) or if a message takes longer than `timeout`
millis to arrive.

response-values

Usage: (response-values responses)

Given a seq of responses (as from response-seq or returned from any function returned
by client or client-session), returns a seq of values read from :value slots found
therein.

url-connect

No usage documentation available

Connects to an nREPL endpoint identified by the given URL/URI.  Valid
examples include:

   nrepl://192.168.0.12:7889
   telnet://localhost:5000
   http://your-app-name.heroku.com/repl

This is a multimethod that dispatches on the scheme of the URI provided
(which can be a string or java.net.URI).  By default, implementations for
nrepl (corresponding to using the default bencode transport) and
telnet (using the clojure.tools.nrepl.transport/tty transport) are
registered.  Alternative implementations may add support for other schemes,
such as HTTP, HTTPS, JMX, existing message queues, etc.

version

Current version of nREPL, map of :major, :minor, :incremental, and :qualifier.

wait-for-ack

Usage: (wait-for-ack timeout)

Waits for a presumably just-launched nREPL server to connect and
deliver its port number.  Returns that number if it's delivered
within `timeout` ms, otherwise nil.  Assumes that `ack`
middleware has been applied to the local nREPL server handler.

Expected usage:

(reset-ack-port!)
(start-server already-running-server-port)
=> (wait-for-ack)
59872 ; the port of the server started via start-server

read-bencode

Usage: (read-bencode input)

Read bencode token from the input stream.

read-netstring

Usage: (read-netstring input)

Reads a classic netstring from input—an InputStream. Returns the
contained binary data as byte array.

write-bencode

No usage documentation available

Write the given thing to the output stream. “Thing” means here a
string, map, sequence or integer. Alternatively an ByteArray may
be provided whose contents are written as a bytestring. Similar
the contents of a given InputStream are written as a byte string.
Named things (symbols or keywords) are written in the form
'namespace/name'.

write-netstring

Usage: (write-netstring output content)

Write the given binary data to the output stream in form of a classic
netstring.

load-file-command

Usage: (load-file-command f)
       (load-file-command f source-root)
       (load-file-command code file-path file-name)

(If it is available, sending clojure.tools.nrepl.middleware.load-file
 compatible messages is far preferable.)

Returns a string expression that can be sent to an nREPL session to
load the Clojure code in given local file in the remote REPL's environment,
preserving debug information (e.g. line numbers, etc).

Typical usage: (nrepl-client-fn
                 {:op "eval" :code
                   (load-file-command "/path/to/clojure/file.clj")})

If appropriate, the source path from which the code is being loaded may
be provided as well (suitably trimming the file's path to a relative one
when loaded).

The 3-arg variation of this function expects the full source of the file to be loaded,
the source-root-relative path of the source file, and the name of the file.  e.g.:

  (load-file-command "…code here…" "some/ns/name/file.clj" "file.clj")

set-descriptor!

Usage: (set-descriptor! middleware-var descriptor)

Sets the given [descriptor] map as the ::descriptor metadata on
the provided [middleware-var], after assoc'ing in the var's
fully-qualified name as the descriptor's "implemented-by" value.

*eval*

Function returning the evaluation of its argument.

*msg*

The message currently being evaluated.

evaluate

Usage: (evaluate bindings {:keys [code ns transport session eval file line column], :as msg})

Evaluates some code within the dynamic context defined by a map of `bindings`,
as per `clojure.core/get-thread-bindings`.

Uses `clojure.main/repl` to drive the evaluation of :code in a second
map argument (either a string or a seq of forms to be evaluated), which may
also optionally specify a :ns (resolved via `find-ns`).  The map MUST
contain a Transport implementation in :transport; expression results and errors
will be sent via that Transport.

Returns the dynamic scope that remains after evaluating all expressions
in :code.

It is assumed that `bindings` already contains useful/appropriate entries
for all vars indicated by `clojure.main/with-bindings`.

interruptible-eval

Usage: (interruptible-eval h & configuration)

Evaluation middleware that supports interrupts.  Returns a handler that supports
"eval" and "interrupt" :op-erations that delegates to the given handler
otherwise.

queue-eval

Usage: (queue-eval session executor f)

Queues the function for the given session.

load-file-code

Usage: (load-file-code file file-path file-name)

Given the contents of a file, its _source-path-relative_ path,
and its filename, returns a string of code containing a single
expression that, when evaluated, will load those contents with
appropriate filename references and line numbers in metadata, etc.

Note that because a single expression is produced, very large
file loads will fail due to the JVM method size limitation.
In such cases, see `load-large-file-code'`.

wrap-load-file

Usage: (wrap-load-file h)

Middleware that evaluates a file's contents, as per load-file,
but with all data supplied in the sent message (i.e. safe for use
with remote REPL environments).

This middleware depends on the availability of an :op "eval"
middleware below it (such as interruptible-eval).

pr-values

Usage: (pr-values h)

Middleware that returns a handler which transforms any :value slots
in messages sent via the request's Transport to strings via `pr`,
delegating all actual message handling to the provided handler.

Requires that results of eval operations are sent in messages in a
:value slot.

If :value is already a string, and a sent message's :printed-value
slot contains any truthy value, then :value will not be re-printed.
This allows evaluation contexts to produce printed results in :value
if they so choose, and opt out of the printing here.

response-for

Usage: (response-for {:keys [session id]} & response-data)

Returns a map containing the :session and :id from the "request" `msg`
as well as all entries specified in `response-data`, which can be one
or more maps (which will be merged), *or* key-value pairs.

(response-for msg :status :done :value "5")
(response-for msg {:status :interrupted})

The :session value in `msg` may be any Clojure reference type (to accommodate
likely implementations of sessions) that has an :id slot in its metadata,
or a string.

returning

Usage: (returning x & body)

Executes `body`, returning `x`.

uuid

Usage: (uuid)

Returns a new UUID string.

handle

Usage: (handle handler transport)

Handles requests received via [transport] using [handler].
Returns nil when [recv] returns nil for the given transport.

stop-server

Usage: (stop-server {:keys [open-transports server-socket], :as server})

Stops a server started via `start-server`.

unknown-op

Usage: (unknown-op {:keys [op transport], :as msg})

Sends an :unknown-op :error for the given message.

Transport

Defines the interface for a wire protocol implementation for use
with nREPL.

Usage: (recv this)
       (recv this timeout)

Reads and returns the next message received.  Will block.
Should return nil the a message is not available after `timeout`
ms or if the underlying channel has been closed.

Usage: (send this msg)

Sends msg. Implementations should return the transport.

FnTransport

QueueTransport

->FnTransport

Usage: (->FnTransport recv-fn send-fn close)

Positional factory function for class clojure.tools.nrepl.transport.FnTransport.

->QueueTransport

Usage: (->QueueTransport in out)

Positional factory function for class clojure.tools.nrepl.transport.QueueTransport.

bencode

Usage: (bencode s)
       (bencode in out & [s])

Returns a Transport implementation that serializes messages
over the given Socket or InputStream/OutputStream using bencode.

fn-transport

Usage: (fn-transport read write)
       (fn-transport read write close)

Returns a Transport implementation that delegates its functionality
to the 2 or 3 functions provided.

piped-transports

Usage: (piped-transports)

Returns a pair of Transports that read from and write to each other.

tty

Usage: (tty s)
       (tty in out & [s])

Returns a Transport implementation suitable for serving an nREPL backend
via simple in/out readers, as with a tty or telnet connection.

tty-greeting

Usage: (tty-greeting transport)

A greeting fn usable with clojure.tools.nrepl.server/start-server,
meant to be used in conjunction with Transports returned by the
`tty` function.

Usually, Clojure-aware client-side tooling would provide this upon connecting
to the server, but telnet et al. isn't that.