[nongnu] elpa/devil 30649e8f47 1/2: Update devil-mode-map when devil-key is updated

[ELPA Syncer]

branch: elpa/devil
commit 30649e8f473ad352d296b05a569acfdc910d9ca5
Author: Susam Pal <susam@susam.net>
Commit: Susam Pal <susam@susam.net>

    Update devil-mode-map when devil-key is updated
---
 CHANGES.org | 30 +++++++++++++++++++--------
 MANUAL.org  | 22 ++++++++------------
 devil.el    | 68 ++++++++++++++++++++++++++++++++++++++++---------------------
 3 files changed, 76 insertions(+), 44 deletions(-)

diff --git a/CHANGES.org b/CHANGES.org
index c919008017..ae849f0bd6 100644
--- a/CHANGES.org
+++ b/CHANGES.org
@@ -2,6 +2,20 @@
 
 * Changelog
 
+** Version 0.5.0 (UNRELEASED)
+:PROPERTIES:
+:CUSTOM_ID: 0.5.0
+:END:
+
+*** Added
+
+- Function =devil-set-key= to set a new Devil key and update the
+  mode's keymap.
+
+*** Changed
+
+- Customising =devil-key= also updates the mode's keymap.
+
 ** Version 0.4.0 (2023-05-27)
 :PROPERTIES:
 :CUSTOM_ID: 0.4.0
@@ -9,11 +23,11 @@
 
 *** Added
 
-- Add customisable variable =devil-all-keys-repeatable= that makes all
+- Customisable variable =devil-all-keys-repeatable= that makes all
   Devil key sequences repeatable when set to =t=.
-- Add =, s= to the default list of repeatable keys.
-- Add =, d= to the default list of repeatable keys.
-- Add =, m m ^= to the default list of repeatable keys.
+- Key =, s= to the default list of repeatable keys.
+- Key =, d= to the default list of repeatable keys.
+- Key =, m m ^= to the default list of repeatable keys.
 - Translate =m m= to =m= to support typing key sequences like =C-c m=.
 - Translate =m z= to =M-= to support typing key sequences like =C-c
   M-m= and =C-M-m=.
@@ -62,10 +76,10 @@
 
 *** Added
 
-- Add =, k= to the default list of repeatable keys.
-- Add =, /= to the default list of repeatable keys.
-- Add =, m m y= to the default list of repeatable keys.
-- Add command =devil-show-version= to display Devil version.
+- Key =, k= to the default list of repeatable keys.
+- Key =, /= to the default list of repeatable keys.
+- Key =, m m y= to the default list of repeatable keys.
+- Command =devil-show-version= to display Devil version.
 
 *** Changed
 
diff --git a/MANUAL.org b/MANUAL.org
index 808fdd49d4..ac04e8498e 100644
--- a/MANUAL.org
+++ b/MANUAL.org
@@ -79,7 +79,6 @@ are presented in the next few subsections.
 :PROPERTIES:
 :CUSTOM_ID: install-interactively-from-melpa
 :END:
-
 To install the latest version of Devil from MELPA, perform the
 following steps:
 
@@ -495,6 +494,7 @@ following configuration:
 #+begin_src elisp
   (require 'devil)
   (global-devil-mode)
+  (global-set-key (kbd "C-,") 'global-devil-mode)
   (setq devil-special-keys '(("%k %k" . (lambda () (interactive) 
(devil-run-key "%k")))))
 #+end_src
 
@@ -510,10 +510,10 @@ The following initialization code shows how we can 
customise Devil to
 use a different Devil key.
 
 #+begin_src elisp
-  (defvar devil-key ";")
   (require 'devil)
   (global-devil-mode)
   (global-set-key (kbd "C-;") 'global-devil-mode)
+  (devil-set-key (kbd ";"))
 #+end_src
 
 The above example sets the Devil key to the semicolon, perhaps another
@@ -528,11 +528,11 @@ The following initialization code shows how we can 
customise Devil to
 use yet another different Devil key.
 
 #+begin_src elisp
-  (defvar devil-key (kbd "<left>"))
-  (defvar devil-special-keys '(("%k %k" . left-char)))
   (require 'devil)
   (global-devil-mode)
   (global-set-key (kbd "C-<left>") 'global-devil-mode)
+  (devil-set-key (kbd "<left>"))
+  (setq devil-special-keys '(("%k %k" . left-char)))
 #+end_src
 
 The above example sets the Devil key to the left arrow key.  With this
@@ -560,17 +560,13 @@ starting point and then customise it further based on your
 requirements:
 
 #+begin_src elisp
-(defvar devil-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map (kbd ",") #'devil)
-    (define-key map (kbd ".") #'devil)
-    map))
-(defvar devil-special-keys '((", ," . (lambda () (insert ",")))
+  (require 'devil)
+  (global-devil-mode)
+  (define-key devil-mode-map (kbd ".") #'devil)
+  (setq devil-special-keys '((", ," . (lambda () (insert ",")))
                              (". ." . (lambda () (insert ".")))))
-(defvar devil-translations '(("," . "C-")
+  (setq devil-translations '(("," . "C-")
                              ("." . "M-")))
-(require 'devil)
-(global-devil-mode)
 #+end_src
 
 With this configuration, we can type =, x , f= for =C-x C-f= like
diff --git a/devil.el b/devil.el
index 73f4bd96d3..c47b9789e3 100644
--- a/devil.el
+++ b/devil.el
@@ -44,25 +44,56 @@
   :prefix "devil-"
   :group 'editing)
 
-(defcustom devil-key ","
-  "The key sequence that begins Devil input."
-  :type 'key-sequence)
+(defvar devil-mode-map (make-sparse-keymap)
+  "Keymap for Devil mode.
+
+By default, only `devil-key' is added to this keymap so that
+Devil can be activated using it.  To support multiple activation
+keys, this keymap may be modified to add multiple keys to
+activate Devil.")
+
+(defcustom devil-logging nil
+  "Non-nil iff Devil should print log messages."
+  :type 'boolean)
+
+(defun devil--log (format-string &rest args)
+  "Write log message with the given FORMAT-STRING and ARGS."
+  (when devil-logging
+    (apply #'message (concat "Devil: " format-string) args)))
+
+(defun devil--custom-devil-key (symbol value)
+  "Set Devil key variable SYMBOL to the key sequence in given VALUE.
+
+After setting SYMBOL to VALUE, clear all key bindings in
+`devil-mode-map' and add a new key binding such that the key
+sequence given in VALUE activates Devil."
+  (set-default symbol value)
+  (setcdr devil-mode-map nil)
+  (define-key devil-mode-map value #'devil)
+  (devil--log "Keymap updated to %s" devil-mode-map))
 
 (defcustom devil-lighter " Devil"
   "String displayed on the mode line when Devil mode is enabled."
   :type 'string)
 
-(defvar devil-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map devil-key #'devil)
-    map)
-  "Keymap to wake up Devil when `devil-key' is typed.
+(defcustom devil-key ","
+  "The key sequence that begins Devil input.
 
-By default, only `devil-key' is added to this keymap so that
-Devil can be activated using it.  To support multiple activation
-keys, this variable may be modified to a new keymap that defines
-multiple different keys to activate Devil.  This variable should
-be modified before loading Devil for it to take effect.")
+Do not set this variable directly.  Either use the
+`devil-set-key' function to set this variable or customize this
+variable using Emacs customization features/functions.  Doing so
+ensures that the `devil-mode-map' is updated correctly to use the
+updated value of this variable."
+  :type 'key-sequence
+  :set #'devil--custom-devil-key)
+
+(defun devil-set-key (key-sequence)
+  "Set `devil-key' to the given KEY-SEQUENCE and update `devil-mode-map'.
+
+This function clears existing key bindings in `devil-mode-map'
+and sets a single key binding in this keymap so that Devil can be
+activated using the given KEY-SEQUENCE."
+  (devil--custom-devil-key 'devil-key key-sequence))
 
 ;;;###autoload
 (define-minor-mode devil-mode
@@ -79,10 +110,6 @@ be modified before loading Devil for it to take effect.")
   "Turn Devil mode on."
   (devil-mode 1))
 
-(defcustom devil-logging nil
-  "Non-nil iff Devil should print log messages."
-  :type 'boolean)
-
 (defvar devil-special-keys
   (list (cons "%k %k" (lambda () (interactive) (devil-run-key "%k")))
         (cons "%k SPC" (lambda () (interactive) (devil-run-key "%k SPC")))
@@ -181,7 +208,7 @@ buffer."
 
 (defun devil-remove-extra-keys ()
   "Remove Devil key bindings from Isearch and universal argument."
-  (devil--log "Removing extra keybindings")
+  (devil--log "Removing extra key bindings")
   (define-key isearch-mode-map (kbd ",")
     (cdr (assoc 'isearch-comma devil--saved-keys)))
   (define-key universal-argument-map (kbd "u")
@@ -432,10 +459,5 @@ this-command: %s; last-command: %s; 
last-repeatable-command: %s"
   (let ((case-fold-search nil))
     (replace-regexp-in-string regexp replacement in-string t)))
 
-(defun devil--log (format-string &rest args)
-  "Write log message with the given FORMAT-STRING and ARGS."
-  (when devil-logging
-    (apply #'message (concat "Devil: " format-string) args)))
-
 (provide 'devil)
 ;;; devil.el ends here