= REPL Configuration
:experimental:

== Behavior on connect

Normally, when you first establish a REPL connection, the REPL buffer is
auto-displayed in a separate window. You can suppress this behavior
like this:

[source,lisp]
----
(setq cider-repl-pop-to-buffer-on-connect nil)
----

If you want the REPL buffer to be auto-displayed, but don't want it to be
focused, use this:

[source,lisp]
----
(setq cider-repl-pop-to-buffer-on-connect 'display-only)
----

== Behavior on switch

By default kbd:[C-c C-z] will display the REPL buffer in a
different window.  You can make kbd:[C-c C-z] switch to the CIDER
REPL buffer in the current window:

[source,lisp]
----
(setq cider-repl-display-in-current-window t)
----

== Customizing the REPL prompt

You can customize the REPL buffer prompt by setting
`cider-repl-prompt-function` to a function that takes one
argument, a namespace name. For convenience, CIDER provides three
functions that implement common formats:

* `cider-repl-prompt-lastname`:

----
ssl>
----

* `cider-repl-prompt-abbreviated`:

----
l.c.ssl>
----

* `cider-repl-prompt-default`:

----
leiningen.core.ssl>
----

By default, CIDER uses `cider-repl-prompt-default`.

You may, of course, write your own function. For example, in `leiningen` there
are two namespaces with similar names - `leiningen.classpath` and
`leiningen.core.classpath`. To make them easily recognizable you can either
use the default value or you can opt to show only two segments of the
namespace and still be able to know which is the REPL's current
namespace. Here is an example function that will do exactly that:

[source,lisp]
----
(defun cider-repl-prompt-show-two (namespace)
  "Return a prompt string with the last 2 segments of NAMESPACE."
  (let ((names (reverse (subseq (reverse (split-string namespace "\\.")) 0 2))))
    (concat (car names) "." (cadr names) "> ")))
----

== TAB Completion

You can control the kbd:[TAB] key behavior in the REPL using the
`cider-repl-tab-command` variable.  While the default command
`cider-repl-indent-and-complete-symbol` should be an adequate choice for
most users, it's very easy to switch to another command if you wish
to. For instance if you'd like kbd:[TAB] to only indent (maybe
because you're used to completing with kbd:[M-TAB]) use the
following:

[source,lisp]
----
(setq cider-repl-tab-command #'indent-for-tab-command)
----

== Customizing the `Return` key's behavior

Ordinarily, kbd:[Return] immediately sends a form for
evaluation. If you want to insert a newline into the REPL buffer as
you're editing, you can do so using kbd:[C-j]. If you are
entering a lot of longer forms that span multiple lines, it may be
more convenient to change the keybindings:

[source,lisp]
----
(define-key cider-repl-mode-map (kbd "RET") #'cider-repl-newline-and-indent)
(define-key cider-repl-mode-map (kbd "C-<return>") #'cider-repl-return)
----

This will make kbd:[Return] insert a newline into the REPL buffer
and kbd:[C-Return] send the form off for evaluation.

== Auto-scrolling the REPL on Output

Prior to version 0.21.0, the REPL buffer would be automatically re-centered
whenever any output was printed, so that the prompt was on the bottom line of
the window, displaying the maximum possible amount of output above it. This is
no longer the default behavior -- you can now replicate it by setting the
built-in option `scroll-conservatively`, for example:

[source,lisp]
----
(add-hook 'cider-repl-mode-hook '(lambda () (setq scroll-conservatively 101)))
----

== Display Output Preceding the REPL Window Boundaries

If your REPL prompt is at the beginning of the REPL window (e.g. you pressed
`C-l` a couple of times to recenter your REPL window) and some output is
displayed there from an interactive evaluation in a Clojure buffer, this output
won't automatically be scrolled into view. If you want to force such output to
be displayed you'll need to add the following to your config:

[source,lisp]
----
(setq cider-repl-display-output-before-window-boundaries t)
----

NOTE: This behavior was changed in CIDER 1.7, as the auto-scrolling of output
before the REPL prompt is rarely needed, but its current implementation is very
slow.

== Auto-trimming the REPL buffer

NOTE: This functionality is disabled by default.

As noted xref:repl/basic_usage.adoc#known-limitations[previously], the REPL buffer's performance will degrade if its size
is allowed to grow infinitely. You can obviously clear the REPL manually from time to
time, but CIDER also has some auto-trimming functionality that can simplify
the process for you.

Auto-trimming can be enabled by setting `cider-repl-buffer-size-limit` to an integer. By
setting a limit to the number of characters in the buffer, the buffer can be
trimmed (from its beginning) after each evaluation if the set limit has been
exceeded. Here's how you can set the size limit in your Emacs config:

[source,lisp]
----
(setq cider-repl-buffer-size-limit 100000)
----

TIP: You can also trigger auto-trimming manually by invoking the command `cider-repl-trim-buffer`
or the REPL shortcut `trim`.

== Result Prefix

You can change the string used to prefix REPL results:

[source,lisp]
----
(setq cider-repl-result-prefix ";; => ")
----

Which then results in the following REPL output:

----
user> (+ 1 2)
;; => 3
----

By default, REPL results have no prefix.

== Set ns in REPL

By default `cider-repl-set-ns` won't require the target ns, just set
it. That's done with the assumption that you've probably evaluated the ns in
question already before switching to it (e.g. by doing kbd:[C-c C-k]
(`cider-load-buffer`) in its source buffer). If you want to change this behavior
(to avoid calling `cider-repl-set-ns` and then `(require 'my-ns)` manually), you
can set:

[source,lisp]
----
(setq cider-repl-require-ns-on-set t)
----

== Customizing the initial REPL namespace

Normally, the CIDER REPL will start in the `user` namespace.  You can
supply an initial namespace for REPL sessions in the `repl-options`
section of your Leiningen project configuration:

[source,clojure]
----
:repl-options {:init-ns 'my-ns}
----

== Customize the REPL Buffer's Name

You can customize the buffer name using the variable
`cider-session-name-template`. See the documentation for this variable for
details.

== Font-locking

Normally, code in the REPL is font-locked the same way as in
`clojure-mode`. Before CIDER 0.10, by default, REPL input was
font-locked with `cider-repl-input-face` (after pressing
kbd:[Return]) and results were font-locked with
`cider-repl-result-face`. If you want to restore the old behavior
use:

[source,lisp]
----
(setq cider-repl-use-clojure-font-lock nil)
----

You can temporarily disable the Clojure font-locking by using
kbd:[M-x cider-repl-toggle-clojure-font-lock]
or the REPL shortcut `toggle-font-lock`.

Keep in mind that by default `cider-repl-input-face` simply makes the input bold
and `cider-repl-result-face` is blank (meaning it doesn't really apply any
font-locking to results), so you might want to adjust those faces to your
preferences. Some Emacs color themes might be providing different defaults for
them.

NOTE: Using Clojure font-locking in the REPL can impact performance negatively, especially
when it comes to font-locking huge results. That, however, is mitigated to a big extent
by result streaming.

=== Font-locking of Results

There are a few things you need to keep in mind about Clojure font-locking of results:

* When streaming is enabled only single-chunk results will be font-locked as Clojure, as
each chunk is font-locked by itself and the results can't really be combined
* The font-locking of results is an expensive operation which involves copying the value
to a temporary buffer, where we check its integrity and do the actual font-locking.

By default CIDER instructs nREPL to stream data in 4K chunks, but you can easily modify this:

[source,lisp]
----
;; let's stream data in 8K chunks
(setq cider-print-buffer-size (8 * 1024))
----

Setting this to `nil` will result in using nREPL's default `buffer-size` of 1024 bytes.
The smaller the print buffer size the faster you'll get feedback/updates in the REPL, so generally
it's a good idea to stick to some relatively small size.

TIP: If you'd like to learn more about the font-locking of results you can check
out the definition of `clojure-font-lock-as` and `clojure-font-lock-as-clojure`
in `cider-util.el`.

== Pretty printing in the REPL

By default the REPL always prints the results of your evaluations using the
printing function specified by `cider-print-fn`.

NOTE: This behavior was changed in CIDER 0.20. In prior CIDER releases
pretty-printing was disabled by default.

You can temporarily disable this behavior and revert to the default behavior
(equivalent to `clojure.core/pr`) using kbd:[M-x cider-repl-toggle-pretty-printing]
or the REPL shortcut `toggle-pprint`.

If you want to disable using `cider-print-fn` entirely, use:

[source,lisp]
----
(setq cider-repl-use-pretty-printing nil)
----

Note that disabling pretty-printing is not advised. Emacs does not handle well
very long lines, so using a printing function that wraps lines beyond a certain
width (i.e. any of them except for `pr`) will keep your REPL running smoothly.

TIP: See xref:usage/pretty_printing.adoc[this section of the documentation] for
more information on configuring printing.

== Displaying images in the REPL

Starting with CIDER 0.17 (Andalucía) expressions that evaluate to
images can be rendered as images in the REPL. You can enable this
behavior like this:

[source,lisp]
----
(setq cider-repl-use-content-types t)
----

NOTE: This setting used to be enabled by default until CIDER 0.25 when it was
disabled due to some rough edges with the feature that were
never properly addressed. See this https://github.com/clojure-emacs/cider/issues/2825[bug report]
for details.

Alternatively, you can toggle this behavior on and off using kbd:[M-x cider-repl-toggle-content-types]
or the REPL shortcut `toggle-content-types`.

== REPL type detection

Normally CIDER would detect automatically the type of a REPL (Clojure or ClojureScript), based
on information it receives from the `track-state` middleware, that's part of `cider-nrepl`.

In some rare cases (e.g. a bug in `cider-nrepl` or `shadow-cljs`) this
auto-detection might fail and return the wrong type (e.g. Clojure instead of
ClojureScript).  You can disable the auto-detection logic like this:

[source,lisp]
----
(setq cider-repl-auto-detect-type nil)
----

Afterwards you can use `cider-repl-set-type` to set the right type manually.

IMPORTANT: Using `cider-repl-set-type` without disabling
`cider-repl-auto-detect-type` won't do much, as the REPL type will constantly be
reset automatically by the `track-state` middleware.

== REPL history

* To make the REPL history wrap around when CIDER reaches the end:

[source,lisp]
----
(setq cider-repl-wrap-history t)
----

* To adjust the maximum number of items kept in the REPL history:

[source,lisp]
----
(setq cider-repl-history-size 1000) ; the default is 500
----

* To store the REPL history of all projects in a single file:

[source,lisp]
----
(setq cider-repl-history-file "path/to/file")
----

* To store the REPL history per project (by creating a
  `.cider-history` file at the root of each):

[source,lisp]
----
(setq cider-repl-history-file 'per-project)
----

Note that CIDER writes the history to the file(s) when you kill the
REPL buffer, which includes invoking `cider-quit`, or when you quit
Emacs.
