5.7 KiB
:editor format
Description unfold
Code style is something that's hotly debated since the beginning of time.
Tabs or spaces? 2-width or 4-width indentation?
Which is right? Doom doesn't care, but we will try and make it easy for you to format code within the safety of Emacs.
At present, the module wraps apheleia, which includes some more detail on the internals of the package; but the long and short of it is on-save your code will be formatted and returned to the buffer using RCS patching.
Maintainers
Module flags
- +onsave
- Enable reformatting of a buffer when it is saved. See var:+format-on-save-disabled-modes to control what major modes to (or not to) format on save.
Packages
Hacks
As of writing this, apheleia doesn't yet support regions or similar kinds of buffers, so there are a couple of hacks to attempt to rectify this.
For the most part, things should work as expected. However, because the formatting occurs on an isolated version of the buffer; lisp/scheme or similarly indentation-based languages may produce poor results.
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, doom-package:apheleia will fail silently.
To see if a particular mode has a configured formatter, check for the mode in var:apheleia-mode-alist which corresponds to the list of formatters defined in var:apheleia-formatters
Usage
With +onsave
When this flag is enabled, you shouldn't need to do anything other than write code and save it.
Without +onsave
Without the flag, formatting will only occur when either apheleia-format-buffer
or +format/buffer is called.
Configuration
Detailed configuration can be found upstream, but for most purposes here we provide a simple macro that looks like the below:
(set-formatter! 'unique-name '("command" "line" "here") :modes '(name-of-major-mode))
If you're trying to override a formatter that has previously been defined by
Doom, you will need to ensure that the call in your config is contained within
an after! form, eg below to override Clojure's with zprint:
(after! clojure-mode
(set-formatter! 'zprint '("zprint" "-") :modes '(clojure-mode)))
There are a few bonus symbols that apheleia uses (for example npx will be
replaced by a correct path to npx) which are all documented in the link above.
Disabling formatters
Permanently
To permanently disable a particular formatter with no provided alternative
(setq apheleia-formatters (delq (assoc 'csharpier apheleia-formatters) apheleia-formatters))Per-buffer
If you want to save without formatting, this is done by first passing the
universal argument thus; SPC u SPC f s for evil users, C-u C-x C-s for non-evil
users.
If you want to save more than a handful of time, you can set
var:apheleia-inhibit to disable even if apheleia-global-mode is on.
Onsave only
This behaviour is controlled via var:+format-on-save-disabled-modes thus;
(setq +format-on-save-disabled-modes
'(emacs-lisp-mode ; elisp's mechanisms are good enough
sql-mode ; sqlformat is currently broken
tex-mode ; latexindent is broken
latex-mode))
In this case, emacs-lisp-mode, sql-mode, tex-mode and latex-mode will not be
formatted on save, but can still be formatted by manually invoking the commands
apheleia-format-buffer or +format/buffer.
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)
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.
;; Overrides `apheleia-mode-alist`
(setq-hook! 'python-mode-hook +format-with 'html-tidy)
;; Or set it to `nil' to fallback to `apheleia-mode-alist`
(setq-hook! 'python-mode-hook +format-with nil)
Formatters are referred to by the name they were defined with. They can be
looked up in the apheleia-mode-alist hash table.
Troubleshooting
There are a few fail-safes apheleia has to prevent accidental code wipe, included silently failing if the command errors or doesn't exist.
Check that the command you've specified runs fine in a terminal first before reporting this as an issue.
If any errors are reported from the command, run apheleia-goto-error to jump to
the error buffer and handle any problems raised there.
Any issues specific to apheleia should most often be reported upstream here.
Frequently asked questions
This module has no FAQs yet. Ask one?
TODO Appendix
This module has no appendix yet. Write one?