1[![License GPL 3][badge-license]][copying] 2[![MELPA][melpa-badge]][melpa-package] 3[![MELPA Stable][melpa-stable-badge]][melpa-stable-package] 4[![circleci][badge-circleci]][circleci] 5 6# Clojure Mode 7 8Provides Emacs font-lock, indentation, navigation and refactoring for the 9[Clojure(Script) programming language](http://clojure.org). 10 11This document assumes you're familiar with Emacs. More thorough walkthroughs, 12targeting Emacs beginners, are available at 13[clojure-doc.org](http://clojure-doc.org/articles/tutorials/emacs.html) and 14[Clojure for the Brave and the True](http://www.braveclojure.com/basic-emacs/). 15Keep in mind, however, that they might be out-of-date. 16 17**This documentation tracks the `master` branch of `clojure-mode`. Some of 18the features and settings discussed here might not be available in 19older releases (including the current stable release). Please, consult 20the relevant git tag (e.g. 5.1.0) if you need documentation for a 21specific `clojure-mode` release.** 22 23*** 24 25- [Installation](#installation) 26- [Bundled major modes](#bundled-major-modes) 27- [Configuration](#configuration) 28 - [Indentation options](#indentation-options) 29 - [Indentation of function forms](#indentation-of-function-forms) 30 - [Indentation of macro forms](#indentation-of-macro-forms) 31 - [Vertical alignment](#vertical-alignment) 32- [Refactoring support](#refactoring-support) 33 - [Threading macros](#threading-macros-related-features) 34 - [Cycling things](#cycling-things) 35 - [Convert collection](#convert-collection) 36 - [Let expression](#let-expression) 37 - [Rename ns alias](#rename-ns-alias) 38 - [Add arity to a function](#add-arity-to-a-function) 39- [Related packages](#related-packages) 40- [REPL Interaction](#repl-interaction) 41 - [Basic REPL](#basic-repl) 42 - [CIDER](#cider) 43- [Changelog](#changelog) 44- [License](#license) 45 46## Installation 47 48Available on the major `package.el` community maintained repos - 49[MELPA Stable][] and [MELPA][] repos. 50 51MELPA Stable is the recommended repo as it has the latest stable 52version. MELPA has a development snapshot for users who don't mind 53(infrequent) breakage but don't want to run from a git checkout. 54 55You can install `clojure-mode` using the following command: 56 57<kbd>M-x package-install [RET] clojure-mode [RET]</kbd> 58 59or if you'd rather keep it in your dotfiles: 60 61```el 62(unless (package-installed-p 'clojure-mode) 63 (package-install 'clojure-mode)) 64``` 65 66If the installation doesn't work try refreshing the package list: 67 68<kbd>M-x package-refresh-contents</kbd> 69 70## Bundled major modes 71 72The `clojure-mode` package actually bundles together several major modes: 73 74* `clojure-mode` is a major mode for editing Clojure code 75* `clojurescript-mode` is a major mode for editing ClojureScript code 76* `clojurec-mode` is a major mode for editing `.cljc` source files 77 78All the major modes derive from `clojure-mode` and provide more or less the same 79functionality. Differences can be found mostly in the font-locking - 80e.g. ClojureScript has some built-in constructs that are not present in Clojure. 81 82The proper major mode is selected automatically based on the extension of the 83file you're editing. 84 85Having separate major modes gives you the flexibility to attach different hooks 86to them and to alter their behavior individually (e.g. add extra font-locking 87just to `clojurescript-mode`) . 88 89Note that all modes derive from `clojure-mode`, so things you add to 90`clojure-mode-hook` and `clojure-mode-map` will affect all the derived modes as 91well. 92 93## Configuration 94 95In the spirit of Emacs, pretty much everything you can think of in `clojure-mode` is configurable. 96 97To see a list of available configuration options do `M-x customize-group RET clojure`. 98 99### Indentation options 100 101The default indentation rules in `clojure-mode` are derived from the 102[community Clojure Style Guide](https://github.com/bbatsov/clojure-style-guide). 103Please, refer to the guide for the general Clojure indentation rules. 104 105#### Indentation of docstrings 106 107By default multi-line docstrings are indented with 2 spaces, as this is a 108somewhat common standard in the Clojure community. You can however adjust this 109by modifying `clojure-docstring-fill-prefix-width`. Set it to 0 if you don't 110want multi-line docstrings to be indented at all (which is pretty common in most lisps). 111 112#### Indentation of function forms 113 114The indentation of function forms is configured by the variable 115`clojure-indent-style`. It takes three possible values: 116 117- `always-align` (the default) 118 119```clj 120(some-function 121 10 122 1 123 2) 124(some-function 10 125 1 126 2) 127``` 128 129- `always-indent` 130 131```clj 132(some-function 133 10 134 1 135 2) 136(some-function 10 137 1 138 2) 139``` 140 141- `align-arguments` 142 143```clj 144(some-function 145 10 146 1 147 2) 148(some-function 10 149 1 150 2) 151``` 152 153**Note:** Prior to clojure-mode 5.10 the configuration options for `clojure-indent-style` used to be 154keywords, but now they are symbols. Keywords will still be supported at least until clojure-mode 6. 155 156#### Indentation of macro forms 157 158The indentation of special forms and macros with bodies is controlled via 159`put-clojure-indent`, `define-clojure-indent` and `clojure-backtracking-indent`. 160Nearly all special forms and built-in macros with bodies have special indentation 161settings in `clojure-mode`. You can add/alter the indentation settings in your 162personal config. Let's assume you want to indent `->>` and `->` like this: 163 164```clojure 165(->> something 166 ala 167 bala 168 portokala) 169``` 170 171You can do so by putting the following in your config: 172 173```el 174(put-clojure-indent '-> 1) 175(put-clojure-indent '->> 1) 176``` 177 178This means that the body of the `->/->>` is after the first argument. 179 180A more compact way to do the same thing is: 181 182```el 183(define-clojure-indent 184 (-> 1) 185 (->> 1)) 186``` 187 188You can also specify different indentation settings for symbols 189prefixed with some ns (or ns alias): 190 191```el 192(put-clojure-indent 'do 0) 193(put-clojure-indent 'my-ns/do 1) 194``` 195 196The bodies of certain more complicated macros and special forms 197(e.g. `letfn`, `deftype`, `extend-protocol`, etc) are indented using 198a contextual backtracking indentation method, require more sophisticated 199indent specifications. Here are a few examples: 200 201```el 202(define-clojure-indent 203 (implement '(1 (1))) 204 (letfn '(1 ((:defn)) nil)) 205 (proxy '(2 nil nil (1))) 206 (reify '(:defn (1))) 207 (deftype '(2 nil nil (1))) 208 (defrecord '(2 nil nil (1))) 209 (specify '(1 (1))) 210 (specify '(1 (1)))) 211``` 212 213These follow the same rules as the `:style/indent` metadata specified by [cider-nrepl][]. 214For instructions on how to write these specifications, see 215[this document](https://docs.cider.mx/cider/indent_spec.html). 216The only difference is that you're allowed to use lists instead of vectors. 217 218### Vertical alignment 219 220You can vertically align sexps with `C-c SPC`. For instance, typing 221this combo on the following form: 222 223```clj 224(def my-map 225 {:a-key 1 226 :other-key 2}) 227``` 228 229Leads to the following: 230 231```clj 232(def my-map 233 {:a-key 1 234 :other-key 2}) 235``` 236 237This can also be done automatically (as part of indentation) by 238turning on `clojure-align-forms-automatically`. This way it will 239happen whenever you select some code and hit `TAB`. 240 241## Refactoring support 242 243The available refactorings were originally created and maintained by the 244`clj-refactor.el` team. The ones implemented in Elisp only are gradually migrated 245to `clojure-mode`. 246 247### Threading macros related features 248 249`clojure-thread`: Thread another form into the surrounding thread. Both `->>` 250and `->` variants are supported. 251 252<img width="512" src="/doc/clojure-thread.gif"> 253 254`clojure-unwind`: Unwind a threaded expression. Supports both `->>` and `->`. 255 256<img width="512" src="/doc/clojure-unwind.gif"> 257 258`clojure-thread-first-all`: Introduce the thread first macro (`->`) and rewrite 259the entire form. With a prefix argument do not thread the last form. 260 261<img width="512" src="/doc/clojure-thread-first-all.gif"> 262 263`clojure-thread-last-all`: Introduce the thread last macro and rewrite the 264entire form. With a prefix argument do not thread the last form. 265 266<img width="512" src="/doc/clojure-thread-last-all.gif"> 267 268`clojure-unwind-all`: Fully unwind a threaded expression removing the threading 269macro. 270 271<img width="512" src="/doc/clojure-unwind-all.gif"> 272 273### Cycling things 274 275`clojure-cycle-privacy`: Cycle privacy of `def`s or `defn`s. Use metadata 276explicitly with setting `clojure-use-metadata-for-privacy` to `t` for `defn`s 277too. 278 279<img width="512" src="/doc/clojure-cycle-privacy.gif"> 280 281`clojure-cycle-not`: Add or remove a `not` form around the current form. 282 283<img width="512" src="/doc/clojure-cycle-not.gif"> 284 285`clojure-cycle-when`: Find the closest `when` or `when-not` up the syntax tree 286and toggle it. 287 288<img width="512" src="/doc/clojure-cycle-when.gif"> 289 290`clojure-cycle-if`: Find the closest `if` or `if-not` up the syntax tree and 291toggle it. Also transpose the `else` and `then` branches, keeping the semantics 292the same as before. 293 294<img width="512" src="/doc/clojure-cycle-if.gif"> 295 296### Convert collection 297 298Convert any given collection at point to list, quoted list, map, vector or set. 299 300### Let expression 301 302`clojure-introduce-let`: Introduce a new `let` form. Put the current form into 303its binding form with a name provided by the user as a bound name. If called 304with a numeric prefix put the let form Nth level up in the form hierarchy. 305 306<img width="512" src="/doc/clojure-introduce-let.gif"> 307 308`clojure-move-to-let`: Move the current form to the closest `let`'s binding 309form. Replace all occurrences of the form in the body of the let. 310 311<img width="512" src="/doc/clojure-move-to-let.gif"> 312 313`clojure-let-forward-slurp-sexp`: Slurp the next form after the `let` into the 314`let`. Replace all occurrences of the bound forms in the form added to the `let` 315form. If called with a prefix argument slurp the next n forms. 316 317<img width="512" src="/doc/clojure-let-forward-slurp-sexp.gif"> 318 319`clojure-let-backward-slurp-sexp`: Slurp the form before the `let` into the 320`let`. Replace all occurrences of the bound forms in the form added to the `let` 321form. If called with a prefix argument slurp the previous n forms. 322 323<img width="512" src="/doc/clojure-let-backward-slurp-sexp.gif"> 324 325`paredit-convolute-sexp` is advised to replace occurrences of bound forms with their bound names when convolute is used on a let form. 326 327### Rename ns alias 328 329`clojure-rename-ns-alias`: Rename an alias inside a namespace declaration. 330 331<img width="512" src="/doc/clojure-rename-ns-alias.gif"> 332 333### Add arity to a function 334 335`clojure-add-arity`: Add a new arity to an existing single-arity or multi-arity function. 336 337<img width="512" src="/doc/clojure-add-arity.gif"> 338 339## Related packages 340 341* [clojure-mode-extra-font-locking][] provides additional font-locking 342for built-in methods and macros. The font-locking is pretty 343imprecise, because it doesn't take namespaces into account and it 344won't font-lock a function at all possible positions in a sexp, but 345if you don't mind its imperfections you can easily enable it: 346 347```el 348(require 'clojure-mode-extra-font-locking) 349``` 350 351The code in `clojure-mode-font-locking` used to be bundled with 352`clojure-mode` before version 3.0. 353 354You can also use the code in this package as a basis for extending the 355font-locking further (e.g. functions/macros from more 356namespaces). Generally you should avoid adding special font-locking 357for things that don't have fairly unique names, as this will result in 358plenty of incorrect font-locking. CIDER users should avoid this package, 359as CIDER does its own dynamic font-locking, which is namespace-aware 360and doesn't produce almost any false positives. 361 362* [clj-refactor][] provides refactoring support. 363 364* Enabling `CamelCase` support for editing commands(like 365`forward-word`, `backward-word`, etc) in `clojure-mode` is quite 366useful since we often have to deal with Java class and method 367names. The built-in Emacs minor mode `subword-mode` provides such 368functionality: 369 370```el 371(add-hook 'clojure-mode-hook #'subword-mode) 372``` 373 374* The use of [paredit][] when editing Clojure (or any other Lisp) code 375is highly recommended. It helps ensure the structure of your forms is 376not compromised and offers a number of operations that work on code 377structure at a higher level than just characters and words. To enable 378it for Clojure buffers: 379 380```el 381(add-hook 'clojure-mode-hook #'paredit-mode) 382``` 383 384* [smartparens][] is an excellent 385 (newer) alternative to paredit. Many Clojure hackers have adopted it 386 recently and you might want to give it a try as well. To enable 387 `smartparens` use the following code: 388 389```el 390(add-hook 'clojure-mode-hook #'smartparens-strict-mode) 391``` 392 393* [RainbowDelimiters][] is a 394 minor mode which highlights parentheses, brackets, and braces 395 according to their depth. Each successive level is highlighted in a 396 different color. This makes it easy to spot matching delimiters, 397 orient yourself in the code, and tell which statements are at a 398 given depth. Assuming you've already installed `RainbowDelimiters` you can 399 enable it like this: 400 401```el 402(add-hook 'clojure-mode-hook #'rainbow-delimiters-mode) 403``` 404 405* [aggressive-indent-mode][] automatically adjust the indentation of your code, 406while you're writing it. Using it together with `clojure-mode` is highly 407recommended. Provided you've already installed `aggressive-indent-mode` you can 408enable it like this: 409 410```el 411(add-hook 'clojure-mode-hook #'aggressive-indent-mode) 412``` 413 414## REPL Interaction 415 416One of the fundamental aspects of Lisps in general, and Clojure in 417particular, is the notion of interactive programming - building your 418programs by continuously changing the state of the running Lisp 419program (as opposed to doing something more traditional like making a 420change and re-running the program afterwards to see the changes in 421action). To get the most of clojure-mode you'll have to combine it 422with some tool which will allow you to interact with your Clojure program 423(a.k.a. process/REPL). 424 425A number of options exist for connecting to a 426running Clojure process and evaluating code interactively. 427 428### Basic REPL 429 430[inf-clojure][] provides basic interaction with a Clojure REPL process. 431It's very similar in nature and supported functionality to `inferior-lisp-mode` 432for Common Lisp. 433 434### CIDER 435 436[CIDER][] is a powerful Clojure interactive development environment, 437similar to SLIME for Common Lisp. 438 439If you're into Clojure and Emacs you should definitely check it out. 440 441## Changelog 442 443An extensive changelog is available [here](CHANGELOG.md). 444 445## License 446 447Copyright © 2007-2019 Jeffrey Chu, Lennart Staflin, Phil Hagelberg, Bozhidar 448Batsov, Artur Malabarba and [contributors][]. 449 450Distributed under the GNU General Public License; type <kbd>C-h C-c</kbd> to view it. 451 452[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg 453[melpa-badge]: http://melpa.org/packages/clojure-mode-badge.svg 454[melpa-stable-badge]: http://stable.melpa.org/packages/clojure-mode-badge.svg 455[melpa-package]: http://melpa.org/#/clojure-mode 456[melpa-stable-package]: http://stable.melpa.org/#/clojure-mode 457[COPYING]: http://www.gnu.org/copyleft/gpl.html 458[badge-circleci]: https://circleci.com/gh/clojure-emacs/clojure-mode.svg?style=svg 459[circleci]: https://circleci.com/gh/clojure-emacs/clojure-mode 460[CIDER]: https://github.com/clojure-emacs/cider 461[cider-nrepl]: https://github.com/clojure-emacs/cider-nrepl 462[inf-clojure]: https://github.com/clojure-emacs/inf-clojure 463[contributors]: https://github.com/clojure-emacs/clojure-mode/contributors 464[melpa]: http://melpa.org 465[melpa stable]: http://stable.melpa.org 466[clojure-mode-extra-font-locking]: https://github.com/clojure-emacs/clojure-mode/blob/master/clojure-mode-extra-font-locking.el 467[clj-refactor]: https://github.com/clojure-emacs/clj-refactor.el 468[paredit]: http://mumble.net/~campbell/emacs/paredit.html 469[smartparens]: https://github.com/Fuco1/smartparens 470[RainbowDelimiters]: https://github.com/Fanael/rainbow-delimiters 471[aggressive-indent-mode]: https://github.com/Malabarba/aggressive-indent-mode 472