Function: helpful--format-command-keys

helpful--format-command-keys is a byte-compiled function defined in helpful.el.

Signature

(helpful--format-command-keys DOCSTRING)

Documentation

Convert command key references and keymap references in DOCSTRING to buttons.

Emacs uses to escape \[ references, so replace that
unescaping too.

This function has :around advice: helpful--format-command-keys@end-of-buffer-fallback.

Source Code

;; Defined in ~/.emacs.d/elpa/helpful-20250408.334/helpful.el
(defun helpful--format-command-keys (docstring)
  "Convert command key references and keymap references
in DOCSTRING to buttons.

Emacs uses \\= to escape \\[ references, so replace that
unescaping too."
  ;; Loosely based on `substitute-command-keys', but converts
  ;; references to buttons.
  (let ((keymap nil))
    (with-temp-buffer
      (insert docstring)
      (goto-char (point-min))
      (while (not (eobp))
        (cond
         ((looking-at
           ;; Text of the form "foo"
           (rx "\""))
          ;; For literal strings, escape backslashes so our output
          ;; shows copy-pasteable literals.
          (let* ((start-pos (point))
                 (end-pos (progn (forward-char) (search-forward "\"" nil t)))
                 contents)
            (if end-pos
                (progn
                  (setq contents (buffer-substring start-pos end-pos))
                  (delete-region start-pos end-pos)
                  (insert (s-replace "\\" "\\\\" contents)))
              (forward-char 1))))
         ((looking-at
           ;; Text of the form \=X
           (rx "\\="))
          ;; Remove the escaping, then step over the escaped char.
          ;; Step over the escaped character.
          (delete-region (point) (+ (point) 2))
          (forward-char 1))
         ((looking-at
           ;; Text of the form `foo'
           (rx "`"))
          (let* ((start-pos (point))
                 (end-pos (search-forward "'" nil t))
                 (contents
                  (when end-pos
                    (buffer-substring (1+ start-pos) (1- end-pos)))))
            (cond
             ((null contents)
              ;; If there's no closing ' to match the opening `, just
              ;; leave it.
              (goto-char (1+ start-pos)))
             ((s-contains-p "`" contents)
              ;; If we have repeated backticks `foo `bar', leave the
              ;; first one.
              (goto-char (1+ start-pos)))
             ((s-contains-p "\\[" contents)
              (delete-region start-pos end-pos)
              (insert (helpful--format-commands contents keymap)))
             ;; Highlight a normal `foo', extracting the surrounding
             ;; text so we can detect e.g. "function `foo'".
             (t
              (let ((before (helpful--chars-before start-pos 10))
                    (after (helpful--chars-after end-pos 10)))
                (delete-region start-pos end-pos)
                (insert (helpful--propertize-sym-ref contents before after)))))))
         ((looking-at
           ;; Text of the form \\<foo-keymap>
           (rx "\\<" (group (+ (not (in ">")))) ">"
               (? "\n")))
          (let* ((symbol-with-parens (match-string 0))
                 (symbol-name (match-string 1)))
            ;; Remove the original string.
            (delete-region (point)
                           (+ (point) (length symbol-with-parens)))
            ;; Set the new keymap.
            (setq keymap (symbol-value (intern symbol-name)))))
         ((looking-at
           ;; Text of the form \\{foo-mode-map}
           (rx "\\{" (group (+ (not (in "}")))) "}"))
          (let* ((symbol-with-parens (match-string 0))
                 (symbol-name (match-string 1))
                 (keymap
                  ;; Gracefully handle variables not being defined.
                  (ignore-errors
                    (symbol-value (intern symbol-name)))))
            ;; Remove the original string.
            (delete-region (point)
                           (+ (point) (length symbol-with-parens)))
            (if keymap
                (insert (helpful--format-keymap keymap))
              (insert (format "Keymap %s is not currently defined."
                              symbol-name)))))
         ((looking-at
           ;; Text of the form \\[foo-command]
           (rx "\\[" (group (+ (not (in "]")))) "]"))
          (let* ((symbol-with-parens (match-string 0)))
            ;; Remove the original string.
            (delete-region (point)
                           (+ (point) (length symbol-with-parens)))
            ;; Add a button.
            (insert (helpful--format-commands symbol-with-parens keymap))))
         ;; Don't modify other characters.
         (t
          (forward-char 1))))
      (buffer-string))))