dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

embark.info (69158B)


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