My Emacs configuration
git clone git://
Log | Files | Refs | LICENSE

embark.texi (63528B)

      1 \input texinfo    @c -*- texinfo -*-
      2 @c %**start of header
      3 @setfilename
      4 @settitle Embark: Emacs Mini-Buffer Actions Rooted in Keymaps
      5 @documentencoding UTF-8
      6 @documentlanguage en
      7 @c %**end of header
      9 @dircategory Emacs misc features
     10 @direntry
     11 * Embark: (embark).     Emacs Mini-Buffer Actions Rooted in Keymaps.
     12 @end direntry
     14 @finalout
     15 @titlepage
     16 @title Embark: Emacs Mini-Buffer Actions Rooted in Keymaps
     17 @author Omar Antolín Camarena
     18 @end titlepage
     20 @contents
     22 @ifnottex
     23 @node Top
     24 @top Embark: Emacs Mini-Buffer Actions Rooted in Keymaps
     25 @end ifnottex
     27 @menu
     28 * Overview::
     29 * Quick start::
     30 * Advanced configuration::
     31 * How does Embark call the actions?::
     32 * Embark, Marginalia and Consult: Embark Marginalia and Consult. 
     33 * Resources::
     34 * Contributions::
     35 * Acknowledgments::
     37 @detailmenu
     38 --- The Detailed Node Listing ---
     40 Overview
     42 * Acting on targets::
     43 * The default action on a target::
     44 * Working with sets of possible targets::
     45 * Switching to a different command without losing what you've typed::
     47 Working with sets of possible targets
     49 * Selecting some targets to make an ad hoc candidate set::
     50 * @samp{embark-live} a live-updating variant of @samp{embark-collect}::
     52 Advanced configuration
     54 * Showing information about available targets and actions::
     55 * Selecting commands via completions instead of key bindings::
     56 * Quitting the minibuffer after an action::
     57 * Running some setup after injecting the target::
     58 * Running hooks before, after or around an action: Running hooks before after or around an action. 
     59 * Creating your own keymaps::
     60 * Defining actions for new categories of targets::
     62 Defining actions for new categories of targets
     64 * New minibuffer target example - tab-bar tabs::
     65 * New target example in regular buffers - short Wikipedia links::
     67 How does Embark call the actions?
     69 * Non-interactive functions as actions::
     71 Embark, Marginalia and Consult
     73 * Marginalia::
     74 * Consult::
     76 @end detailmenu
     77 @end menu
     79 @node Overview
     80 @chapter Overview
     82 Embark makes it easy to choose a command to run based on what is near
     83 point, both during a minibuffer completion session (in a way familiar
     84 to Helm or Counsel users) and in normal buffers. Bind the command
     85 @samp{embark-act} to a key and it acts like prefix-key for a keymap of
     86 @emph{actions} (commands) relevant to the @emph{target} around point. With point on
     87 an URL in a buffer you can open the URL in a browser or eww or
     88 download the file it points to. If while switching buffers you spot an
     89 old one, you can kill it right there and continue to select another.
     90 Embark comes preconfigured with over a hundred actions for common
     91 types of targets such as files, buffers, identifiers, s-expressions,
     92 sentences; and it is easy to add more actions and more target types.
     93 Embark can also collect all the candidates in a minibuffer to an
     94 occur-like buffer or export them to a buffer in a major-mode specific
     95 to the type of candidates, such as dired for a set of files, ibuffer
     96 for a set of buffers, or customize for a set of variables.
     98 @menu
     99 * Acting on targets::
    100 * The default action on a target::
    101 * Working with sets of possible targets::
    102 * Switching to a different command without losing what you've typed::
    103 @end menu
    105 @node Acting on targets
    106 @section Acting on targets
    108 You can think of @samp{embark-act} as a keyboard-based version of a
    109 right-click contextual menu. The @samp{embark-act} command (which you should
    110 bind to a convenient key), acts as a prefix for a keymap offering you
    111 relevant @emph{actions} to use on a @emph{target} determined by the context:
    113 @itemize
    114 @item
    115 In the minibuffer, the target is the current top completion
    116 candidate.
    117 @item
    118 In the @samp{*Completions*} buffer the target is the completion at point.
    119 @item
    120 In a regular buffer, the target is the region if active, or else the
    121 file, symbol, URL, s-expression or defun at point.
    122 @end itemize
    124 Multiple targets can be present at the same location and you can cycle
    125 between them by repeating the @samp{embark-act} key binding. The type of
    126 actions offered depend on the type of the target. Here is a sample of
    127 a few of the actions offered in the default configuration:
    129 @itemize
    130 @item
    131 For files you get offered actions like deleting, copying,
    132 renaming, visiting in another window, running a shell command on the
    133 file, etc.
    134 @item
    135 For buffers the actions include switching to or killing the buffer.
    136 @item
    137 For package names the actions include installing, removing or
    138 visiting the homepage.
    139 @item
    140 For Emacs Lisp symbols the actions include finding the definition,
    141 looking up documentation, evaluating (which for a variable
    142 immediately shows the value, but for a function lets you pass it
    143 some arguments first). There are some actions specific to variables,
    144 such as setting the value directly or though the customize system,
    145 and some actions specific to commands, such as binding it to a key.
    146 @end itemize
    148 By default when you use @samp{embark-act} if you don't immediately select an
    149 action, after a short delay Embark will pop up a buffer showing a list
    150 of actions and their corresponding key bindings. If you are using
    151 @samp{embark-act} outside the minibuffer, Embark will also highlight the
    152 current target. These behaviors are configurable via the variable
    153 @samp{embark-indicators}. Instead of selecting an action via its key binding,
    154 you can select it by name with completion by typing @samp{C-h} after
    155 @samp{embark-act}.
    157 Everything is easily configurable: determining the current target,
    158 classifying it, and deciding which actions are offered for each type
    159 in the classification. The above introduction just mentions part of
    160 the default configuration.
    162 Configuring which actions are offered for a type is particularly easy
    163 and requires no programming: the variable @samp{embark-keymap-alist}
    164 associates target types with variables containing keymaps, and those
    165 keymaps containing bindings for the actions. (To examine the available
    166 categories and their associated keymaps, you can use @samp{C-h v
    167 embark-keymap-alist} or customize that variable.) For example, in the
    168 default configuration the type @samp{file} is associated with the symbol
    169 @samp{embark-file-map}. That symbol names a keymap with single-letter key
    170 bindings for common Emacs file commands, for instance @samp{c} is bound to
    171 @samp{copy-file}. This means that if you are in the minibuffer after running
    172 a command that prompts for a file, such as @samp{find-file} or @samp{rename-file},
    173 you can copy a file by running @samp{embark-act} and then pressing @samp{c}.
    175 These action keymaps are very convenient but not strictly necessary
    176 when using @samp{embark-act}: you can use any command that reads from the
    177 minibuffer as an action and the target of the action will be inserted
    178 at the first minibuffer prompt. After running @samp{embark-act} all of your
    179 key bindings and even @samp{execute-extended-command} can be used to run a
    180 command. For example, if you want to replace all occurrences of the
    181 symbol at point, just use @samp{M-%} as the action, there is no need to bind
    182 @samp{query-replace} in one of Embark's keymaps. Also, those action keymaps
    183 are normal Emacs keymaps and you should feel free to bind in them
    184 whatever commands you find useful as actions and want to be available
    185 through convenient bindings.
    187 The actions in @samp{embark-general-map} are available no matter what type
    188 of completion you are in the middle of. By default this includes
    189 bindings to save the current candidate in the kill ring and to insert
    190 the current candidate in the previously selected buffer (the buffer
    191 that was current when you executed a command that opened up the
    192 minibuffer).
    194 Emacs's minibuffer completion system includes metadata indicating the
    195 @emph{category} of what is being completed. For example, @samp{find-file}'s
    196 metadata indicates a category of @samp{file} and @samp{switch-to-buffer}'s metadata
    197 indicates a category of @samp{buffer}. Embark has the related notion of the
    198 @emph{type} of a target for actions, and by default when category metadata
    199 is present it is taken to be the type of minibuffer completion
    200 candidates when used as targets. Emacs commands often do not set
    201 useful category metadata so the @uref{, Marginalia} package, which supplies
    202 this missing metadata, is highly recommended for use with Embark.
    204 Embark's default configuration has actions for the following target
    205 types: files, buffers, symbols, packages, URLs, bookmarks, and as a
    206 somewhat special case, actions for when the region is active. You can
    207 read about the @uref{, default actions and their key bindings} on the GitHub
    208 project wiki.
    210 @node The default action on a target
    211 @section The default action on a target
    213 Embark has a notion of default action for a target:
    215 @itemize
    216 @item
    217 If the target is a minibuffer completion candidate, then the default
    218 action is whatever command opened the minibuffer in the first place.
    219 For example if you run @samp{kill-buffer}, then the default action will be
    220 to kill buffers.
    221 @item
    222 If the target comes from a regular buffer (i.e., not a minibuffer),
    223 then the default action is whatever is bound to @samp{RET} in the keymap of
    224 actions for that type of target. For example, in Embark's default
    225 configuration for a URL found at point the default action is
    226 @samp{browse-url}, because @samp{RET} is bound to @samp{browse-url} in the @samp{embark-url-map}
    227 keymap.
    228 @end itemize
    230 To run the default action you can press @samp{RET} after running @samp{embark-act}.
    231 Note that if there are several different targets at a given location,
    232 each has its own default action, so first cycle to the target you want
    233 and then press @samp{RET} to run the corresponding default action.
    235 There is also @samp{embark-dwim} which runs the default action for the first
    236 target found. It's pretty handy in non-minibuffer buffers: with
    237 Embark's default configuration it will:
    239 @itemize
    240 @item
    241 Open the file at point.
    242 @item
    243 Open the URL at point in a web browser (using the @samp{browse-url}
    244 command).
    245 @item
    246 Compose a new email to the email address at point.
    247 @item
    248 In an Emacs Lisp buffer, if point is on an opening parenthesis or
    249 right after a closing one, it will evaluate the corresponding
    250 expression.
    251 @item
    252 Go to the definition of an Emacs Lisp function, variable or macro at
    253 point.
    254 @item
    255 Find the file corresponding to an Emacs Lisp library at point.
    256 @end itemize
    258 @node Working with sets of possible targets
    259 @section Working with sets of possible targets
    261 Besides acting individually on targets, Embark lets you work
    262 collectively on a set of target @emph{candidates}. For example, while you are
    263 in the minibuffer the candidates are simply the possible completions
    264 of your input. Embark provides three main commands to work on candidate
    265 sets:
    267 @itemize
    268 @item
    269 The @samp{embark-act-all} command runs the same action on each of the
    270 current candidates. It is just like using @samp{embark-act} on each
    271 candidate in turn. (Because you can easily act on many more
    272 candidates than you meant to, by default Embark asks you to confirm
    273 uses of @samp{embark-act-all}; you can turn this off by setting the user
    274 option @samp{embark-confirm-act-all} to @samp{nil}.)
    276 @item
    277 The @samp{embark-collect} command produces a buffer listing all the current
    278 candidates, for you to peruse and run actions on at your leisure.
    279 The candidates are displayed as a list showing additional annotations.
    281 The Embark Collect buffer is somewhat ``dired-like'': you can select
    282 and deselect candidates through the @samp{embark-select} action (bound to
    283 @samp{SPC}). In an Embark Collect buffer @samp{embark-act} is bound to @samp{a} and
    284 @samp{embark-act-all} is bound to @samp{A}; @samp{embark-act-all} will act on all
    285 currently marked candidates if there any, and will act on all
    286 candidates if none are marked. In particular, this means that @samp{a SPC}
    287 will toggle whether the candidate at point is selected, and @samp{A SPC}
    288 will select all candidates if none are selected, or deselect all
    289 selected candidates if there are some.
    291 @item
    292 The @samp{embark-export} command tries to open a buffer in an appropriate
    293 major mode for the set of candidates. If the candidates are files
    294 export produces a Dired buffer; if they are buffers, you get an
    295 Ibuffer buffer; and if they are packages you get a buffer in
    296 package menu mode.
    298 If you use the grepping commands from the @uref{, Consult} package,
    299 @samp{consult-grep}, @samp{consult-git-grep} or @samp{consult-ripgrep}, then you should
    300 install the @samp{embark-consult} package, which adds support for exporting a
    301 list of grep results to an honest grep-mode buffer, on which you can
    302 even use @uref{, wgrep} if you wish.
    303 @end itemize
    305 When in doubt choosing between exporting and collecting, a good rule
    306 of thumb is to always prefer @samp{embark-export} since when an exporter to a
    307 special major mode is available for a given type of target, it will be
    308 more featureful than an Embark collect buffer, and if no such exporter
    309 is configured the @samp{embark-export} command falls back to the generic
    310 @samp{embark-collect}.
    312 These commands are always available as ``actions'' (although they do not
    313 act on just the current target but on all candidates) for @samp{embark-act}
    314 and are bound to @samp{A}, @samp{S} (for ``snapshot''), and @samp{E}, respectively, in
    315 @samp{embark-general-map}. This means that you do not have to bind your own
    316 key bindings for these (although you can, of course!), just a key
    317 binding for @samp{embark-act}.
    319 In Embark Collect or Embark Export buffers that were obtained by
    320 running @samp{embark-collect} or @samp{embark-export} from within a minibuffer
    321 completion session, @samp{g} is bound to a command that restarts the
    322 completion session, that is, the command that opened the minibuffer is
    323 run again and the minibuffer contents restored. You can then interact
    324 normally with the command, perhaps editing the minibuffer contents,
    325 and, if you wish, you can rerun @samp{embark-collect} or @samp{embark-export} to get
    326 an updated buffer.
    328 @menu
    329 * Selecting some targets to make an ad hoc candidate set::
    330 * @samp{embark-live} a live-updating variant of @samp{embark-collect}::
    331 @end menu
    333 @node Selecting some targets to make an ad hoc candidate set
    334 @subsection Selecting some targets to make an ad hoc candidate set
    336 The commands for working with sets of candidates just described,
    337 namely @samp{embark-act-all}, @samp{embark-export} and @samp{embark-collect} by default
    338 work with all candidates defined in the current context. For example,
    339 in the minibuffer they operate on all currently completion candidates,
    340 or in a dired buffer they work on all marked files (or all files if
    341 none are marked). Embark also has a notion of @emph{selection}, where you can
    342 accumulate an ad hoc list of targets for these commands to work on.
    344 The selection is controlled by using the @samp{embark-select} action (which
    345 must be run as an action through @samp{embark-act}), bound to @samp{SPC} in
    346 @samp{embark-general-map} so that it is always available. Calling this action
    347 on a target toggles its membership in the current buffer's Embark
    348 selection; that is, it adds it to selection if not selected and
    349 removes it from the selection if it was selected. Whenever the
    350 selection for a buffer is non-empty, the commands @samp{embark-act-all},
    351 @samp{embark-export} and @samp{embark-collect} will act on the selection.
    353 To deselect all selected targets, you can use the @samp{embark-select} action
    354 through @samp{embark-act-all}, since this will run @samp{embark-select} on each
    355 member of the current selection. Similarly if no targets are selected
    356 and you are in a minibuffer completion session, running @samp{embark-select}
    357 from @samp{embark-act-all} will select all the current completion candidates.
    359 This functionality is supported everywhere:
    361 @itemize
    362 @item
    363 In the minibuffer this gives a convenient way to act on several
    364 completion candidates that don't follow any simple pattern: just go
    365 through the completions selecting the ones you want, then use
    366 @samp{embark-act-all}. For example, you could attach several files at once
    367 to an email.
    368 @item
    369 For Embark Collect buffers this functionality enables a dired-like
    370 workflow, in which you mark various candidates and apply an action
    371 to all at once. (It supersedes a previous ad hoc dired-like
    372 interface that was implemented only in Embark Collect buffers, with
    373 a slightly different interface.)
    374 @item
    375 In a eww buffer you could use this to select various links you wish
    376 to follow up on, and then collect them into a buffer. Similarly,
    377 while reading Emacs's info manual you could select some symbols you
    378 want to read more about and export them to an @samp{apropos-mode} buffer.
    379 @item
    380 You can use selections in regular text or programming buffers to do
    381 complex editing operations. For example, if you have three
    382 paragraphs scattered over a file and you want to bring them
    383 together, you can select each one, insert them all somewhere and
    384 finally delete all of them (from their original locations).
    385 @end itemize
    387 @node @samp{embark-live} a live-updating variant of @samp{embark-collect}
    388 @subsection @samp{embark-live} a live-updating variant of @samp{embark-collect}
    390 Finally, there is also an @samp{embark-live} variant of the @samp{embark-collect}
    391 command which automatically updates the collection after each change
    392 in the source buffer. Users of a completion UI that automatically
    393 updates and displays the candidate list (such as Vertico, Icomplete,
    394 Fido-mode, or MCT) will probably not want to use
    395 @samp{embark-live} from the minibuffer as they will then have two live
    396 updating displays of the completion candidates!
    398 A more likely use of @samp{embark-live} is to be called from a regular buffer
    399 to display a sort of live updating ``table of contents'' for the buffer.
    400 This depends on having appropriate candidate collectors configured in
    401 @samp{embark-candidate-collectors}. There are not many in Embark's default
    402 configuration, but you can try this experiment: open a dired buffer in
    403 a directory that has very many files, mark a few, and run @samp{embark-live}.
    404 You'll get an Embark Collect buffer containing only the marked files,
    405 which updates as you mark or unmark files in dired. To make
    406 @samp{embark-live} genuinely useful other candidate collectors are required.
    407 The @samp{embark-consult} package (documented near the end of this manual)
    408 contains a few: one for imenu items and one for outline headings as
    409 used by @samp{outline-minor-mode}. Those collectors really do give
    410 @samp{embark-live} a table-of-contents feel.
    412 @node Switching to a different command without losing what you've typed
    413 @section Switching to a different command without losing what you've typed
    415 Embark also has the @samp{embark-become} command which is useful for when
    416 you run a command, start typing at the minibuffer and realize you
    417 meant a different command. The most common case for me is that I run
    418 @samp{switch-to-buffer}, start typing a buffer name and realize I haven't
    419 opened the file I had in mind yet! I'll use this situation as a
    420 running example to illustrate @samp{embark-become}. When this happens I can,
    421 of course, press @samp{C-g} and then run @samp{find-file} and open the file, but
    422 this requires retyping the portion of the file name you already
    423 typed. This process can be streamlined with @samp{embark-become}: while still
    424 in the @samp{switch-to-buffer} you can run @samp{embark-become} and effectively
    425 make the @samp{switch-to-buffer} command become @samp{find-file} for this run.
    427 You can bind @samp{embark-become} to a key in @samp{minibuffer-local-map}, but it is
    428 also available as an action under the letter @samp{B} (uppercase), so you
    429 don't need a binding if you already have one for @samp{embark-act}. So,
    430 assuming I have @samp{embark-act} bound to, say, @samp{C-.}, once I realize I
    431 haven't open the file I can type @samp{C-. B C-x C-f} to have
    432 @samp{switch-to-buffer} become @samp{find-file} without losing what I have already
    433 typed in the minibuffer.
    435 But for even more convenience, @samp{embark-become} offers shorter key
    436 bindings for commands you are likely to want the current command to
    437 become. When you use @samp{embark-become} it looks for the current command in
    438 all keymaps named in the list @samp{embark-become-keymaps} and then activates
    439 all keymaps that contain it. For example, the default value of
    440 @samp{embark-become-keymaps} contains a keymap @samp{embark-become-file+buffer-map}
    441 with bindings for several commands related to files and buffers, in
    442 particular, it binds @samp{switch-to-buffer} to @samp{b} and @samp{find-file} to @samp{f}. So when
    443 I accidentally try to switch to a buffer for a file I haven't opened
    444 yet, @samp{embark-become} finds that the command I ran, @samp{switch-to-buffer}, is
    445 in the keymap @samp{embark-become-file+buffer-map}, so it activates that
    446 keymap (and any others that also contain a binding for
    447 @samp{switch-to-buffer}). The end result is that I can type @samp{C-. B f} to
    448 switch to @samp{find-file}.
    450 @node Quick start
    451 @chapter Quick start
    453 The easiest way to install Embark is from GNU ELPA, just run @samp{M-x
    454 package-install RET embark RET}. (It is also available on MELPA@.) It is
    455 highly recommended to also install @uref{, Marginalia} (also available on GNU
    456 ELPA), so that Embark can offer you preconfigured actions in more
    457 contexts. For @samp{use-package} users, the following is a very reasonable
    458 starting configuration:
    460 @lisp
    461 (use-package marginalia
    462   :ensure t
    463   :config
    464   (marginalia-mode))
    466 (use-package embark
    467   :ensure t
    469   :bind
    470   (("C-." . embark-act)         ;; pick some comfortable binding
    471    ("C-;" . embark-dwim)        ;; good alternative: M-.
    472    ("C-h B" . embark-bindings)) ;; alternative for `describe-bindings'
    474   :init
    476   ;; Optionally replace the key help with a completing-read interface
    477   (setq prefix-help-command #'embark-prefix-help-command)
    479   ;; Show the Embark target at point via Eldoc.  You may adjust the Eldoc
    480   ;; strategy, if you want to see the documentation from multiple providers.
    481   (add-hook 'eldoc-documentation-functions #'embark-eldoc-first-target)
    482   ;; (setq eldoc-documentation-strategy #'eldoc-documentation-compose-eagerly)
    484   :config
    486   ;; Hide the mode line of the Embark live/completions buffers
    487   (add-to-list 'display-buffer-alist
    488                '("\\`\\*Embark Collect \\(Live\\|Completions\\)\\*"
    489                  nil
    490                  (window-parameters (mode-line-format . none)))))
    492 ;; Consult users will also want the embark-consult package.
    493 (use-package embark-consult
    494   :ensure t ; only need to install it, embark loads it after consult if found
    495   :hook
    496   (embark-collect-mode . consult-preview-at-point-mode))
    497 @end lisp
    499 About the suggested key bindings for @samp{embark-act} and @samp{embark-dwim}:
    500 @itemize
    501 @item
    502 Those key bindings are unlikely to work in the terminal, but
    503 terminal users are probably well aware of this and will know to
    504 select different bindings.
    505 @item
    506 The suggested @samp{C-.} binding is used by default in (at least some
    507 installations of) GNOME to input emojis, and Emacs doesn't even get
    508 a chance to respond to the binding. You can select a different key
    509 binding for @samp{embark-act} or use @samp{ibus-setup} to change the shortcut for
    510 emoji insertion (Emacs 29 will likely use @samp{C-x 8 e e}, in case you
    511 want to set the same one system-wide).
    512 @item
    513 The suggested alternative of @samp{M-.} for @samp{embark-dwim} is bound by default
    514 to @samp{xref-find-definitions}. That is a very useful command but
    515 overwriting it with @samp{embark-dwim} is sensible since in Embark's
    516 default configuration, @samp{embark-dwim} will also find the definition of
    517 the identifier at point. (Note that @samp{xref-find-definitions} with a
    518 prefix argument prompts you for an identifier, @samp{embark-dwim} does not
    519 cover this case).
    520 @end itemize
    522 Other Embark commands such as @samp{embark-act-all}, @samp{embark-become},
    523 @samp{embark-collect}, and @samp{embark-export} can be run through @samp{embark-act} as
    524 actions bound to @samp{A}, @samp{B}, @samp{S} (for ``snapshot''), and @samp{E} respectively, and
    525 thus don't really need a dedicated key binding, but feel free to bind
    526 them directly if you so wish. If you do choose to bind them directly,
    527 you'll probably want to bind them in @samp{minibuffer-local-map}, since they
    528 are most useful in the minibuffer (in fact, @samp{embark-become} only works
    529 in the minibuffer).
    531 The command @samp{embark-dwim} executes the default action at point. Another good
    532 keybinding for @samp{embark-dwim} is @samp{M-.} since @samp{embark-dwim} acts like
    533 @samp{xref-find-definitions} on the symbol at point. @samp{C-.} can be seen as a
    534 right-click context menu at point and @samp{M-.} acts like left-click. The
    535 keybindings are mnemonic, both act at the point (@samp{.}).
    537 Embark needs to know what your minibuffer completion system considers
    538 to be the list of candidates and which one is the current candidate.
    539 Embark works out of the box if you use Emacs's default tab completion,
    540 the built-in @samp{icomplete-mode} or @samp{fido-mode}, or the third-party packages
    541 @uref{, Vertico} or @uref{, Ivy}.
    543 If you are a @uref{, Helm} or @uref{, Ivy} user you are unlikely to want Embark since
    544 those packages include comprehensive functionality for acting on
    545 minibuffer completion candidates. (Embark does come with Ivy
    546 integration despite this.)
    548 @node Advanced configuration
    549 @chapter Advanced configuration
    551 @menu
    552 * Showing information about available targets and actions::
    553 * Selecting commands via completions instead of key bindings::
    554 * Quitting the minibuffer after an action::
    555 * Running some setup after injecting the target::
    556 * Running hooks before, after or around an action: Running hooks before after or around an action. 
    557 * Creating your own keymaps::
    558 * Defining actions for new categories of targets::
    559 @end menu
    561 @node Showing information about available targets and actions
    562 @section Showing information about available targets and actions
    564 By default, if you run @samp{embark-act} and do not immediately select an
    565 action, after a short delay Embark will pop up a buffer called @samp{*Embark
    566 Actions*} containing a list of available actions with their key
    567 bindings. You can scroll that buffer with the mouse of with the usual
    568 commands @samp{scroll-other-window} and @samp{scroll-other-window-down} (bound by
    569 default to @samp{C-M-v} and @samp{C-M-S-v}).
    571 That functionality is provided by the @samp{embark-mixed-indicator}, but
    572 Embark has other indicators that can provide information about the
    573 target and its type, what other targets you can cycle to, and which
    574 actions have key bindings in the action map for the current type of
    575 target. Any number of indicators can be active at once and the user
    576 option @samp{embark-indicators} should be set to a list of the desired
    577 indicators.
    579 Embark comes with the following indicators:
    581 @itemize
    582 @item
    583 @samp{embark-minimal-indicator}: shows a messages in the echo area or
    584 minibuffer prompt showing the current target and the types of all
    585 targets starting with the current one; this one is on by default.
    587 @item
    588 @samp{embark-highlight-indicator}: highlights the target at point;
    589 also on by default.
    591 @item
    592 @samp{embark-verbose-indicator}: displays a table of actions and their key
    593 bindings in a buffer; this is not on by default, in favor of the
    594 mixed indicator described next.
    596 @item
    597 @samp{embark-mixed-indicator}: starts out by behaving as the minimal
    598 indicator but after a short delay acts as the verbose indicator;
    599 this is on by default.
    601 @item
    602 @samp{embark-isearch-highlight-indicator}: this only does something when
    603 the current target is the symbol at point, in which case it
    604 lazily highlights all occurrences of that symbol in the current
    605 buffer, like isearch; also on by default.
    606 @end itemize
    608 Users of the popular @uref{, which-key} package may prefer to use the
    609 @samp{embark-which-key-indicator} from the @uref{, Embark wiki}. Just copy its
    610 definition from the wiki into your configuration and customize the
    611 @samp{embark-indicators} user option to exclude the mixed and verbose
    612 indicators and to include @samp{embark-which-key-indicator}.
    614 @node Selecting commands via completions instead of key bindings
    615 @section Selecting commands via completions instead of key bindings
    617 As an alternative to reading the list of actions in the verbose or
    618 mixed indicators (see the previous section for a description of
    619 these), you can press the @samp{embark-help-key}, which is @samp{C-h} by default
    620 (but you may prefer @samp{?} to free up @samp{C-h} for use as a prefix) after
    621 running @samp{embark-act}. Pressing the help key will prompt you for the name
    622 of an action with completion (but feel free to enter a command that is
    623 not among the offered candidates!), and will also remind you of the
    624 key bindings. You can press @samp{embark-keymap-prompter-key}, which is @samp{@@} by
    625 default, at the prompt and then one of the key bindings to enter the
    626 name of the corresponding action.
    628 You may think that with the @samp{*Embark Actions*} buffer popping up to
    629 remind you of the key bindings you'd never want to use completion to
    630 select an action by name, but personally I find that typing a small
    631 portion of the action name to narrow down the list of candidates feels
    632 significantly faster than visually scanning the entire list of actions.
    634 If you find you prefer entering actions that way, you can configure
    635 embark to always prompt you for actions by setting the variable
    636 @samp{embark-prompter} to @samp{embark-completing-read-prompter}.
    638 @node Quitting the minibuffer after an action
    639 @section Quitting the minibuffer after an action
    641 By default, if you call @samp{embark-act} from the minibuffer it quits the
    642 minibuffer after performing the action. You can change this by setting
    643 the user option @samp{embark-quit-after-action} to @samp{nil}. Having @samp{embark-act} @emph{not}
    644 quit the minibuffer can be useful to turn commands into little ``thing
    645 managers''. For example, you can use @samp{find-file} as a little file manager
    646 or @samp{describe-package} as a little package manager: you can run those
    647 commands, perform a series of actions, and then quit the command.
    649 If you want to control the quitting behavior in a fine-grained manner
    650 depending on the action, you can set @samp{embark-quit-after-action} to an
    651 alist, associating commands to either @samp{t} for quitting or @samp{nil} for not
    652 quitting. When using an alist, you can use the special key @samp{t} to
    653 specify the default behavior. For example, to specify that by default
    654 actions should not quit the minibuffer but that using @samp{kill-buffer} as
    655 an action should quit, you can use the following configuration:
    657 @lisp
    658 (setq embark-quit-after-action '((kill-buffer . t) (t . nil)))
    659 @end lisp
    661 The variable @samp{embark-quit-after-action} only specifies a default, that
    662 is, it only controls whether or not @samp{embark-act} quits the minibuffer
    663 when you call it without a prefix argument, and you can select the
    664 opposite behavior to what the variable says by calling @samp{embark-act} with
    665 @samp{C-u}. Also note that both the variable @samp{embark-quit-after-action} and @samp{C-u}
    666 have no effect when you call @samp{embark-act} outside the minibuffer.
    668 If you find yourself using the quitting and non-quitting variants of
    669 @samp{embark-act} about equally often, independently of the action, you may
    670 prefer to simply have separate commands for them instead of a single
    671 command that you call with @samp{C-u} half the time. You could, for example,
    672 keep the default exiting behavior of @samp{embark-act} and define a
    673 non-quitting version as follows:
    675 @lisp
    676 (defun embark-act-noquit ()
    677   "Run action but don't quit the minibuffer afterwards."
    678   (interactive)
    679   (let ((embark-quit-after-action nil))
    680     (embark-act)))
    681 @end lisp
    683 @node Running some setup after injecting the target
    684 @section Running some setup after injecting the target
    686 You can customize what happens after the target is inserted at the
    687 minibuffer prompt of an action. There are
    688 @samp{embark-target-injection-hooks}, that are run by default after injecting
    689 the target into the minibuffer. The variable
    690 @samp{embark-target-injection-hooks} is an alist associating commands to
    691 their setup hooks. There are two special keys: if no setup hook is
    692 specified for a given action, the hook associated to @samp{t} is run; and the
    693 hook associated to @samp{:always} is run regardless of the action. (This
    694 variable used to have the less explicit name of
    695 @samp{embark-setup-action-hooks}, so please update your configuration.)
    697 For example, consider using @samp{shell-command} as an action during file
    698 completion. It would be useful to insert a space before the target
    699 file name and to leave the point at the beginning, so you can
    700 immediately type the shell command to run on that file. That's why in
    701 Embark's default configuration there is an entry in
    702 @samp{embark-target-injection-hooks} associating @samp{shell-command} to a hook that
    703 includes @samp{embark--shell-prep}, a simple helper function that quotes all
    704 the spaces in the file name, inserts an extra space at the beginning
    705 of the line and leaves point to the left of it.
    707 Now, the preparation that @samp{embark--shell-prep} does would be useless if
    708 Embark did what it normally does after it inserts the target of the
    709 action at the minibuffer prompt, which is to ``press @samp{RET}'' for you,
    710 accepting the target as is; if Embark did that for @samp{shell-command} you
    711 wouldn't get a chance to type in the command to execute! That is why
    712 in Embark's default configuration the entry for @samp{shell-command} in
    713 @samp{embark-target-injection-hooks} also contains the function
    714 @samp{embark--allow-edit}.
    716 Embark used to have a dedicated variable @samp{embark-allow-edit-actions} to
    717 which you could add commands for which Embark should forgo pressing
    718 @samp{RET} for you after inserting the target. Since its effect can also be
    719 achieved via the general @samp{embark-target-injection-hooks} mechanism, that
    720 variable has been removed to simply Embark. Be sure to update your
    721 configuration; if you had something like:
    723 @lisp
    724 (add-to-list 'embark-allow-edit-actions 'my-command)
    725 @end lisp
    727 you should replace it with:
    729 @lisp
    730 (push 'embark--allow-edit
    731       (alist-get 'my-command embark-target-injection-hooks))
    732 @end lisp
    735 Also note that while you could abuse @samp{embark--allow-edit} so that you
    736 have to confirm ``dangerous'' actions such as @samp{delete-file}, it is better
    737 to implement confirmation by adding the @samp{embark--confirm} function to
    738 the appropriate entry of a different hook alist, namely,
    739 @samp{embark-pre-action-hooks}.
    741 Besides @samp{embark--allow-edit}, Embark comes with another function that is
    742 of general utility in action setup hooks: @samp{embark--ignore-target}. Use
    743 it for commands that do prompt you in the minibuffer but for which
    744 inserting the target would be inappropriate. This is not a common
    745 situation but does occasionally arise. For example it is used by
    746 default for @samp{shell-command-on-region}: that command is used as an action
    747 for region targets, and it prompts you for a shell command; you
    748 typically do @emph{not} want the target, that is the contents of the region,
    749 to be entered at that prompt!
    751 @node Running hooks before after or around an action
    752 @section Running hooks before, after or around an action
    754 Embark has three variables, @samp{embark-pre-action-hooks},
    755 @samp{embark-post-action-hooks} and @samp{embark-around-action-hooks}, which are
    756 alists associating commands to hooks that should run before or after
    757 or as around advice for the command when used as an action. As with
    758 @samp{embark-target-injection-hooks}, there are two special keys for the
    759 alists: @samp{t} designates the default hook to run when no specific hook is
    760 specified for a command; and the hook associated to @samp{:always} runs
    761 regardless.
    763 The default values of those variables are fairly extensive, adding
    764 creature comforts to make running actions a smooth experience. Embark
    765 comes with several functions intended to be added to these hooks, and
    766 used in the default values of @samp{embark-pre-action-hooks},
    767 @samp{embark-post-action-hooks} and @samp{embark-around-action-hooks}.
    769 For pre-action hooks:
    771 @table @asis
    772 @item @samp{embark--confirm}
    773 Prompt the user for confirmation before executing
    774 the action. This is used be default for commands deemed ``dangerous'',
    775 or, more accurately, hard to undo, such as @samp{delete-file} and
    776 @samp{kill-buffer}.
    778 @item @samp{embark--unmark-target}
    779 Unmark the active region. Use this for
    780 commands you want to act on the region contents but without the
    781 region being active. The default configuration uses this function as
    782 a pre-action hook for @samp{occur} and @samp{query-replace}, for example, so that
    783 you can use them as actions with region targets to search the whole
    784 buffer for the text contained in the region. Without this pre-action
    785 hook using @samp{occur} as an action for a region target would be
    786 pointless: it would search for the the region contents @emph{in the
    787 region}, (typically, due to the details of regexps) finding only one
    788 match!
    790 @item @samp{embark--beginning-of-target}
    791 Move to the beginning of the target
    792 (for targets that report bounds). This is used by default for
    793 backward motion commands such as @samp{backward-sexp}, so that they don't
    794 accidentally leave you on the current target.
    796 @item @samp{embark--end-of-target}
    797 Move to the end of the target. This is used
    798 similarly to the previous function, but also for commands that act
    799 on the last s-expression like @samp{eval-last-sexp}. This allow you to act
    800 on an s-expression from anywhere inside it and still use
    801 @samp{eval-last-sexp} as an action.
    803 @item @samp{embark--xref-push-markers}
    804 Push the current location on the xref
    805 marker stack. Use this for commands that take you somewhere and for
    806 which you'd like to be able to come back to where you were using
    807 @samp{xref-pop-marker-stack}. This is used by default for @samp{find-library}.
    808 @end table
    810 For post-action hooks:
    812 @table @asis
    813 @item @samp{embark--restart}
    814 Restart the command currently prompting in the
    815 minibuffer, so that the list of completion candidates is updated.
    816 This is useful as a post action hook for commands that delete or
    817 rename a completion candidate; for example the default value of
    818 @samp{embark-post-action-hooks} uses it for @samp{delete-file}, @samp{kill-buffer},
    819 @samp{rename-file}, @samp{rename-buffer}, etc.
    820 @end table
    822 For around-action hooks:
    824 @table @asis
    825 @item @samp{embark--mark-target}
    826 Save existing mark and point location, mark
    827 the target and run the action. Most targets at point outside the
    828 minibuffer report which region of the buffer they correspond to
    829 (this is the information used by @samp{embark-highlight-indicator} to
    830 know what portion of the buffer to highlight); this function marks
    831 that region. It is useful as an around action hook for commands that
    832 expect a region to be marked, for example, it is used by default for
    833 @samp{indent-region} so that it works on s-expression targets, or for
    834 @samp{fill-region} so that it works on paragraph targets.
    836 @item @samp{embark--cd}
    837 Run the action with @samp{default-directory} set to the
    838 directory associated to the current target. The target should be of
    839 type @samp{file}, @samp{buffer}, @samp{bookmark} or @samp{library}, and the associated directory
    840 is what you'd expect in each case.
    842 @item @samp{embark--narrow-to-target}
    843 Run the action with buffer narrowed to
    844 current target. Use this as an around hook to localize the effect of
    845 actions that don't already work on just the region. In the default
    846 configuration it is used for @samp{repunctuate-sentences}.
    848 @item @samp{embark--save-excursion}
    849 Run the action restoring point at the end.
    850 The current default configuration doesn't use this but it is
    851 available for users.
    852 @end table
    854 @node Creating your own keymaps
    855 @section Creating your own keymaps
    857 All internal keymaps are defined with the standard helper macro
    858 @samp{defvar-keymap}. For example a simple version of the file action keymap
    859 could be defined as follows:
    861 @lisp
    862 (defvar-keymap embark-file-map
    863   :doc "Example keymap with a few file actions"
    864   :parent embark-general-map
    865   "d" #'delete-file
    866   "r" #'rename-file
    867   "c" #'copy-file)
    868 @end lisp
    870 These action keymaps are perfectly normal Emacs
    871 keymaps.  You may want to inherit from the @samp{embark-general-map} if you
    872 want to access the default Embark actions. Note that @samp{embark-collect}
    873 and @samp{embark-export} are also made available via @samp{embark-general-map}.
    875 @node Defining actions for new categories of targets
    876 @section Defining actions for new categories of targets
    878 It is easy to configure Embark to provide actions for new types of
    879 targets, either in the minibuffer or outside it. I present below two
    880 very detailed examples of how to do this. At several points I'll
    881 explain more than one way to proceed, typically with the easiest
    882 option first. I include the alternative options since there will be
    883 similar situations where the easiest option is not available.
    885 @menu
    886 * New minibuffer target example - tab-bar tabs::
    887 * New target example in regular buffers - short Wikipedia links::
    888 @end menu
    890 @node New minibuffer target example - tab-bar tabs
    891 @subsection New minibuffer target example - tab-bar tabs
    893 As an example, take the new @uref{, tab bars} from Emacs 27. I'll explain how
    894 to configure Embark to offer tab-specific actions when you use the
    895 tab-bar-mode commands that mention tabs by name. The configuration
    896 explained here is now built-in to Embark (and Marginalia), but it's
    897 still a good self-contained example. In order to setup up tab actions
    898 you would need to: (1) make sure Embark knows those commands deal with
    899 tabs, (2) define a keymap for tab actions and configure Embark so it
    900 knows that's the keymap you want.
    902 @enumerate
    903 @item
    904 @anchor{Telling Embark about commands that prompt for tabs by name}Telling Embark about commands that prompt for tabs by name
    907 For step (1), it would be great if the @samp{tab-bar-mode} commands reported
    908 the completion category @samp{tab} when asking you for a tab with
    909 completion. (All built-in Emacs commands that prompt for file names,
    910 for example, do have metadata indicating that they want a @samp{file}.) They
    911 do not, unfortunately, and I will describe a couple of ways to deal
    912 with this.
    914 Maybe the easiest thing is to configure @uref{, Marginalia} to enhance those
    915 commands. All of the @samp{tab-bar-*-tab-by-name} commands have the words
    916 ``tab by name'' in the minibuffer prompt, so you can use:
    918 @lisp
    919 (add-to-list 'marginalia-prompt-categories '("tab by name" . tab))
    920 @end lisp
    922 That's it! But in case you are ever in a situation where you don't
    923 already have commands that prompt for the targets you want, I'll
    924 describe how writing your own command with appropriate @samp{category}
    925 metadata looks:
    927 @lisp
    928 (defun my-select-tab-by-name (tab)
    929   (interactive
    930    (list
    931     (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab)))
    932                                 (tab-bar-tabs))
    933                         (user-error "No tabs found"))))
    934       (completing-read
    935        "Tabs: "
    936        (lambda (string predicate action)
    937          (if (eq action 'metadata)
    938              '(metadata (category . tab))
    939            (complete-with-action
    940             action tab-list string predicate)))))))
    941   (tab-bar-select-tab-by-name tab))
    942 @end lisp
    944 As you can see, the built-in support for setting the category
    945 meta-datum is not very easy to use or pretty to look at. To help with
    946 this I recommend the @samp{consult--read} function from the excellent
    947 @uref{, Consult} package. With that function we can rewrite the command as
    948 follows:
    950 @lisp
    951 (defun my-select-tab-by-name (tab)
    952   (interactive
    953    (list
    954     (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab)))
    955                                 (tab-bar-tabs))
    956                         (user-error "No tabs found"))))
    957       (consult--read tab-list
    958                      :prompt "Tabs: "
    959                      :category 'tab))))
    960   (tab-bar-select-tab-by-name tab))
    961 @end lisp
    963 Much nicer! No matter how you define the @samp{my-select-tab-by-name}
    964 command, the first approach with Marginalia and prompt detection has
    965 the following advantages: you get the @samp{tab} category for all the
    966 @samp{tab-bar-*-bar-by-name} commands at once, also, you enhance built-in
    967 commands, instead of defining new ones.
    969 @item
    970 @anchor{Defining and configuring a keymap for tab actions}Defining and configuring a keymap for tab actions
    973 Let's say we want to offer select, rename and close actions for tabs
    974 (in addition to Embark general actions, such as saving the tab name to
    975 the kill-ring, which you get for free). Then this will do:
    977 @lisp
    978 (defvar-keymap embark-tab-actions
    979   :doc "Keymap for actions for tab-bar tabs (when mentioned by name)."
    980   :parent embark-general-map
    981   "s" #'tab-bar-select-tab-by-name
    982   "r" #'tab-bar-rename-tab-by-name
    983   "k" #'tab-bar-close-tab-by-name)
    985 (add-to-list 'embark-keymap-alist '(tab . embark-tab-actions))
    986 @end lisp
    988 What if after using this for a while you feel closing the tab
    989 without confirmation is dangerous? You have a couple of options:
    991 @enumerate
    992 @item
    993 You can keep using the @samp{tab-bar-close-tab-by-name} command, but have
    994 Embark ask you for confirmation:
    995 @lisp
    996 (push #'embark--confirm
    997       (alist-get 'tab-bar-close-tab-by-name
    998                  embark-pre-action-hooks))
    999 @end lisp
   1001 @item
   1002 You can write your own command that prompts for confirmation and
   1003 use that instead of @samp{tab-bar-close-tab-by-name} in the above keymap:
   1004 @lisp
   1005 (defun my-confirm-close-tab-by-name (tab)
   1006   (interactive "sTab to close: ")
   1007   (when (y-or-n-p (format "Close tab '%s'? " tab))
   1008     (tab-bar-close-tab-by-name tab)))
   1009 @end lisp
   1011 Notice that this is a command you can also use directly from @samp{M-x}
   1012 independently of Embark. Using it from @samp{M-x} leaves something to be
   1013 desired, though, since you don't get completion for the tab names.
   1014 You can fix this if you wish as described in the previous section.
   1015 @end enumerate
   1016 @end enumerate
   1018 @node New target example in regular buffers - short Wikipedia links
   1019 @subsection New target example in regular buffers - short Wikipedia links
   1021 Say you want to teach Embark to treat text of the form
   1022 @samp{wikipedia:Garry_Kasparov} in any regular buffer as a link to Wikipedia,
   1023 with actions to open the Wikipedia page in eww or an external browser
   1024 or to save the URL of the page in the kill-ring. We can take advantage
   1025 of the actions that Embark has preconfigured for URLs, so all we need
   1026 to do is teach Embark that @samp{wikipedia:Garry_Kasparov} stands for the URL
   1027 @samp{}.
   1029 You can be as fancy as you want with the recognized syntax. Here, to
   1030 keep the example simple, I'll assume the link matches the regexp
   1031 @samp{wikipedia:[[:alnum:]_]+}. We will write a function that looks for a
   1032 match surrounding point, and returns a dotted list of the form @samp{'(url
   1033 URL-OF-THE-PAGE START . END)} where @samp{START} and @samp{END} are the buffer
   1034 positions bounding the target, and are used by Embark to highlight it
   1035 if you have @samp{embark-highlight-indicator} included in the list
   1036 @samp{embark-indicators}. (There are a couple of other options for the return
   1037 value of a target finder: the bounding positions are optional and a
   1038 single target finder is allowed to return multiple targets; see the
   1039 documentation for @samp{embark-target-finders} for details.)
   1041 @lisp
   1042 (defun my-short-wikipedia-link ()
   1043   "Target a link at point of the form wikipedia:Page_Name."
   1044   (save-excursion
   1045     (let* ((start (progn (skip-chars-backward "[:alnum:]_:") (point)))
   1046            (end (progn (skip-chars-forward "[:alnum:]_:") (point)))
   1047            (str (buffer-substring-no-properties start end)))
   1048       (save-match-data
   1049         (when (string-match "wikipedia:\\([[:alnum:]_]+\\)" str)
   1050           `(url
   1051             ,(format ""
   1052                      (match-string 1 str))
   1053             ,start . ,end))))))
   1055 (add-to-list 'embark-target-finders 'my-short-wikipedia-link)
   1056 @end lisp
   1058 @node How does Embark call the actions?
   1059 @chapter How does Embark call the actions?
   1061 Embark actions are normal Emacs commands, that is, functions with an
   1062 interactive specification. In order to execute an action, Embark
   1063 calls the command with @samp{call-interactively}, so the command reads user
   1064 input exactly as if run directly by the user. For example the
   1065 command may open a minibuffer and read a string
   1066 (@samp{read-from-minibuffer}) or open a completion interface
   1067 (@samp{completing-read}). If this happens, Embark takes the target string
   1068 and inserts it automatically into the minibuffer, simulating user
   1069 input this way. After inserting the string, Embark exits the
   1070 minibuffer, submitting the input. (The immediate minibuffer exit can
   1071 be disabled for specific actions in order to allow editing the
   1072 input; this is done by adding the @samp{embark--allow-edit} function to the
   1073 appropriate entry of @samp{embark-target-injection-hooks}). Embark inserts
   1074 the target string at the first minibuffer opened by the action
   1075 command, and if the command happens to prompt the user for input
   1076 more than once, the user still interacts with the second and further
   1077 prompts in the normal fashion. Note that if a command does not
   1078 prompt the user for input in the minibuffer, Embark still allows you
   1079 to use it as an action, but of course, never inserts the target
   1080 anywhere. (There are plenty of examples in the default configuration
   1081 of commands that do not prompt the user bound to keys in the action
   1082 maps, most of the region actions, for instance.)
   1084 This is how Embark manages to reuse normal commands as actions. The
   1085 mechanism allows you to use as Embark actions commands that were not
   1086 written with Embark in mind (and indeed almost all actions that are
   1087 bound by default in Embark's action keymaps are standard Emacs
   1088 commands). It also allows you to write new custom actions in such a
   1089 way that they are useful even without Embark.
   1091 Staring from version 28.1, Emacs has a variable
   1092 @samp{y-or-n-p-use-read-key}, which when set to @samp{t} causes @samp{y-or-n-p} to use
   1093 @samp{read-key} instead of @samp{read-from-minibuffer}. Setting
   1094 @samp{y-or-n-p-use-read-key} to @samp{t} is recommended for Embark users because
   1095 it keeps Embark from attempting to insert the target at a @samp{y-or-n-p}
   1096 prompt, which would almost never be sensible. Also consider this as
   1097 a warning to structure your own action commands so that if they use
   1098 @samp{y-or-n-p}, they do so only after the prompting for the target.
   1100 Here is a simple example illustrating the various ways of reading
   1101 input from the user mentioned above. Bind the following commands to
   1102 the @samp{embark-symbol-map} to be used as actions, then put the point on
   1103 some symbol and run them with @samp{embark-act}:
   1105 @lisp
   1106 (defun example-action-command1 ()
   1107   (interactive)
   1108   (message "The input was `%s'." (read-from-minibuffer "Input: ")))
   1110 (defun example-action-command2 (arg input1 input2)
   1111   (interactive "P\nsInput 1: \nsInput 2: ")
   1112   (message "The first input %swas `%s', and the second was `%s'."
   1113            (if arg "truly " "")
   1114            input1
   1115            input2))
   1117 (defun example-action-command3 ()
   1118   (interactive)
   1119   (message "Your selection was `%s'."
   1120            (completing-read "Select: " '("E" "M" "B" "A" "R" "K"))))
   1122 (defun example-action-command4 ()
   1123   (interactive)
   1124   (message "I don't prompt you for input and thus ignore the target!"))
   1126 (keymap-set embark-symbol-map "X 1" #'example-action-command1)
   1127 (keymap-set embark-symbol-map "X 2" #'example-action-command2)
   1128 (keymap-set embark-symbol-map "X 3" #'example-action-command3)
   1129 (keymap-set embark-symbol-map "X 4" #'example-action-command4)
   1130 @end lisp
   1132 Also note that if you are using the key bindings to call actions,
   1133 you can pass prefix arguments to actions in the normal way. For
   1134 example, you can use @samp{C-u X2} with the above demonstration actions to
   1135 make the message printed by @samp{example-action-command2} more emphatic.
   1136 This ability to pass prefix arguments to actions is useful for some
   1137 actions in the default configuration, such as
   1138 @samp{embark-shell-command-on-buffer}.
   1140 @menu
   1141 * Non-interactive functions as actions::
   1142 @end menu
   1144 @node Non-interactive functions as actions
   1145 @section Non-interactive functions as actions
   1147 Alternatively, Embark does support one other type of action: a
   1148 non-interactive function of a single argument. The target is passed
   1149 as argument to the function. For example:
   1151 @lisp
   1152 (defun example-action-function (target)
   1153   (message "The target was `%s'." target))
   1155 (keymap-set embark-symbol-map "X 4" #'example-action-function)
   1156 @end lisp
   1158 Note that normally binding non-interactive functions in a keymap is
   1159 useless, since when attempting to run them using the key binding you
   1160 get an error message similar to ``Wrong type argument: commandp,
   1161 example-action-function''. In general it is more flexible to write
   1162 any new Embark actions as commands, that is, as interactive
   1163 functions, because that way you can also run them directly, without
   1164 Embark. But there are a couple of reasons to use non-interactive
   1165 functions as actions:
   1167 @enumerate
   1168 @item
   1169 You may already have the function lying around, and it is
   1170 convenient to simply reuse it.
   1172 @item
   1173 For command actions the targets can only be simple string, with
   1174 no text properties. For certain advanced uses you may want the
   1175 action to receive a string @emph{with} some text properties, or even a
   1176 non-string target.
   1177 @end enumerate
   1179 @node Embark Marginalia and Consult
   1180 @chapter Embark, Marginalia and Consult
   1182 Embark cooperates well with the @uref{, Marginalia} and @uref{, Consult} packages.
   1183 Neither of those packages is a dependency of Embark, but both are
   1184 highly recommended companions to Embark, for opposite reasons:
   1185 Marginalia greatly enhances Embark's usefulness, while Embark can help
   1186 enhance Consult.
   1188 In the remainder of this section I'll explain what exactly Marginalia
   1189 does for Embark, and what Embark can do for Consult.
   1191 @menu
   1192 * Marginalia::
   1193 * Consult::
   1194 @end menu
   1196 @node Marginalia
   1197 @section Marginalia
   1199 Embark comes with actions for symbols (commands, functions, variables
   1200 with actions such as finding the definition, looking up the
   1201 documentation, evaluating, etc.) in the @samp{embark-symbol-map} keymap, and
   1202 for packages (actions like install, delete, browse url, etc.) in the
   1203 @samp{embark-package-keymap}.
   1205 Unfortunately Embark does not automatically offers you these keymaps
   1206 when relevant, because many built-in Emacs commands don't report
   1207 accurate category metadata. For example, a command like
   1208 @samp{describe-package}, which reads a package name from the minibuffer,
   1209 does not have metadata indicating this fact.
   1211 In an earlier Embark version, there were functions to supply this
   1212 missing metadata, but they have been moved to Marginalia, which
   1213 augments many Emacs command to report accurate category metadata.
   1214 Simply activating @samp{marginalia-mode} allows Embark to offer you the
   1215 package and symbol actions when appropriate again. Candidate
   1216 annotations in the Embark collect buffer are also provided by the
   1217 Marginalia package:
   1219 @itemize
   1220 @item
   1221 If you install Marginalia and activate @samp{marginalia-mode}, Embark
   1222 Collect buffers will use the Marginalia annotations automatically.
   1224 @item
   1225 If you don't install Marginalia, you will see only the annotations
   1226 that come with Emacs (such as key bindings in @samp{M-x}, or the unicode
   1227 characters in @samp{C-x 8 RET}).
   1228 @end itemize
   1230 @node Consult
   1231 @section Consult
   1233 The excellent Consult package provides many commands that use
   1234 minibuffer completion, via the @samp{completing-read} function; plenty of its
   1235 commands can be considered enhanced versions of built-in Emacs
   1236 commands, and some are completely new functionality. One common
   1237 enhancement provided in all commands for which it makes sense is
   1238 preview functionality, for example @samp{consult-buffer} will show you a
   1239 quick preview of a buffer before you actually switch to it.
   1241 If you use both Consult and Embark you should install the
   1242 @samp{embark-consult} package which provides integration between the two. It
   1243 provides exporters for several Consult commands and also tweaks the
   1244 behavior of many Consult commands when used as actions with @samp{embark-act}
   1245 in subtle ways that you may not even notice, but make for a smoother
   1246 experience. You need only install it to get these benefits: Embark
   1247 will automatically load it after Consult if found.
   1249 The @samp{embark-consult} package provides the following exporters:
   1251 @itemize
   1252 @item
   1253 You can use @samp{embark-export} from @samp{consult-line}, @samp{consult-outline}, or
   1254 @samp{consult-mark} to obtain an @samp{occur-mode} buffer. As with the built-in
   1255 @samp{occur} command you use that buffer to jump to a match and after that,
   1256 you can then use @samp{next-error} and @samp{previous-error} to navigate to other
   1257 matches. You can also press @samp{e} to activate @samp{occur-edit-mode} and edit
   1258 the matches in place!
   1260 @item
   1261 You can export from any of the Consult asynchronous search commands,
   1262 @samp{consult-grep}, @samp{consult-git-grep}, or @samp{consult-ripgrep} to get a
   1263 @samp{grep-mode} buffer. Here too you can use @samp{next-error} and @samp{previous-error}
   1264 to navigate among matches, and, if you install the @uref{ , wgrep} package,
   1265 you can use it to edit the matches in place.
   1266 @end itemize
   1268 In both cases, pressing @samp{g} will rerun the Consult command you had
   1269 exported from and re-enter the input you had typed (which is similar
   1270 to reverting but a little more flexible). You can then proceed to
   1271 re-export if that's what you want, but you can also edit the input
   1272 changing the search terms or simply cancel if you see you are done
   1273 with that search.
   1275 The @samp{embark-consult} also contains some candidates collectors that allow
   1276 you to run @samp{embark-live} to get a live-updating table of contents for
   1277 your buffer:
   1279 @itemize
   1280 @item
   1281 @samp{embark-consult-outline-candidates} produces the outline headings of
   1282 the current buffer, using @samp{consult-outline}.
   1283 @item
   1284 @samp{embark-consult-imenu-candidates} produces the imenu items of
   1285 the current buffer, using @samp{consult-imenu}.
   1286 @item
   1287 @samp{embark-consult-imenu-or-outline-candidates} is a simple combination
   1288 of the two previous functions: it produces imenu items in buffers
   1289 deriving from @samp{prog-mode} and otherwise outline headings.
   1290 @end itemize
   1292 The way to configure @samp{embark-live} (or @samp{embark-collect} and @samp{embark-export}
   1293 for that matter) to use one of these function is to add it at the end
   1294 of the @samp{embark-candidate-collectors} list. The @samp{embark-consult} package by
   1295 default adds the last one, which seems to be the most sensible
   1296 default.
   1298 Besides those exporters and candidate collectors, the @samp{embark-consult}
   1299 package provides many subtle tweaks and small integrations between
   1300 Embark and Consult. Some examples are:
   1302 @itemize
   1303 @item
   1304 The asynchronous search commands will start in the directory
   1305 associated to the Embark target if that target is a file, buffer,
   1306 bookmark or Emacs Lisp library.
   1308 @itemize
   1309 @item
   1310 For all other target types, a Consult search command (asynchronous
   1311 or not) will search for the text of the target but leave the
   1312 minibuffer open so you can interact with the Consult command.
   1313 @end itemize
   1315 @item
   1316 @samp{consult-imenu} will search for the target and take you directly to
   1317 the location if it matches a unique imenu entry, otherwise it will
   1318 leave the minibuffer open so you can navigate among the matches.
   1319 @end itemize
   1321 @node Resources
   1322 @chapter Resources
   1324 If you want to learn more about how others have used Embark here are
   1325 some links to read:
   1327 @itemize
   1328 @item
   1329 @uref{, Fifteen ways to use Embark}, a blog post by Karthik Chikmagalur.
   1330 @item
   1331 @uref{, Protesilaos Stavrou's dotemacs}, look for the section called
   1332 ``Extended minibuffer actions and more (embark.el and
   1333 prot-embark.el)''
   1334 @end itemize
   1336 And some videos to watch:
   1338 @itemize
   1339 @item
   1340 @uref{, Embark and my extras} by Protesilaos Stavrou.
   1341 @item
   1342 @uref{, Embark -- Key features and tweaks} by Raoul Comninos on the
   1343 Emacs-Elements YouTube channel.
   1344 @item
   1345 @uref{, Livestreamed: Adding an Embark context action to send a stream
   1346 message} by Sacha Chua.
   1347 @item
   1348 @uref{, System Crafters Live! - The Many Uses of Embark} by David Wilson.
   1349 @item
   1350 @uref{, Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark} by
   1351 Mike Zamansky.
   1352 @end itemize
   1354 @node Contributions
   1355 @chapter Contributions
   1357 Contributions to Embark are very welcome. There is a @uref{, wish list} for
   1358 actions, target finders, candidate collectors and exporters. For other
   1359 ideas you have for Embark, feel free to open an issue on the @uref{, issue
   1360 tracker}. Any neat configuration tricks you find might be a good fit
   1361 for the @uref{, wiki}.
   1363 Code contributions are very welcome too, but since Embark is now on
   1364 GNU ELPA, copyright assignment to the FSF is required before you can
   1365 contribute code.
   1367 @node Acknowledgments
   1368 @chapter Acknowledgments
   1370 While I, Omar Antolín Camarena, have written most of the Embark code
   1371 and remain very stubborn about some of the design decisions, Embark
   1372 has received substantial help from a number of other people which this
   1373 document has neglected to mention for far too long. In particular,
   1374 Daniel Mendler has been absolutely invaluable, implementing several
   1375 important features, and providing a lot of useful advice.
   1377 Code contributions:
   1379 @itemize
   1380 @item
   1381 @uref{, Daniel Mendler}
   1382 @item
   1383 @uref{, Clemens Radermacher}
   1384 @item
   1385 @uref{, José Antonio Ortega Ruiz}
   1386 @item
   1387 @uref{, Itai Y@. Efrat}
   1388 @item
   1389 @uref{, a13}
   1390 @item
   1391 @uref{, jakanakaevangeli}
   1392 @item
   1393 @uref{, mihakam}
   1394 @item
   1395 @uref{, Brian Leung}
   1396 @item
   1397 @uref{, Karthik Chikmagalur}
   1398 @item
   1399 @uref{, Roshan Shariff}
   1400 @item
   1401 @uref{, condy0919}
   1402 @item
   1403 @uref{, Damien Cassou}
   1404 @item
   1405 @uref{, JimDBh}
   1406 @end itemize
   1408 Advice and useful discussions:
   1410 @itemize
   1411 @item
   1412 @uref{, Daniel Mendler}
   1413 @item
   1414 @uref{, Protesilaos Stavrou}
   1415 @item
   1416 @uref{, Clemens Radermacher}
   1417 @item
   1418 @uref{, Howard Melman}
   1419 @item
   1420 @uref{, Augusto Stoffel}
   1421 @item
   1422 @uref{, Bruce d'Arcus}
   1423 @item
   1424 @uref{, JD Smith}
   1425 @item
   1426 @uref{, Karthik Chikmagalur}
   1427 @item
   1428 @uref{, jakanakaevangeli}
   1429 @item
   1430 @uref{, Itai Y@. Efrat}
   1431 @item
   1432 @uref{, Mohsin Kaleem}
   1433 @end itemize
   1435 @bye