Protesilaos

Change Log of pulsar (pulsar.el)

The newest release is at the top. For further details, please consult the manual: https://protesilaos.com/emacs/pulsar.

Version 1.4.0 on 2026-07-22

This version fixes a few bugs and brings quality-of-life improvements to an already stable package.

Correctly pulse the full line even in M-x shell and related

In certain buffers, we cannot use regular motions to reach a portion of text. This is done by text properties that make the propertized text inaccessible. One use-case is to prevent the user from deleting the shell prompt in M-x shell.

Pulsar is now designed to handle inhibit-field-text-motion correctly so that it works as intended in all relevant cases.

Thanks to Jake Miles for telling me that the shell buffer was not pulsing, which made me investigate the underlying problem. This was done in issue 40: https://github.com/protesilaos/pulsar/issues/40.

The pulsing behaviour of Evil commands is more refined

In short:

  • editing commands should pulse the region, not the entire line;
  • evil-delete-char should not produce a pulse;
  • evil-delete-marks is not an editing command, as it removes invisible marks from the buffer.

Thanks to Steven Allen from modifying the relevant variables in pull request 39: https://github.com/protesilaos/pulsar/pull/39. Steven has assigned copyright to the Free Software Foundation.

Also thanks to Javier Pacheco for adding more Evil-related commands to the list, in pull requests 37 and 38:

The pulsar-face is no longer hardcoded in one case

It is always meant to be a variable, specifically a user option, meaning that we want to use its value as defined by the user.

Thanks to irisjae for reporting the bug in issue 36: https://github.com/protesilaos/pulsar/issues/36.

Pulsing is done correctly on the TTY and other frames

The technicalities are covered in issue 33: https://github.com/protesilaos/pulsar/issues/33. Thanks to the participation of Sébastien Delafond who provided feedback about their Emacs environment and helped me test the snippets I had provided.

In a TTY we cannot use what we normally do, so I arrange for a standard colour to be used instead. My rationale for the choice of colour is this:

  • we are in an environment which does not guarantee accurate colour reproduction;
  • it is almost a given that the frame supports at least 8 colours;
  • of those 8 colours we have black, red, green, yellow, blue, magenta, cyan, white;
  • excluding black and white, the colour that contrasts best against both black and white is red;
  • picking red means we do not need to know the background-mode of the frame, which saves us the extra computations.

The contrast table for the six colours, using Org, where Λ is an alias for modus-themes-contrast:

  #000000 #ffffff
#ff0000 5.25 4.00
#00ff00 15.30 1.37
#0000ff 2.44 8.59
#ffff00 19.56 1.07
#ff00ff 6.70 3.14
#00ffff 16.75 1.25

Pulsing is consistent even when the Emacs daemon is involved

In short, things should work as intended in all sorts of configurations.

Thanks to Koloszár Gergely, Mehrad Mahmoudian, and Nikolaos Bezirgiannis for reporting that the Emacs daemon would produce static highlights instead of pulsing them in and out of effect. This was done in issue 32: https://github.com/protesilaos/pulsar/issues/32.

In this context, also thanks to Gautier Ponsinet for removing an unnecessary let binding. This was sent to me as a patch via email.

The ace-window command is added to the default value of pulsar-pulse-functions

This means that it will produce a pulse effect after it is invoked.

Version 1.3.0 on 2025-11-30

This version introduces a new feature and makes small refinements to an already reliable base.

Permanent static highlight for a line or region

In the most common use-case, Pulsar produces a highlight that fades in and out of view after a certain amount of time. The idea with such a "pulse effect" is to quickly get a sense of where the cursor is when some change occurs (e.g. switching to another window).

The permanent static highlights differ from pulse effects in two ways: (i) they do not have a fade-in and fade-out phase and (ii) are not removed automatically. These highlights stick around either until the user removes them or their underlying text is deleted. They are meant to be used as intentional highlights, such as to draw attention to a certain statement while doing a presentation.

The command pulsar-highlight-permanently adds a permanent static highlight to the current line. When the region is active, the highlight is applied from the beginning to the end of the region.

The command pulsar-highlight-permanently-remove removes permanent static highlights from the active region or current line. This command operates on the entire buffer when it is called with a universal prefix argument (C-u by default).

The command pulsar-highlight-permanently-dwim adds a permanent static highlight if there is none or removes it if there is one. It operates on the currently active region or line at point.

Permanent static highlights are rendered with the face specified in the user option pulsar-highlight-face.

New name for temporary static highlights

The commands pulsar-highlight-dwim and pulsar-highlight-line are obsolete aliases for pulsar-highlight-temporarily.

Temporary static highlights do not have a fade-in and fade-out phase. They are automatically removed as soon as an action occurs. They are an alternative to the aforementioned permanent static highlights.

The command pulsar-highlight-temporarily will operate on the active region or the current line.

Miscellaneous

  • Thanks to Koloszár Gergely for reporting an intermediate bug where the pulse effect actually did not pulse under certain conditions. This was done in issue 31: https://github.com/protesilaos/pulsar/issues/31.
  • Parts of the code are rewritten in the interest of clarity.
  • The entire manual is redone to better organise the documentation.

Version 1.2.0 on 2024-12-12

This version refines an already stable base. Users do not need to make any changes to their setup, unless they wish to try the new features.

Automatically pulse the affected region

With the out-of-the-box settings, Pulsar temporarily highlights the current line after any of the pulsar-pulse-functions is invoked and pulsar-mode (or pulsar-global-mode) is enabled.

The new user option pulsar-pulse-region-functions makes Pulsar temporarily highlight the affected region as well. For example, when pasting some text into the buffer, it will highlight the portion of text that was added.

The default value of pulsar-pulse-region-functions is nil, meaning that no region pulsing is in effect (what we had before). Otherwise, it is a list of functions. A typical use-case is the following: 

(setq pulsar-pulse-region-functions pulsar-pulse-region-common-functions)

This covers common commands, such as for copying and pasting a region of text (restart pulsar-mode or pulsar-global-mode if needed).

Thanks to shipmints and Abdelhak Bougouffa for contributing the core of this functionality. It was done in pull request 25: https://github.com/protesilaos/pulsar/pull/25. Abdelhak's contribution is within the ~15 line limit, meaning that no copyright assignment to the Free Software Foundation is necessary, while shipmints has already done the paperwork.

Relevant discussions took place in issues 10, 18, 21, and 22, as well as pull request 24:

Thanks to Anwesh Gangula, Alex Kreisher, Diego Alvarez, and Ronny Randen for their participation.

The region pulsing is inspired by Daniel Mendler's goggles package, which itself is a take on a common theme covered by many other such packages.

Style region highlights differently

The following user options control the face of the pulsar-pulse-region-functions.

pulsar-region-face
Face to pulse a region that has not changed.
pulsar-region-change-face
Face to pulse a region that has changed (added or removed).

Pulsar defines several faces to get a nice style. Here is an example: 

(setq pulsar-region-face 'pulsar-green) ; unchanged regions are green
(setq pulsar-region-change-face 'pulsar-red) ; changed regions are red

Pulse on window state change

An alternative to how Pulsar works out-of-the-box by reacting to the pulsar-pulse-functions is to check for changes to the window layout. Users who wish to have this behaviour can set the new user option pulsar-pulse-on-window-change to a non-nil value.

As there may be overlap between the pulsar-pulse-functions and the pulsar-pulse-on-window-change, users are advised to pick only one. This is not a hard rule though: Pulsar will blithely highlight everything if configured accordingly.

Thanks again to shipmints and Abdelhak Bougouffa for this contribution. It is part of the aforementioned pull request 25.

Version 1.1.0 on 2024-08-29

This version includes quality-of-life refinements to an already stable package.

Function aliases are recognised automatically

Pulsar will produce a highlight on the current line after one of the functions in pulsar-pulse-functions is used. This now works for aliases of those functions as well, even if they are not explicitly referenced in pulsar-pulse-functions. Whereas before, only the explicitly named functions would produce the pulse effect.

Thanks to shipmints for the contribution, which was originally done in in pull request 12 and then refined over a series of commits: https://github.com/protesilaos/pulsar/pull/12. The author has assigned copyright to the Free Software Foundation.

Users who want to opt out of this behaviour, can set the user option pulsar-resolve-pulse-function-aliases to a nil value.

The next-multiframe-window will produce a pulse by default

This command is added to the pulsar-pulse-functions. It is consistent with what we do with the other-window command.

Thanks to Maxim Dunaevsky for the contribution. This was done in pull request 6: https://github.com/protesilaos/pulsar/pull/6. The change is small, meaning that Maxim does not need to assign copyright to the Free Software Foundation.

More common commands will pulse the current line

I added the following to pulsar-pulse-functions:

  1. evil-goto-first-line
  2. evil-goto-line
  3. evil-scroll-down
  4. evil-scroll-line-to-bottom
  5. evil-scroll-line-to-center
  6. evil-scroll-line-to-top
  7. evil-scroll-up
  8. goto-line
  9. handle-switch-frame
  10. logos-backward-page-dwim
  11. logos-forward-page-dwim
  12. narrow-to-defun
  13. narrow-to-page
  14. narrow-to-region
  15. widen

If you are using setq, setopt, the :custom keyword of use-package, or related, make sure to update the value accordingly. You do not need to do anything if you are doing it with add-to-list.

Pulse a region with pulsar-pulse-region

The command pulsar-pulse-region pulses the active region. Thanks to Bahman Movaqar for the contribution. This was done on the now-deprecated mailing list: https://lists.sr.ht/~protesilaos/pulsar/169317951630.22395.14797122445974295748-0@git.sr.ht

The change is below the ~15 line limit and thus Bahman is not require to assign copyright to the Free Software Foundation.

I still want to make this work with rectangular regions, which are not contiguous (in terms of character positions reading from left to right), but it is tricky. Maybe I will do it for the next version.

Remember that the command pulsar-highlight-dwim will apply a temporary highlight to the active region or the current line. The highlight is removed as soon as another key is pressed.

Version 1.0.0 on 2023-08-12

  • The next-buffer and previous-buffer commands are added to the default value of the user option pulsar-pulse-functions. They will now trigger a pulse effect after they are called (if pulsar-mode is enabled in the current buffer or pulsar-global-mode is in use).
  • The command pulsar-recenter-middle is now an alias for pulsar-recenter-center, instead of being the original name. Users do not need to change anything on their end: this is just an internal arrangement to use a name that corresponds to the one of the underlying "recenter" mechanism.

  • The Lisp macro that was used to derive the Pulsar "recenter" commands has been removed. The commands are pulsar-recenter-top and pulsar-recenter-center. I originally thought the macro would be useful in more places, but I ended up relying on it only twice.

    Thanks to Ryan Kaskel for pointing out an intermediate typo/error I made while redefining the macro and before I decided to remove it altogether. This was done as a comment on the GitHub mirror: https://github.com/protesilaos/pulsar/commit/c5086de779a0226d72eca4d5cba8c7689bc278b2#r123397272.

  • The Lisp macro pulsar-pulse-with-face is renamed to pulsar-define-pulse-with-face. Its definition is updated to simplify how a Pulsar function is defined with a given face. Examples of such functions are pulsar-pulse-line-red, pulsar-pulse-line-blue.
  • Pulsar now retrieves the absolute beginning of the minibuffer prompt. This means that a pulse in the minibuffer will cover the text of the prompt, as opposed to only affecting the input area. As such, the pulse is visible even if the minibuffer is empty (e.g. what happens with the default completion setup when calling M-x).

  • The manual provides instructions on how to set up Pulsar to produce a pulse when the minibuffer is activated. It cannot be done with the pulsar-pulse-functions, though the setup is not too involved. In short: 

      (add-hook 'minibuffer-setup-hook #'pulsar-pulse-line)

  ;; OR something like this, replacing "blue" with one among red,
  ;; green, yellow, magenta, cyan:
  (add-hook 'minibuffer-setup-hook #'pulsar-pulse-line-blue)

Version 0.5.0 on 2022-08-19

  • Added convenience functions/commands to pulse a line using one of the provided faces. These can be used interactively or via Lisp (e.g. be assigned to a hook). They are:
    • pulsar-pulse-line-red
    • pulsar-pulse-line-green
    • pulsar-pulse-line-yellow
    • pulsar-pulse-line-blue
    • pulsar-pulse-line-magenta
    • pulsar-pulse-line-cyan
  • Deprecated pulsar-pulse-on-window-change due to complications it created in some edge cases. Part of this effort was to fix a bug that pertained to a duplicate pulse when the pulsar commands were invoked via M-x. The duplication had the effect of potentially overriding the color of the pulse such as if, say, pulsar-pulse-line-red was invoked while the pulsar-face was blue.
  • Restored several command symbols to the default value of pulsar-pulse-functions. Those were disabled to support the use option pulsar-pulse-on-window-change, but as that is now removed we revert to the old and more predictable way of handling things.

  • Introduced conditionality that checks for real-this-command. This is necessary for commands that have to fudge this-command to provide their functionality. Such is the case with the evil-scroll-up and evil-scroll-down commands which are internally reported as previous-line and next-line, respectively. I discovered this problem while trying to support Duy Nguyen attempts that making pulsar work with evil.

    Thanks to Duy Nguyen for reporting the issue on the mailing list and then to Tom Dalziel who explained why evil does things the way it does (it is a good reason):

  • Documented how to use pulsar with the next-error-hook. By default, the n and p keys in Emacs' compilation buffers (e.g. the results of a grep search) produce a highlight for the locus of the given match. Due to how the code is implemented, we cannot use Pulsar's standard mechanism to trigger a pulse after the match is highlighted (i.e. by adding the commands to pulsar-pulse-functions. Instead, the user must add this to their configuration: 

      (add-hook 'next-error-hook #'pulsar-pulse-line)
  • Made other miscellaneous changes to tweak the code base and the manual.

Version 0.4.0 on 2022-07-19

  • Added the user option pulsar-pulse-on-window-change. This covers all commands or functions that affect the current window, so there is no need to include them individually in the pulsar-pulse-functions. Users who prefer to trigger a pulse only after select functions (e.g. only after other-window) are advised to set this user option to nil and update the pulsar-pulse-functions accordingly. Thanks to Ivan Popovych for the patch (commit b1a78dd).
  • Changed the default value of pulsar-pulse-functions to omit all those commands which are already covered by the aforementioned. In the interest of continuity, the old value is kept in the source code, with the relevant symbols commented out.
  • Named the mailing list email address as the Maintainer: of Pulsar. The package headers help the user find our primary sources and/or communication channels. This change conforms with work being done upstream in package.el by Philip Kaludercic. I was informed about it here: https://lists.sr.ht/~protesilaos/general-issues/%3C875ykl84yi.fsf%40posteo.net%3E.
  • Updated the documentation, where necessary and made other minor tweaks to the code.

Version 0.3.0 on 2022-04-08

  • Changed the source repository from GitLab to SourceHut: https://git.sr.ht/~protesilaos/pulsar. Use the mailing list to start a discussion, report a bug, send a patch, etc.: https://lists.sr.ht/~protesilaos/pulsar. The GitLab URL will serve as a mirror from now on (a GitHub mirror is still available and will remain that way).
  • Refined how Pulsar behaves in the case of the last line. Basically, when the last line cannot be highlighted we want to pulse the one right above. Thanks to JD Smith for fine-tuning this behaviour in merge request 1 over at the GitLab mirror: https://gitlab.com/protesilaos/pulsar/-/merge_requests/1 (exempt from the requirement to assign copyright to the Free Software Foundation as it is below the threshold).
  • Ensured that the Pulsar effect are limited to the current window when the buffer is displayed in multiple windows. This avoids the common problem of simultaneous highlights in multiple locations, which confuse rather than inform the user of where the point is. Thanks to Aymeric Agon-Rambosson for the contribution in merge request 2 over at the GitLab mirror: https://gitlab.com/protesilaos/pulsar/-/merge_requests/2. Aymeric has assigned copyright to the Free Software Foundation.
  • Wrote a buffer-local and a global minor mode that sets up Pulsar. This supersedes the old design which had a built-in assumption that the "pulse line" effect should always be global. Now the user has more flexibility. They may also disable Pulsar on demand. Note that pulsar still only triggers its effect for entries in the user option pulsar-pulse-functions. Thanks to Rudolf Adamkovič for the feedback in issue 9 over at the GitLab mirror: https://gitlab.com/protesilaos/pulsar/-/issues/9.
  • Implement the pulsar-highlight-dwim command. It is like the pulsar-highlight-line except it also understands regions, be they regular or rectangular. Thanks to Mark Barton for the feedback in issue 13 over at the GitLab mirror: https://gitlab.com/protesilaos/pulsar/-/issues/13.
  • Clarified some technical points in various doc strings and the manual, such as what is the pulsar-delay and the pulsar-iterations. Thanks to Rudolf Adamkovič for the feedback in issue 12 over at the GitLab mirror: https://gitlab.com/protesilaos/pulsar/-/issues/12.

Version 0.2.0 on 2022-03-16

  • Fixed an inconsistency that was present when Emacs was running in a server-client model where the highlight would never pulse but instead remain fixed in place until another command was invoked. By default, the pulse effect should now work for that use-case. Thanks to Mark Barton, Petter Storvik, and user kb for their feedback in issue 1: https://gitlab.com/protesilaos/pulsar/-/issues/1.
  • Implemented the pulsar-highlight-line command and abstracted the relevant code. Unlike pulsar-pulse-line, it never pulses the current line. Instead it keeps the highlight in place until another command is invoked. Thanks to Mark Barton for proposing this in issue 1.
  • Introduced the user option pulsar-pulse which determines whether pulsar should use a pulse effect (notwithstanding the aforementioned new command). When its value is non-nil (the default) pulsing takes place. Thanks to Petter Storvik for suggesting this approach in issue 1.
  • Added the user option pulsar-iterations which controls how smooth or abrupt the pulse effect is. This complements the existing variable pulsar-delay. Both apply only when pulsar-pulse is non-nil.
  • Wrote the pulsar-generic face and made it the default value of the pulsar-face user option. This is consistent with the original design of a theme-agnostic presentation, though now it ensures that the :extend attribute is used to stretch the highlight to the edge of the window (without it and depending on the theme, the highlight would only reach the last character on the line).
  • Updated the manual to reflect those changes.

Version 0.1.0 on 2022-03-14

Initial release of the package. Please read the manual.

The core idea for this package was implemented in the prot-pulse.el file that is part of my dotfiles (now deprecated). I was using it at least since December 2020.