doom-emacs/modules/editor/format

:editor format

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
• Configuration
  • Automatic reformatting when saving buffers
  • Disabling the LSP formatter
  • Defining your own formatters
  • Selecting a specific formatter for a particular buffer
• Troubleshooting
• Frequently asked questions
• Appendix

← Back to module index ! Issues ↖ Github ± Suggest edits ? Help

---

🔨 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   unfold

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. Become a maintainer?

Module flags

+onsave

Enable reformatting of a buffer when it is saved. See +format-on-save-enabled-modes to control what major modes to (or not to) format on save.

Packages

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

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has no direct requirements, but each language will need one of their supported formatter programs in order for this to work. In their absence, format-all will fail silently.

Supported formatters:

• 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 Usage

🔨 This module has no usage documentation yet. Write some?

TODO Configuration

🔨 This module's configuration documentation is incomplete. Complete it?

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.

Troubleshooting

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

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

🔨 This module has no appendix yet. Write one?