NonGNU-devel ELPA - ws-butler

ws-butler -- an unobtrusive way to trim whitespace

1. Only lines edited get meaningless whitespace trimmed (e.g. end-of-line).
2. Trimming only happens when saving.

What does unobtrusive mean?

"Unobtrusive" is doing double duty here.

1. ws-butler is keeping frivolous whitespace at bay in the background.
   • The user doesn't enable show-trailing-whitespace, seeing whitespace is wasted mental energy.
2. In a cooperative environment, the user is considerate of other people's time by not making PRs that contain meaningless whitespace change.

Not moving point because of space deletion.

By default, ws-butler preserves "virtual spaces" in front of point if necessary. The file on disk is cleaned up however.

This can be disabled with ws-butler-keep-whitespace-before-point.

Trimming only specific lines.

There might be lines you don't want to get trimmed, e.g. spaces in multi-line strings. The behavior can be customized through ws-butler-trim-predicate. This variable should hold a function that expects 2 arguments (region beginning and end) and should return true only for regions that one wants to get trimmed. As an example

(setq ws-butler-trim-predicate
      (lambda (beg end)
        (not (eq 'font-lock-string-face
                 (get-text-property end 'face)))))

Installation

use-package configuration

(use-package ws-butler :ensure t :hook (prog-mode . ws-butler-mode))

Manual Configuration

To use ws-butler, require it and add ws-butler-mode as a hook on any mode where you would like it to be enabled. For example, to enable for all programming language modes, add this to your .emacs:

(require 'ws-butler)
(add-hook 'prog-mode-hook #'ws-butler-mode)

Global mode

Alternatively, you can use ws-butler-global-mode to turn it on everywhere.

Debian 9 or later or Ubuntu 16.10 or later

apt-get install elpa-ws-butler

History

1. I started by trimming all spaces at EOL in source code in a "write-file-hook" when I started programming. It seemed like a great idea.

2. Then I got a job working on a code base where no one else trimmed spaces, so my commits became super noisy. I wanted to stop being the "white space" police, so switched to ws-trim.

   • ws-trim works in a post-command-hook and trims white space while you edit.
   • This was too eager for me. For example, I would stop and scroll away to look at some code, and when I get back to continue, my indentation is gone.
   • It caused some problems with other customizations which also rely on post-command-hook.

3. I started experimenting with using highlight-changes-mode to trim only lines I touch on save.

4. Now, the dependency on highlight-changes-mode has been removed and we handle change changing through text properties ourselves.

Ver 1.3 2025/03/10 Sean Whitton
    Replace a use of `always' to retain compatibility with older Emacs.
    Thanks to Chris Rayner for the reporting the problem.

Ver 1.2 2025/02/25 Sean Whitton
    When `special-mode' is in `ws-butler-global-exempt-modes', also check
    whether a mode has a `mode-class' of `special', and don't activate
    `ws-butler-mode' if it does.
    Remove entries from `ws-butler-global-exempt-modes' that the preceding
    changes renders redundant.
    Exempt `org-agenda-mode' from `ws-butler-global-mode' by default.

Ver 1.1 2025/02/21 Sean Whitton
    Exempt `compilation-mode' from `ws-butler-global-mode' by default.
    Clarify docstring of `ws-butler-global-exempt-modes'.

Ver 1.0 2025/02/18 Sean Whitton
    Take over maintenance; maintain out of nongnu-elpa.git.
    Bump to version 1.0: core functionality not expected to change.
    Move customisation group from `convenience' to `text'.
    Rewrite docstrings.
    Fix accidental change `point-at-bol'->`line-end-position'.
    Exempt `message-mode' from `ws-butler-global-mode' by default.
    Other tidying.