embark.texi (63528B)
1 \input texinfo @c -*- texinfo -*- 2 @c %**start of header 3 @setfilename embark.info 4 @settitle Embark: Emacs Mini-Buffer Actions Rooted in Keymaps 5 @documentencoding UTF-8 6 @documentlanguage en 7 @c %**end of header 8 9 @dircategory Emacs misc features 10 @direntry 11 * Embark: (embark). Emacs Mini-Buffer Actions Rooted in Keymaps. 12 @end direntry 13 14 @finalout 15 @titlepage 16 @title Embark: Emacs Mini-Buffer Actions Rooted in Keymaps 17 @author Omar Antolín Camarena 18 @end titlepage 19 20 @contents 21 22 @ifnottex 23 @node Top 24 @top Embark: Emacs Mini-Buffer Actions Rooted in Keymaps 25 @end ifnottex 26 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:: 36 37 @detailmenu 38 --- The Detailed Node Listing --- 39 40 Overview 41 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:: 46 47 Working with sets of possible targets 48 49 * Selecting some targets to make an ad hoc candidate set:: 50 * @samp{embark-live} a live-updating variant of @samp{embark-collect}:: 51 52 Advanced configuration 53 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:: 61 62 Defining actions for new categories of targets 63 64 * New minibuffer target example - tab-bar tabs:: 65 * New target example in regular buffers - short Wikipedia links:: 66 67 How does Embark call the actions? 68 69 * Non-interactive functions as actions:: 70 71 Embark, Marginalia and Consult 72 73 * Marginalia:: 74 * Consult:: 75 76 @end detailmenu 77 @end menu 78 79 @node Overview 80 @chapter Overview 81 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. 97 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 104 105 @node Acting on targets 106 @section Acting on targets 107 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: 112 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 123 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: 128 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 147 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}. 156 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. 161 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}. 174 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. 186 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). 193 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{https://github.com/minad/marginalia, Marginalia} package, which supplies 202 this missing metadata, is highly recommended for use with Embark. 203 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{https://github.com/oantolin/embark/wiki/Default-Actions, default actions and their key bindings} on the GitHub 208 project wiki. 209 210 @node The default action on a target 211 @section The default action on a target 212 213 Embark has a notion of default action for a target: 214 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 229 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. 234 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: 238 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 257 258 @node Working with sets of possible targets 259 @section Working with sets of possible targets 260 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: 266 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}.) 275 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. 280 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. 290 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. 297 298 If you use the grepping commands from the @uref{https://github.com/minad/consult/, 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{https://github.com/mhayashi1120/Emacs-wgrep, wgrep} if you wish. 303 @end itemize 304 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}. 311 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}. 318 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. 327 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 332 333 @node Selecting some targets to make an ad hoc candidate set 334 @subsection Selecting some targets to make an ad hoc candidate set 335 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. 343 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. 352 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. 358 359 This functionality is supported everywhere: 360 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 386 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} 389 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! 397 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. 411 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 414 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. 426 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. 434 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}. 449 450 @node Quick start 451 @chapter Quick start 452 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{https://github.com/minad/marginalia, 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: 459 460 @lisp 461 (use-package marginalia 462 :ensure t 463 :config 464 (marginalia-mode)) 465 466 (use-package embark 467 :ensure t 468 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' 473 474 :init 475 476 ;; Optionally replace the key help with a completing-read interface 477 (setq prefix-help-command #'embark-prefix-help-command) 478 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) 483 484 :config 485 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))))) 491 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 498 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 521 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). 530 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{.}). 536 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{https://github.com/minad/vertico, Vertico} or @uref{https://github.com/abo-abo/swiper, Ivy}. 542 543 If you are a @uref{https://emacs-helm.github.io/helm/, Helm} or @uref{https://github.com/abo-abo/swiper, 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.) 547 548 @node Advanced configuration 549 @chapter Advanced configuration 550 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 560 561 @node Showing information about available targets and actions 562 @section Showing information about available targets and actions 563 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}). 570 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. 578 579 Embark comes with the following indicators: 580 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. 586 587 @item 588 @samp{embark-highlight-indicator}: highlights the target at point; 589 also on by default. 590 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. 595 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. 600 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 607 608 Users of the popular @uref{https://github.com/justbur/emacs-which-key, which-key} package may prefer to use the 609 @samp{embark-which-key-indicator} from the @uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt, 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}. 613 614 @node Selecting commands via completions instead of key bindings 615 @section Selecting commands via completions instead of key bindings 616 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. 627 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. 633 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}. 637 638 @node Quitting the minibuffer after an action 639 @section Quitting the minibuffer after an action 640 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. 648 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: 656 657 @lisp 658 (setq embark-quit-after-action '((kill-buffer . t) (t . nil))) 659 @end lisp 660 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. 667 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: 674 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 682 683 @node Running some setup after injecting the target 684 @section Running some setup after injecting the target 685 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.) 696 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. 706 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}. 715 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: 722 723 @lisp 724 (add-to-list 'embark-allow-edit-actions 'my-command) 725 @end lisp 726 727 you should replace it with: 728 729 @lisp 730 (push 'embark--allow-edit 731 (alist-get 'my-command embark-target-injection-hooks)) 732 @end lisp 733 734 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}. 740 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! 750 751 @node Running hooks before after or around an action 752 @section Running hooks before, after or around an action 753 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. 762 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}. 768 769 For pre-action hooks: 770 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}. 777 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! 789 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. 795 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. 802 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 809 810 For post-action hooks: 811 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 821 822 For around-action hooks: 823 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. 835 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. 841 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}. 847 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 853 854 @node Creating your own keymaps 855 @section Creating your own keymaps 856 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: 860 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 869 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}. 874 875 @node Defining actions for new categories of targets 876 @section Defining actions for new categories of targets 877 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. 884 885 @menu 886 * New minibuffer target example - tab-bar tabs:: 887 * New target example in regular buffers - short Wikipedia links:: 888 @end menu 889 890 @node New minibuffer target example - tab-bar tabs 891 @subsection New minibuffer target example - tab-bar tabs 892 893 As an example, take the new @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Tab-Bars.html, 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. 901 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 905 906 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. 913 914 Maybe the easiest thing is to configure @uref{https://github.com/minad/marginalia, 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: 917 918 @lisp 919 (add-to-list 'marginalia-prompt-categories '("tab by name" . tab)) 920 @end lisp 921 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: 926 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 943 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{https://github.com/minad/consult/, Consult} package. With that function we can rewrite the command as 948 follows: 949 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 962 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. 968 969 @item 970 @anchor{Defining and configuring a keymap for tab actions}Defining and configuring a keymap for tab actions 971 972 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: 976 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) 984 985 (add-to-list 'embark-keymap-alist '(tab . embark-tab-actions)) 986 @end lisp 987 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: 990 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 1000 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 1010 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 1017 1018 @node New target example in regular buffers - short Wikipedia links 1019 @subsection New target example in regular buffers - short Wikipedia links 1020 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{https://en.wikipedia.org/wiki/Garry_Kasparov}. 1028 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.) 1040 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 "https://en.wikipedia.org/wiki/%s" 1052 (match-string 1 str)) 1053 ,start . ,end)))))) 1054 1055 (add-to-list 'embark-target-finders 'my-short-wikipedia-link) 1056 @end lisp 1057 1058 @node How does Embark call the actions? 1059 @chapter How does Embark call the actions? 1060 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.) 1083 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. 1090 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. 1099 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}: 1104 1105 @lisp 1106 (defun example-action-command1 () 1107 (interactive) 1108 (message "The input was `%s'." (read-from-minibuffer "Input: "))) 1109 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)) 1116 1117 (defun example-action-command3 () 1118 (interactive) 1119 (message "Your selection was `%s'." 1120 (completing-read "Select: " '("E" "M" "B" "A" "R" "K")))) 1121 1122 (defun example-action-command4 () 1123 (interactive) 1124 (message "I don't prompt you for input and thus ignore the target!")) 1125 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 1131 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}. 1139 1140 @menu 1141 * Non-interactive functions as actions:: 1142 @end menu 1143 1144 @node Non-interactive functions as actions 1145 @section Non-interactive functions as actions 1146 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: 1150 1151 @lisp 1152 (defun example-action-function (target) 1153 (message "The target was `%s'." target)) 1154 1155 (keymap-set embark-symbol-map "X 4" #'example-action-function) 1156 @end lisp 1157 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: 1166 1167 @enumerate 1168 @item 1169 You may already have the function lying around, and it is 1170 convenient to simply reuse it. 1171 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 1178 1179 @node Embark Marginalia and Consult 1180 @chapter Embark, Marginalia and Consult 1181 1182 Embark cooperates well with the @uref{https://github.com/minad/marginalia, Marginalia} and @uref{https://github.com/minad/consult, 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. 1187 1188 In the remainder of this section I'll explain what exactly Marginalia 1189 does for Embark, and what Embark can do for Consult. 1190 1191 @menu 1192 * Marginalia:: 1193 * Consult:: 1194 @end menu 1195 1196 @node Marginalia 1197 @section Marginalia 1198 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}. 1204 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. 1210 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: 1218 1219 @itemize 1220 @item 1221 If you install Marginalia and activate @samp{marginalia-mode}, Embark 1222 Collect buffers will use the Marginalia annotations automatically. 1223 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 1229 1230 @node Consult 1231 @section Consult 1232 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. 1240 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. 1248 1249 The @samp{embark-consult} package provides the following exporters: 1250 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! 1259 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{http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el , wgrep} package, 1265 you can use it to edit the matches in place. 1266 @end itemize 1267 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. 1274 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: 1278 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 1291 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. 1297 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: 1301 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. 1307 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 1314 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 1320 1321 @node Resources 1322 @chapter Resources 1323 1324 If you want to learn more about how others have used Embark here are 1325 some links to read: 1326 1327 @itemize 1328 @item 1329 @uref{https://karthinks.com/software/fifteen-ways-to-use-embark/, Fifteen ways to use Embark}, a blog post by Karthik Chikmagalur. 1330 @item 1331 @uref{https://protesilaos.com/dotemacs/, 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 1335 1336 And some videos to watch: 1337 1338 @itemize 1339 @item 1340 @uref{https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/, Embark and my extras} by Protesilaos Stavrou. 1341 @item 1342 @uref{https://youtu.be/qpoQiiinCtY, Embark -- Key features and tweaks} by Raoul Comninos on the 1343 Emacs-Elements YouTube channel. 1344 @item 1345 @uref{https://youtu.be/WsxXr1ncukY, Livestreamed: Adding an Embark context action to send a stream 1346 message} by Sacha Chua. 1347 @item 1348 @uref{https://youtu.be/qk2Is_sC8Lk, System Crafters Live! - The Many Uses of Embark} by David Wilson. 1349 @item 1350 @uref{https://youtu.be/5ffb2at2d7w, Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark} by 1351 Mike Zamansky. 1352 @end itemize 1353 1354 @node Contributions 1355 @chapter Contributions 1356 1357 Contributions to Embark are very welcome. There is a @uref{https://github.com/oantolin/embark/issues/95, 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{https://github.com/oantolin/embark/issues, issue 1360 tracker}. Any neat configuration tricks you find might be a good fit 1361 for the @uref{https://github.com/oantolin/embark/wiki, wiki}. 1362 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. 1366 1367 @node Acknowledgments 1368 @chapter Acknowledgments 1369 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. 1376 1377 Code contributions: 1378 1379 @itemize 1380 @item 1381 @uref{https://github.com/minad, Daniel Mendler} 1382 @item 1383 @uref{https://github.com/clemera/, Clemens Radermacher} 1384 @item 1385 @uref{https://codeberg.org/jao/, José Antonio Ortega Ruiz} 1386 @item 1387 @uref{https://github.com/iyefrat, Itai Y@. Efrat} 1388 @item 1389 @uref{https://github.com/a13, a13} 1390 @item 1391 @uref{https://github.com/jakanakaevangeli, jakanakaevangeli} 1392 @item 1393 @uref{https://github.com/mihakam, mihakam} 1394 @item 1395 @uref{https://github.com/leungbk, Brian Leung} 1396 @item 1397 @uref{https://github.com/karthink, Karthik Chikmagalur} 1398 @item 1399 @uref{https://github.com/roshanshariff, Roshan Shariff} 1400 @item 1401 @uref{https://github.com/condy0919, condy0919} 1402 @item 1403 @uref{https://github.com/DamienCassou, Damien Cassou} 1404 @item 1405 @uref{https://github.com/JimDBh, JimDBh} 1406 @end itemize 1407 1408 Advice and useful discussions: 1409 1410 @itemize 1411 @item 1412 @uref{https://github.com/minad, Daniel Mendler} 1413 @item 1414 @uref{https://gitlab.com/protesilaos/, Protesilaos Stavrou} 1415 @item 1416 @uref{https://github.com/clemera/, Clemens Radermacher} 1417 @item 1418 @uref{https://github.com/hmelman/, Howard Melman} 1419 @item 1420 @uref{https://github.com/astoff, Augusto Stoffel} 1421 @item 1422 @uref{https://github.com/bdarcus, Bruce d'Arcus} 1423 @item 1424 @uref{https://github.com/jdtsmith, JD Smith} 1425 @item 1426 @uref{https://github.com/karthink, Karthik Chikmagalur} 1427 @item 1428 @uref{https://github.com/jakanakaevangeli, jakanakaevangeli} 1429 @item 1430 @uref{https://github.com/iyefrat, Itai Y@. Efrat} 1431 @item 1432 @uref{https://github.com/mohkale, Mohsin Kaleem} 1433 @end itemize 1434 1435 @bye