CIDER packs a ton of extra functionality, besides basic Clojure code
evaluation. Much of the functionality is centered around additional major modes,
which provide you with convenient ways to get something done or inspect
something.
## Evaluating Clojure code in the minibuffer
You can evaluate Clojure code in the minibuffer from pretty much everywhere by
using M-x `cider-read-and-eval` (bound in `cider-mode` buffers to
C-c M-:). TAB completion will work in the minibuffer,
just as in a REPL/source buffer.
Pressing C-c C-v . in a Clojure buffer will insert the defun
at point into the minibuffer for evaluation. This way you can pass arguments
to the function and evaluate it and see the result in the minibuffer.
You can also enable `eldoc-mode` in the minibuffer by adding the following to your
config:
```el
(add-hook 'eval-expression-minibuffer-setup-hook #'eldoc-mode)
```
You can also enable `paredit` or `smartparens` for minibuffer evaluations:
```el
(add-hook 'eval-expression-minibuffer-setup-hook #'paredit-mode)
```
## Using a scratchpad
CIDER provides a simple way to create a Clojure scratchpad via the
M-x `cider-scratch` command. It provides a great way to
play around with some code, without having to create source files
or pollute the REPL buffer.
In many ways the CIDER scratchpad is similar to Emacs's own `*scratch*` buffer.
## Macroexpansion
Pressing C-c C-m after some form in a source buffer or the REPL will
result in a new buffer, showing the macroexpansion of the form in
question. You'll have access to additional keybindings in the macroexpansion
buffer (which is internally using `cider-macroexpansion-mode`):
Keyboard shortcut | Description
----------------------------------|-------------------------------
m | Invoke `macroexpand-1` on the form at point and replace the original form with its expansion. If invoked with a prefix argument, `macroexpand` is used instead of `macroexpand-1`.
a | Invoke `clojure.walk/macroexpand-all` on the form at point and replace the original form with its expansion.
g | The prior macroexpansion is performed again and the current contents of the macroexpansion buffer are replaced with the new expansion.
C-/
u | Undo the last inplace expansion performed in the macroexpansion buffer.
## Value inspection
Pressing C-c M-i after some form in a source buffer or the REPL will
result in a new buffer, showing the structure of the result of the form in question.
You can also use C-u C-c M-i to inspect the result of the current top-level
form and C-u C-u C-c M-i to read an expression from the minibuffer and
inspect its result.
You'll have access to additional keybindings in the inspector buffer (which is
internally using `cider-inspector-mode`):
Keyboard shortcut | Description
----------------------------------------|-------------------------------
Tab or Shift-Tab | Navigate inspectable sub-objects
Return | Inspect sub-objects
l | Pop to the parent object
g | Refresh the inspector (e.g. if viewing an atom/ref/agent)
SPC | Jump to next page in paginated view
M-SPC | Jump to previous page in paginated view
s | Set a new page size in paginated view
## Enlighten (display local values)
This feature displays the value of locals in realtime, as your code is being
executed. This is somewhat akin to one of the features of the Light Table
editor.
- To turn it on, issue M-x `cider-enlighten-mode`.
- To use it, evaluate your functions one at a time (e.g., use C-M-x or
C-x C-e, because C-c C-k won't work).
That's it! Once your code executes, the regular old buffer on the left will turn
into the brilliant show of lights on the right.
To stop displaying the locals you'll have to disable `cider-enlighten-mode`
and reevaluate the definitions you had instrumented previously.
You can also trigger this on specific functions (without having to turn on the
minor mode) by writing `#light` before the `(def` and reevaluating it.
## Code reloading
`cider-refresh` wraps
[clojure.tools.namespace](https://github.com/clojure/tools.namespace), and as
such the same
[benefits](https://github.com/clojure/tools.namespace#reloading-code-motivation)
and
[caveats](https://github.com/clojure/tools.namespace#reloading-code-preparing-your-application)
regarding writing reloadable code also apply.
Calling `cider-refresh` will cause all modified Clojure files on the classpath
to be reloaded. You can also provide a single prefix argument to reload all
Clojure files on the classpath unconditionally, or a double prefix argument to
first clear the state of the namespace tracker before reloading.
The above three operations are analogous to
[`clojure.tools.namespace.repl/refresh`](http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh),
[`clojure.tools.namespace.repl/refresh-all`](http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh-all)
and
[`clojure.tools.namespace.repl/clear`](http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/clear)
(followed by a normal refresh), respectively.
* You can define Clojure functions to be called before reloading, and after a
successful reload, when using `cider-refresh`:
```el
(setq cider-refresh-before-fn "user/stop-system!"
cider-refresh-after-fn "user/start-system!")
```
* These must be set to the namespace-qualified names of vars bound to functions
of no arguments. The functions must be synchronous (blocking), and are
expected to be side-effecting - they will always be executed serially, without
retries.
* By default, messages regarding the status of the in-progress reload will be
displayed in the echo area after you call `cider-refresh`. The same
information will also be recorded in the `*cider-refresh-log*` buffer, along
with anything printed to `*out*` or `*err*` by `cider-refresh-before-fn` and
`cider-refresh-start-fn`.
* You can make the `*cider-refresh-log*` buffer display automatically after you
call `cider-refresh` by setting the `cider-refresh-show-log-buffer` variable
to a non-nil value (this will also prevent any related messages from also
being displayed in the echo area):
```el
(setq cider-refresh-show-log-buffer t)
```
## Tracing function execution
You can trace the results produced by functions using C-c M-t v. The
command will prompt you for the name of the function you want to trace.
Evaluating the command again for the same function will result in the function
being untraced.
You can also use C-c M-t n to toggle tracing on and off for an entire
namespace.
## Classpath browser
You can easily browse the items on your classpath with the command
M-x `cider-classpath`.
Here you can see it in action:
Press RET on a classpath entry to navigate into it.
## Namespace browser
You can browse the contents of any loaded namespace with the command
M-x `cider-browse-ns`. The command will prompt you for the namespace
to browse.
You can also browse all available namespaces with M-x
`cider-browse-ns-all`.
There are a bunch of useful keybindings that are defined in browser buffers.
Keyboard shortcut | Description
--------------------------------|-------------------------------
d | Display documentation for item at point.
RET | Browse ns or display documentation for item at point.
s | Go to definition for item at point.
^ | Browse all namespaces.
n | Go to next line.
p | Go to previous line.
## REPL history browser
You can browse your REPL input history with the command M-x
`cider-repl-history`. It is also bound in `cider-repl-mode` buffers to
C-c M-p, and is also available via the `history` shortcut.
The history is displayed in order, with the most recent input at the top of the
buffer, and the oldest one at the bottom. You can scroll through the history,
and when you find the history item you were looking for, you can insert it from
the history buffer into your REPL buffer.
### Mode
The history buffer has its own major mode, `cider-repl-history-mode` which is derived
from `clojure-mode`, so you get fontification in the history buffer. It supports
the expected defcustom hook variable, `cider-repl-history-hook`.
### Insertion
Typically your cursor will be at the bottom of the REPL buffer (`point-max`)
when you use this feature; if that's the case, the text is inserted, and point
is advanced to the end of the inserted text. In the unusual case where you
invoke the history browser when your cursor is _not_ at the end of the buffer,
the text is _still_ inserted at point-max, but point is not modified.
The text is inserted without a final newline, meaning you can edit the form
if you wish, and you must explicitly hit Enter to have it evaluated
by the REPL.
### Quitting
After text is inserted, the history buffer is automatically quit. If you decide
you don't want to insert any text after all, you can explicitly quit by running
`cider-repl-history-quit` (see keyboard shortcuts). Due to the initialization and
cleanup done, it is better to properly quit, rather than just switch away from
the history buffer.
When you quit the history buffer, there are several different ways for the
buffers and windows to be restored. This is controlled by the custom variable
`cider-repl-history-quit-action`, which can be assigned one of several values:
- `quit-window` restores the window configuration to what it was before.
This is the default.
- `delete-and-restore` restores the window configuration to what it was before,
and kills the `*cider-repl-history*` buffer.
- `kill-and-delete-window` kills the `*cider-repl-history*` buffer, and
deletes the window.
- `bury-buffer` simply buries the `*cider-repl-history*` buffer, but keeps the
window.
- `bury-and-delete-window` buries the buffer, and (if there is more than one
window) deletes the window.
- any other value is interpreted as the name of a function to call
### Filtering
By invoking `cider-repl-history-occur` from the history buffer, you will be prompted
for a regular expression, and the history buffer will be filtered to only those
inputs that match the regexp.
### Preview and Highlight
When `cider-repl-history-show-preview` is non-nil, we display an [`overlay`]
(https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html)
of the currently selected history entry, in the REPL buffer.
This is a nice feature; the only thing to be careful of is that if you do not
properly quit from browsing the history (i.e., if you just C-x b
away from the buffer), you may be left with an unwanted overlay in your REPL
buffer. It can be eliminated with M-x `cider-repl-history-clear-preview`.
By default, the variable is nil and the feature is off.
A related feature is to highlight the entry once it is actually inserted into
the REPL buffer. This is controlled by the variable
`cider-repl-history-highlight-inserted-item`. The non-nil value selected controls how
the inserted item is highlighted, possible values are `solid` (highlight the
inserted text for a fixed period of time), or `pulse` (fade out the highlighting
gradually). Setting this variable to the value t will select the default
highlighting style, which currently `pulse`. Default is nil.
When "highlight-inserted" is turned on, you can customize the face of the
inserted text with the variable `cider-repl-history-inserted-item-face`.
### Additional Customization
There are quite a few customizations available, in addition to the ones
already mentioned.
- `cider-repl-history-display-duplicates` - when set to `nil`, will not display any
duplicate entries in the history buffer. Default is `t`.
- `cider-repl-history-display-duplicate-highest` - when not displaying duplicates,
this controls where in the history the one instance of the duplicated text
is displayed. When `t`, it displays the entry in the highest position
applicable; when `nil`, it displays it in the lowest position.
- `cider-repl-history-display-style` - the history entries will often be more than
one line. The package gives you two options for displaying the entries:
- `separated` - a separator string is inserted between entries; entries
may span multiple lines. This is the default.
- `one-line` - any newlines are replaced with literal `\n` strings, and
therefore no separator is necessary. Each `\n` becomes a proper newline
when the text is inserted into the REPL.
- `cider-repl-history-separator` - when `cider-repl-history-display-style` is `separated`,
this gives the text to use as the separator. The default is a series of ten
semicolons, which is, of course, a comment in Clojure. The separator could be
anything, but it may screw up the fontification if you make it something weird.
- `cider-repl-history-separator-face` - specifies the face for the separator.
- `cider-repl-history-maximum-display-length` - when nil (the default), all history
items are displayed in full. If you prefer to have long items abbreviated,
you can set this variable to an integer, and each item will be limited to that
many characters. (This variable does not affect the number of items displayed,
only the maximum length of each item.)
- `cider-repl-history-recenter` - when non-nil, always keep the current entry at the
top of the history window. Default is nil.
- `cider-repl-history-resize-window` - whether to resize the history window to fit
its contents. Value is either t, meaning yes, or a cons pair of integers,
(MAXIMUM . MINIMUM) for the size of the window. MAXIMUM defaults to the window
size chosen by `pop-to-buffer`; MINIMUM defaults to `window-min-height`.
- `cider-repl-history-highlight-current-entry` - if non-nil, highlight the currently
selected entry in the history buffer. Default is nil.
- `cider-repl-history-current-entry-face` - specifies the face for the history-entry
highlight.
- `cider-repl-history-text-properties` - when set to `t`, maintains Emacs text
properties on the entry. Default is `nil`.
### Key Bindings
There are a number of important keybindings in history buffers.
Keyboard shortcut | Description
---------------------------------|-------------------------------
n | Go to next (lower, older) item in the history.
p | Go to previous (higher, more recent) item in the history.
RET or SPC | Insert history item (at point) at the end of the REPL buffer, and quit.
l (lower-case L) | Filter the command history (see **Filtering**, above).
s | Regexp search forward.
r | Regexp search backward.
q | Quit (and take quit action).
U | Undo in the REPL buffer.
## Documentation buffers include "See Also" references
You can add references to other vars by including their names in `` ` `` in the docstring.
If the var is in another namespace, then you'll have to include the full
namespace qualified name in the docstring. If you want to use some other delimiter instead
of the backticks, you'll have to update the value of `cider-doc-xref-regexp` to match that.
The first group of the regexp should always match the var name.
As an example, if you want to want to use the delimiter style used by
[Codox](https://github.com/weavejester/codox) (`[[...]]`) the regexp would be;
```
(setq cider-doc-xref-regexp "\\[\\[\\(.*?\\)\\]\\]")
```
Example function with a docstring containing references:
```
(defn test-fn
"Test function.
Also see: `clojure.core/map`, `clojure.core/reduce`, `defn`.
You can reference variables like `thor`, `kubaru.data.zookeeper/yoda`.
Also works with references to java interop forms, `java.lang.String/.length`."
[]
(+ 1 1))
```