clang-format+

Description

clang-format+ is a small package aimed at improving the user experience of using clang-format in Emacs.

The existing package (clang-format.el) provides a wrapper around the CLI allowing its users to format buffers and regions. The workflow it suggests is a bit too manual, so custom before-save-hooks and then minor-modes come to play. clang-format+ joins all these customizations in order to remove all the duplicated ad-hocs.

clang-format+ defines a minor mode clang-format+-mode, which applies clang-format on save. It can also apply clang-format to the modified parts of the region only and try to be smart about it.

Installation

Install from MELPA

You can install clang-format+ from MELPA by simply executing the following command:

M-x package-install [RET] clang-format+ [RET]

Install using Quelpa

Quelpa gives you an ability to install Emacs packages directly from remote git repos. I recommend using it with quelpa-use-package if you already use use-package.

Here how it's done:

(use-package clang-format+
  :quelpa (clang-format+
           :fetcher github
           :repo "SavchenkoValeriy/emacs-clang-format-plus"))

Install manually

First, install clang-format.el either from MELPA:

M-x package-install [RET] clang-format [RET]

or manually.

After that you should clone this repo and add the following code to you init.el file:

(use-package clang-format+
  :load-path "<path/to/my/cloned/clang-format+/directory>")

Setting up a hook

You can use clang-format+ for all C/C++ projects you edit:

(add-hook 'c-mode-common-hook #'clang-format+-mode)

This will enable automatic formatting of C/C++ files in source trees with a .clang-format (or _clang-format) file, or all C/C++ files if the variable clang-format-style is set to something else than "file". You can set clang-format+-always-enable to t to force formatting; then the default LLVM style will be used if not specified otherwise.

Project-level hook

If you don't want to enable formatting for all projects with a .clang-format/_clang-format file, you can do it selectively by adding a .dir-locals.el file in the root directory of your project with the following code inside:

((c++-mode . ((mode . clang-format+))))

Customization

clang-format+ defines these variables that the user can tweak:

clang-format+-context defines how much context to reformat after modifications. Possible values:
- 'buffer: Reformat the whole buffer.
- 'definition: Reformat the enclosing definition (class/function/etc., but not namespace). This is the default.
- 'modification: Reformat only the modified parts.
clang-format+-offset-modified-region defines the number of extra lines to reformat outside of a modified region both before and after (0 by default). If clang-format+-context is 'definition', the region will only be extended for modifications outside of definitions.
clang-format+-always-enable defines whether to enable formatting even if a style hasn't been selected. If clang-format+-always-enable is nil (which is the default), formatting will be enabled if there is a .clang-format/_clang-format file in the source tree or if clang-format-style is set to something else than "file". If non-nil, formatting will always be enabled.

Contribute

All contributions are most welcome!

It might include any help: bug reports, questions on how to use it, feature suggestions, and documentation updates.

Tributes

Many thanks to the authors of clang-format.

clang-format+ is pretty much a direct clone of the ws-butler package in the way it tracks changes, which in its turn copies this mechanism from highlight-changes-mode (probably we should make a mode that will be used as a base for all other modes). Please, check out those nice modes as well.

License

GPL-3.0