Running hooks before, after or around an action

Embark has three variables, ‘embark-pre-action-hooks’, ‘embark-post-action-hooks’ and ‘embark-around-action-hooks’, which are alists associating commands to hooks that should run before or after or as around advice for the command when used as an 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.

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’, ‘embark-post-action-hooks’ and ‘embark-around-action-hooks’.

For pre-action hooks:

‘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--unmark-target’

Unmark the active region. Use this for commands you want to act on the region contents but without the region being active. The default configuration uses this function as a pre-action hook for ‘occur’ and ‘query-replace’, for example, so that you can use them as actions with region targets to search the whole buffer for the text contained in the region. Without this pre-action hook using ‘occur’ as an action for a region target would be pointless: it would search for the the region contents in the region, (typically, due to the details of regexps) finding only one match!

‘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’.

For post-action hooks:

‘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.

For around-action hooks:

‘embark--mark-target’

Save existing mark and point location, mark the target and run the action. 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 an around 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--cd’

Run the action with ‘default-directory’ set to the directory associated to the current target. The target should be of type ‘file’, ‘buffer’, ‘bookmark’ or ‘library’, and the associated directory is what you’d expect in each case.

‘embark--narrow-to-target’

Run the action with buffer narrowed to current target. Use this as an around hook to localize the effect of actions that don’t already work on just the region. In the default configuration it is used for ‘repunctuate-sentences’.

‘embark--save-excursion’

Run the action restoring point at the end. The current default configuration doesn’t use this but it is available for users.