Function: helpful--definition

helpful--definition is a byte-compiled function defined in helpful.el.

Signature

(helpful--definition SYM CALLABLE-P)

Documentation

Return a list (BUF POS OPENED) where SYM is defined.

BUF is the buffer containing the definition. If the user wasn't already visiting this buffer, OPENED is t and callers should kill the buffer when done.

POS is the position of the start of the definition within the buffer.

This function has :around advice: helpful--definition@definition-fallback.

Source Code

;; Defined in ~/.emacs.d/elpa/helpful-20250408.334/helpful.el
(defun helpful--definition (sym callable-p)
  "Return a list (BUF POS OPENED) where SYM is defined.

BUF is the buffer containing the definition. If the user wasn't
already visiting this buffer, OPENED is t and callers should kill
the buffer when done.

POS is the position of the start of the definition within the
buffer."
  (let ((primitive-p (helpful--primitive-p sym callable-p))
        (library-name nil)
        (src-path nil)
        (buf nil)
        (pos nil)
        (opened nil))
    ;; We shouldn't be called on primitive functions if we don't have
    ;; a directory of Emacs C sourcecode.
    (cl-assert
     (or find-function-C-source-directory
         (not primitive-p)))

    (when (symbolp sym)
      (if callable-p
          (setq library-name (cdr (find-function-library sym)))
        ;; Based on `find-variable-noselect'.
        (setq library-name
              (or
               (symbol-file sym 'defvar)
               (help-C-file-name sym 'var)))))

    (when library-name
      (setq src-path (helpful--library-path library-name)))

    (cond
     ((and (not (symbolp sym)) (functionp sym))
      (list nil nil nil))
     ((and callable-p library-name)
      (when src-path
        (-let [(src-buf src-opened) (helpful--open-if-needed src-path)]
          (setq buf src-buf)
          (setq opened src-opened))

        ;; Based on `find-function-noselect'.
        (with-current-buffer buf
          ;; `find-function-search-for-symbol' moves point. Prevent
          ;; that.
          (save-excursion
            ;; Narrowing has been fixed upstream:
            ;; http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=abd18254aec76b26e86ae27e91d2c916ec20cc46
            (save-restriction
              (widen)
              (setq pos
                    (cdr (find-function-search-for-symbol sym nil library-name))))))
        ;; If we found the containing buffer, but not the symbol, attempt
        ;; to find it by macroexpanding interesting forms.
        (when (and buf (not pos))
          (setq pos (helpful--find-by-macroexpanding buf sym t)))))
     ;; A function, but no file found.
     (callable-p
      ;; Functions defined interactively may have an edebug property
      ;; that contains the location of the definition.
      (-when-let (edebug-info (get sym 'edebug))
        (-let [marker (if (consp edebug-info)
                          (car edebug-info)
                        edebug-info)]
          (setq buf (marker-buffer marker))
          (setq pos (marker-position marker)))))
     ((and (not callable-p) src-path)
      (-let [(src-buf src-opened) (helpful--open-if-needed src-path)]
        (setq buf src-buf)
        (setq opened src-opened)

        (with-current-buffer buf
          ;; `find-function-search-for-symbol' moves point. Prevent
          ;; that.
          (save-excursion
            (condition-case _err
                (setq pos (cdr (find-variable-noselect sym library-name)))
              (search-failed nil)
              ;; If your current Emacs instance doesn't match the source
              ;; code configured in find-function-C-source-directory, we can
              ;; get an error about not finding source. Try
              ;; `default-tab-width' against Emacs trunk.
              (error nil)))))))

    (list buf pos opened)))