| 1 | This library lets elisp authors easily define an idiomatic command |
| 2 | to reformat the current buffer using a command-line program, |
| 3 | together with an optional minor mode which can apply this command |
| 4 | automatically on save. |
| 5 | |
| 6 | By default, reformatter.el expects programs to read from stdin and |
| 7 | write to stdout, and you should prefer this mode of operation where |
| 8 | possible. If this isn't possible with your particular formatting |
| 9 | program, refer to the options for `reformatter-define', and see the |
| 10 | examples in the package's tests. |
| 11 | |
| 12 | As an example, let's define a reformat command that applies the |
| 13 | "dhall format" command. We'll assume here that we've already defined a |
| 14 | variable `dhall-command' which holds the string name or path of the |
| 15 | dhall executable: |
| 16 | |
| 17 | (reformatter-define dhall-format |
| 18 | :program dhall-command |
| 19 | :args '("format")) |
| 20 | |
| 21 | The `reformatter-define' macro expands to code which generates |
| 22 | `dhall-format-buffer' and `dhall-format-region' interactive |
| 23 | commands, and a local minor mode called |
| 24 | `dhall-format-on-save-mode'. The :args" and :program expressions |
| 25 | will be evaluated at runtime, so they can refer to variables that |
| 26 | may (later) have a buffer-local value. A custom variable will be |
| 27 | generated for the mode lighter, with the supplied value becoming |
| 28 | the default. |
| 29 | |
| 30 | The generated minor mode allows idiomatic per-directory or per-file |
| 31 | customisation, via the "modes" support baked into Emacs' file-local |
| 32 | and directory-local variables mechanisms. For example, users of |
| 33 | the above example might add the following to a project-specific |
| 34 | .dir-locals.el file: |
| 35 | |
| 36 | ((dhall-mode |
| 37 | (mode . dhall-format-on-save))) |
| 38 | |
| 39 | See the documentation for `reformatter-define', which provides a |
| 40 | number of options for customising the generated code. |
| 41 | |
| 42 | Library authors might like to provide autoloads for the generated |
| 43 | code, e.g.: |
| 44 | |
| 45 | ;;;###autoload (autoload 'dhall-format-buffer "current-file" nil t) |
| 46 | ;;;###autoload (autoload 'dhall-format-region "current-file" nil t) |
| 47 | ;;;###autoload (autoload 'dhall-format-on-save-mode "current-file" nil t) |