# -*- mode: doom-docs-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