Function: describe-map

describe-map is a byte-compiled function defined in help.el.gz.

Signature

(describe-map MAP &optional PREFIX TRANSL PARTIAL SHADOW NOMENU MENTION-SHADOW BUFFER)

Documentation

Describe the contents of keymap MAP.

Assume that this keymap itself is reached by the sequence of prefix keys PREFIX (a string or vector).

TRANSL, PARTIAL, SHADOW, NOMENU, MENTION-SHADOW and BUFFER are as in describe-map-tree.

Source Code

;; Defined in /usr/src/emacs/lisp/help.el.gz
(defun describe-map (map &optional prefix transl partial shadow
                         nomenu mention-shadow buffer)
  "Describe the contents of keymap MAP.
Assume that this keymap itself is reached by the sequence of
prefix keys PREFIX (a string or vector).

TRANSL, PARTIAL, SHADOW, NOMENU, MENTION-SHADOW and BUFFER are as
in `describe-map-tree'."
  ;; Converted from describe_map in keymap.c.
  (let* ((map (keymap-canonicalize map))
         (tail map)
         (first t)
         done vect)
    (while (and (consp tail) (not done))
      (cond ((or (vectorp (car tail)) (char-table-p (car tail)))
             (let ((columns ()))
               (help--describe-vector
                (car tail) prefix
                (lambda (def)
                  (let ((start-line (line-beginning-position))
                        (end-key (point))
                        (column (current-column)))
                    (help--describe-command def transl)
                    (push (list column start-line end-key (1- (point)))
                          columns)))
                partial shadow map mention-shadow)
               (when columns
                 (describe-map--align-section columns))))
            ((consp (car tail))
             (let ((event (caar tail))
                   definition this-shadowed)
               ;; Ignore bindings whose "prefix" are not really
               ;; valid events. (We get these in the frames and
               ;; buffers menu.)
               (and (or (symbolp event) (fixnump event))
                    (not (and nomenu (eq event 'menu-bar)))
                    ;; Don't show undefined commands or suppressed
                    ;; commands.
                    (setq definition (keymap--get-keyelt (cdr (car tail)) nil))
                    (or (not (symbolp definition))
                        (not (get definition (when partial 'suppress-keymap))))
                    ;; Don't show a command that isn't really
                    ;; visible because a local definition of the
                    ;; same key shadows it.
                    (or (not shadow)
                        (let ((tem (help--shadow-lookup shadow (vector event) t nil)))
                          (cond ((null tem) t)
                                ;; If both bindings are keymaps,
                                ;; this key is a prefix key, so
                                ;; don't say it is shadowed.
                                ((and (keymapp definition) (keymapp tem)) t)
                                ;; Avoid generating duplicate
                                ;; entries if the shadowed binding
                                ;; has the same definition.
                                ((and mention-shadow (not (eq tem definition)))
                                 (setq this-shadowed t))
                                (t nil))))
                    (eq definition (if buffer
                                       (with-current-buffer buffer
                                         (lookup-key tail (vector event) t))
                                     (lookup-key tail (vector event) t)))
                    (push (list event definition this-shadowed) vect))))
            ((eq (car tail) 'keymap)
             ;; The same keymap might be in the structure twice, if
             ;; we're using an inherited keymap.  So skip anything
             ;; we've already encountered.
             (let ((tem (assq tail help--keymaps-seen)))
               (if (and (consp tem)
                        (equal (car tem) prefix))
                   (setq done t)
                 (push (cons tail prefix) help--keymaps-seen)))))
      (setq tail (cdr tail)))
    ;; If we found some sparse map events, sort them.
    (let ((vect (sort vect #'help--describe-map-compare))
          (columns ())
          line-start key-end column)
      ;; Now output them in sorted order.
      (while vect
        (let* ((elem (car vect))
               (start (nth 0 elem))
               (definition (nth 1 elem))
               (shadowed (nth 2 elem))
               (end start)
               remapped)
          ;; Find consecutive chars that are identically defined.
          (when (fixnump start)
            (while (and (cdr vect)
                        (let ((this-event (caar vect))
                              (this-definition (cadar vect))
                              (this-shadowed (caddar vect))
                              (next-event (caar (cdr vect)))
                              (next-definition (cadar (cdr vect)))
                              (next-shadowed (caddar (cdr vect))))
                          (and (eq next-event (1+ this-event))
                               (equal next-definition this-definition)
                               (eq this-shadowed next-shadowed))))
              (setq vect (cdr vect))
              (setq end (caar vect))))
          (when (or (not (eq start end))
                    describe-bindings-show-prefix-commands
                    ;; Don't output keymap prefixes.
                    (not (keymapp definition)))
            (when first
              (insert "\n")
              (setq first nil))
            ;; Now START .. END is the range to describe next.
            ;; Insert the string to describe the event START.
            (setq line-start (point))
            ;; If we're in a <remap> section of the output, then also
            ;; display the bindings of the keys that we've remapped from.
            ;; This enables the user to actually see what keys to tap to
            ;; execute the remapped commands.
            (if (setq remapped
                      (and (equal prefix [remap])
                           (not (eq definition 'self-insert-command))
                           (car (where-is-internal definition))))
                (insert (help--key-description-fontified
                         (vector (elt remapped (1- (length remapped))))
                         (seq-into (butlast (seq-into remapped 'list))
                                   'vector)))
              (insert (help--key-description-fontified (vector start) prefix)))
            (when (not (eq start end))
              (insert " .. " (help--key-description-fontified (vector end)
                                                              prefix)))
            (setq key-end (point)
                  column (current-column))
            ;; Print a description of the definition of this character.
            ;; Called function will take care of spacing out far enough
            ;; for alignment purposes.
            (help--describe-command definition transl)
            (push (list column line-start key-end (1- (point))) columns)
            ;; Print a description of the definition of this character.
            ;; elt_describer will take care of spacing out far enough for
            ;; alignment purposes.
            (when (or shadowed remapped)
              (goto-char (max (1- (point)) (point-min)))
              (when shadowed
                (insert "\n  (this binding is currently shadowed)"))
              (when remapped
                (insert (format
                         "\n  (Remapped via %s)"
                         (help--key-description-fontified
                          (vector start) prefix))))
              (goto-char (min (1+ (point)) (point-max))))))
        ;; Next item in list.
        (setq vect (cdr vect)))
      (when columns
        (describe-map--align-section columns)))))