clojure-tools.nrepl

nREPL is a message-oriented, asynchronous protocol built on three primary abstractions: Handlers, Middleware, and Transports.

• Handlers: Functions that process incoming messages. An nREPL server runs a single handler for its lifetime. Handlers do not return values; instead, they use the provided :transport to send one or more response messages back to the client.
• Middleware: Higher-order functions that wrap handlers to add functionality (e.g., session management, evaluation, or custom operations). They follow patterns similar to Ring middleware.
• Transports: Implementations of the clojure.tools.nrepl.transport.Transport protocol that handle the encoding and transmission of messages over a channel (e.g., sockets).

You can host an nREPL server directly within your application to enable remote debugging and code patching. Use clojure.tools.nrepl.server to manage the server lifecycle.

1. Add org.clojure/tools.nrepl to your dependencies.
2. Use start-server to create the server instance.
3. Use stop-server to shut it down.

(use '[clojure.tools.nrepl.server :only (start-server stop-server)])

;; Start the server on port 7888
(defonce server (start-server :port 7888))

;; To stop the server later:
(stop-server server)

If you need to build nREPL manually using Maven:

1. Clone the repository.
2. Ensure Maven is installed.
3. Run one of the following commands:
   • mvn package: Produces an nREPL jar in the target directory and runs tests against Clojure 1.2.0.
   • mvn verify: Runs tests against all supported Clojure versions/profiles.

# To produce a jar and run basic tests
mvn package

# To run tests against all supported Clojure profiles
mvn verify

nREPL is available in Maven Central. You can add it to your project using Leiningen or Maven.

Compatibility: nREPL is compatible with Clojure 1.2.0 and higher.

### Leiningen (`project.clj`)
```clojure
[org.clojure/tools.nrepl "0.2.13"]

Maven (pom.xml)

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>tools.nrepl</artifactId>
  <version>0.2.13</version>
</dependency>

By default, repl/response-values returns only the evaluated results. To see the full content of message responses (including :out, :session, and :id), use repl/message and ensure you consume the lazy sequence (e.g., using doall) before printing.

(with-open [conn (repl/connect :port 59258)]
  (-> (repl/client conn 1000)
    (repl/message {:op :eval :code "(time (reduce + (range 1e6)))"})
    doall      ;; `message` and `client-session` all return lazy seqs
    pprint))

Attempts to interrupt a running code evaluation in a specific session. To target a specific evaluation, provide the :interrupt-id that matches the :id sent in the original :eval request.

;; Required parameters:
;; :session The ID of the session used to start the evaluation.

;; Optional parameters:
;; :interrupt-id The opaque message ID sent with the original "eval" request.

;; Returns:
;; :status 'interrupted' (interruption attempted)
;; :status 'session-idle' (no code currently evaluating)
;; :status 'interrupt-id-mismatch' (evaluating code with a different ID)

Closes the specified nREPL session.

;; Required parameters:
;; :session The ID of the session to be closed.

Adds the provided content to the *in* value in the current session. This is used when a session's *in* requires input to satisfy a read operation.

;; Required parameters:
;; :stdin Content to add to *in*.

;; Returns:
;; :status "need-input" if the session requires more content to satisfy a read.

Returns a list of all currently active session IDs available on the nREPL endpoint.

;; Returns:
;; :sessions A list of all available session IDs.

Produces a machine- and human-readable directory and documentation for the operations supported by the current nREPL endpoint. This is useful for inspecting the capabilities of a server and its middleware.

;; Optional parameters:
;; :verbose? Include informational detail for each operation in the return message.

;; Returns:
;; :aux Map of auxiliary data from active middleware via :describe-fn.
;; :ops Map of operations supported by this endpoint.
;; :versions Map containing version information (e.g., "nrepl", "clojure").

Loads the full contents of a file and evaluates it. This operation sets source file and line number metadata by delegating to the underlying evaluation middleware.

;; Required parameters:
;; :file Full contents of the file to be loaded.

;; Optional parameters:
;; :file-name Name of the source file (e.g., io.clj).
;; :file-path Source-path-relative path (e.g., clojure/java/io.clj).

;; Returns:
;; :ex The type of exception thrown (if any).
;; :ns The *ns* after successful evaluation.
;; :root-ex The type of the root exception thrown (if any).
;; :values The result of evaluating the code.