[elpa] externals/pulsar cf34b2ad7d: BREAKING: use a minor mode to set up pulsar

[ELPA Syncer]

branch: externals/pulsar
commit cf34b2ad7deb3e6e12f05a57f9cdf61c5e8c5388
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    BREAKING: use a minor mode to set up pulsar
    
    This supersedes the old design which has a built-in assumption that the
    "pulse line" effect should always be global.  Now the user can have a
    global style or a buffer-local one.  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:
    <https://gitlab.com/protesilaos/pulsar/-/issues/9>.
---
 README.org | 104 +++++++++++++++++++++++++++++++------------------------------
 pulsar.el  |  51 ++++++++++++++++--------------
 2 files changed, 80 insertions(+), 75 deletions(-)

diff --git a/README.org b/README.org
index 162e777ac9..d1217e271a 100644
--- a/README.org
+++ b/README.org
@@ -64,23 +64,19 @@ modify this GNU manual.”
 :END:
 
 #+vindex: pulse-pulse-functions
+#+findex: pulsar-mode
+#+findex: pulsar-global-mode
 This is a small package that temporarily highlights the current line
 after a given function is invoked.  The affected functions are defined
-in the user option ~pulsar-pulse-functions~.
+in the user option ~pulsar-pulse-functions~ and the effect takes place
+when either ~pulsar-mode~ (buffer-local) or ~pulsar-global-mode~ is
+enabled.
 
 [ NOTE 2022-03-20 07:26 +0200: The ~pulse-after-function-hook~ has been
   removed as part of {{{development-version}}}.  Pulsar no longer uses
   the advice mechanism.  Instead, it does its work by leveraging the
   ~post-command-hook~. ]
 
-#+findex: pulsar-setup
-To remove the advice and disable Pulsar altogether, evaluate this form:
-~(pulsar-setup 'reverse)~.  The ~pulsar-setup~ function can be used
-manually to install the advice on the relevant functions, though it is
-strongly encouraged to use ~customize-set-variable~ for the user option
-~pulsar-pulse-functions~ and let Emacs set up everything correctly (that
-user option has a special custom setter function).
-
 #+vindex: pulsar-delay
 #+vindex: pulsar-iterations
 #+vindex: pulsar-face
@@ -89,9 +85,9 @@ smooth the effect is depends on ~pulsar-iterations~.  While 
the
 applicable face is specified in ~pulsar-face~.
 
 #+vindex: pulsar-pulse
-To disable the pulse but keep the highlight, set ~pulsar-pulse~ to nil.
-The current line will remain highlighted until another command is
-invoked.
+To disable the pulse but keep the temporary highlight, set the user
+option ~pulsar-pulse~ to nil.  The current line will remain highlighted
+until another command is invoked.
 
 #+findex: pulsar-pulse-line
 #+findex: pulsar-highlight-line
@@ -102,10 +98,10 @@ command never pulses the line: the highlight stays in 
place as if
 ~pulsar-pulse~ is nil.
 
 #+vindex: pulsar-highlight-face
-To help users differentiate between the momentary pulse and transient
-highlight effects, the user option ~pulsar-highlight-face~ controls the
-presentation of the ~pulsar-highlight-line~ command.  By default, this
-that variable is the same as ~pulsar-face~.
+To help users differentiate between the pulse and highlight effects, the
+user option ~pulsar-highlight-face~ controls the presentation of the
+~pulsar-highlight-line~ command.  By default, this variable is the same
+as ~pulsar-face~.
 
 Pulsar depends on the built-in ~pulse.el~ library.
 
@@ -172,41 +168,40 @@ Remember to read the doc string of each of these 
variables.
 #+begin_src emacs-lisp
 (require 'pulsar)
 
-(pulsar-setup)
-
-(customize-set-variable
- 'pulsar-pulse-functions ; Read the doc string for why not `setq'
- '(recenter-top-bottom
-   move-to-window-line-top-bottom
-   reposition-window
-   bookmark-jump
-   other-window
-   delete-window
-   delete-other-windows
-   forward-page
-   backward-page
-   scroll-up-command
-   scroll-down-command
-   windmove-right
-   windmove-left
-   windmove-up
-   windmove-down
-   windmove-swap-states-right
-   windmove-swap-states-left
-   windmove-swap-states-up
-   windmove-swap-states-down
-   tab-new
-   tab-close
-   tab-next
-   org-next-visible-heading
-   org-previous-visible-heading
-   org-forward-heading-same-level
-   org-backward-heading-same-level
-   outline-backward-same-level
-   outline-forward-same-level
-   outline-next-visible-heading
-   outline-previous-visible-heading
-   outline-up-heading))
+(setq pulsar-pulse-functions
+      '(isearch-repeat-forward
+        isearch-repeat-backward
+        recenter-top-bottom
+        move-to-window-line-top-bottom
+        reposition-window
+        bookmark-jump
+        other-window
+        delete-window
+        delete-other-windows
+        forward-page
+        backward-page
+        scroll-up-command
+        scroll-down-command
+        windmove-right
+        windmove-left
+        windmove-up
+        windmove-down
+        windmove-swap-states-right
+        windmove-swap-states-left
+        windmove-swap-states-up
+        windmove-swap-states-down
+        tab-new
+        tab-close
+        tab-next
+        org-next-visible-heading
+        org-previous-visible-heading
+        org-forward-heading-same-level
+        org-backward-heading-same-level
+        outline-backward-same-level
+        outline-forward-same-level
+        outline-next-visible-heading
+        outline-previous-visible-heading
+        outline-up-heading))
 
 (setq pulsar-pulse t)
 (setq pulsar-delay 0.055)
@@ -214,6 +209,13 @@ Remember to read the doc string of each of these variables.
 (setq pulsar-face 'pulsar-magenta)
 (setq pulsar-highlight-face 'pulsar-yellow)
 
+(pulsar-global-mode 1)
+
+;; OR use the local mode for select mode hooks
+
+(dolist (hook '(org-mode-hook emacs-lisp-mode-hook))
+  (add-hook hook #'pulsar-mode))
+
 ;; pulsar does not define any key bindings.  This is just a sample that
 ;; respects the key binding conventions.  Evaluate:
 ;;
diff --git a/pulsar.el b/pulsar.el
index 155e929c23..b393562d9b 100644
--- a/pulsar.el
+++ b/pulsar.el
@@ -60,7 +60,9 @@ Extension of `pulse.el'."
 ;;;; User options
 
 (defcustom pulsar-pulse-functions
-  '(recenter-top-bottom
+  '(isearch-repeat-forward
+    isearch-repeat-backward
+    recenter-top-bottom
     move-to-window-line-top-bottom
     reposition-window
     bookmark-jump
@@ -91,21 +93,10 @@ Extension of `pulse.el'."
     outline-next-visible-heading
     outline-previous-visible-heading
     outline-up-heading)
-  "Functions that highlight the current line after invocation.
-This only takes effect when `pulsar-setup' is invoked (e.g. while
-setting up `pulsar.el').
-
-Any update to this user option outside of Custom (e.g. with
-`setq') requires a re-run of `pulsar-setup'.  Whereas functions
-such as `customize-set-variable' do that automatically."
+  "Functions that `pulsar-pulse-line' after invocation.
+This only takes effect when `pulsar-mode' or `pulsar-global-mode'
+is enabled."
   :type '(repeat function)
-  :initialize #'custom-initialize-default
-  :set (lambda (symbol value)
-         (if (eq value (default-value symbol))
-             (set-default symbol value)
-           (pulsar-setup 'reverse)
-           (set-default symbol value)
-           (pulsar-setup)))
   :group 'pulsar)
 
 (defcustom pulsar-face 'pulsar-generic
@@ -294,20 +285,32 @@ default)."
   (interactive)
   (pulsar--pulse :no-pulse pulsar-highlight-face))
 
-;;;; Advice setup
+;;;; Mode setup
+
+(define-minor-mode pulsar-mode
+  "Set up pulsar for each function in `pulsar-pulse-functions'.
+This is a buffer-local mode.  Also check `pulsar-global-mode'."
+  :global nil
+  (if pulsar-mode
+      (add-hook 'post-command-hook #'pulsar--post-command-pulse nil 'local)
+    (remove-hook 'post-command-hook #'pulsar--post-command-pulse 'local)))
+
+(defun pulsar--on ()
+  "Enable `pulsar-mode'."
+  (unless (minibufferp)
+    (let (inhibit-quit)
+      (pulsar-mode 1))))
+
+;;;###autoload
+(define-globalized-minor-mode pulsar-global-mode pulsar-mode pulsar--on)
 
 (defun pulsar--post-command-pulse ()
   "Run `pulsar-pulse-line' for `pulsar-pulse-functions'."
-  (when (memq this-command pulsar-pulse-functions)
+  (when (and (or pulsar-mode pulsar-global-mode)
+             (memq this-command pulsar-pulse-functions))
     (pulsar-pulse-line)))
 
-;;;###autoload
-(defun pulsar-setup (&optional reverse)
-  "Set up pulsar for each function in `pulsar-pulse-functions'.
-With optional non-nil REVERSE argument, remove the effect."
-  (if reverse
-      (remove-hook 'post-command-hook #'pulsar--post-command-pulse)
-    (add-hook 'post-command-hook #'pulsar--post-command-pulse)))
+(make-obsolete 'pulsar-setup nil "0.3.0")
 
 ;;;; Recentering commands