diff options
Diffstat (limited to 'doc/miscellaneous_features.md')
| -rw-r--r-- | doc/miscellaneous_features.md | 246 |
1 files changed, 138 insertions, 108 deletions
diff --git a/doc/miscellaneous_features.md b/doc/miscellaneous_features.md index 499aedcc..05111a28 100644 --- a/doc/miscellaneous_features.md +++ b/doc/miscellaneous_features.md @@ -1,64 +1,59 @@ -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. +As the infomercials always say, "But wait, there's more!" If +simultaneous Clojure and ClojureScript REPLs, interactive programming, +code completion, stacktrace navigation, test running, and debugging +weren't enough for you, CIDER delivers several additional +features. -## Evaluating Clojure code in the minibuffer +## Evaluating Clojure Code in the Minibuffer -You can evaluate Clojure code in the minibuffer from pretty much everywhere by +You can evaluate Clojure code in the minibuffer at almost any time using <kbd>M-x</kbd> `cider-read-and-eval` (bound in `cider-mode` buffers to <kbd>C-c M-:</kbd>). <kbd>TAB</kbd> completion will work in the minibuffer, -just as in a REPL/source buffer. +just as in REPL and source buffers. -Pressing <kbd>C-c C-v .</kbd> in a Clojure buffer will insert the defun +Typing <kbd>C-c C-v .</kbd> 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: +You can also enable other convenient modes in the minibuffer. For +instance, you might want to have both `eldoc-mode` and `paredit-mode` +available to you: ```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 +## Using a Scratchpad CIDER provides a simple way to create a Clojure scratchpad via the -<kbd>M-x</kbd> `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. +<kbd>M-x</kbd> `cider-scratch` command. This is a great way to play +around with some code without having to create source files or pollute +the REPL buffer and is very similar to Emacs's own `*scratch*` buffer. -In many ways the CIDER scratchpad is similar to Emacs's own `*scratch*` buffer. +## Expanding Macros -## Macroexpansion - -Pressing <kbd>C-c C-m</kbd> 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`): +Typing <kbd>C-c C-m</kbd> after some form in a source buffer or the +REPL will show you the macro expansion of the form in a new +buffer. You'll have access to additional keybindings in the macro +expansion buffer (which is internally using +`cider-macroexpansion-mode`): Keyboard shortcut | Description ----------------------------------|------------------------------- <kbd>m</kbd> | 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`. <kbd>a</kbd> | Invoke `clojure.walk/macroexpand-all` on the form at point and replace the original form with its expansion. -<kbd>g</kbd> | The prior macroexpansion is performed again and the current contents of the macroexpansion buffer are replaced with the new expansion. -<kbd>C-/</kbd> <br/> <kbd>u</kbd> | Undo the last inplace expansion performed in the macroexpansion buffer. - -## Value inspection +<kbd>g</kbd> | The prior macro expansion is performed again and the current contents of the macro expansion buffer are replaced with the new expansion. +<kbd>C-/</kbd> <br/> <kbd>u</kbd> | Undo the last in-place expansion performed in the macroexpansion buffer. -Pressing <kbd>C-c M-i</kbd> 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 <kbd>C-u C-c M-i</kbd> to inspect the result of the current top-level -form and <kbd>C-u C-u C-c M-i</kbd> to read an expression from the minibuffer and -inspect its result. +## Inspecting Values -You'll have access to additional keybindings in the inspector buffer (which is +Typing <kbd>C-c M-i</kbd> after some form in a source buffer or the +REPL will show you the structure for the result of the form in a new +buffer. You can also use <kbd>C-u C-c M-i</kbd> to inspect the result +of the current top-level form and <kbd>C-u C-u C-c M-i</kbd> 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 @@ -71,31 +66,52 @@ Keyboard shortcut | Description <kbd>M-SPC</kbd> | Jump to previous page in paginated view <kbd>s</kbd> | Set a new page size in paginated view -## Enlighten (display local values) +## Displaying Local Values with Enlighten Mode -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 +Enlighten Mode displays the value of locals in realtime, as your code +runs. This feature is somewhat similar to a feature in the Light Table editor. -- To turn it on, issue <kbd>M-x</kbd> `cider-enlighten-mode`. -- To use it, evaluate your functions one at a time (e.g., use <kbd>C-M-x</kbd> or -<kbd>C-x C-e</kbd>, because <kbd>C-c C-k</kbd> won't work). +To turn it on, issue <kbd>M-x</kbd> `cider-enlighten-mode`. Then, +evaluate your functions one at a time using <kbd>C-M-x</kbd> or +<kbd>C-x C-e</kbd>. Note that <kbd>C-c C-k</kbd> 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. -<p align="center"> - <img src="images/enlighten_disabled.png" height="300" /> - <img src="images/enlighten_enabled.png" height="300" /> -</p> +Enlighten Mode Disabled | Enlighten Mode Enabled +-------------------------------------------|--------------------------------------- + |  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. +minor mode) by writing `#light` before the `(def` and re-evaluating +it. + +## Reloading Code -## Code reloading +While Clojure's and CIDER's interactive programming style means you'll +restart your application far less often than with other languages and +development environments, sometimes you'll want to clean everything up +and reload one or more namespaces to ensure that they are up to date +and there are no temporary definitions hanging around. + +Typing <kbd>C-c M-n r</kbd> or <kbd>C-c M-n M-r</kbd> will invoke +`cider-ns-refresh` and reload all modified Clojure files on the +classpath. + +Adding a prefix argument, <kbd>C-u C-c M-n n</kbd>, will reload all +the namespaces on the classpath unconditionally, regardless of their +modification status. + +Adding a double prefix argument, <kbd>C-u C-u M-n n</kbd>, will first +clear the state of the namespace tracker before reloading. This is +useful for recovering from some classes of error that normal reloads +would otherwise not recover from. A good example is circular +dependencies. The trade-off is that stale code from any deleted files +may not be completely unloaded. `cider-ns-refresh` wraps [clojure.tools.namespace](https://github.com/clojure/tools.namespace), and as @@ -105,11 +121,6 @@ and [caveats](https://github.com/clojure/tools.namespace#reloading-code-preparing-your-application) regarding writing reloadable code also apply. -Calling `cider-ns-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) @@ -117,55 +128,62 @@ 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-ns-refresh`: +You can define Clojure functions to be called before reloading, and after a +successful reload, when using `cider-ns-refresh`: ```el (setq cider-ns-refresh-before-fn "user/stop-system!" cider-ns-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. +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-ns-refresh`. The same - information will also be recorded in the `*cider-ns-refresh-log*` buffer, along - with anything printed to `*out*` or `*err*` by `cider-ns-refresh-before-fn` and - `cider-ns-refresh-start-fn`. +By default, messages regarding the status of the in-progress reload +will be displayed in the echo area after you call +`cider-ns-refresh`. The same information will also be recorded in the +`*cider-ns-refresh-log*` buffer, along with anything printed to +`*out*` or `*err*` by `cider-ns-refresh-before-fn` and +`cider-ns-refresh-start-fn`. -* You can make the `*cider-ns-refresh-log*` buffer display automatically after you - call `cider-ns-refresh` by setting the `cider-ns-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): +You can make the `*cider-ns-refresh-log*` buffer display automatically +after you call `cider-ns-refresh` by setting the +`cider-ns-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-ns-refresh-show-log-buffer t) ``` -* By default, all modified Clojure buffers are prompted to be saved. This - behaviour can be customized using `cider-ns-save-files-on-refresh`. +By default, CIDER will prompt for whether to save all modified Clojure +buffers. You can customize this behavior with +`cider-ns-save-files-on-refresh`. -In case `cider-ns-refresh` does not work for you the -`cider-ns-reload`|`cider-ns-reload-all` commands can be used instead: they will -evaluate the Clojure's out of the box `(require ... :reload|:reload-all)` at -the REPL. +Sometimes, `cider-ns-refresh` may not work for you. If you're looking +for a bit more forceful reloading the `cider-ns-reload` +and `cider-ns-reload-all` commands can be used instead. These commands +invoke Clojure's `(require ... :reload)` and `(require +... :reload-all)` commands at the REPL. -## Tracing function execution +## Tracing Function Execution -You can trace the results produced by functions using <kbd>C-c M-t v</kbd>. 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 trace the arguments supplied to and the result values produced +by functions using <kbd>C-c M-t v</kbd>. CIDER will prompt you for the +name of the function you want to trace, defaulting to the previous +top-level definition.  -You can also use <kbd>C-c M-t n</kbd> to toggle tracing on and off for an entire -namespace. +Invoking <kbd>C-c M-t v</kbd> again for the same function will result +in the function being untraced. + +You can also use <kbd>C-c M-t n</kbd> to toggle tracing on and off for +an entire namespace. -## Classpath browser +## Browsing the Classpath You can easily browse the items on your classpath with the command <kbd>M-x</kbd> `cider-classpath`. @@ -176,10 +194,10 @@ Here you can see it in action: Press <kbd>RET</kbd> on a classpath entry to navigate into it. -## Namespace browser +## Browsing Namespaces You can browse the contents of any loaded namespace with the command -<kbd>M-x</kbd> `cider-browse-ns`. The command will prompt you for the namespace +<kbd>M-x</kbd> `cider-browse-ns`. CIDER will prompt you for the namespace to browse.  @@ -198,22 +216,24 @@ Keyboard shortcut | Description <kbd>n</kbd> | Go to next line. <kbd>p</kbd> | Go to previous line. -## Spec browser +## Browsing the Clojure Spec Registry -If you are using Clojure 1.9.0-alpha16 or newer you can browse the Clojure specs registry. +If you are using Clojure 1.9 or newer you can browse the Clojure spec registry. -If you know what you are looking for, you can type <kbd>M-x</kbd> `cider-browse-spec`. -It will prompt you for a spec name to browse to, hit <kbd>RET</kbd> and you will find yourself -at the spec browser. +If you already know which spec you're looking for, you can type +<kbd>M-x</kbd> `cider-browse-spec` and CIDER will prompt you for a +spec name and then drop you into the spec browser.  -You can also type the command <kbd>M-x</kbd> `cider-browse-spec-all`. This command will prompt you for -a regex you can use to filter out the specs you are interested in, and will also take you to the spec browser. +If you aren't quite sure which spec you want, you can type +<kbd>M-x</kbd> `cider-browse-spec-all`. CIDER will then prompt you for +a regex and will filter out all the spec names that don't match.  -Once in the browser you can use your mouse or the keybindings below to navigate deeper into sub specs. +Once in the browser you can use your mouse or the keybindings below to +navigate deeper. Keyboard shortcut | Description --------------------------------|------------------------------- @@ -223,27 +243,22 @@ Keyboard shortcut | Description <kbd>p</kbd> | Go to previous spec. <kbd>e</kbd> | Generate an example for the current browser spec. -If your project contains a version of `org.clojure/test.check`, you can type <kbd>e</kbd> when browsing -a spec to generate and print an example of it. +If your project includes the `org.clojure/test.check` library, you can +type <kbd>e</kbd> when browsing a spec to generate an example that +meets the spec.  -## 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. +## Generating Documentation Cross References -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; +Sometimes in your documentation strings, you'd like to be able to +point other programmers at different definitions. If you specify the +name of a definition in backticks (`` ` ``), CIDER will convert these +references into live links when it displays the documentation string +in the documentation buffer. -``` -(setq cider-doc-xref-regexp "\\[\\[\\(.*?\\)\\]\\]") -``` - - +If the name is in another namespace, then you'll have to include the +fully qualified name in the docstring. Example function with a docstring containing references: @@ -256,3 +271,18 @@ Example function with a docstring containing references: [] (+ 1 1)) ``` + +You can change the delimiters that CIDER uses to find references if +you don't like using backticks. Simply update the regexp in +`cider-doc-xref-regexp` to match your preferred format. The first +group of the regexp should always match the cross-reference name. For +example, if you want to want to use +[Codox's](https://github.com/weavejester/codox) delimiter style +(`[[...]]`) instead of backticks, the regexp would be: + +``` +(setq cider-doc-xref-regexp "\\[\\[\\(.*?\\)\\]\\]") +``` + + + |