### Start nREPL Server in Clojure

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Demonstrates how to start an nREPL socket-based server within a Clojure application. This allows for remote debugging and interaction with the running application. Requires the `clojure.tools.nrepl.server` namespace.

```Clojure
(use '[clojure.tools.nrepl.server :only (start-server stop-server)])
(defonce server (start-server :port 7888))
```

--------------------------------

### Connect to nREPL Server from Clojure

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Shows how to connect to a running nREPL server from another Clojure process and execute code remotely. This example uses the `clojure.tools.nrepl.repl` namespace to establish a connection and send messages.

```Clojure
(with-open [conn (repl/connect :port 7888)]
     (-> (repl/client conn 1000)
       (repl/message {:op :eval :code "(+ 1 1)"})
       repl/response-values))
```

--------------------------------

### Connect to nREPL Server Programmatically (Clojure)

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Connect to an nREPL server programmatically using the clojure.tools.nrepl library. This example demonstrates establishing a connection, sending an evaluation message, and retrieving only the values from the response.

```clojure
(require '[clojure.tools.nrepl :as repl])

(with-open [conn (repl/connect :port 59258)]
  (-> (repl/client conn 1000)    ; message receive timeout required
    (repl/message {:op "eval" :code "(+ 2 3)"})
    repl/response-values))
```

--------------------------------

### Clojure nREPL Middleware Example

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Demonstrates a Clojure middleware function for nREPL that handles a hypothetical 'time?' :op by replying with the server's current time. It composes functionality onto an existing handler, requiring transport and misc utilities.

```clojure
(require '[clojure.tools.nrepl.transport :as t])
(use '[clojure.tools.nrepl.misc :only (response-for)])

(defn current-time
  [h]
  (fn [{:keys [op transport] :as msg}]
    (if (= "time?" op)
      (t/send transport (response-for msg :status :done :time (System/currentTimeMillis)))
      (h msg))))
```

--------------------------------

### nREPL Evaluation Message Example

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

An example of a message sent to an nREPL endpoint to evaluate code. It includes the 'op' key specifying the operation ('eval') and the 'code' key containing the Clojure code to be executed.

```clojure
{"op" "eval" "code" "(+ 1 2 3)"}
```

--------------------------------

### Install nREPL with Leiningen

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Add the nREPL dependency to your Leiningen project.clj file to include it in your Clojure project. This allows you to use nREPL's features within your development workflow.

```clojure
[:dependencies]
[org.clojure/tools.nrepl "0.2.13"]
```

--------------------------------

### View Full nREPL Server Response (Clojure)

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Connect to an nREPL server and retrieve the complete response, including status, output, and evaluated values. This example shows how to process the full message structure returned by the nREPL client.

```clojure
(require '[clojure.tools.nrepl :as repl])

(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))
```

--------------------------------

### Install nREPL with Maven

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Add the nREPL dependency to your Maven project's pom.xml file. This ensures that nREPL is available for use in your Java or Clojure projects managed by Maven.

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

--------------------------------

### Build nREPL with Maven

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Instructions for building the nREPL project using Apache Maven. This process compiles the code, runs tests against different Clojure versions, and produces a JAR file in the target directory.

```bash
mvn package
# or
mvn verify
```

--------------------------------

### Basic IDE Interaction with nREPL

Source: https://github.com/clojure/tools.nrepl/wiki/Nrepl.next:-Use-Cases

This snippet demonstrates a simple, one-shot message exchange for IDE features like code completion or docstrings. The server evaluates the code in a temporary, transient session that is discarded immediately after evaluation.

```clojure
Client sends message:
{:message-id "uuid-string-123" :code "(do-something)"}

Server evaluates code in a fresh transient session.

Server sends response:
{:message-id "uuid-string-123" :value "[:done :something]"}

Server sends response:
{:message-id "uuid-string-123" :status "evaluation finished"}

Server discards transient session.
```

--------------------------------

### Describe nREPL Operations

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Generates a machine- and human-readable directory and documentation for the operations supported by an nREPL endpoint. It can optionally include verbose details.

```APIDOC
:describe
  Produce a machine- and human-readable directory and documentation for the operations supported by an nREPL endpoint.

  Required parameters:
    None

  Optional parameters:
    * :verbose? (boolean): Include informational detail for each "op"eration in the return message.

  Returns:
    * :aux (map): Map of auxilliary data contributed by all of the active nREPL middleware via :describe-fn functions in their descriptors.
    * :ops (map): Map of "op"erations supported by this nREPL endpoint.
    * :versions (map): Map containing version maps (like *clojure-version*, e.g. major, minor, incremental, and qualifier keys) for values, component names as keys. Common keys include "nrepl" and "clojure".
```

--------------------------------

### Setting Middleware Descriptor

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Demonstrates how to use `set-descriptor!` to attach a descriptor map to a middleware var. This descriptor specifies dependencies (`:requires`, `:expects`) and documented operations (`:handles`) for the middleware.

```clojure
(set-descriptor! #'add-stdin
  {:requires #{#'session}
   :expects #{"eval"}
   :handles {"stdin"
             {:doc "Add content from the value of \"stdin\" to *in* in the current session."
              :requires {"stdin" "Content to add to *in*."}
              :optional {}
              :returns {"status" "A status of \"need-input\" will be sent if a session's *in* requires content in order to satisfy an attempted read operation."}}})
```

--------------------------------

### Clone nREPL Session

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Clones the current nREPL session, creating a new session with potentially default bindings. It returns the ID of the newly-created session.

```APIDOC
:clone
  Clones the current session, returning the ID of the newly-created session.

  Required parameters:
    None

  Optional parameters:
    * :session (string): The ID of the session to be cloned; if not provided, a new session with default bindings is created, and mapped to the returned session ID.

  Returns:
    * :new-session (string): The ID of the new session.
```

--------------------------------

### Load File in nREPL Session

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Loads a body of code from a file into an nREPL session, setting source file and line number metadata. It delegates to the underlying "eval" middleware.

```APIDOC
:load-file
  Loads a body of code, using supplied path and filename info to set source file and line number metadata. Delegates to underlying "eval" middleware/handler.

  Required parameters:
    * :file (string): Full contents of a file of code.

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

  Returns:
    * :ex (string): The type of exception thrown, if any. If present, then `values` will be absent.
    * :ns (*ns): *ns*, after successful evaluation of `code`.
    * :root-ex (string): The type of the root exception thrown, if any. If present, then `values` will be absent.
    * :values (any): The result of evaluating `code`, often `read`able. This printing is provided by the `pr-values` middleware, and could theoretically be customized. Superseded by `ex` and `root-ex` if an exception occurs during evaluation.
```

--------------------------------

### List nREPL Sessions

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Lists the IDs of all currently active nREPL sessions. This operation requires no parameters.

```APIDOC
:ls-sessions
  Lists the IDs of all active sessions.

  Required parameters:
    None

  Optional parameters:
    None

  Returns:
    * :sessions (list of strings): A list of all available session IDs.
```

--------------------------------

### Persistent Session Management in nREPL

Source: https://github.com/clojure/tools.nrepl/wiki/Nrepl.next:-Use-Cases

This snippet illustrates how to establish and manage persistent sessions for interactive REPL use. A session ID is generated and retained by the server, allowing subsequent messages to be evaluated within the same context.

```clojure
Client sends message to retain session:
{:message-id "uuid-string-123" :code "(clojure.tools.nrepl/retain-session!)"}

Server creates a transient session, registers a persistent session, and returns a session ID.

Server sends response:
{:message-id "uuid-string-123" :value "uuid-string-abc"}

Server sends response:
{:message-id "uuid-string-123" :status "evaluation finished"}

Client sends message using session ID:
{:message-id "uuid-string-124" :session-id "uuid-string-abc" :code "(+ 1 2)"}

Server evaluates code in the referenced persistent session.

Client sends message to release session:
{:message-id "uuid-string-256" :code "(clojure.tools.nrepl/release-session! \"uuid-string-abc\")"}

Server evaluates code to release the session and discards the transient session.
```

--------------------------------

### Evaluate Code in nREPL Session

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Evaluates Clojure code within a specified nREPL session. It supports providing context like file path, line/column numbers, and custom evaluation functions.

```APIDOC
:eval
  Evaluates code.

  Required parameters:
    * :code (string): The code to be evaluated.
    * :session (string): The ID of the session within which to evaluate the code.

  Optional parameters:
    * :column (integer): The column number in [file] at which [code] starts.
    * :eval (symbol): A fully-qualified symbol naming a var whose function value will be used to evaluate [code], instead of `clojure.core/eval` (the default).
    * :file (string): The path to the file containing [code]. `clojure.core/*file*` will be bound to this.
    * :id (string): An opaque message ID that will be included in responses related to the evaluation, and which may be used to restrict the scope of a later "interrupt" operation.
    * :line (integer): The line number in [file] at which [code] starts.

  Returns:
    * :ex (string): The type of exception thrown, if any. If present, then `values` will be absent.
    * :ns (*ns): *ns*, after successful evaluation of `code`.
    * :root-ex (string): The type of the root exception thrown, if any. If present, then `values` will be absent.
    * :values (any): The result of evaluating `code`, often `read`able. This printing is provided by the `pr-values` middleware, and could theoretically be customized. Superseded by `ex` and `root-ex` if an exception occurs during evaluation.
```

--------------------------------

### Send Stdin to nREPL Session

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Adds content from the "stdin" parameter to the standard input stream (*in*) of the current nREPL session. This is useful for interactive operations.

```APIDOC
:stdin
  Add content from the value of "stdin" to *in* in the current session.

  Required parameters:
    * :stdin (string): Content to add to *in*.

  Optional parameters:
    None

  Returns:
    * :status (string): A status of "need-input" will be sent if a session's *in* requires content in order to satisfy an attempted read operation.
```

--------------------------------

### nREPL Server Response Structure and Status Codes

Source: https://github.com/clojure/tools.nrepl/blob/master/README.md

Details the structure of messages sent by the nREPL server in response to client requests. It covers the common slots like 'id', 'ns', 'out', 'err', 'value', and 'status', explaining their purpose and conditions for presence. It also elaborates on the different 'status' codes ('error', 'timeout', 'interrupted', 'server-failure', 'done') and their implications.

```APIDOC
Server Responses:

The nREPL server sends multiple messages in response to each client request. Each message can contain the following slots:

- `id`: The ID of the request for which the response was generated. Always defined.
- `ns`: The stringified value of `*ns*` at the time of the response message's generation. Always defined.
- `out`: Contains content written to `*out*` during evaluation. Sent at the discretion of the server, typically corresponding with flushes.
- `err`: Same as `out`, but for `*err*`. Sent when new content is written to `*err*`.
- `value`: The result of printing an evaluated form. Can be printed with `prn` or a pretty-printer if conditions are met (Clojure >= 1.2.0 or Clojure Contrib, and `clojure.tools.nrepl/*pretty-print*` is true). Sent when new data is available.
- `status`: Indicates the processing status of the request. Conditional.

Status Codes:

- `error`: An error occurred during evaluation. The exception is bound to `*e` and printed to `*err*`. Stack trace printing is controlled by `clojure.tools.nrepl/*print-stack-trace-on-error*`.
- `timeout`: The code evaluation exceeded the specified timeout.
- `interrupted`: The evaluation was interrupted by a client message invoking `clojure.tools.nrepl/interrupt`.
- `server-failure`: An unrecoverable error occurred within the server itself, indicating a potential bug or fatal system fault.
- `done`: The request has been completely processed. This does not imply success, only that no timeout or interrupt condition was met.

Note: Evaluations that timeout or are interrupted may still result in multiple response messages being sent before the final status message.

Timeouts and Interrupts:

- Each message has an associated timeout that limits execution time before interruption and a `timeout` status response.
- Interruptions can be initiated by a client sending a message that invokes `clojure.tools.nrepl/interrupt` with the target message ID.
- Interrupts are performed on a "best-effort" basis, subject to Java's threading model limitations.
```

--------------------------------

### Close nREPL Session

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Closes a specified nREPL session. This operation requires the session ID to identify which session to terminate.

```APIDOC
:close
  Closes the specified session.

  Required parameters:
    * :session (string): The ID of the session to be closed.

  Optional parameters:
    None

  Returns:
    None
```

--------------------------------

### Interrupt nREPL Evaluation

Source: https://github.com/clojure/tools.nrepl/blob/master/doc/ops.md

Attempts to interrupt code evaluation in an nREPL session. It requires the session ID and optionally an interrupt ID to target a specific evaluation.

```APIDOC
:interrupt
  Attempts to interrupt some code evaluation.

  Required parameters:
    * :session (string): The ID of the session used to start the evaluation to be interrupted.

  Optional parameters:
    * :interrupt-id (string): The opaque message ID sent with the original "eval" request.

  Returns:
    * :status (string): 'interrupted' if an evaluation was identified and interruption will be attempted; 'session-idle' if the session is not currently evaluating any code; 'interrupt-id-mismatch' if the session is currently evaluating code sent using a different ID than specified by the "interrupt-id" value.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.