= Basic Usage
:experimental:

CIDER comes with a powerful REPL that complements the interactive
development functionality in `cider-mode`. Using the CIDER REPL you
can experiment with your running program, test functions, or just
explore a new library you're interested in using. The CIDER REPL offers a number of advanced features:

* code completion
* font-locking (the same as in `clojure-mode`)
* quick access to many CIDER commands (e.g. definition and documentation lookup, tracing, etc)
* pretty-printing of evaluation results
* inline display of images
* persistent REPL history
* powerful REPL history browser
* eldoc support
* highly customizable REPL prompt

== Interacting with the REPL

Interacting with CIDER's REPL is pretty simple - most of the time
you'd just write expressions there and press kbd:[RET] to
evaluate them.

But the REPL is a bit more powerful than that and it allows you to do some things that might not be available in
other Clojure REPLs. Some examples of such things would be:

* You can close an incomplete expression with kbd:[C-RET]
* You can enter a multi-line expression by pressing kbd:[C-j] at the end of each line
* You can quickly jump to the definition of a symbol (kbd:[.]) or to its documentation (kbd:[C-c C-d d])
* You can clear the output of the last expression with kbd:[C-c C-o]
* You can clear the REPL buffer with kbd:[C-u C-c C-o]
* You can jump between your source buffers and the REPL with kbd:[C-c C-z]
* You can jump between your Clojure and ClojureScript REPLs with kbd:[C-c M-o]

On top of this the REPL is extremely configurable and you can tweak almost every aspect of it.

== Interrupting Evaluations

If you accidentally try to evaluate something that's going to take a lot of time (if it finishes at all), you
can interrupt the rogue evaluation operation by pressing kbd:[C-c C-c].

TIP: Note that this is different from the keybinding for interrupting evaluations in source buffers,
namely kbd:[C-c C-b].

== Quitting a REPL

When you're done with a REPL you can dispose of it with kbd:[C-c C-q].

TIP: Avoid killing REPL buffers with kbd:[C-c C-k]. This will forgo
some of the operations needed to properly dispose of a REPL buffer.

== Loading REPL Utility Functions

Normally Clojure REPLs load the following code in the first REPL that you start:

[source,clojure]
----
(clojure.core/apply clojure.core/require clojure.main/repl-requires)
----

CIDER does this as well, but goes one step further and actually allows you
to control what code to evaluate when a REPL is being initialized via
the variable `cider-repl-init-code`.

This initialization code is auto-loaded only in the first REPL namespace
(normally `user`), but you can easily invoke it in any namespace using the REPL
shortcut `require-repl-utils`. The functionality is also accessible via
CIDER's menu ("REPL -> Require REPL utils").

TIP: You'll rarely need the REPL utility functions when using CIDER, as it
provides many Emacs commands that behave similarly (e.g. instead of doing
something like `(doc str)` you'd probably use the `cider-doc` (kbd:[C-c C-d C-d]) command).

== Known Limitations

Performance can degrade when the REPL buffer grows very large. This is
especially true if either `cider-repl-use-clojure-font-lock` or
`nrepl-log-messages` are enabled.

Very long lines are guaranteed to bring Emacs to a crawl, so using a value of
`cider-print-fn` that wraps lines beyond a certain width (i.e. any of the
built-in options except for `pr`) is advised.

TIP: You can use `cider-repl-clear-output` to
either clear the result of the previous evaluation, or with a prefix argument
clear the entire REPL buffer. You can also set `cider-repl-buffer-size-limit`
which will enable trimming the buffer automatically after each evaluation. This
trimming can also be invoked manually with `cider-repl-trim-buffer`.
