editor/format: add README #1166
This commit is contained in:
Henrik Lissner
parent
4b96039374
commit
d41df5f2c2
1 changed files with 174 additions and 0 deletions
174
modules/editor/format/README.org
Normal file
174
modules/editor/format/README.org
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue