Function: describe-map

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

Signature

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

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 are as in describe-map-tree.

Source Code

;; Defined in /usr/src/emacs/lisp/help.el.gz
(defun describe-map (map prefix transl partial shadow nomenu mention-shadow)
  "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 are as in
`describe-map-tree'."
  ;; Converted from describe_map in keymap.c.
  (let* ((suppress (and partial 'suppress-keymap))
         (map (keymap-canonicalize map))
         (tail map)
         (first t)
         (describer (if transl
                        #'help--describe-translation
                      #'help--describe-command))
         done vect)
    (while (and (consp tail) (not done))
      (cond ((or (vectorp (car tail)) (char-table-p (car tail)))
             (help--describe-vector (car tail) prefix describer partial
                                shadow map mention-shadow))
            ((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))
                        (null (get definition suppress)))
                    ;; 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 (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)))
      ;; Now output them in sorted order.
      (while vect
        (let* ((elem (car vect))
               (start (car elem))
               (definition (cadr elem))
               (shadowed (caddr elem))
               (end start))
          (when first
            (setq help--previous-description-column 0)
            (insert "\n")
            (setq first nil))
          ;; 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))))
          ;; Now START .. END is the range to describe next.
          ;; Insert the string to describe the event START.
          (insert (help--key-description-fontified (vector start) prefix))
          (when (not (eq start end))
            (insert " .. " (help--key-description-fontified (vector end) prefix)))
          ;; Print a description of the definition of this character.
          ;; Called function will take care of spacing out far enough
          ;; for alignment purposes.
          (if transl
              (help--describe-translation definition)
            (help--describe-command definition))
          ;; Print a description of the definition of this character.
          ;; elt_describer will take care of spacing out far enough for
          ;; alignment purposes.
          (when shadowed
            (goto-char (max (1- (point)) (point-min)))
            (insert "\n  (this binding is currently shadowed)")
            (goto-char (min (1+ (point)) (point-max)))))
        ;; Next item in list.
        (setq vect (cdr vect))))))