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: