doomemacs/modules/lang/clojure/README.org

#+title:    :lang clojure
#+subtitle: Java with a lisp
#+created:  May 30, 2017
#+since:    2.0.3

* Description :unfold:
This module adds support for the Clojure(Script) language.

- Interactive development environment (~cider~): REPL, compilation, debugging,
  running tests, definitions & documentation lookup, code completion, and much
  more
- Refactoring (~clj-refactor~)
- Linting (~clj-kondo~), requires [[doom-module::checkers syntax]]
- LSP support (~clojure-lsp~), required [[doom-module:+lsp]]

** Maintainers
- [[doom-user:][@elken]]

** Module flags
- +lsp ::
  Enable LSP support for ~clojure-mode~ (alongside Cider). Requires [[doom-module::tools lsp]]
  and a langserver (supports [[https://clojure-lsp.io/][clojure-lsp]]).
- +tree-sitter ::
  Leverages tree-sitter for better syntax highlighting and structural text
  editing. Requires [[doom-module::tools tree-sitter]].

** Packages
- [[doom-package:cider]]
- [[doom-package:clj-refactor]]
- [[doom-package:flycheck-clj-kondo]] if [[doom-module::checkers syntax]]

** Hacks
- Error messages emitted from CIDER are piped into the REPL buffer when it is
  first opened, to make them easier to notice.
- Disabled the help banner when opening the cider REPL.

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires:
- [[https://clojure.org/][clojure]]

This module optionally requires:
- [[https://github.com/borkdude/clj-kondo][clj-kondo]], for linting code (if [[doom-module::checkers syntax]])
- [[https://clojure-lsp.github.io/clojure-lsp/][clojure-lsp]], for LSP support (if [[doom-module:+lsp]])
- [[https://github.com/babashka/neil][neil]] for the ability to add packages to your Clojure project from Emacs
- [[https://github.com/borkdude/jet][jet]] for jet integration
- [[https://github.com/weavejester/cljfmt][cljfmt]], for formatting code (if [[doom-module::editor format]])

* Usage

Below is a listing of the various keybinds provided by the module. 

** REPL management
For the most part, general usage should fall into:

- Open a Clojure project
- Open/connect to a REPL

As such, these bindings are most likely to be used.

| Keybind                     | Command                                            |
|-----------------------------+----------------------------------------------------|
| [[kbd:][<localleader> ']]   | ~cider-jack-in-clj~                                  |
| [[kbd:][<localleader> c]]   | ~cider-connect-clj~                                  |
| [[kbd:][<localleader> C]]   | ~cider-connect-cljs~                                 |
| [[kbd:][<localleader> m "]] | ~cider-jack-in-cljs~                                 |
| [[kbd:][<localleader> r R]] | ~cider-restart~                                      |
| [[kbd:][<localleader> r q]] | ~cider-quit~                                         |
| [[kbd:][<localleader> r B]] | ~+clojure/cider-switch-to-repl-buffer-and-switch-ns~ |
| [[kbd:][<localleader> r L]] | ~cider-load-buffer-and-switch-to-repl-buffer~        |
| [[kbd:][<localleader> r b]] | ~cider-switch-to-repl-buffer~                        |
| [[kbd:][<localleader> r c]] | ~cider-find-and-clear-repl-output~                   |
| [[kbd:][<localleader> r l]] | ~cider-load-buffer~                                  |
| [[kbd:][<localleader> r n]] | ~cider-repl-set-ns~                                  |
| [[kbd:][<localleader> r r]] | ~cider-ns-refresh~                                   |

** Tests
The module also provides support for running tests through cider, including a nicely formatted output.

| Keybind                     | Command                              |
|-----------------------------+--------------------------------------|
| [[kbd:][<localleader> t a]] | ~cider-test-rerun-test~                |
| [[kbd:][<localleader> t l]] | ~cider-test-run-loaded-tests~          |
| [[kbd:][<localleader> t n]] | ~cider-test-run-ns-tests~              |
| [[kbd:][<localleader> t p]] | ~cider-test-run-project-tests~         |
| [[kbd:][<localleader> t r]] | ~cider-test-rerun-failed-tests~        |
| [[kbd:][<localleader> t s]] | ~cider-test-run-ns-tests-with-filters~ |
| [[kbd:][<localleader> t t]] | ~cider-test-run-test~                  |


** Search/navigation
Some useful bindings for navigating around namespaces and symbols. When using [[doom-module:+lsp]], the bindings in [[doom-module::tools lsp]] are supported.

| Keybind                     | Command             |
|-----------------------------+---------------------|
| [[kbd:][<localleader> g b]] | ~cider-pop-back~      |
| [[kbd:][<localleader> g g]] | ~cider-find-var~      |
| [[kbd:][<localleader> g n]] | ~cider-find-ns~       |
| [[kbd:][<localleader> h n]] | ~cider-find-ns~       |
| [[kbd:][<localleader> n N]] | ~cider-browse-ns-all~ |
| [[kbd:][<localleader> n n]] | ~cider-browse-ns~     |
| [[kbd:][<localleader> h a]] | ~cider-apropos~       |

** Evaluation
Outside of the [[kbd:][SPC m e]] bindings for evaluating forms, the following are also available; including some to pretty-print the results.

| Keybind                     | Command                                |
|-----------------------------+----------------------------------------|
| [[kbd:][<localleader> e D]] | ~cider-insert-defun-in-repl~             |
| [[kbd:][<localleader> e E]] | ~cider-insert-last-sexp-in-repl~         |
| [[kbd:][<localleader> e R]] | ~cider-insert-region-in-repl~            |
| [[kbd:][<localleader> e b]] | ~cider-eval-buffer~                      |
| [[kbd:][<localleader> e d]] | ~cider-eval-defun-at-point~              |
| [[kbd:][<localleader> e e]] | ~cider-eval-last-sexp~                   |
| [[kbd:][<localleader> e r]] | ~cider-eval-region~                      |
| [[kbd:][<localleader> p d]] | ~cider-pprint-eval-defun-at-point~       |
| [[kbd:][<localleader> p D]] | ~cider-pprint-eval-defun-to-comment~     |
| [[kbd:][<localleader> p p]] | ~cider-pprint-eval-last-sexp~            |
| [[kbd:][<localleader> p P]] | ~cider-pprint-eval-last-sexp-to-comment~ |
| [[kbd:][<localleader> p r]] | ~cider-pprint-eval-last-sexp-to-repl~    |

** Debugging
A number of bindings to provide useful overlays that help during debugging. ~cider-enlighten-mode~ is a mode that will highlight the results of a function evaluation, /including the locals/. See a demo [[https://www.youtube.com/watch?v=tCu2AewBTR4][here]].

| Keybind                     | Command                   |
|-----------------------------+---------------------------|
| [[kbd:][<localleader> M]]   | ~cider-macroexpand-all~     |
| [[kbd:][<localleader> R]]   | ~hydra-cljr-help-menu/body~ |
| [[kbd:][<localleader> e u]] | ~cider-undef~               |
| [[kbd:][<localleader> i e]] | ~cider-enlighten-mode~      |
| [[kbd:][<localleader> i i]] | ~cider-inspect~             |
| [[kbd:][<localleader> i r]] | ~cider-inspect-last-result~ |
| [[kbd:][<localleader> m]]   | ~cider-macroexpand-1~       |

** Help
Several bindings used for viewing documentation for various functions, both inside and outside of both a REPL and Emacs ([[kbd:][K]] for example uses the sources and a cached version of clojuredocs)

| Keybind                     | Command               |
|-----------------------------+-----------------------|
| [[kbd:][<localleader> h c]] | ~cider-clojuredocs~     |
| [[kbd:][<localleader> h d]] | ~cider-doc~             |
| [[kbd:][<localleader> h j]] | ~cider-javadoc~         |
| [[kbd:][<localleader> h w]] | ~cider-clojuredocs-web~ |
| [[kbd:][K]]                 | ~+lookup/documentation~ |


* Configuration
** =enrich-classpath=
In recent versions, an option has been introduced that attempts to improve the experience of CIDER by accessing java source & javadocs, though this option is still currently considered beta.

In order to opt into this, add the following to your =config.el=

#+begin_src emacs-lisp
(setq cider-enrich-classpath t)
#+end_src

See [[https://docs.cider.mx/cider/config/basic_config.html#use-enrich-classpath][the docs]] for more

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote