branch: externals/embark
commit 82475bb826b21b90b3c61c1d7772ecddd136d870
Author: Omar Antolín <omar.anto...@gmail.com>
Commit: Omar Antolín <omar.anto...@gmail.com>
Rename embark-setup-action-hooks to embark-target-injection-hooks
As discussed with @minad on GitHub at
5ebe2dfd91868ec525ea34ffd45941c5e9ce5358.
---
README.org | 44 +++++++++++++++++++++++---------------------
embark-consult.el | 18 ++++++++++--------
embark.el | 17 +++++++++++------
embark.texi | 44 +++++++++++++++++++++++---------------------
4 files changed, 67 insertions(+), 56 deletions(-)
diff --git a/README.org b/README.org
index 30451b62cf..19cf043693 100644
--- a/README.org
+++ b/README.org
@@ -411,20 +411,22 @@ behavior of =embark-act= and define a non-quitting
version as follows:
** 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 variable =embark-setup-action-hooks= is an alist
-associating commands to their setup hooks. There are two special keys:
-if no setup hook is specified for a given action, the hook associated
-to =t= is run; and the hook associated to =:always= is run regardless of
-the action.
+minibuffer prompt of an action. There are
+=embark-target-injection-hooks=, that are run by default after injecting
+the target into the minibuffer. The variable
+=embark-target-injection-hooks= is an alist associating commands to
+their setup hooks. There are two special keys: if no setup hook is
+specified for a given action, the hook associated to =t= is run; and the
+hook associated to =:always= is run regardless of the action. (This
+variable used to have the less explicit name of
+=embark-setup-action-hooks=, so please update your configuration.)
For example, consider using =shell-command= as an action during file
completion. It would be useful to insert a space before the target
file name and to leave the point at the beginning, so you can
immediately type the shell command to run on that file. That's why in
Embark's default configuration there is an entry in
-=embark-setup-action-hooks= associating =shell-command= to a hook that
+=embark-target-injection-hooks= associating =shell-command= to a hook that
includes =embark--shell-prep=, a simple helper function that 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.
@@ -435,13 +437,13 @@ action at the minibuffer prompt, which is to "press
=RET=" for you,
accepting the target as is; if Embark did that for =shell-command= you
wouldn't get a chance to type in the command to execute! That is why
in Embark's default configuration the entry for =shell-command= in
-=embark-setup-action-hooks= also contains the function
+=embark-target-injection-hooks= also contains the function
=embark--allow-edit=.
Embark used to have a dedicated variable =embark-allow-edit-actions= to
which you could add commands for which Embark should forgo pressing
=RET= for you after inserting the target. Since its effect can also be
-achieved via the general =embark-setup-action-hooks= mechanism, that
+achieved via the general =embark-target-injection-hooks= mechanism, that
variable has been removed to simply Embark. Be sure to update your
configuration; if you had something like:
@@ -453,7 +455,7 @@ you should replace it with:
#+begin_src emacs-lisp
(push 'embark--allow-edit
- (alist-get 'my-command embark-setup-action-hooks))
+ (alist-get 'my-command embark-target-injection-hooks))
#+end_src
@@ -478,7 +480,7 @@ to be entered at that prompt!
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
+action. As with, =embark-target-injection-hooks=, there are two special keys
for the alists: =t= designates the default hook to run when no specific
hook is specified for a command; and the hook associated to =:always=
runs regardless.
@@ -724,15 +726,15 @@ included in the list =embark-indicators=).
minibuffer, submitting the input. (The immediate minibuffer exit can
be disabled for specific actions in order to allow editing the
input; this is done by adding the =embark--allow-edit= function to the
- appropriate entry of =embark-setup-action-hooks=). Embark inserts the
- target string at the first minibuffer opened by the action command,
- and if the command happens to prompt the user for input more than
- once, the user still interacts with the second and further prompts
- in the normal fashion. Note that if a command does not prompt the
- user for input in the minibuffer, Embark still allows you to use it
- as an action, but of course, never inserts the target anywhere.
- (There are plenty of examples in the default configuration of
- commands that do not prompt the user bound to keys in the action
+ appropriate entry of =embark-target-injection-hooks=). Embark inserts
+ the target string at the first minibuffer opened by the action
+ command, and if the command happens to prompt the user for input
+ more than once, the user still interacts with the second and further
+ prompts in the normal fashion. Note that if a command does not
+ prompt the user for input in the minibuffer, Embark still allows you
+ to use it as an action, but of course, never inserts the target
+ anywhere. (There are plenty of examples in the default configuration
+ of commands that do not prompt the user bound to keys in the action
maps, most of the region actions, for instance.)
This is how Embark manages to reuse normal commands as actions. The
diff --git a/embark-consult.el b/embark-consult.el
index 723a4d2015..7118c7f695 100644
--- a/embark-consult.el
+++ b/embark-consult.el
@@ -5,7 +5,7 @@
;; Author: Omar Antolín Camarena <o...@matem.unam.mx>
;; Maintainer: Omar Antolín Camarena <o...@matem.unam.mx>
;; Keywords: convenience
-;; Version: 0.2
+;; Version: 0.3
;; Homepage: https://github.com/oantolin/embark
;; Package-Requires: ((emacs "26.1") (embark "0.12") (consult "0.10"))
@@ -267,12 +267,13 @@ actual type."
(map-keymap
(lambda (_key cmd)
- (cl-pushnew 'embark--allow-edit (alist-get cmd embark-setup-action-hooks)))
+ (cl-pushnew 'embark--allow-edit
+ (alist-get cmd embark-target-injection-hooks)))
embark-consult-search-map)
(defun embark-consult--unique-match (&rest _)
"If there is a unique matching candidate, accept it.
-This is intended to be used in `embark-setup-action-hooks'."
+This is intended to be used in `embark-target-injection-hooks'."
(let ((candidates (cdr (embark-minibuffer-candidates))))
(if (or (null candidates) (cdr candidates))
(embark--allow-edit)
@@ -280,14 +281,15 @@ This is intended to be used in
`embark-setup-action-hooks'."
(insert (car candidates)))))
(dolist (cmd '(consult-outline consult-imenu consult-imenu-multi))
- (setf (alist-get cmd embark-setup-action-hooks)
- (remq 'embark--allow-edit (alist-get cmd embark-setup-action-hooks)))
+ (setf (alist-get cmd embark-target-injection-hooks)
+ (remq 'embark--allow-edit
+ (alist-get cmd embark-target-injection-hooks)))
(cl-pushnew #'embark-consult--unique-match
- (alist-get cmd embark-setup-action-hooks)))
+ (alist-get cmd embark-target-injection-hooks)))
(defun embark-consult--add-async-separator (&rest _)
"Add Consult's async separator at the beginning.
-This is intended to be used in `embark-setup-action-hooks' for any action
+This is intended to be used in `embark-target-injection-hooks' for any action
that is a Consult async command."
(let* ((style (alist-get consult-async-split-style
consult-async-split-styles-alist))
@@ -305,7 +307,7 @@ that is a Consult async command."
(map-keymap
(lambda (_key cmd)
(cl-pushnew #'embark-consult--add-async-separator
- (alist-get cmd embark-setup-action-hooks)))
+ (alist-get cmd embark-target-injection-hooks)))
embark-consult-async-search-map)
;;; Tables of contents for buffers: imenu and outline candidate collectors
diff --git a/embark.el b/embark.el
index 2cb85bc6e2..aab89a552c 100644
--- a/embark.el
+++ b/embark.el
@@ -371,7 +371,7 @@ with `find-file'."
(make-obsolete-variable
'embark-allow-edit-actions
"To allow editing for an action add `embark--allow-edit' to the
-entry of `embark-setup-action-hooks' whose key is the action."
+entry of `embark-target-injection-hooks' whose key is the action."
"0.14")
(defvar embark-skip-edit-commands nil)
@@ -383,7 +383,12 @@ entry of `embark-setup-action-hooks' whose key is the
action."
replaced by the single `embark-allow-edit-actions' variable."
"0.12"))
-(defcustom embark-setup-action-hooks
+(define-obsolete-variable-alias
+ 'embark-setup-action-hooks
+ 'embark-target-injection-hooks
+ "0.14")
+
+(defcustom embark-target-injection-hooks
'((async-shell-command embark--allow-edit embark--shell-prep)
(shell-command embark--allow-edit embark--shell-prep)
(shell-command-on-region embark--allow-edit)
@@ -418,7 +423,7 @@ the key :always are executed always."
(dolist (obsolete
'(embark-setup-hook embark-setup-hooks embark-setup-overrides))
(make-obsolete obsolete
- "see the new `embark-setup-action-hooks' variable."
+ "see the new `embark-target-injection-hooks' variable."
"0.12"))
(defcustom embark-pre-action-hooks
@@ -469,7 +474,7 @@ the key :always are executed always."
(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
+`embark-target-injection-hooks' for information about the hook
arguments and more details."
:type '(alist :key-type
(choice symbol
@@ -497,7 +502,7 @@ arguments and more details."
(package-delete embark--restart))
"Alist associating commands with post-action hooks.
The hooks are run after an embarked upon action concludes. See
-`embark-setup-action-hooks' for information about the hook
+`embark-target-injection-hooks' for information about the hook
arguments and more details."
:type '(alist :key-type
(choice symbol
@@ -1770,7 +1775,7 @@ minibuffer before executing the action."
;; its post command hook first, so use depth 10
(add-hook 'post-command-hook 'ivy-immediate-done 10 t)
(add-hook 'post-command-hook #'exit-minibuffer nil t))
- (embark--run-action-hooks embark-setup-action-hooks
+ (embark--run-action-hooks embark-target-injection-hooks
action target quit)))
(dedicate (and (derived-mode-p 'embark-collect-mode)
(not (window-dedicated-p))
diff --git a/embark.texi b/embark.texi
index 1c1afbd90f..12ac55eea8 100644
--- a/embark.texi
+++ b/embark.texi
@@ -531,20 +531,22 @@ behavior of @samp{embark-act} and define a non-quitting
version as follows:
@section 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 @samp{embark-setup-action-hooks},
-that are run by default after injecting the target into the
-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 hook is specified for a given action, the hook associated
-to @samp{t} is run; and the hook associated to @samp{:always} is run
regardless of
-the action.
+minibuffer prompt of an action. There are
+@samp{embark-target-injection-hooks}, that are run by default after injecting
+the target into the minibuffer. The variable
+@samp{embark-target-injection-hooks} is an alist associating commands to
+their setup hooks. There are two special keys: if no setup hook is
+specified for a given action, the hook associated to @samp{t} is run; and the
+hook associated to @samp{:always} is run regardless of the action. (This
+variable used to have the less explicit name of
+@samp{embark-setup-action-hooks}, so please update your configuration.)
For example, consider using @samp{shell-command} as an action during file
completion. It would be useful to insert a space before the target
file name and to leave the point at the beginning, so you can
immediately type the shell command to run on that file. That's why in
Embark's default configuration there is an entry in
-@samp{embark-setup-action-hooks} associating @samp{shell-command} to a hook
that
+@samp{embark-target-injection-hooks} associating @samp{shell-command} to a
hook that
includes @samp{embark--shell-prep}, a simple helper function that 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.
@@ -555,13 +557,13 @@ action at the minibuffer prompt, which is to ``press
@samp{RET}'' for you,
accepting the target as is; if Embark did that for @samp{shell-command} you
wouldn't get a chance to type in the command to execute! That is why
in Embark's default configuration the entry for @samp{shell-command} in
-@samp{embark-setup-action-hooks} also contains the function
+@samp{embark-target-injection-hooks} also contains the function
@samp{embark--allow-edit}.
Embark used to have a dedicated variable @samp{embark-allow-edit-actions} to
which you could add commands for which Embark should forgo pressing
@samp{RET} for you after inserting the target. Since its effect can also be
-achieved via the general @samp{embark-setup-action-hooks} mechanism, that
+achieved via the general @samp{embark-target-injection-hooks} mechanism, that
variable has been removed to simply Embark. Be sure to update your
configuration; if you had something like:
@@ -573,7 +575,7 @@ you should replace it with:
@lisp
(push 'embark--allow-edit
- (alist-get 'my-command embark-setup-action-hooks))
+ (alist-get 'my-command embark-target-injection-hooks))
@end lisp
@@ -599,7 +601,7 @@ to be entered at that prompt!
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
+action. As with, @samp{embark-target-injection-hooks}, there are two special
keys
for the alists: @samp{t} designates the default hook to run when no specific
hook is specified for a command; and the hook associated to @samp{:always}
runs regardless.
@@ -875,15 +877,15 @@ input this way. After inserting the string, Embark exits
the
minibuffer, submitting the input. (The immediate minibuffer exit can
be disabled for specific actions in order to allow editing the
input; this is done by adding the @samp{embark--allow-edit} function to the
-appropriate entry of @samp{embark-setup-action-hooks}). Embark inserts the
-target string at the first minibuffer opened by the action command,
-and if the command happens to prompt the user for input more than
-once, the user still interacts with the second and further prompts
-in the normal fashion. Note that if a command does not prompt the
-user for input in the minibuffer, Embark still allows you to use it
-as an action, but of course, never inserts the target anywhere.
-(There are plenty of examples in the default configuration of
-commands that do not prompt the user bound to keys in the action
+appropriate entry of @samp{embark-target-injection-hooks}). Embark inserts
+the target string at the first minibuffer opened by the action
+command, and if the command happens to prompt the user for input
+more than once, the user still interacts with the second and further
+prompts in the normal fashion. Note that if a command does not
+prompt the user for input in the minibuffer, Embark still allows you
+to use it as an action, but of course, never inserts the target
+anywhere. (There are plenty of examples in the default configuration
+of commands that do not prompt the user bound to keys in the action
maps, most of the region actions, for instance.)
This is how Embark manages to reuse normal commands as actions. The
