editor/format

Description
Prerequisites
Features
Configuration
Troubleshooting

This module has been scheduled for a rewrite. Its documentation will remain incomplete and edge cases left unpatched in the meantime. A preview of this rewrite can be found in my private config.

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, fish_indent, 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

Maintainers

This module has no dedicated maintainers.

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.

Plugins

format-all

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).

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)

TODO Features

Configuration

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)

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)

TODO Defining your own formatters

See the set-formatter! function.

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.

6 KiB Raw Blame History