doomemacs/modules/editor/format

:editor format

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • With +onsave
  • Without +onsave
• Configuration
  • Selecting or disabling a specific formatter
  • One-off save-buffer without auto-formatting
  • Using lsp-mode or eglot's formatter
• Troubleshooting
• Frequently asked questions
• Appendix

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

• @elken

Become a maintainer?

Module flags

+onsave

Enable reformatting of a buffer when it is saved. See var:+format-on-save-disabled-modes to disable format on save for certain major modes.

+lsp

Use lsp-mode's or eglot's formatters, instead of Apheleia's, if the active client has the capabilities.

Packages

• doom-package:apheleia

Hacks

• Apheleia – and many formatters – don't support partial formatting (i.e. the opposite of whole-file formatting), so a couple of hacks are in place to force them to support this when you run fn:+format/region. This works by copying the selection into a fake, standalone file and operating on that. This works in many cases, but makes no guarantees that it will work with all formatters. Lisp, Scheme, Python, or similarly indentation-based languages are most likely to see strange results.
• fn:save-buffer is advised to suppress format-on-save behavior if passed the universal argument (e.g. kbd:SPC u SPC b s or kbd:C-u C-x C-s).

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 +format/buffer or apheleia-format-buffer is called. The difference between them is +format/buffer will use a LSP server if configured and available.

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.

Selecting or disabling a specific formatter

Doom exposes a couple variables and functions to help you configure this module's behavior:

var:+format-with

What formatter(s) to use for the current buffer.

var:+format-inhibit

If non-nil, formatting-on-save behavior is disabled, regardless of apehelia-global-mode.

var:+format-on-save-disabled-modes

A list of major modes to disable format-on-save behavior in. These buffers can still be formatted by calling the +format/buffer or +format/region commands, manually.

fn:set-formatter!

A helper function for configuring registered formatters (or adding some of your own) and assigning them to major modes.

Here are some ways to use them:

1. In a project's .dir-locals.el file:

   ((js2-mode    . (+format-with . lsp))
    (python-mode . (+format-with . (isort black)))
   
    ;; If +format-inhibit is non-nil, formatting-on-save behavior will be
    ;; disabled, regardless of apheleia-global-mode.
    (rustic-mode . (+format-inhibit . t)))

2. With a file-local variable. E.g. At the top of a file:

   // -*- +format-with: prettier -*-
   

   Or at the bottom of a file

   # Local Variables:
   # +format-with: (isort black)
   # End:

3. From your Doom configuration:

   ;;; add to $DOOMDIR/config.el
   (setq-hook! 'python-mode-hook +format-with 'black)
   
   ;; Or set it to `nil' to fallback to Apheleia's default
   (setq-hook! 'python-mode-hook +format-with nil)
   
   ;; Disable format-on-save behavior in Emacs Lisp buffers
   (setq-hook! 'emacs-lisp-mode-hook +format-inhibit t)
   
   ;; To permenantly disable a formatter:
   (after! csharp-mode
     (set-formatter! 'csharpier nil))
   
   ;; To define new formatters:
   ;; From modules/tools/docker/config.el:
   (after! dockerfile-mode
     (set-formatter! 'dockfmt '("dockfmt" "fmt" filepath) :modes '(dockerfile-mode)))
   
   ;; From modules/lang/sh/config.el:
   (after! sh-script
     (set-formatter! 'shfmt '("shfmt" "-ci"
                              (unless indent-tabs-mode
                                (list "-i" (number-to-string tab-width))))))
   
   (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))

Formatters are referred to by the name they were defined with. They can be looked up in the apheleia-mode-alist hash table (with kbd:<help> v).

One-off save-buffer without auto-formatting

To save the buffer without formatting just once, pass the universal argument to save-buffer (SPC u for evil users, C-u for non-evil users). For example:

• Evil: SPC u SPC f s
• Without evil: C-u C-x C-s

Using lsp-mode or eglot's formatter

If you have a buffer open with doom-package:lsp-mode or doom-package:eglot enabled, and the running server supports textDocument/formatting or textDocument/rangeFormatting, it can be used instead of doom-package:apheleia's (or Doom's) default formatters by enabling this module with its +lsp flag or manually activating the fn:+format-with-lsp-mode minor mode (though it's a better idea to use fn:+format-with-lsp-toggle-h if you're looking for a function to use with mode hooks; this function will respect pre-existing modifications to var:+format-with).

To enable this formatter selectively, see the next section.

Troubleshooting

There are a few fail-safes doom-package: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 issues.

If any errors are reported from the command, run apheleia-goto-error to jump to the error buffer and handle any problems raised.

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?