:editor format

Automated prettiness

This module will be rewritten soon. Most development efforts on it have been halted until it finished.

1. Description

This module integrates code formatters into Emacs. Here are some of the formatters that it currently supports:

asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt, dhall format, dockfmt, elm-format, emacs, fishindent, fprettify, gleam format, gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo, rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

+onsave
Preform buffer-wide reformatting of a buffer when you save it. See +format-on-save-enabled-modes to control what major modes to (or not to) format on save.

1.4. Hacks

  • format-all has been heavily modified to suit Doom’s goals for this module:
    • Reformatted text is applied to the buffer by RCS patch, as to reduce its affect on cursor position.
    • Adds partial formatting, i.e. you can now reformat a subset of the buffer.
    • Adds the ability to use any arbitrary formatter on the current buffer if you pass the universal argument to +format/buffer or +format/region (i.e. removes the major-mode lock on formatters).

2. Prerequisites

This module depends on external programs to perform the actual formatting. These will need to be installed for them to work. In their absence, format-all will fail silently.

  • Angular/Vue (prettier)
  • Assembly (asmfmt)
  • Bazel Starlark (buildifier)
  • BibTeX (emacs)
  • C/C++/Objective-C (clang-format)
  • Cabal (cabal-fmt)
  • Clojure/ClojureScript (node-cljfmt)
  • CMake (cmake-format)
  • Crystal (crystal tool format)
  • CSS/Less/SCSS (prettier)
  • D (dfmt)
  • Dart (dartfmt)
  • Dhall (dhall format)
  • Dockerfile (dockfmt)
  • Elixir (mix format)
  • Elm (elm-format)
  • Emacs Lisp (emacs)
  • Fish Shell (fish_indent)
  • Fortran 90 (fprettify)
  • Gleam (gleam format)
  • Go (gofmt)
  • GraphQL (prettier)
  • Haskell (brittany)
  • HTML/XHTML/XML (tidy)
  • Java (clang-format)
  • JavaScript/JSON/JSX (prettier)
  • Jsonnet (jsonnetfmt)
  • Kotlin (ktlint)
  • LaTeX (latexindent)
  • Ledger (ledger-mode)
  • Lua (lua-fmt)
  • Markdown (prettier)
  • Nix (nixfmt)
  • OCaml (ocp-indent)
  • Perl (perltidy)
  • PHP (prettier plugin-php)
  • Protocol Buffers (clang-format)
  • PureScript (purty)
  • Python (black)
  • R (styler)
  • Ruby (rufo)
  • Rust (rustfmt)
  • Scala (scalafmt)
  • Shell script (shfmt)
  • Snakemake (snakefmt)
  • Solidity (prettier-plugin-solidity)
  • SQL (sqlformat)
  • Swift (swiftformat)
  • Terraform (terraform fmt)
  • TOML (prettier-plugin-toml)
  • TypeScript/TSX (prettier)
  • Verilog (iStyle)
  • YAML (prettier)

3. TODO Usage

This module has no usage documentation yet. Write some?

4. TODO Configuration

This module’s configuration documentation is incomplete. Complete it?

4.1. Automatic reformatting when saving buffers

There are two ways to achieve this. Either through the +onsave flag, or by adding format-all-mode to the hook of each major mode you want this behavior enabled in.

If you choose the former, what modes it applies to can be changed by modifying +format-on-save-enabled-modes, which contains a list of major modes. If the first item in the list is the symbol not, the list is negated. This is its default value:

# ⎘
(setq +format-on-save-enabled-modes
      '(not emacs-lisp-mode  ; elisp's mechanisms are good enough
	    sql-mode         ; sqlformat is currently broken
	    tex-mode         ; latexindent is broken
	    latex-mode))

If you want to format code when you save a buffer, but want more granular control over which major modes this behavior is enabled in, there is an alternative. Make sure +onsave is disabled before you try this:

# ⎘
(add-hook 'python-mode-hook #'format-all-mode)
(add-hook 'js2-mode-hook #'format-all-mode)

4.2. Disabling the LSP formatter

If you are in a buffer with lsp-mode enabled and a server that supports textDocument/formatting, it will be used instead of format-all’s formatter.

  • To disable this behavior universally use: (setq +format-with-lsp nil)
  • To disable this behavior in one mode: (setq-hook! 'python-mode-hook +format-with-lsp nil)

4.3. TODO Defining your own formatters

See the set-formatter! function.

4.4. TODO Selecting a specific formatter for a particular buffer

Set the buffer-local variable +format-with to the name of the formatter to use. e.g.

# ⎘
(setq-hook! 'python-mode-hook +format-with 'html-tidy)

;; Or set it to `:none' to disable formatting
(setq-hook! 'python-mode-hook +format-with :none)

Formatters are referred to by the name they were defined with. They can be looked up in the format-all-mode-table hash table or in format-all’s source code.

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?