[elpa] externals/embark 407ce26: Switch to embark--confirm as pre-action hook; update documentation

[ELPA Syncer]

branch: externals/embark
commit 407ce267c34d44a35c403ea73512e4abb5c63cf9
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>

    Switch to embark--confirm as pre-action hook; update documentation
---
 README.org  | 125 ++++++++++++++++++++++++++++++++++++++++++----------
 embark.el   |  53 +++++++++++++++--------
 embark.texi | 142 +++++++++++++++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 253 insertions(+), 67 deletions(-)

diff --git a/README.org b/README.org
index 10a3cd1..ae83b09 100644
--- a/README.org
+++ b/README.org
@@ -145,9 +145,13 @@ Embark's default configuration it will:
 Besides acting individually on targets, Embark lets you work
 collectively on a set of target /candidates/. For example, while you are
 in the minibuffer the candidates are simply the possible completions
-of your input. Embark provides two main commands to work on candidate
+of your input. Embark provides three main commands to work on candidate
 sets:
 
+- The =embark-act-all= command runs the same action on each of the
+  current candidates. It is just like using =embark-act= on each
+  candidate in turn.
+
 - The =embark-collect-snapshot= command produces a buffer listing all
   the current candidates, for you to peruse and run actions on at your
   leisure. The candidates can be viewed in a grid or as a list showing
@@ -174,19 +178,25 @@ an Embark collect buffer, and if no such exporter is 
configured the
 
 These commands are always available as "actions" (although they do not
 act on just the current target but on all candidates) for =embark-act=
-and are bound to =S=, =E=, respectively, in =embark-general-map=. This means
-that you do not have to bind your own key bindings for these (although
-you can, of course!), just a key binding for =embark-act=.
+and are bound to =A=, =S=, and =E=, respectively, in =embark-general-map=.
+This means that you do not have to bind your own key bindings for
+these (although you can, of course!), just a key binding for
+=embark-act=.
 
 There is also the =embark-collect-live= variant of
 =embark-collect-snapshot= which produces "live" Embark Collect buffers,
 meaning they auto-update as the set of candidates changes. Most users
 of visual completion UIs such as Vertico, Icomplete, Selectrum or Ivy
-will probably either not want to use this, to avoid seeing double (the
-list of candidates is displayed both by Embark and by the completion
-UI), or to configure their completion UI to hide while using
-=embark-collect-live=. See the Embark wiki for 
[[https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live][sample
 configuration for
-Selectrum]].
+will probably either not want to use this from the minibuffer, to
+avoid seeing double (the list of candidates is displayed both by
+Embark and by the completion UI), or to configure their completion UI
+to hide while using =embark-collect-live=. See the Embark wiki for
+[[https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live][sample
 configuration for Selectrum]]. This command can also be used
+outside the minibuffer if you have a relevant candidate collector
+registered in =embark-candidate-collectors=. Users of the =embark-consult=
+package, for example, get such a candidate collector registered for
+them, and can produce a live-updating table of contents for any
+buffer, whose items are the lines matching =outline-regexp=.
 
 ** Switching to a different command without losing what you've typed
 
@@ -403,23 +413,29 @@ By default, for most commands =embark= inserts the target 
of the action
 into the next minibuffer prompt and "presses =RET=" for you, accepting
 the target as is.
 
-For some commands this might be undesirable, either for safety
-(because a command is "hard to undo", like =delete-file= or
-=kill-buffer=), or because further input is required next to the target
-(like when using =shell-command=: the target is the file and you still
-need to enter a shell command to run on it, at the same prompt). You
-can add such commands to the =embark-allow-edit-actions= variable
-(which by default already contains the examples mentioned, and a few
-others as well).
+For some commands this might be undesirable because further input is
+required next to the target, like when using =shell-command=: the target
+is the file and you still need to enter a shell command to run on it,
+at the same prompt. You can add such commands to the
+=embark-allow-edit-actions= variable (which by default already contains
+the examples mentioned, and a few others as well).
+
+You could abuse this feature so that you have to confirm "dangerous"
+actions such as =delete-file= (and indeed, Embark used to have
+=delete-file= in the default value of =embark-allow-edit-actions=), but it
+is better to implement confirmation by adding the =embark--confirm=
+function to the appropriate entry of =embark-pre-action-hooks=.
 
 ** Running some setup after injecting the target
 
 You can customize what happens after the target is inserted at the
 minibuffer prompt of an action. There are =embark-setup-action-hooks=,
 that are run by default after injecting the target into the
-minibuffer. The hook can be specified for specific action commands by
-associating the command to the desired hook. By default the hooks with
-the key t are executed.
+minibuffer. The variable =embark-setup-action-hooks= is an alist
+associating commands to their setup hooks. There are two special keys:
+if no setup hooks are specified for a given action, the hooks
+associated to =t= are run; and the hooks associated to =:always= are run
+regardless of the action.
 
 For example, consider using =shell-command= as an action during file
 completion. It would be useful to insert a space before the target
@@ -430,6 +446,69 @@ configuration there is an entry in 
=embark-setup-action-hooks= associating
 quotes all the spaces in the file name, inserts an extra space at the
 beginning of the line and leaves point to the left of it.
 
+** Running hooks before or after an action
+
+Embark has two variables, =embark-pre-action-hooks= and
+=embark-post-action-hooks=, which are alists associating commands to
+hooks that should run before or after the command is used as an
+action.  As with, =embark-setup-action-hooks=, there are two special
+keys for the alists: =t= designates the default hooks to run when no
+specific hooks are specified for a command; and hooks associated to
+=:always= run regardless.
+
+The default values of those variables are fairly extensive, adding
+creature comforts to make running actions a smooth experience. Embark
+comes with several functions intended to be added to these hooks, and
+used in the default values of =embark-pre-action-hooks= and
+=embark-post-action-hooks=:
+
+- =embark--ignore-target= :: Ignore the target. Use this for commands
+  that do prompt you in the minibuffer but for which inserting the
+  target would be inappropriate. This is not a common situation but
+  does occasionally arise. For example it is used by default for
+  =shell-command-on-region=: this is used as action for region targets,
+  and it prompts for a shell command, you typically do /not/ want the
+  target, that is the contents of the region, to be entered at that
+  prompt!
+
+- =embark--confirm= :: Prompt the user for confirmation before executing
+  the action. This is used be default for commands deemed "dangerous",
+  or, more accurately, hard to undo, such as =delete-file= and
+  =kill-buffer=.
+
+- =embark--mark-target= :: Mark the target as an active region. Most
+  targets at point outside the minibuffer report which region of the
+  buffer they correspond to (this is the information used by
+  =embark-highlight-indicator= to know what portion of the buffer to
+  highlight); this function marks that region. It is useful as a pre
+  action hook for commands that expect a region to be marked, for
+  example, it is used by default for =indent-region= so that it works on
+  s-expression targets, or for =fill-region= so that it works on
+  paragraph targets.
+
+- =embark--beginning-of-target= :: Move to the beginning of the target
+  (for targets that report bounds). This is used by default for
+  backward motion commands such as =backward-sexp=, so that they don't
+  accidentally leave you on the current target.
+
+- =embark--end-of-target= :: Move to the end of the target. This is used
+  similarly to the previous function, but also for commands that act
+  on the last s-expression like =eval-last-sexp=. This allow you to act
+  on an s-expression from anywhere inside it and still use
+  =eval-last-sexp= as an action.
+
+- =embark--xref-push-markers= :: Push the current location on the xref
+  marker stack. Use this for commands that take you somewhere and for
+  which you'd like to be able to come back to where you were using
+  =xref-pop-marker-stack=. This is used by default for =find-library=.
+
+- =embark--restart= :: Restart the command currently prompting in the
+  minibuffer, so that the list of completion candidates is updated.
+  This is useful as a post action hook for commands that delete or
+  rename a completion candidate; for example the default value of
+  =embark-post-action-hooks= uses it for =delete-file=, =kill-buffer=,
+  =rename-file=, =rename-buffer=, etc.
+
 ** Creating your own keymaps
 
 All internal keymaps are defined with a helper macro
@@ -507,7 +586,7 @@ metadata looks:
 #+end_src
 
 As you can see, the built-in support for setting the category
-metadatum is not very easy to use or pretty to look at. To help with
+meta-datum is not very easy to use or pretty to look at. To help with
 this I recommend the =consult--read= function from the excellent
 [[https://github.com/minad/consult/][Consult]] package. With that function we 
can rewrite the command as
 follows:
@@ -794,11 +873,11 @@ Code contributions are very welcome too, but since Embark 
is now on
 GNU ELPA, copyright assignment to the FSF is required before you can
 contribute code.
 
-* Acknowledgements
+* Acknowledgments
 
 While I, Omar Antolín Camarena, have written most of the Embark code
 and remain very stubborn about some of the design decisions, Embark
-has recieved substantial help from a number of other people which this
+has received substantial help from a number of other people which this
 document has neglected to mention for far too long. In particular,
 Daniel Mendler has been absolutely invaluable, implementing several
 important features, and providing a lot of useful advice.
diff --git a/embark.el b/embark.el
index 176466a..772667c 100644
--- a/embark.el
+++ b/embark.el
@@ -368,17 +368,23 @@ with `find-file'."
   'embark-allow-edit-actions
   "0.12")
 (defcustom embark-allow-edit-actions
-  '(delete-file
-    delete-directory
-    kill-buffer
-    shell-command
+  '(shell-command
     shell-command-on-region
     async-shell-command
-    embark-kill-buffer-and-window
     pp-eval-expression)
   "Enable editing of target prior to acting for these commands.
-Editing the target is useful as a confirmation feature for
-destructive commands like `delete-file'."
+Put commands on this list for which additional information needs
+to be entered at the same minibuffer prompt where the target is
+placed.  For example, `shell-command' is on the default value of
+this list because when using `shell-command' as an action
+typically the target is a file name, and you still need to type
+the program and possibly other command line parameters, at the
+same prompt.
+
+Embark used to recommend abusing this as a means of asking the
+user for confirmation before an action, but it is preferable to
+add `embark--confirm' as a pre-action hook for the action in
+`embark-pre-action-hooks'."
   :type '(repeat function))
 
 (defvar embark-skip-edit-commands nil)
@@ -402,7 +408,7 @@ into in the minibuffer and before acting on it.  The hooks 
must
 accept arbitrary keyword argument. The :action symbol, the
 :target string and target :type are always present.  For actions
 at point the target bounds are passed too.  The default pre-action
-hook is specified by the entry with key t.  Furthermore hooks with
+hook is specified by the entry with key t.  Furthermore, hooks with
 the key :always are executed always."
   :type '(alist :key-type
                 (choice symbol
@@ -460,7 +466,12 @@ the key :always are executed always."
     ;; commands we want to be able to jump back from
     ;; (embark-find-definition achieves this by calling
     ;; xref-find-definitions which pushes the markers itself)
-    (find-library embark--xref-push-markers))
+    (find-library embark--xref-push-markers)
+    ;; commands which prompt the user for confirmation before running
+    (delete-file embark--confirm)
+    (delete-directory embark--confirm)
+    (kill-buffer embark--confirm)
+    (embark-kill-buffer-and-window embark--confirm))
   "Alist associating commands with pre-action hooks.
 The hooks are run right before an action is embarked upon.  See
 `embark-setup-action-hooks' for information about the hook
@@ -1714,9 +1725,9 @@ If called outside the minibuffer, simply apply FN to 
ARGS."
   "Run HOOKS for ACTION.
 The HOOKS argument must be alist.  The keys t and :always are
 treated specially.  The :always hooks are executed always and the
-t hooks are the default hooks, if there are no command-specific
-hooks.  The QUIT, ACTION and TARGET arguments are passed to the
-hooks."
+t hooks are the default hooks, for when there are no
+command-specific hooks for ACTION.  The QUIT, ACTION and TARGET
+arguments are passed to the hooks as keyword arguments."
   (mapc (lambda (h) (apply h :action action :quit quit target))
         (or (alist-get action hooks)
             (alist-get t hooks)))
@@ -2091,19 +2102,18 @@ ARG is the prefix argument."
                      indicators (embark--action-keymap type nil)
                      (list (list :type type :multi (length candidates))))
                     (user-error "Canceled")))
-               (post-action-wo-restart
-                (mapcar (lambda (x) (remq 'embark--restart x))
-                        embark-post-action-hooks))
                (act (lambda (candidate)
-                      (let ((embark-allow-edit-actions nil)
-                            (embark-post-action-hooks post-action-wo-restart))
+                      (cl-letf (((symbol-function 'embark--restart) #'ignore)
+                                ((symbol-function 'embark--confirm) #'ignore))
                         (embark--act action candidate))))
                (quit (if embark-quit-after-action (not arg) arg)))
           (when (and (eq action (embark--default-action type))
                      (eq action embark--command))
             (setq candidates (mapcar #'embark--orig-target candidates)))
-          (when (y-or-n-p (format "Run %s on %d %ss? "
-                                  action (length candidates) type))
+          (when (or (not (memq 'embark--confirm
+                               (alist-get action embark-pre-action-hooks)))
+                    (y-or-n-p (format "Run %s on %d %ss? "
+                                      action (length candidates) type)))
             (if (memq action embark-multitarget-actions)
                 (embark--act action transformed quit)
               (if quit
@@ -3687,6 +3697,11 @@ and leaves the point to the left of it."
   "Push the xref markers to leave a location trail."
   (xref--push-markers))
 
+(cl-defun embark--confirm (&key action target &allow-other-keys)
+  "Ask for confirmation before running the ACTION on the TARGET."
+  (unless (y-or-n-p (format "Run %s on %s? " action target))
+    (user-error "Cancelled")))
+
 ;;; keymaps
 
 (embark-define-keymap embark-meta-map
diff --git a/embark.texi b/embark.texi
index 38312d4..b44a44d 100644
--- a/embark.texi
+++ b/embark.texi
@@ -32,7 +32,7 @@
 * Embark, Marginalia and Consult: Embark Marginalia and Consult. 
 * Resources::
 * Contributions::
-* Acknowledgements::
+* Acknowledgments::
 
 @detailmenu
 --- The Detailed Node Listing ---
@@ -51,6 +51,7 @@ Advanced configuration
 * Quitting the minibuffer after an action::
 * Allowing the target to be edited before acting on it::
 * Running some setup after injecting the target::
+* Running hooks before or after an action::
 * Creating your own keymaps::
 * Defining actions for new categories of targets::
 
@@ -235,11 +236,16 @@ Find the file corresponding to an Emacs Lisp library at 
point.
 Besides acting individually on targets, Embark lets you work
 collectively on a set of target @emph{candidates}. For example, while you are
 in the minibuffer the candidates are simply the possible completions
-of your input. Embark provides two main commands to work on candidate
+of your input. Embark provides three main commands to work on candidate
 sets:
 
 @itemize
 @item
+The @samp{embark-act-all} command runs the same action on each of the
+current candidates. It is just like using @samp{embark-act} on each
+candidate in turn.
+
+@item
 The @samp{embark-collect-snapshot} command produces a buffer listing all
 the current candidates, for you to peruse and run actions on at your
 leisure. The candidates can be viewed in a grid or as a list showing
@@ -268,19 +274,25 @@ an Embark collect buffer, and if no such exporter is 
configured the
 
 These commands are always available as ``actions'' (although they do not
 act on just the current target but on all candidates) for @samp{embark-act}
-and are bound to @samp{S}, @samp{E}, respectively, in 
@samp{embark-general-map}. This means
-that you do not have to bind your own key bindings for these (although
-you can, of course!), just a key binding for @samp{embark-act}.
+and are bound to @samp{A}, @samp{S}, and @samp{E}, respectively, in 
@samp{embark-general-map}.
+This means that you do not have to bind your own key bindings for
+these (although you can, of course!), just a key binding for
+@samp{embark-act}.
 
 There is also the @samp{embark-collect-live} variant of
 @samp{embark-collect-snapshot} which produces ``live'' Embark Collect buffers,
 meaning they auto-update as the set of candidates changes. Most users
 of visual completion UIs such as Vertico, Icomplete, Selectrum or Ivy
-will probably either not want to use this, to avoid seeing double (the
-list of candidates is displayed both by Embark and by the completion
-UI), or to configure their completion UI to hide while using
-@samp{embark-collect-live}. See the Embark wiki for 
@uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live,
 sample configuration for
-Selectrum}.
+will probably either not want to use this from the minibuffer, to
+avoid seeing double (the list of candidates is displayed both by
+Embark and by the completion UI), or to configure their completion UI
+to hide while using @samp{embark-collect-live}. See the Embark wiki for
+@uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live,
 sample configuration for Selectrum}. This command can also be used
+outside the minibuffer if you have a relevant candidate collector
+registered in @samp{embark-candidate-collectors}. Users of the 
@samp{embark-consult}
+package, for example, get such a candidate collector registered for
+them, and can produce a live-updating table of contents for any
+buffer, whose items are the lines matching @samp{outline-regexp}.
 
 @node Switching to a different command without losing what you've typed
 @section Switching to a different command without losing what you've typed
@@ -402,6 +414,7 @@ integration despite this.)
 * Quitting the minibuffer after an action::
 * Allowing the target to be edited before acting on it::
 * Running some setup after injecting the target::
+* Running hooks before or after an action::
 * Creating your own keymaps::
 * Defining actions for new categories of targets::
 @end menu
@@ -522,14 +535,18 @@ By default, for most commands @samp{embark} inserts the 
target of the action
 into the next minibuffer prompt and ``presses @samp{RET}'' for you, accepting
 the target as is.
 
-For some commands this might be undesirable, either for safety
-(because a command is ``hard to undo'', like @samp{delete-file} or
-@samp{kill-buffer}), or because further input is required next to the target
-(like when using @samp{shell-command}: the target is the file and you still
-need to enter a shell command to run on it, at the same prompt). You
-can add such commands to the @samp{embark-allow-edit-actions} variable
-(which by default already contains the examples mentioned, and a few
-others as well).
+For some commands this might be undesirable because further input is
+required next to the target, like when using @samp{shell-command}: the target
+is the file and you still need to enter a shell command to run on it,
+at the same prompt. You can add such commands to the
+@samp{embark-allow-edit-actions} variable (which by default already contains
+the examples mentioned, and a few others as well).
+
+You could abuse this feature so that you have to confirm ``dangerous''
+actions such as @samp{delete-file} (and indeed, Embark used to have
+@samp{delete-file} in the default value of @samp{embark-allow-edit-actions}), 
but it
+is better to implement confirmation by adding the @samp{embark--confirm}
+function to the appropriate entry of @samp{embark-pre-action-hooks}.
 
 @node Running some setup after injecting the target
 @section Running some setup after injecting the target
@@ -537,9 +554,11 @@ others as well).
 You can customize what happens after the target is inserted at the
 minibuffer prompt of an action. There are @samp{embark-setup-action-hooks},
 that are run by default after injecting the target into the
-minibuffer. The hook can be specified for specific action commands by
-associating the command to the desired hook. By default the hooks with
-the key t are executed.
+minibuffer. The variable @samp{embark-setup-action-hooks} is an alist
+associating commands to their setup hooks. There are two special keys:
+if no setup hooks are specified for a given action, the hooks
+associated to @samp{t} are run; and the hooks associated to @samp{:always} are 
run
+regardless of the action.
 
 For example, consider using @samp{shell-command} as an action during file
 completion. It would be useful to insert a space before the target
@@ -550,6 +569,79 @@ configuration there is an entry in 
@samp{embark-setup-action-hooks} associating
 quotes all the spaces in the file name, inserts an extra space at the
 beginning of the line and leaves point to the left of it.
 
+@node Running hooks before or after an action
+@section Running hooks before or after an action
+
+Embark has two variables, @samp{embark-pre-action-hooks} and
+@samp{embark-post-action-hooks}, which are alists associating commands to
+hooks that should run before or after the command is used as an
+action.  As with, @samp{embark-setup-action-hooks}, there are two special
+keys for the alists: @samp{t} designates the default hooks to run when no
+specific hooks are specified for a command; and hooks associated to
+@samp{:always} run regardless.
+
+The default values of those variables are fairly extensive, adding
+creature comforts to make running actions a smooth experience. Embark
+comes with several functions intended to be added to these hooks, and
+used in the default values of @samp{embark-pre-action-hooks} and
+@samp{embark-post-action-hooks}:
+
+@table @asis
+@item @samp{embark--ignore-target}
+Ignore the target. Use this for commands
+that do prompt you in the minibuffer but for which inserting the
+target would be inappropriate. This is not a common situation but
+does occasionally arise. For example it is used by default for
+@samp{shell-command-on-region}: this is used as action for region targets,
+and it prompts for a shell command, you typically do @emph{not} want the
+target, that is the contents of the region, to be entered at that
+prompt!
+
+@item @samp{embark--confirm}
+Prompt the user for confirmation before executing
+the action. This is used be default for commands deemed ``dangerous'',
+or, more accurately, hard to undo, such as @samp{delete-file} and
+@samp{kill-buffer}.
+
+@item @samp{embark--mark-target}
+Mark the target as an active region. Most
+targets at point outside the minibuffer report which region of the
+buffer they correspond to (this is the information used by
+@samp{embark-highlight-indicator} to know what portion of the buffer to
+highlight); this function marks that region. It is useful as a pre
+action hook for commands that expect a region to be marked, for
+example, it is used by default for @samp{indent-region} so that it works on
+s-expression targets, or for @samp{fill-region} so that it works on
+paragraph targets.
+
+@item @samp{embark--beginning-of-target}
+Move to the beginning of the target
+(for targets that report bounds). This is used by default for
+backward motion commands such as @samp{backward-sexp}, so that they don't
+accidentally leave you on the current target.
+
+@item @samp{embark--end-of-target}
+Move to the end of the target. This is used
+similarly to the previous function, but also for commands that act
+on the last s-expression like @samp{eval-last-sexp}. This allow you to act
+on an s-expression from anywhere inside it and still use
+@samp{eval-last-sexp} as an action.
+
+@item @samp{embark--xref-push-markers}
+Push the current location on the xref
+marker stack. Use this for commands that take you somewhere and for
+which you'd like to be able to come back to where you were using
+@samp{xref-pop-marker-stack}. This is used by default for @samp{find-library}.
+
+@item @samp{embark--restart}
+Restart the command currently prompting in the
+minibuffer, so that the list of completion candidates is updated.
+This is useful as a post action hook for commands that delete or
+rename a completion candidate; for example the default value of
+@samp{embark-post-action-hooks} uses it for @samp{delete-file}, 
@samp{kill-buffer},
+@samp{rename-file}, @samp{rename-buffer}, etc.
+@end table
+
 @node Creating your own keymaps
 @section Creating your own keymaps
 
@@ -638,7 +730,7 @@ metadata looks:
 @end lisp
 
 As you can see, the built-in support for setting the category
-metadatum is not very easy to use or pretty to look at. To help with
+meta-datum is not very easy to use or pretty to look at. To help with
 this I recommend the @samp{consult--read} function from the excellent
 @uref{https://github.com/minad/consult/, Consult} package. With that function 
we can rewrite the command as
 follows:
@@ -963,12 +1055,12 @@ Code contributions are very welcome too, but since 
Embark is now on
 GNU ELPA, copyright assignment to the FSF is required before you can
 contribute code.
 
-@node Acknowledgements
-@chapter Acknowledgements
+@node Acknowledgments
+@chapter Acknowledgments
 
 While I, Omar Antolín Camarena, have written most of the Embark code
 and remain very stubborn about some of the design decisions, Embark
-has recieved substantial help from a number of other people which this
+has received substantial help from a number of other people which this
 document has neglected to mention for far too long. In particular,
 Daniel Mendler has been absolutely invaluable, implementing several
 important features, and providing a lot of useful advice.