doomemacs/modules/editor/format/README.org

#+title:    :editor format
#+subtitle: Standardize your ugly code
#+created:  July 26, 2020
#+since:    21.12.0

#+begin_quote
 🔨 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 [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]].
#+end_quote

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

#+begin_quote
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
#+end_quote

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +onsave ::
  Enable reformatting of a buffer when it is saved. See
  [[var:][+format-on-save-enabled-modes]] to control what major modes to (or not to)
  format on save.

** Packages
- [[doom-package:][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 [[fn:][+format/buffer]] or [[fn:][+format/region]] (i.e.
    removes the major-mode lock on formatters).

** 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 has no direct requirements, but each language will need one of their
supported formatter programs in order for this to work. In their absence,
[[doom-package:][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
#+begin_quote
 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** 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:
#+begin_src emacs-lisp
(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))
#+end_src

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 [[doom-module:][+onsave]] is disabled before you try this:
#+begin_src emacs-lisp
(add-hook 'python-mode-hook #'format-all-mode)
(add-hook 'js2-mode-hook #'format-all-mode)
#+end_src

** 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 [[doom-package:][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.
#+begin_src emacs-lisp
(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)
#+end_src

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 [[https://github.com/lassik/emacs-format-all-the-code/blob/master/format-all.el#L512][source
code]].

* 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