API for clojure.tools.nrepl - Network REPL 0.2.7 (in development)

by Chas Emerick

Full namespace name: clojure.tools.nrepl

Overview

High level nREPL client support.

Public Variables and Functions



client

function
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.
Source


client-session

function
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.
Source


code

macro
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"))}
Source


code*

function
Usage: (code* & expressions)
Returns a single string containing the pr-str'd representations
of the given expressions.
Source


combine-responses

function
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
Source


connect

function
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.
Source


message

function
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.
Source


new-session

function
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.
Source


read-response-value

function
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.
Source


response-seq

function
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.
Source


response-values

function
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.
Source


url-connect

multimethod
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.
Source


version

var

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

clojure.tools.nrepl.ack





Public Variables and Functions



wait-for-ack

function
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
Source

clojure.tools.nrepl.bencode

A netstring and bencode implementation for Clojure.

Public Variables and Functions



read-bencode

function
Usage: (read-bencode input)
Read bencode token from the input stream.
Source


read-netstring

function
Usage: (read-netstring input)
Reads a classic netstring from input—an InputStream. Returns the
contained binary data as byte array.
Source


write-bencode

multimethod
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'.
Source


write-netstring

function
Usage: (write-netstring output content)
Write the given binary data to the output stream in form of a classic
netstring.
Source

clojure.tools.nrepl.cmdline

A proof-of-concept command-line client for nREPL.  Please see
e.g. reply for a proper command-line nREPL client @
https://github.com/trptcolin/reply/


clojure.tools.nrepl.helpers





Public Variables and Functions



load-file-command

function
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")
Source

clojure.tools.nrepl.middleware





Public Variables and Functions



set-descriptor!

function
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.
Source

clojure.tools.nrepl.middleware.interruptible-eval





Public Variables and Functions



*eval*

dynamic var

    
Function returning the evaluation of its argument.
Source


*msg*

dynamic var

    
The message currently being evaluated.
Source


evaluate

function
Usage: (evaluate bindings {:keys [code ns transport session eval], :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`.
Source


interruptible-eval

function
Usage: (interruptible-eval h & {:keys [executor], :or {executor (configure-executor)}})
Evaluation middleware that supports interrupts.  Returns a handler that supports
"eval" and "interrupt" :op-erations that delegates to the given handler
otherwise.
Source

clojure.tools.nrepl.middleware.load-file





Public Variables and Functions



load-file-code

dynamic function
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'`.
Source


wrap-load-file

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

clojure.tools.nrepl.middleware.pr-values





Public Variables and Functions



pr-values

function
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.
Source

clojure.tools.nrepl.middleware.session

Support for persistent, cross-connection REPL sessions.

Public Variables and Functions



add-stdin

function
Usage: (add-stdin h)
stdin middleware.  Returns a handler that supports a "stdin" :op-eration, which
adds content provided in a :stdin slot to the session's *in* Reader.  Delegates to
the given handler for other operations.

Requires the session middleware.
Source


session

function
Usage: (session h)
Session middleware.  Returns a handler which supports these :op-erations:

* "ls-sessions", which results in a response message
  containing a list of the IDs of the currently-retained sessions in a
  :session slot.
* "close", which drops the session indicated by the
  ID in the :session slot.  The response message's :status will include
  :session-closed.
* "clone", which will cause a new session to be retained.  The ID of this
  new session will be returned in a response message in a :new-session
  slot.  The new session's state (dynamic scope, etc) will be a copy of
  the state of the session identified in the :session slot of the request.

Messages indicating other operations are delegated to the given handler,
with the session identified by the :session ID added to the message. If
no :session ID is found, a new session is created (which will only
persist for the duration of the handling of the given message).

Requires the interruptible-eval middleware (specifically, its binding of
*msg* to the currently-evaluated message so that session-specific *out*
and *err* content can be associated with the originating message).
Source

clojure.tools.nrepl.misc

Misc utilities used in nREPL's implementation (potentially also useful
for anyone extending it).

Public Variables and Functions



response-for

function
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.
Source


returning

macro
Usage: (returning x & body)
Executes `body`, returning `x`.
Source


uuid

function
Usage: (uuid)
Returns a new UUID string.
Source

clojure.tools.nrepl.server

Default server implementations

Types



Server

record

    Fields: [server-socket port open-transports transport greeting handler]
Protocols:
Interfaces: clojure.lang.IDeref, clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Closeable, java.io.Serializable, java.util.Map

Public Variables and Functions



->Server

function
Usage: (->Server server-socket port open-transports transport greeting handler)
Positional factory function for class clojure.tools.nrepl.server.Server.
Source


default-handler

function
Usage: (default-handler & additional-middlewares)
A default handler supporting interruptible evaluation, stdin, sessions, and
readable representations of evaluated expressions via `pr`.

Additional middlewares to mix into the default stack may be provided; these
should all be values (usually vars) that have an nREPL middleware descriptor
in their metadata (see clojure.tools.nrepl.middleware/set-descriptor!).
Source


handle

function
Usage: (handle handler transport)
Handles requests received via [transport] using [handler].
Returns nil when [recv] returns nil for the given transport.
Source


map->Server

function
Usage: (map->Server m#)
Factory function for class clojure.tools.nrepl.server.Server, taking a map of keywords to field values.
Source


start-server

function
Usage: (start-server & {:keys [port bind transport-fn handler ack-port greeting-fn], :or {port 0}})
Starts a socket-based nREPL server.  Configuration options include:

  * :port — defaults to 0, which autoselects an open port on localhost
  * :bind — bind address, by default any (0.0.0.0)
  * :handler — the nREPL message handler to use for each incoming connection;
      defaults to the result of `(default-handler)`
  * :transport-fn — a function that, given a java.net.Socket corresponding
      to an incoming connection, will return an value satisfying the
      clojure.tools.nrepl.Transport protocol for that Socket.
  * :ack-port — if specified, the port of an already-running server
      that will be connected to to inform of the new server's port.
      Useful only by Clojure tooling implementations.

  Returns a (map) handle to the server that is started, which may be stopped
  either via `stop-server`, (.close server), or automatically via `with-open`.
  The port that the server is open on is available in the :port slot of the
  server map (useful if the :port option is 0 or was left unspecified.
Source


stop-server

function
Usage: (stop-server {:keys [open-transports server-socket], :as server})
Stops a server started via `start-server`.
Source


unknown-op

function
Usage: (unknown-op {:keys [op transport], :as msg})
Sends an :unknown-op :error for the given message.
Source

clojure.tools.nrepl.transport





Protocols



Transport

Protocol
Defines the interface for a wire protocol implementation for use
with nREPL.
Known implementations: FnTransport, QueueTransport

recv

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

send

function
Usage: (send this msg)
Sends msg. Implementations should return the transport.
Source

Types



FnTransport

type

    Fields: [recv-fn send-fn close]
Protocols: Transport
Interfaces: java.io.Closeable


QueueTransport

type

    Fields: [in out]
Protocols: Transport
Interfaces:

Public Variables and Functions



->FnTransport

function
Usage: (->FnTransport recv-fn send-fn close)
Positional factory function for class clojure.tools.nrepl.transport.FnTransport.
Source


->QueueTransport

function
Usage: (->QueueTransport in out)
Positional factory function for class clojure.tools.nrepl.transport.QueueTransport.
Source


bencode

function
Usage: (bencode s)
       (bencode in out & [s])
Returns a Transport implementation that serializes messages
over the given Socket or InputStream/OutputStream using bencode.
Source


fn-transport

function
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.
Source


piped-transports

function
Usage: (piped-transports)
Returns a pair of Transports that read from and write to each other.
Source


tty

function
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.
Source


tty-greeting

function
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.
Source
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.