Merge pull request #587 from minad/keymap-fixes

Keymap fixes

Author: oantolin

README.org

@@ -388,23 +388,23 @@ Embark comes with the following indicators:
 - =embark-minimal-indicator=: shows a messages in the echo area or
   minibuffer prompt showing the current target and the types of all
   targets starting with the current one; this one is on by default.
-  
+
 - =embark-highlight-indicator=: highlights the target at point;
   also on by default.
-  
+
 - =embark-verbose-indicator=: displays a table of actions and their key
   bindings in a buffer; this is not on by default, in favor of the
   mixed indicator described next.
-  
+
 - =embark-mixed-indicator=: starts out by behaving as the minimal
   indicator but after a short delay acts as the verbose indicator;
   this is on by default.
-  
+
 - =embark-isearch-highlight-indicator=: this only does something when
   the current target is the symbol at point, in which case it
   lazily highlights all occurrences of that symbol in the current
   buffer, like isearch; also on by default.
-  
+
 Users of the popular [[https://github.com/justbur/emacs-which-key][which-key]] package may prefer to use the
 =embark-which-key-indicator= from the [[https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt][Embark wiki]]. Just copy its
 definition from the wiki into your configuration and customize the
@@ -633,24 +633,23 @@ For around-action hooks:
 
 ** Creating your own keymaps
 
-All internal keymaps are defined with a helper macro
-=embark-define-keymap= that you can use to define your own keymaps,
-whether they are for new categories in =embark-keymap-alist= or for any
-other purpose! For example a simple version of the file action keymap
+All internal keymaps are defined with the standard helper macro
+=defvar-keymap=. For example a simple version of the file action keymap
 could be defined as follows:
 
 #+BEGIN_SRC emacs-lisp
-  (embark-define-keymap embark-file-map
-    "Example keymap with a few file actions"
-    ("d" delete-file)
-    ("r" rename-file)
-    ("c" copy-file))
+  (defvar-keymap embark-file-map
+    :doc "Example keymap with a few file actions"
+    :parent embark-general-map
+    "d" #'delete-file
+    "r" #'rename-file
+    "c" #'copy-file)
 #+END_SRC
 
-Remember also that these action keymaps are perfectly normal Emacs
-keymaps, and do not need to be created with this helper macro. You
-can use the built-in =define-key=, or your favorite external package
-such as =bind-key= or =general.el= to manage them.
+These action keymaps are perfectly normal Emacs
+keymaps.  You may want to inherit from the =embark-general-map= if you
+want to access the default Embark actions. Note that =embark-collect=
+and =embark-export= are also made available via =embark-general-map=.
 
 ** Defining actions for new categories of targets
 
@@ -743,11 +742,12 @@ commands, instead of defining new ones.
  the kill-ring, which you get for free). Then this will do:
 
  #+begin_src emacs-lisp
-   (embark-define-keymap embark-tab-actions
-     "Keymap for actions for tab-bar tabs (when mentioned by name)."
-     ("s" tab-bar-select-tab-by-name)
-     ("r" tab-bar-rename-tab-by-name)
-     ("k" tab-bar-close-tab-by-name))
+   (defvar-keymap embark-tab-actions
+     :doc "Keymap for actions for tab-bar tabs (when mentioned by name)."
+     :parent embark-general-map
+     "s" #'tab-bar-select-tab-by-name
+     "r" #'tab-bar-rename-tab-by-name
+     "k" #'tab-bar-close-tab-by-name)
 
    (add-to-list 'embark-keymap-alist '(tab . embark-tab-actions))
  #+end_src
@@ -805,7 +805,7 @@ included in the list =embark-indicators=).
              (str (buffer-substring-no-properties beg end)))
         (save-match-data
           (when (string-match "wikipedia:\\([[:alnum:]_]+\\)" str)
-            `(url 
+            `(url
               ,(format "https://en.wikipedia.org/wiki/%s"
                        (match-string 1 str))
               ,beg . ,end))))))
@@ -853,7 +853,7 @@ included in the list =embark-indicators=).
   prompt, which would almost never be sensible. Also consider this as
   a warning to structure your own action commands so that if they use
   =y-or-n-p=, they do so only after the prompting for the target.
-  
+
   Here is a simple example illustrating the various ways of reading
   input from the user mentioned above. Bind the following commands to
   the =embark-symbol-map= to be used as actions, then put the point on
@@ -863,27 +863,27 @@ included in the list =embark-indicators=).
     (defun example-action-command1 ()
       (interactive)
       (message "The input was `%s'." (read-from-minibuffer "Input: ")))
-    
+
     (defun example-action-command2 (arg input1 input2)
       (interactive "P\nsInput 1: \nsInput 2: ")
       (message "The first input %swas `%s', and the second was `%s'."
                (if arg "truly " "")
                input1
                input2))
-    
+
     (defun example-action-command3 ()
       (interactive)
       (message "Your selection was `%s'."
                (completing-read "Select: " '("E" "M" "B" "A" "R" "K"))))
-    
+
     (defun example-action-command4 ()
       (interactive)
       (message "I don't prompt you for input and thus ignore the target!"))
-    
-    (define-key embark-symbol-map "X1" #'example-action-command1)
-    (define-key embark-symbol-map "X2" #'example-action-command2)
-    (define-key embark-symbol-map "X3" #'example-action-command3)
-    (define-key embark-symbol-map "X4" #'example-action-command4)
+
+    (keymap-set embark-symbol-map "X 1" #'example-action-command1)
+    (keymap-set embark-symbol-map "X 2" #'example-action-command2)
+    (keymap-set embark-symbol-map "X 3" #'example-action-command3)
+    (keymap-set embark-symbol-map "X 4" #'example-action-command4)
   #+end_src
 
   Also note that if you are using the key bindings to call actions,
@@ -893,9 +893,9 @@ included in the list =embark-indicators=).
   This ability to pass prefix arguments to actions is useful for some
   actions in the default configuration, such as
   =embark-shell-command-on-buffer=.
-  
+
 ** Non-interactive functions as actions
-   
+
   Alternatively, Embark does support one other type of action: a
   non-interactive function of a single argument. The target is passed
   as argument to the function. For example:
@@ -904,7 +904,7 @@ included in the list =embark-indicators=).
     (defun example-action-function (target)
       (message "The target was `%s'." target))
 
-    (define-key embark-symbol-map "X4" #'example-action-function)
+    (keymap-set embark-symbol-map "X 4" #'example-action-function)
   #+end_src
 
   Note that normally binding non-interactive functions in a keymap is
@@ -923,7 +923,7 @@ included in the list =embark-indicators=).
      no text properties. For certain advanced uses you may want the
      action to receive a string /with/ some text properties, or even a
      non-string target.
-  
+
 * Embark, Marginalia and Consult
 
 Embark cooperates well with the [[https://github.com/minad/marginalia][Marginalia]] and [[https://github.com/minad/consult][Consult]] packages.
@@ -1043,7 +1043,7 @@ behavior of Consult commands when used as Embark actions are:
 - =consult-imenu= will search for the target and take you directly to
   the location if it matches a unique imenu entry, otherwise it will
   leave the minibuffer open so you can navigate among the matches.
-   
+
 * Resources
 
 If you want to learn more about how others have used Embark here are

embark-consult.el

@@ -7,7 +7,7 @@
 ;; Keywords: convenience
 ;; Version: 0.6
 ;; Homepage: https://github.com/oantolin/embark
-;; Package-Requires: ((emacs "27.1") (embark "0.17") (consult "0.17"))
+;; Package-Requires: ((emacs "27.1") (embark "0.20") (consult "0.17"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -24,7 +24,7 @@
 
 ;;; Commentary:
 
-;; This package provides integration between Embark and Consult. The package
+;; This package provides integration between Embark and Consult.  The package
 ;; will be loaded automatically by Embark.
 
 ;; Some of the functionality here was previously contained in Embark
@@ -45,7 +45,7 @@
 ;; Additionally this package contains some functionality that has
 ;; never been in Embark: access to Consult preview from auto-updating
 ;; Embark Collect buffer that is associated to an active minibuffer
-;; for a Consult command. For information on Consult preview, see
+;; for a Consult command.  For information on Consult preview, see
 ;; Consult's info manual or its readme on GitHub.
 
 ;; If you always want the minor mode enabled whenever it possible use:
@@ -55,7 +55,7 @@
 ;; If you don't want the minor mode automatically on and prefer to
 ;; trigger the consult previews manually use this instead:
 
-;; (define-key embark-collect-mode-map (kbd "C-j")
+;; (keymap-set embark-collect-mode-map "C-j"
 ;;   #'consult-preview-at-point)
 
 ;;; Code:
@@ -160,10 +160,10 @@ This function is meant to be added to `embark-collect-mode-hook'."
 (defvar wgrep-header/footer-parser)
 (declare-function wgrep-setup "ext:wgrep")
 
-(embark-define-keymap embark-consult-revert-map
-  "A keymap with a binding for revert-buffer."
+(defvar-keymap embark-consult-revert-map
+  :doc "A keymap with a binding for revert-buffer."
   :parent nil
-  ("g" revert-buffer))
+  "g" #'revert-buffer)
 
 (defun embark-consult-export-grep (lines)
   "Create a grep mode buffer listing LINES."
@@ -276,6 +276,7 @@ This function is meant to be added to `embark-collect-mode-hook'."
 ;;; Support for consult-man and consult-info
 
 (defun embark-consult-man (cand)
+  "Default action override for `consult-man', open CAND man page."
   (man (get-text-property 0 'consult-man cand)))
 
 (setf (alist-get 'consult-man embark-default-action-overrides)
@@ -284,6 +285,7 @@ This function is meant to be added to `embark-collect-mode-hook'."
 (declare-function consult-info--action "ext:consult-info")
 
 (defun embark-consult-info (cand)
+  "Default action override for `consult-info', open CAND info manual."
   (consult-info--action cand)
   (pulse-momentary-highlight-one-line (point)))
 
@@ -295,28 +297,28 @@ This function is meant to be added to `embark-collect-mode-hook'."
 
 ;;; Bindings for consult commands in embark keymaps
 
-(define-key embark-become-file+buffer-map "Cb" #'consult-buffer)
-(define-key embark-become-file+buffer-map "C4b" #'consult-buffer-other-window)
+(keymap-set embark-become-file+buffer-map "C b" #'consult-buffer)
+(keymap-set embark-become-file+buffer-map "C 4 b" #'consult-buffer-other-window)
 
 ;;; Support for Consult search commands
 
-(embark-define-keymap embark-consult-sync-search-map
-  "Keymap for Consult sync search commands"
+(defvar-keymap embark-consult-sync-search-map
+  :doc "Keymap for Consult sync search commands"
   :parent nil
-  ("o" consult-outline)
-  ("i" 'consult-imenu)
-  ("I" 'consult-imenu-multi)
-  ("l" consult-line)
-  ("L" consult-line-multi))
-
-(embark-define-keymap embark-consult-async-search-map
-  "Keymap for Consult async search commands"
+  "o" #'consult-outline
+  "i" 'consult-imenu
+  "I" 'consult-imenu-multi
+  "l" #'consult-line
+  "L" #'consult-line-multi)
+
+(defvar-keymap embark-consult-async-search-map
+  :doc "Keymap for Consult async search commands"
   :parent nil
-  ("g" consult-grep)
-  ("r" consult-ripgrep)
-  ("G" consult-git-grep)
-  ("f" consult-find)
-  ("F" consult-locate))
+  "g" #'consult-grep
+  "r" #'consult-ripgrep
+  "G" #'consult-git-grep
+  "f" #'consult-find
+  "F" #'consult-locate)
 
 (defvar embark-consult-search-map
   (keymap-canonicalize
@@ -325,12 +327,12 @@ This function is meant to be added to `embark-collect-mode-hook'."
   "Keymap for all Consult search commands.")
 
 (fset 'embark-consult-sync-search-map embark-consult-sync-search-map)
-(define-key embark-become-match-map "C" 'embark-consult-sync-search-map)
+(keymap-set embark-become-match-map "C" 'embark-consult-sync-search-map)
 
 (cl-pushnew 'embark-consult-async-search-map embark-become-keymaps)
 
 (fset 'embark-consult-search-map embark-consult-search-map)
-(define-key embark-general-map "C" 'embark-consult-search-map)
+(keymap-set embark-general-map "C" 'embark-consult-search-map)
 
 (map-keymap
  (lambda (_key cmd)