Need help with reformatter.el?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

purcell
142 Stars 11 Forks 57 Commits 9 Opened issues

Description

Define commands which run reformatters on the current Emacs buffer

Services available

!
?

Need anything else?

Contributors list

No Data

Melpa Status Melpa Stable Status Build Status Support me

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.

By default, reformatter.el expects programs to read from stdin and write to stdout, and you should prefer this mode of operation where possible. If this isn't possible with your particular formatting program, refer to the options for

reformatter-define
, and see the examples in the package's tests.

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
dhall-format-buffer
and
dhall-format-region
interactive commands, 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-buffer "current-file" nil t)
;;;###autoload (autoload 'dhall-format-region "current-file" nil t)
;;;###autoload (autoload 'dhall-format-on-save-mode "current-file" nil t)

Examples of usage in the wild

To find reverse dependencies, look for "Needed by" on the MELPA page for reformatter. Here are some specific examples:

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.

FAQ

How is this different from format-all.el?

format-all
is a very different approach: it aims to provide a single minor mode which you then enable and configure to do the right thing (including nothing) for all the languages you use. It even tries to tell you how to install missing programs. It's an interesting project, but IMO it's hard to design the configuration for such a grand unified approach, and it can get complex. For example, you'd have to be able to configure which of two possible reformatters you want to use for a specific language, and to be able to do that on a per-project basis.

In contrast reformatter produces small, self-contained and separate formatters and minor modes which all work consistently and are individually configured. It makes it possible to replace existing formatter code, and it's also very convenient for users to define their own ad-hoc reformatter wrappers

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.

About

Author: Steve Purcell

Homepage: https://github.com/purcell/reformatter.el


💝 Support this project and my other Open Source work

💼 LinkedIn profile

✍ sanityinc.com

🐦 @sanityinc

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.