From d41df5f2c22a55bf9634786206ce51dedd2929c6 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sat, 25 Jul 2020 23:24:38 -0400 Subject: [PATCH] editor/format: add README #1166 --- modules/editor/format/README.org | 174 +++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 modules/editor/format/README.org diff --git a/modules/editor/format/README.org b/modules/editor/format/README.org new file mode 100644 index 000000000..95569c4a9 --- /dev/null +++ b/modules/editor/format/README.org @@ -0,0 +1,174 @@ +#+TITLE: editor/format +#+DATE: July 25, 2020 +#+SINCE: v3.0.0 +#+STARTUP: inlineimages nofold + +#+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 + +* Table of Contents :TOC_3:noexport: +- [[#description][Description]] + - [[#maintainers][Maintainers]] + - [[#module-flags][Module Flags]] + - [[#plugins][Plugins]] + - [[#hacks][Hacks]] +- [[#prerequisites][Prerequisites]] +- [[#features][Features]] +- [[#configuration][Configuration]] + - [[#automatic-reformatting-when-saving-buffers][Automatic reformatting when saving buffers]] + - [[#disabling-the-lsp-formatter][Disabling the LSP formatter]] + - [[#defining-your-own-formatters][Defining your own formatters]] + - [[#selecting-a-specific-formatter-for-a-particular-buffer][Selecting a specific formatter for a particular buffer]] +- [[#troubleshooting][Troubleshooting]] + +* Description +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. + +** 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 ++ [[https://github.com/lassik/emacs-format-all-the-code][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 +# An in-depth list of features, how to use them, and their dependencies. + +* 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: +#+BEGIN_SRC elisp +(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 =+onsave= is disabled before you try this: + +#+BEGIN_SRC elisp +(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 =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 elisp +(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 +# Common issues and their solution, or places to look for help.