README.md

Define commands which run reformatters on the current Emacs buffer

This library lets elisp authors easily define an idiomatic command to reformat the current buffer using a command-line program, together with an optional minor mode which can apply this command automatically on save.

In its initial release it supports only reformatters which can read from stdin and write to stdout, but a more versatile interface will be provided as development continues.

As an example, let's define a reformat command that applies the "dhall format" command. We'll assume here that we've already defined a variable dhall-command which holds the string name or path of the dhall executable:

(reformatter-define dhall-format
  :program dhall-command
  :args '("format")
  :lighter 'DF)

The reformatter-define macro expands to code which generates both a dhall-format interactive command and a local minor mode called dhall-format-on-save-mode. The :args and :program expressions will be evaluated at runtime, so they can refer to variables that may (later) have a buffer-local value. A custom variable will be generated for the mode lighter, with the supplied value becoming the default.

The generated minor mode allows idiomatic per-directory or per-file customisation, via the "modes" support baked into Emacs' file-local and directory-local variables mechanisms. For example, users of the above example might add the following to a project-specific .dir-locals.el file:

((dhall-mode
   (mode . dhall-format-on-save)))

See the documentation for reformatter-define, which provides a number of options for customising the generated code.

Library authors might like to provide autoloads for the generated code, e.g.:

;;;###autoload (autoload 'dhall-format "current-file" nil t)
;;;###autoload (autoload 'dhall-format-on-save-mode "current-file" nil t)

Examples of usage in the wild

dhall-mode.el
elm-format.el, in elm-mode
Here is a user defining a reformatter in his own configuration

Rationale

I contribute to a number of Emacs programming language modes and tools, and increasingly use code reformatters in my daily work. It's surprisingly difficult to write robust, correct code to apply these reformatters, given that it must consider such issues as:

Missing programs
Buffers not yet saved to a file
Displaying error output
Colorising ANSI escape sequences in any error output
Handling file encodings correctly

With this library, I hope to help the community standardise on best practices, and make things easier for tool authors and end users alike.

Installation

Manual

Ensure reformatter.el is in a directory on your load-path, and add the following to your ~/.emacs or ~/.emacs.d/init.el:

(require 'reformatter)

MELPA

If you're an Emacs 24 user or you have a recent version of package.el you can install reformatter from the MELPA repository. The version of reformatter there will always be up-to-date.

See the command reformatter.