* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
@ 2024-02-04 22:02 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 2:15 ` Justin Burkett
` (3 more replies)
0 siblings, 4 replies; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-04 22:02 UTC (permalink / raw)
To: 68929, monnier, justin
[-- Attachment #1: Type: text/plain, Size: 187 bytes --]
Tags: patch
This patch brings the latest version of which-key from GNU ELPA into
Emacs core
If suitable I will then work on the updates to user-facing aspects such as
manual and NEWS.
[-- Attachment #2: 0001-lisp-which-key.el-Display-available-keybindings-in-p.patch --]
[-- Type: text/patch, Size: 120855 bytes --]
From 1a3207344a18b6743772927b6f8f709b05246a51 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Sun, 4 Feb 2024 21:56:16 +0000
Subject: [PATCH] * lisp/which-key.el: Display available keybindings in popup
Copy feature which-key from GNU ELPA
---
lisp/which-key.el | 2753 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 2753 insertions(+)
create mode 100644 lisp/which-key.el
diff --git a/lisp/which-key.el b/lisp/which-key.el
new file mode 100644
index 00000000000..d68942cf8b1
--- /dev/null
+++ b/lisp/which-key.el
@@ -0,0 +1,2753 @@
+;;; which-key.el --- Display available keybindings in popup -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2017-2021 Free Software Foundation, Inc.
+
+;; Author: Justin Burkett <justin@burkett.cc>
+;; Maintainer: Justin Burkett <justin@burkett.cc>
+;; URL: https://github.com/justbur/emacs-which-key
+;; Version: 3.6.0
+;; Keywords:
+;; Package-Requires: ((emacs "24.4"))
+
+;; 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
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; which-key provides the minor mode which-key-mode for Emacs. The mode displays
+;; the key bindings following your currently entered incomplete command (a
+;; prefix) in a popup. For example, after enabling the minor mode if you enter
+;; C-x and wait for the default of 1 second the minibuffer will expand with all
+;; of the available key bindings that follow C-x (or as many as space allows
+;; given your settings). This includes prefixes like C-x 8 which are shown in a
+;; different face. Screenshots of what the popup will look like along with
+;; information about additional features can be found at
+;; https://github.com/justbur/emacs-which-key.
+;;
+
+;;; Code:
+
+(require 'cl-lib)
+(require 'button)
+(require 'regexp-opt)
+
+;; For compiler
+(defvar evil-operator-shortcut-map)
+(defvar evil-operator-state-map)
+(defvar evil-motion-state-map)
+(defvar golden-ratio-mode)
+(declare-function evil-get-command-property "ext:evil-common.el")
+
+;;; Options
+
+(defgroup which-key nil
+ "Customization options for which-key-mode"
+ :group 'help
+ :prefix "which-key-")
+
+(defcustom which-key-idle-delay 1.0
+ "Delay (in seconds) for which-key buffer to popup.
+This variable should be set before activating `which-key-mode'.
+
+A value of zero might lead to issues, so a non-zero value is
+recommended
+(see https://github.com/justbur/emacs-which-key/issues/134)."
+ :group 'which-key
+ :type 'float)
+
+(defcustom which-key-idle-secondary-delay nil
+ "Once the which-key buffer shows once for a key sequence reduce
+the idle time to this amount (in seconds). This makes it possible
+to shorten the delay for subsequent popups in the same key
+sequence. The default is for this value to be nil, which disables
+this behavior."
+ :group 'which-key
+ :type '(choice float (const :tag "Disabled" nil)))
+
+(defcustom which-key-echo-keystrokes (if (and echo-keystrokes
+ (> (+ echo-keystrokes 0.01)
+ which-key-idle-delay))
+ (/ (float which-key-idle-delay) 4)
+ echo-keystrokes)
+ "Value to use for `echo-keystrokes'.
+This only applies if `which-key-popup-type' is minibuffer or
+`which-key-show-prefix' is echo. It needs to be less than
+`which-key-idle-delay' or else the keystroke echo will erase the
+which-key popup."
+ :group 'which-key
+ :type 'float)
+
+(defcustom which-key-max-description-length 27
+ "Truncate the description of keys to this length.
+Either nil (no truncation), an integer (truncate after that many
+characters), a float (use that fraction of the available width),
+or a function, which takes one argument, the available width in
+characters, and whose return value has one of the types mentioned
+before. Truncation is done using `which-key-ellipsis'."
+ :group 'which-key
+ :type '(choice (const :tag "Disable truncation" nil)
+ (integer :tag "Width in characters")
+ (float :tag "Use fraction of available width")
+ function))
+
+(defcustom which-key-min-column-description-width 0
+ "Every column should at least have this width."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-add-column-padding 0
+ "Additional padding (number of spaces) to add to the left of
+each key column."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-unicode-correction 3
+ "Correction for wide unicode characters.
+Since we measure width in terms of the number of characters,
+Unicode characters that are wider than ASCII characters throw off
+the calculation for available width in the which-key buffer. This
+variable allows you to adjust for the wide unicode characters by
+artificially reducing the available width in the buffer.
+
+The default of 3 means allow for the total extra width
+contributed by any wide unicode characters to be up to one
+additional ASCII character in the which-key buffer. Increase this
+number if you are seeing characters get cutoff on the right side
+of the which-key popup."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-dont-use-unicode nil
+ "If non-nil, don't use any unicode characters in default setup."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-separator
+ (if which-key-dont-use-unicode " : " " → ")
+ "Separator to use between key and description. Default is \" →
+\", unless `which-key-dont-use-unicode' is non nil, in which case
+the default is \" : \"."
+ :group 'which-key
+ :type 'string)
+
+(defcustom which-key-ellipsis
+ (if which-key-dont-use-unicode ".." "…")
+ "Ellipsis to use when truncating.
+Default is \"…\", unless `which-key-dont-use-unicode' is non nil,
+in which case the default is \"..\". This can also be the empty
+string to truncate without using any ellipsis."
+ :group 'which-key
+ :type 'string)
+
+(defcustom which-key-prefix-prefix "+"
+ "String to insert in front of prefix commands (i.e., commands
+that represent a sub-map). Default is \"+\"."
+ :group 'which-key
+ :type 'string)
+
+(defcustom which-key-compute-remaps nil
+ "If non-nil, show remapped command if a command has been
+remapped given the currently active keymaps."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-replacement-alist
+ (delq nil
+ `(((nil . "which-key-show-next-page-no-cycle") . (nil . "wk next pg"))
+ ,@(unless which-key-dont-use-unicode
+ '((("<left>") . ("←"))
+ (("<right>") . ("→"))))
+ (("<\\([[:alnum:]-]+\\)>") . ("\\1"))))
+ "Association list to determine how to manipulate descriptions
+of key bindings in the which-key popup. Each element of the list
+is a nested cons cell with the format
+
+\(MATCH CONS . REPLACEMENT\).
+
+The MATCH CONS determines when a replacement should occur and
+REPLACEMENT determines how the replacement should occur. Each may
+have the format \(KEY REGEXP . BINDING REGEXP\). For the
+replacement to apply the key binding must match both the KEY
+REGEXP and the BINDING REGEXP. A value of nil in either position
+can be used to match every possibility. The replacement is
+performed by using `replace-regexp-in-string' on the KEY REGEXP
+from the MATCH CONS and REPLACEMENT when it is a cons cell, and
+then similarly for the BINDING REGEXP. A nil value in the BINDING
+REGEXP position cancels the replacement. For example, the entry
+
+\(\(nil . \"Prefix Command\"\) . \(nil . \"prefix\"\)\)
+
+matches any binding with the descriptions \"Prefix Command\" and
+replaces the description with \"prefix\", ignoring the
+corresponding key.
+
+REPLACEMENT may also be a function taking a cons cell
+\(KEY . BINDING\) and producing a new corresponding cons cell.
+
+If REPLACEMENT is anything other than a cons cell \(and non nil\)
+the key binding is ignored by which-key.
+
+Finally, you can multiple replacements to occur for a given key
+binding by setting `which-key-allow-multiple-replacements' to a
+non-nil value."
+ :group 'which-key
+ :type '(alist :key-type (cons (choice regexp (const nil))
+ (choice regexp (const nil)))
+ :value-type (cons (choice string (const nil))
+ (choice string (const nil)))))
+
+(defcustom which-key-allow-multiple-replacements nil
+ "Allow a key binding to match and be modified by multiple
+elements in `which-key-replacement-alist' if non-nil. When nil,
+only the first match is used to perform replacements from
+`which-key-replacement-alist'."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-show-docstrings nil
+ "If non-nil, show each command's docstring next to the command
+in the which-key buffer. This will only display the docstring up
+to the first line break. If you set this variable to the symbol
+docstring-only, then the command's name with be omitted. You
+probably also want to adjust `which-key-max-description-length'
+at the same time if you use this feature."
+ :group 'which-key
+ :type '(radio
+ (const :tag "Do not show docstrings" nil)
+ (const :tag "Add docstring to command names" t)
+ (const :tag "Replace command name with docstring" docstring-only)))
+
+(defcustom which-key-highlighted-command-list '()
+ "A list of strings and/or cons cells used to highlight certain
+commands. If the element is a string, assume it is a regexp
+pattern for matching command names and use
+`which-key-highlighted-command-face' for any matching names. If
+the element is a cons cell, it should take the form (regexp .
+face to apply)."
+ :group 'which-key
+ :type '(repeat (choice string (cons regexp face))))
+
+(defcustom which-key-special-keys '()
+ "These keys will automatically be truncated to one character
+and have `which-key-special-key-face' applied to them. This is
+disabled by default. Try this to see the effect.
+
+\(setq which-key-special-keys \\='(\"SPC\" \"TAB\" \"RET\" \"ESC\" \"DEL\")\)"
+ :group 'which-key
+ :type '(repeat string))
+
+(defcustom which-key-buffer-name " *which-key*"
+ "Name of which-key buffer."
+ :group 'which-key
+ :type 'string)
+
+(defcustom which-key-show-prefix 'echo
+ "Whether to and where to display the current prefix sequence
+Possible choices are echo for echo area (the default), left, top
+and nil. Nil turns the feature off."
+ :group 'which-key
+ :type '(radio (const :tag "Left of the keys" left)
+ (const :tag "In the first line" top)
+ (const :tag "In the last line" bottom)
+ (const :tag "In the echo area" echo)
+ (const :tag "In the mode-line" mode-line)
+ (const :tag "Hide" nil)))
+
+(defcustom which-key-popup-type 'side-window
+ "Supported types are minibuffer, side-window, frame, and custom"
+ :group 'which-key
+ :type '(radio (const :tag "Show in minibuffer" minibuffer)
+ (const :tag "Show in side window" side-window)
+ (const :tag "Show in popup frame" frame)
+ (const :tag "Use your custom display functions" custom)))
+
+(defcustom which-key-min-display-lines 1
+ "Minimum number of horizontal lines to display in the which-key buffer"
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-max-display-columns nil
+ "Maximum number of columns to display in the which-key buffer
+nil means don't impose a maximum."
+ :group 'which-key
+ :type '(choice integer (const :tag "Unbounded" nil)))
+
+(defcustom which-key-side-window-location 'bottom
+ "Location of which-key popup when `which-key-popup-type' is side-window.
+Should be one of top, bottom, left or right. You can also specify
+a list of two locations, like (right bottom). In this case, the
+first location is tried. If there is not enough room, the second
+location is tried."
+ :group 'which-key
+ :type '(radio (const right)
+ (const bottom)
+ (const left)
+ (const top)
+ (const (right bottom))
+ (const (bottom right))))
+
+(defcustom which-key-side-window-slot 0
+ "The `slot' to use for `display-buffer-in-side-window' when
+`which-key-popup-type' is `side-window'. Quoting from the
+docstring of `display-buffer-in-side-window',
+
+`slot' if non-nil, specifies the window slot where to display
+BUFFER. A value of zero or nil means use the middle slot on the
+specified side. A negative value means use a slot
+preceding (that is, above or on the left of) the middle slot. A
+positive value means use a slot following (that is, below or on
+the right of) the middle slot. The default is zero."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-side-window-max-width 0.333
+ "Maximum width of which-key popup when type is side-window
+This variable can also be a number between 0 and 1. In that case,
+it denotes a percentage out of the frame's width."
+ :group 'which-key
+ :type 'float)
+
+(defcustom which-key-side-window-max-height 0.25
+ "Maximum height of which-key popup when type is side-window
+This variable can also be a number between 0 and 1. In that case, it denotes
+a percentage out of the frame's height."
+ :group 'which-key
+ :type 'float)
+
+(defcustom which-key-frame-max-width 60
+ "Maximum width of which-key popup when type is frame."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-frame-max-height 20
+ "Maximum height of which-key popup when type is frame."
+ :group 'which-key
+ :type 'integer)
+
+(defcustom which-key-allow-imprecise-window-fit (not (display-graphic-p))
+ "If non-nil allow which-key to use a less intensive method of
+fitting the popup window to the buffer. If you are noticing lag
+when the which-key popup displays turning this on may help.
+
+See https://github.com/justbur/emacs-which-key/issues/130
+and https://github.com/justbur/emacs-which-key/issues/225."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-show-remaining-keys nil
+ "Show remaining keys in last slot, when keys are hidden."
+ :group 'which-key
+ :type '(radio (const :tag "Yes" t)
+ (const :tag "No" nil)))
+
+(defcustom which-key-sort-order 'which-key-key-order
+ "If nil, do not resort the output from
+`describe-buffer-bindings' which groups by mode. Ordering options
+are
+
+1. `which-key-key-order': by key (default)
+2. `which-key-key-order-alpha': by key using alphabetical order
+3. `which-key-description-order': by description
+4. `which-key-prefix-then-key-order': prefix (no prefix first) then key
+5. `which-key-local-then-key-order': local binding then key
+
+See the README and the docstrings for those functions for more
+information."
+ :group 'which-key
+ :type '(choice (function-item which-key-key-order)
+ (function-item which-key-key-order-alpha)
+ (function-item which-key-description-order)
+ (function-item which-key-prefix-then-key-order)
+ (function-item which-key-local-then-key-order)))
+
+(defcustom which-key-sort-uppercase-first t
+ "If non-nil, uppercase comes before lowercase in sorting
+function chosen in `which-key-sort-order'. Otherwise, the order
+is reversed."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-paging-prefixes '()
+ "Enable paging for these prefixes."
+ :group 'which-key
+ :type '(repeat string))
+
+(defcustom which-key-paging-key "<f5>"
+ "Key to use for changing pages. Bound after each of the
+prefixes in `which-key-paging-prefixes'"
+ :group 'which-key
+ :type 'string)
+
+;; (defcustom which-key-undo-key nil
+;; "Key (string) to use for undoing keypresses. Bound recursively
+;; in each of the maps in `which-key-undo-keymaps'."
+;; :group 'which-key
+;; :type 'string)
+
+;; (defcustom which-key-undo-keymaps '()
+;; "Keymaps in which to bind `which-key-undo-key'"
+;; :group 'which-key
+;; :type '(repeat symbol))
+
+(defcustom which-key-use-C-h-commands t
+ "Use C-h (or whatever `help-char' is set to) for paging if
+non-nil. Normally C-h after a prefix calls
+`describe-prefix-bindings'. This changes that command to a
+which-key paging command when which-key-mode is active."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-show-early-on-C-h nil
+ "Show the which-key buffer before if C-h (or whatever
+`help-char' is set to) is pressed in the middle of a prefix
+before the which-key buffer would normally be triggered through
+the idle delay. If combined with the following settings,
+which-key will effectively only show when triggered \"manually\"
+using C-h.
+
+\(setq `which-key-idle-delay' 10000)
+\(setq `which-key-idle-secondary-delay' 0.05)
+
+Note that `which-key-idle-delay' should be set before turning on
+`which-key-mode'. "
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-is-verbose nil
+ "Whether to warn about potential mistakes in configuration."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-preserve-window-configuration nil
+ "If non-nil, save window configuration before which-key buffer is shown
+and restore it after which-key buffer is hidden. It prevents which-key from
+changing window position of visible buffers.
+Only takken into account when popup type is side-window."
+ :group
+ 'which-key
+ :type 'boolean)
+
+(defvar which-key-C-h-map-prompt
+ (concat " \\<which-key-C-h-map>"
+ " \\[which-key-show-next-page-cycle]"
+ which-key-separator "next-page,"
+ " \\[which-key-show-previous-page-cycle]"
+ which-key-separator "previous-page,"
+ " \\[which-key-undo-key]"
+ which-key-separator "undo-key,"
+ " \\[which-key-toggle-docstrings]"
+ which-key-separator "toggle-docstrings,"
+ " \\[which-key-show-standard-help]"
+ which-key-separator "help,"
+ " \\[which-key-abort]"
+ which-key-separator "abort"
+ " 1..9"
+ which-key-separator "digit-arg")
+ "Prompt to display when invoking `which-key-C-h-map'. This string
+is fed into `substitute-command-keys'")
+
+(defvar which-key-C-h-map
+ (let ((map (make-sparse-keymap)))
+ (dolist (bind `(("\C-a" . which-key-abort)
+ ("a" . which-key-abort)
+ ("\C-d" . which-key-toggle-docstrings)
+ ("d" . which-key-toggle-docstrings)
+ (,(vector help-char) . which-key-show-standard-help)
+ ("h" . which-key-show-standard-help)
+ ("\C-n" . which-key-show-next-page-cycle)
+ ("n" . which-key-show-next-page-cycle)
+ ("\C-p" . which-key-show-previous-page-cycle)
+ ("p" . which-key-show-previous-page-cycle)
+ ("\C-u" . which-key-undo-key)
+ ("u" . which-key-undo-key)
+ ("1" . which-key-digit-argument)
+ ("2" . which-key-digit-argument)
+ ("3" . which-key-digit-argument)
+ ("4" . which-key-digit-argument)
+ ("5" . which-key-digit-argument)
+ ("6" . which-key-digit-argument)
+ ("7" . which-key-digit-argument)
+ ("8" . which-key-digit-argument)
+ ("9" . which-key-digit-argument)))
+ (define-key map (car bind) (cdr bind)))
+ map)
+ "Keymap for C-h commands.")
+
+(defvar which-key--paging-functions '(which-key-C-h-dispatch
+ which-key-manual-update
+ which-key-turn-page
+ which-key-show-next-page-cycle
+ which-key-show-next-page-no-cycle
+ which-key-show-previous-page-cycle
+ which-key-show-previous-page-no-cycle
+ which-key-undo-key
+ which-key-undo))
+
+(defvar which-key-persistent-popup nil
+ "Whether or not to disable `which-key--hide-popup'.")
+
+(defcustom which-key-hide-alt-key-translations t
+ "Hide key translations using Alt key if non nil.
+These translations are not relevant most of the times since a lot
+of terminals issue META modifier for the Alt key.
+
+See http://www.gnu.org/software/emacs/manual/html_node/emacs/Modifier-Keys.html"
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-delay-functions nil
+ "A list of functions that may decide whether to delay the
+which-key popup based on the current incomplete key
+sequence. Each function in the list is run with two arguments,
+the current key sequence as produced by `key-description' and the
+length of the key sequence. If the popup should be delayed based
+on that key sequence, the function should return the delay time
+in seconds. Returning nil means no delay. The first function in
+this list to return a value is the value that is used.
+
+The delay time is effectively added to the normal
+`which-key-idle-delay'."
+ :group 'which-key
+ :type '(repeat function))
+
+(defcustom which-key-allow-regexps nil
+ "A list of regexp strings to use to filter key sequences.
+When non-nil, for a key sequence to trigger the which-key popup
+it must match one of the regexps in this list. The format of the
+key sequences is what is produced by `key-description'."
+ :group 'which-key
+ :type '(repeat regexp))
+
+(defcustom which-key-inhibit-regexps nil
+ "Similar to `which-key-allow-regexps', a list of regexp strings
+to use to filter key sequences. When non-nil, for a key sequence
+to trigger the which-key popup it cannot match one of the regexps
+in this list. The format of the key sequences is what is produced
+by `key-description'."
+ :group 'which-key
+ :type '(repeat regexp))
+
+(defcustom which-key-show-transient-maps nil
+ "Show keymaps created by `set-transient-map' when applicable.
+
+More specifically, detect when `overriding-terminal-local-map' is
+set (this is the keymap used by `set-transient-map') and display
+it."
+ :group 'which-key
+ :type 'boolean)
+
+(make-obsolete-variable
+ 'which-key-enable-extended-define-key
+ "which-key-enable-extended-define-key is obsolete and has no effect."
+ "2021-06-21")
+
+;; Hooks
+(defcustom which-key-init-buffer-hook '()
+ "Hook run when which-key buffer is initialized."
+ :group 'which-key
+ :type 'hook)
+
+;;;; Faces
+
+(defgroup which-key-faces nil
+ "Faces for which-key-mode"
+ :group 'which-key
+ :prefix "which-key-")
+
+(defface which-key-key-face
+ '((t . (:inherit font-lock-constant-face)))
+ "Face for which-key keys"
+ :group 'which-key-faces)
+
+(defface which-key-separator-face
+ '((t . (:inherit font-lock-comment-face)))
+ "Face for the separator (default separator is an arrow)"
+ :group 'which-key-faces)
+
+(defface which-key-note-face
+ '((t . (:inherit which-key-separator-face)))
+ "Face for notes or hints occasionally provided"
+ :group 'which-key-faces)
+
+(defface which-key-command-description-face
+ '((t . (:inherit font-lock-function-name-face)))
+ "Face for the key description when it is a command"
+ :group 'which-key-faces)
+
+(defface which-key-local-map-description-face
+ '((t . (:inherit which-key-command-description-face)))
+ "Face for the key description when it is found in `current-local-map'"
+ :group 'which-key-faces)
+
+(defface which-key-highlighted-command-face
+ '((t . (:inherit which-key-command-description-face :underline t)))
+ "Default face for the command description when it is a command
+and it matches a string in `which-key-highlighted-command-list'."
+ :group 'which-key-faces)
+
+(defface which-key-group-description-face
+ '((t . (:inherit font-lock-keyword-face)))
+ "Face for the key description when it is a group or prefix"
+ :group 'which-key-faces)
+
+(defface which-key-special-key-face
+ '((t . (:inherit which-key-key-face :inverse-video t :weight bold)))
+ "Face for special keys (SPC, TAB, RET)"
+ :group 'which-key-faces)
+
+(defface which-key-docstring-face
+ '((t . (:inherit which-key-note-face)))
+ "Face for docstrings"
+ :group 'which-key-faces)
+
+;;;; Custom popup
+
+(defcustom which-key-custom-popup-max-dimensions-function nil
+ "Variable to hold a custom max-dimensions function.
+Will be passed the width of the active window and is expected to
+return the maximum height in lines and width in characters of the
+which-key popup in the form a cons cell (height . width)."
+ :group 'which-key
+ :type '(choice function (const nil)))
+
+(defcustom which-key-custom-hide-popup-function nil
+ "Variable to hold a custom hide-popup function.
+It takes no arguments and the return value is ignored."
+ :group 'which-key
+ :type '(choice function (const nil)))
+
+(defcustom which-key-custom-show-popup-function nil
+ "Variable to hold a custom show-popup function.
+Will be passed the required dimensions in the form (height .
+width) in lines and characters respectively. The return value is
+ignored."
+ :group 'which-key
+ :type '(choice function (const nil)))
+
+(defcustom which-key-lighter " WK"
+ "Minor mode lighter to use in the mode-line."
+ :group 'which-key
+ :type 'string)
+
+(defvar which-key-inhibit nil
+ "Prevent which-key from popping up momentarily by setting this
+to a non-nil value for the execution of a command. Like this
+
+\(let \(\(which-key-inhibit t\)\)
+...\)")
+
+(defvar which-key-keymap-history nil
+ "History of keymap selections in functions like
+`which-key-show-keymap'.")
+
+;;; Internal Vars
+
+(defvar which-key--buffer nil
+ "Internal: Holds reference to which-key buffer.")
+(defvar which-key--timer nil
+ "Internal: Holds reference to open window timer.")
+(defvar which-key--secondary-timer-active nil
+ "Internal: Non-nil if the secondary timer is active.")
+(defvar which-key--paging-timer nil
+ "Internal: Holds reference to timer for paging.")
+(defvar which-key--frame nil
+ "Internal: Holds reference to which-key frame.
+Used when `which-key-popup-type' is frame.")
+(defvar which-key--echo-keystrokes-backup nil
+ "Internal: Backup the initial value of `echo-keystrokes'.")
+(defvar which-key--prefix-help-cmd-backup nil
+ "Internal: Backup the value of `prefix-help-command'.")
+(defvar which-key--last-try-2-loc nil
+ "Internal: Last location of side-window when two locations
+used.")
+(defvar which-key--automatic-display nil
+ "Internal: Non-nil if popup was triggered with automatic
+update.")
+(defvar which-key--debug-buffer-name nil
+ "If non-nil, use this buffer for debug messages.")
+(defvar which-key--multiple-locations nil)
+(defvar which-key--inhibit-next-operator-popup nil)
+(defvar which-key--prior-show-keymap-args nil)
+(defvar which-key--previous-frame-size nil)
+(defvar which-key--prefix-title-alist nil)
+(defvar which-key--evil-keys-regexp (eval-when-compile
+ (regexp-opt '("-state"))))
+(defvar which-key--ignore-non-evil-keys-regexp
+ (eval-when-compile
+ (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
+ "select-window" "switch-frame" "which-key"))))
+(defvar which-key--ignore-keys-regexp
+ (eval-when-compile
+ (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
+ "select-window" "switch-frame" "-state"
+ "which-key"))))
+
+(defvar which-key--pages-obj nil)
+(cl-defstruct which-key--pages
+ pages
+ height
+ widths
+ keys/page
+ page-nums
+ num-pages
+ total-keys
+ prefix
+ prefix-title)
+
+(defvar which-key--saved-window-configuration nil)
+
+(defun which-key--rotate (list n)
+ (let* ((len (length list))
+ (n (if (< n 0) (+ len n) n))
+ (n (mod n len)))
+ (append (last list (- len n)) (butlast list (- len n)))))
+
+(defun which-key--pages-set-current-page (pages-obj n)
+ (setf (which-key--pages-pages pages-obj)
+ (which-key--rotate (which-key--pages-pages pages-obj) n))
+ (setf (which-key--pages-widths pages-obj)
+ (which-key--rotate (which-key--pages-widths pages-obj) n))
+ (setf (which-key--pages-keys/page pages-obj)
+ (which-key--rotate (which-key--pages-keys/page pages-obj) n))
+ (setf (which-key--pages-page-nums pages-obj)
+ (which-key--rotate (which-key--pages-page-nums pages-obj) n))
+ pages-obj)
+
+(defsubst which-key--on-first-page ()
+ (= (which-key--pages-page-nums which-key--pages-obj) 1))
+
+(defsubst which-key--on-last-page ()
+ (= (which-key--pages-page-nums which-key--pages-obj)
+ (which-key--pages-num-pages which-key--pages-obj)))
+
+(defsubst which-key--current-prefix ()
+ (and which-key--pages-obj
+ (which-key--pages-prefix which-key--pages-obj)))
+
+(defmacro which-key--debug-message (&rest msg)
+ `(when which-key--debug-buffer-name
+ (let ((buf (get-buffer-create which-key--debug-buffer-name))
+ (fmt-msg (format ,@msg)))
+ (with-current-buffer buf
+ (goto-char (point-max))
+ (insert "\n" fmt-msg "\n")))))
+
+(defsubst which-key--safe-lookup-key (keymap key)
+ "Version of `lookup-key' that allows KEYMAP to be nil.
+Also convert numeric results of `lookup-key' to nil. KEY is not
+checked."
+ (when (keymapp keymap)
+ (let ((result (lookup-key keymap key)))
+ (when (and result (not (numberp result)))
+ result))))
+
+(defsubst which-key--safe-lookup-key-description (keymap key)
+ "Version of `lookup-key' that allows KEYMAP to be nil.
+Also convert numeric results of `lookup-key' to nil. KEY
+should be formatted as an input for `kbd'."
+ (let ((key (ignore-errors (kbd key))))
+ (when (and key (keymapp keymap))
+ (let ((result (lookup-key keymap key)))
+ (when (and result (not (numberp result)))
+ result)))))
+
+;;; Third-party library support
+;;;; Evil
+
+(defvar evil-state nil)
+
+(defcustom which-key-allow-evil-operators (boundp 'evil-this-operator)
+ "Allow popup to show for evil operators.
+The popup is normally inhibited in the middle of commands, but
+setting this to non-nil will override this behavior for evil
+operators."
+ :group 'which-key
+ :type 'boolean)
+
+(defcustom which-key-show-operator-state-maps nil
+ "Experimental: Try to show the right keys following an evil
+command that reads a motion, such as \"y\", \"d\" and \"c\" from
+normal state. This is experimental, because there might be some
+valid keys missing and it might be showing some invalid keys."
+ :group 'which-key
+ :type 'boolean)
+
+;;;; God-mode
+
+(defvar which-key--god-mode-support-enabled nil
+ "Support god-mode if non-nil. This is experimental,
+so you need to explicitly opt-in for now. Please report any
+problems at github.")
+
+(defvar which-key--god-mode-key-string nil
+ "Holds key string to use for god-mode support.")
+
+(defun which-key--god-mode-lookup-command-advice (orig-fun arg1 &rest args)
+ (setq which-key--god-mode-key-string arg1)
+ (unwind-protect
+ (apply orig-fun arg1 args)
+ (when (bound-and-true-p which-key-mode)
+ (which-key--hide-popup))))
+
+(defun which-key-enable-god-mode-support (&optional disable)
+ "Enable support for god-mode if non-nil.
+This is experimental, so you need to explicitly opt-in for
+now. Please report any problems at github. If DISABLE is non-nil
+disable support."
+ (interactive "P")
+ (setq which-key--god-mode-support-enabled (null disable))
+ (if disable
+ (advice-remove 'god-mode-lookup-command
+ #'which-key--god-mode-lookup-command-advice)
+ (advice-add 'god-mode-lookup-command :around
+ #'which-key--god-mode-lookup-command-advice)))
+
+;;; Mode
+
+;;;###autoload
+(define-minor-mode which-key-mode
+ "Toggle which-key-mode."
+ :global t
+ :group 'which-key
+ :lighter which-key-lighter
+ :keymap (let ((map (make-sparse-keymap)))
+ (mapc
+ (lambda (prefix)
+ (define-key map
+ (kbd (concat prefix " " which-key-paging-key))
+ #'which-key-C-h-dispatch))
+ which-key-paging-prefixes)
+ map)
+ (if which-key-mode
+ (progn
+ (setq which-key--echo-keystrokes-backup echo-keystrokes)
+ (when (or (eq which-key-show-prefix 'echo)
+ (eq which-key-popup-type 'minibuffer))
+ (which-key--setup-echo-keystrokes))
+ (unless (member prefix-help-command which-key--paging-functions)
+ (setq which-key--prefix-help-cmd-backup prefix-help-command))
+ (when (or which-key-use-C-h-commands
+ which-key-show-early-on-C-h)
+ (setq prefix-help-command #'which-key-C-h-dispatch))
+ (when which-key-show-remaining-keys
+ (add-hook 'pre-command-hook #'which-key--lighter-restore))
+ (add-hook 'pre-command-hook #'which-key--hide-popup)
+ (add-hook 'window-size-change-functions
+ #'which-key--hide-popup-on-frame-size-change)
+ (which-key--start-timer))
+ (setq echo-keystrokes which-key--echo-keystrokes-backup)
+ (when which-key--prefix-help-cmd-backup
+ (setq prefix-help-command which-key--prefix-help-cmd-backup))
+ (when which-key-show-remaining-keys
+ (remove-hook 'pre-command-hook #'which-key--lighter-restore))
+ (remove-hook 'pre-command-hook #'which-key--hide-popup)
+ (remove-hook 'window-size-change-functions
+ #'which-key--hide-popup-on-frame-size-change)
+ (which-key--stop-timer)))
+
+(defun which-key--init-buffer ()
+ "Initialize which-key buffer"
+ (unless (buffer-live-p which-key--buffer)
+ (setq which-key--buffer (get-buffer-create which-key-buffer-name))
+ (with-current-buffer which-key--buffer
+ ;; suppress confusing minibuffer message
+ (let (message-log-max)
+ (toggle-truncate-lines 1)
+ (message ""))
+ (setq-local cursor-type nil)
+ (setq-local cursor-in-non-selected-windows nil)
+ (setq-local mode-line-format nil)
+ (setq-local header-line-format nil)
+ (setq-local word-wrap nil)
+ (setq-local show-trailing-whitespace nil)
+ (run-hooks 'which-key-init-buffer-hook))))
+
+(defun which-key--setup-echo-keystrokes ()
+ "Reduce `echo-keystrokes' if necessary (it will interfere if
+it's set too high)."
+ (when (and echo-keystrokes
+ (> (abs (- echo-keystrokes which-key-echo-keystrokes)) 0.000001))
+ (if (> which-key-idle-delay which-key-echo-keystrokes)
+ (setq echo-keystrokes which-key-echo-keystrokes)
+ (setq which-key-echo-keystrokes (/ (float which-key-idle-delay) 4)
+ echo-keystrokes which-key-echo-keystrokes))))
+
+(defun which-key-remove-default-unicode-chars ()
+ "Use of `which-key-dont-use-unicode' is preferred to this
+function, but it's included here in case someone cannot set that
+variable early enough in their configuration, if they are using a
+starter kit for example."
+ (when (string-equal which-key-separator " → ")
+ (setq which-key-separator " : ")))
+
+;;; Default configuration functions for use by users.
+
+;;;###autoload
+(defun which-key-setup-side-window-right ()
+ "Apply suggested settings for side-window that opens on right."
+ (interactive)
+ (setq which-key-popup-type 'side-window
+ which-key-side-window-location 'right
+ which-key-show-prefix 'top))
+
+;;;###autoload
+(defun which-key-setup-side-window-right-bottom ()
+ "Apply suggested settings for side-window that opens on right
+if there is space and the bottom otherwise."
+ (interactive)
+ (setq which-key-popup-type 'side-window
+ which-key-side-window-location '(right bottom)
+ which-key-show-prefix 'top))
+
+;;;###autoload
+(defun which-key-setup-side-window-bottom ()
+ "Apply suggested settings for side-window that opens on bottom."
+ (interactive)
+ (which-key--setup-echo-keystrokes)
+ (setq which-key-popup-type 'side-window
+ which-key-side-window-location 'bottom
+ which-key-show-prefix 'echo))
+
+;;;###autoload
+(defun which-key-setup-minibuffer ()
+ "Apply suggested settings for minibuffer.
+Do not use this setup if you use the paging commands. Instead use
+`which-key-setup-side-window-bottom', which is nearly identical
+but more functional."
+ (interactive)
+ (which-key--setup-echo-keystrokes)
+ (setq which-key-popup-type 'minibuffer
+ which-key-show-prefix 'left))
+
+;;; Helper functions to modify replacement lists.
+
+;;;###autoload
+(defun which-key-add-keymap-based-replacements (keymap key replacement &rest more)
+ "Replace the description of KEY using REPLACEMENT in KEYMAP.
+KEY should take a format suitable for use in `kbd'. REPLACEMENT
+should be a cons cell of the form \(STRING . COMMAND\) for each
+REPLACEMENT, where STRING is the replacement string and COMMAND
+is a symbol corresponding to the intended command to be
+replaced. COMMAND can be nil if the binding corresponds to a key
+prefix. An example is
+
+\(which-key-add-keymap-based-replacements global-map
+ \"C-x w\" \\='\(\"Save as\" . write-file\)\).
+
+For backwards compatibility, REPLACEMENT can also be a string,
+but the above format is preferred, and the option to use a string
+for REPLACEMENT will eventually be removed."
+ (while key
+ (let ((def
+ (cond
+ ((consp replacement) replacement)
+ ((stringp replacement)
+ (cons replacement
+ (or (which-key--safe-lookup-key-description keymap key)
+ (make-sparse-keymap))))
+ (t
+ (user-error "replacement is neither a cons cell or a string")))))
+ (define-key keymap (kbd key) def))
+ (setq key (pop more)
+ replacement (pop more))))
+(put 'which-key-add-keymap-based-replacements 'lisp-indent-function 'defun)
+
+;;;###autoload
+(defun which-key-add-key-based-replacements
+ (key-sequence replacement &rest more)
+ "Replace the description of KEY-SEQUENCE with REPLACEMENT.
+KEY-SEQUENCE is a string suitable for use in `kbd'. REPLACEMENT
+may either be a string, as in
+
+\(which-key-add-key-based-replacements \"C-x 1\" \"maximize\"\)
+
+a cons of two strings as in
+
+\(which-key-add-key-based-replacements \"C-x 8\"
+ \\='(\"unicode\" . \"Unicode keys\")\)
+
+or a function that takes a \(KEY . BINDING\) cons and returns a
+replacement.
+
+In the second case, the second string is used to provide a longer
+name for the keys under a prefix.
+
+MORE allows you to specifcy additional KEY REPLACEMENT pairs. All
+replacements are added to `which-key-replacement-alist'."
+ ;; TODO: Make interactive
+ (while key-sequence
+ ;; normalize key sequences before adding
+ (let ((key-seq (key-description (kbd key-sequence)))
+ (replace (or (and (functionp replacement) replacement)
+ (car-safe replacement)
+ replacement)))
+ (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
+ (if (functionp replace) replace (cons nil replace)))
+ which-key-replacement-alist)
+ (when (and (not (functionp replacement)) (consp replacement))
+ (push (cons key-seq (cdr-safe replacement))
+ which-key--prefix-title-alist)))
+ (setq key-sequence (pop more) replacement (pop more))))
+(put 'which-key-add-key-based-replacements 'lisp-indent-function 'defun)
+
+;;;###autoload
+(defun which-key-add-major-mode-key-based-replacements
+ (mode key-sequence replacement &rest more)
+ "Functions like `which-key-add-key-based-replacements'.
+The difference is that MODE specifies the `major-mode' that must
+be active for KEY-SEQUENCE and REPLACEMENT (MORE contains
+addition KEY-SEQUENCE REPLACEMENT pairs) to apply."
+ ;; TODO: Make interactive
+ (when (not (symbolp mode))
+ (error "MODE should be a symbol corresponding to a value of major-mode"))
+ (let ((mode-alist
+ (or (cdr-safe (assq mode which-key-replacement-alist)) (list)))
+ (title-mode-alist
+ (or (cdr-safe (assq mode which-key--prefix-title-alist)) (list))))
+ (while key-sequence
+ ;; normalize key sequences before adding
+ (let ((key-seq (key-description (kbd key-sequence)))
+ (replace (or (and (functionp replacement) replacement)
+ (car-safe replacement)
+ replacement)))
+ (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
+ (if (functionp replace) replace (cons nil replace)))
+ mode-alist)
+ (when (and (not (functionp replacement)) (consp replacement))
+ (push (cons key-seq (cdr-safe replacement))
+ title-mode-alist)))
+ (setq key-sequence (pop more) replacement (pop more)))
+ (if (assq mode which-key-replacement-alist)
+ (setcdr (assq mode which-key-replacement-alist) mode-alist)
+ (push (cons mode mode-alist) which-key-replacement-alist))
+ (if (assq mode which-key--prefix-title-alist)
+ (setcdr (assq mode which-key--prefix-title-alist) title-mode-alist)
+ (push (cons mode title-mode-alist) which-key--prefix-title-alist))))
+(put 'which-key-add-major-mode-key-based-replacements
+ 'lisp-indent-function 'defun)
+
+(defun which-key-define-key-recursively (map key def &optional at-root)
+ "Recursively bind KEY in MAP to DEF on every level of MAP except the first.
+If AT-ROOT is non-nil the binding is also placed at the root of MAP."
+ (when at-root (define-key map key def))
+ (map-keymap
+ (lambda (_ev df)
+ (when (keymapp df)
+ (which-key-define-key-recursively df key def t)))
+ map))
+
+;;; Functions for computing window sizes
+
+(defun which-key--text-width-to-total (text-width)
+ "Convert window text-width to window total-width.
+TEXT-WIDTH is the desired text width of the window. The function
+calculates what total width is required for a window in the
+selected to have a text-width of TEXT-WIDTH columns. The
+calculation considers possible fringes and scroll bars. This
+function assumes that the desired window has the same character
+width as the frame."
+ (let ((char-width (frame-char-width)))
+ (+ text-width
+ (/ (frame-fringe-width) char-width)
+ (/ (frame-scroll-bar-width) char-width)
+ (if (which-key--char-enlarged-p) 1 0)
+ ;; add padding to account for possible wide (unicode) characters
+ 3)))
+
+(defun which-key--total-width-to-text (total-width)
+ "Convert window total-width to window text-width.
+TOTAL-WIDTH is the desired total width of the window. The function calculates
+what text width fits such a window. The calculation considers possible fringes
+and scroll bars. This function assumes that the desired window has the same
+character width as the frame."
+ (let ((char-width (frame-char-width)))
+ (- total-width
+ (/ (frame-fringe-width) char-width)
+ (/ (frame-scroll-bar-width) char-width)
+ (if (which-key--char-enlarged-p) 1 0)
+ ;; add padding to account for possible wide (unicode) characters
+ 3)))
+
+(defun which-key--char-enlarged-p (&optional _frame)
+ (> (frame-char-width)
+ (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
+
+(defun which-key--char-reduced-p (&optional _frame)
+ (< (frame-char-width)
+ (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
+
+(defun which-key--char-exact-p (&optional _frame)
+ (= (frame-char-width)
+ (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
+
+(defun which-key--width-or-percentage-to-width (width-or-percentage)
+ "Return window total width.
+If WIDTH-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
+should be a percentage (a number between 0 and 1) out of the frame's width.
+More precisely, it should be a percentage out of the frame's root window's
+total width."
+ (if (wholenump width-or-percentage)
+ width-or-percentage
+ (round (* width-or-percentage (window-total-width (frame-root-window))))))
+
+(defun which-key--height-or-percentage-to-height (height-or-percentage)
+ "Return window total height.
+If HEIGHT-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
+should be a percentage (a number between 0 and 1) out of the frame's height.
+More precisely, it should be a percentage out of the frame's root window's
+total height."
+ (if (wholenump height-or-percentage)
+ height-or-percentage
+ (round (* height-or-percentage (window-total-height (frame-root-window))))))
+
+(defun which-key--frame-size-changed-p ()
+ "Non-nil if a change in frame size is detected."
+ (let ((new-size (cons (frame-width) (frame-height))))
+ (cond ((null which-key--previous-frame-size)
+ (setq which-key--previous-frame-size new-size)
+ nil)
+ ((not (equal which-key--previous-frame-size new-size))
+ (setq which-key--previous-frame-size new-size)))))
+
+;;; Show/hide which-key buffer
+
+(defun which-key--hide-popup ()
+ "This function is called to hide the which-key buffer."
+ (unless (or which-key-persistent-popup
+ (member real-this-command which-key--paging-functions))
+ (setq which-key--last-try-2-loc nil)
+ (setq which-key--pages-obj nil)
+ (setq which-key--automatic-display nil)
+ (setq which-key--prior-show-keymap-args nil)
+ (when (and which-key-idle-secondary-delay which-key--secondary-timer-active)
+ (which-key--start-timer))
+ (which-key--lighter-restore)
+ (which-key--hide-popup-ignore-command)))
+
+(defun which-key--hide-popup-ignore-command ()
+ "Version of `which-key--hide-popup' without the check of
+`real-this-command'."
+ (cl-case which-key-popup-type
+ ;; Not necessary to hide minibuffer
+ ;; (minibuffer (which-key--hide-buffer-minibuffer))
+ (side-window (which-key--hide-buffer-side-window))
+ (frame (which-key--hide-buffer-frame))
+ (custom (funcall which-key-custom-hide-popup-function))))
+
+(defun which-key--hide-popup-on-frame-size-change (&optional _)
+ "Hide which-key popup if the frame is resized (to trigger a new popup)."
+ (when (which-key--frame-size-changed-p)
+ (which-key--hide-popup)))
+
+(defun which-key--hide-buffer-side-window ()
+ "Hide which-key buffer when side-window popup is used."
+ (when (buffer-live-p which-key--buffer)
+ ;; in case which-key buffer was shown in an existing window, `quit-window'
+ ;; will re-show the previous buffer, instead of closing the window
+ (quit-windows-on which-key--buffer)
+ (when (and which-key-preserve-window-configuration
+ which-key--saved-window-configuration)
+ (set-window-configuration which-key--saved-window-configuration)
+ (setq which-key--saved-window-configuration nil))))
+
+(defun which-key--hide-buffer-frame ()
+ "Hide which-key buffer when frame popup is used."
+ (when (frame-live-p which-key--frame)
+ (delete-frame which-key--frame)))
+
+(defun which-key--popup-showing-p ()
+ (and (bufferp which-key--buffer)
+ (or (window-live-p (get-buffer-window which-key--buffer))
+ (let ((window (get-buffer-window which-key--buffer t)))
+ (and (window-live-p window)
+ (frame-visible-p (window-frame window)))))))
+
+(defun which-key--show-popup (act-popup-dim)
+ "Show the which-key buffer.
+ACT-POPUP-DIM includes the dimensions, (height . width) of the
+buffer text to be displayed in the popup. Return nil if no window
+is shown, or if there is no need to start the closing timer."
+ (when (and (> (car act-popup-dim) 0)
+ (> (cdr act-popup-dim) 0))
+ (cl-case which-key-popup-type
+ ;; Not called for minibuffer
+ ;; (minibuffer (which-key--show-buffer-minibuffer act-popup-dim))
+ (side-window (which-key--show-buffer-side-window act-popup-dim))
+ (frame (which-key--show-buffer-frame act-popup-dim))
+ (custom (funcall which-key-custom-show-popup-function act-popup-dim)))))
+
+(defun which-key--fit-buffer-to-window-horizontally
+ (&optional window &rest params)
+ "Slightly modified version of `fit-buffer-to-window'.
+Use &rest params because `fit-buffer-to-window' has a different
+call signature in different emacs versions"
+ (let ((fit-window-to-buffer-horizontally t)
+ (window-min-height 1))
+ (apply #'fit-window-to-buffer window params)))
+
+(defun which-key--show-buffer-side-window (act-popup-dim)
+ "Show which-key buffer when popup type is side-window."
+ (when (and which-key-preserve-window-configuration
+ (not which-key--saved-window-configuration))
+ (setq which-key--saved-window-configuration (current-window-configuration)))
+ (let* ((height (car act-popup-dim))
+ (width (cdr act-popup-dim))
+ (alist
+ (if which-key-allow-imprecise-window-fit
+ `((window-width . ,(which-key--text-width-to-total width))
+ (window-height . ,height)
+ (side . ,which-key-side-window-location)
+ (slot . ,which-key-side-window-slot))
+ `((window-width . which-key--fit-buffer-to-window-horizontally)
+ (window-height . (lambda (w) (fit-window-to-buffer w nil 1)))
+ (side . ,which-key-side-window-location)
+ (slot . ,which-key-side-window-slot)))))
+ ;; Previously used `display-buffer-in-major-side-window' here, but
+ ;; apparently that is meant to be an internal function. See emacs bug #24828
+ ;; and advice given there.
+ (cond
+ ((eq which-key--multiple-locations t)
+ ;; possibly want to switch sides in this case so we can't reuse the window
+ (delete-windows-on which-key--buffer)
+ (display-buffer-in-side-window which-key--buffer alist))
+ ((get-buffer-window which-key--buffer)
+ (display-buffer-reuse-window which-key--buffer alist))
+ (t
+ (display-buffer-in-side-window which-key--buffer alist)))))
+
+(defun which-key--show-buffer-frame (act-popup-dim)
+ "Show which-key buffer when popup type is frame."
+ (let* (;(orig-window (selected-window))
+ (frame-height (+ (car act-popup-dim)
+ (if (with-current-buffer which-key--buffer
+ mode-line-format)
+ 1
+ 0)))
+ ;; without adding 2, frame sometimes isn't wide enough for the buffer.
+ ;; this is probably because of the fringes. however, setting fringes
+ ;; sizes to 0 (instead of adding 2) didn't always make the frame wide
+ ;; enough. don't know why it is so.
+ (frame-width (+ (cdr act-popup-dim) 2))
+ (new-window (if (and (frame-live-p which-key--frame)
+ (eq which-key--buffer
+ (window-buffer
+ (frame-root-window which-key--frame))))
+ (which-key--show-buffer-reuse-frame
+ frame-height frame-width)
+ (which-key--show-buffer-new-frame
+ frame-height frame-width))))
+ (when new-window
+ ;; display successful
+ (setq which-key--frame (window-frame new-window))
+ new-window)))
+
+(defun which-key--show-buffer-new-frame (frame-height frame-width)
+ "Helper for `which-key--show-buffer-frame'."
+ (let* ((frame-params `((height . ,frame-height)
+ (width . ,frame-width)
+ ;; tell the window manager to respect the given sizes
+ (user-size . t)
+ ;; which-key frame doesn't need a minibuffer
+ (minibuffer . nil)
+ (name . "which-key")
+ ;; no need for scroll bars in which-key frame
+ (vertical-scroll-bars . nil)
+ ;; (left-fringe . 0)
+ ;; (right-fringe . 0)
+ ;; (right-divider-width . 0)
+ ;; make sure frame is visible
+ (visibility . t)))
+ (alist `((pop-up-frame-parameters . ,frame-params)))
+ (orig-frame (selected-frame))
+ (new-window (display-buffer-pop-up-frame which-key--buffer alist)))
+ (when new-window
+ ;; display successful
+ (redirect-frame-focus (window-frame new-window) orig-frame)
+ new-window)))
+
+(defun which-key--show-buffer-reuse-frame (frame-height frame-width)
+ "Helper for `which-key--show-buffer-frame'."
+ (let ((window
+ (display-buffer-reuse-window
+ which-key--buffer `((reusable-frames . ,which-key--frame)))))
+ (when window
+ ;; display successful
+ (set-frame-size (window-frame window) frame-width frame-height)
+ window)))
+
+;;; Max dimension of available window functions
+
+(defun which-key--popup-max-dimensions ()
+ "Dimesion functions should return the maximum possible (height
+. width) of the intended popup. SELECTED-WINDOW-WIDTH is the
+width of currently active window, not the which-key buffer
+window."
+ (cl-case which-key-popup-type
+ (minibuffer (which-key--minibuffer-max-dimensions))
+ (side-window (which-key--side-window-max-dimensions))
+ (frame (which-key--frame-max-dimensions))
+ (custom (funcall which-key-custom-popup-max-dimensions-function
+ (window-width)))))
+
+(defun which-key--minibuffer-max-dimensions ()
+ "Return max-dimensions of minibuffer (height . width).
+Measured in lines and characters respectively."
+ (cons
+ ;; height
+ (if (floatp max-mini-window-height)
+ (floor (* (frame-text-lines)
+ max-mini-window-height))
+ max-mini-window-height)
+ ;; width
+ (max 0 (- (frame-text-cols) which-key-unicode-correction))))
+
+(defun which-key--side-window-max-dimensions ()
+ "Return max-dimensions of the side-window popup (height .
+width) in lines and characters respectively."
+ (cons
+ ;; height
+ (if (member which-key-side-window-location '(left right))
+ ;; 1 is a kludge to make sure there is no overlap
+ (- (frame-height) (window-text-height (minibuffer-window)) 1)
+ ;; (window-mode-line-height which-key--window))
+ ;; FIXME: change to something like
+ ;; (min which-*-height (calculate-max-height))
+ (which-key--height-or-percentage-to-height
+ which-key-side-window-max-height))
+ ;; width
+ (max 0
+ (- (if (member which-key-side-window-location '(left right))
+ (which-key--total-width-to-text
+ (which-key--width-or-percentage-to-width
+ which-key-side-window-max-width))
+ (which-key--total-width-to-text
+ (which-key--width-or-percentage-to-width
+ 1.0)))
+ which-key-unicode-correction))))
+
+(defun which-key--frame-max-dimensions ()
+ "Return max-dimensions of the frame popup (height .
+width) in lines and characters respectively."
+ (cons which-key-frame-max-height which-key-frame-max-width))
+
+;;; Sorting functions
+
+(defun which-key--string< (a b &optional alpha)
+ (let ((da (downcase a))
+ (db (downcase b)))
+ (cond
+ ((and alpha (not which-key-sort-uppercase-first))
+ (if (string-equal da db)
+ (not (string-lessp a b))
+ (string-lessp da db)))
+ ((and alpha which-key-sort-uppercase-first)
+ (if (string-equal da db)
+ (string-lessp a b)
+ (string-lessp da db)))
+ ((not which-key-sort-uppercase-first)
+ (let ((aup (not (string-equal da a)))
+ (bup (not (string-equal db b))))
+ (if (eq aup bup)
+ (string-lessp a b)
+ bup)))
+ (t (string-lessp a b)))))
+
+(defun which-key--key-description< (a b &optional alpha)
+ "Sorting function used for `which-key-key-order' and
+`which-key-key-order-alpha'."
+ (save-match-data
+ (let* ((a (which-key--extract-key a))
+ (b (which-key--extract-key b))
+ (rngrgxp "^\\([^ ]+\\) \\.\\. [^ ]+")
+ (a (if (string-match rngrgxp a) (match-string 1 a) a))
+ (b (if (string-match rngrgxp b) (match-string 1 b) b))
+ (aem? (string-equal a ""))
+ (bem? (string-equal b ""))
+ (a1? (= 1 (length a)))
+ (b1? (= 1 (length b)))
+ (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
+ (asp? (string-match-p srgxp a))
+ (bsp? (string-match-p srgxp b))
+ (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
+ (apr? (string-match-p prrgxp a))
+ (bpr? (string-match-p prrgxp b))
+ (afn? (string-match-p "<f[0-9]+>" a))
+ (bfn? (string-match-p "<f[0-9]+>" b)))
+ (cond ((or aem? bem?) (and aem? (not bem?)))
+ ((and asp? bsp?)
+ (if (string-equal (substring a 0 3) (substring b 0 3))
+ (which-key--key-description<
+ (substring a 3) (substring b 3) alpha)
+ (which-key--string< a b alpha)))
+ ((or asp? bsp?) asp?)
+ ((and a1? b1?) (which-key--string< a b alpha))
+ ((or a1? b1?) a1?)
+ ((and afn? bfn?)
+ (< (string-to-number
+ (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" a))
+ (string-to-number
+ (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" b))))
+ ((or afn? bfn?) afn?)
+ ((and apr? bpr?)
+ (if (string-equal (substring a 0 2) (substring b 0 2))
+ (which-key--key-description<
+ (substring a 2) (substring b 2) alpha)
+ (which-key--string< a b alpha)))
+ ((or apr? bpr?) apr?)
+ (t (which-key--string< a b alpha))))))
+
+(defsubst which-key-key-order-alpha (acons bcons)
+ "Order key descriptions A and B.
+Order is lexicographic within a \"class\", where the classes and
+the ordering of classes are listed below.
+
+special (SPC,TAB,...) < single char < mod (C-,M-,...) < other.
+Sorts single characters alphabetically with lowercase coming
+before upper."
+ (which-key--key-description< (car acons) (car bcons) t))
+
+(defsubst which-key-key-order (acons bcons)
+ "Order key descriptions A and B.
+Order is lexicographic within a \"class\", where the classes and
+the ordering of classes are listed below.
+
+special (SPC,TAB,...) < single char < mod (C-,M-,...) < other."
+ (which-key--key-description< (car acons) (car bcons)))
+
+(defsubst which-key-description-order (acons bcons)
+ "Order descriptions of A and B.
+Uses `string-lessp' after applying lowercase."
+ (string-lessp (downcase (cdr acons)) (downcase (cdr bcons))))
+
+(defsubst which-key--group-p (description)
+ (or (string-equal description "prefix")
+ (string-match-p "^group:" description)
+ (keymapp (intern description))))
+
+(defun which-key-prefix-then-key-order (acons bcons)
+ "Order first by whether A and/or B is a prefix with no prefix
+coming before a prefix. Within these categories order using
+`which-key-key-order'."
+ (let ((apref? (which-key--group-p (cdr acons)))
+ (bpref? (which-key--group-p (cdr bcons))))
+ (if (not (eq apref? bpref?))
+ (and (not apref?) bpref?)
+ (which-key-key-order acons bcons))))
+
+(defun which-key-prefix-then-key-order-reverse (acons bcons)
+ "Order first by whether A and/or B is a prefix with prefix
+coming before a prefix. Within these categories order using
+`which-key-key-order'."
+ (let ((apref? (which-key--group-p (cdr acons)))
+ (bpref? (which-key--group-p (cdr bcons))))
+ (if (not (eq apref? bpref?))
+ (and apref? (not bpref?))
+ (which-key-key-order acons bcons))))
+
+(defun which-key-local-then-key-order (acons bcons)
+ "Order first by whether A and/or B is a local binding with
+local bindings coming first. Within these categories order using
+`which-key-key-order'."
+ (let ((aloc? (which-key--local-binding-p acons))
+ (bloc? (which-key--local-binding-p bcons)))
+ (if (not (eq aloc? bloc?))
+ (and aloc? (not bloc?))
+ (which-key-key-order acons bcons))))
+
+;;; Functions for retrieving and formatting keys
+
+(defsubst which-key--string-width (maybe-string)
+ "If MAYBE-STRING is a string use `which-key--string-width' o/w return 0."
+ (if (stringp maybe-string) (string-width maybe-string) 0))
+
+(defsubst which-key--butlast-string (str)
+ (mapconcat #'identity (butlast (split-string str)) " "))
+
+(defun which-key--match-replacement (key-binding replacement)
+ ;; these are mode specific ones to ignore. The mode specific case is
+ ;; handled in the selection of alist
+ (when (and (consp key-binding) (not (symbolp (car replacement))))
+ (let ((key-regexp (caar replacement))
+ (binding-regexp (cdar replacement))
+ case-fold-search)
+ (and (or (null key-regexp)
+ (string-match-p key-regexp
+ (car key-binding)))
+ (or (null binding-regexp)
+ (string-match-p binding-regexp
+ (cdr key-binding)))))))
+
+(defsubst which-key--replace-in-binding (key-binding repl)
+ (cond ((or (not (consp repl)) (null (cdr repl)))
+ key-binding)
+ ((functionp (cdr repl))
+ (funcall (cdr repl) key-binding))
+ ((consp (cdr repl))
+ (cons
+ (cond ((and (caar repl) (cadr repl))
+ (replace-regexp-in-string
+ (caar repl) (cadr repl) (car key-binding) t))
+ ((cadr repl) (cadr repl))
+ (t (car key-binding)))
+ (cond ((and (cdar repl) (cddr repl))
+ (replace-regexp-in-string
+ (cdar repl) (cddr repl) (cdr key-binding) t))
+ ((cddr repl) (cddr repl))
+ (t (cdr key-binding)))))))
+
+(defun which-key--replace-in-repl-list-once (key-binding repls)
+ (cl-dolist (repl repls)
+ (when (which-key--match-replacement key-binding repl)
+ (cl-return `(replaced . ,(which-key--replace-in-binding key-binding repl))))))
+
+(defun which-key--replace-in-repl-list-many (key-binding repls)
+ (let (found)
+ (dolist (repl repls)
+ (when (which-key--match-replacement key-binding repl)
+ (setq found 't)
+ (setq key-binding (which-key--replace-in-binding key-binding repl))))
+ (when found `(replaced . ,key-binding))))
+
+(defun which-key--maybe-replace (key-binding)
+ "Use `which-key--replacement-alist' to maybe replace KEY-BINDING.
+KEY-BINDING is a cons cell of the form \(KEY . BINDING\) each of
+which are strings. KEY is of the form produced by `key-binding'."
+ (let* ((replacer (if which-key-allow-multiple-replacements
+ #'which-key--replace-in-repl-list-many
+ #'which-key--replace-in-repl-list-once)))
+ (pcase
+ (apply replacer
+ (list key-binding
+ (cdr-safe (assq major-mode which-key-replacement-alist))))
+ (`(replaced . ,repl)
+ (if which-key-allow-multiple-replacements
+ (pcase (apply replacer (list repl which-key-replacement-alist))
+ (`(replaced . ,repl) repl)
+ ('() repl))
+ repl))
+ ('()
+ (pcase (apply replacer (list key-binding which-key-replacement-alist))
+ (`(replaced . ,repl) repl)
+ ('() key-binding))))))
+
+(defsubst which-key--current-key-list (&optional key-str)
+ (append (listify-key-sequence (which-key--current-prefix))
+ (when key-str
+ (listify-key-sequence (kbd key-str)))))
+
+(defsubst which-key--current-key-string (&optional key-str)
+ (key-description (which-key--current-key-list key-str)))
+
+(defun which-key--local-binding-p (keydesc)
+ (eq (which-key--safe-lookup-key-description
+ (current-local-map)
+ (which-key--current-key-string (car keydesc)))
+ (intern (cdr keydesc))))
+
+(defun which-key--map-binding-p (map keydesc)
+ "Does MAP contain KEYDESC = (key . binding)?"
+ (or
+ (when (bound-and-true-p evil-state)
+ (let ((lookup
+ (which-key--safe-lookup-key-description
+ map
+ (which-key--current-key-string
+ (format "<%s-state> %s" evil-state (car keydesc))))))
+ (or (eq lookup (intern (cdr keydesc)))
+ (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command")))))
+ (let ((lookup
+ (which-key--safe-lookup-key-description
+ map (which-key--current-key-string (car keydesc)))))
+ (or (eq lookup (intern (cdr keydesc)))
+ (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command"))))))
+
+(defun which-key--maybe-get-prefix-title (keys)
+ "KEYS is a string produced by `key-description'.
+A title is possibly returned using
+`which-key--prefix-title-alist'. An empty string is returned if
+no title exists."
+ (cond
+ ((not (string-equal keys ""))
+ (let* ((title-res
+ (cdr-safe (assoc-string keys which-key--prefix-title-alist)))
+ (repl-res
+ (cdr-safe (which-key--maybe-replace (cons keys ""))))
+ (binding (key-binding (kbd keys)))
+ (alternate (when (and binding (symbolp binding))
+ (symbol-name binding))))
+ (cond (title-res title-res)
+ ((not (string-equal repl-res "")) repl-res)
+ ((and (eq which-key-show-prefix 'echo) alternate)
+ alternate)
+ ((and (member which-key-show-prefix '(bottom top mode-line))
+ (eq which-key-side-window-location 'bottom)
+ echo-keystrokes)
+ (if alternate alternate
+ (concat "Following " keys)))
+ (t ""))))
+ (t "")))
+
+(defun which-key--propertize (string &rest properties)
+ "Version of `propertize' that checks type of STRING."
+ (when (stringp string)
+ (apply #'propertize string properties)))
+
+(defun which-key--propertize-key (key)
+ "Add a face to KEY.
+If KEY contains any \"special keys\" defined in
+`which-key-special-keys' then truncate and add the corresponding
+`which-key-special-key-face'."
+ (let ((key-w-face (which-key--propertize key 'face 'which-key-key-face))
+ (regexp (concat "\\("
+ (mapconcat #'identity which-key-special-keys
+ "\\|")
+ "\\)"))
+ case-fold-search)
+ (save-match-data
+ (if (and which-key-special-keys
+ (string-match regexp key))
+ (let ((beg (match-beginning 0)) (end (match-end 0)))
+ (concat (substring key-w-face 0 beg)
+ (which-key--propertize (substring key-w-face beg (1+ beg))
+ 'face 'which-key-special-key-face)
+ (substring key-w-face end
+ (which-key--string-width key-w-face))))
+ key-w-face))))
+
+(defsubst which-key--truncate-description (desc avl-width)
+ "Truncate DESC description to `which-key-max-description-length'."
+ (let* ((max which-key-max-description-length)
+ (max (cl-etypecase max
+ (null nil)
+ (integer max)
+ (float (truncate (* max avl-width)))
+ (function (let ((val (funcall max avl-width)))
+ (if (floatp val) (truncate val) val))))))
+ (if (and max (> (length desc) max))
+ (let ((dots (and (not (equal which-key-ellipsis ""))
+ (which-key--propertize
+ which-key-ellipsis 'face
+ (get-text-property (1- (length desc)) 'face desc)))))
+ (if dots
+ (concat (substring desc 0 (- max (length dots))) dots)
+ (substring desc 0 max)))
+ desc)))
+
+(defun which-key--highlight-face (description)
+ "Return the highlight face for DESCRIPTION if it has one."
+ (let (face)
+ (dolist (el which-key-highlighted-command-list)
+ (unless face
+ (cond ((consp el)
+ (when (string-match-p (car el) description)
+ (setq face (cdr el))))
+ ((stringp el)
+ (when (string-match-p el description)
+ (setq face 'which-key-highlighted-command-face)))
+ (t
+ (message "which-key: warning: element %s of \
+which-key-highlighted-command-list is not a string or a cons
+cell" el)))))
+ face))
+
+(defun which-key--propertize-description
+ (description group local hl-face &optional original-description)
+ "Add face to DESCRIPTION where the face chosen depends on
+whether the description represents a group or a command. Also
+make some minor adjustments to the description string, like
+removing a \"group:\" prefix.
+
+ORIGINAL-DESCRIPTION is the description given by
+`describe-buffer-bindings'."
+ (when description
+ (let* ((desc description)
+ (desc (if (string-match-p "^group:" desc)
+ (substring desc 6) desc))
+ (desc (if group (concat which-key-prefix-prefix desc) desc)))
+ (make-text-button
+ desc nil
+ 'face (cond (hl-face hl-face)
+ (group 'which-key-group-description-face)
+ (local 'which-key-local-map-description-face)
+ (t 'which-key-command-description-face))
+ 'help-echo (cond
+ ((and original-description
+ (fboundp (intern original-description))
+ (documentation (intern original-description))
+ ;; tooltip-mode doesn't exist in emacs-nox
+ (boundp 'tooltip-mode) tooltip-mode)
+ (documentation (intern original-description)))
+ ((and original-description
+ (fboundp (intern original-description))
+ (documentation (intern original-description))
+ (let* ((doc (documentation
+ (intern original-description)))
+ (str (replace-regexp-in-string "\n" " " doc))
+ (max (floor (* (frame-width) 0.8))))
+ (if (> (length str) max)
+ (concat (substring str 0 max) "...")
+ str)))))))))
+
+(defun which-key--extract-key (key-str)
+ "Pull the last key (or key range) out of KEY-STR."
+ (save-match-data
+ (let ((key-range-regexp "\\`.*\\([^ \t]+ \\.\\. [^ \t]+\\)\\'"))
+ (if (string-match key-range-regexp key-str)
+ (match-string 1 key-str)
+ (car (last (split-string key-str " ")))))))
+
+(defun which-key--maybe-add-docstring (current original)
+ "Maybe concat a docstring to CURRENT and return result.
+Specifically, do this if ORIGINAL is a command with a docstring
+and `which-key-show-docstrings' is non-nil. If
+`which-key-show-docstrings' is the symbol docstring-only, just
+return the docstring."
+ (let* ((orig-sym (intern original))
+ (doc (when (commandp orig-sym)
+ (documentation orig-sym)))
+ (doc (when doc
+ (replace-regexp-in-string
+ (concat "^\\(?::"
+ (regexp-opt '("around" "override"
+ "after" "after-until" "after-while"
+ "before" "before-until" "before-while"
+ "filter-args" "filter-return"))
+ " advice: [^\n]+\n"
+ "\\)+\n")
+ "" doc)))
+ (docstring (when doc
+ (which-key--propertize (car (split-string doc "\n"))
+ 'face 'which-key-docstring-face))))
+ (cond ((not (and which-key-show-docstrings docstring))
+ current)
+ ((eq which-key-show-docstrings 'docstring-only)
+ docstring)
+ (t
+ (format "%s %s" current docstring)))))
+
+(defun which-key--format-and-replace (unformatted &optional preserve-full-key)
+ "Take a list of (key . desc) cons cells in UNFORMATTED, add
+faces and perform replacements according to the three replacement
+alists. Returns a list (key separator description)."
+ (let ((sep-w-face
+ (which-key--propertize which-key-separator
+ 'face 'which-key-separator-face))
+ (local-map (current-local-map))
+ (avl-width (cdr (which-key--popup-max-dimensions)))
+ new-list)
+ (dolist (key-binding unformatted)
+ (let* ((keys (car key-binding))
+ (orig-desc (cdr key-binding))
+ (group (which-key--group-p orig-desc))
+ (local (eq (which-key--safe-lookup-key-description
+ local-map keys)
+ (intern orig-desc)))
+ (hl-face (which-key--highlight-face orig-desc))
+ (key-binding (which-key--maybe-replace key-binding))
+ (final-desc (which-key--propertize-description
+ (cdr key-binding) group local hl-face orig-desc)))
+ (when final-desc
+ (setq final-desc
+ (which-key--truncate-description
+ (which-key--maybe-add-docstring final-desc orig-desc)
+ avl-width)))
+ (when (consp key-binding)
+ (push
+ (list (which-key--propertize-key
+ (if preserve-full-key
+ (car key-binding)
+ (which-key--extract-key (car key-binding))))
+ sep-w-face
+ final-desc)
+ new-list))))
+ (nreverse new-list)))
+
+(defun which-key--compute-binding (binding)
+ "Replace BINDING with remapped binding if it exists.
+
+Requires `which-key-compute-remaps' to be non-nil"
+ (let (remap)
+ (if (and which-key-compute-remaps
+ (setq remap (command-remapping binding)))
+ (copy-sequence (symbol-name remap))
+ (copy-sequence (symbol-name binding)))))
+
+(defun which-key--get-menu-item-binding (def)
+ "Retrieve binding for menu-item"
+ ;; see `keymap--menu-item-binding'
+ (let* ((binding (nth 2 def))
+ (plist (nthcdr 3 def))
+ (filter (plist-get plist :filter)))
+ (if filter (funcall filter binding) binding)))
+
+(defun which-key--get-keymap-bindings-1
+ (keymap start &optional prefix filter all ignore-commands)
+ "See `which-key--get-keymap-bindings'."
+ (let ((bindings start)
+ (prefix-map (if prefix (lookup-key keymap prefix) keymap)))
+ (when (keymapp prefix-map)
+ (map-keymap
+ (lambda (ev def)
+ (let* ((key (vconcat prefix (list ev)))
+ (key-desc (key-description key)))
+ (cond
+ ((assoc key-desc bindings))
+ ((and (listp ignore-commands) (symbolp def) (memq def ignore-commands)))
+ ((or (string-match-p
+ which-key--ignore-non-evil-keys-regexp key-desc)
+ (eq ev 'menu-bar)))
+ ((and (keymapp def)
+ (string-match-p which-key--evil-keys-regexp key-desc)))
+ ((and (keymapp def)
+ (or all
+ ;; event 27 is escape, so this will pick up meta
+ ;; bindings and hopefully not too much more
+ (and (numberp ev) (= ev 27))))
+ (setq bindings
+ (which-key--get-keymap-bindings-1
+ keymap bindings key nil all ignore-commands)))
+ (def
+ (let* ((def (if (eq 'menu-item (car-safe def))
+ (which-key--get-menu-item-binding def)
+ def))
+ (binding
+ (cons key-desc
+ (cond
+ ((symbolp def) (which-key--compute-binding def))
+ ((keymapp def) "prefix")
+ ((eq 'lambda (car-safe def)) "lambda")
+ ((eq 'closure (car-safe def)) "closure")
+ ((stringp def) def)
+ ((vectorp def) (key-description def))
+ ((and (consp def)
+ ;; looking for (STRING . DEFN)
+ (stringp (car def)))
+ (concat (when (keymapp (cdr-safe def))
+ "group:")
+ (car def)))
+ (t "unknown")))))
+ (when (or (null filter)
+ (and (functionp filter)
+ (funcall filter binding)))
+ (push binding bindings)))))))
+ prefix-map))
+ bindings))
+
+(defun which-key--get-keymap-bindings
+ (keymap &optional start prefix filter all evil)
+ "Retrieve top-level bindings from KEYMAP.
+PREFIX limits bindings to those starting with this key
+sequence. START is a list of existing bindings to add to. If ALL
+is non-nil, recursively retrieve all bindings below PREFIX. If
+EVIL is non-nil, extract active evil bidings."
+ (let ((bindings start)
+ (ignore '(self-insert-command ignore ignore-event company-ignore))
+ (evil-map
+ (when (and evil (bound-and-true-p evil-local-mode))
+ (lookup-key keymap (kbd (format "<%s-state>" evil-state))))))
+ (when (keymapp evil-map)
+ (setq bindings (which-key--get-keymap-bindings-1
+ evil-map bindings prefix filter all ignore)))
+ (which-key--get-keymap-bindings-1
+ keymap bindings prefix filter all ignore)))
+
+(defun which-key--get-current-bindings (&optional prefix filter)
+ "Generate a list of current active bindings."
+ (let (bindings)
+ (dolist (map (current-active-maps t) bindings)
+ (when (cdr map)
+ (setq bindings
+ (which-key--get-keymap-bindings
+ map bindings prefix filter))))))
+
+(defun which-key--get-bindings (&optional prefix keymap filter recursive)
+ "Collect key bindings.
+If KEYMAP is nil, collect from current buffer using the current
+key sequence as a prefix. Otherwise, collect from KEYMAP. FILTER
+is a function to use to filter the bindings. If RECURSIVE is
+non-nil, then bindings are collected recursively for all prefixes."
+ (let* ((unformatted
+ (cond ((keymapp keymap)
+ (which-key--get-keymap-bindings
+ keymap nil prefix filter recursive))
+ (keymap
+ (error "%s is not a keymap" keymap))
+ (t
+ (which-key--get-current-bindings prefix filter)))))
+ (when which-key-sort-order
+ (setq unformatted
+ (sort unformatted which-key-sort-order)))
+ (which-key--format-and-replace unformatted recursive)))
+
+;;; Functions for laying out which-key buffer pages
+
+(defun which-key--normalize-columns (columns)
+ "Pad COLUMNS to the same length using empty strings."
+ (let ((max-len (cl-reduce (lambda (a x) (max a (length x))) columns
+ :initial-value 0)))
+ (mapcar
+ (lambda (c)
+ (if (< (length c) max-len)
+ (append c (make-list (- max-len (length c)) ""))
+ c))
+ columns)))
+
+(defsubst which-key--join-columns (columns)
+ "Transpose columns into rows, concat rows into lines and rows into page."
+ (let* ((padded (which-key--normalize-columns (nreverse columns)))
+ (rows (apply #'cl-mapcar #'list padded)))
+ (mapconcat (lambda (row) (mapconcat #'identity row " ")) rows "\n")))
+
+(defsubst which-key--max-len (keys index &optional initial-value)
+ "Internal function for finding the max length of the INDEX
+element in each list element of KEYS."
+ (cl-reduce
+ (lambda (x y) (max x (which-key--string-width (nth index y))))
+ keys :initial-value (if initial-value initial-value 0)))
+
+(defun which-key--pad-column (col-keys avl-width)
+ "Take a column of (key separator description) COL-KEYS,
+calculate the max width in the column and pad all cells out to
+that width."
+ (let* ((col-key-width (+ which-key-add-column-padding
+ (which-key--max-len col-keys 0)))
+ (col-sep-width (which-key--max-len col-keys 1))
+ (avl-width (- avl-width col-key-width col-sep-width))
+ (col-desc-width (min avl-width
+ (which-key--max-len
+ col-keys 2
+ which-key-min-column-description-width)))
+ (col-width (+ col-key-width col-sep-width col-desc-width))
+ (col-format (concat "%" (int-to-string col-key-width)
+ "s%s%-" (int-to-string col-desc-width) "s")))
+ (cons col-width
+ (mapcar (lambda (k) (apply #'format col-format k))
+ col-keys))))
+
+(defun which-key--partition-list (n list)
+ "Partition LIST into N-sized sublists."
+ (let (res)
+ (while list
+ (setq res (cons (cl-subseq list 0 (min n (length list))) res)
+ list (nthcdr n list)))
+ (nreverse res)))
+
+(defun which-key--list-to-pages (keys avl-lines avl-width)
+ "Convert list of KEYS to columns based on dimensions AVL-LINES and AVL-WIDTH.
+Returns a `which-key--pages' object that holds the page strings,
+as well as metadata."
+ (let ((cols-w-widths (mapcar (lambda (c) (which-key--pad-column c avl-width))
+ (which-key--partition-list avl-lines keys)))
+ (page-width 0) (n-pages 0) (n-keys 0) (n-columns 0)
+ page-cols pages page-widths keys/page col)
+ (if (> (apply #'max (mapcar #'car cols-w-widths)) avl-width)
+ ;; give up if no columns fit
+ nil
+ (while cols-w-widths
+ ;; start new page
+ (cl-incf n-pages)
+ (setq col (pop cols-w-widths))
+ (setq page-cols (list (cdr col)))
+ (setq page-width (car col))
+ (setq n-keys (length (cdr col)))
+ (setq n-columns 1)
+ ;; add additional columns as long as they fit
+ (while (and cols-w-widths
+ (or (null which-key-max-display-columns)
+ (< n-columns which-key-max-display-columns))
+ (<= (+ page-width 1 (caar cols-w-widths)) avl-width))
+ (setq col (pop cols-w-widths))
+ (push (cdr col) page-cols)
+ (cl-incf page-width (1+ (car col)))
+ (cl-incf n-keys (length (cdr col)))
+ (cl-incf n-columns))
+ (push (which-key--join-columns page-cols) pages)
+ (push n-keys keys/page)
+ (push page-width page-widths))
+ (make-which-key--pages
+ :pages (nreverse pages)
+ :height (if (> n-pages 1) avl-lines (min avl-lines n-keys))
+ :widths (nreverse page-widths)
+ :keys/page (reverse keys/page)
+ :page-nums (number-sequence 1 n-pages)
+ :num-pages n-pages
+ :total-keys (apply #'+ keys/page)))))
+
+(defun which-key--create-pages-1
+ (keys available-lines available-width &optional min-lines vertical)
+ "Create page strings using `which-key--list-to-pages'.
+Will try to find the best number of rows and columns using the
+given dimensions and the length and widths of ITEMS. Use VERTICAL
+if the ITEMS are laid out vertically and the number of columns
+should be minimized."
+ (let ((result (which-key--list-to-pages
+ keys available-lines available-width))
+ (min-lines (or min-lines 0))
+ found prev-result)
+ (if (or (null result)
+ vertical
+ (> (which-key--pages-num-pages result) 1)
+ (= 1 available-lines))
+ result
+ ;; simple search for a fitting page
+ (while (and (> available-lines min-lines)
+ (not found))
+ (setq available-lines (- available-lines 1)
+ prev-result result
+ result (which-key--list-to-pages
+ keys available-lines available-width)
+ found (> (which-key--pages-num-pages result) 1)))
+ (if found prev-result result))))
+
+(defun which-key--create-pages (keys &optional prefix-keys prefix-title)
+ "Create page strings using `which-key--list-to-pages'.
+Will try to find the best number of rows and columns using the
+given dimensions and the length and wdiths of KEYS. SEL-WIN-WIDTH
+is the width of the live window."
+ (let* ((max-dims (which-key--popup-max-dimensions))
+ (max-lines (car max-dims))
+ (max-width (cdr max-dims))
+ (prefix-desc (key-description prefix-keys))
+ (full-prefix (which-key--full-prefix prefix-desc))
+ (prefix (when (eq which-key-show-prefix 'left)
+ (+ 2 (which-key--string-width full-prefix))))
+ (prefix-top-bottom (member which-key-show-prefix '(bottom top)))
+ (avl-lines (if prefix-top-bottom (- max-lines 1) max-lines))
+ (min-lines (min avl-lines which-key-min-display-lines))
+ (avl-width (if prefix (- max-width prefix) max-width))
+ (vertical (or (and (eq which-key-popup-type 'side-window)
+ (member which-key-side-window-location '(left right)))
+ (eq which-key-max-display-columns 1)))
+ result)
+ (setq result
+ (which-key--create-pages-1
+ keys avl-lines avl-width min-lines vertical))
+ (when (and result
+ (> (which-key--pages-num-pages result) 0))
+ (setf (which-key--pages-prefix result) prefix-keys)
+ (setf (which-key--pages-prefix-title result)
+ (or prefix-title
+ (which-key--maybe-get-prefix-title
+ (key-description prefix-keys))))
+ (when prefix-top-bottom
+ ;; Add back the line earlier reserved for the page information.
+ (setf (which-key--pages-height result) max-lines))
+ (when (and (= (which-key--pages-num-pages result) 1)
+ (> which-key-min-display-lines
+ (which-key--pages-height result)))
+ ;; result is shorter than requested, so we artificially increase the
+ ;; height. See #325. Note this only has an effect if
+ ;; `which-key-allow-imprecise-window-fit' is non-nil.
+ (setf (which-key--pages-height result) which-key-min-display-lines))
+ (which-key--debug-message "Frame height: %s
+Minibuffer height: %s
+Max dimensions: (%s,%s)
+Available for bindings: (%s,%s)
+Actual lines: %s" (frame-height) (window-text-height (minibuffer-window))
+max-lines max-width avl-lines avl-width (which-key--pages-height result))
+ result)))
+
+(defun which-key--lighter-status ()
+ "Possibly show number of keys and total in the mode line."
+ (when which-key-show-remaining-keys
+ (let ((n-shown (car (which-key--pages-keys/page which-key--pages-obj)))
+ (n-tot (which-key--pages-total-keys which-key--pages-obj)))
+ (setcar (cdr (assq 'which-key-mode minor-mode-alist))
+ (format " WK: %s/%s keys" n-shown n-tot)))))
+
+(defun which-key--lighter-restore ()
+ "Restore the lighter for which-key."
+ (when which-key-show-remaining-keys
+ (setcar (cdr (assq 'which-key-mode minor-mode-alist))
+ which-key-lighter)))
+
+(defun which-key--echo (text)
+ "Echo TEXT to minibuffer without logging."
+ (let (message-log-max)
+ (message "%s" text)))
+
+(defun which-key--next-page-hint (prefix-keys)
+ "Return string for next page hint."
+ (let* ((paging-key (concat prefix-keys " " which-key-paging-key))
+ (paging-key-bound (eq 'which-key-C-h-dispatch
+ (key-binding (kbd paging-key))))
+ (key (key-description (vector help-char)))
+ (key (if paging-key-bound
+ (concat key " or " which-key-paging-key)
+ key)))
+ (when (and which-key-use-C-h-commands
+ (not (equal (vector help-char)
+ (vconcat (kbd prefix-keys)))))
+ (which-key--propertize (format "[%s paging/help]" key)
+ 'face 'which-key-note-face))))
+
+(eval-and-compile
+ (if (fboundp 'universal-argument--description)
+ (defalias 'which-key--universal-argument--description
+ #'universal-argument--description)
+ (defun which-key--universal-argument--description ()
+ ;; Backport of the definition of universal-argument--description in
+ ;; emacs25 on 2015-12-04
+ (when prefix-arg
+ (concat "C-u"
+ (pcase prefix-arg
+ (`(-) " -")
+ (`(,(and (pred integerp) n))
+ (let ((str ""))
+ (while (and (> n 4) (= (mod n 4) 0))
+ (setq str (concat str " C-u"))
+ (setq n (/ n 4)))
+ (if (= n 4) str (format " %s" prefix-arg))))
+ (_ (format " %s" prefix-arg))))))))
+
+(defun which-key--full-prefix (prefix-keys &optional -prefix-arg dont-prop-keys)
+ "Return a description of the full key sequence up to now,
+including prefix arguments."
+ (let* ((left (eq which-key-show-prefix 'left))
+ (prefix-arg (if -prefix-arg -prefix-arg prefix-arg))
+ (str (concat
+ (which-key--universal-argument--description)
+ (when prefix-arg " ")
+ prefix-keys))
+ (dash (if (and (not (string= prefix-keys ""))
+ (null left)) "-" "")))
+ (if (or (eq which-key-show-prefix 'echo) dont-prop-keys)
+ (concat str dash)
+ (concat (which-key--propertize-key str)
+ (which-key--propertize dash 'face 'which-key-key-face)))))
+
+(defun which-key--get-popup-map ()
+ "Generate transient-map for use in the top level binding display."
+ (unless which-key--automatic-display
+ (let ((map (make-sparse-keymap)))
+ (define-key map (kbd which-key-paging-key) #'which-key-C-h-dispatch)
+ (when which-key-use-C-h-commands
+ ;; Show next page even when C-h is pressed
+ (define-key map (vector help-char) #'which-key-C-h-dispatch))
+ map)))
+
+(defun which-key--process-page (pages-obj)
+ "Add information to the basic list of key bindings, including
+if applicable the current prefix, the name of the current prefix,
+and a page count."
+ (let* ((page (car (which-key--pages-pages pages-obj)))
+ (height (which-key--pages-height pages-obj))
+ (n-pages (which-key--pages-num-pages pages-obj))
+ (page-n (car (which-key--pages-page-nums pages-obj)))
+ (prefix-desc (key-description (which-key--pages-prefix pages-obj)))
+ (prefix-title (which-key--pages-prefix-title pages-obj))
+ (full-prefix (which-key--full-prefix prefix-desc))
+ (nxt-pg-hint (which-key--next-page-hint prefix-desc))
+ ;; not used in left case
+ (status-line
+ (concat (which-key--propertize prefix-title 'face 'which-key-note-face)
+ (when (< 1 n-pages)
+ (which-key--propertize (format " (%s of %s)" page-n n-pages)
+ 'face 'which-key-note-face)))))
+ (pcase which-key-show-prefix
+ (`left
+ (let* ((page-cnt (which-key--propertize (format "%s/%s" page-n n-pages)
+ 'face 'which-key-separator-face))
+ (first-col-width (+ 2 (max (which-key--string-width full-prefix)
+ (which-key--string-width page-cnt))))
+ (prefix (format (concat "%-" (int-to-string first-col-width) "s")
+ full-prefix))
+ (page-cnt (if (> n-pages 1)
+ (format
+ (concat "%-" (int-to-string first-col-width) "s")
+ page-cnt)
+ (make-string first-col-width 32)))
+ lines first-line new-end)
+ (if (= 1 height)
+ (cons (concat prefix page) nil)
+ (setq lines (split-string page "\n")
+ first-line (concat prefix (car lines) "\n" page-cnt)
+ new-end (concat "\n" (make-string first-col-width 32)))
+ (cons
+ (concat first-line (mapconcat #'identity (cdr lines) new-end))
+ nil))))
+ (`top
+ (cons
+ (concat (when (or (= 0 echo-keystrokes)
+ (not (eq which-key-side-window-location 'bottom)))
+ (concat full-prefix " "))
+ status-line " " nxt-pg-hint "\n" page)
+ nil))
+ (`bottom
+ (cons
+ (concat page "\n"
+ (when (or (= 0 echo-keystrokes)
+ (not (eq which-key-side-window-location 'bottom)))
+ (concat full-prefix " "))
+ status-line " " nxt-pg-hint)
+ nil))
+ (`echo
+ (cons page
+ (lambda ()
+ (which-key--echo
+ (concat full-prefix (when prefix-desc " ")
+ status-line (when status-line " ")
+ nxt-pg-hint)))))
+ (`mode-line
+ (cons page
+ (lambda ()
+ (with-current-buffer which-key--buffer
+ (setq-local mode-line-format
+ (concat " " full-prefix
+ " " status-line
+ " " nxt-pg-hint))))))
+ (_ (cons page nil)))))
+
+(defun which-key--show-page (&optional n)
+ "Show current page.
+N changes the current page to the Nth page relative to the
+current one."
+ (which-key--init-buffer) ;; in case it was killed
+ (let ((prefix-keys (which-key--current-key-string))
+ golden-ratio-mode)
+ (if (null which-key--pages-obj)
+ (message "%s- which-key can't show keys: There is not \
+enough space based on your settings and frame size." prefix-keys)
+ (when n
+ (setq which-key--pages-obj
+ (which-key--pages-set-current-page which-key--pages-obj n)))
+ (let ((page-echo (which-key--process-page which-key--pages-obj))
+ (height (which-key--pages-height which-key--pages-obj))
+ (width (car (which-key--pages-widths which-key--pages-obj))))
+ (which-key--lighter-status)
+ (if (eq which-key-popup-type 'minibuffer)
+ (which-key--echo (car page-echo))
+ (with-current-buffer which-key--buffer
+ (erase-buffer)
+ (insert (car page-echo))
+ (goto-char (point-min)))
+ (when (cdr page-echo) (funcall (cdr page-echo)))
+ (which-key--show-popup (cons height width)))))
+ ;; used for paging at top-level
+ (if (fboundp 'set-transient-map)
+ (set-transient-map (which-key--get-popup-map))
+ (with-no-warnings
+ (set-temporary-overlay-map (which-key--get-popup-map))))))
+
+;;; Paging functions
+
+;;;###autoload
+(defun which-key-reload-key-sequence (&optional key-seq)
+ "Simulate entering the key sequence KEY-SEQ.
+KEY-SEQ should be a list of events as produced by
+`listify-key-sequence'. If nil, KEY-SEQ defaults to
+`which-key--current-key-list'. Any prefix arguments that were
+used are reapplied to the new key sequence."
+ (let* ((key-seq (or key-seq (which-key--current-key-list)))
+ (next-event (mapcar (lambda (ev) (cons t ev)) key-seq)))
+ (setq prefix-arg current-prefix-arg
+ unread-command-events next-event)))
+
+(defun which-key-turn-page (delta)
+ "Show the next page of keys."
+ (which-key-reload-key-sequence)
+ (if which-key--last-try-2-loc
+ (let ((which-key-side-window-location which-key--last-try-2-loc)
+ (which-key--multiple-locations t))
+ (which-key--show-page delta))
+ (which-key--show-page delta))
+ (which-key--start-paging-timer))
+
+;;;###autoload
+(defun which-key-show-standard-help (&optional _)
+ "Call the command in `which-key--prefix-help-cmd-backup'.
+Usually this is `describe-prefix-bindings'."
+ (interactive)
+ (let ((which-key-inhibit t)
+ (popup-showing (which-key--popup-showing-p)))
+ (which-key--hide-popup-ignore-command)
+ (cond ((and (eq which-key--prefix-help-cmd-backup
+ 'describe-prefix-bindings)
+ ;; If the popup is not showing, we call
+ ;; `describe-prefix-bindings' directly.
+ popup-showing)
+ ;; This is essentially what `describe-prefix-bindings' does. We can't
+ ;; use this function directly, because the prefix will not be correct
+ ;; when we enter using `which-key-C-h-dispatch'.
+ (describe-bindings (kbd (which-key--current-key-string))))
+ ((functionp which-key--prefix-help-cmd-backup)
+ (funcall which-key--prefix-help-cmd-backup)))))
+
+;;;###autoload
+(defun which-key-show-next-page-no-cycle ()
+ "Show next page of keys unless on the last page, in which case
+call `which-key-show-standard-help'."
+ (interactive)
+ (let ((which-key-inhibit t))
+ (if (which-key--on-last-page)
+ (which-key-show-standard-help)
+ (which-key-turn-page 1))))
+
+;;;###autoload
+(defun which-key-show-previous-page-no-cycle ()
+ "Show previous page of keys unless on the first page, in which
+case do nothing."
+ (interactive)
+ (let ((which-key-inhibit t))
+ (unless (which-key--on-first-page)
+ (which-key-turn-page -1))))
+
+;;;###autoload
+(defun which-key-show-next-page-cycle (&optional _)
+ "Show the next page of keys, cycling from end to beginning
+after last page."
+ (interactive)
+ (let ((which-key-inhibit t))
+ (which-key-turn-page 1)))
+
+;;;###autoload
+(defun which-key-show-previous-page-cycle (&optional _)
+ "Show the previous page of keys, cycling from beginning to end
+after first page."
+ (interactive)
+ (let ((which-key-inhibit t))
+ (which-key-turn-page -1)))
+
+;;;###autoload
+(defun which-key-show-top-level (&optional _)
+ "Show top-level bindings."
+ (interactive)
+ (which-key--create-buffer-and-show nil nil nil "Top-level bindings"))
+
+;;;###autoload
+(defun which-key-show-major-mode (&optional all)
+ "Show top-level bindings in the map of the current major mode.
+
+This function will also detect evil bindings made using
+`evil-define-key' in this map. These bindings will depend on the
+current evil state. "
+ (interactive "P")
+ (let ((map-sym (intern (format "%s-map" major-mode))))
+ (if (and (boundp map-sym) (keymapp (symbol-value map-sym)))
+ (which-key--show-keymap
+ "Major-mode bindings"
+ (symbol-value map-sym)
+ (apply-partially #'which-key--map-binding-p (symbol-value map-sym))
+ all)
+ (message "which-key: No map named %s" map-sym))))
+
+;;;###autoload
+(defun which-key-show-full-major-mode ()
+ "Show all bindings in the map of the current major mode.
+
+This function will also detect evil bindings made using
+`evil-define-key' in this map. These bindings will depend on the
+current evil state. "
+ (interactive)
+ (which-key-show-major-mode t))
+
+;;;###autoload
+(defun which-key-dump-bindings (prefix buffer-name)
+ "Dump bindings from PREFIX into buffer named BUFFER-NAME.
+
+PREFIX should be a string suitable for `kbd'."
+ (interactive "sPrefix: \nB")
+ (let* ((buffer (get-buffer-create buffer-name))
+ (keys (which-key--get-bindings (kbd prefix))))
+ (with-current-buffer buffer
+ (point-max)
+ (save-excursion
+ (dolist (key keys)
+ (insert (apply #'format "%s%s%s\n" key)))))
+ (switch-to-buffer-other-window buffer)))
+
+;;;###autoload
+(defun which-key-undo-key (&optional _)
+ "Undo last keypress and force which-key update."
+ (interactive)
+ (let* ((key-lst (butlast (which-key--current-key-list)))
+ (which-key-inhibit t))
+ (cond (which-key--prior-show-keymap-args
+ (if (keymapp (cdr (car-safe which-key--prior-show-keymap-args)))
+ (let ((args (pop which-key--prior-show-keymap-args)))
+ (which-key--show-keymap (car args) (cdr args)))
+ (which-key--hide-popup)))
+ (key-lst
+ (which-key-reload-key-sequence key-lst)
+ (which-key--create-buffer-and-show (apply #'vector key-lst)))
+ (t (setq which-key--automatic-display nil)
+ (which-key-show-top-level)))))
+(defalias 'which-key-undo #'which-key-undo-key)
+
+(defun which-key-abort (&optional _)
+ "Abort key sequence."
+ (interactive)
+ (let ((which-key-inhibit t))
+ (which-key--hide-popup-ignore-command)
+ (keyboard-quit)))
+
+(defun which-key-digit-argument (key)
+ "Version of `digit-argument' for use in `which-key-C-h-map'."
+ (interactive)
+ (let ((last-command-event (string-to-char key)))
+ (digit-argument key))
+ (let ((current-prefix-arg prefix-arg))
+ (which-key-reload-key-sequence)))
+
+(defun which-key-toggle-docstrings (&optional _)
+ "Toggle the display of docstrings."
+ (interactive)
+ (unless (eq which-key-show-docstrings 'docstring-only)
+ (setq which-key-show-docstrings (null which-key-show-docstrings)))
+ (which-key-reload-key-sequence)
+ (which-key--create-buffer-and-show (which-key--current-prefix)))
+
+;;;###autoload
+(defun which-key-C-h-dispatch ()
+ "Dispatch C-h commands by looking up key in
+`which-key-C-h-map'. This command is always accessible (from any
+prefix) if `which-key-use-C-h-commands' is non nil."
+ (interactive)
+ (cond ((and (not (which-key--popup-showing-p))
+ which-key-show-early-on-C-h)
+ (let ((current-prefix
+ (butlast
+ (listify-key-sequence (which-key--this-command-keys)))))
+ (which-key-reload-key-sequence current-prefix)
+ (if which-key-idle-secondary-delay
+ (which-key--start-timer which-key-idle-secondary-delay t)
+ (which-key--start-timer 0.05 t))))
+ ((not (which-key--popup-showing-p))
+ (which-key-show-standard-help))
+ (t
+ (if (not (which-key--popup-showing-p))
+ (which-key-show-standard-help)
+ (let* ((prefix-keys (which-key--current-key-string))
+ (full-prefix (which-key--full-prefix prefix-keys current-prefix-arg t))
+ (prompt (concat (when (string-equal prefix-keys "")
+ (which-key--propertize
+ (concat " "
+ (which-key--pages-prefix-title
+ which-key--pages-obj))
+ 'face 'which-key-note-face))
+ full-prefix
+ (which-key--propertize
+ (substitute-command-keys
+ which-key-C-h-map-prompt)
+ 'face 'which-key-note-face)))
+ (key (let ((key (read-key prompt)))
+ (if (numberp key)
+ (string key)
+ (vector key))))
+ (cmd (lookup-key which-key-C-h-map key))
+ (which-key-inhibit t))
+ (if cmd (funcall cmd key) (which-key-turn-page 0)))))))
+
+;;; Update
+
+(defun which-key--any-match-p (regexps string)
+ "Non-nil if any of REGEXPS match STRING."
+ (catch 'match
+ (dolist (regexp regexps)
+ (when (string-match-p regexp string)
+ (throw 'match t)))))
+
+(defun which-key--try-2-side-windows
+ (bindings prefix-keys prefix-title loc1 loc2 &rest _ignore)
+ "Try to show BINDINGS (PAGE-N) in LOC1 first.
+
+Only if no bindings fit fallback to LOC2."
+ (let (pages1)
+ (let ((which-key-side-window-location loc1)
+ (which-key--multiple-locations t))
+ (setq pages1 (which-key--create-pages
+ bindings prefix-keys prefix-title)))
+ (if pages1
+ (progn
+ (setq which-key--pages-obj pages1)
+ (let ((which-key-side-window-location loc1)
+ (which-key--multiple-locations t))
+ (which-key--show-page))
+ loc1)
+ (let ((which-key-side-window-location loc2)
+ (which-key--multiple-locations t))
+ (setq which-key--pages-obj
+ (which-key--create-pages bindings prefix-keys prefix-title))
+ (which-key--show-page)
+ loc2))))
+
+(defun which-key--read-keymap ()
+ "Read keymap symbol from minibuffer."
+ (intern
+ (completing-read "Keymap: " obarray
+ (lambda (m)
+ (and (boundp m)
+ (keymapp (symbol-value m))
+ (not (equal (symbol-value m)
+ (make-sparse-keymap)))))
+ t
+ (let ((sym (symbol-at-point)))
+ (and (boundp sym)
+ (keymapp (symbol-value sym))
+ (symbol-name sym)))
+ 'which-key-keymap-history)))
+
+;;;###autoload
+(defun which-key-show-keymap (keymap &optional no-paging)
+ "Show the top-level bindings in KEYMAP using which-key.
+KEYMAP is selected interactively from all available keymaps.
+
+If NO-PAGING is non-nil, which-key will not intercept subsequent
+keypresses for the paging functionality."
+ (interactive (list (which-key--read-keymap)))
+ (which-key--show-keymap (symbol-name keymap)
+ (symbol-value keymap)
+ nil nil no-paging))
+
+;;;###autoload
+(defun which-key-show-full-keymap (keymap)
+ "Show all bindings in KEYMAP using which-key.
+KEYMAP is selected interactively from all available keymaps."
+ (interactive (list (which-key--read-keymap)))
+ (which-key--show-keymap (symbol-name keymap)
+ (symbol-value keymap)
+ nil t))
+
+;;;###autoload
+(defun which-key-show-minor-mode-keymap (&optional all)
+ "Show the top-level bindings in KEYMAP using which-key.
+KEYMAP is selected interactively by mode in
+`minor-mode-map-alist'."
+ (interactive)
+ (let ((mode-sym
+ (intern
+ (completing-read
+ "Minor Mode: "
+ (mapcar #'car
+ (cl-remove-if-not
+ (lambda (entry)
+ (and (symbol-value (car entry))
+ (not (equal (cdr entry) (make-sparse-keymap)))))
+ minor-mode-map-alist))
+ nil t nil 'which-key-keymap-history))))
+ (which-key--show-keymap (symbol-name mode-sym)
+ (cdr (assq mode-sym minor-mode-map-alist))
+ all)))
+;;;###autoload
+(defun which-key-show-full-minor-mode-keymap ()
+ "Show all bindings in KEYMAP using which-key.
+KEYMAP is selected interactively by mode in
+`minor-mode-map-alist'."
+ (interactive)
+ (which-key-show-minor-mode-keymap t))
+
+(defun which-key--show-keymap
+ (keymap-name keymap &optional prior-args all no-paging filter)
+ (when prior-args (push prior-args which-key--prior-show-keymap-args))
+ (let ((bindings (which-key--get-bindings nil keymap filter all)))
+ (if (= (length bindings) 0)
+ (message "which-key: No bindings found in %s" keymap-name)
+ (cond ((listp which-key-side-window-location)
+ (setq which-key--last-try-2-loc
+ (apply #'which-key--try-2-side-windows
+ bindings nil keymap-name
+ which-key-side-window-location)))
+ (t (setq which-key--pages-obj
+ (which-key--create-pages bindings nil keymap-name))
+ (which-key--show-page)))
+ (unless no-paging
+ (let* ((key (read-key))
+ (key-desc (key-description (list key)))
+ (next-def (lookup-key keymap (vector key))))
+ (cond ((and which-key-use-C-h-commands
+ (numberp key) (= key help-char))
+ (which-key-C-h-dispatch))
+ ((keymapp next-def)
+ (which-key--hide-popup-ignore-command)
+ (which-key--show-keymap
+ (concat keymap-name " " key-desc)
+ next-def
+ (cons keymap-name keymap)))
+ (t (which-key--hide-popup))))))))
+
+(defun which-key--evil-operator-filter (binding)
+ (let ((def (intern (cdr binding))))
+ (and (functionp def)
+ (not (evil-get-command-property def :suppress-operator)))))
+
+(defun which-key--show-evil-operator-keymap ()
+ (if which-key--inhibit-next-operator-popup
+ (setq which-key--inhibit-next-operator-popup nil)
+ (let ((keymap
+ (make-composed-keymap (list evil-operator-shortcut-map
+ evil-operator-state-map
+ evil-motion-state-map))))
+ (when (keymapp keymap)
+ (let ((formatted-keys
+ (which-key--get-bindings
+ nil keymap #'which-key--evil-operator-filter)))
+ (cond ((= (length formatted-keys) 0)
+ (message "which-key: Keymap empty"))
+ ((listp which-key-side-window-location)
+ (setq which-key--last-try-2-loc
+ (apply #'which-key--try-2-side-windows
+ formatted-keys nil "evil operator/motion keys"
+ which-key-side-window-location)))
+ (t (setq which-key--pages-obj
+ (which-key--create-pages
+ formatted-keys
+ nil "evil operator/motion keys"))
+ (which-key--show-page)))))
+ (let* ((key (read-key)))
+ (when (member key '(?f ?F ?t ?T ?`))
+ ;; these keys trigger commands that read the next char manually
+ (setq which-key--inhibit-next-operator-popup t))
+ (cond ((and which-key-use-C-h-commands (numberp key) (= key help-char))
+ (which-key-C-h-dispatch))
+ ((and (numberp key) (= key ?\C-\[))
+ (which-key--hide-popup)
+ (keyboard-quit))
+ (t
+ (which-key--hide-popup)
+ (setq unread-command-events (vector key))))))))
+
+(defun which-key--create-buffer-and-show
+ (&optional prefix-keys from-keymap filter prefix-title)
+ "Fill `which-key--buffer' with key descriptions and reformat.
+Finally, show the buffer."
+ (let ((start-time (current-time))
+ (formatted-keys (which-key--get-bindings
+ prefix-keys from-keymap filter))
+ (prefix-desc (key-description prefix-keys)))
+ (cond ((= (length formatted-keys) 0)
+ (message "%s- which-key: There are no keys to show" prefix-desc))
+ ((listp which-key-side-window-location)
+ (setq which-key--last-try-2-loc
+ (apply #'which-key--try-2-side-windows
+ formatted-keys prefix-keys prefix-title
+ which-key-side-window-location)))
+ (t (setq which-key--pages-obj
+ (which-key--create-pages
+ formatted-keys prefix-keys prefix-title))
+ (which-key--show-page)))
+ (which-key--debug-message
+ "On prefix \"%s\" which-key took %.0f ms." prefix-desc
+ (* 1000 (float-time (time-since start-time))))))
+
+(defun which-key--this-command-keys ()
+ "Version of `this-single-command-keys' corrected for key-chords and god-mode."
+ (let ((this-command-keys (this-single-command-keys)))
+ (when (and (vectorp this-command-keys)
+ (> (length this-command-keys) 0)
+ (eq (aref this-command-keys 0) 'key-chord)
+ (bound-and-true-p key-chord-mode))
+ (setq this-command-keys (this-single-command-raw-keys)))
+ (when (and which-key--god-mode-support-enabled
+ (bound-and-true-p god-local-mode)
+ (eq this-command 'god-mode-self-insert))
+ (setq this-command-keys (when which-key--god-mode-key-string
+ (kbd which-key--god-mode-key-string))))
+ this-command-keys))
+
+(defun which-key--update ()
+ "Function run by timer to possibly trigger
+`which-key--create-buffer-and-show'."
+ (let ((prefix-keys (which-key--this-command-keys))
+ delay-time)
+ (cond ((and (> (length prefix-keys) 0)
+ (or (keymapp (key-binding prefix-keys))
+ ;; Some keymaps are stored here like iso-transl-ctl-x-8-map
+ (keymapp (which-key--safe-lookup-key
+ key-translation-map prefix-keys))
+ ;; just in case someone uses one of these
+ (keymapp (which-key--safe-lookup-key
+ function-key-map prefix-keys)))
+ (not which-key-inhibit)
+ (or (null which-key-allow-regexps)
+ (which-key--any-match-p
+ which-key-allow-regexps (key-description prefix-keys)))
+ (or (null which-key-inhibit-regexps)
+ (not
+ (which-key--any-match-p
+ which-key-inhibit-regexps (key-description prefix-keys))))
+ ;; Do not display the popup if a command is currently being
+ ;; executed
+ (or (and which-key-allow-evil-operators
+ (bound-and-true-p evil-this-operator))
+ (and which-key--god-mode-support-enabled
+ (bound-and-true-p god-local-mode)
+ (eq this-command 'god-mode-self-insert))
+ (null this-command))
+ (let ((max-dim (which-key--popup-max-dimensions)))
+ (> (min (car-safe max-dim) (cdr-safe max-dim)) 0)))
+ (when (and (not (equal prefix-keys (which-key--current-prefix)))
+ (or (null which-key-delay-functions)
+ (null (setq delay-time
+ (run-hook-with-args-until-success
+ 'which-key-delay-functions
+ (key-description prefix-keys)
+ (length prefix-keys))))
+ (sit-for delay-time)))
+ (setq which-key--automatic-display t)
+ (which-key--create-buffer-and-show prefix-keys)
+ (when (and which-key-idle-secondary-delay
+ (not which-key--secondary-timer-active))
+ (which-key--start-timer which-key-idle-secondary-delay t))))
+ ((and which-key-show-transient-maps
+ ;; Assuming that if this is not true we're in
+ ;; `which-key-show-top-level', which would then be overwritten.
+ (> (length prefix-keys) 0)
+ (keymapp overriding-terminal-local-map)
+ ;; basic test for it being a hydra
+ (not (eq (lookup-key overriding-terminal-local-map "\C-u")
+ 'hydra--universal-argument)))
+ (which-key--create-buffer-and-show
+ nil overriding-terminal-local-map))
+ ((and which-key-show-operator-state-maps
+ (bound-and-true-p evil-state)
+ (eq evil-state 'operator)
+ (not (which-key--popup-showing-p)))
+ (which-key--show-evil-operator-keymap))
+ (which-key--automatic-display
+ (which-key--hide-popup)))))
+
+;;; Timers
+
+(defun which-key--start-timer (&optional delay secondary)
+ "Activate idle timer to trigger `which-key--update'."
+ (which-key--stop-timer)
+ (setq which-key--secondary-timer-active secondary)
+ (setq which-key--timer
+ (run-with-idle-timer (or delay which-key-idle-delay)
+ t #'which-key--update)))
+
+(defun which-key--stop-timer ()
+ "Deactivate idle timer for `which-key--update'."
+ (when which-key--timer (cancel-timer which-key--timer)))
+
+(defun which-key--start-paging-timer ()
+ "Activate timer to restart which-key after paging."
+ (when which-key--paging-timer (cancel-timer which-key--paging-timer))
+ (which-key--stop-timer)
+ (setq which-key--paging-timer
+ (run-with-idle-timer
+ 0.2 t (lambda ()
+ (when (or (not (member real-last-command
+ which-key--paging-functions))
+ (and (< 0 (length (this-single-command-keys)))
+ (not (equal (which-key--current-prefix)
+ (which-key--this-command-keys)))))
+ (cancel-timer which-key--paging-timer)
+ (if which-key-idle-secondary-delay
+ ;; we haven't executed a command yet so the secandary
+ ;; timer is more relevant here
+ (which-key--start-timer which-key-idle-secondary-delay t)
+ (which-key--start-timer)))))))
+
+(provide 'which-key)
+;;; which-key.el ends here
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-05 2:15 ` Justin Burkett
2024-02-05 3:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 12:32 ` Eli Zaretskii
` (2 subsequent siblings)
3 siblings, 1 reply; 86+ messages in thread
From: Justin Burkett @ 2024-02-05 2:15 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, monnier
[-- Attachment #1: Type: text/plain, Size: 391 bytes --]
I can take care of this tomorrow, but otherwise feel free to make the move
yourselves.
Justin
On Sun, Feb 4, 2024 at 5:04 PM Jeremy Bryant <jb@jeremybryant.net> wrote:
> Tags: patch
>
> This patch brings the latest version of which-key from GNU ELPA into
> Emacs core
>
> If suitable I will then work on the updates to user-facing aspects such as
> manual and NEWS.
>
>
[-- Attachment #2: Type: text/html, Size: 720 bytes --]
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-05 2:15 ` Justin Burkett
@ 2024-02-05 3:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 86+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-05 3:08 UTC (permalink / raw)
To: Justin Burkett; +Cc: jb, 68929
> I can take care of this tomorrow, but otherwise feel free to make the move
> yourselves.
BTW, rather than adding a file, another way to add it to `emacs.git` is
by `git merge --allow-unrelated-histories`.
If you wan to do that, you'll want to first create a new commit which
moves the files to their "final" destination, like:
git rm .gitignore .github Makefile LICENSE.md ...
git mv which-key.el lisp/which-key.el
git mv which-key-tests.el test/lisp/which-key-tests.el
[ not sure what you plan to do with the README.org and image files. ]
git commit -m 'Move files in preparation for merge into emacs.git'
and then you can `git merge` that new commit into Emacs, preserving
the history.
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 2:15 ` Justin Burkett
@ 2024-02-05 12:32 ` Eli Zaretskii
2024-02-06 2:51 ` Justin Burkett
2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-07 8:20 ` Philip Kaludercic
2024-04-14 21:56 ` bug#68929: Fwd: Re: bug#68929: which-key tests " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
3 siblings, 2 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-05 12:32 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, monnier, justin
> Date: Sun, 04 Feb 2024 22:02:50 +0000
> From: Jeremy Bryant via "Bug reports for GNU Emacs,
> the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>
> This patch brings the latest version of which-key from GNU ELPA into
> Emacs core
>
> If suitable I will then work on the updates to user-facing aspects such as
> manual and NEWS.
This "needs work"... Based on a very superficial reading of this huge
file:
> +;; which-key provides the minor mode which-key-mode for Emacs. The mode displays
^^
Two spaces between sentences in comments and doc strings, here and
elsewhere.
> +(defcustom which-key-idle-delay 1.0
> + "Delay (in seconds) for which-key buffer to popup.
> +This variable should be set before activating `which-key-mode'.
> +
> +A value of zero might lead to issues, so a non-zero value is
> +recommended
> +(see https://github.com/justbur/emacs-which-key/issues/134)."
> + :group 'which-key
> + :type 'float)
Please add a :version tag to all defcustom's and defface's.
> +(defcustom which-key-idle-secondary-delay nil
> + "Once the which-key buffer shows once for a key sequence reduce
> +the idle time to this amount (in seconds). This makes it possible
The first sentence of a doc string should be a single complete
sentence. In this case I suggest
Number of seconds to reduce idle-timer delay after showing which-key once.
> +(defcustom which-key-min-column-description-width 0
> + "Every column should at least have this width."
This needs details, otherwise it's mot very useful.
> +(defcustom which-key-unicode-correction 3
> + "Correction for wide unicode characters.
> +Since we measure width in terms of the number of characters,
> +Unicode characters that are wider than ASCII characters throw off
> +the calculation for available width in the which-key buffer. This
> +variable allows you to adjust for the wide unicode characters by
> +artificially reducing the available width in the buffer.
> +
> +The default of 3 means allow for the total extra width
> +contributed by any wide unicode characters to be up to one
> +additional ASCII character in the which-key buffer. Increase this
> +number if you are seeing characters get cutoff on the right side
> +of the which-key popup."
This seems to be a sub-optimal way of accounting for character widths.
We have better ways, e.g., char-width, string-pixel-width etc.
> +(defcustom which-key-dont-use-unicode nil
> + "If non-nil, don't use any unicode characters in default setup."
This should mention the settings affected by it.
Please go through all the doc strings and make sure they are
sufficiently self-explanatory.
Thanks.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-05 12:32 ` Eli Zaretskii
@ 2024-02-06 2:51 ` Justin Burkett
2024-02-07 21:53 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 86+ messages in thread
From: Justin Burkett @ 2024-02-06 2:51 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Jeremy Bryant, 68929, monnier
Thanks for the comments. I'll work on these.
On Mon, Feb 5, 2024 at 7:32 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > Date: Sun, 04 Feb 2024 22:02:50 +0000
> > From: Jeremy Bryant via "Bug reports for GNU Emacs,
> > the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >
> > This patch brings the latest version of which-key from GNU ELPA into
> > Emacs core
> >
> > If suitable I will then work on the updates to user-facing aspects such as
> > manual and NEWS.
>
> This "needs work"... Based on a very superficial reading of this huge
> file:
>
> > +;; which-key provides the minor mode which-key-mode for Emacs. The mode displays
> ^^
> Two spaces between sentences in comments and doc strings, here and
> elsewhere.
>
> > +(defcustom which-key-idle-delay 1.0
> > + "Delay (in seconds) for which-key buffer to popup.
> > +This variable should be set before activating `which-key-mode'.
> > +
> > +A value of zero might lead to issues, so a non-zero value is
> > +recommended
> > +(see https://github.com/justbur/emacs-which-key/issues/134)."
> > + :group 'which-key
> > + :type 'float)
>
> Please add a :version tag to all defcustom's and defface's.
>
>
> > +(defcustom which-key-idle-secondary-delay nil
> > + "Once the which-key buffer shows once for a key sequence reduce
> > +the idle time to this amount (in seconds). This makes it possible
>
> The first sentence of a doc string should be a single complete
> sentence. In this case I suggest
>
> Number of seconds to reduce idle-timer delay after showing which-key once.
>
> > +(defcustom which-key-min-column-description-width 0
> > + "Every column should at least have this width."
>
> This needs details, otherwise it's mot very useful.
>
> > +(defcustom which-key-unicode-correction 3
> > + "Correction for wide unicode characters.
> > +Since we measure width in terms of the number of characters,
> > +Unicode characters that are wider than ASCII characters throw off
> > +the calculation for available width in the which-key buffer. This
> > +variable allows you to adjust for the wide unicode characters by
> > +artificially reducing the available width in the buffer.
> > +
> > +The default of 3 means allow for the total extra width
> > +contributed by any wide unicode characters to be up to one
> > +additional ASCII character in the which-key buffer. Increase this
> > +number if you are seeing characters get cutoff on the right side
> > +of the which-key popup."
>
> This seems to be a sub-optimal way of accounting for character widths.
> We have better ways, e.g., char-width, string-pixel-width etc.
>
> > +(defcustom which-key-dont-use-unicode nil
> > + "If non-nil, don't use any unicode characters in default setup."
>
> This should mention the settings affected by it.
>
> Please go through all the doc strings and make sure they are
> sufficiently self-explanatory.
>
> Thanks.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 2:15 ` Justin Burkett
2024-02-05 12:32 ` Eli Zaretskii
@ 2024-02-07 8:20 ` Philip Kaludercic
2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-23 23:07 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 21:56 ` bug#68929: Fwd: Re: bug#68929: which-key tests " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
3 siblings, 2 replies; 86+ messages in thread
From: Philip Kaludercic @ 2024-02-07 8:20 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, monnier, justin
Jeremy Bryant <jb@jeremybryant.net> writes:
> Tags: patch
>
> This patch brings the latest version of which-key from GNU ELPA into
> Emacs core
>
> If suitable I will then work on the updates to user-facing aspects such as
> manual and NEWS.
>
>>From 1a3207344a18b6743772927b6f8f709b05246a51 Mon Sep 17 00:00:00 2001
> From: Jeremy Bryant <jb@jeremybryant.net>
> Date: Sun, 4 Feb 2024 21:56:16 +0000
> Subject: [PATCH] * lisp/which-key.el: Display available keybindings in popup
>
> Copy feature which-key from GNU ELPA
> ---
> lisp/which-key.el | 2753 +++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 2753 insertions(+)
> create mode 100644 lisp/which-key.el
>
> diff --git a/lisp/which-key.el b/lisp/which-key.el
> new file mode 100644
> index 00000000000..d68942cf8b1
> --- /dev/null
> +++ b/lisp/which-key.el
> @@ -0,0 +1,2753 @@
> +;;; which-key.el --- Display available keybindings in popup -*- lexical-binding: t; -*-
> +
> +;; Copyright (C) 2017-2021 Free Software Foundation, Inc.
> +
> +;; Author: Justin Burkett <justin@burkett.cc>
> +;; Maintainer: Justin Burkett <justin@burkett.cc>
> +;; URL: https://github.com/justbur/emacs-which-key
IIUC the plan is to maintain the package in emacs.git, right? Shouldn't
this line then be removed?
> +;; Version: 3.6.0
> +;; Keywords:
> +;; Package-Requires: ((emacs "24.4"))
> +
> +;; 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
> +;; the Free Software Foundation, either version 3 of the License, or
> +;; (at your option) any later version.
> +
> +;; This program is distributed in the hope that it will be useful,
> +;; but WITHOUT ANY WARRANTY; without even the implied warranty of
> +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +;; GNU General Public License for more details.
> +
> +;; You should have received a copy of the GNU General Public License
> +;; along with this program. If not, see <http://www.gnu.org/licenses/>.
> +
> +;;; Commentary:
> +
> +;; which-key provides the minor mode which-key-mode for Emacs. The mode displays
> +;; the key bindings following your currently entered incomplete command (a
> +;; prefix) in a popup. For example, after enabling the minor mode if you enter
> +;; C-x and wait for the default of 1 second the minibuffer will expand with all
> +;; of the available key bindings that follow C-x (or as many as space allows
> +;; given your settings). This includes prefixes like C-x 8 which are shown in a
> +;; different face. Screenshots of what the popup will look like along with
> +;; information about additional features can be found at
> +;; https://github.com/justbur/emacs-which-key.
> +;;
> +
> +;;; Code:
> +
> +(require 'cl-lib)
> +(require 'button)
> +(require 'regexp-opt)
> +
> +;; For compiler
> +(defvar evil-operator-shortcut-map)
> +(defvar evil-operator-state-map)
> +(defvar evil-motion-state-map)
> +(defvar golden-ratio-mode)
> +(declare-function evil-get-command-property "ext:evil-common.el")
> +
> +;;; Options
> +
> +(defgroup which-key nil
> + "Customization options for which-key-mode"
> + :group 'help
> + :prefix "which-key-")
> +
> +(defcustom which-key-idle-delay 1.0
> + "Delay (in seconds) for which-key buffer to popup.
> +This variable should be set before activating `which-key-mode'.
> +
> +A value of zero might lead to issues, so a non-zero value is
> +recommended
> +(see https://github.com/justbur/emacs-which-key/issues/134)."
> + :group 'which-key
By default :group falls back to the last defgroup, so you don't need to
specify them every time.
> + :type 'float)
> +
> +(defcustom which-key-idle-secondary-delay nil
> + "Once the which-key buffer shows once for a key sequence reduce
> +the idle time to this amount (in seconds). This makes it possible
> +to shorten the delay for subsequent popups in the same key
> +sequence. The default is for this value to be nil, which disables
> +this behavior."
> + :group 'which-key
> + :type '(choice float (const :tag "Disabled" nil)))
> +
> +(defcustom which-key-echo-keystrokes (if (and echo-keystrokes
> + (> (+ echo-keystrokes 0.01)
> + which-key-idle-delay))
> + (/ (float which-key-idle-delay) 4)
> + echo-keystrokes)
> + "Value to use for `echo-keystrokes'.
> +This only applies if `which-key-popup-type' is minibuffer or
> +`which-key-show-prefix' is echo. It needs to be less than
> +`which-key-idle-delay' or else the keystroke echo will erase the
> +which-key popup."
> + :group 'which-key
> + :type 'float)
> +
> +(defcustom which-key-max-description-length 27
> + "Truncate the description of keys to this length.
> +Either nil (no truncation), an integer (truncate after that many
> +characters), a float (use that fraction of the available width),
> +or a function, which takes one argument, the available width in
> +characters, and whose return value has one of the types mentioned
> +before. Truncation is done using `which-key-ellipsis'."
> + :group 'which-key
> + :type '(choice (const :tag "Disable truncation" nil)
> + (integer :tag "Width in characters")
> + (float :tag "Use fraction of available width")
> + function))
> +
> +(defcustom which-key-min-column-description-width 0
> + "Every column should at least have this width."
> + :group 'which-key
> + :type 'integer)
Perhasps natnum would be a more specific type here.
> +
> +(defcustom which-key-add-column-padding 0
> + "Additional padding (number of spaces) to add to the left of
> +each key column."
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-unicode-correction 3
> + "Correction for wide unicode characters.
> +Since we measure width in terms of the number of characters,
> +Unicode characters that are wider than ASCII characters throw off
> +the calculation for available width in the which-key buffer. This
> +variable allows you to adjust for the wide unicode characters by
> +artificially reducing the available width in the buffer.
> +
> +The default of 3 means allow for the total extra width
> +contributed by any wide unicode characters to be up to one
> +additional ASCII character in the which-key buffer. Increase this
> +number if you are seeing characters get cutoff on the right side
> +of the which-key popup."
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-dont-use-unicode nil
Could we set this to t? That would seem to be more consistent with the
regular appearance of Emacs OOTB.
> + "If non-nil, don't use any unicode characters in default setup."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-separator
> + (if which-key-dont-use-unicode " : " " → ")
> + "Separator to use between key and description. Default is \" →
> +\", unless `which-key-dont-use-unicode' is non nil, in which case
> +the default is \" : \"."
> + :group 'which-key
> + :type 'string)
> +
> +(defcustom which-key-ellipsis
> + (if which-key-dont-use-unicode ".." "…")
> + "Ellipsis to use when truncating.
> +Default is \"…\", unless `which-key-dont-use-unicode' is non nil,
> +in which case the default is \"..\". This can also be the empty
> +string to truncate without using any ellipsis."
> + :group 'which-key
> + :type 'string)
> +
> +(defcustom which-key-prefix-prefix "+"
> + "String to insert in front of prefix commands (i.e., commands
> +that represent a sub-map). Default is \"+\"."
> + :group 'which-key
> + :type 'string)
> +
> +(defcustom which-key-compute-remaps nil
> + "If non-nil, show remapped command if a command has been
> +remapped given the currently active keymaps."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-replacement-alist
> + (delq nil
> + `(((nil . "which-key-show-next-page-no-cycle") . (nil . "wk next pg"))
> + ,@(unless which-key-dont-use-unicode
> + '((("<left>") . ("←"))
> + (("<right>") . ("→"))))
> + (("<\\([[:alnum:]-]+\\)>") . ("\\1"))))
> + "Association list to determine how to manipulate descriptions
> +of key bindings in the which-key popup. Each element of the list
> +is a nested cons cell with the format
> +
> +\(MATCH CONS . REPLACEMENT\).
> +
> +The MATCH CONS determines when a replacement should occur and
> +REPLACEMENT determines how the replacement should occur. Each may
> +have the format \(KEY REGEXP . BINDING REGEXP\). For the
> +replacement to apply the key binding must match both the KEY
> +REGEXP and the BINDING REGEXP. A value of nil in either position
> +can be used to match every possibility. The replacement is
> +performed by using `replace-regexp-in-string' on the KEY REGEXP
> +from the MATCH CONS and REPLACEMENT when it is a cons cell, and
> +then similarly for the BINDING REGEXP. A nil value in the BINDING
> +REGEXP position cancels the replacement. For example, the entry
> +
> +\(\(nil . \"Prefix Command\"\) . \(nil . \"prefix\"\)\)
> +
> +matches any binding with the descriptions \"Prefix Command\" and
> +replaces the description with \"prefix\", ignoring the
> +corresponding key.
> +
> +REPLACEMENT may also be a function taking a cons cell
> +\(KEY . BINDING\) and producing a new corresponding cons cell.
> +
> +If REPLACEMENT is anything other than a cons cell \(and non nil\)
> +the key binding is ignored by which-key.
> +
> +Finally, you can multiple replacements to occur for a given key
> +binding by setting `which-key-allow-multiple-replacements' to a
> +non-nil value."
> + :group 'which-key
> + :type '(alist :key-type (cons (choice regexp (const nil))
> + (choice regexp (const nil)))
> + :value-type (cons (choice string (const nil))
> + (choice string (const nil)))))
> +
> +(defcustom which-key-allow-multiple-replacements nil
> + "Allow a key binding to match and be modified by multiple
> +elements in `which-key-replacement-alist' if non-nil. When nil,
> +only the first match is used to perform replacements from
> +`which-key-replacement-alist'."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-show-docstrings nil
> + "If non-nil, show each command's docstring next to the command
> +in the which-key buffer. This will only display the docstring up
> +to the first line break. If you set this variable to the symbol
> +docstring-only, then the command's name with be omitted. You
> +probably also want to adjust `which-key-max-description-length'
> +at the same time if you use this feature."
> + :group 'which-key
> + :type '(radio
> + (const :tag "Do not show docstrings" nil)
> + (const :tag "Add docstring to command names" t)
> + (const :tag "Replace command name with docstring" docstring-only)))
> +
> +(defcustom which-key-highlighted-command-list '()
> + "A list of strings and/or cons cells used to highlight certain
> +commands. If the element is a string, assume it is a regexp
> +pattern for matching command names and use
> +`which-key-highlighted-command-face' for any matching names. If
> +the element is a cons cell, it should take the form (regexp .
> +face to apply)."
> + :group 'which-key
> + :type '(repeat (choice string (cons regexp face))))
> +
> +(defcustom which-key-special-keys '()
> + "These keys will automatically be truncated to one character
> +and have `which-key-special-key-face' applied to them. This is
> +disabled by default. Try this to see the effect.
> +
> +\(setq which-key-special-keys \\='(\"SPC\" \"TAB\" \"RET\" \"ESC\" \"DEL\")\)"
> + :group 'which-key
> + :type '(repeat string))
Perhaps '(repeat key) here?
> +
> +(defcustom which-key-buffer-name " *which-key*"
> + "Name of which-key buffer."
> + :group 'which-key
> + :type 'string)
> +
> +(defcustom which-key-show-prefix 'echo
> + "Whether to and where to display the current prefix sequence
> +Possible choices are echo for echo area (the default), left, top
> +and nil. Nil turns the feature off."
> + :group 'which-key
> + :type '(radio (const :tag "Left of the keys" left)
> + (const :tag "In the first line" top)
> + (const :tag "In the last line" bottom)
> + (const :tag "In the echo area" echo)
> + (const :tag "In the mode-line" mode-line)
> + (const :tag "Hide" nil)))
> +
> +(defcustom which-key-popup-type 'side-window
> + "Supported types are minibuffer, side-window, frame, and custom"
> + :group 'which-key
> + :type '(radio (const :tag "Show in minibuffer" minibuffer)
> + (const :tag "Show in side window" side-window)
> + (const :tag "Show in popup frame" frame)
> + (const :tag "Use your custom display functions" custom)))
> +
> +(defcustom which-key-min-display-lines 1
> + "Minimum number of horizontal lines to display in the which-key buffer"
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-max-display-columns nil
> + "Maximum number of columns to display in the which-key buffer
> +nil means don't impose a maximum."
> + :group 'which-key
> + :type '(choice integer (const :tag "Unbounded" nil)))
> +
> +(defcustom which-key-side-window-location 'bottom
> + "Location of which-key popup when `which-key-popup-type' is side-window.
> +Should be one of top, bottom, left or right. You can also specify
> +a list of two locations, like (right bottom). In this case, the
> +first location is tried. If there is not enough room, the second
> +location is tried."
> + :group 'which-key
> + :type '(radio (const right)
> + (const bottom)
> + (const left)
> + (const top)
> + (const (right bottom))
> + (const (bottom right))))
> +
> +(defcustom which-key-side-window-slot 0
> + "The `slot' to use for `display-buffer-in-side-window' when
> +`which-key-popup-type' is `side-window'. Quoting from the
> +docstring of `display-buffer-in-side-window',
> +
> +`slot' if non-nil, specifies the window slot where to display
> +BUFFER. A value of zero or nil means use the middle slot on the
> +specified side. A negative value means use a slot
> +preceding (that is, above or on the left of) the middle slot. A
> +positive value means use a slot following (that is, below or on
> +the right of) the middle slot. The default is zero."
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-side-window-max-width 0.333
> + "Maximum width of which-key popup when type is side-window
> +This variable can also be a number between 0 and 1. In that case,
> +it denotes a percentage out of the frame's width."
> + :group 'which-key
> + :type 'float)
> +
> +(defcustom which-key-side-window-max-height 0.25
> + "Maximum height of which-key popup when type is side-window
> +This variable can also be a number between 0 and 1. In that case, it denotes
> +a percentage out of the frame's height."
> + :group 'which-key
> + :type 'float)
> +
> +(defcustom which-key-frame-max-width 60
> + "Maximum width of which-key popup when type is frame."
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-frame-max-height 20
> + "Maximum height of which-key popup when type is frame."
> + :group 'which-key
> + :type 'integer)
> +
> +(defcustom which-key-allow-imprecise-window-fit (not (display-graphic-p))
> + "If non-nil allow which-key to use a less intensive method of
> +fitting the popup window to the buffer. If you are noticing lag
> +when the which-key popup displays turning this on may help.
> +
> +See https://github.com/justbur/emacs-which-key/issues/130
> +and https://github.com/justbur/emacs-which-key/issues/225."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-show-remaining-keys nil
> + "Show remaining keys in last slot, when keys are hidden."
> + :group 'which-key
> + :type '(radio (const :tag "Yes" t)
> + (const :tag "No" nil)))
> +
> +(defcustom which-key-sort-order 'which-key-key-order
> + "If nil, do not resort the output from
> +`describe-buffer-bindings' which groups by mode. Ordering options
> +are
> +
> +1. `which-key-key-order': by key (default)
> +2. `which-key-key-order-alpha': by key using alphabetical order
> +3. `which-key-description-order': by description
> +4. `which-key-prefix-then-key-order': prefix (no prefix first) then key
> +5. `which-key-local-then-key-order': local binding then key
> +
> +See the README and the docstrings for those functions for more
> +information."
> + :group 'which-key
> + :type '(choice (function-item which-key-key-order)
> + (function-item which-key-key-order-alpha)
> + (function-item which-key-description-order)
> + (function-item which-key-prefix-then-key-order)
> + (function-item which-key-local-then-key-order)))
> +
> +(defcustom which-key-sort-uppercase-first t
> + "If non-nil, uppercase comes before lowercase in sorting
> +function chosen in `which-key-sort-order'. Otherwise, the order
> +is reversed."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-paging-prefixes '()
> + "Enable paging for these prefixes."
> + :group 'which-key
> + :type '(repeat string))
> +
> +(defcustom which-key-paging-key "<f5>"
> + "Key to use for changing pages. Bound after each of the
> +prefixes in `which-key-paging-prefixes'"
> + :group 'which-key
> + :type 'string)
Can you set this to key and replace the default value with (kbd "<f5>")?
Also, do we really want to use f5 for this? Also, also why is this
configured in a user option, not part of a map?
> +
> +;; (defcustom which-key-undo-key nil
> +;; "Key (string) to use for undoing keypresses. Bound recursively
> +;; in each of the maps in `which-key-undo-keymaps'."
> +;; :group 'which-key
> +;; :type 'string)
> +
> +;; (defcustom which-key-undo-keymaps '()
> +;; "Keymaps in which to bind `which-key-undo-key'"
> +;; :group 'which-key
> +;; :type '(repeat symbol))
Comments are not for code, please remove these.
> +(defcustom which-key-use-C-h-commands t
> + "Use C-h (or whatever `help-char' is set to) for paging if
> +non-nil. Normally C-h after a prefix calls
Rephrase this to avoid the line break. I think that checkdoc should
warn you about issues like these.
> +`describe-prefix-bindings'. This changes that command to a
> +which-key paging command when which-key-mode is active."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-show-early-on-C-h nil
> + "Show the which-key buffer before if C-h (or whatever
> +`help-char' is set to) is pressed in the middle of a prefix
> +before the which-key buffer would normally be triggered through
> +the idle delay. If combined with the following settings,
> +which-key will effectively only show when triggered \"manually\"
> +using C-h.
> +
> +\(setq `which-key-idle-delay' 10000)
> +\(setq `which-key-idle-secondary-delay' 0.05)
> +
> +Note that `which-key-idle-delay' should be set before turning on
> +`which-key-mode'. "
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-is-verbose nil
> + "Whether to warn about potential mistakes in configuration."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-preserve-window-configuration nil
> + "If non-nil, save window configuration before which-key buffer is shown
> +and restore it after which-key buffer is hidden. It prevents which-key from
> +changing window position of visible buffers.
> +Only takken into account when popup type is side-window."
> + :group
> + 'which-key
> + :type 'boolean)
> +
> +(defvar which-key-C-h-map-prompt
> + (concat " \\<which-key-C-h-map>"
> + " \\[which-key-show-next-page-cycle]"
> + which-key-separator "next-page,"
> + " \\[which-key-show-previous-page-cycle]"
> + which-key-separator "previous-page,"
> + " \\[which-key-undo-key]"
> + which-key-separator "undo-key,"
> + " \\[which-key-toggle-docstrings]"
> + which-key-separator "toggle-docstrings,"
> + " \\[which-key-show-standard-help]"
> + which-key-separator "help,"
> + " \\[which-key-abort]"
> + which-key-separator "abort"
> + " 1..9"
> + which-key-separator "digit-arg")
> + "Prompt to display when invoking `which-key-C-h-map'. This string
> +is fed into `substitute-command-keys'")
> +
> +(defvar which-key-C-h-map
> + (let ((map (make-sparse-keymap)))
> + (dolist (bind `(("\C-a" . which-key-abort)
You should be able to use defvar-keymap here. That might be closer to
what you are looking for with the dolist here.
> + ("a" . which-key-abort)
> + ("\C-d" . which-key-toggle-docstrings)
> + ("d" . which-key-toggle-docstrings)
> + (,(vector help-char) . which-key-show-standard-help)
> + ("h" . which-key-show-standard-help)
> + ("\C-n" . which-key-show-next-page-cycle)
> + ("n" . which-key-show-next-page-cycle)
> + ("\C-p" . which-key-show-previous-page-cycle)
> + ("p" . which-key-show-previous-page-cycle)
> + ("\C-u" . which-key-undo-key)
> + ("u" . which-key-undo-key)
> + ("1" . which-key-digit-argument)
> + ("2" . which-key-digit-argument)
> + ("3" . which-key-digit-argument)
> + ("4" . which-key-digit-argument)
> + ("5" . which-key-digit-argument)
> + ("6" . which-key-digit-argument)
> + ("7" . which-key-digit-argument)
> + ("8" . which-key-digit-argument)
> + ("9" . which-key-digit-argument)))
> + (define-key map (car bind) (cdr bind)))
> + map)
> + "Keymap for C-h commands.")
> +
> +(defvar which-key--paging-functions '(which-key-C-h-dispatch
In your place, I'd not use a quoted list here but (list ...) where each
element is sharp-quoted so that the byte-compiler can check if the
functions exist.
> + which-key-manual-update
> + which-key-turn-page
> + which-key-show-next-page-cycle
> + which-key-show-next-page-no-cycle
> + which-key-show-previous-page-cycle
> + which-key-show-previous-page-no-cycle
> + which-key-undo-key
> + which-key-undo))
> +
> +(defvar which-key-persistent-popup nil
> + "Whether or not to disable `which-key--hide-popup'.")
> +
> +(defcustom which-key-hide-alt-key-translations t
> + "Hide key translations using Alt key if non nil.
> +These translations are not relevant most of the times since a lot
> +of terminals issue META modifier for the Alt key.
> +
> +See http://www.gnu.org/software/emacs/manual/html_node/emacs/Modifier-Keys.html"
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-delay-functions nil
> + "A list of functions that may decide whether to delay the
> +which-key popup based on the current incomplete key
> +sequence. Each function in the list is run with two arguments,
> +the current key sequence as produced by `key-description' and the
> +length of the key sequence. If the popup should be delayed based
> +on that key sequence, the function should return the delay time
> +in seconds. Returning nil means no delay. The first function in
> +this list to return a value is the value that is used.
> +
> +The delay time is effectively added to the normal
> +`which-key-idle-delay'."
> + :group 'which-key
> + :type '(repeat function))
> +
> +(defcustom which-key-allow-regexps nil
> + "A list of regexp strings to use to filter key sequences.
> +When non-nil, for a key sequence to trigger the which-key popup
> +it must match one of the regexps in this list. The format of the
> +key sequences is what is produced by `key-description'."
> + :group 'which-key
> + :type '(repeat regexp))
> +
> +(defcustom which-key-inhibit-regexps nil
> + "Similar to `which-key-allow-regexps', a list of regexp strings
> +to use to filter key sequences. When non-nil, for a key sequence
> +to trigger the which-key popup it cannot match one of the regexps
> +in this list. The format of the key sequences is what is produced
> +by `key-description'."
> + :group 'which-key
> + :type '(repeat regexp))
> +
> +(defcustom which-key-show-transient-maps nil
> + "Show keymaps created by `set-transient-map' when applicable.
> +
> +More specifically, detect when `overriding-terminal-local-map' is
> +set (this is the keymap used by `set-transient-map') and display
> +it."
> + :group 'which-key
> + :type 'boolean)
> +
> +(make-obsolete-variable
> + 'which-key-enable-extended-define-key
> + "which-key-enable-extended-define-key is obsolete and has no effect."
> + "2021-06-21")
> +
> +;; Hooks
> +(defcustom which-key-init-buffer-hook '()
> + "Hook run when which-key buffer is initialized."
> + :group 'which-key
> + :type 'hook)
> +
> +;;;; Faces
> +
> +(defgroup which-key-faces nil
> + "Faces for which-key-mode"
> + :group 'which-key
> + :prefix "which-key-")
> +
> +(defface which-key-key-face
> + '((t . (:inherit font-lock-constant-face)))
Shouldn't this inherit from `help-key-binding'?
> + "Face for which-key keys"
> + :group 'which-key-faces)
> +
> +(defface which-key-separator-face
> + '((t . (:inherit font-lock-comment-face)))
Why comment face? What is the semantic intention here? I guess the
same question applies below as well, these mappings seem arbitrary.
> + "Face for the separator (default separator is an arrow)"
> + :group 'which-key-faces)
> +
> +(defface which-key-note-face
> + '((t . (:inherit which-key-separator-face)))
> + "Face for notes or hints occasionally provided"
> + :group 'which-key-faces)
> +
> +(defface which-key-command-description-face
> + '((t . (:inherit font-lock-function-name-face)))
> + "Face for the key description when it is a command"
> + :group 'which-key-faces)
> +
> +(defface which-key-local-map-description-face
> + '((t . (:inherit which-key-command-description-face)))
> + "Face for the key description when it is found in `current-local-map'"
> + :group 'which-key-faces)
> +
> +(defface which-key-highlighted-command-face
> + '((t . (:inherit which-key-command-description-face :underline t)))
> + "Default face for the command description when it is a command
> +and it matches a string in `which-key-highlighted-command-list'."
> + :group 'which-key-faces)
> +
> +(defface which-key-group-description-face
> + '((t . (:inherit font-lock-keyword-face)))
> + "Face for the key description when it is a group or prefix"
> + :group 'which-key-faces)
> +
> +(defface which-key-special-key-face
> + '((t . (:inherit which-key-key-face :inverse-video t :weight bold)))
> + "Face for special keys (SPC, TAB, RET)"
> + :group 'which-key-faces)
> +
> +(defface which-key-docstring-face
> + '((t . (:inherit which-key-note-face)))
> + "Face for docstrings"
> + :group 'which-key-faces)
> +
> +;;;; Custom popup
> +
> +(defcustom which-key-custom-popup-max-dimensions-function nil
> + "Variable to hold a custom max-dimensions function.
> +Will be passed the width of the active window and is expected to
> +return the maximum height in lines and width in characters of the
> +which-key popup in the form a cons cell (height . width)."
> + :group 'which-key
> + :type '(choice function (const nil)))
> +
> +(defcustom which-key-custom-hide-popup-function nil
> + "Variable to hold a custom hide-popup function.
> +It takes no arguments and the return value is ignored."
> + :group 'which-key
> + :type '(choice function (const nil)))
> +
> +(defcustom which-key-custom-show-popup-function nil
> + "Variable to hold a custom show-popup function.
> +Will be passed the required dimensions in the form (height .
> +width) in lines and characters respectively. The return value is
> +ignored."
> + :group 'which-key
> + :type '(choice function (const nil)))
> +
> +(defcustom which-key-lighter " WK"
> + "Minor mode lighter to use in the mode-line."
> + :group 'which-key
> + :type 'string)
> +
> +(defvar which-key-inhibit nil
> + "Prevent which-key from popping up momentarily by setting this
> +to a non-nil value for the execution of a command. Like this
> +
> +\(let \(\(which-key-inhibit t\)\)
> +...\)")
> +
> +(defvar which-key-keymap-history nil
> + "History of keymap selections in functions like
> +`which-key-show-keymap'.")
> +
> +;;; Internal Vars
> +
> +(defvar which-key--buffer nil
> + "Internal: Holds reference to which-key buffer.")
> +(defvar which-key--timer nil
> + "Internal: Holds reference to open window timer.")
> +(defvar which-key--secondary-timer-active nil
> + "Internal: Non-nil if the secondary timer is active.")
> +(defvar which-key--paging-timer nil
> + "Internal: Holds reference to timer for paging.")
> +(defvar which-key--frame nil
> + "Internal: Holds reference to which-key frame.
> +Used when `which-key-popup-type' is frame.")
> +(defvar which-key--echo-keystrokes-backup nil
> + "Internal: Backup the initial value of `echo-keystrokes'.")
> +(defvar which-key--prefix-help-cmd-backup nil
> + "Internal: Backup the value of `prefix-help-command'.")
> +(defvar which-key--last-try-2-loc nil
> + "Internal: Last location of side-window when two locations
> +used.")
> +(defvar which-key--automatic-display nil
> + "Internal: Non-nil if popup was triggered with automatic
> +update.")
> +(defvar which-key--debug-buffer-name nil
> + "If non-nil, use this buffer for debug messages.")
> +(defvar which-key--multiple-locations nil)
> +(defvar which-key--inhibit-next-operator-popup nil)
> +(defvar which-key--prior-show-keymap-args nil)
> +(defvar which-key--previous-frame-size nil)
> +(defvar which-key--prefix-title-alist nil)
> +(defvar which-key--evil-keys-regexp (eval-when-compile
> + (regexp-opt '("-state"))))
> +(defvar which-key--ignore-non-evil-keys-regexp
> + (eval-when-compile
> + (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
> + "select-window" "switch-frame" "which-key"))))
> +(defvar which-key--ignore-keys-regexp
> + (eval-when-compile
> + (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
> + "select-window" "switch-frame" "-state"
> + "which-key"))))
regexp-opt is marked as pure, you don't need the eval-when-compile here.
> +
> +(defvar which-key--pages-obj nil)
> +(cl-defstruct which-key--pages
> + pages
> + height
> + widths
> + keys/page
> + page-nums
> + num-pages
> + total-keys
> + prefix
> + prefix-title)
> +
> +(defvar which-key--saved-window-configuration nil)
> +
> +(defun which-key--rotate (list n)
> + (let* ((len (length list))
> + (n (if (< n 0) (+ len n) n))
> + (n (mod n len)))
> + (append (last list (- len n)) (butlast list (- len n)))))
> +
> +(defun which-key--pages-set-current-page (pages-obj n)
> + (setf (which-key--pages-pages pages-obj)
> + (which-key--rotate (which-key--pages-pages pages-obj) n))
> + (setf (which-key--pages-widths pages-obj)
> + (which-key--rotate (which-key--pages-widths pages-obj) n))
> + (setf (which-key--pages-keys/page pages-obj)
> + (which-key--rotate (which-key--pages-keys/page pages-obj) n))
> + (setf (which-key--pages-page-nums pages-obj)
> + (which-key--rotate (which-key--pages-page-nums pages-obj) n))
> + pages-obj)
> +
> +(defsubst which-key--on-first-page ()
> + (= (which-key--pages-page-nums which-key--pages-obj) 1))
> +
> +(defsubst which-key--on-last-page ()
> + (= (which-key--pages-page-nums which-key--pages-obj)
> + (which-key--pages-num-pages which-key--pages-obj)))
> +
> +(defsubst which-key--current-prefix ()
> + (and which-key--pages-obj
> + (which-key--pages-prefix which-key--pages-obj)))
> +
> +(defmacro which-key--debug-message (&rest msg)
> + `(when which-key--debug-buffer-name
> + (let ((buf (get-buffer-create which-key--debug-buffer-name))
> + (fmt-msg (format ,@msg)))
> + (with-current-buffer buf
> + (goto-char (point-max))
> + (insert "\n" fmt-msg "\n")))))
> +
> +(defsubst which-key--safe-lookup-key (keymap key)
> + "Version of `lookup-key' that allows KEYMAP to be nil.
> +Also convert numeric results of `lookup-key' to nil. KEY is not
> +checked."
> + (when (keymapp keymap)
> + (let ((result (lookup-key keymap key)))
> + (when (and result (not (numberp result)))
> + result))))
> +
> +(defsubst which-key--safe-lookup-key-description (keymap key)
> + "Version of `lookup-key' that allows KEYMAP to be nil.
> +Also convert numeric results of `lookup-key' to nil. KEY
> +should be formatted as an input for `kbd'."
> + (let ((key (ignore-errors (kbd key))))
???
> + (when (and key (keymapp keymap))
> + (let ((result (lookup-key keymap key)))
> + (when (and result (not (numberp result)))
> + result)))))
> +
> +;;; Third-party library support
Should this be kept? Or can the other libraries take over this code?
> +;;;; Evil
> +
> +(defvar evil-state nil)
> +
> +(defcustom which-key-allow-evil-operators (boundp 'evil-this-operator)
> + "Allow popup to show for evil operators.
> +The popup is normally inhibited in the middle of commands, but
> +setting this to non-nil will override this behavior for evil
> +operators."
> + :group 'which-key
> + :type 'boolean)
> +
> +(defcustom which-key-show-operator-state-maps nil
> + "Experimental: Try to show the right keys following an evil
> +command that reads a motion, such as \"y\", \"d\" and \"c\" from
> +normal state. This is experimental, because there might be some
> +valid keys missing and it might be showing some invalid keys."
> + :group 'which-key
> + :type 'boolean)
> +
> +;;;; God-mode
> +
> +(defvar which-key--god-mode-support-enabled nil
> + "Support god-mode if non-nil. This is experimental,
> +so you need to explicitly opt-in for now. Please report any
> +problems at github.")
> +
> +(defvar which-key--god-mode-key-string nil
> + "Holds key string to use for god-mode support.")
> +
> +(defun which-key--god-mode-lookup-command-advice (orig-fun arg1 &rest args)
> + (setq which-key--god-mode-key-string arg1)
> + (unwind-protect
> + (apply orig-fun arg1 args)
> + (when (bound-and-true-p which-key-mode)
> + (which-key--hide-popup))))
> +
> +(defun which-key-enable-god-mode-support (&optional disable)
> + "Enable support for god-mode if non-nil.
> +This is experimental, so you need to explicitly opt-in for
> +now. Please report any problems at github. If DISABLE is non-nil
> +disable support."
> + (interactive "P")
> + (setq which-key--god-mode-support-enabled (null disable))
> + (if disable
> + (advice-remove 'god-mode-lookup-command
> + #'which-key--god-mode-lookup-command-advice)
> + (advice-add 'god-mode-lookup-command :around
> + #'which-key--god-mode-lookup-command-advice)))
> +
> +;;; Mode
> +
> +;;;###autoload
> +(define-minor-mode which-key-mode
> + "Toggle which-key-mode."
> + :global t
> + :group 'which-key
> + :lighter which-key-lighter
> + :keymap (let ((map (make-sparse-keymap)))
> + (mapc
> + (lambda (prefix)
> + (define-key map
> + (kbd (concat prefix " " which-key-paging-key))
> + #'which-key-C-h-dispatch))
> + which-key-paging-prefixes)
> + map)
> + (if which-key-mode
> + (progn
> + (setq which-key--echo-keystrokes-backup echo-keystrokes)
> + (when (or (eq which-key-show-prefix 'echo)
> + (eq which-key-popup-type 'minibuffer))
> + (which-key--setup-echo-keystrokes))
> + (unless (member prefix-help-command which-key--paging-functions)
> + (setq which-key--prefix-help-cmd-backup prefix-help-command))
> + (when (or which-key-use-C-h-commands
> + which-key-show-early-on-C-h)
> + (setq prefix-help-command #'which-key-C-h-dispatch))
> + (when which-key-show-remaining-keys
> + (add-hook 'pre-command-hook #'which-key--lighter-restore))
> + (add-hook 'pre-command-hook #'which-key--hide-popup)
> + (add-hook 'window-size-change-functions
> + #'which-key--hide-popup-on-frame-size-change)
> + (which-key--start-timer))
> + (setq echo-keystrokes which-key--echo-keystrokes-backup)
> + (when which-key--prefix-help-cmd-backup
> + (setq prefix-help-command which-key--prefix-help-cmd-backup))
> + (when which-key-show-remaining-keys
> + (remove-hook 'pre-command-hook #'which-key--lighter-restore))
> + (remove-hook 'pre-command-hook #'which-key--hide-popup)
> + (remove-hook 'window-size-change-functions
> + #'which-key--hide-popup-on-frame-size-change)
> + (which-key--stop-timer)))
> +
> +(defun which-key--init-buffer ()
> + "Initialize which-key buffer"
> + (unless (buffer-live-p which-key--buffer)
> + (setq which-key--buffer (get-buffer-create which-key-buffer-name))
> + (with-current-buffer which-key--buffer
> + ;; suppress confusing minibuffer message
> + (let (message-log-max)
> + (toggle-truncate-lines 1)
> + (message ""))
> + (setq-local cursor-type nil)
> + (setq-local cursor-in-non-selected-windows nil)
> + (setq-local mode-line-format nil)
> + (setq-local header-line-format nil)
> + (setq-local word-wrap nil)
> + (setq-local show-trailing-whitespace nil)
> + (run-hooks 'which-key-init-buffer-hook))))
> +
> +(defun which-key--setup-echo-keystrokes ()
> + "Reduce `echo-keystrokes' if necessary (it will interfere if
> +it's set too high)."
> + (when (and echo-keystrokes
> + (> (abs (- echo-keystrokes which-key-echo-keystrokes)) 0.000001))
> + (if (> which-key-idle-delay which-key-echo-keystrokes)
> + (setq echo-keystrokes which-key-echo-keystrokes)
> + (setq which-key-echo-keystrokes (/ (float which-key-idle-delay) 4)
> + echo-keystrokes which-key-echo-keystrokes))))
> +
> +(defun which-key-remove-default-unicode-chars ()
> + "Use of `which-key-dont-use-unicode' is preferred to this
> +function, but it's included here in case someone cannot set that
> +variable early enough in their configuration, if they are using a
> +starter kit for example."
> + (when (string-equal which-key-separator " → ")
> + (setq which-key-separator " : ")))
> +
> +;;; Default configuration functions for use by users.
> +
> +;;;###autoload
> +(defun which-key-setup-side-window-right ()
> + "Apply suggested settings for side-window that opens on right."
> + (interactive)
> + (setq which-key-popup-type 'side-window
> + which-key-side-window-location 'right
> + which-key-show-prefix 'top))
> +
> +;;;###autoload
> +(defun which-key-setup-side-window-right-bottom ()
> + "Apply suggested settings for side-window that opens on right
> +if there is space and the bottom otherwise."
> + (interactive)
> + (setq which-key-popup-type 'side-window
> + which-key-side-window-location '(right bottom)
> + which-key-show-prefix 'top))
> +
> +;;;###autoload
> +(defun which-key-setup-side-window-bottom ()
> + "Apply suggested settings for side-window that opens on bottom."
> + (interactive)
> + (which-key--setup-echo-keystrokes)
> + (setq which-key-popup-type 'side-window
> + which-key-side-window-location 'bottom
> + which-key-show-prefix 'echo))
> +
> +;;;###autoload
> +(defun which-key-setup-minibuffer ()
> + "Apply suggested settings for minibuffer.
> +Do not use this setup if you use the paging commands. Instead use
> +`which-key-setup-side-window-bottom', which is nearly identical
> +but more functional."
> + (interactive)
> + (which-key--setup-echo-keystrokes)
> + (setq which-key-popup-type 'minibuffer
> + which-key-show-prefix 'left))
> +
> +;;; Helper functions to modify replacement lists.
> +
> +;;;###autoload
> +(defun which-key-add-keymap-based-replacements (keymap key replacement &rest more)
> + "Replace the description of KEY using REPLACEMENT in KEYMAP.
> +KEY should take a format suitable for use in `kbd'. REPLACEMENT
> +should be a cons cell of the form \(STRING . COMMAND\) for each
> +REPLACEMENT, where STRING is the replacement string and COMMAND
> +is a symbol corresponding to the intended command to be
> +replaced. COMMAND can be nil if the binding corresponds to a key
> +prefix. An example is
> +
> +\(which-key-add-keymap-based-replacements global-map
> + \"C-x w\" \\='\(\"Save as\" . write-file\)\).
> +
> +For backwards compatibility, REPLACEMENT can also be a string,
> +but the above format is preferred, and the option to use a string
> +for REPLACEMENT will eventually be removed."
> + (while key
> + (let ((def
> + (cond
> + ((consp replacement) replacement)
> + ((stringp replacement)
> + (cons replacement
> + (or (which-key--safe-lookup-key-description keymap key)
> + (make-sparse-keymap))))
> + (t
> + (user-error "replacement is neither a cons cell or a string")))))
> + (define-key keymap (kbd key) def))
> + (setq key (pop more)
> + replacement (pop more))))
> +(put 'which-key-add-keymap-based-replacements 'lisp-indent-function 'defun)
You can also set this using a declare form at the beginning of the above
defun's body.
> +
> +;;;###autoload
> +(defun which-key-add-key-based-replacements
> + (key-sequence replacement &rest more)
> + "Replace the description of KEY-SEQUENCE with REPLACEMENT.
> +KEY-SEQUENCE is a string suitable for use in `kbd'. REPLACEMENT
> +may either be a string, as in
> +
> +\(which-key-add-key-based-replacements \"C-x 1\" \"maximize\"\)
> +
> +a cons of two strings as in
> +
> +\(which-key-add-key-based-replacements \"C-x 8\"
> + \\='(\"unicode\" . \"Unicode keys\")\)
> +
> +or a function that takes a \(KEY . BINDING\) cons and returns a
> +replacement.
> +
> +In the second case, the second string is used to provide a longer
> +name for the keys under a prefix.
> +
> +MORE allows you to specifcy additional KEY REPLACEMENT pairs. All
> +replacements are added to `which-key-replacement-alist'."
> + ;; TODO: Make interactive
> + (while key-sequence
> + ;; normalize key sequences before adding
> + (let ((key-seq (key-description (kbd key-sequence)))
> + (replace (or (and (functionp replacement) replacement)
> + (car-safe replacement)
> + replacement)))
> + (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
> + (if (functionp replace) replace (cons nil replace)))
> + which-key-replacement-alist)
> + (when (and (not (functionp replacement)) (consp replacement))
> + (push (cons key-seq (cdr-safe replacement))
> + which-key--prefix-title-alist)))
> + (setq key-sequence (pop more) replacement (pop more))))
> +(put 'which-key-add-key-based-replacements 'lisp-indent-function 'defun)
> +
> +;;;###autoload
> +(defun which-key-add-major-mode-key-based-replacements
> + (mode key-sequence replacement &rest more)
> + "Functions like `which-key-add-key-based-replacements'.
> +The difference is that MODE specifies the `major-mode' that must
> +be active for KEY-SEQUENCE and REPLACEMENT (MORE contains
> +addition KEY-SEQUENCE REPLACEMENT pairs) to apply."
> + ;; TODO: Make interactive
> + (when (not (symbolp mode))
> + (error "MODE should be a symbol corresponding to a value of major-mode"))
> + (let ((mode-alist
> + (or (cdr-safe (assq mode which-key-replacement-alist)) (list)))
> + (title-mode-alist
> + (or (cdr-safe (assq mode which-key--prefix-title-alist)) (list))))
> + (while key-sequence
> + ;; normalize key sequences before adding
> + (let ((key-seq (key-description (kbd key-sequence)))
> + (replace (or (and (functionp replacement) replacement)
> + (car-safe replacement)
> + replacement)))
> + (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
> + (if (functionp replace) replace (cons nil replace)))
> + mode-alist)
> + (when (and (not (functionp replacement)) (consp replacement))
> + (push (cons key-seq (cdr-safe replacement))
> + title-mode-alist)))
> + (setq key-sequence (pop more) replacement (pop more)))
> + (if (assq mode which-key-replacement-alist)
> + (setcdr (assq mode which-key-replacement-alist) mode-alist)
> + (push (cons mode mode-alist) which-key-replacement-alist))
> + (if (assq mode which-key--prefix-title-alist)
> + (setcdr (assq mode which-key--prefix-title-alist) title-mode-alist)
> + (push (cons mode title-mode-alist) which-key--prefix-title-alist))))
> +(put 'which-key-add-major-mode-key-based-replacements
> + 'lisp-indent-function 'defun)
> +
> +(defun which-key-define-key-recursively (map key def &optional at-root)
> + "Recursively bind KEY in MAP to DEF on every level of MAP except the first.
> +If AT-ROOT is non-nil the binding is also placed at the root of MAP."
> + (when at-root (define-key map key def))
> + (map-keymap
> + (lambda (_ev df)
> + (when (keymapp df)
> + (which-key-define-key-recursively df key def t)))
> + map))
> +
> +;;; Functions for computing window sizes
> +
> +(defun which-key--text-width-to-total (text-width)
> + "Convert window text-width to window total-width.
> +TEXT-WIDTH is the desired text width of the window. The function
> +calculates what total width is required for a window in the
> +selected to have a text-width of TEXT-WIDTH columns. The
> +calculation considers possible fringes and scroll bars. This
> +function assumes that the desired window has the same character
> +width as the frame."
> + (let ((char-width (frame-char-width)))
> + (+ text-width
> + (/ (frame-fringe-width) char-width)
> + (/ (frame-scroll-bar-width) char-width)
> + (if (which-key--char-enlarged-p) 1 0)
> + ;; add padding to account for possible wide (unicode) characters
> + 3)))
> +
> +(defun which-key--total-width-to-text (total-width)
> + "Convert window total-width to window text-width.
> +TOTAL-WIDTH is the desired total width of the window. The function calculates
> +what text width fits such a window. The calculation considers possible fringes
> +and scroll bars. This function assumes that the desired window has the same
> +character width as the frame."
> + (let ((char-width (frame-char-width)))
> + (- total-width
> + (/ (frame-fringe-width) char-width)
> + (/ (frame-scroll-bar-width) char-width)
> + (if (which-key--char-enlarged-p) 1 0)
> + ;; add padding to account for possible wide (unicode) characters
> + 3)))
> +
> +(defun which-key--char-enlarged-p (&optional _frame)
> + (> (frame-char-width)
> + (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
> +
> +(defun which-key--char-reduced-p (&optional _frame)
> + (< (frame-char-width)
> + (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
> +
> +(defun which-key--char-exact-p (&optional _frame)
> + (= (frame-char-width)
> + (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
> +
> +(defun which-key--width-or-percentage-to-width (width-or-percentage)
> + "Return window total width.
> +If WIDTH-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
> +should be a percentage (a number between 0 and 1) out of the frame's width.
> +More precisely, it should be a percentage out of the frame's root window's
> +total width."
> + (if (wholenump width-or-percentage)
> + width-or-percentage
> + (round (* width-or-percentage (window-total-width (frame-root-window))))))
> +
> +(defun which-key--height-or-percentage-to-height (height-or-percentage)
> + "Return window total height.
> +If HEIGHT-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
> +should be a percentage (a number between 0 and 1) out of the frame's height.
> +More precisely, it should be a percentage out of the frame's root window's
> +total height."
> + (if (wholenump height-or-percentage)
> + height-or-percentage
> + (round (* height-or-percentage (window-total-height (frame-root-window))))))
> +
> +(defun which-key--frame-size-changed-p ()
> + "Non-nil if a change in frame size is detected."
> + (let ((new-size (cons (frame-width) (frame-height))))
> + (cond ((null which-key--previous-frame-size)
> + (setq which-key--previous-frame-size new-size)
> + nil)
> + ((not (equal which-key--previous-frame-size new-size))
> + (setq which-key--previous-frame-size new-size)))))
> +
> +;;; Show/hide which-key buffer
> +
> +(defun which-key--hide-popup ()
> + "This function is called to hide the which-key buffer."
> + (unless (or which-key-persistent-popup
> + (member real-this-command which-key--paging-functions))
> + (setq which-key--last-try-2-loc nil)
> + (setq which-key--pages-obj nil)
> + (setq which-key--automatic-display nil)
> + (setq which-key--prior-show-keymap-args nil)
> + (when (and which-key-idle-secondary-delay which-key--secondary-timer-active)
> + (which-key--start-timer))
> + (which-key--lighter-restore)
> + (which-key--hide-popup-ignore-command)))
> +
> +(defun which-key--hide-popup-ignore-command ()
> + "Version of `which-key--hide-popup' without the check of
> +`real-this-command'."
> + (cl-case which-key-popup-type
> + ;; Not necessary to hide minibuffer
> + ;; (minibuffer (which-key--hide-buffer-minibuffer))
> + (side-window (which-key--hide-buffer-side-window))
> + (frame (which-key--hide-buffer-frame))
> + (custom (funcall which-key-custom-hide-popup-function))))
> +
> +(defun which-key--hide-popup-on-frame-size-change (&optional _)
> + "Hide which-key popup if the frame is resized (to trigger a new popup)."
> + (when (which-key--frame-size-changed-p)
> + (which-key--hide-popup)))
> +
> +(defun which-key--hide-buffer-side-window ()
> + "Hide which-key buffer when side-window popup is used."
> + (when (buffer-live-p which-key--buffer)
> + ;; in case which-key buffer was shown in an existing window, `quit-window'
> + ;; will re-show the previous buffer, instead of closing the window
> + (quit-windows-on which-key--buffer)
> + (when (and which-key-preserve-window-configuration
> + which-key--saved-window-configuration)
> + (set-window-configuration which-key--saved-window-configuration)
> + (setq which-key--saved-window-configuration nil))))
> +
> +(defun which-key--hide-buffer-frame ()
> + "Hide which-key buffer when frame popup is used."
> + (when (frame-live-p which-key--frame)
> + (delete-frame which-key--frame)))
> +
> +(defun which-key--popup-showing-p ()
> + (and (bufferp which-key--buffer)
> + (or (window-live-p (get-buffer-window which-key--buffer))
> + (let ((window (get-buffer-window which-key--buffer t)))
> + (and (window-live-p window)
> + (frame-visible-p (window-frame window)))))))
> +
> +(defun which-key--show-popup (act-popup-dim)
> + "Show the which-key buffer.
> +ACT-POPUP-DIM includes the dimensions, (height . width) of the
> +buffer text to be displayed in the popup. Return nil if no window
> +is shown, or if there is no need to start the closing timer."
> + (when (and (> (car act-popup-dim) 0)
> + (> (cdr act-popup-dim) 0))
> + (cl-case which-key-popup-type
> + ;; Not called for minibuffer
> + ;; (minibuffer (which-key--show-buffer-minibuffer act-popup-dim))
> + (side-window (which-key--show-buffer-side-window act-popup-dim))
> + (frame (which-key--show-buffer-frame act-popup-dim))
> + (custom (funcall which-key-custom-show-popup-function act-popup-dim)))))
> +
> +(defun which-key--fit-buffer-to-window-horizontally
> + (&optional window &rest params)
> + "Slightly modified version of `fit-buffer-to-window'.
> +Use &rest params because `fit-buffer-to-window' has a different
> +call signature in different emacs versions"
> + (let ((fit-window-to-buffer-horizontally t)
> + (window-min-height 1))
> + (apply #'fit-window-to-buffer window params)))
> +
> +(defun which-key--show-buffer-side-window (act-popup-dim)
> + "Show which-key buffer when popup type is side-window."
> + (when (and which-key-preserve-window-configuration
> + (not which-key--saved-window-configuration))
> + (setq which-key--saved-window-configuration (current-window-configuration)))
> + (let* ((height (car act-popup-dim))
> + (width (cdr act-popup-dim))
> + (alist
> + (if which-key-allow-imprecise-window-fit
> + `((window-width . ,(which-key--text-width-to-total width))
> + (window-height . ,height)
> + (side . ,which-key-side-window-location)
> + (slot . ,which-key-side-window-slot))
> + `((window-width . which-key--fit-buffer-to-window-horizontally)
> + (window-height . (lambda (w) (fit-window-to-buffer w nil 1)))
> + (side . ,which-key-side-window-location)
> + (slot . ,which-key-side-window-slot)))))
> + ;; Previously used `display-buffer-in-major-side-window' here, but
> + ;; apparently that is meant to be an internal function. See emacs bug #24828
> + ;; and advice given there.
> + (cond
> + ((eq which-key--multiple-locations t)
> + ;; possibly want to switch sides in this case so we can't reuse the window
> + (delete-windows-on which-key--buffer)
> + (display-buffer-in-side-window which-key--buffer alist))
> + ((get-buffer-window which-key--buffer)
> + (display-buffer-reuse-window which-key--buffer alist))
> + (t
> + (display-buffer-in-side-window which-key--buffer alist)))))
> +
> +(defun which-key--show-buffer-frame (act-popup-dim)
> + "Show which-key buffer when popup type is frame."
> + (let* (;(orig-window (selected-window))
> + (frame-height (+ (car act-popup-dim)
> + (if (with-current-buffer which-key--buffer
> + mode-line-format)
> + 1
> + 0)))
> + ;; without adding 2, frame sometimes isn't wide enough for the buffer.
> + ;; this is probably because of the fringes. however, setting fringes
> + ;; sizes to 0 (instead of adding 2) didn't always make the frame wide
> + ;; enough. don't know why it is so.
> + (frame-width (+ (cdr act-popup-dim) 2))
> + (new-window (if (and (frame-live-p which-key--frame)
> + (eq which-key--buffer
> + (window-buffer
> + (frame-root-window which-key--frame))))
> + (which-key--show-buffer-reuse-frame
> + frame-height frame-width)
> + (which-key--show-buffer-new-frame
> + frame-height frame-width))))
> + (when new-window
> + ;; display successful
> + (setq which-key--frame (window-frame new-window))
> + new-window)))
> +
> +(defun which-key--show-buffer-new-frame (frame-height frame-width)
> + "Helper for `which-key--show-buffer-frame'."
> + (let* ((frame-params `((height . ,frame-height)
> + (width . ,frame-width)
> + ;; tell the window manager to respect the given sizes
> + (user-size . t)
> + ;; which-key frame doesn't need a minibuffer
> + (minibuffer . nil)
> + (name . "which-key")
> + ;; no need for scroll bars in which-key frame
> + (vertical-scroll-bars . nil)
> + ;; (left-fringe . 0)
> + ;; (right-fringe . 0)
> + ;; (right-divider-width . 0)
> + ;; make sure frame is visible
> + (visibility . t)))
> + (alist `((pop-up-frame-parameters . ,frame-params)))
> + (orig-frame (selected-frame))
> + (new-window (display-buffer-pop-up-frame which-key--buffer alist)))
> + (when new-window
> + ;; display successful
> + (redirect-frame-focus (window-frame new-window) orig-frame)
> + new-window)))
> +
> +(defun which-key--show-buffer-reuse-frame (frame-height frame-width)
> + "Helper for `which-key--show-buffer-frame'."
> + (let ((window
> + (display-buffer-reuse-window
> + which-key--buffer `((reusable-frames . ,which-key--frame)))))
> + (when window
> + ;; display successful
> + (set-frame-size (window-frame window) frame-width frame-height)
> + window)))
> +
> +;;; Max dimension of available window functions
> +
> +(defun which-key--popup-max-dimensions ()
> + "Dimesion functions should return the maximum possible (height
> +. width) of the intended popup. SELECTED-WINDOW-WIDTH is the
> +width of currently active window, not the which-key buffer
> +window."
> + (cl-case which-key-popup-type
> + (minibuffer (which-key--minibuffer-max-dimensions))
> + (side-window (which-key--side-window-max-dimensions))
> + (frame (which-key--frame-max-dimensions))
> + (custom (funcall which-key-custom-popup-max-dimensions-function
> + (window-width)))))
> +
> +(defun which-key--minibuffer-max-dimensions ()
> + "Return max-dimensions of minibuffer (height . width).
> +Measured in lines and characters respectively."
> + (cons
> + ;; height
> + (if (floatp max-mini-window-height)
> + (floor (* (frame-text-lines)
> + max-mini-window-height))
> + max-mini-window-height)
> + ;; width
> + (max 0 (- (frame-text-cols) which-key-unicode-correction))))
> +
> +(defun which-key--side-window-max-dimensions ()
> + "Return max-dimensions of the side-window popup (height .
> +width) in lines and characters respectively."
> + (cons
> + ;; height
> + (if (member which-key-side-window-location '(left right))
> + ;; 1 is a kludge to make sure there is no overlap
> + (- (frame-height) (window-text-height (minibuffer-window)) 1)
> + ;; (window-mode-line-height which-key--window))
> + ;; FIXME: change to something like
> + ;; (min which-*-height (calculate-max-height))
> + (which-key--height-or-percentage-to-height
> + which-key-side-window-max-height))
> + ;; width
> + (max 0
> + (- (if (member which-key-side-window-location '(left right))
Could be a memq here.
> + (which-key--total-width-to-text
> + (which-key--width-or-percentage-to-width
> + which-key-side-window-max-width))
> + (which-key--total-width-to-text
> + (which-key--width-or-percentage-to-width
> + 1.0)))
> + which-key-unicode-correction))))
> +
> +(defun which-key--frame-max-dimensions ()
> + "Return max-dimensions of the frame popup (height .
> +width) in lines and characters respectively."
> + (cons which-key-frame-max-height which-key-frame-max-width))
> +
> +;;; Sorting functions
> +
> +(defun which-key--string< (a b &optional alpha)
> + (let ((da (downcase a))
> + (db (downcase b)))
Perhaps you could also use `string-equal-ignore-case' below.
> + (cond
> + ((and alpha (not which-key-sort-uppercase-first))
> + (if (string-equal da db)
> + (not (string-lessp a b))
> + (string-lessp da db)))
> + ((and alpha which-key-sort-uppercase-first)
> + (if (string-equal da db)
> + (string-lessp a b)
> + (string-lessp da db)))
> + ((not which-key-sort-uppercase-first)
> + (let ((aup (not (string-equal da a)))
> + (bup (not (string-equal db b))))
> + (if (eq aup bup)
> + (string-lessp a b)
> + bup)))
> + (t (string-lessp a b)))))
> +
> +(defun which-key--key-description< (a b &optional alpha)
> + "Sorting function used for `which-key-key-order' and
> +`which-key-key-order-alpha'."
> + (save-match-data
> + (let* ((a (which-key--extract-key a))
> + (b (which-key--extract-key b))
> + (rngrgxp "^\\([^ ]+\\) \\.\\. [^ ]+")
> + (a (if (string-match rngrgxp a) (match-string 1 a) a))
> + (b (if (string-match rngrgxp b) (match-string 1 b) b))
> + (aem? (string-equal a ""))
> + (bem? (string-equal b ""))
> + (a1? (= 1 (length a)))
> + (b1? (= 1 (length b)))
> + (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
> + (asp? (string-match-p srgxp a))
> + (bsp? (string-match-p srgxp b))
> + (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
> + (apr? (string-match-p prrgxp a))
> + (bpr? (string-match-p prrgxp b))
> + (afn? (string-match-p "<f[0-9]+>" a))
> + (bfn? (string-match-p "<f[0-9]+>" b)))
> + (cond ((or aem? bem?) (and aem? (not bem?)))
> + ((and asp? bsp?)
> + (if (string-equal (substring a 0 3) (substring b 0 3))
> + (which-key--key-description<
> + (substring a 3) (substring b 3) alpha)
> + (which-key--string< a b alpha)))
> + ((or asp? bsp?) asp?)
> + ((and a1? b1?) (which-key--string< a b alpha))
> + ((or a1? b1?) a1?)
> + ((and afn? bfn?)
> + (< (string-to-number
> + (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" a))
> + (string-to-number
> + (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" b))))
> + ((or afn? bfn?) afn?)
> + ((and apr? bpr?)
> + (if (string-equal (substring a 0 2) (substring b 0 2))
> + (which-key--key-description<
> + (substring a 2) (substring b 2) alpha)
> + (which-key--string< a b alpha)))
> + ((or apr? bpr?) apr?)
> + (t (which-key--string< a b alpha))))))
> +
> +(defsubst which-key-key-order-alpha (acons bcons)
> + "Order key descriptions A and B.
> +Order is lexicographic within a \"class\", where the classes and
> +the ordering of classes are listed below.
> +
> +special (SPC,TAB,...) < single char < mod (C-,M-,...) < other.
> +Sorts single characters alphabetically with lowercase coming
> +before upper."
> + (which-key--key-description< (car acons) (car bcons) t))
> +
> +(defsubst which-key-key-order (acons bcons)
> + "Order key descriptions A and B.
> +Order is lexicographic within a \"class\", where the classes and
> +the ordering of classes are listed below.
> +
> +special (SPC,TAB,...) < single char < mod (C-,M-,...) < other."
> + (which-key--key-description< (car acons) (car bcons)))
> +
> +(defsubst which-key-description-order (acons bcons)
> + "Order descriptions of A and B.
> +Uses `string-lessp' after applying lowercase."
> + (string-lessp (downcase (cdr acons)) (downcase (cdr bcons))))
> +
> +(defsubst which-key--group-p (description)
> + (or (string-equal description "prefix")
> + (string-match-p "^group:" description)
> + (keymapp (intern description))))
> +
> +(defun which-key-prefix-then-key-order (acons bcons)
> + "Order first by whether A and/or B is a prefix with no prefix
> +coming before a prefix. Within these categories order using
> +`which-key-key-order'."
> + (let ((apref? (which-key--group-p (cdr acons)))
> + (bpref? (which-key--group-p (cdr bcons))))
> + (if (not (eq apref? bpref?))
> + (and (not apref?) bpref?)
> + (which-key-key-order acons bcons))))
> +
> +(defun which-key-prefix-then-key-order-reverse (acons bcons)
> + "Order first by whether A and/or B is a prefix with prefix
> +coming before a prefix. Within these categories order using
> +`which-key-key-order'."
> + (let ((apref? (which-key--group-p (cdr acons)))
> + (bpref? (which-key--group-p (cdr bcons))))
> + (if (not (eq apref? bpref?))
> + (and apref? (not bpref?))
> + (which-key-key-order acons bcons))))
> +
> +(defun which-key-local-then-key-order (acons bcons)
> + "Order first by whether A and/or B is a local binding with
> +local bindings coming first. Within these categories order using
> +`which-key-key-order'."
> + (let ((aloc? (which-key--local-binding-p acons))
> + (bloc? (which-key--local-binding-p bcons)))
> + (if (not (eq aloc? bloc?))
> + (and aloc? (not bloc?))
> + (which-key-key-order acons bcons))))
> +
> +;;; Functions for retrieving and formatting keys
> +
> +(defsubst which-key--string-width (maybe-string)
> + "If MAYBE-STRING is a string use `which-key--string-width' o/w return 0."
> + (if (stringp maybe-string) (string-width maybe-string) 0))
> +
> +(defsubst which-key--butlast-string (str)
> + (mapconcat #'identity (butlast (split-string str)) " "))
Or string-join.
> +
> +(defun which-key--match-replacement (key-binding replacement)
> + ;; these are mode specific ones to ignore. The mode specific case is
> + ;; handled in the selection of alist
> + (when (and (consp key-binding) (not (symbolp (car replacement))))
> + (let ((key-regexp (caar replacement))
> + (binding-regexp (cdar replacement))
> + case-fold-search)
> + (and (or (null key-regexp)
> + (string-match-p key-regexp
> + (car key-binding)))
> + (or (null binding-regexp)
> + (string-match-p binding-regexp
> + (cdr key-binding)))))))
> +
> +(defsubst which-key--replace-in-binding (key-binding repl)
> + (cond ((or (not (consp repl)) (null (cdr repl)))
> + key-binding)
> + ((functionp (cdr repl))
> + (funcall (cdr repl) key-binding))
> + ((consp (cdr repl))
> + (cons
> + (cond ((and (caar repl) (cadr repl))
> + (replace-regexp-in-string
> + (caar repl) (cadr repl) (car key-binding) t))
> + ((cadr repl) (cadr repl))
> + (t (car key-binding)))
> + (cond ((and (cdar repl) (cddr repl))
> + (replace-regexp-in-string
> + (cdar repl) (cddr repl) (cdr key-binding) t))
> + ((cddr repl) (cddr repl))
> + (t (cdr key-binding)))))))
> +
> +(defun which-key--replace-in-repl-list-once (key-binding repls)
> + (cl-dolist (repl repls)
> + (when (which-key--match-replacement key-binding repl)
> + (cl-return `(replaced . ,(which-key--replace-in-binding key-binding repl))))))
> +
> +(defun which-key--replace-in-repl-list-many (key-binding repls)
> + (let (found)
> + (dolist (repl repls)
> + (when (which-key--match-replacement key-binding repl)
> + (setq found 't)
> + (setq key-binding (which-key--replace-in-binding key-binding repl))))
> + (when found `(replaced . ,key-binding))))
I think a throw-catch construct would be preferable.
> +
> +(defun which-key--maybe-replace (key-binding)
> + "Use `which-key--replacement-alist' to maybe replace KEY-BINDING.
> +KEY-BINDING is a cons cell of the form \(KEY . BINDING\) each of
> +which are strings. KEY is of the form produced by `key-binding'."
> + (let* ((replacer (if which-key-allow-multiple-replacements
> + #'which-key--replace-in-repl-list-many
> + #'which-key--replace-in-repl-list-once)))
> + (pcase
> + (apply replacer
> + (list key-binding
> + (cdr-safe (assq major-mode which-key-replacement-alist))))
> + (`(replaced . ,repl)
> + (if which-key-allow-multiple-replacements
> + (pcase (apply replacer (list repl which-key-replacement-alist))
> + (`(replaced . ,repl) repl)
> + ('() repl))
> + repl))
> + ('()
> + (pcase (apply replacer (list key-binding which-key-replacement-alist))
> + (`(replaced . ,repl) repl)
> + ('() key-binding))))))
> +
> +(defsubst which-key--current-key-list (&optional key-str)
> + (append (listify-key-sequence (which-key--current-prefix))
> + (when key-str
> + (listify-key-sequence (kbd key-str)))))
> +
> +(defsubst which-key--current-key-string (&optional key-str)
> + (key-description (which-key--current-key-list key-str)))
> +
> +(defun which-key--local-binding-p (keydesc)
> + (eq (which-key--safe-lookup-key-description
> + (current-local-map)
> + (which-key--current-key-string (car keydesc)))
> + (intern (cdr keydesc))))
> +
> +(defun which-key--map-binding-p (map keydesc)
> + "Does MAP contain KEYDESC = (key . binding)?"
> + (or
> + (when (bound-and-true-p evil-state)
> + (let ((lookup
> + (which-key--safe-lookup-key-description
> + map
> + (which-key--current-key-string
> + (format "<%s-state> %s" evil-state (car keydesc))))))
> + (or (eq lookup (intern (cdr keydesc)))
> + (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command")))))
> + (let ((lookup
> + (which-key--safe-lookup-key-description
> + map (which-key--current-key-string (car keydesc)))))
> + (or (eq lookup (intern (cdr keydesc)))
> + (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command"))))))
> +
> +(defun which-key--maybe-get-prefix-title (keys)
> + "KEYS is a string produced by `key-description'.
> +A title is possibly returned using
> +`which-key--prefix-title-alist'. An empty string is returned if
> +no title exists."
> + (cond
> + ((not (string-equal keys ""))
> + (let* ((title-res
> + (cdr-safe (assoc-string keys which-key--prefix-title-alist)))
> + (repl-res
> + (cdr-safe (which-key--maybe-replace (cons keys ""))))
> + (binding (key-binding (kbd keys)))
> + (alternate (when (and binding (symbolp binding))
> + (symbol-name binding))))
> + (cond (title-res title-res)
> + ((not (string-equal repl-res "")) repl-res)
> + ((and (eq which-key-show-prefix 'echo) alternate)
> + alternate)
> + ((and (member which-key-show-prefix '(bottom top mode-line))
> + (eq which-key-side-window-location 'bottom)
> + echo-keystrokes)
> + (if alternate alternate
> + (concat "Following " keys)))
> + (t ""))))
> + (t "")))
> +
> +(defun which-key--propertize (string &rest properties)
> + "Version of `propertize' that checks type of STRING."
> + (when (stringp string)
> + (apply #'propertize string properties)))
What is the point of this? This seems to be the kind of thing that
would let bugs slide through silently.
> +
> +(defun which-key--propertize-key (key)
> + "Add a face to KEY.
> +If KEY contains any \"special keys\" defined in
> +`which-key-special-keys' then truncate and add the corresponding
> +`which-key-special-key-face'."
> + (let ((key-w-face (which-key--propertize key 'face 'which-key-key-face))
> + (regexp (concat "\\("
> + (mapconcat #'identity which-key-special-keys
> + "\\|")
> + "\\)"))
> + case-fold-search)
> + (save-match-data
> + (if (and which-key-special-keys
> + (string-match regexp key))
> + (let ((beg (match-beginning 0)) (end (match-end 0)))
> + (concat (substring key-w-face 0 beg)
> + (which-key--propertize (substring key-w-face beg (1+ beg))
> + 'face 'which-key-special-key-face)
> + (substring key-w-face end
> + (which-key--string-width key-w-face))))
> + key-w-face))))
> +
> +(defsubst which-key--truncate-description (desc avl-width)
> + "Truncate DESC description to `which-key-max-description-length'."
> + (let* ((max which-key-max-description-length)
> + (max (cl-etypecase max
> + (null nil)
> + (integer max)
> + (float (truncate (* max avl-width)))
> + (function (let ((val (funcall max avl-width)))
> + (if (floatp val) (truncate val) val))))))
> + (if (and max (> (length desc) max))
> + (let ((dots (and (not (equal which-key-ellipsis ""))
> + (which-key--propertize
> + which-key-ellipsis 'face
> + (get-text-property (1- (length desc)) 'face desc)))))
> + (if dots
> + (concat (substring desc 0 (- max (length dots))) dots)
> + (substring desc 0 max)))
> + desc)))
> +
> +(defun which-key--highlight-face (description)
> + "Return the highlight face for DESCRIPTION if it has one."
> + (let (face)
> + (dolist (el which-key-highlighted-command-list)
> + (unless face
> + (cond ((consp el)
> + (when (string-match-p (car el) description)
> + (setq face (cdr el))))
> + ((stringp el)
> + (when (string-match-p el description)
> + (setq face 'which-key-highlighted-command-face)))
> + (t
> + (message "which-key: warning: element %s of \
> +which-key-highlighted-command-list is not a string or a cons
> +cell" el)))))
> + face))
> +
> +(defun which-key--propertize-description
> + (description group local hl-face &optional original-description)
> + "Add face to DESCRIPTION where the face chosen depends on
> +whether the description represents a group or a command. Also
> +make some minor adjustments to the description string, like
> +removing a \"group:\" prefix.
> +
> +ORIGINAL-DESCRIPTION is the description given by
> +`describe-buffer-bindings'."
> + (when description
> + (let* ((desc description)
> + (desc (if (string-match-p "^group:" desc)
> + (substring desc 6) desc))
> + (desc (if group (concat which-key-prefix-prefix desc) desc)))
> + (make-text-button
> + desc nil
> + 'face (cond (hl-face hl-face)
> + (group 'which-key-group-description-face)
> + (local 'which-key-local-map-description-face)
> + (t 'which-key-command-description-face))
> + 'help-echo (cond
> + ((and original-description
> + (fboundp (intern original-description))
> + (documentation (intern original-description))
> + ;; tooltip-mode doesn't exist in emacs-nox
> + (boundp 'tooltip-mode) tooltip-mode)
> + (documentation (intern original-description)))
> + ((and original-description
> + (fboundp (intern original-description))
> + (documentation (intern original-description))
> + (let* ((doc (documentation
> + (intern original-description)))
> + (str (replace-regexp-in-string "\n" " " doc))
> + (max (floor (* (frame-width) 0.8))))
> + (if (> (length str) max)
> + (concat (substring str 0 max) "...")
> + str)))))))))
> +
> +(defun which-key--extract-key (key-str)
> + "Pull the last key (or key range) out of KEY-STR."
> + (save-match-data
> + (let ((key-range-regexp "\\`.*\\([^ \t]+ \\.\\. [^ \t]+\\)\\'"))
> + (if (string-match key-range-regexp key-str)
> + (match-string 1 key-str)
> + (car (last (split-string key-str " ")))))))
> +
> +(defun which-key--maybe-add-docstring (current original)
> + "Maybe concat a docstring to CURRENT and return result.
> +Specifically, do this if ORIGINAL is a command with a docstring
> +and `which-key-show-docstrings' is non-nil. If
> +`which-key-show-docstrings' is the symbol docstring-only, just
> +return the docstring."
> + (let* ((orig-sym (intern original))
> + (doc (when (commandp orig-sym)
> + (documentation orig-sym)))
> + (doc (when doc
> + (replace-regexp-in-string
> + (concat "^\\(?::"
> + (regexp-opt '("around" "override"
> + "after" "after-until" "after-while"
> + "before" "before-until" "before-while"
> + "filter-args" "filter-return"))
> + " advice: [^\n]+\n"
> + "\\)+\n")
> + "" doc)))
> + (docstring (when doc
> + (which-key--propertize (car (split-string doc "\n"))
> + 'face 'which-key-docstring-face))))
> + (cond ((not (and which-key-show-docstrings docstring))
> + current)
> + ((eq which-key-show-docstrings 'docstring-only)
> + docstring)
> + (t
> + (format "%s %s" current docstring)))))
> +
> +(defun which-key--format-and-replace (unformatted &optional preserve-full-key)
> + "Take a list of (key . desc) cons cells in UNFORMATTED, add
> +faces and perform replacements according to the three replacement
> +alists. Returns a list (key separator description)."
> + (let ((sep-w-face
> + (which-key--propertize which-key-separator
> + 'face 'which-key-separator-face))
> + (local-map (current-local-map))
> + (avl-width (cdr (which-key--popup-max-dimensions)))
> + new-list)
> + (dolist (key-binding unformatted)
> + (let* ((keys (car key-binding))
> + (orig-desc (cdr key-binding))
> + (group (which-key--group-p orig-desc))
> + (local (eq (which-key--safe-lookup-key-description
> + local-map keys)
> + (intern orig-desc)))
> + (hl-face (which-key--highlight-face orig-desc))
> + (key-binding (which-key--maybe-replace key-binding))
> + (final-desc (which-key--propertize-description
> + (cdr key-binding) group local hl-face orig-desc)))
> + (when final-desc
> + (setq final-desc
> + (which-key--truncate-description
> + (which-key--maybe-add-docstring final-desc orig-desc)
> + avl-width)))
> + (when (consp key-binding)
> + (push
> + (list (which-key--propertize-key
> + (if preserve-full-key
> + (car key-binding)
> + (which-key--extract-key (car key-binding))))
> + sep-w-face
> + final-desc)
> + new-list))))
> + (nreverse new-list)))
> +
> +(defun which-key--compute-binding (binding)
> + "Replace BINDING with remapped binding if it exists.
> +
> +Requires `which-key-compute-remaps' to be non-nil"
> + (let (remap)
> + (if (and which-key-compute-remaps
> + (setq remap (command-remapping binding)))
> + (copy-sequence (symbol-name remap))
> + (copy-sequence (symbol-name binding)))))
> +
> +(defun which-key--get-menu-item-binding (def)
> + "Retrieve binding for menu-item"
> + ;; see `keymap--menu-item-binding'
> + (let* ((binding (nth 2 def))
> + (plist (nthcdr 3 def))
> + (filter (plist-get plist :filter)))
> + (if filter (funcall filter binding) binding)))
> +
> +(defun which-key--get-keymap-bindings-1
> + (keymap start &optional prefix filter all ignore-commands)
> + "See `which-key--get-keymap-bindings'."
> + (let ((bindings start)
> + (prefix-map (if prefix (lookup-key keymap prefix) keymap)))
> + (when (keymapp prefix-map)
> + (map-keymap
> + (lambda (ev def)
> + (let* ((key (vconcat prefix (list ev)))
> + (key-desc (key-description key)))
> + (cond
> + ((assoc key-desc bindings))
> + ((and (listp ignore-commands) (symbolp def) (memq def ignore-commands)))
> + ((or (string-match-p
> + which-key--ignore-non-evil-keys-regexp key-desc)
> + (eq ev 'menu-bar)))
> + ((and (keymapp def)
> + (string-match-p which-key--evil-keys-regexp key-desc)))
> + ((and (keymapp def)
> + (or all
> + ;; event 27 is escape, so this will pick up meta
> + ;; bindings and hopefully not too much more
> + (and (numberp ev) (= ev 27))))
> + (setq bindings
> + (which-key--get-keymap-bindings-1
> + keymap bindings key nil all ignore-commands)))
> + (def
> + (let* ((def (if (eq 'menu-item (car-safe def))
> + (which-key--get-menu-item-binding def)
> + def))
> + (binding
> + (cons key-desc
> + (cond
> + ((symbolp def) (which-key--compute-binding def))
> + ((keymapp def) "prefix")
> + ((eq 'lambda (car-safe def)) "lambda")
> + ((eq 'closure (car-safe def)) "closure")
> + ((stringp def) def)
> + ((vectorp def) (key-description def))
> + ((and (consp def)
> + ;; looking for (STRING . DEFN)
> + (stringp (car def)))
> + (concat (when (keymapp (cdr-safe def))
> + "group:")
> + (car def)))
> + (t "unknown")))))
> + (when (or (null filter)
> + (and (functionp filter)
> + (funcall filter binding)))
> + (push binding bindings)))))))
> + prefix-map))
> + bindings))
> +
> +(defun which-key--get-keymap-bindings
> + (keymap &optional start prefix filter all evil)
> + "Retrieve top-level bindings from KEYMAP.
> +PREFIX limits bindings to those starting with this key
> +sequence. START is a list of existing bindings to add to. If ALL
> +is non-nil, recursively retrieve all bindings below PREFIX. If
> +EVIL is non-nil, extract active evil bidings."
> + (let ((bindings start)
> + (ignore '(self-insert-command ignore ignore-event company-ignore))
> + (evil-map
> + (when (and evil (bound-and-true-p evil-local-mode))
> + (lookup-key keymap (kbd (format "<%s-state>" evil-state))))))
> + (when (keymapp evil-map)
> + (setq bindings (which-key--get-keymap-bindings-1
> + evil-map bindings prefix filter all ignore)))
> + (which-key--get-keymap-bindings-1
> + keymap bindings prefix filter all ignore)))
> +
> +(defun which-key--get-current-bindings (&optional prefix filter)
> + "Generate a list of current active bindings."
> + (let (bindings)
> + (dolist (map (current-active-maps t) bindings)
> + (when (cdr map)
> + (setq bindings
> + (which-key--get-keymap-bindings
> + map bindings prefix filter))))))
> +
> +(defun which-key--get-bindings (&optional prefix keymap filter recursive)
> + "Collect key bindings.
> +If KEYMAP is nil, collect from current buffer using the current
> +key sequence as a prefix. Otherwise, collect from KEYMAP. FILTER
> +is a function to use to filter the bindings. If RECURSIVE is
> +non-nil, then bindings are collected recursively for all prefixes."
> + (let* ((unformatted
> + (cond ((keymapp keymap)
> + (which-key--get-keymap-bindings
> + keymap nil prefix filter recursive))
> + (keymap
> + (error "%s is not a keymap" keymap))
> + (t
> + (which-key--get-current-bindings prefix filter)))))
> + (when which-key-sort-order
> + (setq unformatted
> + (sort unformatted which-key-sort-order)))
> + (which-key--format-and-replace unformatted recursive)))
> +
> +;;; Functions for laying out which-key buffer pages
> +
> +(defun which-key--normalize-columns (columns)
> + "Pad COLUMNS to the same length using empty strings."
> + (let ((max-len (cl-reduce (lambda (a x) (max a (length x))) columns
> + :initial-value 0)))
> + (mapcar
> + (lambda (c)
> + (if (< (length c) max-len)
Using (length< c max-len) avoids traversing the entire list, but it
probably doesn't matter because of the length in the next line.
> + (append c (make-list (- max-len (length c)) ""))
> + c))
> + columns)))
> +
> +(defsubst which-key--join-columns (columns)
> + "Transpose columns into rows, concat rows into lines and rows into page."
> + (let* ((padded (which-key--normalize-columns (nreverse columns)))
> + (rows (apply #'cl-mapcar #'list padded)))
> + (mapconcat (lambda (row) (mapconcat #'identity row " ")) rows "\n")))
> +
> +(defsubst which-key--max-len (keys index &optional initial-value)
> + "Internal function for finding the max length of the INDEX
> +element in each list element of KEYS."
> + (cl-reduce
> + (lambda (x y) (max x (which-key--string-width (nth index y))))
> + keys :initial-value (if initial-value initial-value 0)))
> +
> +(defun which-key--pad-column (col-keys avl-width)
> + "Take a column of (key separator description) COL-KEYS,
> +calculate the max width in the column and pad all cells out to
> +that width."
> + (let* ((col-key-width (+ which-key-add-column-padding
> + (which-key--max-len col-keys 0)))
> + (col-sep-width (which-key--max-len col-keys 1))
> + (avl-width (- avl-width col-key-width col-sep-width))
> + (col-desc-width (min avl-width
> + (which-key--max-len
> + col-keys 2
> + which-key-min-column-description-width)))
> + (col-width (+ col-key-width col-sep-width col-desc-width))
> + (col-format (concat "%" (int-to-string col-key-width)
> + "s%s%-" (int-to-string col-desc-width) "s")))
> + (cons col-width
> + (mapcar (lambda (k) (apply #'format col-format k))
> + col-keys))))
> +
> +(defun which-key--partition-list (n list)
> + "Partition LIST into N-sized sublists."
> + (let (res)
> + (while list
> + (setq res (cons (cl-subseq list 0 (min n (length list))) res)
> + list (nthcdr n list)))
> + (nreverse res)))
> +
> +(defun which-key--list-to-pages (keys avl-lines avl-width)
> + "Convert list of KEYS to columns based on dimensions AVL-LINES and AVL-WIDTH.
> +Returns a `which-key--pages' object that holds the page strings,
> +as well as metadata."
> + (let ((cols-w-widths (mapcar (lambda (c) (which-key--pad-column c avl-width))
> + (which-key--partition-list avl-lines keys)))
> + (page-width 0) (n-pages 0) (n-keys 0) (n-columns 0)
> + page-cols pages page-widths keys/page col)
> + (if (> (apply #'max (mapcar #'car cols-w-widths)) avl-width)
It probably won't cause any issues, but
(cl-reduce #'max cols-w-widths :key #'car)
shouldn't run into issues with the maximum number of arguments you can
apply to a function. Also saves you from consing a list.
> + ;; give up if no columns fit
> + nil
> + (while cols-w-widths
> + ;; start new page
> + (cl-incf n-pages)
> + (setq col (pop cols-w-widths))
> + (setq page-cols (list (cdr col)))
> + (setq page-width (car col))
> + (setq n-keys (length (cdr col)))
> + (setq n-columns 1)
> + ;; add additional columns as long as they fit
> + (while (and cols-w-widths
> + (or (null which-key-max-display-columns)
> + (< n-columns which-key-max-display-columns))
> + (<= (+ page-width 1 (caar cols-w-widths)) avl-width))
> + (setq col (pop cols-w-widths))
> + (push (cdr col) page-cols)
> + (cl-incf page-width (1+ (car col)))
> + (cl-incf n-keys (length (cdr col)))
> + (cl-incf n-columns))
> + (push (which-key--join-columns page-cols) pages)
> + (push n-keys keys/page)
> + (push page-width page-widths))
> + (make-which-key--pages
> + :pages (nreverse pages)
> + :height (if (> n-pages 1) avl-lines (min avl-lines n-keys))
> + :widths (nreverse page-widths)
> + :keys/page (reverse keys/page)
> + :page-nums (number-sequence 1 n-pages)
> + :num-pages n-pages
> + :total-keys (apply #'+ keys/page)))))
> +
> +(defun which-key--create-pages-1
> + (keys available-lines available-width &optional min-lines vertical)
> + "Create page strings using `which-key--list-to-pages'.
> +Will try to find the best number of rows and columns using the
> +given dimensions and the length and widths of ITEMS. Use VERTICAL
> +if the ITEMS are laid out vertically and the number of columns
> +should be minimized."
> + (let ((result (which-key--list-to-pages
> + keys available-lines available-width))
> + (min-lines (or min-lines 0))
> + found prev-result)
> + (if (or (null result)
> + vertical
> + (> (which-key--pages-num-pages result) 1)
> + (= 1 available-lines))
> + result
> + ;; simple search for a fitting page
> + (while (and (> available-lines min-lines)
> + (not found))
> + (setq available-lines (- available-lines 1)
> + prev-result result
> + result (which-key--list-to-pages
> + keys available-lines available-width)
> + found (> (which-key--pages-num-pages result) 1)))
> + (if found prev-result result))))
> +
> +(defun which-key--create-pages (keys &optional prefix-keys prefix-title)
> + "Create page strings using `which-key--list-to-pages'.
> +Will try to find the best number of rows and columns using the
> +given dimensions and the length and wdiths of KEYS. SEL-WIN-WIDTH
> +is the width of the live window."
> + (let* ((max-dims (which-key--popup-max-dimensions))
> + (max-lines (car max-dims))
> + (max-width (cdr max-dims))
> + (prefix-desc (key-description prefix-keys))
> + (full-prefix (which-key--full-prefix prefix-desc))
> + (prefix (when (eq which-key-show-prefix 'left)
> + (+ 2 (which-key--string-width full-prefix))))
> + (prefix-top-bottom (member which-key-show-prefix '(bottom top)))
> + (avl-lines (if prefix-top-bottom (- max-lines 1) max-lines))
> + (min-lines (min avl-lines which-key-min-display-lines))
> + (avl-width (if prefix (- max-width prefix) max-width))
> + (vertical (or (and (eq which-key-popup-type 'side-window)
> + (member which-key-side-window-location '(left right)))
> + (eq which-key-max-display-columns 1)))
> + result)
> + (setq result
> + (which-key--create-pages-1
> + keys avl-lines avl-width min-lines vertical))
> + (when (and result
> + (> (which-key--pages-num-pages result) 0))
> + (setf (which-key--pages-prefix result) prefix-keys)
> + (setf (which-key--pages-prefix-title result)
> + (or prefix-title
> + (which-key--maybe-get-prefix-title
> + (key-description prefix-keys))))
> + (when prefix-top-bottom
> + ;; Add back the line earlier reserved for the page information.
> + (setf (which-key--pages-height result) max-lines))
> + (when (and (= (which-key--pages-num-pages result) 1)
> + (> which-key-min-display-lines
> + (which-key--pages-height result)))
> + ;; result is shorter than requested, so we artificially increase the
> + ;; height. See #325. Note this only has an effect if
> + ;; `which-key-allow-imprecise-window-fit' is non-nil.
> + (setf (which-key--pages-height result) which-key-min-display-lines))
> + (which-key--debug-message "Frame height: %s
> +Minibuffer height: %s
> +Max dimensions: (%s,%s)
> +Available for bindings: (%s,%s)
> +Actual lines: %s" (frame-height) (window-text-height (minibuffer-window))
> +max-lines max-width avl-lines avl-width (which-key--pages-height result))
> + result)))
> +
> +(defun which-key--lighter-status ()
> + "Possibly show number of keys and total in the mode line."
> + (when which-key-show-remaining-keys
> + (let ((n-shown (car (which-key--pages-keys/page which-key--pages-obj)))
> + (n-tot (which-key--pages-total-keys which-key--pages-obj)))
> + (setcar (cdr (assq 'which-key-mode minor-mode-alist))
> + (format " WK: %s/%s keys" n-shown n-tot)))))
> +
> +(defun which-key--lighter-restore ()
> + "Restore the lighter for which-key."
> + (when which-key-show-remaining-keys
> + (setcar (cdr (assq 'which-key-mode minor-mode-alist))
> + which-key-lighter)))
> +
> +(defun which-key--echo (text)
> + "Echo TEXT to minibuffer without logging."
> + (let (message-log-max)
> + (message "%s" text)))
> +
> +(defun which-key--next-page-hint (prefix-keys)
> + "Return string for next page hint."
> + (let* ((paging-key (concat prefix-keys " " which-key-paging-key))
> + (paging-key-bound (eq 'which-key-C-h-dispatch
> + (key-binding (kbd paging-key))))
> + (key (key-description (vector help-char)))
> + (key (if paging-key-bound
> + (concat key " or " which-key-paging-key)
> + key)))
> + (when (and which-key-use-C-h-commands
> + (not (equal (vector help-char)
> + (vconcat (kbd prefix-keys)))))
> + (which-key--propertize (format "[%s paging/help]" key)
> + 'face 'which-key-note-face))))
> +
> +(eval-and-compile
> + (if (fboundp 'universal-argument--description)
> + (defalias 'which-key--universal-argument--description
> + #'universal-argument--description)
> + (defun which-key--universal-argument--description ()
> + ;; Backport of the definition of universal-argument--description in
> + ;; emacs25 on 2015-12-04
> + (when prefix-arg
> + (concat "C-u"
> + (pcase prefix-arg
> + (`(-) " -")
> + (`(,(and (pred integerp) n))
> + (let ((str ""))
> + (while (and (> n 4) (= (mod n 4) 0))
> + (setq str (concat str " C-u"))
> + (setq n (/ n 4)))
> + (if (= n 4) str (format " %s" prefix-arg))))
> + (_ (format " %s" prefix-arg))))))))
> +
> +(defun which-key--full-prefix (prefix-keys &optional -prefix-arg dont-prop-keys)
> + "Return a description of the full key sequence up to now,
> +including prefix arguments."
> + (let* ((left (eq which-key-show-prefix 'left))
> + (prefix-arg (if -prefix-arg -prefix-arg prefix-arg))
> + (str (concat
> + (which-key--universal-argument--description)
> + (when prefix-arg " ")
> + prefix-keys))
> + (dash (if (and (not (string= prefix-keys ""))
> + (null left)) "-" "")))
> + (if (or (eq which-key-show-prefix 'echo) dont-prop-keys)
> + (concat str dash)
> + (concat (which-key--propertize-key str)
> + (which-key--propertize dash 'face 'which-key-key-face)))))
> +
> +(defun which-key--get-popup-map ()
> + "Generate transient-map for use in the top level binding display."
> + (unless which-key--automatic-display
> + (let ((map (make-sparse-keymap)))
> + (define-key map (kbd which-key-paging-key) #'which-key-C-h-dispatch)
> + (when which-key-use-C-h-commands
> + ;; Show next page even when C-h is pressed
> + (define-key map (vector help-char) #'which-key-C-h-dispatch))
> + map)))
> +
> +(defun which-key--process-page (pages-obj)
> + "Add information to the basic list of key bindings, including
> +if applicable the current prefix, the name of the current prefix,
> +and a page count."
> + (let* ((page (car (which-key--pages-pages pages-obj)))
> + (height (which-key--pages-height pages-obj))
> + (n-pages (which-key--pages-num-pages pages-obj))
> + (page-n (car (which-key--pages-page-nums pages-obj)))
> + (prefix-desc (key-description (which-key--pages-prefix pages-obj)))
> + (prefix-title (which-key--pages-prefix-title pages-obj))
> + (full-prefix (which-key--full-prefix prefix-desc))
> + (nxt-pg-hint (which-key--next-page-hint prefix-desc))
> + ;; not used in left case
> + (status-line
> + (concat (which-key--propertize prefix-title 'face 'which-key-note-face)
> + (when (< 1 n-pages)
> + (which-key--propertize (format " (%s of %s)" page-n n-pages)
> + 'face 'which-key-note-face)))))
> + (pcase which-key-show-prefix
> + (`left
There is no need for a backtick here.
> + (let* ((page-cnt (which-key--propertize (format "%s/%s" page-n n-pages)
> + 'face 'which-key-separator-face))
> + (first-col-width (+ 2 (max (which-key--string-width full-prefix)
> + (which-key--string-width page-cnt))))
> + (prefix (format (concat "%-" (int-to-string first-col-width) "s")
> + full-prefix))
> + (page-cnt (if (> n-pages 1)
> + (format
> + (concat "%-" (int-to-string first-col-width) "s")
> + page-cnt)
> + (make-string first-col-width 32)))
> + lines first-line new-end)
> + (if (= 1 height)
> + (cons (concat prefix page) nil)
> + (setq lines (split-string page "\n")
> + first-line (concat prefix (car lines) "\n" page-cnt)
> + new-end (concat "\n" (make-string first-col-width 32)))
> + (cons
> + (concat first-line (mapconcat #'identity (cdr lines) new-end))
> + nil))))
> + (`top
> + (cons
> + (concat (when (or (= 0 echo-keystrokes)
> + (not (eq which-key-side-window-location 'bottom)))
> + (concat full-prefix " "))
> + status-line " " nxt-pg-hint "\n" page)
> + nil))
> + (`bottom
> + (cons
> + (concat page "\n"
> + (when (or (= 0 echo-keystrokes)
> + (not (eq which-key-side-window-location 'bottom)))
> + (concat full-prefix " "))
> + status-line " " nxt-pg-hint)
> + nil))
> + (`echo
> + (cons page
> + (lambda ()
> + (which-key--echo
> + (concat full-prefix (when prefix-desc " ")
> + status-line (when status-line " ")
> + nxt-pg-hint)))))
> + (`mode-line
> + (cons page
> + (lambda ()
> + (with-current-buffer which-key--buffer
> + (setq-local mode-line-format
> + (concat " " full-prefix
> + " " status-line
> + " " nxt-pg-hint))))))
> + (_ (cons page nil)))))
> +
> +(defun which-key--show-page (&optional n)
> + "Show current page.
> +N changes the current page to the Nth page relative to the
> +current one."
> + (which-key--init-buffer) ;; in case it was killed
> + (let ((prefix-keys (which-key--current-key-string))
> + golden-ratio-mode)
What is this?
> + (if (null which-key--pages-obj)
> + (message "%s- which-key can't show keys: There is not \
> +enough space based on your settings and frame size." prefix-keys)
> + (when n
> + (setq which-key--pages-obj
> + (which-key--pages-set-current-page which-key--pages-obj n)))
> + (let ((page-echo (which-key--process-page which-key--pages-obj))
> + (height (which-key--pages-height which-key--pages-obj))
> + (width (car (which-key--pages-widths which-key--pages-obj))))
> + (which-key--lighter-status)
> + (if (eq which-key-popup-type 'minibuffer)
> + (which-key--echo (car page-echo))
> + (with-current-buffer which-key--buffer
> + (erase-buffer)
> + (insert (car page-echo))
> + (goto-char (point-min)))
> + (when (cdr page-echo) (funcall (cdr page-echo)))
> + (which-key--show-popup (cons height width)))))
> + ;; used for paging at top-level
> + (if (fboundp 'set-transient-map)
> + (set-transient-map (which-key--get-popup-map))
> + (with-no-warnings
If you disable warnings, you should explain why you are doing that.
> + (set-temporary-overlay-map (which-key--get-popup-map))))))
> +
> +;;; Paging functions
> +
> +;;;###autoload
> +(defun which-key-reload-key-sequence (&optional key-seq)
> + "Simulate entering the key sequence KEY-SEQ.
> +KEY-SEQ should be a list of events as produced by
> +`listify-key-sequence'. If nil, KEY-SEQ defaults to
> +`which-key--current-key-list'. Any prefix arguments that were
> +used are reapplied to the new key sequence."
> + (let* ((key-seq (or key-seq (which-key--current-key-list)))
> + (next-event (mapcar (lambda (ev) (cons t ev)) key-seq)))
> + (setq prefix-arg current-prefix-arg
> + unread-command-events next-event)))
> +
> +(defun which-key-turn-page (delta)
> + "Show the next page of keys."
> + (which-key-reload-key-sequence)
> + (if which-key--last-try-2-loc
> + (let ((which-key-side-window-location which-key--last-try-2-loc)
> + (which-key--multiple-locations t))
> + (which-key--show-page delta))
> + (which-key--show-page delta))
> + (which-key--start-paging-timer))
> +
> +;;;###autoload
> +(defun which-key-show-standard-help (&optional _)
> + "Call the command in `which-key--prefix-help-cmd-backup'.
> +Usually this is `describe-prefix-bindings'."
> + (interactive)
> + (let ((which-key-inhibit t)
> + (popup-showing (which-key--popup-showing-p)))
> + (which-key--hide-popup-ignore-command)
> + (cond ((and (eq which-key--prefix-help-cmd-backup
> + 'describe-prefix-bindings)
> + ;; If the popup is not showing, we call
> + ;; `describe-prefix-bindings' directly.
> + popup-showing)
> + ;; This is essentially what `describe-prefix-bindings' does. We can't
> + ;; use this function directly, because the prefix will not be correct
> + ;; when we enter using `which-key-C-h-dispatch'.
> + (describe-bindings (kbd (which-key--current-key-string))))
> + ((functionp which-key--prefix-help-cmd-backup)
> + (funcall which-key--prefix-help-cmd-backup)))))
> +
> +;;;###autoload
> +(defun which-key-show-next-page-no-cycle ()
> + "Show next page of keys unless on the last page, in which case
> +call `which-key-show-standard-help'."
> + (interactive)
> + (let ((which-key-inhibit t))
> + (if (which-key--on-last-page)
> + (which-key-show-standard-help)
> + (which-key-turn-page 1))))
> +
> +;;;###autoload
> +(defun which-key-show-previous-page-no-cycle ()
> + "Show previous page of keys unless on the first page, in which
> +case do nothing."
> + (interactive)
> + (let ((which-key-inhibit t))
> + (unless (which-key--on-first-page)
> + (which-key-turn-page -1))))
> +
> +;;;###autoload
> +(defun which-key-show-next-page-cycle (&optional _)
> + "Show the next page of keys, cycling from end to beginning
> +after last page."
> + (interactive)
> + (let ((which-key-inhibit t))
> + (which-key-turn-page 1)))
> +
> +;;;###autoload
> +(defun which-key-show-previous-page-cycle (&optional _)
> + "Show the previous page of keys, cycling from beginning to end
> +after first page."
> + (interactive)
> + (let ((which-key-inhibit t))
> + (which-key-turn-page -1)))
> +
> +;;;###autoload
> +(defun which-key-show-top-level (&optional _)
> + "Show top-level bindings."
> + (interactive)
> + (which-key--create-buffer-and-show nil nil nil "Top-level bindings"))
> +
> +;;;###autoload
> +(defun which-key-show-major-mode (&optional all)
> + "Show top-level bindings in the map of the current major mode.
> +
> +This function will also detect evil bindings made using
> +`evil-define-key' in this map. These bindings will depend on the
> +current evil state. "
> + (interactive "P")
> + (let ((map-sym (intern (format "%s-map" major-mode))))
> + (if (and (boundp map-sym) (keymapp (symbol-value map-sym)))
> + (which-key--show-keymap
> + "Major-mode bindings"
> + (symbol-value map-sym)
> + (apply-partially #'which-key--map-binding-p (symbol-value map-sym))
> + all)
> + (message "which-key: No map named %s" map-sym))))
> +
> +;;;###autoload
> +(defun which-key-show-full-major-mode ()
> + "Show all bindings in the map of the current major mode.
> +
> +This function will also detect evil bindings made using
> +`evil-define-key' in this map. These bindings will depend on the
> +current evil state. "
> + (interactive)
> + (which-key-show-major-mode t))
> +
> +;;;###autoload
> +(defun which-key-dump-bindings (prefix buffer-name)
> + "Dump bindings from PREFIX into buffer named BUFFER-NAME.
> +
> +PREFIX should be a string suitable for `kbd'."
> + (interactive "sPrefix: \nB")
> + (let* ((buffer (get-buffer-create buffer-name))
> + (keys (which-key--get-bindings (kbd prefix))))
> + (with-current-buffer buffer
> + (point-max)
> + (save-excursion
> + (dolist (key keys)
> + (insert (apply #'format "%s%s%s\n" key)))))
> + (switch-to-buffer-other-window buffer)))
> +
> +;;;###autoload
> +(defun which-key-undo-key (&optional _)
> + "Undo last keypress and force which-key update."
> + (interactive)
> + (let* ((key-lst (butlast (which-key--current-key-list)))
> + (which-key-inhibit t))
> + (cond (which-key--prior-show-keymap-args
> + (if (keymapp (cdr (car-safe which-key--prior-show-keymap-args)))
> + (let ((args (pop which-key--prior-show-keymap-args)))
> + (which-key--show-keymap (car args) (cdr args)))
> + (which-key--hide-popup)))
> + (key-lst
> + (which-key-reload-key-sequence key-lst)
> + (which-key--create-buffer-and-show (apply #'vector key-lst)))
> + (t (setq which-key--automatic-display nil)
> + (which-key-show-top-level)))))
> +(defalias 'which-key-undo #'which-key-undo-key)
> +
> +(defun which-key-abort (&optional _)
> + "Abort key sequence."
> + (interactive)
> + (let ((which-key-inhibit t))
> + (which-key--hide-popup-ignore-command)
> + (keyboard-quit)))
> +
> +(defun which-key-digit-argument (key)
> + "Version of `digit-argument' for use in `which-key-C-h-map'."
> + (interactive)
> + (let ((last-command-event (string-to-char key)))
> + (digit-argument key))
> + (let ((current-prefix-arg prefix-arg))
> + (which-key-reload-key-sequence)))
> +
> +(defun which-key-toggle-docstrings (&optional _)
> + "Toggle the display of docstrings."
> + (interactive)
> + (unless (eq which-key-show-docstrings 'docstring-only)
> + (setq which-key-show-docstrings (null which-key-show-docstrings)))
> + (which-key-reload-key-sequence)
> + (which-key--create-buffer-and-show (which-key--current-prefix)))
> +
> +;;;###autoload
> +(defun which-key-C-h-dispatch ()
> + "Dispatch C-h commands by looking up key in
> +`which-key-C-h-map'. This command is always accessible (from any
> +prefix) if `which-key-use-C-h-commands' is non nil."
> + (interactive)
> + (cond ((and (not (which-key--popup-showing-p))
> + which-key-show-early-on-C-h)
> + (let ((current-prefix
> + (butlast
> + (listify-key-sequence (which-key--this-command-keys)))))
> + (which-key-reload-key-sequence current-prefix)
> + (if which-key-idle-secondary-delay
> + (which-key--start-timer which-key-idle-secondary-delay t)
> + (which-key--start-timer 0.05 t))))
> + ((not (which-key--popup-showing-p))
> + (which-key-show-standard-help))
> + (t
> + (if (not (which-key--popup-showing-p))
> + (which-key-show-standard-help)
> + (let* ((prefix-keys (which-key--current-key-string))
> + (full-prefix (which-key--full-prefix prefix-keys current-prefix-arg t))
> + (prompt (concat (when (string-equal prefix-keys "")
> + (which-key--propertize
> + (concat " "
> + (which-key--pages-prefix-title
> + which-key--pages-obj))
> + 'face 'which-key-note-face))
> + full-prefix
> + (which-key--propertize
> + (substitute-command-keys
> + which-key-C-h-map-prompt)
> + 'face 'which-key-note-face)))
> + (key (let ((key (read-key prompt)))
> + (if (numberp key)
> + (string key)
> + (vector key))))
> + (cmd (lookup-key which-key-C-h-map key))
> + (which-key-inhibit t))
> + (if cmd (funcall cmd key) (which-key-turn-page 0)))))))
> +
> +;;; Update
> +
> +(defun which-key--any-match-p (regexps string)
> + "Non-nil if any of REGEXPS match STRING."
> + (catch 'match
> + (dolist (regexp regexps)
> + (when (string-match-p regexp string)
> + (throw 'match t)))))
You should be able to check this with a
(string-match-p
(string-join regexps "\\|")
string)
> +
> +(defun which-key--try-2-side-windows
> + (bindings prefix-keys prefix-title loc1 loc2 &rest _ignore)
> + "Try to show BINDINGS (PAGE-N) in LOC1 first.
> +
> +Only if no bindings fit fallback to LOC2."
> + (let (pages1)
> + (let ((which-key-side-window-location loc1)
> + (which-key--multiple-locations t))
> + (setq pages1 (which-key--create-pages
> + bindings prefix-keys prefix-title)))
> + (if pages1
> + (progn
> + (setq which-key--pages-obj pages1)
> + (let ((which-key-side-window-location loc1)
> + (which-key--multiple-locations t))
> + (which-key--show-page))
> + loc1)
> + (let ((which-key-side-window-location loc2)
> + (which-key--multiple-locations t))
> + (setq which-key--pages-obj
> + (which-key--create-pages bindings prefix-keys prefix-title))
> + (which-key--show-page)
> + loc2))))
> +
> +(defun which-key--read-keymap ()
> + "Read keymap symbol from minibuffer."
> + (intern
> + (completing-read "Keymap: " obarray
> + (lambda (m)
> + (and (boundp m)
> + (keymapp (symbol-value m))
> + (not (equal (symbol-value m)
> + (make-sparse-keymap)))))
> + t
> + (let ((sym (symbol-at-point)))
> + (and (boundp sym)
> + (keymapp (symbol-value sym))
> + (symbol-name sym)))
> + 'which-key-keymap-history)))
> +
> +;;;###autoload
> +(defun which-key-show-keymap (keymap &optional no-paging)
> + "Show the top-level bindings in KEYMAP using which-key.
> +KEYMAP is selected interactively from all available keymaps.
> +
> +If NO-PAGING is non-nil, which-key will not intercept subsequent
> +keypresses for the paging functionality."
> + (interactive (list (which-key--read-keymap)))
> + (which-key--show-keymap (symbol-name keymap)
> + (symbol-value keymap)
> + nil nil no-paging))
> +
> +;;;###autoload
> +(defun which-key-show-full-keymap (keymap)
> + "Show all bindings in KEYMAP using which-key.
> +KEYMAP is selected interactively from all available keymaps."
> + (interactive (list (which-key--read-keymap)))
> + (which-key--show-keymap (symbol-name keymap)
> + (symbol-value keymap)
> + nil t))
> +
> +;;;###autoload
> +(defun which-key-show-minor-mode-keymap (&optional all)
> + "Show the top-level bindings in KEYMAP using which-key.
> +KEYMAP is selected interactively by mode in
> +`minor-mode-map-alist'."
> + (interactive)
> + (let ((mode-sym
> + (intern
> + (completing-read
> + "Minor Mode: "
> + (mapcar #'car
> + (cl-remove-if-not
> + (lambda (entry)
> + (and (symbol-value (car entry))
> + (not (equal (cdr entry) (make-sparse-keymap)))))
> + minor-mode-map-alist))
> + nil t nil 'which-key-keymap-history))))
> + (which-key--show-keymap (symbol-name mode-sym)
> + (cdr (assq mode-sym minor-mode-map-alist))
> + all)))
> +;;;###autoload
> +(defun which-key-show-full-minor-mode-keymap ()
> + "Show all bindings in KEYMAP using which-key.
> +KEYMAP is selected interactively by mode in
> +`minor-mode-map-alist'."
> + (interactive)
> + (which-key-show-minor-mode-keymap t))
> +
> +(defun which-key--show-keymap
> + (keymap-name keymap &optional prior-args all no-paging filter)
> + (when prior-args (push prior-args which-key--prior-show-keymap-args))
> + (let ((bindings (which-key--get-bindings nil keymap filter all)))
> + (if (= (length bindings) 0)
Prefer (null bindings).
> + (message "which-key: No bindings found in %s" keymap-name)
> + (cond ((listp which-key-side-window-location)
> + (setq which-key--last-try-2-loc
> + (apply #'which-key--try-2-side-windows
> + bindings nil keymap-name
> + which-key-side-window-location)))
> + (t (setq which-key--pages-obj
> + (which-key--create-pages bindings nil keymap-name))
> + (which-key--show-page)))
> + (unless no-paging
> + (let* ((key (read-key))
> + (key-desc (key-description (list key)))
> + (next-def (lookup-key keymap (vector key))))
> + (cond ((and which-key-use-C-h-commands
> + (numberp key) (= key help-char))
> + (which-key-C-h-dispatch))
> + ((keymapp next-def)
> + (which-key--hide-popup-ignore-command)
> + (which-key--show-keymap
> + (concat keymap-name " " key-desc)
> + next-def
> + (cons keymap-name keymap)))
> + (t (which-key--hide-popup))))))))
> +
> +(defun which-key--evil-operator-filter (binding)
> + (let ((def (intern (cdr binding))))
> + (and (functionp def)
> + (not (evil-get-command-property def :suppress-operator)))))
> +
> +(defun which-key--show-evil-operator-keymap ()
> + (if which-key--inhibit-next-operator-popup
> + (setq which-key--inhibit-next-operator-popup nil)
> + (let ((keymap
> + (make-composed-keymap (list evil-operator-shortcut-map
> + evil-operator-state-map
> + evil-motion-state-map))))
> + (when (keymapp keymap)
> + (let ((formatted-keys
> + (which-key--get-bindings
> + nil keymap #'which-key--evil-operator-filter)))
> + (cond ((= (length formatted-keys) 0)
> + (message "which-key: Keymap empty"))
> + ((listp which-key-side-window-location)
> + (setq which-key--last-try-2-loc
> + (apply #'which-key--try-2-side-windows
> + formatted-keys nil "evil operator/motion keys"
> + which-key-side-window-location)))
> + (t (setq which-key--pages-obj
> + (which-key--create-pages
> + formatted-keys
> + nil "evil operator/motion keys"))
> + (which-key--show-page)))))
> + (let* ((key (read-key)))
> + (when (member key '(?f ?F ?t ?T ?`))
> + ;; these keys trigger commands that read the next char manually
> + (setq which-key--inhibit-next-operator-popup t))
> + (cond ((and which-key-use-C-h-commands (numberp key) (= key help-char))
> + (which-key-C-h-dispatch))
> + ((and (numberp key) (= key ?\C-\[))
> + (which-key--hide-popup)
> + (keyboard-quit))
> + (t
> + (which-key--hide-popup)
> + (setq unread-command-events (vector key))))))))
> +
> +(defun which-key--create-buffer-and-show
> + (&optional prefix-keys from-keymap filter prefix-title)
> + "Fill `which-key--buffer' with key descriptions and reformat.
> +Finally, show the buffer."
> + (let ((start-time (current-time))
> + (formatted-keys (which-key--get-bindings
> + prefix-keys from-keymap filter))
> + (prefix-desc (key-description prefix-keys)))
> + (cond ((= (length formatted-keys) 0)
> + (message "%s- which-key: There are no keys to show" prefix-desc))
> + ((listp which-key-side-window-location)
> + (setq which-key--last-try-2-loc
> + (apply #'which-key--try-2-side-windows
> + formatted-keys prefix-keys prefix-title
> + which-key-side-window-location)))
> + (t (setq which-key--pages-obj
> + (which-key--create-pages
> + formatted-keys prefix-keys prefix-title))
> + (which-key--show-page)))
> + (which-key--debug-message
> + "On prefix \"%s\" which-key took %.0f ms." prefix-desc
> + (* 1000 (float-time (time-since start-time))))))
> +
> +(defun which-key--this-command-keys ()
> + "Version of `this-single-command-keys' corrected for key-chords and god-mode."
> + (let ((this-command-keys (this-single-command-keys)))
> + (when (and (vectorp this-command-keys)
> + (> (length this-command-keys) 0)
> + (eq (aref this-command-keys 0) 'key-chord)
> + (bound-and-true-p key-chord-mode))
> + (setq this-command-keys (this-single-command-raw-keys)))
> + (when (and which-key--god-mode-support-enabled
> + (bound-and-true-p god-local-mode)
> + (eq this-command 'god-mode-self-insert))
> + (setq this-command-keys (when which-key--god-mode-key-string
> + (kbd which-key--god-mode-key-string))))
> + this-command-keys))
> +
> +(defun which-key--update ()
> + "Function run by timer to possibly trigger
> +`which-key--create-buffer-and-show'."
> + (let ((prefix-keys (which-key--this-command-keys))
> + delay-time)
> + (cond ((and (> (length prefix-keys) 0)
> + (or (keymapp (key-binding prefix-keys))
> + ;; Some keymaps are stored here like iso-transl-ctl-x-8-map
> + (keymapp (which-key--safe-lookup-key
> + key-translation-map prefix-keys))
> + ;; just in case someone uses one of these
> + (keymapp (which-key--safe-lookup-key
> + function-key-map prefix-keys)))
> + (not which-key-inhibit)
> + (or (null which-key-allow-regexps)
> + (which-key--any-match-p
> + which-key-allow-regexps (key-description prefix-keys)))
> + (or (null which-key-inhibit-regexps)
> + (not
> + (which-key--any-match-p
> + which-key-inhibit-regexps (key-description prefix-keys))))
> + ;; Do not display the popup if a command is currently being
> + ;; executed
> + (or (and which-key-allow-evil-operators
> + (bound-and-true-p evil-this-operator))
> + (and which-key--god-mode-support-enabled
> + (bound-and-true-p god-local-mode)
> + (eq this-command 'god-mode-self-insert))
> + (null this-command))
> + (let ((max-dim (which-key--popup-max-dimensions)))
> + (> (min (car-safe max-dim) (cdr-safe max-dim)) 0)))
> + (when (and (not (equal prefix-keys (which-key--current-prefix)))
> + (or (null which-key-delay-functions)
> + (null (setq delay-time
> + (run-hook-with-args-until-success
> + 'which-key-delay-functions
> + (key-description prefix-keys)
> + (length prefix-keys))))
> + (sit-for delay-time)))
> + (setq which-key--automatic-display t)
> + (which-key--create-buffer-and-show prefix-keys)
> + (when (and which-key-idle-secondary-delay
> + (not which-key--secondary-timer-active))
> + (which-key--start-timer which-key-idle-secondary-delay t))))
> + ((and which-key-show-transient-maps
> + ;; Assuming that if this is not true we're in
> + ;; `which-key-show-top-level', which would then be overwritten.
> + (> (length prefix-keys) 0)
> + (keymapp overriding-terminal-local-map)
> + ;; basic test for it being a hydra
> + (not (eq (lookup-key overriding-terminal-local-map "\C-u")
> + 'hydra--universal-argument)))
> + (which-key--create-buffer-and-show
> + nil overriding-terminal-local-map))
> + ((and which-key-show-operator-state-maps
> + (bound-and-true-p evil-state)
> + (eq evil-state 'operator)
> + (not (which-key--popup-showing-p)))
> + (which-key--show-evil-operator-keymap))
> + (which-key--automatic-display
> + (which-key--hide-popup)))))
> +
> +;;; Timers
> +
> +(defun which-key--start-timer (&optional delay secondary)
> + "Activate idle timer to trigger `which-key--update'."
> + (which-key--stop-timer)
> + (setq which-key--secondary-timer-active secondary)
> + (setq which-key--timer
> + (run-with-idle-timer (or delay which-key-idle-delay)
> + t #'which-key--update)))
> +
> +(defun which-key--stop-timer ()
> + "Deactivate idle timer for `which-key--update'."
> + (when which-key--timer (cancel-timer which-key--timer)))
> +
> +(defun which-key--start-paging-timer ()
> + "Activate timer to restart which-key after paging."
> + (when which-key--paging-timer (cancel-timer which-key--paging-timer))
> + (which-key--stop-timer)
> + (setq which-key--paging-timer
> + (run-with-idle-timer
> + 0.2 t (lambda ()
> + (when (or (not (member real-last-command
> + which-key--paging-functions))
> + (and (< 0 (length (this-single-command-keys)))
> + (not (equal (which-key--current-prefix)
> + (which-key--this-command-keys)))))
> + (cancel-timer which-key--paging-timer)
> + (if which-key-idle-secondary-delay
> + ;; we haven't executed a command yet so the secandary
> + ;; timer is more relevant here
> + (which-key--start-timer which-key-idle-secondary-delay t)
> + (which-key--start-timer)))))))
> +
> +(provide 'which-key)
> +;;; which-key.el ends here
My genera feeling is that the code is reinventing the wheel at a number
of places, which might make it more complicated to maintain in the long
term. Looking for ways to slim down the codebase, perhaps by
deprecating some options, dropping support for third-party packages and
reusing existing functionality seems like something one should look into.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-07 8:20 ` Philip Kaludercic
@ 2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:03 ` Eli Zaretskii
2024-02-23 23:07 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-07 21:48 UTC (permalink / raw)
To: Philip Kaludercic; +Cc: 68929, monnier, justin
Philip Kaludercic <philipk@posteo.net> writes:
> My genera feeling is that the code is reinventing the wheel at a number
> of places, which might make it more complicated to maintain in the long
> term. Looking for ways to slim down the codebase, perhaps by
> deprecating some options, dropping support for third-party packages and
> reusing existing functionality seems like something one should look into.
Should these improvements be made before moving which-key to core?
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-06 2:51 ` Justin Burkett
@ 2024-02-07 21:53 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:09 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-07 21:53 UTC (permalink / raw)
To: Justin Burkett; +Cc: Eli Zaretskii, 68929, monnier
Justin Burkett <justin@burkett.cc> writes:
> Thanks for the comments. I'll work on these.
>
> On Mon, Feb 5, 2024 at 7:32 AM Eli Zaretskii <eliz@gnu.org> wrote:
>>
>> > Date: Sun, 04 Feb 2024 22:02:50 +0000
>> > From: Jeremy Bryant via "Bug reports for GNU Emacs,
>> > the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> >
>> > This patch brings the latest version of which-key from GNU ELPA into
>> > Emacs core
>> >
>> > If suitable I will then work on the updates to user-facing aspects such as
>> > manual and NEWS.
Is there a natural place in the Emacs manual (Perhaps "Other Help
Commands"?) to add a new section on M-x which-key? WDYT?
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-05 12:32 ` Eli Zaretskii
2024-02-06 2:51 ` Justin Burkett
@ 2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:16 ` Eli Zaretskii
1 sibling, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-07 22:01 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 68929, monnier, justin
Eli Zaretskii <eliz@gnu.org> writes:
> Two spaces between sentences in comments and doc strings, here and
> elsewhere.
OK. Related point - This is not in the Elisp manual "Tips for
documentation strings", is it worth a patch for this?
(although this is flagged by M-x checkdoc)
>
> Please add a :version tag to all defcustom's and defface's.
I cannot locate this in the elisp manual, Appendix D "Tips and
conventions", or in the defcustom and defface sections, should this be
documented and how?
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-08 6:03 ` Eli Zaretskii
2024-03-01 23:08 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-08 6:03 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: philipk, 68929, monnier, justin
> Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
> Date: Wed, 07 Feb 2024 21:48:00 +0000
> From: Jeremy Bryant via "Bug reports for GNU Emacs,
> the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
> > My genera feeling is that the code is reinventing the wheel at a number
> > of places, which might make it more complicated to maintain in the long
> > term. Looking for ways to slim down the codebase, perhaps by
> > deprecating some options, dropping support for third-party packages and
> > reusing existing functionality seems like something one should look into.
>
> Should these improvements be made before moving which-key to core?
Preferably, yes.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-07 21:53 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-08 6:09 ` Eli Zaretskii
2024-02-08 22:25 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-08 6:09 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, justin, monnier
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org,
> monnier@iro.umontreal.ca
> Date: Wed, 07 Feb 2024 21:53:55 +0000
>
> Is there a natural place in the Emacs manual (Perhaps "Other Help
> Commands"?) to add a new section on M-x which-key? WDYT?
Will the section be very long? How long?
If it's not very long, I think the right place is in "Key Help",
perhaps as a separate subsection below it. Also, I think which-key
should be briefly mentioned in "Display Custom", where echo-keystrokes
is described.
If the section about which-key you envision is supposed to be long and
detailed, perhaps it would be better to have a separate manual with
all that stuff, whereas the Emacs user manual should have only a short
description of the main features, and a cross-reference to the
separate manual.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-08 6:16 ` Eli Zaretskii
2024-02-08 15:42 ` Justin Burkett
2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 2 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-08 6:16 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, monnier, justin
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
> Date: Wed, 07 Feb 2024 22:01:05 +0000
>
>
> Eli Zaretskii <eliz@gnu.org> writes:
> > Two spaces between sentences in comments and doc strings, here and
> > elsewhere.
>
> OK. Related point - This is not in the Elisp manual "Tips for
> documentation strings", is it worth a patch for this?
That section is not specific to the Emacs development. Our
conventions, which are specific to the Emacs development project, are
in CONTRIBUTE.
> > Please add a :version tag to all defcustom's and defface's.
>
> I cannot locate this in the elisp manual, Appendix D "Tips and
> conventions", or in the defcustom and defface sections, should this be
> documented and how?
It's already documented in CONTRIBUTE. Again, other Lisp programs out
there are free not to follow these guidelines (and, in fact, :version
might not have any useful effect in 3rd party packages), it is our own
convention whose purpose is to help "M-x customize-changed" do its job
well.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 6:16 ` Eli Zaretskii
@ 2024-02-08 15:42 ` Justin Burkett
2024-02-08 16:10 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 86+ messages in thread
From: Justin Burkett @ 2024-02-08 15:42 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Jeremy Bryant, 68929, monnier
Hi all,
I appreciate the feedback. I have no doubt there are improvements to
be made. To the extent that I reinvented the wheel, it was because I
wasn't aware that particular wheel existed at the time. When I get
time, I will work on the things that have been mentioned here. I do
have a few questions and comments:
1. I think replacing third-party support with hooks that will allow
whatever package to insert code where needed is a good idea, although
some of these packages (like evil) have some pretty idiosyncratic
needs if I remember correctly.
2. I would like to depend as much as possible on built-in functions,
but I am probably unaware of all of the possibilities here, so any
suggestions would be appreciated. There might also be libraries in
emacs that have been written/improved since I wrote many of these
functions.
3. There were some oddities that we ran into early on around computing
the width of unicode characters that I did not fully understand, which
is why there are some clunky options for those. The main issue was
some characters came out wider than anticipated, breaking the width
calculations for the table shown by which-key. I would be happy to
improve those with guidance.
4. I never really liked the timer mechanism either, but I didn't find
an alternative to detecting when emacs was in the middle of reading a
key sequence. I like the idea of which-key as simply being a different
describe-prefix-bindings function, but my sense is that novices
appreciate the automatic popup. I'm wondering if anyone has any other
ideas. In principle, one could have a hook that emacs uses to notify
which-key that emacs is waiting on a key sequence, but maybe that is
overkill.
Thanks,
Justin
On Thu, Feb 8, 2024 at 1:16 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Jeremy Bryant <jb@jeremybryant.net>
> > Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
> > Date: Wed, 07 Feb 2024 22:01:05 +0000
> >
> >
> > Eli Zaretskii <eliz@gnu.org> writes:
> > > Two spaces between sentences in comments and doc strings, here and
> > > elsewhere.
> >
> > OK. Related point - This is not in the Elisp manual "Tips for
> > documentation strings", is it worth a patch for this?
>
> That section is not specific to the Emacs development. Our
> conventions, which are specific to the Emacs development project, are
> in CONTRIBUTE.
>
> > > Please add a :version tag to all defcustom's and defface's.
> >
> > I cannot locate this in the elisp manual, Appendix D "Tips and
> > conventions", or in the defcustom and defface sections, should this be
> > documented and how?
>
> It's already documented in CONTRIBUTE. Again, other Lisp programs out
> there are free not to follow these guidelines (and, in fact, :version
> might not have any useful effect in 3rd party packages), it is our own
> convention whose purpose is to help "M-x customize-changed" do its job
> well.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 15:42 ` Justin Burkett
@ 2024-02-08 16:10 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 16:54 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-08 16:10 UTC (permalink / raw)
To: Justin Burkett; +Cc: Eli Zaretskii, 68929, Jeremy Bryant
> 1. I think replacing third-party support with hooks that will allow
> whatever package to insert code where needed is a good idea, although
> some of these packages (like evil) have some pretty idiosyncratic
> needs if I remember correctly.
Indeed, resolving such issues can be non-trivial (especially when they
require synchronization with other packages).
Often we end up doing it in two steps: first introduce the hook (making
sure that it is flexible enough that it can cover our needs and those
of other packages), then later remove the ad-hoc third-party support.
> 3. There were some oddities that we ran into early on around computing
> the width of unicode characters that I did not fully understand, which
> is why there are some clunky options for those. The main issue was
> some characters came out wider than anticipated, breaking the width
> calculations for the table shown by which-key. I would be happy to
> improve those with guidance.
For monospace fonts, `string-width` *should* give you the information
you need.
> 4. I never really liked the timer mechanism either, but I didn't find
> an alternative to detecting when emacs was in the middle of reading a
> key sequence. I like the idea of which-key as simply being a different
> describe-prefix-bindings function, but my sense is that novices
> appreciate the automatic popup. I'm wondering if anyone has any other
> ideas. In principle, one could have a hook that emacs uses to notify
> which-key that emacs is waiting on a key sequence, but maybe that is
> overkill.
I don't have a strong opinion about the use of a timer.
But maybe we could hook into the `echo-keystrokes` mechanism (and thus
reuse its timer, which also defaults to 1s).
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 16:10 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-08 16:54 ` Eli Zaretskii
0 siblings, 0 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-08 16:54 UTC (permalink / raw)
To: Stefan Monnier; +Cc: jb, 68929, justin
> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>, Jeremy Bryant <jb@jeremybryant.net>,
> 68929@debbugs.gnu.org
> Date: Thu, 08 Feb 2024 11:10:44 -0500
>
> > 4. I never really liked the timer mechanism either, but I didn't find
> > an alternative to detecting when emacs was in the middle of reading a
> > key sequence. I like the idea of which-key as simply being a different
> > describe-prefix-bindings function, but my sense is that novices
> > appreciate the automatic popup. I'm wondering if anyone has any other
> > ideas. In principle, one could have a hook that emacs uses to notify
> > which-key that emacs is waiting on a key sequence, but maybe that is
> > overkill.
>
> I don't have a strong opinion about the use of a timer.
> But maybe we could hook into the `echo-keystrokes` mechanism (and thus
> reuse its timer, which also defaults to 1s).
Yes, that'd be the first possibility I'd recommend to explore.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 6:09 ` Eli Zaretskii
@ 2024-02-08 22:25 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-11 21:32 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-08 22:25 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 68929, justin, monnier
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org,
>> monnier@iro.umontreal.ca
>> Date: Wed, 07 Feb 2024 21:53:55 +0000
>>
>> Is there a natural place in the Emacs manual (Perhaps "Other Help
>> Commands"?) to add a new section on M-x which-key? WDYT?
>
> Will the section be very long? How long?
>
> If it's not very long, I think the right place is in "Key Help",
> perhaps as a separate subsection below it. Also, I think which-key
> should be briefly mentioned in "Display Custom", where echo-keystrokes
> is described.
>
> If the section about which-key you envision is supposed to be long and
> detailed, perhaps it would be better to have a separate manual with
> all that stuff, whereas the Emacs user manual should have only a short
> description of the main features, and a cross-reference to the
> separate manual.
I would propose to make a new section short enough to belong in the main
Emacs manual, as which-key's "keymay discovery" perspective should be
easier to find.
I can volunteer to write a draft and confer with Justin, the actual
author, for completeness.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 6:16 ` Eli Zaretskii
2024-02-08 15:42 ` Justin Burkett
@ 2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-09 6:51 ` Eli Zaretskii
1 sibling, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-08 22:27 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 68929, monnier, justin
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
>> Date: Wed, 07 Feb 2024 22:01:05 +0000
>>
>>
>> Eli Zaretskii <eliz@gnu.org> writes:
>> > Two spaces between sentences in comments and doc strings, here and
>> > elsewhere.
>>
>> OK. Related point - This is not in the Elisp manual "Tips for
>> documentation strings", is it worth a patch for this?
>
> That section is not specific to the Emacs development. Our
> conventions, which are specific to the Emacs development project, are
> in CONTRIBUTE.
I stand corrected, indeed, I was looking in the wrong place.
>> > Please add a :version tag to all defcustom's and defface's.
>>
>> I cannot locate this in the elisp manual, Appendix D "Tips and
>> conventions", or in the defcustom and defface sections, should this be
>> documented and how?
>
> It's already documented in CONTRIBUTE. Again, other Lisp programs out
> there are free not to follow these guidelines (and, in fact, :version
> might not have any useful effect in 3rd party packages), it is our own
> convention whose purpose is to help "M-x customize-changed" do its job
> well.
Understood.
Defcustom is covered below
"
New defcustom's should always have a ':version' tag stating the first
Emacs version in which they will appear. Likewise with defcustom's
whose value is changed -- update their ':version' tag.
"
Is defface conceptually close enough not to warrant an extra para?
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-09 6:51 ` Eli Zaretskii
0 siblings, 0 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-09 6:51 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, monnier, justin
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
> Date: Thu, 08 Feb 2024 22:27:58 +0000
>
> Defcustom is covered below
> "
> New defcustom's should always have a ':version' tag stating the first
> Emacs version in which they will appear. Likewise with defcustom's
> whose value is changed -- update their ':version' tag.
> "
>
> Is defface conceptually close enough not to warrant an extra para?
No, it's an omission, now fixed.
Thanks.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 22:25 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-11 21:32 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-15 8:29 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-11 21:32 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: eliz, 68929, justin, monnier
[-- Attachment #1: Type: text/plain, Size: 1008 bytes --]
> Eli Zaretskii <eliz@gnu.org> writes:
>
>> Will the section be very long? How long?
>>
>> If it's not very long, I think the right place is in "Key Help",
>> perhaps as a separate subsection below it. Also, I think which-key
>> should be briefly mentioned in "Display Custom", where echo-keystrokes
>> is described.
>>
>> If the section about which-key you envision is supposed to be long and
>> detailed, perhaps it would be better to have a separate manual with
>> all that stuff, whereas the Emacs user manual should have only a short
>> description of the main features, and a cross-reference to the
>> separate manual.
>
> I would propose to make a new section short enough to belong in the main
> Emacs manual, as which-key's "keymay discovery" perspective should be
> easier to find.
>
> I can volunteer to write a draft and confer with Justin, the actual
> author, for completeness.
Attached are a proposed patch for the Emacs manual, intentionally very
short.
Feedback welcome on any aspects.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-Add-manual-entries-for-which-key.patch --]
[-- Type: text/x-diff, Size: 1634 bytes --]
From c8264398374ad6eae380ea46428092efa0ba02fc Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Sun, 11 Feb 2024 21:26:41 +0000
Subject: [PATCH 2/2] Add manual entries for which-key
* doc/emacs/display.texi (Display Custom): brief mention
* doc/emacs/help.texi (Key Help): reference node above
---
doc/emacs/display.texi | 3 ++-
doc/emacs/help.texi | 6 ++++++
2 files changed, 8 insertions(+), 1 deletion(-)
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d2557d6148e..754f9b6d048 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -2215,7 +2215,8 @@ Display Custom
default), the multi-character key sequence echo shown according to
@code{echo-keystrokes} will include a short help text about keys which
will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
-the list of commands for the prefix you already typed.
+the list of commands for the prefix you already typed. For a related
+help facility (@pxref{which-key}).
@cindex mouse pointer
@cindex hourglass pointer display
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 99a4173ac29..25bb3ccc08a 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -260,6 +260,12 @@ Key Help
@code{widget-describe} commands, that should be run with point over
the button.
+@node which-key
+@subsection which-key
+ @command{M-x which-key} is a global minor mode which helps in
+ discovering keymaps. It displays keybindings following your currently
+ entered incomplete command (prefix), in a popup.
+
@node Name Help
@section Help by Command or Variable Name
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-11 21:32 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-15 8:29 ` Eli Zaretskii
2024-02-17 13:10 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-15 8:29 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, justin, monnier
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org, justin@burkett.cc,
> monnier@iro.umontreal.ca, bug-gnu-emacs@gnu.org
> Date: Sun, 11 Feb 2024 21:32:44 +0000
>
> > Eli Zaretskii <eliz@gnu.org> writes:
> >
> >> Will the section be very long? How long?
> >>
> >> If it's not very long, I think the right place is in "Key Help",
> >> perhaps as a separate subsection below it. Also, I think which-key
> >> should be briefly mentioned in "Display Custom", where echo-keystrokes
> >> is described.
> >>
> >> If the section about which-key you envision is supposed to be long and
> >> detailed, perhaps it would be better to have a separate manual with
> >> all that stuff, whereas the Emacs user manual should have only a short
> >> description of the main features, and a cross-reference to the
> >> separate manual.
> >
> > I would propose to make a new section short enough to belong in the main
> > Emacs manual, as which-key's "keymay discovery" perspective should be
> > easier to find.
> >
> > I can volunteer to write a draft and confer with Justin, the actual
> > author, for completeness.
>
> Attached are a proposed patch for the Emacs manual, intentionally very
> short.
> Feedback welcome on any aspects.
LGTM, thanks. Some minor comments below.
> * doc/emacs/display.texi (Display Custom): brief mention
> * doc/emacs/help.texi (Key Help): reference node above
The descriptions of the changes in these entries should be complete
sentences: begin with a capital letter and end with a period.
> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -2215,7 +2215,8 @@ Display Custom
> default), the multi-character key sequence echo shown according to
> @code{echo-keystrokes} will include a short help text about keys which
> will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
> -the list of commands for the prefix you already typed.
> +the list of commands for the prefix you already typed. For a related
> +help facility (@pxref{which-key}).
The parentheses here don't look right. It is better to say
For a related help facility, see @ref{which-key}.
> +@node which-key
It is better to use
@anchor which-key
Then you don't need the @subsection at all.
> + @command{M-x which-key} is a global minor mode which helps in
@command is for shell commands. Here you show something the user
types, so the right markup is @kbd.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-15 8:29 ` Eli Zaretskii
@ 2024-02-17 13:10 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-17 16:58 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-17 13:10 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 68929, justin, monnier
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0003-v2-Add-manual-entries-for-which-key.patch --]
[-- Type: text/x-diff, Size: 1629 bytes --]
From eae203569f73081e82035990a5a5ac1e0beb9083 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Sun, 11 Feb 2024 21:26:41 +0000
Subject: [PATCH 3/3] Add manual entries for which-key
* doc/emacs/display.texi (Display Custom): Briefly introduce which-key.
* doc/emacs/help.texi (Key Help): Briefly mention which-key.
---
doc/emacs/display.texi | 3 ++-
doc/emacs/help.texi | 5 +++++
2 files changed, 7 insertions(+), 1 deletion(-)
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d2557d6148e..bda57d2b30e 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -2215,7 +2215,8 @@ Display Custom
default), the multi-character key sequence echo shown according to
@code{echo-keystrokes} will include a short help text about keys which
will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
-the list of commands for the prefix you already typed.
+the list of commands for the prefix you already typed. For a related
+help facility, see @ref{which-key}.
@cindex mouse pointer
@cindex hourglass pointer display
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 99a4173ac29..1a76e663657 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -260,6 +260,11 @@ Key Help
@code{widget-describe} commands, that should be run with point over
the button.
+@anchor which-key
+@kbd{M-x which-key} is a global minor mode which helps in discovering
+ keymaps. It displays keybindings following your currently entered
+ incomplete command (prefix), in a popup.
+
@node Name Help
@section Help by Command or Variable Name
--
2.42.0
[-- Attachment #2: Type: text/plain, Size: 1433 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
> LGTM, thanks. Some minor comments below.
Revised patch attached.
>> * doc/emacs/display.texi (Display Custom): brief mention
>> * doc/emacs/help.texi (Key Help): reference node above
>
> The descriptions of the changes in these entries should be complete
> sentences: begin with a capital letter and end with a period.
Corrected in patch.
Thank you for explaining, I now realise this was in CONTRIBUTE.
>
>> --- a/doc/emacs/display.texi
>> +++ b/doc/emacs/display.texi
>> @@ -2215,7 +2215,8 @@ Display Custom
>> default), the multi-character key sequence echo shown according to
>> @code{echo-keystrokes} will include a short help text about keys which
>> will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
>> -the list of commands for the prefix you already typed.
>> +the list of commands for the prefix you already typed. For a related
>> +help facility (@pxref{which-key}).
>
> The parentheses here don't look right. It is better to say
>
> For a related help facility, see @ref{which-key}.
>
>> +@node which-key
>
> It is better to use
>
> @anchor which-key
>
> Then you don't need the @subsection at all.
>
>> + @command{M-x which-key} is a global minor mode which helps in
>
> @command is for shell commands. Here you show something the user
> types, so the right markup is @kbd.
Corrected in patch.
Thanks, I have learnt more TeXinfo with this.
^ permalink raw reply related [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-17 13:10 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-17 16:58 ` Eli Zaretskii
0 siblings, 0 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-02-17 16:58 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929-done, monnier, justin
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 68929@debbugs.gnu.org, justin@burkett.cc, monnier@iro.umontreal.ca
> Date: Sat, 17 Feb 2024 13:10:51 +0000
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> > LGTM, thanks. Some minor comments below.
>
> Revised patch attached.
Thanks. (The argument of @anchor should be in braces; I fixed that.)
Installed on master, and closing the bug.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-07 8:20 ` Philip Kaludercic
2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-02-23 23:07 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 0 replies; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-02-23 23:07 UTC (permalink / raw)
To: Philip Kaludercic; +Cc: 68929, monnier, justin
Philip,
Going through your suggestions, progressing upstream.
Philip Kaludercic <philipk@posteo.net> writes:
>> +(defvar which-key--ignore-keys-regexp
>> + (eval-when-compile
>> + (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
>> + "select-window" "switch-frame" "-state"
>> + "which-key"))))
>
> regexp-opt is marked as pure, you don't need the eval-when-compile here.
>
Please clarify your request?
It would seem The manual has a similar example to the original code.
(elisp) Eval During Compile
If you have a constant that needs some calculation to produce,
‘eval-when-compile’ can do that at compile-time. For example,
(defvar my-regexp
(eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
What am I missing?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Incorporate package macrostep into Emacs or NonGNU ELPA?
[not found] ` <874jdspsqb.fsf@bernoul.li>
@ 2024-02-28 20:56 ` Jeremy Bryant via Emacs development discussions.
2024-02-28 21:16 ` Stefan Monnier
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Emacs development discussions. @ 2024-02-28 20:56 UTC (permalink / raw)
To: emacs-devel@gnu.org
Cc: j.j.oddie, Stefan Kangas, Stefan Kangas, Stefan Monnier,
Jonas Bernoulli
[-- Attachment #1: Type: text/plain, Size: 966 bytes --]
Please consider the suggestion below
What facility?
"macrostep: interactive macro-expander
macrostep is an Emacs minor mode for interactively stepping through the expansion of macros in Emacs Lisp source code. It lets you see exactly what happens at each step of the expansion process by pretty-printing the expanded forms inline in the source buffer, which is temporarily read-only while macro expansions are visible. "
Where?
Current repo:
This is currently maintained by Jonas in
https://github.com/emacsorphanage/macrostep
based on a fork of Jon Oddie's repo (original author hasn't responded in
a while) at https://github.com/joddie/macrostep
This is packaged via MELPA.
Who?
Jonas has forked and enhanced the code with contributions from Stefan K
and Stefan M in the last 2y
License?
License is GPLv3
Next steps?
I understand Jonas is supportive of a move to e.g. (eg elpa.git)
Latest package main file attached for convenience in code review
[-- Attachment #2: macrostep.el --]
[-- Type: application/emacs-lisp, Size: 48074 bytes --]
[-- Attachment #3: Type: text/plain, Size: 38 bytes --]
I can volunteer for part of the work
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-28 20:56 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Jeremy Bryant via Emacs development discussions.
@ 2024-02-28 21:16 ` Stefan Monnier
2024-02-28 23:04 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Stefan Monnier @ 2024-02-28 21:16 UTC (permalink / raw)
To: Jeremy Bryant
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli
> Please consider the suggestion below
http://elpa.nongnu.org/nongnu/macrostep.html
It's been there since 2021 :-)
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-28 21:16 ` Stefan Monnier
@ 2024-02-28 23:04 ` Jeremy Bryant
2024-02-29 20:44 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-02-28 23:04 UTC (permalink / raw)
To: Stefan Monnier
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Please consider the suggestion below
>
> http://elpa.nongnu.org/nongnu/macrostep.html
>
> It's been there since 2021 :-)
>
>
> Stefan
Thanks Stefan, my fault for not double checking - no excuse!
Which brings us to the other point suggested by Jonas - moving
development & maintenance of macrostep to NonGNU ELPA (on Savannah) itself and
archiving the previous fork.
Would this be of interest?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-28 23:04 ` Jeremy Bryant
@ 2024-02-29 20:44 ` Jeremy Bryant
2024-03-01 4:15 ` Adam Porter
` (2 more replies)
0 siblings, 3 replies; 86+ messages in thread
From: Jeremy Bryant @ 2024-02-29 20:44 UTC (permalink / raw)
To: Stefan Monnier
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli, Eli Zaretskii
Jeremy Bryant <jb@jeremybryant.net> writes:
>
> Which brings us to the other point suggested by Jonas - moving
> development & maintenance of macrostep to NonGNU ELPA (on Savannah) itself and
> archiving the previous fork.
>
> Would this be of interest?
Jonathan Oddie has kindly proposed to sign the FSF paperwork once he
receives it.
Given that macrostep is useful for Emacs Lisp macro development, would
there be interest to include in Emacs core?
If so I can volunteer to reach out to other recent contributors, beyond
the original author, for the same purpose?
WDYT?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-29 20:44 ` Jeremy Bryant
@ 2024-03-01 4:15 ` Adam Porter
2024-03-01 23:26 ` Stefan Monnier
2024-03-02 6:51 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Eli Zaretskii
2 siblings, 0 replies; 86+ messages in thread
From: Adam Porter @ 2024-03-01 4:15 UTC (permalink / raw)
To: jb; +Cc: eliz, emacs-devel, j.j.oddie, jonas, monnier, stefan,
stefankangas
Hi Jeremy,
> Jonathan Oddie has kindly proposed to sign the FSF paperwork once he
> receives it.
>
> Given that macrostep is useful for Emacs Lisp macro development, would
> there be interest to include in Emacs core?
>
> If so I can volunteer to reach out to other recent contributors, beyond
> the original author, for the same purpose?
>
> WDYT?
To the extent that my input matters, I would certainly be in favor of
having macrostep in core!
Thanks for working on this.
--Adam
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-02-08 6:03 ` Eli Zaretskii
@ 2024-03-01 23:08 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-03-02 9:33 ` Philip Kaludercic
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-03-01 23:08 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: philipk, 68929, monnier, justin
[-- Attachment #1: Type: text/plain, Size: 1789 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: 68929@debbugs.gnu.org, monnier@iro.umontreal.ca, justin@burkett.cc
>> Date: Wed, 07 Feb 2024 21:48:00 +0000
>> From: Jeremy Bryant via "Bug reports for GNU Emacs,
>> the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>
>>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>> > My genera feeling is that the code is reinventing the wheel at a number
>> > of places, which might make it more complicated to maintain in the long
>> > term. Looking for ways to slim down the codebase, perhaps by
>> > deprecating some options, dropping support for third-party packages and
>> > reusing existing functionality seems like something one should look into.
>>
>> Should these improvements be made before moving which-key to core?
>
> Preferably, yes.
Eli/Philip,
Here is a progress update.
For convenience please find attached a v2 version of which-key with the
improvements (in conjunction with Justin). This includes
* All improvements requested by Eli; docstrings, :verion tags,
etc.. - with the exception of the redesign point for character widths
* The vast majority of improvements requested by Philip; defcustoms
changes, docstrings, sharp-quoted elements, pure function, third party
libs, declare, memq, string-join, null-bindings etc) Missing are some
elements I'm less familiar with, such as design choices related to
deffaces.
These are currently in the form of individual patches in the upstream
git repo (thus attached only for convenience). Using the 'preserving
history' approach described by Stefan M, this could be moved to core,
thus preserving the commits thus allowing checking of contributor FSF
attribution.
If there are certain elements you feel deserve further work, all
feedback welcome.
WDYT?
[-- Attachment #2: which-key-v2.el --]
[-- Type: application/emacs-lisp, Size: 119438 bytes --]
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-29 20:44 ` Jeremy Bryant
2024-03-01 4:15 ` Adam Porter
@ 2024-03-01 23:26 ` Stefan Monnier
2024-03-02 21:50 ` Jeremy Bryant
2024-03-02 6:51 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Eli Zaretskii
2 siblings, 1 reply; 86+ messages in thread
From: Stefan Monnier @ 2024-03-01 23:26 UTC (permalink / raw)
To: Jeremy Bryant
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli, Eli Zaretskii
Hi Jeremy,
> Which brings us to the other point suggested by Jonas - moving
> development & maintenance of macrostep to NonGNU ELPA (on Savannah)
> itself and archiving the previous fork.
Not sure what you mean by "previous fork".
[ BTW, I only now notice that the "upstream" is called "emacsorphanage". ]
We can set the upstream to nil and change the headers to say that
development takes place directly in `nongnu.git`, but I'm not sure it's
really an improvement over the status quo.
> Jonathan Oddie has kindly proposed to sign the FSF paperwork once he
> receives it.
Not sure if I understand correctly. Is he already in the process of
signing the paperwork, or is he waiting for someone to send him the form
for that (in which case, I'd be happy to send it to him)?
> Given that macrostep is useful for Emacs Lisp macro development, would
> there be interest to include in Emacs core?
I don't have a strong opinion either way.
> If so I can volunteer to reach out to other recent contributors, beyond
> the original author, for the same purpose?
That would be awesome.
% git log elpa/macrostep | grep Author: | sort | uniq -c | sort -n
1 Author: Chunyang Xu <xuchunyang56@gmail.com>
1 Author: duianto <duianto@users.noreply.github.com>
1 Author: John Wiegley <johnw@newartisans.com>
1 Author: Jonathan Oddie <jonxfield@gmail.com>
1 Author: Torbjörn Norinder <torbjorn@genunix.se>
2 Author: Fice T <fice-t@protonmail.com>
2 Author: Jon Oddie <jonxfield@gmail.com>
2 Author: Luís Borges de Oliveira <lbo@siscog.pt>
2 Author: Stefan Monnier <monnier@iro.umontreal.ca>
3 Author: George Kettleborough <g.kettleborough@member.fsf.org>
4 Author: Jonathan Oddie <j.j.oddie@gmail.com>
4 Author: Stefan Kangas <stefankangas@gmail.com>
12 Author: Luís Oliveira <loliveira@common-lisp.net>
13 Author: Jonas Bernoulli <jonas@bernoul.li>
80 Author: joddie <jonxfield@gmail.com>
Of those, Luís Oliveira has signed some paperwork but not for Emacs, and
Fice, Torbjörn, and "duianto" don't appear at all in the
`copyright.list` so we'll need to either ask them to sign the paperwork,
or look at their contributions (to see if they're small enough or have
been replaced since).
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-02-29 20:44 ` Jeremy Bryant
2024-03-01 4:15 ` Adam Porter
2024-03-01 23:26 ` Stefan Monnier
@ 2024-03-02 6:51 ` Eli Zaretskii
2024-03-02 21:36 ` Jeremy Bryant
2 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-02 6:51 UTC (permalink / raw)
To: Jeremy Bryant
Cc: monnier, emacs-devel, j.j.oddie, stefan, stefankangas, jonas
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, j.j.oddie@gmail.com,
> Stefan Kangas <stefan@marxist.se>, Stefan Kangas
> <stefankangas@gmail.com>, Jonas Bernoulli <jonas@bernoul.li>, Eli
> Zaretskii <eliz@gnu.org>
> Date: Thu, 29 Feb 2024 20:44:56 +0000
>
> Given that macrostep is useful for Emacs Lisp macro development, would
> there be interest to include in Emacs core?
Sounds useful, so I'm in favor.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-03-01 23:08 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-03-02 9:33 ` Philip Kaludercic
[not found] ` <87r0faibbg.fsf@jeremybryant.net>
[not found] ` <87wmp2ibjj.fsf@jeremybryant.net>
0 siblings, 2 replies; 86+ messages in thread
From: Philip Kaludercic @ 2024-03-02 9:33 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: Eli Zaretskii, 68929, monnier, justin
[...]
> * The vast majority of improvements requested by Philip; defcustoms
> changes, docstrings, sharp-quoted elements, pure function, third party
> libs, declare, memq, string-join, null-bindings etc) Missing are some
> elements I'm less familiar with, such as design choices related to
> deffaces.
>
> These are currently in the form of individual patches in the upstream
> git repo (thus attached only for convenience). Using the 'preserving
> history' approach described by Stefan M, this could be moved to core,
> thus preserving the commits thus allowing checking of contributor FSF
> attribution.
>
>
> If there are certain elements you feel deserve further work, all
> feedback welcome.
Ok, but I might be repeating myself, because I don't recall everything
from my last response.
> WDYT?
>
>
> ;;; which-key.el --- Display available keybindings in popup -*- lexical-binding: t; -*-
>
> ;; Copyright (C) 2017-2024 Free Software Foundation, Inc.
>
> ;; Author: Justin Burkett <justin@burkett.cc>
> ;; Maintainer: Justin Burkett <justin@burkett.cc>
> ;; Version: 3.6.0
> ;; Keywords:
> ;; Package-Requires: ((emacs "24.4"))
>
> ;; 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
> ;; the Free Software Foundation, either version 3 of the License, or
> ;; (at your option) any later version.
>
> ;; This program is distributed in the hope that it will be useful,
> ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
> ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> ;; GNU General Public License for more details.
>
> ;; You should have received a copy of the GNU General Public License
> ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
>
> ;;; Commentary:
>
> ;; which-key provides the minor mode which-key-mode for Emacs. The mode displays
> ;; the key bindings following your currently entered incomplete command (a
> ;; prefix) in a popup. For example, after enabling the minor mode if you enter
> ;; C-x and wait for the default of 1 second the minibuffer will expand with all
> ;; of the available key bindings that follow C-x (or as many as space allows
> ;; given your settings). This includes prefixes like C-x 8 which are shown in a
> ;; different face. Screenshots of what the popup will look like along with
> ;; information about additional features can be found at
> ;; https://github.com/justbur/emacs-which-key.
> ;;
>
> ;;; Code:
>
> (require 'cl-lib)
> (require 'button)
> (require 'regexp-opt)
It shouldn't be necessary to require regexp-opt, especially seeing as
all instances will be optimised away by the byte compiler.
> ;; For compiler
> (defvar evil-operator-shortcut-map)
> (defvar evil-operator-state-map)
> (defvar evil-motion-state-map)
> (defvar golden-ratio-mode)
> (declare-function evil-get-command-property "ext:evil-common.el")
So what was the conclusion on the question of support for external
packages inside of which-key?
> ;;; Options
>
> (defgroup which-key nil
> "Customization options for which-key-mode."
> :group 'help
> :prefix "which-key-")
>
> (defcustom which-key-idle-delay 1.0
> "Delay (in seconds) for which-key buffer to popup.
> This variable should be set before activating `which-key-mode'.
>
> A value of zero might lead to issues, so a non-zero value is
> recommended
> (see https://github.com/justbur/emacs-which-key/issues/134)."
> :group 'which-key
Not sure if I mentioned this or not, but all :group attributes can be
left away, since a defcustom will default to the last group you defined.
> :type 'float
> :version "1.0")
>
> (defcustom which-key-idle-secondary-delay nil
> "Seconds to wait for which-key to pop up after initial display.
> This makes it possible to shorten the delay for subsequent popups
> in the same key sequence. The default is for this value to be
> nil, which disables this behavior."
> :group 'which-key
> :type '(choice float (const :tag "Disabled" nil))
> :version "1.0")
>
> (defcustom which-key-echo-keystrokes (if (and echo-keystrokes
> (> (+ echo-keystrokes 0.01)
> which-key-idle-delay))
> (/ (float which-key-idle-delay) 4)
> echo-keystrokes)
> "Value to use for `echo-keystrokes'.
> This only applies if `which-key-popup-type' is minibuffer or
> `which-key-show-prefix' is echo. It needs to be less than
> `which-key-idle-delay' or else the keystroke echo will erase the
> which-key popup."
> :group 'which-key
> :type 'float
> :version "1.0")
>
> (defcustom which-key-max-description-length 27
> "Truncate the description of keys to this length.
> Either nil (no truncation), an integer (truncate after that many
> characters), a float (use that fraction of the available width),
> or a function, which takes one argument, the available width in
> characters, and whose return value has one of the types mentioned
> before. Truncation is done using `which-key-ellipsis'."
> :group 'which-key
> :type '(choice (const :tag "Disable truncation" nil)
> (integer :tag "Width in characters")
> (float :tag "Use fraction of available width")
> function)
> :version "1.0")
>
> (defcustom which-key-min-column-description-width 0
> "Every column should at least have this width."
> :group 'which-key
> :type 'natnum
> :version "1.0")
>
> (defcustom which-key-add-column-padding 0
> "Additional spaces to add to the left of each key column."
> :group 'which-key
> :type 'integer
> :version "1.0")
>
> (defcustom which-key-unicode-correction 3
> "Correction for wide unicode characters.
> Since we measure width in terms of the number of characters,
> Unicode characters that are wider than ASCII characters throw off
> the calculation for available width in the which-key buffer. This
> variable allows you to adjust for the wide unicode characters by
> artificially reducing the available width in the buffer.
>
> The default of 3 means allow for the total extra width
> contributed by any wide unicode characters to be up to one
> additional ASCII character in the which-key buffer. Increase this
> number if you are seeing characters get cutoff on the right side
> of the which-key popup."
> :group 'which-key
> :type 'integer
> :version "1.0")
>
> (defcustom which-key-dont-use-unicode nil
I believe I mentioned this as well, but if not, I'd like to advocate for
setting this to non-nil by default, just because using unicode by
default could be tricky, if the user doesn't have the right fonts
installed, making everything look off. ASCII seems to be the safer
default.
> "If non-nil, don't use any unicode characters in default setup.
> For affected settings, see `which-key-replacement-alist', `which-key-ellipsis'
> 'which-key-separator'."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-separator
> (if which-key-dont-use-unicode " : " " → ")
> "Separator to use between key and description.
> Default is \" → \", unless `which-key-dont-use-unicode' is non
> nil, in which case the default is \" : \"."
> :group 'which-key
> :type 'string
> :version "1.0")
If the default value of this option relies on
`which-key-dont-use-unicode', shouldn't you add a :set-after here?
>
> (defcustom which-key-ellipsis
> (if which-key-dont-use-unicode ".." "…")
> "Ellipsis to use when truncating.
> Default is \"…\", unless `which-key-dont-use-unicode' is non nil,
> in which case the default is \"..\". This can also be the empty
> string to truncate without using any ellipsis."
> :group 'which-key
> :type 'string
> :version "1.0")
>
> (defcustom which-key-prefix-prefix "+"
> "Prefix string to indicate a key bound to a keymap.
> Default is \"+\"."
> :group 'which-key
> :type 'string
> :version "1.0")
>
> (defcustom which-key-compute-remaps nil
> "If non-nil, show remapped commands.
> This applies to commands that have been remapped given the
> currently active keymaps."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-replacement-alist
> (delq nil
Regardless of the value of `which-key-dont-use-unicode', it seems to me
that the list will never contain a nil that has to be removed. If
`which-key-dont-use-unicode' is nil, then an empty list is spliced,
which won't add a nil, otherwise a single non-nil element is added.
> `(((nil . "which-key-show-next-page-no-cycle") . (nil . "wk next pg"))
> ,@(unless which-key-dont-use-unicode
> '((("<left>") . ("←"))
> (("<right>") . ("→"))))
> (("<\\([[:alnum:]-]+\\)>") . ("\\1"))))
> "ALIST for manipulating display of binding descriptions.
> Each element of the list is a nested cons cell with the format
>
> \(MATCH CONS . REPLACEMENT\).
>
> The MATCH CONS determines when a replacement should occur and
> REPLACEMENT determines how the replacement should occur. Each may
> have the format \(KEY REGEXP . BINDING REGEXP\). For the
> replacement to apply the key binding must match both the KEY
> REGEXP and the BINDING REGEXP. A value of nil in either position
> can be used to match every possibility. The replacement is
> performed by using `replace-regexp-in-string' on the KEY REGEXP
> from the MATCH CONS and REPLACEMENT when it is a cons cell, and
> then similarly for the BINDING REGEXP. A nil value in the BINDING
> REGEXP position cancels the replacement. For example, the entry
>
> \(\(nil . \"Prefix Command\"\) . \(nil . \"prefix\"\)\)
>
> matches any binding with the descriptions \"Prefix Command\" and
> replaces the description with \"prefix\", ignoring the
> corresponding key.
>
> REPLACEMENT may also be a function taking a cons cell
> \(KEY . BINDING\) and producing a new corresponding cons cell.
>
> If REPLACEMENT is anything other than a cons cell \(and non nil\)
> the key binding is ignored by which-key.
>
> Finally, you can multiple replacements to occur for a given key
> binding by setting `which-key-allow-multiple-replacements' to a
> non-nil value."
> :group 'which-key
> :type '(alist :key-type (cons (choice regexp (const nil))
> (choice regexp (const nil)))
> :value-type (cons (choice string (const nil))
> (choice string (const nil))))
> :version "1.0")
>
> (defcustom which-key-allow-multiple-replacements nil
> "Allow a key binding to be modified by multiple elements.
> When non-nil, this allows a single key binding to match multiple
> patterns in `which-key-replacement-alist'. When nil, only the
> first match is used to perform replacements from
> `which-key-replacement-alist'."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-show-docstrings nil
> "If non-nil, show each command's docstring in the which-key popup.
> This will only display the docstring up to the first line
> break. If you set this variable to the symbol docstring-only,
> then the command's name with be omitted. You probably also want
> to adjust `which-key-max-description-length' at the same time if
> you use this feature."
> :group 'which-key
> :type '(radio
> (const :tag "Do not show docstrings" nil)
> (const :tag "Add docstring to command names" t)
> (const :tag "Replace command name with docstring" docstring-only))
> :version "1.0")
>
> (defcustom which-key-highlighted-command-list '()
> "Rules used to highlight certain commands.
> If the element is a string, assume it is a regexp pattern for
> matching command names and use
> `which-key-highlighted-command-face' for any matching names. If
> the element is a cons cell, it should take the form (regexp .
> face to apply)."
> :group 'which-key
> :type '(repeat (choice string (cons regexp face)))
> :version "1.0")
>
> (defcustom which-key-special-keys '()
> "These keys will automatically be truncated to one character.
> They also have `which-key-special-key-face' applied to them. This
> is disabled by default. An example configuration is
>
> \(setq which-key-special-keys \\='(\"SPC\" \"TAB\" \"RET\" \"ESC\" \"DEL\")\)"
> :group 'which-key
> :type '(repeat string)
> :version "1.0")
>
> (defcustom which-key-buffer-name " *which-key*"
Is it supposed to be a hidden buffer? If so, why?
> "Name of which-key buffer."
> :group 'which-key
> :type 'string
> :version "1.0")
>
> (defcustom which-key-show-prefix 'echo
> "Whether to and where to display the current prefix sequence.
> Possible choices are echo for echo area (the default), left, top
> and nil. Nil turns the feature off."
> :group 'which-key
> :type '(radio (const :tag "Left of the keys" left)
> (const :tag "In the first line" top)
> (const :tag "In the last line" bottom)
> (const :tag "In the echo area" echo)
> (const :tag "In the mode-line" mode-line)
> (const :tag "Hide" nil))
> :version "1.0")
>
> (defcustom which-key-popup-type 'side-window
> "Supported types are minibuffer, side-window, frame, and custom."
> :group 'which-key
> :type '(radio (const :tag "Show in minibuffer" minibuffer)
> (const :tag "Show in side window" side-window)
> (const :tag "Show in popup frame" frame)
> (const :tag "Use your custom display functions" custom))
> :version "1.0")
>
> (defcustom which-key-min-display-lines 1
> "Minimum number of horizontal lines to display in the which-key buffer."
> :group 'which-key
> :type 'integer
> :version "1.0")
>
> (defcustom which-key-max-display-columns nil
> "Maximum number of columns to display in the which-key buffer.
> A value of nil means don't impose a maximum."
> :group 'which-key
> :type '(choice integer (const :tag "Unbounded" nil))
> :version "1.0")
>
> (defcustom which-key-side-window-location 'bottom
> "Location of which-key popup when `which-key-popup-type' is side-window.
> Should be one of top, bottom, left or right. You can also specify
> a list of two locations, like (right bottom). In this case, the
> first location is tried. If there is not enough room, the second
> location is tried."
> :group 'which-key
> :type '(radio (const right)
> (const bottom)
> (const left)
> (const top)
> (const (right bottom))
> (const (bottom right)))
> :version "1.0")
>
> (defcustom which-key-side-window-slot 0
> "The `slot' to use for `display-buffer-in-side-window'.
> This applies when `which-key-popup-type' is `side-window'.
> Quoting from the docstring of `display-buffer-in-side-window',
>
> `slot' if non-nil, specifies the window slot where to display
> BUFFER. A value of zero or nil means use the middle slot on the
> specified side. A negative value means use a slot
> preceding (that is, above or on the left of) the middle slot. A
> positive value means use a slot following (that is, below or on
> the right of) the middle slot. The default is zero."
> :group 'which-key
> :type 'integer
> :version "1.0")
>
> (defcustom which-key-side-window-max-width 0.333
> "Maximum width of which-key popup when type is side-window.
> This variable can also be a number between 0 and 1. In that case,
> it denotes a percentage out of the frame's width."
> :group 'which-key
> :type 'float
> :version "1.0")
>
> (defcustom which-key-side-window-max-height 0.25
> "Maximum height of which-key popup when type is side-window.
> This variable can also be a number between 0 and 1. In that case, it denotes
> a percentage out of the frame's height."
> :group 'which-key
> :type 'float
> :version "1.0")
>
> (defcustom which-key-frame-max-width 60
> "Maximum width of which-key popup when type is frame."
> :group 'which-key
> :type 'integer
> :version "1.0")
>
> (defcustom which-key-frame-max-height 20
> "Maximum height of which-key popup when type is frame."
> :group 'which-key
> :type 'integer
> :version "1.0")
These two also sound like natnums?
>
> (defcustom which-key-allow-imprecise-window-fit (not (display-graphic-p))
> "Allow which-key to use a simpler method for resizing the popup.
> If you are noticing lag when the which-key popup displays turning
> this on may help.
>
> See https://github.com/justbur/emacs-which-key/issues/130
> and https://github.com/justbur/emacs-which-key/issues/225."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-show-remaining-keys nil
> "Show remaining keys in last slot, when keys are hidden."
> :group 'which-key
> :type '(radio (const :tag "Yes" t)
> (const :tag "No" nil))
> :version "1.0")
>
> (defcustom which-key-sort-order 'which-key-key-order
If this is a function, then it should be sharp-quoted.
> "Order in which the key bindings are sorted.
> If nil, do not resort the output from `describe-buffer-bindings'
> which groups by mode. Ordering options
> are
>
> 1. `which-key-key-order': by key (default)
> 2. `which-key-key-order-alpha': by key using alphabetical order
> 3. `which-key-description-order': by description
> 4. `which-key-prefix-then-key-order': prefix (no prefix first) then key
> 5. `which-key-local-then-key-order': local binding then key
>
> See the README and the docstrings for those functions for more
> information."
> :group 'which-key
> :type '(choice (function-item which-key-key-order)
> (function-item which-key-key-order-alpha)
> (function-item which-key-description-order)
> (function-item which-key-prefix-then-key-order)
> (function-item which-key-local-then-key-order))
> :version "1.0")
>
> (defcustom which-key-sort-uppercase-first t
> "If non-nil, uppercase comes before lowercase in sorting.
> This applies to the function chosen in
> `which-key-sort-order'. Otherwise, the order is reversed."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-paging-prefixes '()
> "Enable paging for these prefixes."
Some more documentation would be useful here, since I find it difficult
to imagine what possible values could be.
> :group 'which-key
> :type '(repeat string)
> :version "1.0")
>
> (defcustom which-key-paging-key "<f5>"
> "Key to use for changing pages.
> Bound after each of the prefixes in `which-key-paging-prefixes'"
> :group 'which-key
> :type 'string
If it is a single key, then why use a string as the type here, and not
replace the default value with (kbd "<f5>")?
> :version "1.0")
>
> ;; (defcustom which-key-undo-key nil
> ;; "Key (string) to use for undoing keypresses. Bound recursively
> ;; in each of the maps in `which-key-undo-keymaps'."
> ;; :group 'which-key
> ;; :type 'string)
>
> ;; (defcustom which-key-undo-keymaps '()
> ;; "Keymaps in which to bind `which-key-undo-key'"
> ;; :group 'which-key
> ;; :type '(repeat symbol))
>
> (defcustom which-key-use-C-h-commands t
> "Use C-h (`help-char') for paging if non-nil.
> Normally `help-char' after a prefix calls
> `describe-prefix-bindings'. This changes that command to a
> which-key paging command when which-key-mode is active."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-show-early-on-C-h nil
> "Allow C-h (`help-char') to trigger which-key popup before timer.
> Show the which-key buffer if `help-char' is pressed in the middle
> of a prefix before the which-key buffer would normally be
> triggered by the time. If combined with the following settings,
> which-key will effectively only show when triggered \"manually\"
> using C-h.
>
> \(setq `which-key-idle-delay' 10000)
> \(setq `which-key-idle-secondary-delay' 0.05)
>
> Note that `which-key-idle-delay' should be set before turning on
> `which-key-mode'."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-is-verbose nil
> "Whether to warn about potential mistakes in configuration."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-preserve-window-configuration nil
> "Save and restore window configuration around which-key popup display.
> If non-nil, save window configuration before which-key buffer is
> shown and restore it after which-key buffer is hidden. It
> prevents which-key from changing window position of visible
> buffers. Only takken into account when popup type is
> side-window."
> :group
> 'which-key
> :type 'boolean
> :version "1.0")
>
> (defvar which-key-C-h-map-prompt
> (concat " \\<which-key-C-h-map>"
> " \\[which-key-show-next-page-cycle]"
> which-key-separator "next-page,"
> " \\[which-key-show-previous-page-cycle]"
> which-key-separator "previous-page,"
> " \\[which-key-undo-key]"
> which-key-separator "undo-key,"
> " \\[which-key-toggle-docstrings]"
> which-key-separator "toggle-docstrings,"
> " \\[which-key-show-standard-help]"
> which-key-separator "help,"
> " \\[which-key-abort]"
> which-key-separator "abort"
> " 1..9"
> which-key-separator "digit-arg")
> "Prompt to display when invoking `which-key-C-h-map'.
> This string is fed into `substitute-command-keys'")
>
> (defvar which-key-C-h-map
> (let ((map (make-sparse-keymap)))
> (dolist (bind `(("\C-a" . which-key-abort)
> ("a" . which-key-abort)
> ("\C-d" . which-key-toggle-docstrings)
> ("d" . which-key-toggle-docstrings)
> (,(vector help-char) . which-key-show-standard-help)
> ("h" . which-key-show-standard-help)
> ("\C-n" . which-key-show-next-page-cycle)
> ("n" . which-key-show-next-page-cycle)
> ("\C-p" . which-key-show-previous-page-cycle)
> ("p" . which-key-show-previous-page-cycle)
> ("\C-u" . which-key-undo-key)
> ("u" . which-key-undo-key)
> ("1" . which-key-digit-argument)
> ("2" . which-key-digit-argument)
> ("3" . which-key-digit-argument)
> ("4" . which-key-digit-argument)
> ("5" . which-key-digit-argument)
> ("6" . which-key-digit-argument)
> ("7" . which-key-digit-argument)
> ("8" . which-key-digit-argument)
> ("9" . which-key-digit-argument)))
> (define-key map (car bind) (cdr bind)))
> map)
> "Keymap for C-h commands.")
If this is going to be added to the core, then why not use `defvar-keymap'?
>
> (defvar which-key--paging-functions
> (list #'which-key-C-h-dispatch
> #'which-key-manual-update
> #'which-key-turn-page
> #'which-key-show-next-page-cycle
> #'which-key-show-next-page-no-cycle
> #'which-key-show-previous-page-cycle
> #'which-key-show-previous-page-no-cycle
> #'which-key-undo-key
> #'which-key-undo))
Avoid indenting these lines using tabs.
>
> (defvar which-key-persistent-popup nil
> "Whether or not to disable `which-key--hide-popup'.")
>
> (defcustom which-key-hide-alt-key-translations t
> "Hide key translations using Alt key if non nil.
> These translations are not relevant most of the times since a lot
> of terminals issue META modifier for the Alt key.
>
> See http://www.gnu.org/software/emacs/manual/html_node/emacs/Modifier-Keys.html"
References like these should be replaced by something like "Info node
`(emacs) Modifier Keys'".
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-delay-functions nil
> "List of functions that may delay the which-key popup.
> A list of functions that may decide whether to delay the
> which-key popup based on the current incomplete key
> sequence. Each function in the list is run with two arguments,
> the current key sequence as produced by `key-description' and the
> length of the key sequence. If the popup should be delayed based
> on that key sequence, the function should return the delay time
> in seconds. Returning nil means no delay. The first function in
> this list to return a value is the value that is used.
>
> The delay time is effectively added to the normal
> `which-key-idle-delay'."
> :group 'which-key
> :type '(repeat function)
> :version "1.0")
>
> (defcustom which-key-allow-regexps nil
> "A list of regexp strings to use to filter key sequences.
> When non-nil, for a key sequence to trigger the which-key popup
> it must match one of the regexps in this list. The format of the
> key sequences is what is produced by `key-description'."
> :group 'which-key
> :type '(repeat regexp)
> :version "1.0")
>
> (defcustom which-key-inhibit-regexps nil
> "A list of regexp strings to use to filter key sequences.
> When non-nil, for a key sequence to trigger the which-key popup
> it cannot match one of the regexps in this list. The format of
> the key sequences is what is produced by `key-description'."
> :group 'which-key
> :type '(repeat regexp)
> :version "1.0")
>
> (defcustom which-key-show-transient-maps nil
> "Show keymaps created by `set-transient-map' when applicable.
>
> More specifically, detect when `overriding-terminal-local-map' is
> set (this is the keymap used by `set-transient-map') and display
> it."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (make-obsolete-variable
> 'which-key-enable-extended-define-key
> "which-key-enable-extended-define-key is obsolete and has no effect."
> "2021-06-21")
>
> ;; Hooks
> (defcustom which-key-init-buffer-hook '()
> "Hook run when which-key buffer is initialized."
> :group 'which-key
> :type 'hook
> :version "1.0")
>
> ;;;; Faces
>
> (defgroup which-key-faces nil
> "Faces for which-key-mode"
> :group 'which-key
> :prefix "which-key-")
>
> (defface which-key-key-face
> '((t . (:inherit font-lock-constant-face)))
> "Face for which-key keys"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-separator-face
> '((t . (:inherit font-lock-comment-face)))
> "Face for the separator (default separator is an arrow)"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-note-face
> '((t . (:inherit which-key-separator-face)))
> "Face for notes or hints occasionally provided"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-command-description-face
> '((t . (:inherit font-lock-function-name-face)))
> "Face for the key description when it is a command"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-local-map-description-face
> '((t . (:inherit which-key-command-description-face)))
> "Face for the key description when it is found in `current-local-map'"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-highlighted-command-face
> '((t . (:inherit which-key-command-description-face :underline t)))
> "Default face for the command description when it is a command
> and it matches a string in `which-key-highlighted-command-list'."
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-group-description-face
> '((t . (:inherit font-lock-keyword-face)))
> "Face for the key description when it is a group or prefix."
> :group 'which-key-faces
> :version "1.0")
These were the design-choices you meant above? I guess we can leave it
for now, I have been planning to work on adding more "semantic" faces,
if I ever get around to that, where after I hope that it should be
obvious what faces to use here.
>
> (defface which-key-special-key-face
> '((t . (:inherit which-key-key-face :inverse-video t :weight bold)))
> "Face for special keys (SPC, TAB, RET)"
> :group 'which-key-faces
> :version "1.0")
>
> (defface which-key-docstring-face
> '((t . (:inherit which-key-note-face)))
> "Face for docstrings."
> :group 'which-key-faces
> :version "1.0")
>
> ;;;; Custom popup
Shouldn't these options occur earlier in the file, along with the other
user options?
> (defcustom which-key-custom-popup-max-dimensions-function nil
> "Set a custom max-dimensions function.
> Will be passed the width of the active window and is expected to
> return the maximum height in lines and width in characters of the
> which-key popup in the form a cons cell (height . width)."
> :group 'which-key
> :type '(choice function (const nil))
> :version "1.0")
>
> (defcustom which-key-custom-hide-popup-function nil
> "Set a custom hide-popup function.
> It takes no arguments and the return value is ignored."
> :group 'which-key
> :type '(choice function (const nil))
> :version "1.0")
>
> (defcustom which-key-custom-show-popup-function nil
> "Set a custom show-popup function.
> Will be passed the required dimensions in the form (height .
> width) in lines and characters respectively. The return value is
> ignored."
> :group 'which-key
> :type '(choice function (const nil))
> :version "1.0")
>
> (defcustom which-key-lighter " WK"
> "Minor mode lighter to use in the mode-line."
> :group 'which-key
> :type 'string
> :version "1.0")
>
> (defvar which-key-inhibit nil
> "Prevent which-key from popping up momentarily.
> This can be used by setting this to a non-nil value for the
> execution of a command, as in
>
> \(let \(\(which-key-inhibit t\)\)
> ...\)")
>
> (defcustom which-key-inhibit-display-hook nil
> "Hook run before display of which-key popup.
> Each function in the hook is run before displaying the which-key
> popup. If any function returns a non-nil value, the popup will
> not display."
> :group 'which-key
> :type 'hook
> :version "1.0")
>
> (defvar which-key-keymap-history nil
> "History of keymap selections.
> Used in functions like `which-key-show-keymap'.")
>
> ;;; Internal Vars
>
> (defvar which-key--buffer nil
> "Holds reference to which-key buffer.")
> (defvar which-key--timer nil
> "Holds reference to open window timer.")
> (defvar which-key--secondary-timer-active nil
> "Non-nil if the secondary timer is active.")
> (defvar which-key--paging-timer nil
> "Holds reference to timer for paging.")
> (defvar which-key--frame nil
> "Holds reference to which-key frame.
> Used when `which-key-popup-type' is frame.")
> (defvar which-key--echo-keystrokes-backup nil
> "Backup the initial value of `echo-keystrokes'.")
> (defvar which-key--prefix-help-cmd-backup nil
> "Backup the value of `prefix-help-command'.")
> (defvar which-key--last-try-2-loc nil
> "Last location of side-window when two locations used.")
> (defvar which-key--automatic-display nil
> "Non-nil if popup was triggered with automatic update.")
> (defvar which-key--debug-buffer-name nil
> "If non-nil, use this buffer for debug messages.")
> (defvar which-key--multiple-locations nil)
> (defvar which-key--inhibit-next-operator-popup nil)
> (defvar which-key--prior-show-keymap-args nil)
> (defvar which-key--previous-frame-size nil)
> (defvar which-key--prefix-title-alist nil)
> (defvar which-key--evil-keys-regexp (eval-when-compile
> (regexp-opt '("-state"))))
> (defvar which-key--ignore-non-evil-keys-regexp
> (eval-when-compile
> (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
> "select-window" "switch-frame" "which-key"))))
The regexp-opt's in the above lines also don't need the eval-when-compile.
> (defvar which-key--ignore-keys-regexp
> (regexp-opt '("mouse-" "wheel-" "remap" "drag-" "scroll-bar"
> "select-window" "switch-frame" "-state"
> "which-key")))
>
> (defvar which-key--pages-obj nil)
> (cl-defstruct which-key--pages
> pages
> height
> widths
> keys/page
> page-nums
> num-pages
> total-keys
> prefix
> prefix-title)
>
> (defvar which-key--saved-window-configuration nil)
>
> (defun which-key--rotate (list n)
> (let* ((len (length list))
> (n (if (< n 0) (+ len n) n))
> (n (mod n len)))
> (append (last list (- len n)) (butlast list (- len n)))))
This can be slightly simplified to
--8<---------------cut here---------------start------------->8---
(defun which-key--rotate0 (list n)
(let* ((len (length list))
(n (- len (mod n len))))
(append (last list n) (butlast list n))))
--8<---------------cut here---------------end--------------->8---
>
> (defun which-key--pages-set-current-page (pages-obj n)
> (setf (which-key--pages-pages pages-obj)
> (which-key--rotate (which-key--pages-pages pages-obj) n))
> (setf (which-key--pages-widths pages-obj)
> (which-key--rotate (which-key--pages-widths pages-obj) n))
> (setf (which-key--pages-keys/page pages-obj)
> (which-key--rotate (which-key--pages-keys/page pages-obj) n))
> (setf (which-key--pages-page-nums pages-obj)
> (which-key--rotate (which-key--pages-page-nums pages-obj) n))
> pages-obj)
>
> (defsubst which-key--on-first-page ()
> (= (which-key--pages-page-nums which-key--pages-obj) 1))
>
> (defsubst which-key--on-last-page ()
> (= (which-key--pages-page-nums which-key--pages-obj)
> (which-key--pages-num-pages which-key--pages-obj)))
>
> (defsubst which-key--current-prefix ()
> (and which-key--pages-obj
> (which-key--pages-prefix which-key--pages-obj)))
>
> (defmacro which-key--debug-message (&rest msg)
> `(when which-key--debug-buffer-name
> (let ((buf (get-buffer-create which-key--debug-buffer-name))
> (fmt-msg (format ,@msg)))
> (with-current-buffer buf
> (goto-char (point-max))
> (insert "\n" fmt-msg "\n")))))
>
> (defsubst which-key--safe-lookup-key (keymap key)
> "Version of `lookup-key' that allows KEYMAP to be nil.
> Also convert numeric results of `lookup-key' to nil. KEY is not
> checked."
> (when (keymapp keymap)
> (let ((result (lookup-key keymap key)))
> (when (and result (not (numberp result)))
> result))))
Arguably you can replace the `when' expression with just (and (not
(numberp result)) result).
>
> (defsubst which-key--safe-lookup-key-description (keymap key)
> "Version of `lookup-key' that allows KEYMAP to be nil.
> Also convert numeric results of `lookup-key' to nil. KEY
> should be formatted as an input for `kbd'."
> (let ((key (ignore-errors (kbd key))))
> (when (and key (keymapp keymap))
> (let ((result (lookup-key keymap key)))
> (when (and result (not (numberp result)))
> result)))))
Here as well.
> ;;; Third-party library support
>
> (defun which-key--this-command-keys ()
> "Version of `this-single-command-keys' corrected for key-chords."
> (let ((this-command-keys (this-single-command-keys)))
> (when (and (vectorp this-command-keys)
> (> (length this-command-keys) 0)
> (eq (aref this-command-keys 0) 'key-chord)
> (bound-and-true-p key-chord-mode))
> (setq this-command-keys (this-single-command-raw-keys)))
> this-command-keys))
>
> (defcustom which-key-this-command-keys-function 'which-key--this-command-keys
> "Function used to retrieve current key sequence.
> The purpose of allowing this variable to be customized is to
> allow which-key to support packages that insert non-standard
> 'keys' into the key sequence being read by emacs."
> :group 'which-key
> :type 'function
> :version "1.0")
>
>
> ;;;; Evil
>
> (defvar evil-state nil)
>
> (defcustom which-key-allow-evil-operators (boundp 'evil-this-operator)
> "Allow popup to show for evil operators.
> The popup is normally inhibited in the middle of commands, but
> setting this to non-nil will override this behavior for evil
> operators."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defcustom which-key-show-operator-state-maps nil
> "Show the keys following an evil command that reads a motion.
> These are commands typically mapped to keys such as \"y\", \"d\"
> and \"c\" from normal state. This is experimental, because there
> might be some valid keys missing and it might be showing some
> invalid keys."
> :group 'which-key
> :type 'boolean
> :version "1.0")
>
> (defun which-key-evil-this-operator-p ()
> (and which-key-allow-evil-operators
> (bound-and-true-p evil-this-operator)))
>
> (add-hook 'which-key-inhibit-display-hook
> 'which-key-evil-this-operator-p)
>
> ;;;; God-mode
>
> (defvar which-key--god-mode-support-enabled nil
> "Support god-mode if non-nil.")
>
> (defvar which-key--god-mode-key-string nil
> "String to use for god-mode support.")
>
> (defun which-key--god-mode-lookup-command-advice (orig-fun arg1 &rest args)
> (setq which-key--god-mode-key-string arg1)
> (unwind-protect
> (apply orig-fun arg1 args)
> (when (bound-and-true-p which-key-mode)
> (which-key--hide-popup))))
>
> (defun which-key--god-mode-this-command-keys ()
> "Version of `this-single-command-keys' corrected for god-mode."
> (let ((this-command-keys (this-single-command-keys)))
> (when (and which-key--god-mode-support-enabled
> (bound-and-true-p god-local-mode)
> (eq this-command 'god-mode-self-insert))
> (setq this-command-keys (when which-key--god-mode-key-string
> (kbd which-key--god-mode-key-string))))
> this-command-keys))
>
> (defun which-key-god-mode-self-insert-p ()
> (and which-key--god-mode-support-enabled
> (bound-and-true-p god-local-mode)
> (eq this-command 'god-mode-self-insert)))
>
> (defun which-key-enable-god-mode-support (&optional disable)
> "Enable support for god-mode if non-nil.
> This is experimental, so you need to explicitly opt-in for
> now. Please report any problems at github. If DISABLE is non-nil
> disable support."
> (interactive "P")
> (setq which-key--god-mode-support-enabled (null disable))
> (if disable
> (progn
> (advice-remove 'god-mode-lookup-command
> #'which-key--god-mode-lookup-command-advice)
> (setq which-key-this-command-keys-function
> 'which-key--this-command-keys)
> (remove-hook 'which-key-inhibit-display-hook
> 'which-key-god-mode-self-insert-p))
> (advice-add 'god-mode-lookup-command :around
> #'which-key--god-mode-lookup-command-advice)
> (setq which-key-this-command-keys-function
> 'which-key--god-mode-this-command-keys)
> (add-hook 'which-key-inhibit-display-hook
> 'which-key-god-mode-self-insert-p)))
>
> ;;; Mode
>
> ;;;###autoload
> (define-minor-mode which-key-mode
> "Toggle which-key-mode."
> :global t
> :group 'which-key
> :lighter which-key-lighter
> :keymap (let ((map (make-sparse-keymap)))
> (mapc
> (lambda (prefix)
> (define-key map
> (kbd (concat prefix " " which-key-paging-key))
As mentioned above, if which-key-paging-key were a key, then you could
just just vconcat here, and would reduce the danger of running into
peculiar edge-cases with `kbd'.
> #'which-key-C-h-dispatch))
> which-key-paging-prefixes)
> map)
> (if which-key-mode
> (progn
> (setq which-key--echo-keystrokes-backup echo-keystrokes)
> (when (or (eq which-key-show-prefix 'echo)
> (eq which-key-popup-type 'minibuffer))
> (which-key--setup-echo-keystrokes))
> (unless (member prefix-help-command which-key--paging-functions)
> (setq which-key--prefix-help-cmd-backup prefix-help-command))
> (when (or which-key-use-C-h-commands
> which-key-show-early-on-C-h)
> (setq prefix-help-command #'which-key-C-h-dispatch))
> (when which-key-show-remaining-keys
> (add-hook 'pre-command-hook #'which-key--lighter-restore))
> (add-hook 'pre-command-hook #'which-key--hide-popup)
> (add-hook 'window-size-change-functions
> #'which-key--hide-popup-on-frame-size-change)
> (which-key--start-timer))
> (setq echo-keystrokes which-key--echo-keystrokes-backup)
> (when which-key--prefix-help-cmd-backup
> (setq prefix-help-command which-key--prefix-help-cmd-backup))
> (when which-key-show-remaining-keys
> (remove-hook 'pre-command-hook #'which-key--lighter-restore))
> (remove-hook 'pre-command-hook #'which-key--hide-popup)
> (remove-hook 'window-size-change-functions
> #'which-key--hide-popup-on-frame-size-change)
> (which-key--stop-timer)))
>
> (defun which-key--init-buffer ()
> "Initialize which-key buffer"
> (unless (buffer-live-p which-key--buffer)
> (setq which-key--buffer (get-buffer-create which-key-buffer-name))
> (with-current-buffer which-key--buffer
> ;; suppress confusing minibuffer message
> (let (message-log-max)
I guess what you want here is to bind `inhibit-message'.
> (toggle-truncate-lines 1)
> (message ""))
> (setq-local cursor-type nil)
> (setq-local cursor-in-non-selected-windows nil)
> (setq-local mode-line-format nil)
> (setq-local header-line-format nil)
> (setq-local word-wrap nil)
> (setq-local show-trailing-whitespace nil)
FWIW you can set multiple variables using setq-local in a single
expression.
> (run-hooks 'which-key-init-buffer-hook))))
>
> (defun which-key--setup-echo-keystrokes ()
> "Reduce `echo-keystrokes' if necessary.
> It will interfere if set too high."
> (when (and echo-keystrokes
> (> (abs (- echo-keystrokes which-key-echo-keystrokes)) 0.000001))
> (if (> which-key-idle-delay which-key-echo-keystrokes)
> (setq echo-keystrokes which-key-echo-keystrokes)
> (setq which-key-echo-keystrokes (/ (float which-key-idle-delay) 4)
> echo-keystrokes which-key-echo-keystrokes))))
>
> (defun which-key-remove-default-unicode-chars ()
> "Remove default unicode chars from settings.
> Use of `which-key-dont-use-unicode' is preferred to this
> function, but it's included here in case someone cannot set that
> variable early enough in their configuration, if they are using a
> starter kit for example."
> (when (string-equal which-key-separator " → ")
> (setq which-key-separator " : ")))
>
> ;;; Default configuration functions for use by users.
>
> ;;;###autoload
> (defun which-key-setup-side-window-right ()
> "Set up side-window on right."
> (interactive)
> (setq which-key-popup-type 'side-window
> which-key-side-window-location 'right
> which-key-show-prefix 'top))
>
> ;;;###autoload
> (defun which-key-setup-side-window-right-bottom ()
> "Set up side-window on right if space allows.
> Otherwise, use bottom."
> (interactive)
> (setq which-key-popup-type 'side-window
> which-key-side-window-location '(right bottom)
> which-key-show-prefix 'top))
>
> ;;;###autoload
> (defun which-key-setup-side-window-bottom ()
> "Set up side-window that opens on bottom."
> (interactive)
> (which-key--setup-echo-keystrokes)
> (setq which-key-popup-type 'side-window
> which-key-side-window-location 'bottom
> which-key-show-prefix 'echo))
>
> ;;;###autoload
> (defun which-key-setup-minibuffer ()
> "Set up minibuffer display.
> Do not use this setup if you use the paging commands. Instead use
> `which-key-setup-side-window-bottom', which is nearly identical
> but more functional."
> (interactive)
> (which-key--setup-echo-keystrokes)
> (setq which-key-popup-type 'minibuffer
> which-key-show-prefix 'left))
>
> ;;; Helper functions to modify replacement lists.
>
> ;;;###autoload
> (defun which-key-add-keymap-based-replacements (keymap key replacement &rest more)
> "Replace the description of KEY using REPLACEMENT in KEYMAP.
> KEY should take a format suitable for use in `kbd'. REPLACEMENT
> should be a cons cell of the form \(STRING . COMMAND\) for each
> REPLACEMENT, where STRING is the replacement string and COMMAND
> is a symbol corresponding to the intended command to be
> replaced. COMMAND can be nil if the binding corresponds to a key
> prefix. An example is
>
> \(which-key-add-keymap-based-replacements global-map
> \"C-x w\" \\='\(\"Save as\" . write-file\)\).
>
> For backwards compatibility, REPLACEMENT can also be a string,
> but the above format is preferred, and the option to use a string
> for REPLACEMENT will eventually be removed."
> (while key
> (let ((def
> (cond
> ((consp replacement) replacement)
> ((stringp replacement)
> (cons replacement
> (or (which-key--safe-lookup-key-description keymap key)
> (make-sparse-keymap))))
> (t
> (user-error "Replacement is neither a cons cell or a string")))))
> (define-key keymap (kbd key) def))
> (setq key (pop more)
> replacement (pop more))))
> (put 'which-key-add-keymap-based-replacements 'lisp-indent-function 'defun)
Replace this with a
(declare (indent defun))
at the beginning of the function definition.
>
> ;;;###autoload
> (defun which-key-add-key-based-replacements
> (key-sequence replacement &rest more)
> "Replace the description of KEY-SEQUENCE with REPLACEMENT.
> KEY-SEQUENCE is a string suitable for use in `kbd'. REPLACEMENT
> may either be a string, as in
>
> \(which-key-add-key-based-replacements \"C-x 1\" \"maximize\"\)
>
> a cons of two strings as in
>
> \(which-key-add-key-based-replacements \"C-x 8\"
> \\='(\"unicode\" . \"Unicode keys\")\)
>
> or a function that takes a \(KEY . BINDING\) cons and returns a
> replacement.
>
> In the second case, the second string is used to provide a longer
> name for the keys under a prefix.
>
> MORE allows you to specifcy additional KEY REPLACEMENT pairs. All
> replacements are added to `which-key-replacement-alist'."
> ;; TODO: Make interactive
> (while key-sequence
> ;; normalize key sequences before adding
> (let ((key-seq (key-description (kbd key-sequence)))
> (replace (or (and (functionp replacement) replacement)
> (car-safe replacement)
> replacement)))
> (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
> (if (functionp replace) replace (cons nil replace)))
> which-key-replacement-alist)
> (when (and (not (functionp replacement)) (consp replacement))
> (push (cons key-seq (cdr-safe replacement))
> which-key--prefix-title-alist)))
> (setq key-sequence (pop more) replacement (pop more))))
> (put 'which-key-add-key-based-replacements 'lisp-indent-function 'defun)
Here as well.
>
> ;;;###autoload
> (defun which-key-add-major-mode-key-based-replacements
> (mode key-sequence replacement &rest more)
> "Functions like `which-key-add-key-based-replacements'.
> The difference is that MODE specifies the `major-mode' that must
> be active for KEY-SEQUENCE and REPLACEMENT (MORE contains
> addition KEY-SEQUENCE REPLACEMENT pairs) to apply."
> (declare (indent defun))
... as has been done here!
> ;; TODO: Make interactive
Should this be resolved?
> (when (not (symbolp mode))
> (error "MODE should be a symbol corresponding to a value of major-mode"))
Why not mention the mode in the error message?
(error "`%S' should be a symbol corresponding to a value of major-mode" mode)
> (let ((mode-alist
> (or (cdr-safe (assq mode which-key-replacement-alist)) (list)))
> (title-mode-alist
> (or (cdr-safe (assq mode which-key--prefix-title-alist)) (list))))
> (while key-sequence
> ;; normalize key sequences before adding
> (let ((key-seq (key-description (kbd key-sequence)))
> (replace (or (and (functionp replacement) replacement)
> (car-safe replacement)
> replacement)))
> (push (cons (cons (concat "\\`" (regexp-quote key-seq) "\\'") nil)
> (if (functionp replace) replace (cons nil replace)))
> mode-alist)
> (when (and (not (functionp replacement)) (consp replacement))
> (push (cons key-seq (cdr-safe replacement))
> title-mode-alist)))
> (setq key-sequence (pop more) replacement (pop more)))
> (if (assq mode which-key-replacement-alist)
> (setcdr (assq mode which-key-replacement-alist) mode-alist)
> (push (cons mode mode-alist) which-key-replacement-alist))
> (if (assq mode which-key--prefix-title-alist)
> (setcdr (assq mode which-key--prefix-title-alist) title-mode-alist)
> (push (cons mode title-mode-alist) which-key--prefix-title-alist))))
>
> (defun which-key-define-key-recursively (map key def &optional at-root)
> "Recursively bind KEY in MAP to DEF on every level of MAP except the first.
> If AT-ROOT is non-nil the binding is also placed at the root of MAP."
> (when at-root (define-key map key def))
> (map-keymap
> (lambda (_ev df)
> (when (keymapp df)
> (which-key-define-key-recursively df key def t)))
> map))
>
> ;;; Functions for computing window sizes
>
> (defun which-key--text-width-to-total (text-width)
> "Convert window TEXT-WIDTH to window total-width.
> TEXT-WIDTH is the desired text width of the window. The function
> calculates what total width is required for a window in the
> selected to have a text-width of TEXT-WIDTH columns. The
> calculation considers possible fringes and scroll bars. This
> function assumes that the desired window has the same character
> width as the frame."
> (let ((char-width (frame-char-width)))
> (+ text-width
> (/ (frame-fringe-width) char-width)
> (/ (frame-scroll-bar-width) char-width)
> (if (which-key--char-enlarged-p) 1 0)
> ;; add padding to account for possible wide (unicode) characters
> 3)))
>
> (defun which-key--total-width-to-text (total-width)
> "Convert window TOTAL-WIDTH to window text-width.
> TOTAL-WIDTH is the desired total width of the window. The function calculates
> what text width fits such a window. The calculation considers possible fringes
> and scroll bars. This function assumes that the desired window has the same
> character width as the frame."
> (let ((char-width (frame-char-width)))
> (- total-width
> (/ (frame-fringe-width) char-width)
> (/ (frame-scroll-bar-width) char-width)
> (if (which-key--char-enlarged-p) 1 0)
> ;; add padding to account for possible wide (unicode) characters
> 3)))
>
> (defun which-key--char-enlarged-p (&optional _frame)
> (> (frame-char-width)
> (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
>
> (defun which-key--char-reduced-p (&optional _frame)
> (< (frame-char-width)
> (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
>
> (defun which-key--char-exact-p (&optional _frame)
> (= (frame-char-width)
> (/ (float (frame-pixel-width)) (window-total-width (frame-root-window)))))
>
> (defun which-key--width-or-percentage-to-width (width-or-percentage)
> "Return window total width.
> If WIDTH-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
> should be a percentage (a number between 0 and 1) out of the frame's width.
> More precisely, it should be a percentage out of the frame's root window's
> total width."
> (if (wholenump width-or-percentage)
I personally find wholenump confusing, due to the apparent ambiguity as
to what a "whole number" is (whether they are integers or naturals).
E.g. (wholenump -3) returns nil, because it is just an alias for
`natnump'. Hence I recommend using `natnump'.
> width-or-percentage
> (round (* width-or-percentage (window-total-width (frame-root-window))))))
>
> (defun which-key--height-or-percentage-to-height (height-or-percentage)
> "Return window total height.
> If HEIGHT-OR-PERCENTAGE is a whole number, return it unchanged. Otherwise, it
> should be a percentage (a number between 0 and 1) out of the frame's height.
> More precisely, it should be a percentage out of the frame's root window's
> total height."
> (if (wholenump height-or-percentage)
> height-or-percentage
> (round (* height-or-percentage (window-total-height (frame-root-window))))))
>
> (defun which-key--frame-size-changed-p ()
> "Non-nil if a change in frame size is detected."
> (let ((new-size (cons (frame-width) (frame-height))))
> (cond ((null which-key--previous-frame-size)
> (setq which-key--previous-frame-size new-size)
> nil)
> ((not (equal which-key--previous-frame-size new-size))
> (setq which-key--previous-frame-size new-size)))))
>
> ;;; Show/hide which-key buffer
>
> (defun which-key--hide-popup ()
> "This function is called to hide the which-key buffer."
> (unless (or which-key-persistent-popup
> (member real-this-command which-key--paging-functions))
> (setq which-key--last-try-2-loc nil)
> (setq which-key--pages-obj nil)
> (setq which-key--automatic-display nil)
> (setq which-key--prior-show-keymap-args nil)
> (when (and which-key-idle-secondary-delay which-key--secondary-timer-active)
> (which-key--start-timer))
> (which-key--lighter-restore)
> (which-key--hide-popup-ignore-command)))
>
> (defun which-key--hide-popup-ignore-command ()
> "`which-key--hide-popup' without the check of `real-this-command'."
> (cl-case which-key-popup-type
> ;; Not necessary to hide minibuffer
> ;; (minibuffer (which-key--hide-buffer-minibuffer))
> (side-window (which-key--hide-buffer-side-window))
> (frame (which-key--hide-buffer-frame))
> (custom (funcall which-key-custom-hide-popup-function))))
>
> (defun which-key--hide-popup-on-frame-size-change (&optional _)
> "Hide which-key popup if the frame is resized (to trigger a new popup)."
> (when (which-key--frame-size-changed-p)
> (which-key--hide-popup)))
>
> (defun which-key--hide-buffer-side-window ()
> "Hide which-key buffer when side-window popup is used."
> (when (buffer-live-p which-key--buffer)
> ;; in case which-key buffer was shown in an existing window, `quit-window'
> ;; will re-show the previous buffer, instead of closing the window
> (quit-windows-on which-key--buffer)
> (when (and which-key-preserve-window-configuration
> which-key--saved-window-configuration)
> (set-window-configuration which-key--saved-window-configuration)
> (setq which-key--saved-window-configuration nil))))
>
> (defun which-key--hide-buffer-frame ()
> "Hide which-key buffer when frame popup is used."
> (when (frame-live-p which-key--frame)
> (delete-frame which-key--frame)))
>
> (defun which-key--popup-showing-p ()
> (and (bufferp which-key--buffer)
> (or (window-live-p (get-buffer-window which-key--buffer))
> (let ((window (get-buffer-window which-key--buffer t)))
> (and (window-live-p window)
> (frame-visible-p (window-frame window)))))))
>
> (defun which-key--show-popup (act-popup-dim)
> "Show the which-key buffer.
> ACT-POPUP-DIM includes the dimensions, (height . width) of the
> buffer text to be displayed in the popup. Return nil if no window
> is shown, or if there is no need to start the closing timer."
> (when (and (> (car act-popup-dim) 0)
> (> (cdr act-popup-dim) 0))
> (cl-case which-key-popup-type
> ;; Not called for minibuffer
> ;; (minibuffer (which-key--show-buffer-minibuffer act-popup-dim))
> (side-window (which-key--show-buffer-side-window act-popup-dim))
> (frame (which-key--show-buffer-frame act-popup-dim))
> (custom (funcall which-key-custom-show-popup-function act-popup-dim)))))
>
> (defun which-key--fit-buffer-to-window-horizontally
> (&optional window &rest params)
> "Slightly modified version of `fit-buffer-to-window'.
> Use &rest params because `fit-buffer-to-window' has a different
> call signature in different emacs versions"
> (let ((fit-window-to-buffer-horizontally t)
> (window-min-height 1))
> (apply #'fit-window-to-buffer window params)))
>
> (defun which-key--show-buffer-side-window (act-popup-dim)
> "Show which-key buffer when popup type is side-window."
> (when (and which-key-preserve-window-configuration
> (not which-key--saved-window-configuration))
> (setq which-key--saved-window-configuration (current-window-configuration)))
> (let* ((height (car act-popup-dim))
> (width (cdr act-popup-dim))
> (alist
> (if which-key-allow-imprecise-window-fit
> `((window-width . ,(which-key--text-width-to-total width))
> (window-height . ,height)
> (side . ,which-key-side-window-location)
> (slot . ,which-key-side-window-slot))
> `((window-width . which-key--fit-buffer-to-window-horizontally)
> (window-height . (lambda (w) (fit-window-to-buffer w nil 1)))
> (side . ,which-key-side-window-location)
> (slot . ,which-key-side-window-slot)))))
> ;; Previously used `display-buffer-in-major-side-window' here, but
> ;; apparently that is meant to be an internal function. See emacs bug #24828
> ;; and advice given there.
> (cond
> ((eq which-key--multiple-locations t)
> ;; possibly want to switch sides in this case so we can't reuse the window
> (delete-windows-on which-key--buffer)
> (display-buffer-in-side-window which-key--buffer alist))
> ((get-buffer-window which-key--buffer)
> (display-buffer-reuse-window which-key--buffer alist))
> (t
> (display-buffer-in-side-window which-key--buffer alist)))))
>
> (defun which-key--show-buffer-frame (act-popup-dim)
> "Show which-key buffer when popup type is frame."
> (let* (;(orig-window (selected-window))
> (frame-height (+ (car act-popup-dim)
> (if (with-current-buffer which-key--buffer
> mode-line-format)
> 1
> 0)))
> ;; without adding 2, frame sometimes isn't wide enough for the buffer.
> ;; this is probably because of the fringes. however, setting fringes
> ;; sizes to 0 (instead of adding 2) didn't always make the frame wide
> ;; enough. don't know why it is so.
> (frame-width (+ (cdr act-popup-dim) 2))
> (new-window (if (and (frame-live-p which-key--frame)
> (eq which-key--buffer
> (window-buffer
> (frame-root-window which-key--frame))))
> (which-key--show-buffer-reuse-frame
> frame-height frame-width)
> (which-key--show-buffer-new-frame
> frame-height frame-width))))
> (when new-window
> ;; display successful
> (setq which-key--frame (window-frame new-window))
> new-window)))
>
> (defun which-key--show-buffer-new-frame (frame-height frame-width)
> "Helper for `which-key--show-buffer-frame'."
> (let* ((frame-params `((height . ,frame-height)
> (width . ,frame-width)
> ;; tell the window manager to respect the given sizes
> (user-size . t)
> ;; which-key frame doesn't need a minibuffer
> (minibuffer . nil)
> (name . "which-key")
> ;; no need for scroll bars in which-key frame
> (vertical-scroll-bars . nil)
> ;; (left-fringe . 0)
> ;; (right-fringe . 0)
> ;; (right-divider-width . 0)
> ;; make sure frame is visible
> (visibility . t)))
> (alist `((pop-up-frame-parameters . ,frame-params)))
> (orig-frame (selected-frame))
> (new-window (display-buffer-pop-up-frame which-key--buffer alist)))
> (when new-window
> ;; display successful
> (redirect-frame-focus (window-frame new-window) orig-frame)
> new-window)))
>
> (defun which-key--show-buffer-reuse-frame (frame-height frame-width)
> "Helper for `which-key--show-buffer-frame'."
> (let ((window
> (display-buffer-reuse-window
> which-key--buffer `((reusable-frames . ,which-key--frame)))))
> (when window
> ;; display successful
> (set-frame-size (window-frame window) frame-width frame-height)
> window)))
>
> ;;; Max dimension of available window functions
>
> (defun which-key--popup-max-dimensions ()
> "Return maximum dimension available for popup.
> Dimesion functions should return the maximum possible (height
> . width) of the intended popup. SELECTED-WINDOW-WIDTH is the
> width of currently active window, not the which-key buffer
> window."
> (cl-case which-key-popup-type
Should this be an cl-ecase?
> (minibuffer (which-key--minibuffer-max-dimensions))
> (side-window (which-key--side-window-max-dimensions))
> (frame (which-key--frame-max-dimensions))
> (custom (funcall which-key-custom-popup-max-dimensions-function
> (window-width)))))
>
> (defun which-key--minibuffer-max-dimensions ()
> "Return max-dimensions of minibuffer (height . width).
> Measured in lines and characters respectively."
> (cons
> ;; height
> (if (floatp max-mini-window-height)
> (floor (* (frame-text-lines)
> max-mini-window-height))
> max-mini-window-height)
> ;; width
> (max 0 (- (frame-text-cols) which-key-unicode-correction))))
>
> (defun which-key--side-window-max-dimensions ()
> "Return max-dimensions of the side-window popup.
> The return value should be (height . width) in lines and
> characters respectively."
> (cons
> ;; height
> (if (member which-key-side-window-location '(left right))
> ;; 1 is a kludge to make sure there is no overlap
> (- (frame-height) (window-text-height (minibuffer-window)) 1)
> ;; (window-mode-line-height which-key--window))
> ;; FIXME: change to something like
> ;; (min which-*-height (calculate-max-height))
> (which-key--height-or-percentage-to-height
> which-key-side-window-max-height))
> ;; width
> (max 0
> (- (if (memq which-key-side-window-location '(left right))
> (which-key--total-width-to-text
> (which-key--width-or-percentage-to-width
> which-key-side-window-max-width))
> (which-key--total-width-to-text
> (which-key--width-or-percentage-to-width
> 1.0)))
> which-key-unicode-correction))))
>
> (defun which-key--frame-max-dimensions ()
> "Return max-dimensions of the frame popup.
> The return value should be (height . width) in lines and
> characters respectively."
> (cons which-key-frame-max-height which-key-frame-max-width))
>
> ;;; Sorting functions
>
> (defun which-key--string< (a b &optional alpha)
> (let ((da (downcase a))
> (db (downcase b)))
> (cond
> ((and alpha (not which-key-sort-uppercase-first))
> (if (string-equal da db)
> (not (string-lessp a b))
> (string-lessp da db)))
> ((and alpha which-key-sort-uppercase-first)
> (if (string-equal da db)
> (string-lessp a b)
> (string-lessp da db)))
> ((not which-key-sort-uppercase-first)
> (let ((aup (not (string-equal da a)))
> (bup (not (string-equal db b))))
> (if (eq aup bup)
> (string-lessp a b)
> bup)))
> (t (string-lessp a b)))))
>
> (defun which-key--key-description< (a b &optional alpha)
> "Key sorting function.
> Used for `which-key-key-order' and `which-key-key-order-alpha'."
> (save-match-data
> (let* ((a (which-key--extract-key a))
> (b (which-key--extract-key b))
> (rngrgxp "^\\([^ ]+\\) \\.\\. [^ ]+")
> (a (if (string-match rngrgxp a) (match-string 1 a) a))
> (b (if (string-match rngrgxp b) (match-string 1 b) b))
> (aem? (string-equal a ""))
> (bem? (string-equal b ""))
> (a1? (= 1 (length a)))
> (b1? (= 1 (length b)))
> (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
> (asp? (string-match-p srgxp a))
> (bsp? (string-match-p srgxp b))
> (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
> (apr? (string-match-p prrgxp a))
> (bpr? (string-match-p prrgxp b))
> (afn? (string-match-p "<f[0-9]+>" a))
> (bfn? (string-match-p "<f[0-9]+>" b)))
> (cond ((or aem? bem?) (and aem? (not bem?)))
> ((and asp? bsp?)
> (if (string-equal (substring a 0 3) (substring b 0 3))
> (which-key--key-description<
> (substring a 3) (substring b 3) alpha)
> (which-key--string< a b alpha)))
> ((or asp? bsp?) asp?)
> ((and a1? b1?) (which-key--string< a b alpha))
> ((or a1? b1?) a1?)
> ((and afn? bfn?)
> (< (string-to-number
> (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" a))
> (string-to-number
> (replace-regexp-in-string "<f\\([0-9]+\\)>" "\\1" b))))
> ((or afn? bfn?) afn?)
> ((and apr? bpr?)
> (if (string-equal (substring a 0 2) (substring b 0 2))
> (which-key--key-description<
> (substring a 2) (substring b 2) alpha)
> (which-key--string< a b alpha)))
> ((or apr? bpr?) apr?)
> (t (which-key--string< a b alpha))))))
>
> (defsubst which-key-key-order-alpha (acons bcons)
> "Order key descriptions A and B.
> Order is lexicographic within a \"class\", where the classes and
> the ordering of classes are listed below.
>
> special (SPC,TAB,...) < single char < mod (C-,M-,...) < other.
> Sorts single characters alphabetically with lowercase coming
> before upper."
> (which-key--key-description< (car acons) (car bcons) t))
>
> (defsubst which-key-key-order (acons bcons)
> "Order key descriptions A and B.
> Order is lexicographic within a \"class\", where the classes and
> the ordering of classes are listed below.
>
> special (SPC,TAB,...) < single char < mod (C-,M-,...) < other."
> (which-key--key-description< (car acons) (car bcons)))
>
> (defsubst which-key-description-order (acons bcons)
> "Order descriptions of A and B.
> Uses `string-lessp' after applying lowercase."
> (string-lessp (downcase (cdr acons)) (downcase (cdr bcons))))
>
> (defsubst which-key--group-p (description)
> (or (string-equal description "prefix")
> (string-match-p "^group:" description)
> (keymapp (intern description))))
>
> (defun which-key-prefix-then-key-order (acons bcons)
> "Order prefixes before non-prefixes.
> Within these categories order using `which-key-key-order'."
> (let ((apref? (which-key--group-p (cdr acons)))
> (bpref? (which-key--group-p (cdr bcons))))
> (if (not (eq apref? bpref?))
> (and (not apref?) bpref?)
> (which-key-key-order acons bcons))))
>
> (defun which-key-prefix-then-key-order-reverse (acons bcons)
> "Order prefixes before non-prefixes.
> Within these categories order using `which-key-key-order'."
> (let ((apref? (which-key--group-p (cdr acons)))
> (bpref? (which-key--group-p (cdr bcons))))
> (if (not (eq apref? bpref?))
> (and apref? (not bpref?))
> (which-key-key-order acons bcons))))
>
> (defun which-key-local-then-key-order (acons bcons)
> "Order local bindings before non-local ones.
> Within these categories order using `which-key-key-order'."
> (let ((aloc? (which-key--local-binding-p acons))
> (bloc? (which-key--local-binding-p bcons)))
> (if (not (eq aloc? bloc?))
> (and aloc? (not bloc?))
> (which-key-key-order acons bcons))))
>
> ;;; Functions for retrieving and formatting keys
>
> (defsubst which-key--string-width (maybe-string)
> "If MAYBE-STRING is a string use `which-key--string-width' o/w return 0."
> (if (stringp maybe-string) (string-width maybe-string) 0))
>
> (defsubst which-key--butlast-string (str)
> (string-join (butlast (split-string str)) " "))
>
> (defun which-key--match-replacement (key-binding replacement)
> ;; these are mode specific ones to ignore. The mode specific case is
> ;; handled in the selection of alist
> (when (and (consp key-binding) (not (symbolp (car replacement))))
> (let ((key-regexp (caar replacement))
> (binding-regexp (cdar replacement))
> case-fold-search)
I think an explicit binding of nil would be nice here, from a
readability standpoint.
> (and (or (null key-regexp)
> (string-match-p key-regexp
> (car key-binding)))
> (or (null binding-regexp)
> (string-match-p binding-regexp
> (cdr key-binding)))))))
>
> (defsubst which-key--replace-in-binding (key-binding repl)
> (cond ((or (not (consp repl)) (null (cdr repl)))
> key-binding)
> ((functionp (cdr repl))
> (funcall (cdr repl) key-binding))
> ((consp (cdr repl))
> (cons
> (cond ((and (caar repl) (cadr repl))
> (replace-regexp-in-string
> (caar repl) (cadr repl) (car key-binding) t))
> ((cadr repl) (cadr repl))
> (t (car key-binding)))
> (cond ((and (cdar repl) (cddr repl))
> (replace-regexp-in-string
> (cdar repl) (cddr repl) (cdr key-binding) t))
> ((cddr repl) (cddr repl))
> (t (cdr key-binding)))))))
>
> (defun which-key--replace-in-repl-list-once (key-binding repls)
> (cl-dolist (repl repls)
> (when (which-key--match-replacement key-binding repl)
> (cl-return `(replaced . ,(which-key--replace-in-binding key-binding repl))))))
>
> (defun which-key--replace-in-repl-list-many (key-binding repls)
> (let (found)
> (dolist (repl repls)
> (when (which-key--match-replacement key-binding repl)
> (setq found 't)
Don't quote t.
> (setq key-binding (which-key--replace-in-binding key-binding repl))))
> (when found `(replaced . ,key-binding))))
>
> (defun which-key--maybe-replace (key-binding)
> "Use `which-key--replacement-alist' to maybe replace KEY-BINDING.
> KEY-BINDING is a cons cell of the form \(KEY . BINDING\) each of
> which are strings. KEY is of the form produced by `key-binding'."
> (let* ((replacer (if which-key-allow-multiple-replacements
> #'which-key--replace-in-repl-list-many
> #'which-key--replace-in-repl-list-once)))
> (pcase
Here also, `pcase-exhaustive'?
> (apply replacer
> (list key-binding
> (cdr-safe (assq major-mode which-key-replacement-alist))))
> (`(replaced . ,repl)
> (if which-key-allow-multiple-replacements
> (pcase (apply replacer (list repl which-key-replacement-alist))
> (`(replaced . ,repl) repl)
> ('() repl))
> repl))
> ('()
> (pcase (apply replacer (list key-binding which-key-replacement-alist))
> (`(replaced . ,repl) repl)
> ('() key-binding))))))
>
> (defsubst which-key--current-key-list (&optional key-str)
> (append (listify-key-sequence (which-key--current-prefix))
> (when key-str
> (listify-key-sequence (kbd key-str)))))
>
> (defsubst which-key--current-key-string (&optional key-str)
> (key-description (which-key--current-key-list key-str)))
>
> (defun which-key--local-binding-p (keydesc)
> (eq (which-key--safe-lookup-key-description
> (current-local-map)
> (which-key--current-key-string (car keydesc)))
> (intern (cdr keydesc))))
>
> (defun which-key--map-binding-p (map keydesc)
> "Does MAP contain KEYDESC = (key . binding)?"
> (or
> (when (bound-and-true-p evil-state)
> (let ((lookup
> (which-key--safe-lookup-key-description
> map
> (which-key--current-key-string
> (format "<%s-state> %s" evil-state (car keydesc))))))
> (or (eq lookup (intern (cdr keydesc)))
> (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command")))))
> (let ((lookup
> (which-key--safe-lookup-key-description
> map (which-key--current-key-string (car keydesc)))))
> (or (eq lookup (intern (cdr keydesc)))
> (and (keymapp lookup) (string= (cdr keydesc) "Prefix Command"))))))
>
> (defun which-key--maybe-get-prefix-title (keys)
> "KEYS is a string produced by `key-description'.
> A title is possibly returned using
> `which-key--prefix-title-alist'. An empty string is returned if
> no title exists."
> (cond
> ((not (string-equal keys ""))
> (let* ((title-res
> (cdr-safe (assoc-string keys which-key--prefix-title-alist)))
> (repl-res
> (cdr-safe (which-key--maybe-replace (cons keys ""))))
> (binding (key-binding (kbd keys)))
> (alternate (when (and binding (symbolp binding))
> (symbol-name binding))))
> (cond (title-res title-res)
> ((not (string-equal repl-res "")) repl-res)
See also `string-empty-p'.
> ((and (eq which-key-show-prefix 'echo) alternate)
> alternate)
> ((and (member which-key-show-prefix '(bottom top mode-line))
> (eq which-key-side-window-location 'bottom)
> echo-keystrokes)
> (if alternate alternate
> (concat "Following " keys)))
> (t ""))))
> (t "")))
>
> (defun which-key--propertize (string &rest properties)
> "Version of `propertize' that checks type of STRING."
> (when (stringp string)
> (apply #'propertize string properties)))
Is there any place where tolerating STRING being nil is used? It seems
to me like the kind of thing, that could easily let bugs slip by
unnoticed and pop up later.
>
> (defun which-key--propertize-key (key)
> "Add a face to KEY.
> If KEY contains any \"special keys\" defined in
> `which-key-special-keys' then truncate and add the corresponding
> `which-key-special-key-face'."
> (let ((key-w-face (which-key--propertize key 'face 'which-key-key-face))
> (regexp (concat "\\("
> (mapconcat #'identity which-key-special-keys
> "\\|")
> "\\)"))
> case-fold-search)
Here also binding nil explicitly would be nice.
> (save-match-data
> (if (and which-key-special-keys
> (string-match regexp key))
> (let ((beg (match-beginning 0)) (end (match-end 0)))
> (concat (substring key-w-face 0 beg)
> (which-key--propertize (substring key-w-face beg (1+ beg))
> 'face 'which-key-special-key-face)
> (substring key-w-face end
> (which-key--string-width key-w-face))))
> key-w-face))))
>
> (defsubst which-key--truncate-description (desc avl-width)
> "Truncate DESC description to `which-key-max-description-length'."
> (let* ((max which-key-max-description-length)
> (max (cl-etypecase max
> (null nil)
> (integer max)
> (float (truncate (* max avl-width)))
> (function (let ((val (funcall max avl-width)))
> (if (floatp val) (truncate val) val))))))
> (if (and max (> (length desc) max))
> (let ((dots (and (not (equal which-key-ellipsis ""))
> (which-key--propertize
> which-key-ellipsis 'face
> (get-text-property (1- (length desc)) 'face desc)))))
> (if dots
> (concat (substring desc 0 (- max (length dots))) dots)
> (substring desc 0 max)))
> desc)))
There are also tabs here that should be replaced.
>
> (defun which-key--highlight-face (description)
> "Return the highlight face for DESCRIPTION if it has one."
> (let (face)
> (dolist (el which-key-highlighted-command-list)
> (unless face
> (cond ((consp el)
> (when (string-match-p (car el) description)
> (setq face (cdr el))))
> ((stringp el)
> (when (string-match-p el description)
> (setq face 'which-key-highlighted-command-face)))
> (t
> (message "which-key: warning: element %s of \
> which-key-highlighted-command-list is not a string or a cons
> cell" el)))))
> face))
>
> (defun which-key--propertize-description
> (description group local hl-face &optional original-description)
> "Add face to DESCRIPTION.
> The face chosen depends on whether the description represents a
> group or a command. Also make some minor adjustments to the
> description string, like removing a \"group:\" prefix.
>
> ORIGINAL-DESCRIPTION is the description given by
> `describe-buffer-bindings'."
> (when description
> (let* ((desc description)
> (desc (if (string-match-p "^group:" desc)
> (substring desc 6) desc))
> (desc (if group (concat which-key-prefix-prefix desc) desc)))
> (make-text-button
> desc nil
> 'face (cond (hl-face hl-face)
> (group 'which-key-group-description-face)
> (local 'which-key-local-map-description-face)
> (t 'which-key-command-description-face))
> 'help-echo (cond
> ((and original-description
> (fboundp (intern original-description))
> (documentation (intern original-description))
> ;; tooltip-mode doesn't exist in emacs-nox
> (boundp 'tooltip-mode) tooltip-mode)
> (documentation (intern original-description)))
> ((and original-description
> (fboundp (intern original-description))
> (documentation (intern original-description))
> (let* ((doc (documentation
> (intern original-description)))
> (str (replace-regexp-in-string "\n" " " doc))
> (max (floor (* (frame-width) 0.8))))
> (if (> (length str) max)
> (concat (substring str 0 max) "...")
> str)))))))))
>
> (defun which-key--extract-key (key-str)
> "Pull the last key (or key range) out of KEY-STR."
> (save-match-data
> (let ((key-range-regexp "\\`.*\\([^ \t]+ \\.\\. [^ \t]+\\)\\'"))
> (if (string-match key-range-regexp key-str)
> (match-string 1 key-str)
> (car (last (split-string key-str " ")))))))
>
> (defun which-key--maybe-add-docstring (current original)
> "Maybe concat a docstring to CURRENT and return result.
> Specifically, do this if ORIGINAL is a command with a docstring
> and `which-key-show-docstrings' is non-nil. If
> `which-key-show-docstrings' is the symbol docstring-only, just
> return the docstring."
> (let* ((orig-sym (intern original))
> (doc (when (commandp orig-sym)
> (documentation orig-sym)))
> (doc (when doc
> (replace-regexp-in-string
> (concat "^\\(?::"
> (regexp-opt '("around" "override"
> "after" "after-until" "after-while"
> "before" "before-until" "before-while"
> "filter-args" "filter-return"))
> " advice: [^\n]+\n"
> "\\)+\n")
> "" doc)))
> (docstring (when doc
> (which-key--propertize (car (split-string doc "\n"))
> 'face 'which-key-docstring-face))))
> (cond ((not (and which-key-show-docstrings docstring))
> current)
> ((eq which-key-show-docstrings 'docstring-only)
> docstring)
> (t
> (format "%s %s" current docstring)))))
>
> (defun which-key--format-and-replace (unformatted &optional preserve-full-key)
> "Make list of key bindings with separators and descriptions.
> Take a list of (key . desc) cons cells in UNFORMATTED, add
> faces and perform replacements according to the three replacement
> alists. Returns a list (key separator description)."
> (let ((sep-w-face
> (which-key--propertize which-key-separator
> 'face 'which-key-separator-face))
> (local-map (current-local-map))
> (avl-width (cdr (which-key--popup-max-dimensions)))
> new-list)
> (dolist (key-binding unformatted)
> (let* ((keys (car key-binding))
> (orig-desc (cdr key-binding))
> (group (which-key--group-p orig-desc))
> (local (eq (which-key--safe-lookup-key-description
> local-map keys)
> (intern orig-desc)))
> (hl-face (which-key--highlight-face orig-desc))
> (key-binding (which-key--maybe-replace key-binding))
> (final-desc (which-key--propertize-description
> (cdr key-binding) group local hl-face orig-desc)))
> (when final-desc
> (setq final-desc
> (which-key--truncate-description
> (which-key--maybe-add-docstring final-desc orig-desc)
> avl-width)))
> (when (consp key-binding)
> (push
> (list (which-key--propertize-key
> (if preserve-full-key
> (car key-binding)
> (which-key--extract-key (car key-binding))))
> sep-w-face
> final-desc)
> new-list))))
> (nreverse new-list)))
>
> (defun which-key--compute-binding (binding)
> "Replace BINDING with remapped binding if it exists.
> Requires `which-key-compute-remaps' to be non-nil."
> (let (remap)
> (if (and which-key-compute-remaps
> (setq remap (command-remapping binding)))
> (copy-sequence (symbol-name remap))
> (copy-sequence (symbol-name binding)))))
Why the `copy-sequence' calls?
>
> (defun which-key--get-menu-item-binding (def)
> "Retrieve binding for menu-item"
> ;; see `keymap--menu-item-binding'
> (let* ((binding (nth 2 def))
> (plist (nthcdr 3 def))
> (filter (plist-get plist :filter)))
> (if filter (funcall filter binding) binding)))
>
> (defun which-key--get-keymap-bindings-1
> (keymap start &optional prefix filter all ignore-commands)
> "See `which-key--get-keymap-bindings'."
> (let ((bindings start)
> (prefix-map (if prefix (lookup-key keymap prefix) keymap)))
> (when (keymapp prefix-map)
> (map-keymap
> (lambda (ev def)
> (let* ((key (vconcat prefix (list ev)))
> (key-desc (key-description key)))
> (cond
> ((assoc key-desc bindings))
> ((and (listp ignore-commands) (symbolp def) (memq def ignore-commands)))
> ((or (string-match-p
> which-key--ignore-non-evil-keys-regexp key-desc)
> (eq ev 'menu-bar)))
> ((and (keymapp def)
> (string-match-p which-key--evil-keys-regexp key-desc)))
> ((and (keymapp def)
> (or all
> ;; event 27 is escape, so this will pick up meta
> ;; bindings and hopefully not too much more
> (and (numberp ev) (= ev 27))))
If you are not certain that EV is a number, you could also check both
type and value with a single (eql ev 27).
> (setq bindings
> (which-key--get-keymap-bindings-1
> keymap bindings key nil all ignore-commands)))
> (def
> (let* ((def (if (eq 'menu-item (car-safe def))
> (which-key--get-menu-item-binding def)
> def))
> (binding
> (cons key-desc
> (cond
> ((symbolp def) (which-key--compute-binding def))
> ((keymapp def) "prefix")
> ((eq 'lambda (car-safe def)) "lambda")
> ((eq 'closure (car-safe def)) "closure")
> ((stringp def) def)
> ((vectorp def) (key-description def))
> ((and (consp def)
> ;; looking for (STRING . DEFN)
> (stringp (car def)))
> (concat (when (keymapp (cdr-safe def))
> "group:")
> (car def)))
> (t "unknown")))))
> (when (or (null filter)
> (and (functionp filter)
> (funcall filter binding)))
> (push binding bindings)))))))
> prefix-map))
> bindings))
>
> (defun which-key--get-keymap-bindings
> (keymap &optional start prefix filter all evil)
> "Retrieve top-level bindings from KEYMAP.
> PREFIX limits bindings to those starting with this key
> sequence. START is a list of existing bindings to add to. If ALL
> is non-nil, recursively retrieve all bindings below PREFIX. If
> EVIL is non-nil, extract active evil bidings."
> (let ((bindings start)
> (ignore '(self-insert-command ignore ignore-event company-ignore))
> (evil-map
> (when (and evil (bound-and-true-p evil-local-mode))
> (lookup-key keymap (kbd (format "<%s-state>" evil-state))))))
> (when (keymapp evil-map)
> (setq bindings (which-key--get-keymap-bindings-1
> evil-map bindings prefix filter all ignore)))
> (which-key--get-keymap-bindings-1
> keymap bindings prefix filter all ignore)))
>
> (defun which-key--get-current-bindings (&optional prefix filter)
> "Generate a list of current active bindings."
> (let (bindings)
> (dolist (map (current-active-maps t) bindings)
> (when (cdr map)
> (setq bindings
> (which-key--get-keymap-bindings
> map bindings prefix filter))))))
>
> (defun which-key--get-bindings (&optional prefix keymap filter recursive)
> "Collect key bindings.
> If KEYMAP is nil, collect from current buffer using the current
> key sequence as a prefix. Otherwise, collect from KEYMAP. FILTER
> is a function to use to filter the bindings. If RECURSIVE is
> non-nil, then bindings are collected recursively for all prefixes."
> (let* ((unformatted
> (cond ((keymapp keymap)
> (which-key--get-keymap-bindings
> keymap nil prefix filter recursive))
> (keymap
> (error "%s is not a keymap" keymap))
> (t
> (which-key--get-current-bindings prefix filter)))))
> (when which-key-sort-order
> (setq unformatted
> (sort unformatted which-key-sort-order)))
> (which-key--format-and-replace unformatted recursive)))
>
> ;;; Functions for laying out which-key buffer pages
>
> (defun which-key--normalize-columns (columns)
> "Pad COLUMNS to the same length using empty strings."
> (let ((max-len (cl-reduce (lambda (a x) (max a (length x))) columns
> :initial-value 0)))
> (mapcar
> (lambda (c)
> (if (< (length c) max-len)
> (append c (make-list (- max-len (length c)) ""))
> c))
> columns)))
Generally speaking, has there been an attempt to use `:align-to' to
format the columns.
>
> (defsubst which-key--join-columns (columns)
> "Transpose columns into rows, concat rows into lines and rows into page."
> (let* ((padded (which-key--normalize-columns (nreverse columns)))
> (rows (apply #'cl-mapcar #'list padded)))
> (mapconcat (lambda (row) (mapconcat #'identity row " ")) rows "\n")))
>
> (defsubst which-key--max-len (keys index &optional initial-value)
> "Find the max length of the INDEX element in each of KEYS."
> (cl-reduce
> (lambda (x y) (max x (which-key--string-width (nth index y))))
> keys :initial-value (if initial-value initial-value 0)))
>
> (defun which-key--pad-column (col-keys avl-width)
> "Pad cells of COL-KEYS to AVL-WIDTH.
> Take a column of (key separator description) COL-KEYS,
> calculate the max width in the column and pad all cells out to
> that width."
> (let* ((col-key-width (+ which-key-add-column-padding
> (which-key--max-len col-keys 0)))
> (col-sep-width (which-key--max-len col-keys 1))
> (avl-width (- avl-width col-key-width col-sep-width))
> (col-desc-width (min avl-width
> (which-key--max-len
> col-keys 2
> which-key-min-column-description-width)))
> (col-width (+ col-key-width col-sep-width col-desc-width))
> (col-format (concat "%" (int-to-string col-key-width)
> "s%s%-" (int-to-string col-desc-width) "s")))
> (cons col-width
> (mapcar (lambda (k) (apply #'format col-format k))
> col-keys))))
More tabs here.
> (defun which-key--partition-list (n list)
> "Partition LIST into N-sized sublists."
> (let (res)
> (while list
> (setq res (cons (cl-subseq list 0 (min n (length list))) res)
See also `take'.
> list (nthcdr n list)))
> (nreverse res)))
>
> (defun which-key--list-to-pages (keys avl-lines avl-width)
> "Convert list of KEYS to columns based on dimensions AVL-LINES and AVL-WIDTH.
> Returns a `which-key--pages' object that holds the page strings,
> as well as metadata."
> (let ((cols-w-widths (mapcar (lambda (c) (which-key--pad-column c avl-width))
> (which-key--partition-list avl-lines keys)))
> (page-width 0) (n-pages 0) (n-keys 0) (n-columns 0)
> page-cols pages page-widths keys/page col)
> (if (> (apply #'max (mapcar #'car cols-w-widths)) avl-width)
Another idea would be (cl-reduce #'max cols-w-widths :key #'car), to
avoid the `apply' and consing a temporary list.
> ;; give up if no columns fit
> nil
> (while cols-w-widths
> ;; start new page
> (cl-incf n-pages)
> (setq col (pop cols-w-widths))
> (setq page-cols (list (cdr col)))
> (setq page-width (car col))
> (setq n-keys (length (cdr col)))
> (setq n-columns 1)
> ;; add additional columns as long as they fit
> (while (and cols-w-widths
> (or (null which-key-max-display-columns)
> (< n-columns which-key-max-display-columns))
> (<= (+ page-width 1 (caar cols-w-widths)) avl-width))
> (setq col (pop cols-w-widths))
> (push (cdr col) page-cols)
> (cl-incf page-width (1+ (car col)))
> (cl-incf n-keys (length (cdr col)))
> (cl-incf n-columns))
> (push (which-key--join-columns page-cols) pages)
> (push n-keys keys/page)
> (push page-width page-widths))
> (make-which-key--pages
> :pages (nreverse pages)
> :height (if (> n-pages 1) avl-lines (min avl-lines n-keys))
> :widths (nreverse page-widths)
> :keys/page (reverse keys/page)
> :page-nums (number-sequence 1 n-pages)
> :num-pages n-pages
> :total-keys (apply #'+ keys/page)))))
>
> (defun which-key--create-pages-1
> (keys available-lines available-width &optional min-lines vertical)
> "Create page strings using `which-key--list-to-pages'.
> Will try to find the best number of rows and columns using the
> given dimensions and the length and widths of ITEMS. Use VERTICAL
> if the ITEMS are laid out vertically and the number of columns
> should be minimized."
> (let ((result (which-key--list-to-pages
> keys available-lines available-width))
> (min-lines (or min-lines 0))
> found prev-result)
> (if (or (null result)
> vertical
> (> (which-key--pages-num-pages result) 1)
> (= 1 available-lines))
> result
> ;; simple search for a fitting page
> (while (and (> available-lines min-lines)
> (not found))
> (setq available-lines (- available-lines 1)
See also `1-' or `cl-decf'.
> prev-result result
> result (which-key--list-to-pages
> keys available-lines available-width)
> found (> (which-key--pages-num-pages result) 1)))
> (if found prev-result result))))
>
> (defun which-key--create-pages (keys &optional prefix-keys prefix-title)
> "Create page strings using `which-key--list-to-pages'.
> Will try to find the best number of rows and columns using the
> given dimensions and the length and wdiths of KEYS. SEL-WIN-WIDTH
> is the width of the live window."
> (let* ((max-dims (which-key--popup-max-dimensions))
> (max-lines (car max-dims))
> (max-width (cdr max-dims))
> (prefix-desc (key-description prefix-keys))
> (full-prefix (which-key--full-prefix prefix-desc))
> (prefix (when (eq which-key-show-prefix 'left)
> (+ 2 (which-key--string-width full-prefix))))
> (prefix-top-bottom (member which-key-show-prefix '(bottom top)))
> (avl-lines (if prefix-top-bottom (- max-lines 1) max-lines))
> (min-lines (min avl-lines which-key-min-display-lines))
> (avl-width (if prefix (- max-width prefix) max-width))
> (vertical (or (and (eq which-key-popup-type 'side-window)
> (member which-key-side-window-location '(left right)))
> (eq which-key-max-display-columns 1)))
Stray tabs to be found here!
> result)
> (setq result
> (which-key--create-pages-1
> keys avl-lines avl-width min-lines vertical))
> (when (and result
> (> (which-key--pages-num-pages result) 0))
> (setf (which-key--pages-prefix result) prefix-keys)
> (setf (which-key--pages-prefix-title result)
> (or prefix-title
> (which-key--maybe-get-prefix-title
> (key-description prefix-keys))))
> (when prefix-top-bottom
> ;; Add back the line earlier reserved for the page information.
Here as well.
> (setf (which-key--pages-height result) max-lines))
> (when (and (= (which-key--pages-num-pages result) 1)
> (> which-key-min-display-lines
> (which-key--pages-height result)))
> ;; result is shorter than requested, so we artificially increase the
> ;; height. See #325. Note this only has an effect if
> ;; `which-key-allow-imprecise-window-fit' is non-nil.
> (setf (which-key--pages-height result) which-key-min-display-lines))
> (which-key--debug-message "Frame height: %s
> Minibuffer height: %s
> Max dimensions: (%s,%s)
> Available for bindings: (%s,%s)
> Actual lines: %s" (frame-height) (window-text-height (minibuffer-window))
> max-lines max-width avl-lines avl-width (which-key--pages-height result))
> result)))
>
> (defun which-key--lighter-status ()
> "Possibly show number of keys and total in the mode line."
> (when which-key-show-remaining-keys
> (let ((n-shown (car (which-key--pages-keys/page which-key--pages-obj)))
> (n-tot (which-key--pages-total-keys which-key--pages-obj)))
> (setcar (cdr (assq 'which-key-mode minor-mode-alist))
> (format " WK: %s/%s keys" n-shown n-tot)))))
>
> (defun which-key--lighter-restore ()
> "Restore the lighter for which-key."
> (when which-key-show-remaining-keys
> (setcar (cdr (assq 'which-key-mode minor-mode-alist))
> which-key-lighter)))
>
> (defun which-key--echo (text)
> "Echo TEXT to minibuffer without logging."
> (let (message-log-max)
> (message "%s" text)))
>
> (defun which-key--next-page-hint (prefix-keys)
> "Return string for next page hint."
> (let* ((paging-key (concat prefix-keys " " which-key-paging-key))
> (paging-key-bound (eq 'which-key-C-h-dispatch
> (key-binding (kbd paging-key))))
> (key (key-description (vector help-char)))
> (key (if paging-key-bound
> (concat key " or " which-key-paging-key)
> key)))
> (when (and which-key-use-C-h-commands
> (not (equal (vector help-char)
> (vconcat (kbd prefix-keys)))))
> (which-key--propertize (format "[%s paging/help]" key)
> 'face 'which-key-note-face))))
>
> (eval-and-compile
> (if (fboundp 'universal-argument--description)
> (defalias 'which-key--universal-argument--description
> #'universal-argument--description)
> (defun which-key--universal-argument--description ()
> ;; Backport of the definition of universal-argument--description in
> ;; emacs25 on 2015-12-04
> (when prefix-arg
> (concat "C-u"
> (pcase prefix-arg
> (`(-) " -")
> (`(,(and (pred integerp) n))
> (let ((str ""))
> (while (and (> n 4) (= (mod n 4) 0))
> (setq str (concat str " C-u"))
> (setq n (/ n 4)))
> (if (= n 4) str (format " %s" prefix-arg))))
> (_ (format " %s" prefix-arg))))))))
Is this still necessary?
>
> (defun which-key--full-prefix (prefix-keys &optional -prefix-arg dont-prop-keys)
> "Return a description of the full key sequence up to now.
> Include prefix arguments."
> (let* ((left (eq which-key-show-prefix 'left))
> (prefix-arg (if -prefix-arg -prefix-arg prefix-arg))
> (str (concat
> (which-key--universal-argument--description)
> (when prefix-arg " ")
> prefix-keys))
> (dash (if (and (not (string= prefix-keys ""))
> (null left)) "-" "")))
> (if (or (eq which-key-show-prefix 'echo) dont-prop-keys)
> (concat str dash)
> (concat (which-key--propertize-key str)
> (which-key--propertize dash 'face 'which-key-key-face)))))
>
> (defun which-key--get-popup-map ()
> "Generate transient-map for use in the top level binding display."
> (unless which-key--automatic-display
> (let ((map (make-sparse-keymap)))
> (define-key map (kbd which-key-paging-key) #'which-key-C-h-dispatch)
> (when which-key-use-C-h-commands
> ;; Show next page even when C-h is pressed
> (define-key map (vector help-char) #'which-key-C-h-dispatch))
> map)))
>
> (defun which-key--process-page (pages-obj)
> "Add information to the basic list of key bindings.
> Include, if applicable, the current prefix, the name of the current
> prefix, and a page count."
> (let* ((page (car (which-key--pages-pages pages-obj)))
> (height (which-key--pages-height pages-obj))
> (n-pages (which-key--pages-num-pages pages-obj))
> (page-n (car (which-key--pages-page-nums pages-obj)))
> (prefix-desc (key-description (which-key--pages-prefix pages-obj)))
> (prefix-title (which-key--pages-prefix-title pages-obj))
> (full-prefix (which-key--full-prefix prefix-desc))
> (nxt-pg-hint (which-key--next-page-hint prefix-desc))
> ;; not used in left case
> (status-line
> (concat (which-key--propertize prefix-title 'face 'which-key-note-face)
> (when (< 1 n-pages)
> (which-key--propertize (format " (%s of %s)" page-n n-pages)
> 'face 'which-key-note-face)))))
> (pcase which-key-show-prefix
> (`left
Why the backtick? Nothing is being destructured here.
> (let* ((page-cnt (which-key--propertize (format "%s/%s" page-n n-pages)
> 'face 'which-key-separator-face))
> (first-col-width (+ 2 (max (which-key--string-width full-prefix)
> (which-key--string-width page-cnt))))
> (prefix (format (concat "%-" (int-to-string first-col-width) "s")
> full-prefix))
> (page-cnt (if (> n-pages 1)
> (format
> (concat "%-" (int-to-string first-col-width) "s")
> page-cnt)
> (make-string first-col-width 32)))
> lines first-line new-end)
> (if (= 1 height)
> (cons (concat prefix page) nil)
> (setq lines (split-string page "\n")
> first-line (concat prefix (car lines) "\n" page-cnt)
> new-end (concat "\n" (make-string first-col-width 32)))
> (cons
> (concat first-line (mapconcat #'identity (cdr lines) new-end))
> nil))))
> (`top
> (cons
> (concat (when (or (= 0 echo-keystrokes)
> (not (eq which-key-side-window-location 'bottom)))
> (concat full-prefix " "))
> status-line " " nxt-pg-hint "\n" page)
> nil))
> (`bottom
> (cons
> (concat page "\n"
> (when (or (= 0 echo-keystrokes)
> (not (eq which-key-side-window-location 'bottom)))
> (concat full-prefix " "))
> status-line " " nxt-pg-hint)
> nil))
> (`echo
> (cons page
> (lambda ()
> (which-key--echo
> (concat full-prefix (when prefix-desc " ")
> status-line (when status-line " ")
> nxt-pg-hint)))))
> (`mode-line
> (cons page
> (lambda ()
> (with-current-buffer which-key--buffer
> (setq-local mode-line-format
> (concat " " full-prefix
> " " status-line
> " " nxt-pg-hint))))))
> (_ (cons page nil)))))
>
> (defun which-key--show-page (&optional n)
> "Show current page.
> N changes the current page to the Nth page relative to the
> current one."
> (which-key--init-buffer) ;; in case it was killed
> (let ((prefix-keys (which-key--current-key-string))
> golden-ratio-mode)
> (if (null which-key--pages-obj)
> (message "%s- which-key can't show keys: There is not \
> enough space based on your settings and frame size." prefix-keys)
> (when n
> (setq which-key--pages-obj
> (which-key--pages-set-current-page which-key--pages-obj n)))
> (let ((page-echo (which-key--process-page which-key--pages-obj))
> (height (which-key--pages-height which-key--pages-obj))
> (width (car (which-key--pages-widths which-key--pages-obj))))
> (which-key--lighter-status)
> (if (eq which-key-popup-type 'minibuffer)
> (which-key--echo (car page-echo))
> (with-current-buffer which-key--buffer
> (erase-buffer)
> (insert (car page-echo))
> (goto-char (point-min)))
> (when (cdr page-echo) (funcall (cdr page-echo)))
> (which-key--show-popup (cons height width)))))
> ;; used for paging at top-level
> (if (fboundp 'set-transient-map)
> (set-transient-map (which-key--get-popup-map))
> (with-no-warnings
> (set-temporary-overlay-map (which-key--get-popup-map))))))
>
> ;;; Paging functions
>
> ;;;###autoload
> (defun which-key-reload-key-sequence (&optional key-seq)
> "Simulate entering the key sequence KEY-SEQ.
> KEY-SEQ should be a list of events as produced by
> `listify-key-sequence'. If nil, KEY-SEQ defaults to
> `which-key--current-key-list'. Any prefix arguments that were
> used are reapplied to the new key sequence."
> (let* ((key-seq (or key-seq (which-key--current-key-list)))
> (next-event (mapcar (lambda (ev) (cons t ev)) key-seq)))
> (setq prefix-arg current-prefix-arg
> unread-command-events next-event)))
>
> (defun which-key-turn-page (delta)
> "Show the next page of keys."
> (which-key-reload-key-sequence)
> (if which-key--last-try-2-loc
> (let ((which-key-side-window-location which-key--last-try-2-loc)
> (which-key--multiple-locations t))
> (which-key--show-page delta))
> (which-key--show-page delta))
> (which-key--start-paging-timer))
>
> ;;;###autoload
> (defun which-key-show-standard-help (&optional _)
> "Call the command in `which-key--prefix-help-cmd-backup'.
> Usually this is `describe-prefix-bindings'."
> (interactive)
> (let ((which-key-inhibit t)
> (popup-showing (which-key--popup-showing-p)))
> (which-key--hide-popup-ignore-command)
> (cond ((and (eq which-key--prefix-help-cmd-backup
> 'describe-prefix-bindings)
> ;; If the popup is not showing, we call
> ;; `describe-prefix-bindings' directly.
> popup-showing)
> ;; This is essentially what `describe-prefix-bindings' does. We can't
> ;; use this function directly, because the prefix will not be correct
> ;; when we enter using `which-key-C-h-dispatch'.
> (describe-bindings (kbd (which-key--current-key-string))))
> ((functionp which-key--prefix-help-cmd-backup)
> (funcall which-key--prefix-help-cmd-backup)))))
>
> ;;;###autoload
> (defun which-key-show-next-page-no-cycle ()
> "Show next page of keys or `which-key-show-standard-help'."
> (interactive)
> (let ((which-key-inhibit t))
> (if (which-key--on-last-page)
> (which-key-show-standard-help)
> (which-key-turn-page 1))))
>
> ;;;###autoload
> (defun which-key-show-previous-page-no-cycle ()
> "Show previous page of keys if one exists."
> (interactive)
> (let ((which-key-inhibit t))
> (unless (which-key--on-first-page)
> (which-key-turn-page -1))))
>
> ;;;###autoload
> (defun which-key-show-next-page-cycle (&optional _)
> "Show the next page of keys, cycling from end to beginning."
> (interactive)
> (let ((which-key-inhibit t))
> (which-key-turn-page 1)))
>
> ;;;###autoload
> (defun which-key-show-previous-page-cycle (&optional _)
> "Show the previous page of keys, cycling from beginning to end."
> (interactive)
> (let ((which-key-inhibit t))
> (which-key-turn-page -1)))
>
> ;;;###autoload
> (defun which-key-show-top-level (&optional _)
> "Show top-level bindings."
> (interactive)
> (which-key--create-buffer-and-show nil nil nil "Top-level bindings"))
>
> ;;;###autoload
> (defun which-key-show-major-mode (&optional all)
> "Show top-level bindings in the map of the current major mode.
> This function will also detect evil bindings made using
> `evil-define-key' in this map. These bindings will depend on the
> current evil state. "
> (interactive "P")
> (let ((map-sym (intern (format "%s-map" major-mode))))
> (if (and (boundp map-sym) (keymapp (symbol-value map-sym)))
> (which-key--show-keymap
> "Major-mode bindings"
> (symbol-value map-sym)
> (apply-partially #'which-key--map-binding-p (symbol-value map-sym))
> all)
> (message "which-key: No map named %s" map-sym))))
>
> ;;;###autoload
> (defun which-key-show-full-major-mode ()
> "Show all bindings in the map of the current major mode.
> This function will also detect evil bindings made using
> `evil-define-key' in this map. These bindings will depend on the
> current evil state. "
> (interactive)
> (which-key-show-major-mode t))
>
> ;;;###autoload
> (defun which-key-dump-bindings (prefix buffer-name)
> "Dump bindings from PREFIX into buffer named BUFFER-NAME.
> PREFIX should be a string suitable for `kbd'."
> (interactive "sPrefix: \nB")
> (let* ((buffer (get-buffer-create buffer-name))
> (keys (which-key--get-bindings (kbd prefix))))
> (with-current-buffer buffer
> (point-max)
> (save-excursion
> (dolist (key keys)
> (insert (apply #'format "%s%s%s\n" key)))))
> (switch-to-buffer-other-window buffer)))
>
> ;;;###autoload
> (defun which-key-undo-key (&optional _)
> "Undo last keypress and force which-key update."
> (interactive)
> (let* ((key-lst (butlast (which-key--current-key-list)))
> (which-key-inhibit t))
> (cond (which-key--prior-show-keymap-args
> (if (keymapp (cdr (car-safe which-key--prior-show-keymap-args)))
> (let ((args (pop which-key--prior-show-keymap-args)))
> (which-key--show-keymap (car args) (cdr args)))
> (which-key--hide-popup)))
> (key-lst
> (which-key-reload-key-sequence key-lst)
> (which-key--create-buffer-and-show (apply #'vector key-lst)))
> (t (setq which-key--automatic-display nil)
> (which-key-show-top-level)))))
> (defalias 'which-key-undo #'which-key-undo-key)
>
> (defun which-key-abort (&optional _)
> "Abort key sequence."
> (interactive)
> (let ((which-key-inhibit t))
> (which-key--hide-popup-ignore-command)
> (keyboard-quit)))
>
> (defun which-key-digit-argument (key)
> "Version of `digit-argument' for use in `which-key-C-h-map'."
> (interactive)
> (let ((last-command-event (string-to-char key)))
> (digit-argument key))
> (let ((current-prefix-arg prefix-arg))
> (which-key-reload-key-sequence)))
>
> (defun which-key-toggle-docstrings (&optional _)
> "Toggle the display of docstrings."
> (interactive)
> (unless (eq which-key-show-docstrings 'docstring-only)
> (setq which-key-show-docstrings (null which-key-show-docstrings)))
> (which-key-reload-key-sequence)
> (which-key--create-buffer-and-show (which-key--current-prefix)))
>
> ;;;###autoload
> (defun which-key-C-h-dispatch ()
> "Dispatch C-h commands by looking up key in `which-key-C-h-map'.
> This command is always accessible (from any prefix) if
> `which-key-use-C-h-commands' is non nil."
> (interactive)
> (cond ((and (not (which-key--popup-showing-p))
> which-key-show-early-on-C-h)
> (let ((current-prefix
> (butlast
> (listify-key-sequence
> (funcall which-key-this-command-keys-function)))))
> (which-key-reload-key-sequence current-prefix)
> (if which-key-idle-secondary-delay
> (which-key--start-timer which-key-idle-secondary-delay t)
> (which-key--start-timer 0.05 t))))
> ((not (which-key--popup-showing-p))
> (which-key-show-standard-help))
> (t
> (if (not (which-key--popup-showing-p))
> (which-key-show-standard-help)
> (let* ((prefix-keys (which-key--current-key-string))
> (full-prefix (which-key--full-prefix prefix-keys current-prefix-arg t))
> (prompt (concat (when (string-equal prefix-keys "")
> (which-key--propertize
> (concat " "
> (which-key--pages-prefix-title
> which-key--pages-obj))
> 'face 'which-key-note-face))
> full-prefix
> (which-key--propertize
> (substitute-command-keys
> which-key-C-h-map-prompt)
> 'face 'which-key-note-face)))
> (key (let ((key (read-key prompt)))
> (if (numberp key)
> (string key)
> (vector key))))
> (cmd (lookup-key which-key-C-h-map key))
> (which-key-inhibit t))
> (if cmd (funcall cmd key) (which-key-turn-page 0)))))))
>
> ;;; Update
>
> (defun which-key--any-match-p (regexps string)
> "Non-nil if any of REGEXPS match STRING."
> (catch 'match
> (dolist (regexp regexps)
> (when (string-match-p regexp string)
> (throw 'match t)))))
>
> (defun which-key--try-2-side-windows
> (bindings prefix-keys prefix-title loc1 loc2 &rest _ignore)
> "Try to show BINDINGS (PAGE-N) in LOC1 first.
> Only if no bindings fit fallback to LOC2."
> (let (pages1)
> (let ((which-key-side-window-location loc1)
> (which-key--multiple-locations t))
> (setq pages1 (which-key--create-pages
> bindings prefix-keys prefix-title)))
> (if pages1
> (progn
> (setq which-key--pages-obj pages1)
> (let ((which-key-side-window-location loc1)
> (which-key--multiple-locations t))
> (which-key--show-page))
> loc1)
> (let ((which-key-side-window-location loc2)
> (which-key--multiple-locations t))
> (setq which-key--pages-obj
> (which-key--create-pages bindings prefix-keys prefix-title))
> (which-key--show-page)
> loc2))))
>
> (defun which-key--read-keymap ()
> "Read keymap symbol from minibuffer."
> (intern
> (completing-read "Keymap: " obarray
> (lambda (m)
> (and (boundp m)
> (keymapp (symbol-value m))
> (not (equal (symbol-value m)
> (make-sparse-keymap)))))
> t
> (let ((sym (symbol-at-point)))
> (and (boundp sym)
> (keymapp (symbol-value sym))
> (symbol-name sym)))
> 'which-key-keymap-history)))
>
> ;;;###autoload
> (defun which-key-show-keymap (keymap &optional no-paging)
> "Show the top-level bindings in KEYMAP using which-key.
> KEYMAP is selected interactively from all available keymaps.
>
> If NO-PAGING is non-nil, which-key will not intercept subsequent
> keypresses for the paging functionality."
> (interactive (list (which-key--read-keymap)))
> (which-key--show-keymap (symbol-name keymap)
> (symbol-value keymap)
> nil nil no-paging))
>
> ;;;###autoload
> (defun which-key-show-full-keymap (keymap)
> "Show all bindings in KEYMAP using which-key.
> KEYMAP is selected interactively from all available keymaps."
> (interactive (list (which-key--read-keymap)))
> (which-key--show-keymap (symbol-name keymap)
> (symbol-value keymap)
> nil t))
>
> ;;;###autoload
> (defun which-key-show-minor-mode-keymap (&optional all)
> "Show the top-level bindings in KEYMAP using which-key.
> KEYMAP is selected interactively by mode in
> `minor-mode-map-alist'."
> (interactive)
> (let ((mode-sym
> (intern
> (completing-read
> "Minor Mode: "
> (mapcar #'car
> (cl-remove-if-not
> (lambda (entry)
> (and (symbol-value (car entry))
> (not (equal (cdr entry) (make-sparse-keymap)))))
> minor-mode-map-alist))
> nil t nil 'which-key-keymap-history))))
> (which-key--show-keymap (symbol-name mode-sym)
> (cdr (assq mode-sym minor-mode-map-alist))
> all)))
> ;;;###autoload
> (defun which-key-show-full-minor-mode-keymap ()
> "Show all bindings in KEYMAP using which-key.
> KEYMAP is selected interactively by mode in
> `minor-mode-map-alist'."
> (interactive)
> (which-key-show-minor-mode-keymap t))
>
> (defun which-key--show-keymap
> (keymap-name keymap &optional prior-args all no-paging filter)
> (when prior-args (push prior-args which-key--prior-show-keymap-args))
> (let ((bindings (which-key--get-bindings nil keymap filter all)))
> (if (null bindings)
> (message "which-key: No bindings found in %s" keymap-name)
> (cond ((listp which-key-side-window-location)
> (setq which-key--last-try-2-loc
> (apply #'which-key--try-2-side-windows
> bindings nil keymap-name
> which-key-side-window-location)))
> (t (setq which-key--pages-obj
> (which-key--create-pages bindings nil keymap-name))
> (which-key--show-page)))
> (unless no-paging
> (let* ((key (read-key))
> (key-desc (key-description (list key)))
> (next-def (lookup-key keymap (vector key))))
> (cond ((and which-key-use-C-h-commands
> (numberp key) (= key help-char))
> (which-key-C-h-dispatch))
> ((keymapp next-def)
> (which-key--hide-popup-ignore-command)
> (which-key--show-keymap
> (concat keymap-name " " key-desc)
> next-def
> (cons keymap-name keymap)))
> (t (which-key--hide-popup))))))))
>
> (defun which-key--evil-operator-filter (binding)
> (let ((def (intern (cdr binding))))
> (and (functionp def)
> (not (evil-get-command-property def :suppress-operator)))))
>
> (defun which-key--show-evil-operator-keymap ()
> (if which-key--inhibit-next-operator-popup
> (setq which-key--inhibit-next-operator-popup nil)
> (let ((keymap
> (make-composed-keymap (list evil-operator-shortcut-map
> evil-operator-state-map
> evil-motion-state-map))))
> (when (keymapp keymap)
> (let ((formatted-keys
> (which-key--get-bindings
> nil keymap #'which-key--evil-operator-filter)))
> (cond ((= (length formatted-keys) 0)
> (message "which-key: Keymap empty"))
> ((listp which-key-side-window-location)
> (setq which-key--last-try-2-loc
> (apply #'which-key--try-2-side-windows
> formatted-keys nil "evil operator/motion keys"
> which-key-side-window-location)))
> (t (setq which-key--pages-obj
> (which-key--create-pages
> formatted-keys
> nil "evil operator/motion keys"))
> (which-key--show-page)))))
> (let* ((key (read-key)))
You don't need a let* here.
> (when (member key '(?f ?F ?t ?T ?`))
Here too, one could use `memq' to be just as explicit as necessary.
> ;; these keys trigger commands that read the next char manually
> (setq which-key--inhibit-next-operator-popup t))
> (cond ((and which-key-use-C-h-commands (numberp key) (= key help-char))
> (which-key-C-h-dispatch))
> ((and (numberp key) (= key ?\C-\[))
> (which-key--hide-popup)
> (keyboard-quit))
> (t
> (which-key--hide-popup)
> (setq unread-command-events (vector key))))))))
>
> (defun which-key--create-buffer-and-show
> (&optional prefix-keys from-keymap filter prefix-title)
> "Fill `which-key--buffer' with key descriptions and reformat.
> Finally, show the buffer."
> (let ((start-time (current-time))
> (formatted-keys (which-key--get-bindings
> prefix-keys from-keymap filter))
> (prefix-desc (key-description prefix-keys)))
> (cond ((= (length formatted-keys) 0)
See also `null'.
> (message "%s- which-key: There are no keys to show" prefix-desc))
> ((listp which-key-side-window-location)
Or move this up and do a `consp' instead.
> (setq which-key--last-try-2-loc
> (apply #'which-key--try-2-side-windows
> formatted-keys prefix-keys prefix-title
> which-key-side-window-location)))
> (t (setq which-key--pages-obj
> (which-key--create-pages
> formatted-keys prefix-keys prefix-title))
> (which-key--show-page)))
> (which-key--debug-message
> "On prefix \"%s\" which-key took %.0f ms." prefix-desc
> (* 1000 (float-time (time-since start-time))))))
>
> (defun which-key--update ()
> "Function run by timer to possibly trigger `which-key--create-buffer-and-show'."
> (let ((prefix-keys (funcall which-key-this-command-keys-function))
> delay-time)
> (cond ((and (> (length prefix-keys) 0)
FWIW there is also `length>', though it won't really make a difference
here, and with length 0 it is basically equivalent to `consp'.
> (or (keymapp (key-binding prefix-keys))
> ;; Some keymaps are stored here like iso-transl-ctl-x-8-map
> (keymapp (which-key--safe-lookup-key
> key-translation-map prefix-keys))
> ;; just in case someone uses one of these
> (keymapp (which-key--safe-lookup-key
> function-key-map prefix-keys)))
> (not which-key-inhibit)
> (or (null which-key-allow-regexps)
> (which-key--any-match-p
> which-key-allow-regexps (key-description prefix-keys)))
> (or (null which-key-inhibit-regexps)
> (not
> (which-key--any-match-p
> which-key-inhibit-regexps (key-description prefix-keys))))
> ;; Do not display the popup if a command is currently being
> ;; executed
> (or (run-hook-with-args-until-success
> 'which-key-inhibit-display-hook)
> (null this-command))
> (let ((max-dim (which-key--popup-max-dimensions)))
> (> (min (car-safe max-dim) (cdr-safe max-dim)) 0)))
> (when (and (not (equal prefix-keys (which-key--current-prefix)))
> (or (null which-key-delay-functions)
> (null (setq delay-time
> (run-hook-with-args-until-success
> 'which-key-delay-functions
> (key-description prefix-keys)
> (length prefix-keys))))
> (sit-for delay-time)))
> (setq which-key--automatic-display t)
> (which-key--create-buffer-and-show prefix-keys)
> (when (and which-key-idle-secondary-delay
> (not which-key--secondary-timer-active))
> (which-key--start-timer which-key-idle-secondary-delay t))))
> ((and which-key-show-transient-maps
> ;; Assuming that if this is not true we're in
> ;; `which-key-show-top-level', which would then be overwritten.
> (> (length prefix-keys) 0)
> (keymapp overriding-terminal-local-map)
> ;; basic test for it being a hydra
> (not (eq (lookup-key overriding-terminal-local-map "\C-u")
> 'hydra--universal-argument)))
> (which-key--create-buffer-and-show
> nil overriding-terminal-local-map))
> ((and which-key-show-operator-state-maps
> (bound-and-true-p evil-state)
> (eq evil-state 'operator)
> (not (which-key--popup-showing-p)))
> (which-key--show-evil-operator-keymap))
> (which-key--automatic-display
> (which-key--hide-popup)))))
>
> ;;; Timers
>
> (defun which-key--start-timer (&optional delay secondary)
> "Activate idle timer to trigger `which-key--update'."
> (which-key--stop-timer)
> (setq which-key--secondary-timer-active secondary)
> (setq which-key--timer
> (run-with-idle-timer (or delay which-key-idle-delay)
> t #'which-key--update)))
>
> (defun which-key--stop-timer ()
> "Deactivate idle timer for `which-key--update'."
> (when which-key--timer (cancel-timer which-key--timer)))
>
> (defun which-key--start-paging-timer ()
> "Activate timer to restart which-key after paging."
> (when which-key--paging-timer (cancel-timer which-key--paging-timer))
> (which-key--stop-timer)
> (setq which-key--paging-timer
> (run-with-idle-timer
> 0.2 t (lambda ()
> (when (or (not (member real-last-command
> which-key--paging-functions))
> (and (< 0 (length (this-single-command-keys)))
> (not (equal (which-key--current-prefix)
> (funcall which-key-this-command-keys-function)))))
> (cancel-timer which-key--paging-timer)
> (if which-key-idle-secondary-delay
> ;; we haven't executed a command yet so the secandary
> ;; timer is more relevant here
> (which-key--start-timer which-key-idle-secondary-delay t)
> (which-key--start-timer)))))))
>
> (provide 'which-key)
> ;;; which-key.el ends here
Again, I hope I didn't repeat myself (setting aside this comment about
myself fearing that I am repeating myself), and I apologise if I'm too
pedantic, it is just interesting how much one can find if you look over
a longer file like this one again.
Also, in some cases, I didn't repeat my comment every time, but it might
be good to check if I didn't miss anything for some of the more general
points.
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-02 6:51 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Eli Zaretskii
@ 2024-03-02 21:36 ` Jeremy Bryant
2024-03-17 21:48 ` Incorporate package macrostep into Emacs core Jeremy Bryant via Emacs development discussions.
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-02 21:36 UTC (permalink / raw)
To: Eli Zaretskii
Cc: monnier, emacs-devel, j.j.oddie, stefan, stefankangas, jonas
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, j.j.oddie@gmail.com,
>> Stefan Kangas <stefan@marxist.se>, Stefan Kangas
>> <stefankangas@gmail.com>, Jonas Bernoulli <jonas@bernoul.li>, Eli
>> Zaretskii <eliz@gnu.org>
>> Date: Thu, 29 Feb 2024 20:44:56 +0000
>>
>> Given that macrostep is useful for Emacs Lisp macro development, would
>> there be interest to include in Emacs core?
>
> Sounds useful, so I'm in favor.
OK, I will continue to work towards it.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-01 23:26 ` Stefan Monnier
@ 2024-03-02 21:50 ` Jeremy Bryant
2024-03-02 22:51 ` Stefan Monnier
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-02 21:50 UTC (permalink / raw)
To: Stefan Monnier
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli, Eli Zaretskii
Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Hi Jeremy,
>
>> Which brings us to the other point suggested by Jonas - moving
>> development & maintenance of macrostep to NonGNU ELPA (on Savannah)
>> itself and archiving the previous fork.
>
> Not sure what you mean by "previous fork".
> [ BTW, I only now notice that the "upstream" is called "emacsorphanage". ]
>
> We can set the upstream to nil and change the headers to say that
> development takes place directly in `nongnu.git`, but I'm not sure it's
> really an improvement over the status quo.
macrostep was originally written by Jonathan Oddie, at
https://github.com/joddie/macrostep
but no longer maintained. It was forked and improved by Jonas Bernoulli
and others (inc. Stefan K.)
https://github.com/emacsorphanage/macrostep
My original request was to move the 'orphanage' repo to one of the
Savannah repos, in line with a discussion with Jonas:
> I think this is a good idea. I've considered this myself before, but
> never got around to it.
>
> There are other people that are much more qualified to maintain this
> package, and that certainly includes the core developers. Stefan Kangas
> (cced) has contributed to the fork before.
>
> I would like to hand of this package to someone else, preferably the
> core team. If we decide to go down that road, that would mean adding
> a branch to elpa.git and making that the official upstream repository,
> and archiving the repository in the orphanage.
>
> Cheers,
> Jonas
>
>> Jonathan Oddie has kindly proposed to sign the FSF paperwork once he
>> receives it.
>
> Not sure if I understand correctly. Is he already in the process of
> signing the paperwork, or is he waiting for someone to send him the form
> for that (in which case, I'd be happy to send it to him)?
The form has now been sent to Jonathan by Eli.
>> Given that macrostep is useful for Emacs Lisp macro development, would
>> there be interest to include in Emacs core?
>
> I don't have a strong opinion either way.
In another message on this list, Eli is in favour so I will continue
work on this, Emacs core rather than NonGNU.
>
>> If so I can volunteer to reach out to other recent contributors, beyond
>> the original author, for the same purpose?
>
> That would be awesome.
>
> % git log elpa/macrostep | grep Author: | sort | uniq -c | sort -n
> 1 Author: Chunyang Xu <xuchunyang56@gmail.com>
> 1 Author: duianto <duianto@users.noreply.github.com>
> 1 Author: John Wiegley <johnw@newartisans.com>
> 1 Author: Jonathan Oddie <jonxfield@gmail.com>
> 1 Author: Torbjörn Norinder <torbjorn@genunix.se>
> 2 Author: Fice T <fice-t@protonmail.com>
> 2 Author: Jon Oddie <jonxfield@gmail.com>
> 2 Author: Luís Borges de Oliveira <lbo@siscog.pt>
> 2 Author: Stefan Monnier <monnier@iro.umontreal.ca>
> 3 Author: George Kettleborough <g.kettleborough@member.fsf.org>
> 4 Author: Jonathan Oddie <j.j.oddie@gmail.com>
> 4 Author: Stefan Kangas <stefankangas@gmail.com>
> 12 Author: Luís Oliveira <loliveira@common-lisp.net>
> 13 Author: Jonas Bernoulli <jonas@bernoul.li>
> 80 Author: joddie <jonxfield@gmail.com>
>
> Of those, Luís Oliveira has signed some paperwork but not for Emacs, and
> Fice, Torbjörn, and "duianto" don't appear at all in the
> `copyright.list` so we'll need to either ask them to sign the paperwork,
> or look at their contributions (to see if they're small enough or have
> been replaced since).
I will start work on this.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-02 21:50 ` Jeremy Bryant
@ 2024-03-02 22:51 ` Stefan Monnier
2024-03-03 7:26 ` Adam Porter
2024-03-03 22:40 ` Jeremy Bryant
0 siblings, 2 replies; 86+ messages in thread
From: Stefan Monnier @ 2024-03-02 22:51 UTC (permalink / raw)
To: Jeremy Bryant
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Stefan Kangas,
Jonas Bernoulli, Eli Zaretskii
>> That would be awesome.
>>
>> % git log elpa/macrostep | grep Author: | sort | uniq -c | sort -n
>> 1 Author: Chunyang Xu <xuchunyang56@gmail.com>
>> 1 Author: duianto <duianto@users.noreply.github.com>
>> 1 Author: John Wiegley <johnw@newartisans.com>
>> 1 Author: Jonathan Oddie <jonxfield@gmail.com>
>> 1 Author: Torbjörn Norinder <torbjorn@genunix.se>
>> 2 Author: Fice T <fice-t@protonmail.com>
>> 2 Author: Jon Oddie <jonxfield@gmail.com>
>> 2 Author: Luís Borges de Oliveira <lbo@siscog.pt>
>> 2 Author: Stefan Monnier <monnier@iro.umontreal.ca>
>> 3 Author: George Kettleborough <g.kettleborough@member.fsf.org>
>> 4 Author: Jonathan Oddie <j.j.oddie@gmail.com>
>> 4 Author: Stefan Kangas <stefankangas@gmail.com>
>> 12 Author: Luís Oliveira <loliveira@common-lisp.net>
>> 13 Author: Jonas Bernoulli <jonas@bernoul.li>
>> 80 Author: joddie <jonxfield@gmail.com>
>>
>> Of those, Luís Oliveira has signed some paperwork but not for Emacs, and
>> Fice, Torbjörn, and "duianto" don't appear at all in the
>> `copyright.list` so we'll need to either ask them to sign the paperwork,
>> or look at their contributions (to see if they're small enough or have
>> been replaced since).
>
> I will start work on this.
Thanks. I have a fair bit of experience looking at those things to try
and whittle down the set of people we need to contact. Let me know if
I can help.
Stefan
PS: Also, if/when you send the form to those people, you can now include
an additional entry at the end so *you* get notified when the paperwork
is finally done (by default only the official Emacs maintainers get the
notification).
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-02 22:51 ` Stefan Monnier
@ 2024-03-03 7:26 ` Adam Porter
2024-03-03 7:51 ` Eli Zaretskii
2024-03-03 14:28 ` Stefan Monnier
2024-03-03 22:40 ` Jeremy Bryant
1 sibling, 2 replies; 86+ messages in thread
From: Adam Porter @ 2024-03-03 7:26 UTC (permalink / raw)
To: monnier; +Cc: eliz, emacs-devel, j.j.oddie, jb, jonas, stefan, stefankangas
> PS: Also, if/when you send the form to those people, you can now include
> an additional entry at the end so *you* get notified when the paperwork
> is finally done (by default only the official Emacs maintainers get the
> notification).
Is this documented anywhere? Or could you show me how to do this? I've
been having to wait for contributors to do the copyright assignment for
some of the packages I maintain on GNU ELPA, and I have to rely on the
contributor to tell me when their assignment is completed.
Also, am I supposed to be asking the Emacs maintainers to confirm when
this happens? Or to confirm when anyone offers a contribution that
would require CA? I understand that "the list" is confidential for
privacy reasons, and for some contributors I can look at emacs.git to
determine whether they've already done it, but otherwise a package
maintainer like myself doesn't always know, beyond what the contributor
says.
Thanks,
Adam
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 7:26 ` Adam Porter
@ 2024-03-03 7:51 ` Eli Zaretskii
2024-03-03 7:53 ` Adam Porter
2024-03-03 14:28 ` Stefan Monnier
1 sibling, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-03 7:51 UTC (permalink / raw)
To: Adam Porter
Cc: monnier, emacs-devel, j.j.oddie, jb, jonas, stefan, stefankangas
> Date: Sun, 3 Mar 2024 01:26:18 -0600
> Cc: eliz@gnu.org, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> jb@jeremybryant.net, jonas@bernoul.li, stefan@marxist.se,
> stefankangas@gmail.com
> From: Adam Porter <adam@alphapapa.net>
>
> Also, am I supposed to be asking the Emacs maintainers to confirm when
> this happens?
Yes, please.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 7:51 ` Eli Zaretskii
@ 2024-03-03 7:53 ` Adam Porter
2024-03-03 8:57 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Adam Porter @ 2024-03-03 7:53 UTC (permalink / raw)
To: Eli Zaretskii
Cc: monnier, emacs-devel, j.j.oddie, jb, jonas, stefan, stefankangas
On 3/3/24 01:51, Eli Zaretskii wrote:
>> Date: Sun, 3 Mar 2024 01:26:18 -0600
>> Cc: eliz@gnu.org, emacs-devel@gnu.org, j.j.oddie@gmail.com,
>> jb@jeremybryant.net, jonas@bernoul.li, stefan@marxist.se,
>> stefankangas@gmail.com
>> From: Adam Porter <adam@alphapapa.net>
>>
>> Also, am I supposed to be asking the Emacs maintainers to confirm when
>> this happens?
>
> Yes, please.
Ok, should I confirm here, or email certain people privately?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 7:53 ` Adam Porter
@ 2024-03-03 8:57 ` Eli Zaretskii
0 siblings, 0 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-03 8:57 UTC (permalink / raw)
To: Adam Porter
Cc: monnier, emacs-devel, j.j.oddie, jb, jonas, stefan, stefankangas
> Date: Sun, 3 Mar 2024 01:53:53 -0600
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> jb@jeremybryant.net, jonas@bernoul.li, stefan@marxist.se,
> stefankangas@gmail.com
> From: Adam Porter <adam@alphapapa.net>
>
> On 3/3/24 01:51, Eli Zaretskii wrote:
> >> Date: Sun, 3 Mar 2024 01:26:18 -0600
> >> Cc: eliz@gnu.org, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> >> jb@jeremybryant.net, jonas@bernoul.li, stefan@marxist.se,
> >> stefankangas@gmail.com
> >> From: Adam Porter <adam@alphapapa.net>
> >>
> >> Also, am I supposed to be asking the Emacs maintainers to confirm when
> >> this happens?
> >
> > Yes, please.
>
> Ok, should I confirm here, or email certain people privately?
It doesn't matter. Your call. If you email privately, use the
addresses of the Emacs maintainers.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 7:26 ` Adam Porter
2024-03-03 7:51 ` Eli Zaretskii
@ 2024-03-03 14:28 ` Stefan Monnier
2024-03-04 11:25 ` Ihor Radchenko
1 sibling, 1 reply; 86+ messages in thread
From: Stefan Monnier @ 2024-03-03 14:28 UTC (permalink / raw)
To: Adam Porter; +Cc: eliz, emacs-devel, j.j.oddie, jb, jonas, stefan, stefankangas
>> PS: Also, if/when you send the form to those people, you can now include
>> an additional entry at the end so *you* get notified when the paperwork
>> is finally done (by default only the official Emacs maintainers get the
>> notification).
> Is this documented anywhere?
It's fairly new, and things don't move fast on that side.
> Or could you show me how to do this?
See the last element in the example below.
> I've been having to wait for contributors to do the copyright
> assignment for some of the packages I maintain on GNU ELPA, and I have
> to rely on the contributor to tell me when their assignment
> is completed.
I know, which is why I have negotiated this new element 🙂
> Also, am I supposed to be asking the Emacs maintainers to confirm when this
> happens?
If by "this" you mean the contributor telling you that it's completed,
then yes. But with the new thingy you should receive that confirmation
directly from the copyright clerk at the same time as the
contributor does, in which case you don't need to.
> I understand that "the list" is confidential for privacy reasons,
Yup, I still haven't managed to negotiate a solution for that 🙁
Stefan
Please email the following information to assign@gnu.org, and we will send you
the assignment form for your past and future changes.
Please use your full legal name (in ASCII characters) as the subject line of
the message.
----------------------------------------------------------------------
REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES
[What is the name of the program or package you're contributing to?]
Emacs
[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]
[Do you have an employer who might have a basis to claim to own your changes?
Do you attend a school which might make such a claim?]
[For the copyright registration, what country are you a citizen of?]
[What year were you born?]
[Please write your email address here.]
[Please write your postal address here.]
[Which files have you changed so far, and which new files have you written
so far?]
[Additional people we should notify about the progress of the assignment.]
Stefan Monnier <monnier@gnu.org>
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-02 22:51 ` Stefan Monnier
2024-03-03 7:26 ` Adam Porter
@ 2024-03-03 22:40 ` Jeremy Bryant
2024-03-04 12:00 ` Eli Zaretskii
1 sibling, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-03 22:40 UTC (permalink / raw)
To: Stefan Monnier
Cc: emacs-devel@gnu.org, j.j.oddie, Stefan Kangas, Jonas Bernoulli,
Eli Zaretskii
>> If so I can volunteer to reach out to other recent contributors, beyond
>> the original author, for the same purpose?
>>> That would be awesome.
>>>
>>> % git log elpa/macrostep | grep Author: | sort | uniq -c | sort -n
>>> 1 Author: Chunyang Xu <xuchunyang56@gmail.com>
>>> 1 Author: duianto <duianto@users.noreply.github.com>
>>> 1 Author: John Wiegley <johnw@newartisans.com>
>>> 1 Author: Jonathan Oddie <jonxfield@gmail.com>
>>> 1 Author: Torbjörn Norinder <torbjorn@genunix.se>
>>> 2 Author: Fice T <fice-t@protonmail.com>
>>> 2 Author: Jon Oddie <jonxfield@gmail.com>
>>> 2 Author: Luís Borges de Oliveira <lbo@siscog.pt>
>>> 2 Author: Stefan Monnier <monnier@iro.umontreal.ca>
>>> 3 Author: George Kettleborough <g.kettleborough@member.fsf.org>
>>> 4 Author: Jonathan Oddie <j.j.oddie@gmail.com>
>>> 4 Author: Stefan Kangas <stefankangas@gmail.com>
>>> 12 Author: Luís Oliveira <loliveira@common-lisp.net>
>>> 13 Author: Jonas Bernoulli <jonas@bernoul.li>
>>> 80 Author: joddie <jonxfield@gmail.com>
>>>
>>> Of those, Luís Oliveira has signed some paperwork but not for Emacs, and
>>> Fice, Torbjörn, and "duianto" don't appear at all in the
>>> `copyright.list` so we'll need to either ask them to sign the paperwork,
>>> or look at their contributions (to see if they're small enough or have
>>> been replaced since).
>>
>> I will start work on this.
>
> Thanks. I have a fair bit of experience looking at those things to try
> and whittle down the set of people we need to contact. Let me know if
> I can help.
>
>
> Stefan
OK, here are some questions on the interpretation of the above.
> 1 Author: duianto <duianto@users.noreply.github.com>
1-line change 7y ago. 2016. A typo fix.
No apparent usable email address
Can we assume no need to chase, equivalent to:
\"Copyright-paperwork-exempt: yes\"
> 2 Author: Fice T <fice-t@protonmail.com>
1 change 7y ago, 1 line
1 change 7y ago, -5 lines +7lines
Small changes, can we assume no need to chase?
> 1 Author: Torbjörn Norinder <torbjorn@genunix.se>
more than 15 lines, 7m ago, apparently non-trivial patch related to macroexpand-1
To contact, I will do this
> 2 Author: Luís Borges de Oliveira <lbo@siscog.pt>
> 12 Author: Luís Oliveira <loliveira@common-lisp.net>
To contact, I will do this
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 14:28 ` Stefan Monnier
@ 2024-03-04 11:25 ` Ihor Radchenko
2024-03-04 15:35 ` Stefan Monnier
0 siblings, 1 reply; 86+ messages in thread
From: Ihor Radchenko @ 2024-03-04 11:25 UTC (permalink / raw)
To: Stefan Monnier
Cc: Adam Porter, eliz, emacs-devel, j.j.oddie, jb, jonas, stefan,
stefankangas
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> PS: Also, if/when you send the form to those people, you can now include
>>> an additional entry at the end so *you* get notified when the paperwork
>>> is finally done (by default only the official Emacs maintainers get the
>>> notification).
>> Is this documented anywhere?
>
> It's fairly new, and things don't move fast on that side.
>
>> Or could you show me how to do this?
>
> See the last element in the example below.
> ...
> [Additional people we should notify about the progress of the assignment.]
> Stefan Monnier <monnier@gnu.org>
Is there any reason why this variant of the form is not linked from
CONTRIBUTE file in Emacs repository? The link there points to
https://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-assign.future
that does not have the added passage.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-03 22:40 ` Jeremy Bryant
@ 2024-03-04 12:00 ` Eli Zaretskii
2024-03-11 22:47 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-04 12:00 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel, j.j.oddie, stefankangas, jonas
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, j.j.oddie@gmail.com,
> Stefan Kangas <stefankangas@gmail.com>, Jonas Bernoulli
> <jonas@bernoul.li>, Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 03 Mar 2024 22:40:16 +0000
>
> > 1 Author: duianto <duianto@users.noreply.github.com>
> 1-line change 7y ago. 2016. A typo fix.
> No apparent usable email address
> Can we assume no need to chase, equivalent to:
> \"Copyright-paperwork-exempt: yes\"
Yes.
> > 2 Author: Fice T <fice-t@protonmail.com>
> 1 change 7y ago, 1 line
> 1 change 7y ago, -5 lines +7lines
> Small changes, can we assume no need to chase?
Yes.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-04 11:25 ` Ihor Radchenko
@ 2024-03-04 15:35 ` Stefan Monnier
0 siblings, 0 replies; 86+ messages in thread
From: Stefan Monnier @ 2024-03-04 15:35 UTC (permalink / raw)
To: Ihor Radchenko
Cc: Adam Porter, eliz, emacs-devel, j.j.oddie, jb, jonas, stefan,
stefankangas
> Is there any reason why this variant of the form is not linked from
> CONTRIBUTE file in Emacs repository? The link there points to
> https://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-assign.future
> that does not have the added passage.
As the famous wise man said:
It's fairly new, and things don't move fast on that side.
IOW, please report it to the gnulib guys.
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs or NonGNU ELPA?
2024-03-04 12:00 ` Eli Zaretskii
@ 2024-03-11 22:47 ` Jeremy Bryant
[not found] ` <jwvsf0wqrqg.fsf-monnier+emacs@gnu.org>
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-11 22:47 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel, j.j.oddie, stefankangas, jonas
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, j.j.oddie@gmail.com,
>> Stefan Kangas <stefankangas@gmail.com>, Jonas Bernoulli
>> <jonas@bernoul.li>, Eli Zaretskii <eliz@gnu.org>
>> Date: Sun, 03 Mar 2024 22:40:16 +0000
>>
>> > 1 Author: duianto <duianto@users.noreply.github.com>
>> 1-line change 7y ago. 2016. A typo fix.
>> No apparent usable email address
>> Can we assume no need to chase, equivalent to:
>> \"Copyright-paperwork-exempt: yes\"
>
> Yes.
>
>> > 2 Author: Fice T <fice-t@protonmail.com>
>> 1 change 7y ago, 1 line
>> 1 change 7y ago, -5 lines +7lines
>> Small changes, can we assume no need to chase?
>
> Yes.
As an update, having contacted them, the previously missing 3 material contributors
have kindly now confirmed they sent the request for the FSF paperwork.
Jonathan Oddie - original author.
Torbjörn Norinder <torbjorn@genunix.se>
Luís Oliveira luismbo@gmail.com
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-02 21:36 ` Jeremy Bryant
@ 2024-03-17 21:48 ` Jeremy Bryant via Emacs development discussions.
2024-03-18 9:09 ` Philip Kaludercic
2024-03-18 12:48 ` Eli Zaretskii
0 siblings, 2 replies; 86+ messages in thread
From: Jeremy Bryant via Emacs development discussions. @ 2024-03-17 21:48 UTC (permalink / raw)
To: Eli Zaretskii
Cc: monnier, emacs-devel, j.j.oddie, stefan, stefankangas, jonas
[-- Attachment #1: Type: text/plain, Size: 719 bytes --]
>>> Given that macrostep is useful for Emacs Lisp macro development, would
>>> there be interest to include in Emacs core?
>>
>> Sounds useful, so I'm in favor.
>
> OK, I will continue to work towards it.
Eli, Stefan,
As I wait for the FSF paperwork to be completed for several
contributors:
Manual?
Should the documentation for macrostep be included in the Emacs Lisp
manual section Macros? Or a more suitable location? I volunteer to
write the manual sections.
Code?
The main file is attached for convenience, from the orphanage upstream
(https://github.com/emacsorphanage/macrostep).
Are any changes needed before this is merged into Emacs?
I volunteer to write some code towards this, please let me know.
[-- Attachment #2: macrostep.el --]
[-- Type: application/emacs-lisp, Size: 48295 bytes --]
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-17 21:48 ` Incorporate package macrostep into Emacs core Jeremy Bryant via Emacs development discussions.
@ 2024-03-18 9:09 ` Philip Kaludercic
2024-03-18 23:03 ` Jeremy Bryant
2024-03-18 12:48 ` Eli Zaretskii
1 sibling, 1 reply; 86+ messages in thread
From: Philip Kaludercic @ 2024-03-18 9:09 UTC (permalink / raw)
To: Jeremy Bryant via Emacs development discussions.
Cc: Eli Zaretskii, Jeremy Bryant, monnier, j.j.oddie, stefan,
stefankangas, jonas
Jeremy Bryant via "Emacs development discussions." <emacs-devel@gnu.org>
writes:
>>>> Given that macrostep is useful for Emacs Lisp macro development, would
>>>> there be interest to include in Emacs core?
>>>
>>> Sounds useful, so I'm in favor.
>>
>> OK, I will continue to work towards it.
>
> Eli, Stefan,
>
> As I wait for the FSF paperwork to be completed for several
> contributors:
>
> Manual?
> Should the documentation for macrostep be included in the Emacs Lisp
> manual section Macros? Or a more suitable location? I volunteer to
> write the manual sections.
>
> Code?
> The main file is attached for convenience, from the orphanage upstream
> (https://github.com/emacsorphanage/macrostep).
> Are any changes needed before this is merged into Emacs?
> I volunteer to write some code towards this, please let me know.
I have a few comments:
>
> ;;; macrostep.el --- Interactive macro expander -*- lexical-binding: t; -*-
>
> ;; Copyright (C) 2012-2015 Jon Oddie
> ;; Copyright (C) 2020-2023 Free Software Foundation, Inc.
I guess this should be updated until 2024.
> ;; Author: Jon Oddie <j.j.oddie@gmail.com>
> ;; Url: https://github.com/emacsorphanage/macrostep
> ;; Keywords: lisp, languages, macro, debugging
>
> ;; Package-Version: 0.9.2
> ;; Package-Requires: ((cl-lib "0.5"))
>
> ;; SPDX-License-Identifier: GPL-3.0-or-later
>
> ;; This file is free software: you can redistribute it and/or modify
> ;; it under the terms of the GNU General Public License as published
> ;; by the Free Software Foundation, either version 3 of the License,
> ;; or (at your option) any later version.
> ;;
> ;; This file is distributed in the hope that it will be useful,
> ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
> ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> ;; GNU General Public License for more details.
> ;;
> ;; You should have received a copy of the GNU General Public License
> ;; along with this file. If not, see <https://www.gnu.org/licenses/>.
>
> ;;; Commentary:
>
> ;; `macrostep' is an Emacs minor mode for interactively stepping through
> ;; the expansion of macros in Emacs Lisp source code. It lets you see
> ;; exactly what happens at each step of the expansion process by
> ;; pretty-printing the expanded forms inline in the source buffer, which is
> ;; temporarily read-only while macro expansions are visible. You can
> ;; expand and collapse macro forms one step at a time, and evaluate or
> ;; instrument the expansions for debugging with Edebug as normal (but see
> ;; "Bugs and known limitations", below). Single-stepping through the
> ;; expansion is particularly useful for debugging macros that expand into
> ;; another macro form. These can be difficult to debug with Emacs'
> ;; built-in `macroexpand', which continues expansion until the top-level
> ;; form is no longer a macro call.
>
> ;; Both globally-visible macros as defined by `defmacro' and local macros
> ;; bound by `(cl-)macrolet' or another macro-defining form can be expanded.
> ;; Within macro expansions, calls to macros and compiler macros are
> ;; fontified specially: macro forms using `macrostep-macro-face', and
> ;; functions with compiler macros using `macrostep-compiler-macro-face'.
> ;; Uninterned symbols (gensyms) are fontified based on which step in the
> ;; expansion created them, to distinguish them both from normal symbols and
> ;; from other gensyms with the same print name.
>
> ;; As of version 0.9, it is also possible to extend `macrostep' to work
> ;; with other languages with macro systems in addition to Emacs Lisp. An
> ;; extension for Common Lisp (via SLIME) is in the works; contributions for
> ;; other languages are welcome. See "Extending macrostep" below for
> ;; details.
>
>
> ;; 1 Key-bindings and usage
> ;; ========================
>
> ;; The standard keybindings in `macrostep-mode' are the following:
>
> ;; e, =, RET : expand the macro form following point one step
> ;; c, u, DEL : collapse the form following point
> ;; q, C-c C-c: collapse all expanded forms and exit macrostep-mode
> ;; n, TAB : jump to the next macro form in the expansion
> ;; p, M-TAB : jump to the previous macro form in the expansion
>
> ;; It's not very useful to enable and disable macrostep-mode directly.
> ;; Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
> ;; for example C-c e:
>
> ;; ,----
> ;; | (define-key emacs-lisp-mode-map (kbd "C-c e") 'macrostep-expand)
> ;; `----
>
> ;; You can then enter macrostep-mode and expand a macro form completely
> ;; by typing `C-c e e e ...' as many times as necessary.
>
> ;; Exit macrostep-mode by typing `q' or `C-c C-c', or by successively
> ;; typing `c' to collapse all surrounding expansions.
>
>
> ;; 2 Customization options
> ;; =======================
>
> ;; Type `M-x customize-group RET macrostep RET' to customize options and
> ;; faces.
>
> ;; To display macro expansions in a separate window, instead of inline in
> ;; the source buffer, customize `macrostep-expand-in-separate-buffer' to
> ;; `t'. The default is `nil'. Whichever default behavior is selected,
> ;; the alternative behavior can be obtained temporarily by giving a
> ;; prefix argument to `macrostep-expand'.
>
> ;; To have `macrostep' ignore compiler macros, customize
> ;; `macrostep-expand-compiler-macros' to `nil'. The default is `t'.
>
> ;; Customize the faces `macrostep-macro-face',
> ;; `macrostep-compiler-macro-face', and `macrostep-gensym-1' through
> ;; `macrostep-gensym-5' to alter the appearance of macro expansions.
>
>
> ;; 3 Locally-bound macros
> ;; ======================
>
> ;; As of version 0.9, `macrostep' can expand calls to a locally-bound
> ;; macro, whether defined by a surrounding `(cl-)macrolet' form, or by
> ;; another macro-defining macro. In other words, it is possible to
> ;; expand the inner `local-macro' forms in both the following examples,
> ;; whether `local-macro' is defined by an enclosing `cl-macrolet' --
>
> ;; ,----
> ;; | (cl-macrolet ((local-macro (&rest args)
> ;; | `(expansion of ,args)))
> ;; | (local-macro (do-something)))
> ;; `----
>
> ;; -- or by a macro which expands into `cl-macrolet', provided that its
> ;; definition of macro is evaluated prior to calling `macrostep-expand':
>
> ;; ,----
> ;; | (defmacro with-local-macro (&rest body)
> ;; | `(cl-macrolet ((local-macro (&rest args)
> ;; | `(expansion of ,args)))
> ;; | ,@body))
> ;; |
> ;; | (with-local-macro
> ;; | (local-macro (do something (else)))
> ;; `----
>
> ;; See the `with-js' macro in Emacs's `js.el' for a real example of the
> ;; latter kind of macro.
>
> ;; Expansion of locally-bound macros is implemented by instrumenting
> ;; Emacs Lisp's macro-expander to capture the environment at point. A
> ;; similar trick is used to detect macro- and compiler-macro calls within
> ;; expanded text so that they can be fontified accurately.
>
>
> ;; 4 Expanding sub-forms
> ;; =====================
>
> ;; By moving point around in the macro expansion using
> ;; `macrostep-next-macro' and `macrostep-prev-macro' (bound to the `n'
> ;; and `p' keys), it is possible to expand other macro calls within the
> ;; expansion before expanding the outermost form. This can sometimes be
> ;; useful, although it does not correspond to the real order of macro
> ;; expansion in Emacs Lisp, which proceeds by fully expanding the outer
> ;; form to a non-macro form before expanding sub-forms.
>
> ;; The main reason to expand sub-forms out of order is to help with
> ;; debugging macros which programmatically expand their arguments in
> ;; order to rewrite them. Expanding the arguments of such a macro lets
> ;; you visualise what the macro definition would compute via
> ;; `macroexpand-all'.
>
>
> ;; 5 Extending macrostep for other languages
> ;; =========================================
>
> ;; Since version 0.9, it is possible to extend macrostep to work with
> ;; other languages besides Emacs Lisp. In typical Emacs fashion, this is
> ;; implemented by setting buffer-local variables to different function
> ;; values. Six buffer-local variables define the language-specific part
> ;; of the implementation:
>
> ;; - `macrostep-sexp-bounds-function'
> ;; - `macrostep-sexp-at-point-function'
> ;; - `macrostep-environment-at-point-function'
> ;; - `macrostep-expand-1-function'
> ;; - `macrostep-print-function'
> ;; - `macrostep-macro-form-p-function'
>
> ;; Typically, an implementation for another language would set these
> ;; variables in a major-mode hook. See the docstrings of each variable
> ;; for details on how each one is called and what it should return. At a
> ;; minimum, another language implementation needs to provide
> ;; `macrostep-sexp-at-point-function', `macrostep-expand-1-function', and
> ;; `macrostep-print-function'. Lisp-like languages may be able to reuse
> ;; the default `macrostep-sexp-bounds-function' if they provide another
> ;; implementation of `macrostep-macro-form-p-function'. Languages which
> ;; do not implement locally-defined macros can set
> ;; `macrostep-environment-at-point-function' to `ignore'.
>
> ;; Note that the core `macrostep' machinery only interprets the return
> ;; value of `macrostep-sexp-bounds-function', so implementations for
> ;; other languages can use any internal representations of code and
> ;; environments which is convenient. Although the terminology is
> ;; Lisp-specific, there is no reason that implementations could not be
> ;; provided for non-Lisp languages with macro systems, provided there is
> ;; some way of identifying macro calls and calling the compiler /
> ;; preprocessor to obtain their expansions.
>
>
> ;; 6 Bugs and known limitations
> ;; ============================
>
> ;; You can evaluate and edebug macro-expanded forms and step through the
> ;; macro-expanded version, but the form that `eval-defun' and friends
> ;; read from the buffer won't have the uninterned symbols of the real
> ;; macro expansion. This will probably work OK with CL-style gensyms,
> ;; but may cause problems with `make-symbol' symbols if they have the
> ;; same print name as another symbol in the expansion. It's possible that
> ;; using `print-circle' and `print-gensym' could get around this.
>
> ;; Please send other bug reports and feature requests to the author.
>
>
> ;; 7 Acknowledgements
> ;; ==================
>
> ;; Thanks to:
> ;; - John Wiegley for fixing a bug with the face definitions under Emacs
> ;; 24 & for plugging macrostep in his [EmacsConf presentation]!
> ;; - George Kettleborough for bug reports, and patches to highlight the
> ;; expanded region and properly handle backquotes.
> ;; - Nic Ferrier for suggesting support for local definitions within
> ;; macrolet forms
> ;; - Luís Oliveira for suggesting and implementing SLIME support
>
> ;; `macrostep' was originally inspired by J. V. Toups's 'Deep Emacs Lisp'
> ;; articles ([part 1], [part 2], [screencast]).
>
> ;; [EmacsConf presentation] http://youtu.be/RvPFZL6NJNQ
>
> ;; [part 1]
> ;; http://dorophone.blogspot.co.uk/2011/04/deep-emacs-part-1.html
>
> ;; [part 2]
> ;; http://dorophone.blogspot.co.uk/2011/04/deep-emacs-lisp-part-2.html
>
> ;; [screencast]
> ;; http://dorophone.blogspot.co.uk/2011/05/monadic-parser-combinators-in-elisp.html
>
>
> ;; 8 Changelog
> ;; ===========
It would be better to convert this into a "News" section so that ELPA
can pick out the changelog.
> ;; - v0.9.2, 2023-05-12:
> ;; - name the keymap macrostep-mode-map, fixing a regression in v0.9.1
> ;; - v0.9.1, 2023-03-12:
> ;; - bug fixes, cleanup and modernization
> ;; - v0.9, 2015-10-01:
> ;; - separate into Elisp-specific and generic components
> ;; - highlight and expand compiler macros
> ;; - improve local macro expansion and macro form identification by
> ;; instrumenting `macroexpand(-all)'
> ;; - v0.8, 2014-05-29: fix a bug with printing the first element of lists
> ;; - v0.7, 2014-05-11: expand locally-defined macros within
> ;; `(cl-)macrolet' forms
> ;; - v0.6, 2013-05-04: better handling of quote and backquote
> ;; - v0.5, 2013-04-16: highlight region, maintain cleaner buffer state
> ;; - v0.4, 2013-04-07: only enter macrostep-mode on successful
> ;; macro-expansion
> ;; - v0.3, 2012-10-30: print dotted lists correctly. autoload
> ;; definitions.
>
> ;;; Code:
>
> (require 'pp)
> (require 'ring)
> (require 'cl-lib)
>
> \f
> ;;; Constants and dynamically bound variables
> (defvar macrostep-overlays nil
> "List of all macro stepper overlays in the current buffer.")
> (make-variable-buffer-local 'macrostep-overlays)
Here (and below) you can use defvar-local
> (defvar macrostep-gensym-depth nil
> "Number of macro expansion levels that have introduced gensyms so far.")
> (make-variable-buffer-local 'macrostep-gensym-depth)
>
> (defvar macrostep-gensyms-this-level nil
> "Non-nil if gensyms have been encountered during current level of macro expansion.")
> (make-variable-buffer-local 'macrostep-gensyms-this-level)
>
> (defvar macrostep-saved-undo-list nil
> "Saved value of `buffer-undo-list' upon entering macrostep mode.")
> (make-variable-buffer-local 'macrostep-saved-undo-list)
>
> (defvar macrostep-saved-read-only nil
> "Saved value of `buffer-read-only' upon entering macrostep mode.")
> (make-variable-buffer-local 'macrostep-saved-read-only)
>
> (defvar macrostep-expansion-buffer nil
> "Non-nil if the current buffer is a macro-expansion buffer.")
> (make-variable-buffer-local 'macrostep-expansion-buffer)
>
> (defvar macrostep-outer-environment nil
> "Outermost macro-expansion environment to use in macro-expansion buffers.
>
> This variable is used to save information about any enclosing
> `cl-macrolet' context when a macro form is expanded in a separate
> buffer.")
> (make-variable-buffer-local 'macrostep-outer-environment)
>
> ;;; Customization options and faces
> (defgroup macrostep nil
> "Interactive macro stepper for Emacs Lisp."
> :group 'lisp
> :link '(emacs-commentary-link :tag "commentary" "macrostep.el")
> :link '(emacs-library-link :tag "lisp file" "macrostep.el")
> :link '(url-link :tag "web page" "https://github.com/joddie/macrostep"))
This URL seems out-of-date.
>
> (defface macrostep-gensym-1
> '((((min-colors 16581375)) :foreground "#8080c0" :box t :bold t)
> (((min-colors 8)) :background "cyan")
> (t :inverse-video t))
> "Face for gensyms created in the first level of macro expansion.")
>
> (defface macrostep-gensym-2
> '((((min-colors 16581375)) :foreground "#8fbc8f" :box t :bold t)
> (((min-colors 8)) :background "#00cd00")
> (t :inverse-video t))
> "Face for gensyms created in the second level of macro expansion.")
>
> (defface macrostep-gensym-3
> '((((min-colors 16581375)) :foreground "#daa520" :box t :bold t)
> (((min-colors 8)) :background "yellow")
> (t :inverse-video t))
> "Face for gensyms created in the third level of macro expansion.")
>
> (defface macrostep-gensym-4
> '((((min-colors 16581375)) :foreground "#cd5c5c" :box t :bold t)
> (((min-colors 8)) :background "red")
> (t :inverse-video t))
> "Face for gensyms created in the fourth level of macro expansion.")
>
> (defface macrostep-gensym-5
> '((((min-colors 16581375)) :foreground "#da70d6" :box t :bold t)
> (((min-colors 8)) :background "magenta")
> (t :inverse-video t))
> "Face for gensyms created in the fifth level of macro expansion.")
>
> (defface macrostep-expansion-highlight-face
> `((((min-colors 16581375) (background light))
> ,@(and (>= emacs-major-version 27) '(:extend t))
> :background "#eee8d5")
> (((min-colors 16581375) (background dark))
> ,@(and (>= emacs-major-version 27) '(:extend t))
Is there any harm in adding :extend before Emacs 27? Also, we won't
need the check in the core.
> :background "#222222"))
> "Face for macro-expansion highlight.")
>
> (defface macrostep-macro-face
> '((t :underline t))
> "Face for macros in macro-expanded code.")
>
> (defface macrostep-compiler-macro-face
> '((t :slant italic))
> "Face for compiler macros in macro-expanded code.")
>
> (defcustom macrostep-expand-in-separate-buffer nil
> "When non-nil, show expansions in a separate buffer instead of inline."
> :type 'boolean)
>
> (defcustom macrostep-expand-compiler-macros t
> "When non-nil, also expand compiler macros."
> :type 'boolean)
>
> ;; Need the following for making the ring of faces
> (defun macrostep-make-ring (&rest items)
> "Make a ring containing all of ITEMS with no empty slots."
> (let ((ring (make-ring (length items))))
> (mapc (lambda (item) (ring-insert ring item)) (reverse items))
> ring))
Isn't this `ring-convert-sequence-to-ring'?
>
> (defvar macrostep-gensym-faces
> (macrostep-make-ring
> 'macrostep-gensym-1 'macrostep-gensym-2 'macrostep-gensym-3
> 'macrostep-gensym-4 'macrostep-gensym-5)
> "Ring of all macrostepper faces for fontifying gensyms.")
>
> ;; Other modes can enable macrostep by redefining these functions to
> ;; language-specific versions.
> (defvar macrostep-sexp-bounds-function
> #'macrostep-sexp-bounds
> "Function to return the bounds of the macro form nearest point.
>
> It will be called with no arguments and should return a cons of
> buffer positions, (START . END). It should use `save-excursion'
> to avoid changing the position of point.
>
> The default value, `macrostep-sexp-bounds', implements this for
> Emacs Lisp, and may be suitable for other Lisp-like languages.")
> (make-variable-buffer-local 'macrostep-sexp-bounds-function)
>
> (defvar macrostep-sexp-at-point-function
> #'macrostep-sexp-at-point
> "Function to return the macro form at point for expansion.
>
> It will be called with two arguments, the values of START and END
> returned by `macrostep-sexp-bounds-function', and with point
> positioned at START. It should return a value suitable for
> passing as the first argument to `macrostep-expand-1-function'.
>
> The default value, `macrostep-sexp-at-point', implements this for
> Emacs Lisp, and may be suitable for other Lisp-like languages.")
> (make-variable-buffer-local 'macrostep-sexp-at-point-function)
>
> (defvar macrostep-environment-at-point-function
> #'macrostep-environment-at-point
> "Function to return the local macro-expansion environment at point.
>
> It will be called with no arguments, and should return a value
> suitable for passing as the second argument to
> `macrostep-expand-1-function'.
>
> The default value, `macrostep-environment-at-point', is specific
> to Emacs Lisp. For languages which do not implement local
> macro-expansion environments, this should be set to `ignore'
> or `(lambda () nil)'.")
> (make-variable-buffer-local 'macrostep-environment-at-point-function)
>
> (defvar macrostep-expand-1-function
> #'macrostep-expand-1
> "Function to perform one step of macro-expansion.
>
> It will be called with two arguments, FORM and ENVIRONMENT, the
> return values of `macrostep-sexp-at-point-function' and
> `macrostep-environment-at-point-function' respectively. It
> should return the result of expanding FORM by one step as a value
> which is suitable for passing as the argument to
> `macrostep-print-function'.
>
> The default value, `macrostep-expand-1', is specific to Emacs Lisp.")
> (make-variable-buffer-local 'macrostep-expand-1-function)
>
> (defvar macrostep-print-function
> #'macrostep-pp
> "Function to pretty-print macro expansions.
>
> It will be called with two arguments, FORM and ENVIRONMENT, the
> return values of `macrostep-sexp-at-point-function' and
> `macrostep-environment-at-point-function' respectively. It
> should insert a pretty-printed representation at point in the
> current buffer, leaving point just after the inserted
> representation, without altering any other text in the current
> buffer.
>
> The default value, `macrostep-pp', is specific to Emacs Lisp.")
> (make-variable-buffer-local 'macrostep-print-function)
>
> (defvar macrostep-macro-form-p-function
> #'macrostep-macro-form-p
> "Function to check whether a form is a macro call.
>
> It will be called with two arguments, FORM and ENVIRONMENT -- the
> return values of `macrostep-sexp-at-point-function' and
> `macrostep-environment-at-point-function' respectively -- and
> should return non-nil if FORM would undergo macro-expansion in
> ENVIRONMENT.
>
> This is called only from `macrostep-sexp-bounds', so it need not
> be provided if a different value is used for
> `macrostep-sexp-bounds-function'.
>
> The default value, `macrostep-macro-form-p', is specific to Emacs Lisp.")
> (make-variable-buffer-local 'macrostep-macro-form-p-function)
>
> \f
> ;;; Define keymap and minor mode
> (define-obsolete-variable-alias 'macrostep-mode-keymap 'macrostep-mode-map "2023")
> (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022")
> (defvar macrostep-mode-map
> (let ((map (make-sparse-keymap)))
> (define-key map (kbd "RET") #'macrostep-expand)
> (define-key map "=" #'macrostep-expand)
> (define-key map "e" #'macrostep-expand)
>
> (define-key map (kbd "DEL") #'macrostep-collapse)
> (define-key map "u" #'macrostep-collapse)
> (define-key map "c" #'macrostep-collapse)
>
> (define-key map (kbd "TAB") #'macrostep-next-macro)
> (define-key map "n" #'macrostep-next-macro)
> (define-key map (kbd "M-TAB") #'macrostep-prev-macro)
> (define-key map "p" #'macrostep-prev-macro)
>
> (define-key map "q" #'macrostep-collapse-all)
> (define-key map (kbd "C-c C-c") #'macrostep-collapse-all)
> map)
> "Keymap for `macrostep-mode'.")
This could be converted to defvar-keymap.
> ;;;###autoload
> (define-minor-mode macrostep-mode
> "Minor mode for inline expansion of macros in Emacs Lisp source buffers.
>
> \\<macrostep-mode-map>Progressively expand macro forms with \
> \\[macrostep-expand], collapse them with \\[macrostep-collapse],
> and move back and forth with \\[macrostep-next-macro] and \
> \\[macrostep-prev-macro]. Use \\[macrostep-collapse-all] or collapse all
> visible expansions to quit and return to normal editing.
>
> \\{macrostep-mode-map}"
> :lighter " Macro-Stepper"
> :group 'macrostep
> (if macrostep-mode
> (progn
> ;; Disable recording of undo information
> (setq macrostep-saved-undo-list buffer-undo-list
> buffer-undo-list t)
> ;; Remember whether buffer was read-only
> (setq macrostep-saved-read-only buffer-read-only
> buffer-read-only t)
> ;; Set up post-command hook to bail out on leaving read-only
> (add-hook 'post-command-hook #'macrostep-command-hook nil t)
> (message (substitute-command-keys "\
> \\<macrostep-mode-map>Entering macro stepper mode. \
> Use \\[macrostep-expand] to expand, \\[macrostep-collapse] to collapse, \
> \\[macrostep-collapse-all] to exit.")))
>
> ;; Exiting mode
> (if macrostep-expansion-buffer
> ;; Kill dedicated expansion buffers
> (quit-window t)
> ;; Collapse any remaining overlays
> (when macrostep-overlays (macrostep-collapse-all))
> ;; Restore undo info & read-only state
> (setq buffer-undo-list macrostep-saved-undo-list
> buffer-read-only macrostep-saved-read-only
> macrostep-saved-undo-list nil)
> ;; Remove our post-command hook
> (remove-hook 'post-command-hook #'macrostep-command-hook t))))
>
> (defun macrostep-command-hook ()
> "Hook function for use by `post-command hook'.
> Bail out of `macrostep-mode' if the user types
> `\\[read-only-mode]' to make the buffer writable again."
> (if (not buffer-read-only)
> (macrostep-mode 0)))
>
> \f
> ;;; Interactive functions
> ;;;###autoload
> (defun macrostep-expand (&optional toggle-separate-buffer)
> "Expand the macro form following point by one step.
>
> Enters `macrostep-mode' if it is not already active, making the
> buffer temporarily read-only. If `macrostep-mode' is active and
> the form following point is not a macro form, search forward in
> the buffer and expand the next macro form found, if any.
>
> If optional argument TOGGLE-SEPARATE-BUFFER is non-nil (or set
> with a prefix argument), the expansion is displayed in a
> separate buffer instead of inline in the current buffer.
> Setting `macrostep-expand-in-separate-buffer' to non-nil swaps
> these two behaviors."
> (interactive "P")
> (cl-destructuring-bind (start . end)
> (funcall macrostep-sexp-bounds-function)
> (goto-char start)
> (let* ((sexp (funcall macrostep-sexp-at-point-function start end))
> (end (copy-marker end))
> (text (buffer-substring start end))
> (env (funcall macrostep-environment-at-point-function))
> (expansion (funcall macrostep-expand-1-function sexp env)))
>
> ;; Create a dedicated macro-expansion buffer and copy the text to
> ;; be expanded into it, if required
> (let ((separate-buffer-p
> (if toggle-separate-buffer
> (not macrostep-expand-in-separate-buffer)
> macrostep-expand-in-separate-buffer)))
> (when (and separate-buffer-p (not macrostep-expansion-buffer))
> (let ((mode major-mode)
> (buffer
> (get-buffer-create (generate-new-buffer-name "*macro expansion*"))))
> (set-buffer buffer)
Shouldn't this be a `with-current-buffer'?
> (funcall mode)
> (setq macrostep-expansion-buffer t)
> (setq macrostep-outer-environment env)
> (save-excursion
> (setq start (point))
> (insert text)
> (setq end (point-marker)))
> (pop-to-buffer buffer))))
>
> (unless macrostep-mode (macrostep-mode t))
> (let ((existing-overlay (macrostep-overlay-at-point))
> (macrostep-gensym-depth macrostep-gensym-depth)
> (macrostep-gensyms-this-level nil)
> priority)
> (if existing-overlay
> (progn ; Expanding part of a previous macro-expansion
> (setq priority (1+ (overlay-get existing-overlay 'priority)))
> (setq macrostep-gensym-depth
> (overlay-get existing-overlay 'macrostep-gensym-depth)))
Multiple `setq's can be merged into one, so the progn isn't necessary here.
> ;; Expanding source buffer text
> (setq priority 1)
> (setq macrostep-gensym-depth -1))
>
> (with-silent-modifications
> (atomic-change-group
> (let ((inhibit-read-only t))
> (save-excursion
> ;; Insert expansion
> (funcall macrostep-print-function expansion env)
> ;; Delete the original form
> (macrostep-collapse-overlays-in (point) end)
> (delete-region (point) end)
> ;; Create a new overlay
> (let* ((overlay
> (make-overlay start
> (if (looking-at "\n")
> (1+ (point))
> (point))))
> (highlight-overlay (unless macrostep-expansion-buffer
> (copy-overlay overlay))))
> (unless macrostep-expansion-buffer
> ;; Highlight the overlay in original source buffers only
> (overlay-put highlight-overlay 'face 'macrostep-expansion-highlight-face)
> (overlay-put highlight-overlay 'priority -1)
> (overlay-put overlay 'macrostep-highlight-overlay highlight-overlay))
> (overlay-put overlay 'priority priority)
> (overlay-put overlay 'macrostep-original-text text)
> (overlay-put overlay 'macrostep-gensym-depth macrostep-gensym-depth)
> (push overlay macrostep-overlays))))))))))
>
> (defun macrostep-collapse ()
> "Collapse the innermost macro expansion near point to its source text.
>
> If no more macro expansions are visible after this, exit
> `macrostep-mode'."
> (interactive)
> (let ((overlay (macrostep-overlay-at-point)))
> (when (not overlay) (error "No macro expansion at point"))
> (let ((inhibit-read-only t))
> (with-silent-modifications
> (atomic-change-group
> (macrostep-collapse-overlay overlay)))))
> (if (not macrostep-overlays)
Or `unless'
> (macrostep-mode 0)))
>
> (defun macrostep-collapse-all ()
> "Collapse all visible macro expansions and exit `macrostep-mode'."
> (interactive)
> (let ((inhibit-read-only t))
> (with-silent-modifications
> (dolist (overlay macrostep-overlays)
> (let ((outermost (= (overlay-get overlay 'priority) 1)))
> ;; We only need restore the original text for the outermost
> ;; overlays
> (macrostep-collapse-overlay overlay (not outermost))))))
> (setq macrostep-overlays nil)
> (macrostep-mode 0))
>
> (defun macrostep-next-macro ()
> "Move point forward to the next macro form in macro-expanded text."
> (interactive)
> (let* ((start (if (get-text-property (point) 'macrostep-macro-start)
> (1+ (point))
> (point)))
> (next (next-single-property-change start 'macrostep-macro-start)))
> (if next
> (goto-char next)
> (error "No more macro forms found"))))
>
> (defun macrostep-prev-macro ()
> "Move point back to the previous macro form in macro-expanded text."
> (interactive)
> (let (prev)
> (save-excursion
> (while
> (progn
> (setq prev (previous-single-property-change
> (point) 'macrostep-macro-start))
> (if (or (not prev)
> (get-text-property (1- prev) 'macrostep-macro-start))
> nil
> (prog1 t (goto-char prev))))))
> (if prev
> (goto-char (1- prev))
> (error "No previous macro form found"))))
>
> \f
> ;;; Utility functions (not language-specific)
>
> (defun macrostep-overlay-at-point ()
> "Return the innermost macro stepper overlay at point."
> (cdr (get-char-property-and-overlay (point) 'macrostep-original-text)))
>
> (defun macrostep-collapse-overlay (overlay &optional no-restore-p)
> "Collapse macro-expansion buffer OVERLAY and restore the unexpanded source text.
>
> As a minor optimization, does not restore the original source
> text if NO-RESTORE-P is non-nil. This is safe to do when
> collapsing all the sub-expansions of an outer overlay, since the
> outer overlay will restore the original source itself.
>
> Also removes the overlay from `macrostep-overlays'."
> (with-current-buffer (overlay-buffer overlay)
> ;; If we're cleaning up we don't need to bother restoring text
> ;; or checking for inner overlays to delete
> (unless no-restore-p
> (let* ((start (overlay-start overlay))
> (end (overlay-end overlay))
> (text (overlay-get overlay 'macrostep-original-text))
> (sexp-end
> (copy-marker
> (if (equal (char-before end) ?\n) (1- end) end))))
> (macrostep-collapse-overlays-in start end)
> (goto-char (overlay-start overlay))
> (save-excursion
> (insert text)
> (delete-region (point) sexp-end))))
> ;; Remove overlay from the list and delete it
> (setq macrostep-overlays
> (delq overlay macrostep-overlays))
> (let ((highlight-overlay (overlay-get overlay 'macrostep-highlight-overlay)))
> (when highlight-overlay (delete-overlay highlight-overlay)))
> (delete-overlay overlay)))
>
> (defun macrostep-collapse-overlays-in (start end)
> "Collapse all macrostepper overlays that are strictly between START and END.
>
> Will not collapse overlays that begin at START and end at END."
> (dolist (ol (overlays-in start end))
> (when (and (overlay-buffer ol) ; collapsing may delete other overlays
> (> (overlay-start ol) start)
> (< (overlay-end ol) end)
> (overlay-get ol 'macrostep-original-text))
> (macrostep-collapse-overlay ol t))))
>
> \f
> ;;; Emacs Lisp implementation
>
> (defun macrostep-sexp-bounds ()
> "Find the bounds of the macro form nearest point.
>
> If point is not before an open-paren, moves up to the nearest
> enclosing list. If the form at point is not a macro call,
> attempts to move forward to the next macro form as determined by
> `macrostep-macro-form-p-function'.
>
> Returns a cons of buffer positions, (START . END)."
> (save-excursion
> (if (not (looking-at "[(`]"))
> (backward-up-list 1))
> (if (equal (char-before) ?`)
> (backward-char))
> (let ((sexp (funcall macrostep-sexp-at-point-function))
> (env (funcall macrostep-environment-at-point-function)))
> ;; If this isn't a macro form, try to find the next one in the buffer
> (unless (funcall macrostep-macro-form-p-function sexp env)
> (condition-case nil
> (macrostep-next-macro)
> (error
> (if (consp sexp)
> (error "(%s ...) is not a macro form" (car sexp))
> (error "Text at point is not a macro form"))))))
> (cons (point) (scan-sexps (point) 1))))
>
> (defun macrostep-sexp-at-point (&rest _ignore)
> "Return the sexp near point for purposes of macro-stepper expansion.
>
> If the sexp near point is part of a macro expansion, returns the
> saved text of the macro expansion, and does not read from the
> buffer. This preserves uninterned symbols in the macro
> expansion, so that they can be fontified consistently. (See
> `macrostep-print-sexp'.)"
> (or (get-text-property (point) 'macrostep-expanded-text)
> (sexp-at-point)))
>
> (defun macrostep-macro-form-p (form environment)
> "Return non-nil if FORM would be evaluated via macro expansion;
> as considered within ENVIRONMENT.
>
> If FORM is an invocation of a macro defined by `defmacro' or an
> enclosing `cl-macrolet' form, return the symbol `macro'.
>
> If `macrostep-expand-compiler-macros' is non-nil and FORM is a
> call to a function with a compiler macro, return the symbol
> `compiler-macro'.
>
> Otherwise, return nil."
> (car (macrostep--macro-form-info form environment t)))
>
> (defun macrostep--macro-form-info (form environment &optional inhibit-autoload)
> "Return information about macro definitions that apply to FORM.
>
> If no macros are involved in the evaluation of FORM within
> ENVIRONMENT, returns nil. Otherwise, returns a cons (TYPE
> . DEFINITION).
>
> If FORM would be evaluated by a macro defined by `defmacro',
> `cl-macrolet', etc., TYPE is the symbol `macro' and DEFINITION is
> the macro definition, as a function.
>
> If `macrostep-expand-compiler-macros' is non-nil and FORM would
> be compiled using a compiler macro, TYPE is the symbol
> `compiler-macro' and DEFINITION is the function that implements
> the compiler macro.
>
> If FORM is an invocation of an autoloaded macro, the behavior
> depends on the value of INHIBIT-AUTOLOAD. If INHIBIT-AUTOLOAD is
> nil, the file containing the macro definition will be loaded
> using `load-library' and the macro definition returned as normal.
> If INHIBIT-AUTOLOAD is non-nil, no files will be loaded, and the
> value of DEFINITION in the result will be nil."
> (if (not (and (consp form)
> (symbolp (car form))))
> `(nil . nil)
> (let* ((head (car form))
> (local-definition (assoc-default head environment #'eq)))
> (if local-definition
> `(macro . ,local-definition)
> (let ((compiler-macro-definition
> (and macrostep-expand-compiler-macros
> (or (get head 'compiler-macro)
> (get head 'cl-compiler-macro)))))
> (if (and compiler-macro-definition
> (not (eq form
> (apply compiler-macro-definition form (cdr form)))))
> `(compiler-macro . ,compiler-macro-definition)
> (condition-case nil
> (let ((fun (indirect-function head)))
> (cl-case (car-safe fun)
> ((macro)
> `(macro . ,(cdr fun)))
> ((autoload)
> (when (memq (nth 4 fun) '(macro t))
> (if inhibit-autoload
> `(macro . nil)
> (load-library (nth 1 fun))
> (macrostep--macro-form-info form nil))))
> (t
> `(nil . nil))))
> (void-function nil))))))))
>
> (defun macrostep-expand-1 (form environment)
> "Return result of macro-expanding by exactly one step the top level of FORM.
> This is done within ENVIRONMENT.
>
> Unlike `macroexpand', this function does not continue macro
> expansion until a non-macro-call results."
> (cl-destructuring-bind (type . definition)
> (macrostep--macro-form-info form environment)
> (cl-ecase type
> ((nil)
> form)
> ((macro)
> (apply definition (cdr form)))
> ((compiler-macro)
> (let ((expansion (apply definition form (cdr form))))
> (if (equal form expansion)
> (error "Form left unchanged by compiler macro")
> expansion))))))
>
> (put 'macrostep-grab-environment-failed 'error-conditions
> '(macrostep-grab-environment-failed error))
>
> (defun macrostep-environment-at-point ()
> "Return the local macro-expansion environment at point, if any.
>
> The local environment includes macros declared by any `macrolet'
> or `cl-macrolet' forms surrounding point, as well as by any macro
> forms which expand into a `macrolet'.
>
> The return value is an alist of elements (NAME . FUNCTION), where
> NAME is the symbol locally bound to the macro and FUNCTION is the
> lambda expression that returns its expansion."
> ;; If point is on a macro form within an expansion inserted by
> ;; `macrostep-print-sexp', a local environment may have been
> ;; previously saved as a text property.
> (let ((saved-environment
> (get-text-property (point) 'macrostep-environment)))
> (if saved-environment
> saved-environment
> ;; Otherwise, we (ab)use the macro-expander to return the
> ;; environment at point. If point is not at an evaluated
> ;; position in the containing form,
> ;; `macrostep-environment-at-point-1' will raise an error, and
> ;; we back up progressively through the containing forms until
> ;; it succeeds.
> (save-excursion
> (catch 'done
> (while t
> (condition-case nil
> (throw 'done (macrostep-environment-at-point-1))
> (macrostep-grab-environment-failed
> (condition-case nil
> (backward-sexp)
> (scan-error (backward-up-list)))))))))))
>
> (defun macrostep-environment-at-point-1 ()
> "Attempt to extract the macro environment that would be active at point.
>
> If point is not at an evaluated position within the containing
> form, raise an error."
> ;; Macro environments are extracted using Emacs Lisp's builtin
> ;; macro-expansion machinery. The form containing point is copied
> ;; to a temporary buffer, and a call to
> ;; `--macrostep-grab-environment--' is inserted at point. This
> ;; altered form is then fully macro-expanded, in an environment
> ;; where `--macrostep-grab-environment--' is defined as a macro
> ;; which throws the environment to a uniquely-generated tag.
> (let* ((point-at-top-level
> (save-excursion
> (while (ignore-errors (backward-up-list) t))
> (point)))
> (enclosing-form
> (buffer-substring point-at-top-level
> (scan-sexps point-at-top-level 1)))
> (position (- (point) point-at-top-level))
> (tag (make-symbol "macrostep-grab-environment-tag"))
> (grab-environment '--macrostep-grab-environment--))
> (if (= position 0)
> nil
> (with-temp-buffer
> (emacs-lisp-mode)
> (insert enclosing-form)
> (goto-char (+ (point-min) position))
> (prin1 `(,grab-environment) (current-buffer))
> (let ((form (read (copy-marker (point-min)))))
> (catch tag
> (cl-letf (((symbol-function #'message) (symbol-function #'format)))
Is this supposed to be an `inhibit-message'?
> (with-no-warnings
> (ignore-errors
> (macroexpand-all
> `(cl-macrolet ((,grab-environment (&environment env)
> (throw ',tag env)))
> ,form)))))
> (signal 'macrostep-grab-environment-failed nil)))))))
>
> (defun macrostep-collect-macro-forms (form &optional environment)
> "Identify sub-forms of FORM which undergo macro-expansion.
>
> FORM is an Emacs Lisp form. ENVIRONMENT is a local environment of
> macro definitions.
>
> The return value is a list of two elements, (MACRO-FORM-ALIST
> COMPILER-MACRO-FORMS).
>
> MACRO-FORM-ALIST is an alist of elements of the form (SUBFORM
> . ENVIRONMENT), where SUBFORM is a form which undergoes
> macro-expansion in the course of expanding FORM, and ENVIRONMENT
> is the local macro environment in force when it is expanded.
>
> COMPILER-MACRO-FORMS is a list of subforms which would be
> compiled using a compiler macro. Since there is no standard way
> to provide a local compiler-macro definition in Emacs Lisp, no
> corresponding local environments are collected for these.
>
> Forms and environments are extracted from FORM by instrumenting
> Emacs's builtin `macroexpand' function and calling
> `macroexpand-all'."
> (let* ((macro-form-alist '())
> (compiler-macro-forms '())
> (override (lambda (real-macroexpand form environment &rest args)
> (let ((expansion
> (apply real-macroexpand form environment args)))
> (cond ((not (eq expansion form))
> (setq macro-form-alist
> (cons (cons form environment)
> macro-form-alist)))
> ((and (consp form)
> (symbolp (car form))
> macrostep-expand-compiler-macros
> (not (eq form
> (cl-compiler-macroexpand form))))
> (setq compiler-macro-forms
> (cons form compiler-macro-forms))))
> expansion))))
> (cl-macrolet ((with-override (fn &rest body)
> `(cl-letf (((symbol-function ,fn)
> (apply-partially override (indirect-function ,fn))))
> ,@body))
> (with-macroexpand-1 (&rest body)
> (if (< emacs-major-version 30)
> `(progn ,@body) `(with-override #'macroexpand-1 ,@body)))
> (with-macroexpand (&rest body)
> `(with-override #'macroexpand ,@body)))
> (with-macroexpand-1
> (with-macroexpand
> (ignore-errors
> (macroexpand-all form environment)))))
> (list macro-form-alist compiler-macro-forms)))
>
> (defvar macrostep-collected-macro-form-alist nil
> "An alist of macro forms and environments.
> Controls the printing of sub-forms in `macrostep-print-sexp'.")
>
> (defvar macrostep-collected-compiler-macro-forms nil
> "A list of compiler-macro forms to be highlighted in `macrostep-print-sexp'.")
>
> (defun macrostep-pp (sexp environment)
> "Pretty-print SEXP, fontifying macro forms and uninterned symbols.
> This is done within ENVIRONMENT."
> (cl-destructuring-bind
> (macrostep-collected-macro-form-alist
> macrostep-collected-compiler-macro-forms)
> (macrostep-collect-macro-forms sexp environment)
> (let ((print-quoted t))
> (macrostep-print-sexp sexp)
> ;; Point is now after the expanded form; pretty-print it
> (save-restriction
> (narrow-to-region (scan-sexps (point) -1) (point))
> (save-excursion
> (pp-buffer)
> ;; Remove the extra newline inserted by pp-buffer
> (goto-char (point-max))
> (delete-region
> (point)
> (save-excursion (skip-chars-backward " \t\n") (point))))
> ;; Indent the newly-inserted form in context
> (widen)
> (save-excursion
> (backward-sexp)
> (indent-sexp))))))
>
> ;; This must be defined before `macrostep-print-sexp':
> (defmacro macrostep-propertize (form &rest plist)
> "Evaluate FORM, applying syntax properties in PLIST to any inserted text."
> (declare (indent 1)
> (debug (&rest form)))
> (let ((start (make-symbol "start")))
> `(let ((,start (point)))
> (prog1
> ,form
> ,@(cl-loop for (key value) on plist by #'cddr
> collect `(put-text-property ,start (point)
> ,key ,value))))))
>
> (defun macrostep-print-sexp (sexp)
> "Insert SEXP like `print', fontifying macro forms and uninterned symbols.
>
> Fontifies uninterned symbols and macro forms using
> `font-lock-face' property, and saves the actual text of SEXP's
> sub-forms as the `macrostep-expanded-text' text property so that
> any uninterned symbols can be reused in macro expansions of the
> sub-forms. See also `macrostep-sexp-at-point'.
>
> Macro and compiler-macro forms within SEXP are identified by
> comparison with the `macrostep-collected-macro-form-alist' and
> `macrostep-collected-compiler-macro-forms' variables, which
> should be dynamically let-bound around calls to this function."
> (cond
> ((symbolp sexp)
> ;; Fontify gensyms
> (if (not (eq sexp (intern-soft (symbol-name sexp))))
> (macrostep-propertize
> (prin1 sexp (current-buffer))
> 'font-lock-face (macrostep-get-gensym-face sexp))
> ;; Print other symbols as normal
> (prin1 sexp (current-buffer))))
>
> ((listp sexp)
> ;; Print quoted and quasiquoted forms nicely.
> (let ((head (car sexp)))
> (cond ((and (eq head 'quote) ; quote
> (= (length sexp) 2))
> (insert "'")
> (macrostep-print-sexp (cadr sexp)))
>
> ((and (eq head '\`) ; backquote
> (= (length sexp) 2))
> (if (assq sexp macrostep-collected-macro-form-alist)
> (macrostep-propertize
> (insert "`")
> 'macrostep-expanded-text sexp
> 'macrostep-macro-start t
> 'font-lock-face 'macrostep-macro-face)
> (insert "`"))
> (macrostep-print-sexp (cadr sexp)))
>
> ((and (memq head '(\, \,@)) ; unquote
> (= (length sexp) 2))
> (princ head (current-buffer))
> (macrostep-print-sexp (cadr sexp)))
>
> (t ; other list form
> (cl-destructuring-bind (macro? . environment)
> (or (assq sexp macrostep-collected-macro-form-alist)
> '(nil . nil))
> (let
> ((compiler-macro?
> (memq sexp macrostep-collected-compiler-macro-forms)))
> (if (or macro? compiler-macro?)
> (progn
> ;; Save the real expansion as a text property on the
> ;; opening paren
> (macrostep-propertize
> (insert "(")
> 'macrostep-macro-start t
> 'macrostep-expanded-text sexp
> 'macrostep-environment environment)
> ;; Fontify the head of the macro
> (macrostep-propertize
> (macrostep-print-sexp head)
> 'font-lock-face
> (if macro?
> 'macrostep-macro-face
> 'macrostep-compiler-macro-face)))
> ;; Not a macro form
> (insert "(")
> (macrostep-print-sexp head))))
>
> ;; Print remaining list elements
> (setq sexp (cdr sexp))
> (when sexp (insert " "))
> (while sexp
> (if (listp sexp)
> (progn
> (macrostep-print-sexp (car sexp))
> (when (cdr sexp) (insert " "))
> (setq sexp (cdr sexp)))
> ;; Print tail of dotted list
> (insert ". ")
> (macrostep-print-sexp sexp)
> (setq sexp nil)))
> (insert ")")))))
>
> ;; Print everything except symbols and lists as normal
> (t (prin1 sexp (current-buffer)))))
>
> (defun macrostep-get-gensym-face (symbol)
> "Return the face to use in fontifying SYMBOL in printed macro expansions.
>
> All symbols introduced in the same level of macro expansion are
> fontified using the same face (modulo the number of faces; see
> `macrostep-gensym-faces')."
> (or (get symbol 'macrostep-gensym-face)
> (progn
> (if (not macrostep-gensyms-this-level)
> (setq macrostep-gensym-depth (1+ macrostep-gensym-depth)
> macrostep-gensyms-this-level t))
> (let ((face (ring-ref macrostep-gensym-faces macrostep-gensym-depth)))
> (put symbol 'macrostep-gensym-face face)
> face))))
>
> \f
> (provide 'macrostep)
> ;; Local Variables:
> ;; indent-tabs-mode: nil
> ;; End:
> ;;; macrostep.el ends here
Isn't there also a C-preprecossor implementation for macrostep? Would
the plan be to include that as well?
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-17 21:48 ` Incorporate package macrostep into Emacs core Jeremy Bryant via Emacs development discussions.
2024-03-18 9:09 ` Philip Kaludercic
@ 2024-03-18 12:48 ` Eli Zaretskii
2024-03-18 13:22 ` Stefan Monnier
` (2 more replies)
1 sibling, 3 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-18 12:48 UTC (permalink / raw)
To: Jeremy Bryant
Cc: monnier, emacs-devel, j.j.oddie, stefan, stefankangas, jonas
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> stefan@marxist.se, stefankangas@gmail.com, jonas@bernoul.li
> Date: Sun, 17 Mar 2024 21:48:08 +0000
>
> Manual?
> Should the documentation for macrostep be included in the Emacs Lisp
> manual section Macros?
Yes, I think so.
Please also provide a suitable entry for NEWS.
> Code?
> The main file is attached for convenience, from the orphanage upstream
> (https://github.com/emacsorphanage/macrostep).
> Are any changes needed before this is merged into Emacs?
> I volunteer to write some code towards this, please let me know.
Please add :version tags to all the defcustom's and defface's.
> (define-obsolete-variable-alias 'macrostep-mode-keymap 'macrostep-mode-map "2023")
> (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022")
The years there should be changed to Emacs versions, I think.
> (defvar macrostep-mode-map
> (let ((map (make-sparse-keymap)))
> (define-key map (kbd "RET") #'macrostep-expand)
> (define-key map "=" #'macrostep-expand)
> (define-key map "e" #'macrostep-expand)
Bonus points for converting this into defvar-keymap.
> ;; Local Variables:
> ;; indent-tabs-mode: nil
> ;; End:
I think this should be deleted, as this is now the default in ELisp
buffers.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 12:48 ` Eli Zaretskii
@ 2024-03-18 13:22 ` Stefan Monnier
2024-03-18 22:58 ` Jeremy Bryant
2024-04-18 21:19 ` Jeremy Bryant
2 siblings, 0 replies; 86+ messages in thread
From: Stefan Monnier @ 2024-03-18 13:22 UTC (permalink / raw)
To: Eli Zaretskii
Cc: Jeremy Bryant, emacs-devel, j.j.oddie, stefan, stefankangas,
jonas
>> (define-obsolete-variable-alias 'macrostep-mode-keymap 'macrostep-mode-map "2023")
>> (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022")
> The years there should be changed to Emacs versions, I think.
Hmm... I don't think it would make sense to make it refer to "the
version of Emacs that was current when the change was made" since
macrostep was not included in Emacs back then.
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 12:48 ` Eli Zaretskii
2024-03-18 13:22 ` Stefan Monnier
@ 2024-03-18 22:58 ` Jeremy Bryant
2024-03-19 12:26 ` Eli Zaretskii
2024-04-18 21:19 ` Jeremy Bryant
2 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-18 22:58 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel, j.j.oddie, stefankangas, jonas
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
>> stefan@marxist.se, stefankangas@gmail.com, jonas@bernoul.li
>> Date: Sun, 17 Mar 2024 21:48:08 +0000
>>
>> Manual?
>> Should the documentation for macrostep be included in the Emacs Lisp
>> manual section Macros?
>
> Yes, I think so.
>
> Please also provide a suitable entry for NEWS.
>
>> Code?
>> The main file is attached for convenience, from the orphanage upstream
>> (https://github.com/emacsorphanage/macrostep).
>> Are any changes needed before this is merged into Emacs?
>> I volunteer to write some code towards this, please let me know.
>
> Please add :version tags to all the defcustom's and defface's.
>
>> (define-obsolete-variable-alias 'macrostep-mode-keymap
>> 'macrostep-mode-map "2023")
>> (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022")
>
> The years there should be changed to Emacs versions, I think.
>
>> (defvar macrostep-mode-map
>> (let ((map (make-sparse-keymap)))
>> (define-key map (kbd "RET") #'macrostep-expand)
>> (define-key map "=" #'macrostep-expand)
>> (define-key map "e" #'macrostep-expand)
>
> Bonus points for converting this into defvar-keymap.
>
>> ;; Local Variables:
>> ;; indent-tabs-mode: nil
>> ;; End:
>
> I think this should be deleted, as this is now the default in ELisp
> buffers.
OK, I'll start working on these.
For the macrostep commits, is it easier for future integration that this
is done externally and submitted in one go, or would something like a
new macrostep branch in the Emacs tree be more appropriate?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 9:09 ` Philip Kaludercic
@ 2024-03-18 23:03 ` Jeremy Bryant
2024-03-19 6:36 ` Philip Kaludercic
2024-03-19 17:03 ` Jonathan Oddie
0 siblings, 2 replies; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-18 23:03 UTC (permalink / raw)
To: Philip Kaludercic
Cc: Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
monnier, j.j.oddie, stefankangas, jonas
[-- Attachment #1: Type: text/plain, Size: 312 bytes --]
Philip Kaludercic <philipk@posteo.net> writes:
Philip,
Thanks for all the comments on the macrostep.el code, I'll work on what
I can.
> Isn't there also a C-preprecossor implementation for macrostep? Would
> the plan be to include that as well?
Presumably, also. Any comments on macrostep-c.el (attached)?
[-- Attachment #2: macrostep-c.el --]
[-- Type: application/emacs-lisp, Size: 6627 bytes --]
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 23:03 ` Jeremy Bryant
@ 2024-03-19 6:36 ` Philip Kaludercic
2024-03-19 7:11 ` Gerd Möllmann
2024-03-19 17:03 ` Jonathan Oddie
1 sibling, 1 reply; 86+ messages in thread
From: Philip Kaludercic @ 2024-03-19 6:36 UTC (permalink / raw)
To: Jeremy Bryant
Cc: Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
monnier, j.j.oddie, stefankangas, jonas
Jeremy Bryant <jb@jeremybryant.net> writes:
> Philip Kaludercic <philipk@posteo.net> writes:
>
> Philip,
> Thanks for all the comments on the macrostep.el code, I'll work on what
> I can.
>
>> Isn't there also a C-preprecossor implementation for macrostep? Would
>> the plan be to include that as well?
>
> Presumably, also. Any comments on macrostep-c.el (attached)?
>
> ;;; macrostep-c.el --- macrostep interface to C preprocessor -*- lexical-binding: t; -*-
>
> ;; Copyright (C) 2015 Jon Oddie
If included, then this should be updated.
> ;; Author: Jon Oddie <j.j.oddie@gmail.com>
> ;; Url: https://github.com/emacsorphanage/macrostep
And this removed.
> ;; Keywords: c, languages, macro, debugging
>
> ;; SPDX-License-Identifier: GPL-3.0-or-later
>
> ;; This file is free software: you can redistribute it and/or modify
> ;; it under the terms of the GNU General Public License as published
> ;; by the Free Software Foundation, either version 3 of the License,
> ;; or (at your option) any later version.
> ;;
> ;; This file is distributed in the hope that it will be useful,
> ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
> ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> ;; GNU General Public License for more details.
> ;;
> ;; You should have received a copy of the GNU General Public License
> ;; along with this file. If not, see <https://www.gnu.org/licenses/>.
>
> ;;; Commentary:
>
> ;; A thin wrapper around Emacs's built-in `cmacexp' library to provide
> ;; basic support for expanding C macros using the `macrostep' user
> ;; interface. To use, position point on a macro use in a C buffer and
> ;; type `M-x macrostep-expand'. The variables `c-macro-preprocessor'
> ;; and especially `c-macro-cppflags' may need to be set correctly for
> ;; accurate expansion.
>
> ;; This is fairly basic compared to the Emacs Lisp `macrostep'. In
> ;; particular, there is no step-by-step expansion, since C macros are
> ;; expanded in a single "cpp" pass, and no pretty-printing.
>
> ;; To hide the buffer containing "cpp" warnings (not recommended), you
> ;; could do something like:
> ;;
> ;; (push `(,(regexp-quote macrostep-c-warning-buffer)
> ;; (display-buffer-no-window))
> ;; display-buffer-alist)
>
> ;;; Code:
>
> (require 'macrostep)
> (require 'cmacexp)
> (require 'cl-lib)
>
> (require 'subr-x nil t)
> (defalias 'macrostep-c-string-trim
> (if (fboundp 'string-trim)
> #'string-trim
> (lambda (string)
> (when (string-match "\\`[ \t\n\r]+" string)
> (setq string (replace-match "" t t string)))
> (when (string-match "[ \t\n\r]+\\'" string)
> (setq string (replace-match "" t t string)))
> string)))
We can drop this (or use Compat to provide the function if the package
is distributeted on ELPA).
> (put 'macrostep-c-non-macro 'error-conditions
> '(macrostep-c-non-macro error))
> (put 'macrostep-c-non-macro 'error-message
> "Text around point is not a macro call.")
>
> (put 'macrostep-c-expansion-failed 'error-conditions
> '(macrostep-c-expansion-failed error))
> (put 'macrostep-c-expansion-failed 'error-message
> "Macro-expansion failed.")
>
> (defvar macrostep-c-warning-buffer "*Macroexpansion Warnings*")
>
> ;;;###autoload
> (defun macrostep-c-mode-hook ()
> (setq macrostep-sexp-bounds-function
> #'macrostep-c-sexp-bounds)
> (setq macrostep-sexp-at-point-function
> #'macrostep-c-sexp-at-point)
> (setq macrostep-environment-at-point-function
> #'ignore)
> (setq macrostep-expand-1-function
> #'macrostep-c-expand-1)
> (setq macrostep-print-function
> #'macrostep-c-print-function)
> (add-hook 'macrostep-mode-off-hook
> #'macrostep-c-mode-off nil t))
>
> (defun macrostep-c-mode-off (&rest _ignore)
> (when (derived-mode-p 'c-mode)
> (let ((warning-window
> (get-buffer-window macrostep-c-warning-buffer)))
> (when warning-window
> (quit-window nil warning-window)))))
>
> ;;;###autoload
> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
This part is suspicious. First of all, it looks like one is adding a
hook to a hook, but this would unconditionally modify
c-mode-hook, which I don't think is reliable. Can we find some other
way to update the variables, depending on the major mode? E.g. in
macrostep.el one could try to intern (format "macrostep-%s-init"
major-mode) and check if the symbol is fboundp?
> (defun macrostep-c-sexp-bounds ()
> (save-excursion
> (cl-loop
> (let ((region (macrostep-c-sexp-bounds-1)))
> (cond
> ((null region)
> (signal 'macrostep-c-non-macro nil))
> ((macrostep-c-expandable-p region)
> (cl-return region))
> (t
> (condition-case nil
> (progn
> (backward-up-list)
> (skip-syntax-backward "-"))
> (scan-error
> (signal 'macrostep-c-non-macro nil)))))))))
>
> (defun macrostep-c-sexp-bounds-1 ()
> (let ((region (bounds-of-thing-at-point 'symbol)))
> (when region
One could use when-let* in places like this.
> (cl-destructuring-bind (symbol-start . symbol-end) region
> (save-excursion
> (goto-char symbol-end)
> (if (looking-at "[[:space:]]*(")
> (cons symbol-start (scan-sexps symbol-end 1))
> region))))))
The indentation is off here, right? Might be worth reindenting
everything once.
>
> (defun macrostep-c-expandable-p (region)
> (cl-destructuring-bind (start . end) region
> (condition-case nil
> (cl-destructuring-bind (expansion _warnings)
> (macrostep-c-expand-region start end)
> (and (cl-plusp (length expansion))
> (not (string= expansion (buffer-substring start end)))))
> (macrostep-c-expansion-failed nil))))
>
> (defun macrostep-c-sexp-at-point (start end)
> (cons start end))
>
> (defun macrostep-c-expand-1 (region _ignore)
> (cl-destructuring-bind (start . end) region
> (cl-destructuring-bind (expansion warnings)
> (macrostep-c-expand-region start end)
> (when (cl-plusp (length warnings))
> (with-current-buffer
> (get-buffer-create macrostep-c-warning-buffer)
> (let ((inhibit-read-only t))
> (erase-buffer)
> (insert warnings)
> (goto-char (point-min)))
> (special-mode)
> (display-buffer (current-buffer)
> '(display-buffer-pop-up-window
> (inhibit-same-window . t)
> (allow-no-window . t)))))
> expansion)))
>
> (defun macrostep-c-expand-region (start end)
> (let ((expansion
> (condition-case nil
> (c-macro-expansion start end
> (concat c-macro-preprocessor " "
> c-macro-cppflags))
> (search-failed
> (signal 'macrostep-c-expansion-failed nil)))))
> (with-temp-buffer
> (save-excursion
> (insert expansion))
> (when (looking-at (regexp-quote "/*"))
> (search-forward "*/"))
> (let ((warnings (buffer-substring (point-min) (point)))
> (expansion (buffer-substring (point) (point-max))))
> (mapcar #'macrostep-c-string-trim (list expansion warnings))))))
>
> (defun macrostep-c-print-function (expansion &rest _ignore)
> (with-temp-buffer
> (insert expansion)
> (let ((exit-code
> (shell-command-on-region (point-min) (point-max) "indent" nil t)))
When calling indent, it might be nice to provide an option for optional
flags, in case someone prefers some other indentation scheme.
> (when (zerop exit-code)
> (setq expansion (macrostep-c-string-trim (buffer-string))))))
> (insert expansion))
>
> (provide 'macrostep-c)
>
> ;;; macrostep-c.el ends here
>
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 6:36 ` Philip Kaludercic
@ 2024-03-19 7:11 ` Gerd Möllmann
2024-03-19 7:26 ` Philip Kaludercic
0 siblings, 1 reply; 86+ messages in thread
From: Gerd Möllmann @ 2024-03-19 7:11 UTC (permalink / raw)
To: Philip Kaludercic
Cc: Jeremy Bryant, Jeremy Bryant via Emacs development discussions.,
Eli Zaretskii, monnier, j.j.oddie, stefankangas, jonas
Philip Kaludercic <philipk@posteo.net> writes:
>> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
>
> This part is suspicious. First of all, it looks like one is adding a
> hook to a hook, but this would unconditionally modify
> c-mode-hook, which I don't think is reliable. Can we find some other
> way to update the variables, depending on the major mode? E.g. in
> macrostep.el one could try to intern (format "macrostep-%s-init"
> major-mode) and check if the symbol is fboundp?
Also, it would be nice to support C++ and Objc, which we have in Emacs
(c-mode-common-hook).
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 7:11 ` Gerd Möllmann
@ 2024-03-19 7:26 ` Philip Kaludercic
2024-03-19 7:30 ` Gerd Möllmann
0 siblings, 1 reply; 86+ messages in thread
From: Philip Kaludercic @ 2024-03-19 7:26 UTC (permalink / raw)
To: Gerd Möllmann
Cc: Jeremy Bryant, Jeremy Bryant via Emacs development discussions.,
Eli Zaretskii, monnier, j.j.oddie, stefankangas, jonas
Gerd Möllmann <gerd.moellmann@gmail.com> writes:
> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
>>
>> This part is suspicious. First of all, it looks like one is adding a
>> hook to a hook, but this would unconditionally modify
>> c-mode-hook, which I don't think is reliable. Can we find some other
>> way to update the variables, depending on the major mode? E.g. in
>> macrostep.el one could try to intern (format "macrostep-%s-init"
>> major-mode) and check if the symbol is fboundp?
>
> Also, it would be nice to support C++ and Objc, which we have in Emacs
> (c-mode-common-hook).
From what I understand, this feature is based on cmacexp, which in turn
just uses cpp. If something like this feature should be supported for
C++ and Objc, then the functionality should first be added to cmacexp or
something analogous (as it is my understanding that this is currently
not the case).
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 7:26 ` Philip Kaludercic
@ 2024-03-19 7:30 ` Gerd Möllmann
2024-03-19 9:33 ` Philip Kaludercic
0 siblings, 1 reply; 86+ messages in thread
From: Gerd Möllmann @ 2024-03-19 7:30 UTC (permalink / raw)
To: Philip Kaludercic
Cc: Jeremy Bryant, Jeremy Bryant via Emacs development discussions.,
Eli Zaretskii, monnier, j.j.oddie, stefankangas, jonas
Philip Kaludercic <philipk@posteo.net> writes:
> Gerd Möllmann <gerd.moellmann@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>>> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
>>>
>>> This part is suspicious. First of all, it looks like one is adding a
>>> hook to a hook, but this would unconditionally modify
>>> c-mode-hook, which I don't think is reliable. Can we find some other
>>> way to update the variables, depending on the major mode? E.g. in
>>> macrostep.el one could try to intern (format "macrostep-%s-init"
>>> major-mode) and check if the symbol is fboundp?
>>
>> Also, it would be nice to support C++ and Objc, which we have in Emacs
>> (c-mode-common-hook).
>
> From what I understand, this feature is based on cmacexp, which in turn
> just uses cpp.
What's the problem using cpp?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 7:30 ` Gerd Möllmann
@ 2024-03-19 9:33 ` Philip Kaludercic
2024-03-19 9:48 ` Gerd Möllmann
0 siblings, 1 reply; 86+ messages in thread
From: Philip Kaludercic @ 2024-03-19 9:33 UTC (permalink / raw)
To: Gerd Möllmann
Cc: Jeremy Bryant, Jeremy Bryant via Emacs development discussions.,
Eli Zaretskii, monnier, j.j.oddie, stefankangas, jonas
Gerd Möllmann <gerd.moellmann@gmail.com> writes:
> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Gerd Möllmann <gerd.moellmann@gmail.com> writes:
>>
>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>
>>>>> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
>>>>
>>>> This part is suspicious. First of all, it looks like one is adding a
>>>> hook to a hook, but this would unconditionally modify
>>>> c-mode-hook, which I don't think is reliable. Can we find some other
>>>> way to update the variables, depending on the major mode? E.g. in
>>>> macrostep.el one could try to intern (format "macrostep-%s-init"
>>>> major-mode) and check if the symbol is fboundp?
>>>
>>> Also, it would be nice to support C++ and Objc, which we have in Emacs
>>> (c-mode-common-hook).
>>
>> From what I understand, this feature is based on cmacexp, which in turn
>> just uses cpp.
>
> What's the problem using cpp?
I don't know what Objc does, but in the case of C++ my understanding was
that for example Templates were not expanded by C++. Of course, if that
is not the intention, then never mind my comment.
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 9:33 ` Philip Kaludercic
@ 2024-03-19 9:48 ` Gerd Möllmann
0 siblings, 0 replies; 86+ messages in thread
From: Gerd Möllmann @ 2024-03-19 9:48 UTC (permalink / raw)
To: Philip Kaludercic
Cc: Jeremy Bryant, Jeremy Bryant via Emacs development discussions.,
Eli Zaretskii, monnier, j.j.oddie, stefankangas, jonas
Philip Kaludercic <philipk@posteo.net> writes:
> Gerd Möllmann <gerd.moellmann@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>> Gerd Möllmann <gerd.moellmann@gmail.com> writes:
>>>
>>>> Philip Kaludercic <philipk@posteo.net> writes:
>>>>
>>>>>> (add-hook 'c-mode-hook #'macrostep-c-mode-hook)
>>>>>
>>>>> This part is suspicious. First of all, it looks like one is adding a
>>>>> hook to a hook, but this would unconditionally modify
>>>>> c-mode-hook, which I don't think is reliable. Can we find some other
>>>>> way to update the variables, depending on the major mode? E.g. in
>>>>> macrostep.el one could try to intern (format "macrostep-%s-init"
>>>>> major-mode) and check if the symbol is fboundp?
>>>>
>>>> Also, it would be nice to support C++ and Objc, which we have in Emacs
>>>> (c-mode-common-hook).
>>>
>>> From what I understand, this feature is based on cmacexp, which in turn
>>> just uses cpp.
>>
>> What's the problem using cpp?
>
> I don't know what Objc does, but in the case of C++ my understanding was
> that for example Templates were not expanded by C++. Of course, if that
> is not the intention, then never mind my comment.
The preprocessor is the same for all three languages.
If by templates, you mean C++ templates -- these have nothing to do with
the preprocessor. They don't work on the level of text.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 22:58 ` Jeremy Bryant
@ 2024-03-19 12:26 ` Eli Zaretskii
0 siblings, 0 replies; 86+ messages in thread
From: Eli Zaretskii @ 2024-03-19 12:26 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel, j.j.oddie, stefankangas, jonas
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> stefankangas@gmail.com, jonas@bernoul.li
> Date: Mon, 18 Mar 2024 22:58:02 +0000
>
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Jeremy Bryant <jb@jeremybryant.net>
> >> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> >> stefan@marxist.se, stefankangas@gmail.com, jonas@bernoul.li
> >> Date: Sun, 17 Mar 2024 21:48:08 +0000
> >>
> >> Manual?
> >> Should the documentation for macrostep be included in the Emacs Lisp
> >> manual section Macros?
> >
> > Yes, I think so.
> >
> > Please also provide a suitable entry for NEWS.
> >
> >> Code?
> >> The main file is attached for convenience, from the orphanage upstream
> >> (https://github.com/emacsorphanage/macrostep).
> >> Are any changes needed before this is merged into Emacs?
> >> I volunteer to write some code towards this, please let me know.
> >
> > Please add :version tags to all the defcustom's and defface's.
> >
> >> (define-obsolete-variable-alias 'macrostep-mode-keymap
> >> 'macrostep-mode-map "2023")
> >> (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022")
> >
> > The years there should be changed to Emacs versions, I think.
> >
> >> (defvar macrostep-mode-map
> >> (let ((map (make-sparse-keymap)))
> >> (define-key map (kbd "RET") #'macrostep-expand)
> >> (define-key map "=" #'macrostep-expand)
> >> (define-key map "e" #'macrostep-expand)
> >
> > Bonus points for converting this into defvar-keymap.
> >
> >> ;; Local Variables:
> >> ;; indent-tabs-mode: nil
> >> ;; End:
> >
> > I think this should be deleted, as this is now the default in ELisp
> > buffers.
>
> OK, I'll start working on these.
Thanks.
> For the macrostep commits, is it easier for future integration that this
> is done externally and submitted in one go, or would something like a
> new macrostep branch in the Emacs tree be more appropriate?
A branch is preferable if you want people to be able to use and test
the package before it lands. If this package is already in use by
enough people, so you can be reasonably sure it doesn't have any grave
problems, a branch is not required, and you can submit everything as a
single patch.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 23:03 ` Jeremy Bryant
2024-03-19 6:36 ` Philip Kaludercic
@ 2024-03-19 17:03 ` Jonathan Oddie
2024-03-19 21:57 ` Jeremy Bryant via Emacs development discussions.
1 sibling, 1 reply; 86+ messages in thread
From: Jonathan Oddie @ 2024-03-19 17:03 UTC (permalink / raw)
To: Jeremy Bryant
Cc: Philip Kaludercic,
Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
Stefan Monnier, Stefan Kangas, Jonas Bernoulli
Hi all,
Sorry I’ve been away from this discussion while traveling.
>> Isn't there also a C-preprecossor implementation for macrostep? Would
>> the plan be to include that as well?
>
> Presumably, also. Any comments on macrostep-c.el (attached)?
I’m not sure how useful the C preprocessor implementation is, as I didn’t do too much work on it. It is more of a proof-of-concept for the ability to extend macrostep to different languages. Of course it’s your choice whether you find it worthwhile to include.
There is a Common Lisp implementation maintained as part of SLIME which is more complete, FYI.
I’ve still to sign and return the FSF paperwork but will do so this week.
Jonathan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 17:03 ` Jonathan Oddie
@ 2024-03-19 21:57 ` Jeremy Bryant via Emacs development discussions.
2024-03-22 20:47 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Emacs development discussions. @ 2024-03-19 21:57 UTC (permalink / raw)
To: Jonathan Oddie
Cc: Philip Kaludercic,
Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
Stefan Monnier, Stefan Kangas, Jonas Bernoulli
[-- Attachment #1: Type: text/plain, Size: 1127 bytes --]
Jonathan Oddie <j.j.oddie@gmail.com> writes:
> Hi all,
>
> Sorry I’ve been away from this discussion while traveling.
>
>>> Isn't there also a C-preprecossor implementation for macrostep? Would
>>> the plan be to include that as well?
>>
>> Presumably, also. Any comments on macrostep-c.el (attached)?
>
> I’m not sure how useful the C preprocessor implementation is, as I
> didn’t do too much work on it. It is more of a proof-of-concept for
> the ability to extend macrostep to different languages. Of course it’s
> your choice whether you find it worthwhile to include.
>
> There is a Common Lisp implementation maintained as part of SLIME
> which is more complete, FYI.
Thank you for clarifying. On this basis I will only work on adding the
main Lisp related macrostep file for the time being.
> I’ve still to sign and return the FSF paperwork but will do so this week.
>
> Jonathan
Thanks in advance!
What about another file - should the tests file be included in Emacs as part of the main Lisp macrostep?
Should test files be added in the Emacs tree test/lisp/?
[-- Attachment #2: macrostep-test.el --]
[-- Type: application/emacs-lisp, Size: 17072 bytes --]
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-19 21:57 ` Jeremy Bryant via Emacs development discussions.
@ 2024-03-22 20:47 ` Jeremy Bryant
2024-03-22 20:50 ` Stefan Monnier
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-03-22 20:47 UTC (permalink / raw)
To: Stefan Monnier, Philip Kaludercic
Cc: Philip Kaludercic,
Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
Stefan Monnier, Stefan Kangas, Jonas Bernoulli
> What about another file - should the tests file be included in Emacs
> as part of the main Lisp macrostep?
>
>
> Should test files be added in the Emacs tree test/lisp/?
>
> [2. application/emacs-lisp; macrostep-test.el]...
Stefan/Philip,
I notice that in NonGNU ELPA's elpa-package there is this 'ignored-files' line:
(macrostep :url "https://github.com/emacsorphanage/macrostep"
:ignored-files ("macrostep-test.el"))
Can you confirm if this means that as part of the move of macrostep to
core, we don't need this test file in core Emacs?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-22 20:47 ` Jeremy Bryant
@ 2024-03-22 20:50 ` Stefan Monnier
0 siblings, 0 replies; 86+ messages in thread
From: Stefan Monnier @ 2024-03-22 20:50 UTC (permalink / raw)
To: Jeremy Bryant
Cc: Philip Kaludercic,
Jeremy Bryant via Emacs development discussions., Eli Zaretskii,
Stefan Kangas, Jonas Bernoulli
Jeremy Bryant [2024-03-22 20:47:06] wrote:
> I notice that in NonGNU ELPA's elpa-package there is this 'ignored-files' line:
> (macrostep :url "https://github.com/emacsorphanage/macrostep"
> :ignored-files ("macrostep-test.el"))
>
> Can you confirm if this means that as part of the move of macrostep to
> core, we don't need this test file in core Emacs?
No, I cannot confirm, on the contrary, we do want this file in
`emacs.git` (at the "mirror place" in `test/`, as usual).
The above `:ignored-files` is because someone did not want to force
every user to download the tests as well.
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: which-key tests from GNU ELPA into core
[not found] ` <87r0faibbg.fsf@jeremybryant.net>
@ 2024-04-12 20:40 ` Philip Kaludercic
0 siblings, 0 replies; 86+ messages in thread
From: Philip Kaludercic @ 2024-04-12 20:40 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: Eli Zaretskii, 68929, monnier, justin
Jeremy Bryant <jb@jeremybryant.net> writes:
> Philip,
>
> Attached is the test file for which-key, are any changes necessary prior
> to the move to core?
I have to admit that I am not too well versed with Emacs testing
infrastructure. Someone else (perhaps Mattias Engdegård) would probably
be in a better position to help you here.
> Thanks in advance
> Jeremy
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
[not found] ` <87wmp2ibjj.fsf@jeremybryant.net>
@ 2024-04-14 9:21 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 10:13 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-04-14 9:21 UTC (permalink / raw)
To: Philip Kaludercic; +Cc: Eli Zaretskii, 68929, monnier, justin
Jeremy Bryant <jb@jeremybryant.net> writes:
> Here is the current status on the road to adapting which-key code to
> merge into Emacs, and in adapting the code to the coding conventions and
> requirements for maintainability,
>
> I've followed comments from Eli and then Philip, there have been
> around 65 patches submitted upstream
> https://github.com/justbur/emacs-which-key/commits/master/
>
> Many thanks to Philip for the detailed code review and the many
> clarifications off-list, and to Justin, the author, for examining and
> merging the patches in preparation for this.
>
> I am currently looking at the merging of history, there appear to be 2
> historical commits which exceed the line length in CONTRIBUTE.
> If there is a recommended way to change them please let me know.
I have worked out the change command that work locally to allow these 2 historical
commits to be merged. (with thanks to Stefan)
git merge --no-verify --allow-unrelated-histories --no-edit
which-key-integration/which-key-prepare-integration
FYI the two exceptions were below. Allowing these would preserve the
copyright assignment tracking.
$ git log --oneline | awk 'length($0)>78+8'
;; :group 'which-key |ad8eb57 Merge branch 'better-window-sizes' of
https://github.com/bmag/emacs-which-key into better-window-sizes
;; :type 'string) |1fd43dc Merge branch 'frame-popup' of
https://github.com/bmag/emacs-which-key into pr12
>
> The latest version is attached, if there are any more comments they are
> welcome.
>
> [2. application/emacs-lisp; which-key.el]...
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-04-14 9:21 ` bug#68929: [PATCH] Copy which-key " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-04-14 10:13 ` Eli Zaretskii
2024-04-14 21:52 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-14 10:13 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: philipk, 68929, monnier, justin
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org,
> monnier@iro.umontreal.ca, justin@burkett.cc
> Date: Sun, 14 Apr 2024 10:21:24 +0100
>
> > I am currently looking at the merging of history, there appear to be 2
> > historical commits which exceed the line length in CONTRIBUTE.
> > If there is a recommended way to change them please let me know.
>
> I have worked out the change command that work locally to allow these 2 historical
> commits to be merged. (with thanks to Stefan)
>
> git merge --no-verify --allow-unrelated-histories --no-edit
> which-key-integration/which-key-prepare-integration
>
>
> FYI the two exceptions were below. Allowing these would preserve the
> copyright assignment tracking.
> $ git log --oneline | awk 'length($0)>78+8'
> ;; :group 'which-key |ad8eb57 Merge branch 'better-window-sizes' of
> https://github.com/bmag/emacs-which-key into better-window-sizes
> ;; :type 'string) |1fd43dc Merge branch 'frame-popup' of
> https://github.com/bmag/emacs-which-key into pr12
Is line length the only issue you are looking at? What about other
requirements of our logs and ChangeLog files, including those imposed
by authors.el? The most problematic issue is when the file names
and/or its leading directories in the log message don't fit the actual
place and name of the file in the tree. Did you look at those issues?
They typically come up when preparing a release tarball, and are quite
annoying at that time, especially if there are a lot of them, because
they require manual fixes.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-04-14 10:13 ` Eli Zaretskii
@ 2024-04-14 21:52 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 11:13 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-04-14 21:52 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: philipk, 68929, monnier, justin
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org,
>> monnier@iro.umontreal.ca, justin@burkett.cc
>> Date: Sun, 14 Apr 2024 10:21:24 +0100
>>
>> > I am currently looking at the merging of history, there appear to be 2
>> > historical commits which exceed the line length in CONTRIBUTE.
>> > If there is a recommended way to change them please let me know.
>>
>> I have worked out the change command that work locally to allow these 2 historical
>> commits to be merged. (with thanks to Stefan)
>>
>> git merge --no-verify --allow-unrelated-histories --no-edit
>> which-key-integration/which-key-prepare-integration
>>
>>
>> FYI the two exceptions were below. Allowing these would preserve the
>> copyright assignment tracking.
>> $ git log --oneline | awk 'length($0)>78+8'
>> ;; :group 'which-key |ad8eb57 Merge branch 'better-window-sizes' of
>> https://github.com/bmag/emacs-which-key into better-window-sizes
>> ;; :type 'string) |1fd43dc Merge branch 'frame-popup' of
>> https://github.com/bmag/emacs-which-key into pr12
>
> Is line length the only issue you are looking at? What about other
> requirements of our logs and ChangeLog files, including those imposed
> by authors.el? The most problematic issue is when the file names
> and/or its leading directories in the log message don't fit the actual
> place and name of the file in the tree. Did you look at those issues?
> They typically come up when preparing a release tarball, and are quite
> annoying at that time, especially if there are a lot of them, because
> they require manual fixes.
Yes, sorry, I have only looked at the line length because it came up as
a blocker.
As far as the file names, this appears stable, but the place in the tree
would move as part of this proposed integration, to be in
lisp/which-key.el rather than at the root as is the case for the ELPA
version. Is this a problem and how was it resolved with other moves
from ELPA to core?
Upon inspection, the earlier historical commits do not generally conform to the
Changelog format.
How to investigate any issues for authors.el? Is there a function try
and run?
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: Fwd: Re: bug#68929: which-key tests from GNU ELPA into core
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
` (2 preceding siblings ...)
2024-02-07 8:20 ` Philip Kaludercic
@ 2024-04-14 21:56 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 8:39 ` Mattias Engdegård
3 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-04-14 21:56 UTC (permalink / raw)
To: Mattias Engdegård, Mattias Engdegård, 68929,
Justin Burkett
[-- Attachment #1: Type: text/plain, Size: 363 bytes --]
-------------------- Start of forwarded message --------------------
From: Jeremy Bryant <jb@jeremybryant.net>
To: Philip Kaludercic <philipk@posteo.net>
Cc: Eli Zaretskii <eliz@gnu.org>, 68929@debbugs.gnu.org,
monnier@iro.umontreal.ca, justin@burkett.cc
Subject: Re: bug#68929: which-key tests from GNU ELPA into core
Date: Fri, 12 Apr 2024 21:18:59 +0100
[-- Attachment #2.1: Type: text/plain, Size: 130 bytes --]
Philip,
Attached is the test file for which-key, are any changes necessary prior
to the move to core?
Thanks in advance
Jeremy
[-- Attachment #2.2: which-key-tests.el --]
[-- Type: application/emacs-lisp, Size: 10425 bytes --]
[-- Attachment #3: Type: text/plain, Size: 267 bytes --]
-------------------- End of forwarded message --------------------
Mattias,
I understand you have expertise on the testing infrastructure, do you
have any comments on any work required to change this file or would it
be good to go 'as is'?
Thanks in advance
Jeremy
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: which-key tests from GNU ELPA into core
2024-04-14 21:56 ` bug#68929: Fwd: Re: bug#68929: which-key tests " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-04-15 8:39 ` Mattias Engdegård
0 siblings, 0 replies; 86+ messages in thread
From: Mattias Engdegård @ 2024-04-15 8:39 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: 68929, Justin Burkett
14 apr. 2024 kl. 23.56 skrev Jeremy Bryant <jb@jeremybryant.net>:
> Mattias,
> I understand you have expertise on the testing infrastructure, do you
> have any comments on any work required to change this file or would it
> be good to go 'as is'?
Well it looks all right as far as I can tell from a quick glance, but you are the one with domain knowledge here.
From the dept. of unimportant details: you may want to update the copyright year, and bug references such as "#109" could perhaps be annotated so that it's clear where to look (maybe use the full URL).
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-04-14 21:52 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-04-15 11:13 ` Eli Zaretskii
2024-04-29 21:00 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-15 11:13 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: philipk, 68929, monnier, justin
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: philipk@posteo.net, 68929@debbugs.gnu.org, monnier@iro.umontreal.ca,
> justin@burkett.cc
> Date: Sun, 14 Apr 2024 22:52:08 +0100
>
> > Is line length the only issue you are looking at? What about other
> > requirements of our logs and ChangeLog files, including those imposed
> > by authors.el? The most problematic issue is when the file names
> > and/or its leading directories in the log message don't fit the actual
> > place and name of the file in the tree. Did you look at those issues?
> > They typically come up when preparing a release tarball, and are quite
> > annoying at that time, especially if there are a lot of them, because
> > they require manual fixes.
>
> Yes, sorry, I have only looked at the line length because it came up as
> a blocker.
>
> As far as the file names, this appears stable, but the place in the tree
> would move as part of this proposed integration, to be in
> lisp/which-key.el rather than at the root as is the case for the ELPA
> version. Is this a problem and how was it resolved with other moves
> from ELPA to core?
Sorry, I don't remember the details. I probably fixed some issues by
hand, and for some others added/modified the relevant data structures
in admin/authors.el, which see.
> Upon inspection, the earlier historical commits do not generally conform to the
> Changelog format.
> How to investigate any issues for authors.el? Is there a function try
> and run?
The function is "M-x authors", defined in admin/authors.el. It first
updates ChangeLog.4, and then attempts the regenerate AUTHORS; you
will need to "git reset" to return to the current versions once you
are finished. The following extract from admin/make-tarball.txt gives
some guidance, and more information is available in comments to
authors.el:
After "M-x authors" finishes, if there is an "*Authors Errors*"
buffer, address the issues. If there was a ChangeLog typo, fix
the relevant entry. If a file was deleted or renamed, consider
adding an appropriate entry to variables authors-ignored-files,
authors-valid-file-names, or authors-renamed-files-alist in
authors.el. If some authors are "ignored", consider adding
entries to the author-aliases variable.
If necessary, repeat 'C-u M-x authors' after making those changes.
If you see too many problems than you can handle, feel free to give up
on them and leave them until the first pretest.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-03-18 12:48 ` Eli Zaretskii
2024-03-18 13:22 ` Stefan Monnier
2024-03-18 22:58 ` Jeremy Bryant
@ 2024-04-18 21:19 ` Jeremy Bryant
2024-04-19 6:38 ` Eli Zaretskii
2 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-04-18 21:19 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
[-- Attachment #1: Type: text/plain, Size: 474 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
>> stefan@marxist.se, stefankangas@gmail.com, jonas@bernoul.li
>> Date: Sun, 17 Mar 2024 21:48:08 +0000
>>
>> Manual?
>> Should the documentation for macrostep be included in the Emacs Lisp
>> manual section Macros?
>
> Yes, I think so.
>
Please find attached a patch for the manual.
Any comments welcome.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-manual-section-on-macrostep.patch --]
[-- Type: text/x-diff, Size: 4750 bytes --]
From cef9258e824d7a20c8364417c9debd8b2d5133fe Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Thu, 18 Apr 2024 21:03:30 +0100
Subject: [PATCH] Add new manual section on macrostep
* doc/lispref/macros.texi (Macros):
Describe macrostep's usage to explore and write macros.
This is based on Jonathan's Oddie's documentation in the macrostep package
Co-authored-by: Jonathan Oddie <j.j.oddie@gmail.com>
---
doc/lispref/macros.texi | 69 ++++++++++++++++++++++++++++++++++-------
1 file changed, 58 insertions(+), 11 deletions(-)
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 659dba17524..06e098a8389 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -23,13 +23,14 @@ Macros
instead. @xref{Inline Functions}.
@menu
-* Simple Macro:: A basic example.
-* Expansion:: How, when and why macros are expanded.
-* Compiling Macros:: How macros are expanded by the compiler.
-* Defining Macros:: How to write a macro definition.
-* Problems with Macros:: Don't evaluate the macro arguments too many times.
+* Simple Macro:: A basic example.
+* Expansion:: How, when and why macros are expanded.
+* Compiling Macros:: How macros are expanded by the compiler.
+* Defining Macros:: How to write a macro definition.
+* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
-* Indenting Macros:: Specifying how to indent macro calls.
+* Indenting Macros:: Specifying how to indent macro calls.
+* macrostep: interactive macro-expander::
@end menu
@node Simple Macro
@@ -262,12 +263,12 @@ Problems with Macros
trouble, and rules to follow to avoid trouble.
@menu
-* Wrong Time:: Do the work in the expansion, not in the macro.
-* Argument Evaluation:: The expansion should evaluate each macro arg once.
-* Surprising Local Vars:: Local variable bindings in the expansion
+* Wrong Time:: Do the work in the expansion, not in the macro.
+* Argument Evaluation:: The expansion should evaluate each macro arg once.
+* Surprising Local Vars:: Local variable bindings in the expansion
require special care.
-* Eval During Expansion:: Don't evaluate them; put them in the expansion.
-* Repeated Expansion:: Avoid depending on how many times expansion is done.
+* Eval During Expansion:: Don't evaluate them; put them in the expansion.
+* Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu
@node Wrong Time
@@ -640,3 +641,49 @@ Indenting Macros
number, @kbd{C-M-q} need not recalculate indentation for the following
lines until the end of the list.
@end table
+
+
+@node macrostep: interactive macro-expander
+@section macrostep: interactive macro-expander
+
+You can use the package @code{macrostep} to explore macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand}.
+
+@ifnottex
+@kbd{macrostep} is an Emacs minor mode for interactively stepping
+through the expansion of macros in Emacs Lisp source code. It lets you
+see exactly what happens at each step of the expansion process by
+pretty-printing the expanded forms inline in the source buffer, which is
+temporarily read-only while macro expansions are visible. You can
+expand and collapse macro forms one step at a time, and evaluate or
+instrument the expansions for debugging with Edebug as normal.
+Single-stepping through the expansion is particularly useful for
+debugging macros that expand into another macro form. These can be
+difficult to debug with @code{macroexpand}, which continues expansion
+until the top-level form is no longer a macro call.
+
+The standard keybindings in @code{macrostep-mode} are the following:
+
+@itemize @minus
+@item
+e, =, RET : expand the macro form following point one step
+@item
+c, u, DEL : collapse the form following point
+@item
+q, C-c C-c: collapse all expanded forms and exit macrostep-mode
+@item
+n, TAB : jump to the next macro form in the expansion
+@item
+p, M-TAB : jump to the previous macro form in the expansion
+@end itemize
+
+It's not very useful to enable and disable macrostep-mode directly.
+Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
+for example @kbd{C-c e}.
+
+You can then enter @code{macrostep-mode} and expand a macro form completely
+by typing @kbd{C-c e e e}@dots as many times as necessary.
+
+Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by successively
+typing @kbd{c} to collapse all surrounding expansions.
+@end ifnottex
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-18 21:19 ` Jeremy Bryant
@ 2024-04-19 6:38 ` Eli Zaretskii
2024-04-19 19:30 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-19 6:38 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Thu, 18 Apr 2024 22:19:36 +0100
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Jeremy Bryant <jb@jeremybryant.net>
> >> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org, j.j.oddie@gmail.com,
> >> stefan@marxist.se, stefankangas@gmail.com, jonas@bernoul.li
> >> Date: Sun, 17 Mar 2024 21:48:08 +0000
> >>
> >> Manual?
> >> Should the documentation for macrostep be included in the Emacs Lisp
> >> manual section Macros?
> >
> > Yes, I think so.
> >
>
> Please find attached a patch for the manual.
> Any comments welcome.
Thanks, see below.
> * doc/lispref/macros.texi (Macros):
> Describe macrostep's usage to explore and write macros.
This is filled sub-optimally; please use change-log-mode to help you
fill better.
> This is based on Jonathan's Oddie's documentation in the macrostep package
Likewise here: this line is too long.
> -* Simple Macro:: A basic example.
> -* Expansion:: How, when and why macros are expanded.
> -* Compiling Macros:: How macros are expanded by the compiler.
> -* Defining Macros:: How to write a macro definition.
> -* Problems with Macros:: Don't evaluate the macro arguments too many times.
> +* Simple Macro:: A basic example.
> +* Expansion:: How, when and why macros are expanded.
> +* Compiling Macros:: How macros are expanded by the compiler.
> +* Defining Macros:: How to write a macro definition.
> +* Problems with Macros:: Don't evaluate the macro arguments too many times.
> Don't hide the user's variables.
> -* Indenting Macros:: Specifying how to indent macro calls.
> +* Indenting Macros:: Specifying how to indent macro calls.
> +* macrostep: interactive macro-expander::
I'd prefer not to change whitespace here. I see no reason for it in
this case.
Also, any change in the menus requires a corresponding change in
elisp.texi, where we have the @detailmenu.
> @menu
> -* Wrong Time:: Do the work in the expansion, not in the macro.
> -* Argument Evaluation:: The expansion should evaluate each macro arg once.
> -* Surprising Local Vars:: Local variable bindings in the expansion
> +* Wrong Time:: Do the work in the expansion, not in the macro.
> +* Argument Evaluation:: The expansion should evaluate each macro arg once.
> +* Surprising Local Vars:: Local variable bindings in the expansion
> require special care.
> -* Eval During Expansion:: Don't evaluate them; put them in the expansion.
> -* Repeated Expansion:: Avoid depending on how many times expansion is done.
> +* Eval During Expansion:: Don't evaluate them; put them in the expansion.
> +* Repeated Expansion:: Avoid depending on how many times expansion is done.
Unnecessary whitespace changes again.
> +@node macrostep: interactive macro-expander
> +@section macrostep: interactive macro-expander
> +
> +You can use the package @code{macrostep} to explore macro definitions, and
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"You can use the @code{macrostep} package" is better.
Alternatively, say "@code{macrostep-mode}" instead; no need to mention
that it's a package.
> +help write new macros, using @kbd{M-x macrostep-expand}.
> +
> +@ifnottex
This @ifnottex makes this section very small in the printed manual,
which I think is undesirable. Instead, I'd move the sentence above to
the parent chapter, and have the entire section be inside @ifnottex
(also in menus).
> +@kbd{macrostep} is an Emacs minor mode for interactively stepping
There's no point of having "Emacs" there, since this manual is about
Emacs Lisp.
> +through the expansion of macros in Emacs Lisp source code. It lets you
> +see exactly what happens at each step of the expansion process by
> +pretty-printing the expanded forms inline in the source buffer, which is
> +temporarily read-only while macro expansions are visible. You can
> +expand and collapse macro forms one step at a time, and evaluate or
> +instrument the expansions for debugging with Edebug as normal.
^^^^^^^^^
"as usual"
> +The standard keybindings in @code{macrostep-mode} are the following:
> +
> +@itemize @minus
> +@item
> +e, =, RET : expand the macro form following point one step
This will produce sub-optimal markup. I suggest to use "@table @kbd"
instead.
Also, our style is to mention the command bound to the keys in
parentheses, and also index each such command.
> +It's not very useful to enable and disable macrostep-mode directly.
> +Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
These two should be in @code instead of in quotes `like this'.
> +by typing @kbd{C-c e e e}@dots as many times as necessary.
@dots{} (not "@dots") should be inside @kbd.
And finally, two more questions:
. should this be in the user manual instead? it sounds like a
user-level feature, not Lisp programming level feature
. how is this mode different from "C-x C-k SPC", which is already
described in the user manual as a similar feature?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-19 6:38 ` Eli Zaretskii
@ 2024-04-19 19:30 ` Jeremy Bryant
2024-04-19 22:26 ` Stefan Monnier
2024-04-20 6:00 ` Eli Zaretskii
0 siblings, 2 replies; 86+ messages in thread
From: Jeremy Bryant @ 2024-04-19 19:30 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> >> Should the documentation for macrostep be included in the Emacs Lisp
>> >> manual section Macros?
>> >
>> > Yes, I think so.
For convenience, to recap from a month ago, this facility is about Lisp
macros, not keyboard macros. macrostep is useful for Emacs Lisp macro
expansion or exploration, and development.
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> * doc/lispref/macros.texi (Macros):
>> Describe macrostep's usage to explore and write macros.
>
> This is filled sub-optimally; please use change-log-mode to help you
> fill better.
Thank you for the pointer, I will use in future.
For this commit I have used magit-generate-changelog, is this suboptimal?
(..)
Thank you for all the comments on style, I will work on that.
(...)
> And finally, two more questions:
>
> . should this be in the user manual instead? it sounds like a
> user-level feature, not Lisp programming level feature
Sure, perhaps this is more suited.
I initially followed your confirmation to write in the Emacs Lisp manual
(top of this message), but indeed this may belong more appropriately in
the Emacs manual. How about in "(emacs) Programs"?
Please confirm your preference either way and I'll continue the rewrite.
> . how is this mode different from "C-x C-k SPC", which is already
> described in the user manual as a similar feature?
Thanks, I'll be clearer in the next iteration. This facility is about
Lisp macros, not keyboard macros. ('C-x C-k SPC runs the command
kmacro-step-edit-macro'). I'll improve the documentation in the next round.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-19 19:30 ` Jeremy Bryant
@ 2024-04-19 22:26 ` Stefan Monnier
2024-04-20 6:07 ` Eli Zaretskii
2024-04-20 6:00 ` Eli Zaretskii
1 sibling, 1 reply; 86+ messages in thread
From: Stefan Monnier @ 2024-04-19 22:26 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: Eli Zaretskii, emacs-devel
> I initially followed your confirmation to write in the Emacs Lisp manual
> (top of this message), but indeed this may belong more appropriately in
> the Emacs manual. How about in "(emacs) Programs"?
> Please confirm your preference either way and I'll continue the rewrite.
If it works only for Emacs Lisp macros, then it makes sense to put it in
the ELisp manual. But if it provides a "generic" interface with
backends for various languages, then it might make sense to document it in
the Emacs manual. And the two are not necessarily mutually exclusive
unless one makes the other redundant.
Stefan
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-19 19:30 ` Jeremy Bryant
2024-04-19 22:26 ` Stefan Monnier
@ 2024-04-20 6:00 ` Eli Zaretskii
2024-04-23 21:37 ` Jeremy Bryant
1 sibling, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-20 6:00 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Fri, 19 Apr 2024 20:30:30 +0100
>
> > . should this be in the user manual instead? it sounds like a
> > user-level feature, not Lisp programming level feature
>
> Sure, perhaps this is more suited.
>
> I initially followed your confirmation to write in the Emacs Lisp manual
> (top of this message), but indeed this may belong more appropriately in
> the Emacs manual. How about in "(emacs) Programs"?
Yes, a section under "Programs" sounds good.
Thanks.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-19 22:26 ` Stefan Monnier
@ 2024-04-20 6:07 ` Eli Zaretskii
2024-04-20 17:14 ` Adam Porter
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-20 6:07 UTC (permalink / raw)
To: Stefan Monnier; +Cc: jb, emacs-devel
> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> Date: Fri, 19 Apr 2024 18:26:11 -0400
>
> > I initially followed your confirmation to write in the Emacs Lisp manual
> > (top of this message), but indeed this may belong more appropriately in
> > the Emacs manual. How about in "(emacs) Programs"?
> > Please confirm your preference either way and I'll continue the rewrite.
>
> If it works only for Emacs Lisp macros, then it makes sense to put it in
> the ELisp manual.
It's a minor mode, and the documentation describes commands of that
mode. I don't think the ELisp manual is a good place for such
features. We have "Programs" in the user manual, which describes
features for developing programs using Emacs, and I think it's a good
place for describing this feature.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-20 6:07 ` Eli Zaretskii
@ 2024-04-20 17:14 ` Adam Porter
0 siblings, 0 replies; 86+ messages in thread
From: Adam Porter @ 2024-04-20 17:14 UTC (permalink / raw)
To: eliz; +Cc: emacs-devel, jb, monnier
>> If it works only for Emacs Lisp macros, then it makes sense to put it in
>> the ELisp manual.
>
> It's a minor mode, and the documentation describes commands of that
> mode. I don't think the ELisp manual is a good place for such
> features. We have "Programs" in the user manual, which describes
> features for developing programs using Emacs, and I think it's a good
> place for describing this feature.
Not that I necessarily disagree, but I think it warrants at least a
mention in the Elisp manual section about macros, because it's very
helpful for understanding how macros work. If it were only mentioned in
the Emacs manual, new Elispers who are reading up on macros could easily
overlook this great tool.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-20 6:00 ` Eli Zaretskii
@ 2024-04-23 21:37 ` Jeremy Bryant
2024-04-25 15:30 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-04-23 21:37 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
[-- Attachment #1: Type: text/plain, Size: 858 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> Date: Fri, 19 Apr 2024 20:30:30 +0100
>>
>> > . should this be in the user manual instead? it sounds like a
>> > user-level feature, not Lisp programming level feature
>>
>> Sure, perhaps this is more suited.
>>
>> I initially followed your confirmation to write in the Emacs Lisp manual
>> (top of this message), but indeed this may belong more appropriately in
>> the Emacs manual. How about in "(emacs) Programs"?
>
> Yes, a section under "Programs" sounds good.
>
> Thanks.
Please find attached a revised patch for consideration. Any feedback on
style and conventions welcome.
Text is adapted from the macrostep package - I believe Jonathan's FSF
paperwork is still outstanding but is expected soon.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-manual-section-on-macrostep.patch --]
[-- Type: text/x-diff, Size: 4750 bytes --]
From cef9258e824d7a20c8364417c9debd8b2d5133fe Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Thu, 18 Apr 2024 21:03:30 +0100
Subject: [PATCH] Add new manual section on macrostep
* doc/lispref/macros.texi (Macros):
Describe macrostep's usage to explore and write macros.
This is based on Jonathan's Oddie's documentation in the macrostep package
Co-authored-by: Jonathan Oddie <j.j.oddie@gmail.com>
---
doc/lispref/macros.texi | 69 ++++++++++++++++++++++++++++++++++-------
1 file changed, 58 insertions(+), 11 deletions(-)
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 659dba17524..06e098a8389 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -23,13 +23,14 @@ Macros
instead. @xref{Inline Functions}.
@menu
-* Simple Macro:: A basic example.
-* Expansion:: How, when and why macros are expanded.
-* Compiling Macros:: How macros are expanded by the compiler.
-* Defining Macros:: How to write a macro definition.
-* Problems with Macros:: Don't evaluate the macro arguments too many times.
+* Simple Macro:: A basic example.
+* Expansion:: How, when and why macros are expanded.
+* Compiling Macros:: How macros are expanded by the compiler.
+* Defining Macros:: How to write a macro definition.
+* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
-* Indenting Macros:: Specifying how to indent macro calls.
+* Indenting Macros:: Specifying how to indent macro calls.
+* macrostep: interactive macro-expander::
@end menu
@node Simple Macro
@@ -262,12 +263,12 @@ Problems with Macros
trouble, and rules to follow to avoid trouble.
@menu
-* Wrong Time:: Do the work in the expansion, not in the macro.
-* Argument Evaluation:: The expansion should evaluate each macro arg once.
-* Surprising Local Vars:: Local variable bindings in the expansion
+* Wrong Time:: Do the work in the expansion, not in the macro.
+* Argument Evaluation:: The expansion should evaluate each macro arg once.
+* Surprising Local Vars:: Local variable bindings in the expansion
require special care.
-* Eval During Expansion:: Don't evaluate them; put them in the expansion.
-* Repeated Expansion:: Avoid depending on how many times expansion is done.
+* Eval During Expansion:: Don't evaluate them; put them in the expansion.
+* Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu
@node Wrong Time
@@ -640,3 +641,49 @@ Indenting Macros
number, @kbd{C-M-q} need not recalculate indentation for the following
lines until the end of the list.
@end table
+
+
+@node macrostep: interactive macro-expander
+@section macrostep: interactive macro-expander
+
+You can use the package @code{macrostep} to explore macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand}.
+
+@ifnottex
+@kbd{macrostep} is an Emacs minor mode for interactively stepping
+through the expansion of macros in Emacs Lisp source code. It lets you
+see exactly what happens at each step of the expansion process by
+pretty-printing the expanded forms inline in the source buffer, which is
+temporarily read-only while macro expansions are visible. You can
+expand and collapse macro forms one step at a time, and evaluate or
+instrument the expansions for debugging with Edebug as normal.
+Single-stepping through the expansion is particularly useful for
+debugging macros that expand into another macro form. These can be
+difficult to debug with @code{macroexpand}, which continues expansion
+until the top-level form is no longer a macro call.
+
+The standard keybindings in @code{macrostep-mode} are the following:
+
+@itemize @minus
+@item
+e, =, RET : expand the macro form following point one step
+@item
+c, u, DEL : collapse the form following point
+@item
+q, C-c C-c: collapse all expanded forms and exit macrostep-mode
+@item
+n, TAB : jump to the next macro form in the expansion
+@item
+p, M-TAB : jump to the previous macro form in the expansion
+@end itemize
+
+It's not very useful to enable and disable macrostep-mode directly.
+Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
+for example @kbd{C-c e}.
+
+You can then enter @code{macrostep-mode} and expand a macro form completely
+by typing @kbd{C-c e e e}@dots as many times as necessary.
+
+Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by successively
+typing @kbd{c} to collapse all surrounding expansions.
+@end ifnottex
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-23 21:37 ` Jeremy Bryant
@ 2024-04-25 15:30 ` Eli Zaretskii
2024-04-25 21:27 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-25 15:30 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Tue, 23 Apr 2024 22:37:50 +0100
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Jeremy Bryant <jb@jeremybryant.net>
> >> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> >> Date: Fri, 19 Apr 2024 20:30:30 +0100
> >>
> >> > . should this be in the user manual instead? it sounds like a
> >> > user-level feature, not Lisp programming level feature
> >>
> >> Sure, perhaps this is more suited.
> >>
> >> I initially followed your confirmation to write in the Emacs Lisp manual
> >> (top of this message), but indeed this may belong more appropriately in
> >> the Emacs manual. How about in "(emacs) Programs"?
> >
> > Yes, a section under "Programs" sounds good.
> >
> > Thanks.
>
> Please find attached a revised patch for consideration. Any feedback on
> style and conventions welcome.
>
> Text is adapted from the macrostep package - I believe Jonathan's FSF
> paperwork is still outstanding but is expected soon.
Thanks, but it looks like you attached the wrong patch? It seems like
it's the same patch you sent the first time, not a revised one after
all the comments above, where we agreed to have this in the Emacs user
manual instead.
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-25 15:30 ` Eli Zaretskii
@ 2024-04-25 21:27 ` Jeremy Bryant
2024-04-26 8:15 ` Eshel Yaron
2024-04-27 9:52 ` Eli Zaretskii
0 siblings, 2 replies; 86+ messages in thread
From: Jeremy Bryant @ 2024-04-25 21:27 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
[-- Attachment #1: Type: text/plain, Size: 1417 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> Date: Tue, 23 Apr 2024 22:37:50 +0100
>>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> >> From: Jeremy Bryant <jb@jeremybryant.net>
>> >> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> >> Date: Fri, 19 Apr 2024 20:30:30 +0100
>> >>
>> >> > . should this be in the user manual instead? it sounds like a
>> >> > user-level feature, not Lisp programming level feature
>> >>
>> >> Sure, perhaps this is more suited.
>> >>
>> >> I initially followed your confirmation to write in the Emacs Lisp manual
>> >> (top of this message), but indeed this may belong more appropriately in
>> >> the Emacs manual. How about in "(emacs) Programs"?
>> >
>> > Yes, a section under "Programs" sounds good.
>> >
>> > Thanks.
>>
>> Please find attached a revised patch for consideration. Any feedback on
>> style and conventions welcome.
>>
>> Text is adapted from the macrostep package - I believe Jonathan's FSF
>> paperwork is still outstanding but is expected soon.
>
> Thanks, but it looks like you attached the wrong patch? It seems like
> it's the same patch you sent the first time, not a revised one after
> all the comments above, where we agreed to have this in the Emacs user
> manual instead.
Absolutely, sorry, attached is the revised patch I have worked on.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-Macrostep-section-in-manual.patch --]
[-- Type: text/x-diff, Size: 3724 bytes --]
From 0ed5971e7a54abe299386ce53e681b16cdb135c5 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Tue, 23 Apr 2024 22:21:07 +0100
Subject: [PATCH] Add Macrostep section in manual
Macrostep is an Emacs Lisp macro-expander useful for exploring and
writing macros. This is based on Jonathan's Oddie's documentation
in the macrostep package.
* doc/emacs/programs.texi (Programs): Add Macrostep section.
* doc/emacs/emacs.texi (Top): Add detailed menu reference.
---
doc/emacs/emacs.texi | 3 ++
doc/emacs/programs.texi | 61 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 64 insertions(+)
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7d77f13ab21..d4d0a753576 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -694,6 +694,9 @@ Top
@ifnottex
* Fortran:: Fortran mode and its special features.
@end ifnottex
+@ifnottex
+* Macrostep:: Interactive Lisp macro-expander.
+@end ifnottex
Top-Level Definitions, or Defuns
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index de28a9f1dd4..15cfffc289b 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -45,6 +45,10 @@ Programs
@ifnottex
* Fortran:: Fortran mode and its special features.
@end ifnottex
+@ifnottex
+* Macrostep:: Interactive Lisp macro-expander.
+@end ifnottex
+
@end menu
@node Program Modes
@@ -2235,3 +2239,60 @@ Asm Mode
@ifnottex
@include fortran-xtra.texi
@end ifnottex
+
+@ifnottex
+@node Macrostep
+@section Macrostep: interactive Lisp macro-expander
+
+You can use @code{macrostep-mode} to explore Lisp macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand} when point is
+over a macro.
+
+@kbd{macrostep} is a minor mode for interactively stepping through the
+expansion of macros in Emacs Lisp source code. It lets you see exactly
+what happens at each step of the expansion process by pretty-printing
+the expanded forms inline in the source buffer, which is temporarily
+read-only while macro expansions are visible. You can expand and
+collapse macro forms one step at a time, and evaluate or instrument the
+expansions for debugging with Edebug as usual. Single-stepping through
+the expansion is particularly useful for debugging macros that expand
+into another macro form. These can be difficult to debug with
+@code{macroexpand}, which continues expansion until the top-level form
+is no longer a macro call.
+
+The standard keybindings in @code{macrostep-mode} are the following:
+@table @kbd
+@item e
+@itemx =
+@itemx RET
+@findex macrostep-expand
+Expand the macro form following point one step (@code{macrostep-expand}).
+@item c
+@itemx u
+@itemx DEL
+@findex macrostep-collapse
+Collapse the form following point (@code{macrostep-collapse}).
+@item n
+@itemx TAB
+@findex macrostep-next-macro
+Jump to the next macro form in the expansion (@code{macrostep-next-macro}).
+@item p
+@itemx M-TAB
+@findex macrostep-previous-macro
+Jump to the previous macro form in the expansion (@code{macrostep-previous-macro}).
+@item q
+@itemx C-c C-c
+@findex macrostep-collapse-all
+Collapse all expanded forms and exit macrostep-mode (@code{macrostep-collapse-all}).
+@end table
+
+It's not very useful to enable and disable macrostep-mode directly.
+Instead, bind @code{macrostep-expand} to a key in
+@code{emacs-lisp-mode-map}, for example @kbd{C-c e}.
+
+You can then enter @code{macrostep-mode} and expand a macro form
+completely by typing @kbd{C-c e e e@dots{}} as many times as necessary.
+
+Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by
+successively typing @kbd{c} to collapse all surrounding expansions.
+@end ifnottex
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-25 21:27 ` Jeremy Bryant
@ 2024-04-26 8:15 ` Eshel Yaron
2024-04-27 9:52 ` Eli Zaretskii
1 sibling, 0 replies; 86+ messages in thread
From: Eshel Yaron @ 2024-04-26 8:15 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: Eli Zaretskii, monnier, emacs-devel
Hello Jeremy,
Jeremy Bryant <jb@jeremybryant.net> writes:
> ...attached is the revised patch I have worked on.
A few minor comments:
> From 0ed5971e7a54abe299386ce53e681b16cdb135c5 Mon Sep 17 00:00:00 2001
> From: Jeremy Bryant <jb@jeremybryant.net>
> Date: Tue, 23 Apr 2024 22:21:07 +0100
> Subject: [PATCH] Add Macrostep section in manual
>
> Macrostep is an Emacs Lisp macro-expander useful for exploring and
> writing macros. This is based on Jonathan's Oddie's documentation
> in the macrostep package.
>
> * doc/emacs/programs.texi (Programs): Add Macrostep section.
> * doc/emacs/emacs.texi (Top): Add detailed menu reference.
> ---
> doc/emacs/emacs.texi | 3 ++
> doc/emacs/programs.texi | 61 +++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 64 insertions(+)
>
> diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
> index 7d77f13ab21..d4d0a753576 100644
> --- a/doc/emacs/emacs.texi
> +++ b/doc/emacs/emacs.texi
> @@ -694,6 +694,9 @@ Top
> @ifnottex
> * Fortran:: Fortran mode and its special features.
> @end ifnottex
> +@ifnottex
> +* Macrostep:: Interactive Lisp macro-expander.
IIUC, this is specific to Emacs Lisp, right? If so, I suggest writing
"Elisp" or "Emacs Lisp" instead of "Lisp" here, for clarity.
> +@end ifnottex
>
> Top-Level Definitions, or Defuns
>
> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
> index de28a9f1dd4..15cfffc289b 100644
> --- a/doc/emacs/programs.texi
> +++ b/doc/emacs/programs.texi
> @@ -45,6 +45,10 @@ Programs
> @ifnottex
> * Fortran:: Fortran mode and its special features.
> @end ifnottex
> +@ifnottex
> +* Macrostep:: Interactive Lisp macro-expander.
Likewise here.
> +@end ifnottex
> +
> @end menu
>
> @node Program Modes
> @@ -2235,3 +2239,60 @@ Asm Mode
> @ifnottex
> @include fortran-xtra.texi
> @end ifnottex
> +
> +@ifnottex
> +@node Macrostep
> +@section Macrostep: interactive Lisp macro-expander
> +
I'd open with a few more words of motivation, e.g. "Emacs Lisp code that
you read and write often makes use of macros (@pxref{Macros,,,elisp})."
> +You can use @code{macrostep-mode} to explore Lisp macro definitions, and
> +help write new macros...
Since macrostep-mode is not intended to be enabled directly, I suggest
putting less emphasis on the minor mode and more on the feature itself,
so maybe something like "Emacs comes with a feature called
@dfn{Macrostep} that helps you explore and write new macros"
> ...using @kbd{M-x macrostep-expand} when point is
> +over a macro.
Here I think that "when point is over a macro" could be made a little
more precise. How about "when point is inside a macro form" or
something along these lines?
> +@kbd{macrostep} is a minor mode for interactively stepping through the
> +expansion of macros in Emacs Lisp source code.
"Macrostep lets you step through the expansion of macros interactively."
> It lets you see exactly
> +what happens at each step of the expansion process by pretty-printing
> +the expanded forms inline in the source buffer, which is temporarily
> +read-only while macro expansions are visible. You can expand and
> +collapse macro forms one step at a time, and evaluate or instrument the
> +expansions for debugging with Edebug as usual.
Maybe add a reference to Edebug?
> Single-stepping through
> +the expansion is particularly useful for debugging macros that expand
> +into another macro form. These can be difficult to debug with
> +@code{macroexpand}, which continues expansion until the top-level form
> +is no longer a macro call.
The comparison with macroexpand seems a bit like a straw-man argument in
favor of Macrostep, what about macroexpand-1? IMO, we can just remove
these two sentences. The utility of Macrostep is clear enough as is.
> +
> +The standard keybindings in @code{macrostep-mode} are the following:
> +@table @kbd
> +@item e
> +@itemx =
> +@itemx RET
> +@findex macrostep-expand
> +Expand the macro form following point one step (@code{macrostep-expand}).
"following point"? ISTM that this command expands the first macro form
containing point, no?
> +@item c
> +@itemx u
> +@itemx DEL
> +@findex macrostep-collapse
> +Collapse the form following point (@code{macrostep-collapse}).
Likewise.
> +@item n
> +@itemx TAB
> +@findex macrostep-next-macro
> +Jump to the next macro form in the expansion (@code{macrostep-next-macro}).
> +@item p
> +@itemx M-TAB
> +@findex macrostep-previous-macro
> +Jump to the previous macro form in the expansion (@code{macrostep-previous-macro}).
> +@item q
> +@itemx C-c C-c
> +@findex macrostep-collapse-all
> +Collapse all expanded forms and exit macrostep-mode (@code{macrostep-collapse-all}).
> +@end table
> +
> +It's not very useful to enable and disable macrostep-mode directly.
This sentence isn't necessary IMO.
> +Instead, bind @code{macrostep-expand} to a key in
> +@code{emacs-lisp-mode-map}, for example @kbd{C-c e}.
Maybe add example code for how to do that? Or just refer to some
relevant part of the manual for defining key bindings.
> +
> +You can then enter @code{macrostep-mode} and expand a macro form
> +completely by typing @kbd{C-c e e e@dots{}} as many times as necessary.
> +
> +Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by
> +successively typing @kbd{c} to collapse all surrounding expansions.
> +@end ifnottex
Best regards,
Eshel
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-25 21:27 ` Jeremy Bryant
2024-04-26 8:15 ` Eshel Yaron
@ 2024-04-27 9:52 ` Eli Zaretskii
2024-04-29 21:38 ` Jeremy Bryant
1 sibling, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-04-27 9:52 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Thu, 25 Apr 2024 22:27:56 +0100
>
> Absolutely, sorry, attached is the revised patch I have worked on.
Thanks, a few minor comments below.
> Subject: [PATCH] Add Macrostep section in manual
>
> Macrostep is an Emacs Lisp macro-expander useful for exploring and
> writing macros. This is based on Jonathan's Oddie's documentation
> in the macrostep package.
>
> * doc/emacs/programs.texi (Programs): Add Macrostep section.
> * doc/emacs/emacs.texi (Top): Add detailed menu reference.
^^^^^^^ ^^^
Those TABs should not be there in the commit log message.
> +You can use @code{macrostep-mode} to explore Lisp macro definitions, and
> +help write new macros, using @kbd{M-x macrostep-expand} when point is
> +over a macro.
We say "when point is in a macro". "Over" is reserved for mouse
pointer.
> +@kbd{macrostep} is a minor mode for interactively stepping through the
^^^^^^^^^
"macrostep-mode", I guess? And why @kbd? is that something the user
is supposed to type?
> +The standard keybindings in @code{macrostep-mode} are the following:
> +@table @kbd
> +@item e
> +@itemx =
> +@itemx RET
> +@findex macrostep-expand
Please move the index entries to _before_ the corresponding @item's,
so that following the index entry lands you on the @item, not after
it.
Otherwise, this LGTM, thanks.
^ permalink raw reply [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-04-15 11:13 ` Eli Zaretskii
@ 2024-04-29 21:00 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-05-01 7:31 ` Philip Kaludercic
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-04-29 21:00 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: philipk, 68929, monnier, justin
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: philipk@posteo.net, 68929@debbugs.gnu.org, monnier@iro.umontreal.ca,
>> justin@burkett.cc
>> Date: Sun, 14 Apr 2024 22:52:08 +0100
>>
>> > Is line length the only issue you are looking at? What about other
>> > requirements of our logs and ChangeLog files, including those imposed
>> > by authors.el? The most problematic issue is when the file names
>> > and/or its leading directories in the log message don't fit the actual
>> > place and name of the file in the tree. Did you look at those issues?
>> > They typically come up when preparing a release tarball, and are quite
>> > annoying at that time, especially if there are a lot of them, because
>> > they require manual fixes.
>>
>> Yes, sorry, I have only looked at the line length because it came up as
>> a blocker.
>>
>> As far as the file names, this appears stable, but the place in the tree
>> would move as part of this proposed integration, to be in
>> lisp/which-key.el rather than at the root as is the case for the ELPA
>> version. Is this a problem and how was it resolved with other moves
>> from ELPA to core?
>
> Sorry, I don't remember the details. I probably fixed some issues by
> hand, and for some others added/modified the relevant data structures
> in admin/authors.el, which see.
>
>> Upon inspection, the earlier historical commits do not generally conform to the
>> Changelog format.
>> How to investigate any issues for authors.el? Is there a function try
>> and run?
>
> The function is "M-x authors", defined in admin/authors.el. It first
> updates ChangeLog.4, and then attempts the regenerate AUTHORS; you
> will need to "git reset" to return to the current versions once you
> are finished. The following extract from admin/make-tarball.txt gives
> some guidance, and more information is available in comments to
> authors.el:
>
> After "M-x authors" finishes, if there is an "*Authors Errors*"
> buffer, address the issues. If there was a ChangeLog typo, fix
> the relevant entry. If a file was deleted or renamed, consider
> adding an appropriate entry to variables authors-ignored-files,
> authors-valid-file-names, or authors-renamed-files-alist in
> authors.el. If some authors are "ignored", consider adding
> entries to the author-aliases variable.
>
> If necessary, repeat 'C-u M-x authors' after making those changes.
>
> If you see too many problems than you can handle, feel free to give up
> on them and leave them until the first pretest.
Eli, thanks for the patient explanations however I have not the time to
work on this in detail due to the complexity.
Philip, as you separately proposed to investigate. Here is a compact
updated summary of Stefan's prior
recommendations to merge the history to preserve the contributor
history/assignments:
"BTW, rather than adding a file, another way to add it to `emacs.git` is
by `git merge --allow-unrelated-histories`.
If you want to do that, you'll want to first create a new commit which
moves the files to their "final" destination, like:
git rm .gitignore .github Makefile LICENSE.md ...
git mv which-key.el lisp/which-key.el
git mv which-key-tests.el test/lisp/which-key-tests.el
git commit -m 'Move files in preparation for merge into emacs.git'
and then you can `git merge` that new commit into Emacs, preserving
the history.
The commands above should be done in a branch containing the which-key history.
Then you go to a branch of Emacs [add a remote pointing to the which-key
repo modified as above] and do
git merge --no-verify --allow-unrelated-histories --no-edit which-key-integration/which-key-prepare-integration
git push"
Start with the upstream which includes all changes discussed
https://github.com/justbur/emacs-which-key/
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-27 9:52 ` Eli Zaretskii
@ 2024-04-29 21:38 ` Jeremy Bryant
2024-05-02 9:32 ` Eli Zaretskii
0 siblings, 1 reply; 86+ messages in thread
From: Jeremy Bryant @ 2024-04-29 21:38 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> Date: Thu, 25 Apr 2024 22:27:56 +0100
>>
>> Absolutely, sorry, attached is the revised patch I have worked on.
>
> Thanks, a few minor comments below.
>
>> Subject: [PATCH] Add Macrostep section in manual
>>
>> Macrostep is an Emacs Lisp macro-expander useful for exploring and
>> writing macros. This is based on Jonathan's Oddie's documentation
>> in the macrostep package.
>>
>> * doc/emacs/programs.texi (Programs): Add Macrostep section.
>> * doc/emacs/emacs.texi (Top): Add detailed menu reference.
> ^^^^^^^ ^^^
> Those TABs should not be there in the commit log message.
>
>> +You can use @code{macrostep-mode} to explore Lisp macro definitions, and
>> +help write new macros, using @kbd{M-x macrostep-expand} when point is
>> +over a macro.
>
> We say "when point is in a macro". "Over" is reserved for mouse
> pointer.
>
>> +@kbd{macrostep} is a minor mode for interactively stepping through the
> ^^^^^^^^^
> "macrostep-mode", I guess? And why @kbd? is that something the user
> is supposed to type?
>
>> +The standard keybindings in @code{macrostep-mode} are the following:
>> +@table @kbd
>> +@item e
>> +@itemx =
>> +@itemx RET
>> +@findex macrostep-expand
>
> Please move the index entries to _before_ the corresponding @item's,
> so that following the index entry lands you on the @item, not after
> it.
>
> Otherwise, this LGTM, thanks.
OK - Attached is a revised patch incorporating the ideas above (as well as a
refinement from Eshel on clarifying this is for Emacs Lisp).
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-Macrostep-section-in-manual.patch --]
[-- Type: text/x-diff, Size: 3743 bytes --]
From 4be7abaa0af33936b62119732609a1d4ff8ee1b4 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Tue, 23 Apr 2024 22:21:07 +0100
Subject: [PATCH] Add Macrostep section in manual
Macrostep is an Emacs Lisp macro-expander useful for exploring and
writing macros. This is based on Jonathan's Oddie's documentation
in the macrostep package.
* doc/emacs/programs.texi (Programs): Add Macrostep section.
* doc/emacs/emacs.texi (Top): Add detailed menu reference.
---
doc/emacs/emacs.texi | 3 ++
doc/emacs/programs.texi | 61 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 64 insertions(+)
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7d77f13ab21..2ce47dd6e5e 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -694,6 +694,9 @@ Top
@ifnottex
* Fortran:: Fortran mode and its special features.
@end ifnottex
+@ifnottex
+* Macrostep:: Interactive Emacs Lisp macro-expander.
+@end ifnottex
Top-Level Definitions, or Defuns
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index de28a9f1dd4..8c8542cc374 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -45,6 +45,10 @@ Programs
@ifnottex
* Fortran:: Fortran mode and its special features.
@end ifnottex
+@ifnottex
+* Macrostep:: Interactive Emacs Lisp macro-expander.
+@end ifnottex
+
@end menu
@node Program Modes
@@ -2235,3 +2239,60 @@ Asm Mode
@ifnottex
@include fortran-xtra.texi
@end ifnottex
+
+@ifnottex
+@node Macrostep
+@section Macrostep: interactive Emacs Lisp macro-expander
+
+You can use @code{macrostep-mode} to explore Lisp macro definitions, and
+help write new macros, using @kbd{M-x macrostep-expand} when point is
+in a macro.
+
+@code{macrostep-mode} is a minor mode for interactively stepping through the
+expansion of macros in Emacs Lisp source code. It lets you see exactly
+what happens at each step of the expansion process by pretty-printing
+the expanded forms inline in the source buffer, which is temporarily
+read-only while macro expansions are visible. You can expand and
+collapse macro forms one step at a time, and evaluate or instrument the
+expansions for debugging with Edebug as usual. Single-stepping through
+the expansion is particularly useful for debugging macros that expand
+into another macro form. These can be difficult to debug with
+@code{macroexpand}, which continues expansion until the top-level form
+is no longer a macro call.
+
+The standard keybindings in @code{macrostep-mode} are the following:
+@table @kbd
+@findex macrostep-expand
+@item e
+@itemx =
+@itemx RET
+Expand the macro form following point one step (@code{macrostep-expand}).
+@findex macrostep-collapse
+@item c
+@itemx u
+@itemx DEL
+Collapse the form following point (@code{macrostep-collapse}).
+@findex macrostep-next-macro
+@item n
+@itemx TAB
+Jump to the next macro form in the expansion (@code{macrostep-next-macro}).
+@findex macrostep-previous-macro
+@item p
+@itemx M-TAB
+Jump to the previous macro form in the expansion (@code{macrostep-previous-macro}).
+@findex macrostep-collapse-all
+@item q
+@itemx C-c C-c
+Collapse all expanded forms and exit macrostep-mode (@code{macrostep-collapse-all}).
+@end table
+
+It's not very useful to enable and disable macrostep-mode directly.
+Instead, bind @code{macrostep-expand} to a key in
+@code{emacs-lisp-mode-map}, for example @kbd{C-c e}.
+
+You can then enter @code{macrostep-mode} and expand a macro form
+completely by typing @kbd{C-c e e e@dots{}} as many times as necessary.
+
+Exit macrostep-mode by typing @kbd{q} or @kbd{C-c C-c}, or by
+successively typing @kbd{c} to collapse all surrounding expansions.
+@end ifnottex
--
2.42.0
^ permalink raw reply related [flat|nested] 86+ messages in thread
* bug#68929: [PATCH] Copy which-key from GNU ELPA into core
2024-04-29 21:00 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-05-01 7:31 ` Philip Kaludercic
0 siblings, 0 replies; 86+ messages in thread
From: Philip Kaludercic @ 2024-05-01 7:31 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: Eli Zaretskii, 68929, monnier, justin
Jeremy Bryant <jb@jeremybryant.net> writes:
> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Jeremy Bryant <jb@jeremybryant.net>
>>> Cc: philipk@posteo.net, 68929@debbugs.gnu.org, monnier@iro.umontreal.ca,
>>> justin@burkett.cc
>>> Date: Sun, 14 Apr 2024 22:52:08 +0100
>>>
>>> > Is line length the only issue you are looking at? What about other
>>> > requirements of our logs and ChangeLog files, including those imposed
>>> > by authors.el? The most problematic issue is when the file names
>>> > and/or its leading directories in the log message don't fit the actual
>>> > place and name of the file in the tree. Did you look at those issues?
>>> > They typically come up when preparing a release tarball, and are quite
>>> > annoying at that time, especially if there are a lot of them, because
>>> > they require manual fixes.
>>>
>>> Yes, sorry, I have only looked at the line length because it came up as
>>> a blocker.
>>>
>>> As far as the file names, this appears stable, but the place in the tree
>>> would move as part of this proposed integration, to be in
>>> lisp/which-key.el rather than at the root as is the case for the ELPA
>>> version. Is this a problem and how was it resolved with other moves
>>> from ELPA to core?
>>
>> Sorry, I don't remember the details. I probably fixed some issues by
>> hand, and for some others added/modified the relevant data structures
>> in admin/authors.el, which see.
>>
>>> Upon inspection, the earlier historical commits do not generally conform to the
>>> Changelog format.
>>> How to investigate any issues for authors.el? Is there a function try
>>> and run?
>>
>> The function is "M-x authors", defined in admin/authors.el. It first
>> updates ChangeLog.4, and then attempts the regenerate AUTHORS; you
>> will need to "git reset" to return to the current versions once you
>> are finished. The following extract from admin/make-tarball.txt gives
>> some guidance, and more information is available in comments to
>> authors.el:
>>
>> After "M-x authors" finishes, if there is an "*Authors Errors*"
>> buffer, address the issues. If there was a ChangeLog typo, fix
>> the relevant entry. If a file was deleted or renamed, consider
>> adding an appropriate entry to variables authors-ignored-files,
>> authors-valid-file-names, or authors-renamed-files-alist in
>> authors.el. If some authors are "ignored", consider adding
>> entries to the author-aliases variable.
>>
>> If necessary, repeat 'C-u M-x authors' after making those changes.
>>
>> If you see too many problems than you can handle, feel free to give up
>> on them and leave them until the first pretest.
>
> Eli, thanks for the patient explanations however I have not the time to
> work on this in detail due to the complexity.
>
>
> Philip, as you separately proposed to investigate. Here is a compact
> updated summary of Stefan's prior
> recommendations to merge the history to preserve the contributor
> history/assignments:
>
> "BTW, rather than adding a file, another way to add it to `emacs.git` is
> by `git merge --allow-unrelated-histories`.
> If you want to do that, you'll want to first create a new commit which
> moves the files to their "final" destination, like:
>
> git rm .gitignore .github Makefile LICENSE.md ...
> git mv which-key.el lisp/which-key.el
> git mv which-key-tests.el test/lisp/which-key-tests.el
> git commit -m 'Move files in preparation for merge into emacs.git'
>
> and then you can `git merge` that new commit into Emacs, preserving
> the history.
>
> The commands above should be done in a branch containing the which-key history.
> Then you go to a branch of Emacs [add a remote pointing to the which-key
> repo modified as above] and do
>
> git merge --no-verify --allow-unrelated-histories --no-edit which-key-integration/which-key-prepare-integration
> git push"
>
>
> Start with the upstream which includes all changes discussed
> https://github.com/justbur/emacs-which-key/
Are you proposing that I run this procedure? I assumed that the authors
issue was still blocking.
--
Philip Kaludercic on peregrine
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-04-29 21:38 ` Jeremy Bryant
@ 2024-05-02 9:32 ` Eli Zaretskii
2024-05-02 22:03 ` Jeremy Bryant
0 siblings, 1 reply; 86+ messages in thread
From: Eli Zaretskii @ 2024-05-02 9:32 UTC (permalink / raw)
To: Jeremy Bryant; +Cc: monnier, emacs-devel
> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Mon, 29 Apr 2024 22:38:27 +0100
>
> OK - Attached is a revised patch incorporating the ideas above (as well as a
> refinement from Eshel on clarifying this is for Emacs Lisp).
LGTM, but I believe we are waiting for when macrostep is actually
added to Emacs, is that right?
^ permalink raw reply [flat|nested] 86+ messages in thread
* Re: Incorporate package macrostep into Emacs core
2024-05-02 9:32 ` Eli Zaretskii
@ 2024-05-02 22:03 ` Jeremy Bryant
0 siblings, 0 replies; 86+ messages in thread
From: Jeremy Bryant @ 2024-05-02 22:03 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: monnier, emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> Date: Mon, 29 Apr 2024 22:38:27 +0100
>>
>> OK - Attached is a revised patch incorporating the ideas above (as well as a
>> refinement from Eshel on clarifying this is for Emacs Lisp).
>
> LGTM, but I believe we are waiting for when macrostep is actually
> added to Emacs, is that right?
Eli, thanks for reviewing, and good to know.
Indeed, this is pending inclusion of macrostep.
^ permalink raw reply [flat|nested] 86+ messages in thread
end of thread, other threads:[~2024-05-02 22:03 UTC | newest]
Thread overview: 86+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <RT-Ticket-2038816@rt.gnu.org>
[not found] ` <87zfvl8r4e.fsf@jeremybryant.net>
[not found] ` <874jdspsqb.fsf@bernoul.li>
2024-02-28 20:56 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Jeremy Bryant via Emacs development discussions.
2024-02-28 21:16 ` Stefan Monnier
2024-02-28 23:04 ` Jeremy Bryant
2024-02-29 20:44 ` Jeremy Bryant
2024-03-01 4:15 ` Adam Porter
2024-03-01 23:26 ` Stefan Monnier
2024-03-02 21:50 ` Jeremy Bryant
2024-03-02 22:51 ` Stefan Monnier
2024-03-03 7:26 ` Adam Porter
2024-03-03 7:51 ` Eli Zaretskii
2024-03-03 7:53 ` Adam Porter
2024-03-03 8:57 ` Eli Zaretskii
2024-03-03 14:28 ` Stefan Monnier
2024-03-04 11:25 ` Ihor Radchenko
2024-03-04 15:35 ` Stefan Monnier
2024-03-03 22:40 ` Jeremy Bryant
2024-03-04 12:00 ` Eli Zaretskii
2024-03-11 22:47 ` Jeremy Bryant
[not found] ` <jwvsf0wqrqg.fsf-monnier+emacs@gnu.org>
[not found] ` <87r0fugl5o.fsf@jeremybryant.net>
[not found] ` <jwvle613zk7.fsf-monnier+emacs@gnu.org>
[not found] ` <rt-4.2.16-14-g9a593ee-16065-1711725597-1342.2038816-6-0@rt.gnu.org>
[not found] ` <87h6g6jthh.fsf@jeremybryant.net>
[not found] ` <rt-4.2.16-14-g9a593ee-24903-1712948497-1603.2038816-5-0@rt.gnu.org>
[not found] ` <jwvjzl25qpv.fsf-monnier+emacs@gnu.org>
2024-02-04 22:02 ` bug#68929: [PATCH] Copy which-key from GNU ELPA into core Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 2:15 ` Justin Burkett
2024-02-05 3:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-05 12:32 ` Eli Zaretskii
2024-02-06 2:51 ` Justin Burkett
2024-02-07 21:53 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:09 ` Eli Zaretskii
2024-02-08 22:25 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-11 21:32 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-15 8:29 ` Eli Zaretskii
2024-02-17 13:10 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-17 16:58 ` Eli Zaretskii
2024-02-07 22:01 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:16 ` Eli Zaretskii
2024-02-08 15:42 ` Justin Burkett
2024-02-08 16:10 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 16:54 ` Eli Zaretskii
2024-02-08 22:27 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-09 6:51 ` Eli Zaretskii
2024-02-07 8:20 ` Philip Kaludercic
2024-02-07 21:48 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08 6:03 ` Eli Zaretskii
2024-03-01 23:08 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-03-02 9:33 ` Philip Kaludercic
[not found] ` <87r0faibbg.fsf@jeremybryant.net>
2024-04-12 20:40 ` bug#68929: which-key tests " Philip Kaludercic
[not found] ` <87wmp2ibjj.fsf@jeremybryant.net>
2024-04-14 9:21 ` bug#68929: [PATCH] Copy which-key " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 10:13 ` Eli Zaretskii
2024-04-14 21:52 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 11:13 ` Eli Zaretskii
2024-04-29 21:00 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-05-01 7:31 ` Philip Kaludercic
2024-02-23 23:07 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 21:56 ` bug#68929: Fwd: Re: bug#68929: which-key tests " Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-15 8:39 ` Mattias Engdegård
2024-03-02 6:51 ` Incorporate package macrostep into Emacs or NonGNU ELPA? Eli Zaretskii
2024-03-02 21:36 ` Jeremy Bryant
2024-03-17 21:48 ` Incorporate package macrostep into Emacs core Jeremy Bryant via Emacs development discussions.
2024-03-18 9:09 ` Philip Kaludercic
2024-03-18 23:03 ` Jeremy Bryant
2024-03-19 6:36 ` Philip Kaludercic
2024-03-19 7:11 ` Gerd Möllmann
2024-03-19 7:26 ` Philip Kaludercic
2024-03-19 7:30 ` Gerd Möllmann
2024-03-19 9:33 ` Philip Kaludercic
2024-03-19 9:48 ` Gerd Möllmann
2024-03-19 17:03 ` Jonathan Oddie
2024-03-19 21:57 ` Jeremy Bryant via Emacs development discussions.
2024-03-22 20:47 ` Jeremy Bryant
2024-03-22 20:50 ` Stefan Monnier
2024-03-18 12:48 ` Eli Zaretskii
2024-03-18 13:22 ` Stefan Monnier
2024-03-18 22:58 ` Jeremy Bryant
2024-03-19 12:26 ` Eli Zaretskii
2024-04-18 21:19 ` Jeremy Bryant
2024-04-19 6:38 ` Eli Zaretskii
2024-04-19 19:30 ` Jeremy Bryant
2024-04-19 22:26 ` Stefan Monnier
2024-04-20 6:07 ` Eli Zaretskii
2024-04-20 17:14 ` Adam Porter
2024-04-20 6:00 ` Eli Zaretskii
2024-04-23 21:37 ` Jeremy Bryant
2024-04-25 15:30 ` Eli Zaretskii
2024-04-25 21:27 ` Jeremy Bryant
2024-04-26 8:15 ` Eshel Yaron
2024-04-27 9:52 ` Eli Zaretskii
2024-04-29 21:38 ` Jeremy Bryant
2024-05-02 9:32 ` Eli Zaretskii
2024-05-02 22:03 ` Jeremy Bryant
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.