lisp/emacs-lisp/find-func.el

   1 ;;; find-func.el --- find the definition of the Emacs Lisp function near point
   2
   3 ;; Copyright (C) 1997, 1999, 2001, 2004, 2005  Free Software Foundation, Inc.
   4
   5 ;; Author: Jens Petersen <petersen@kurims.kyoto-u.ac.jp>
   6 ;; Maintainer: petersen@kurims.kyoto-u.ac.jp
   7 ;; Keywords: emacs-lisp, functions, variables
   8 ;; Created: 97/07/25
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28 ;;
  29 ;; The funniest thing about this is that I can't imagine why a package
  30 ;; so obviously useful as this hasn't been written before!!
  31 ;; ;;; find-func
  32 ;; (find-function-setup-keys)
  33 ;;
  34 ;; or just:
  35 ;;
  36 ;; (load "find-func")
  37 ;;
  38 ;; if you don't like the given keybindings and away you go!  It does
  39 ;; pretty much what you would expect, putting the cursor at the
  40 ;; definition of the function or variable at point.
  41 ;;
  42 ;; The code started out from `describe-function', `describe-key'
  43 ;; ("help.el") and `fff-find-loaded-emacs-lisp-function' (Noah Friedman's
  44 ;; "fff.el").
  45
  46 ;;; Code:
  47
  48 (require 'loadhist)
  49
  50 ;;; User variables:
  51
  52 (defgroup find-function nil
  53   "Finds the definition of the Emacs Lisp symbol near point."
  54 ;;   :prefix "find-function"
  55   :group 'lisp)
  56
  57 (defconst find-function-space-re "\\(?:\\s-\\|\n\\|;.*\n\\)+")
  58
  59 (defcustom find-function-regexp
  60   ;; Match things like (defun foo ...), (defmacro foo ...),
  61   ;; (define-skeleton foo ...), (define-generic-mode 'foo ...),
  62   ;;  (define-derived-mode foo ...), (define-minor-mode foo)
  63   (concat
  64    "^\\s-*(\\(def\\(ine-skeleton\\|ine-generic-mode\\|ine-derived-mode\\|\
  65 ine-minor-mode\\|un-cvs-mode\\|foo\\|[^cfgv]\\w+\\*?\\)\
  66 \\|easy-mmode-define-global-mode\\|menu-bar-make-toggle\\)"
  67    find-function-space-re
  68    "\\('\\|\(quote \\)?%s\\(\\s-\\|$\\|\(\\|\)\\)")
  69   "The regexp used by `find-function' to search for a function definition.
  70 Note it must contain a `%s' at the place where `format'
  71 should insert the function name.  The default value avoids `defconst',
  72 `defgroup', `defvar', `defface'.
  73
  74 Please send improvements and fixes to the maintainer."
  75   :type 'regexp
  76   :group 'find-function
  77   :version "21.1")
  78
  79 (defcustom find-variable-regexp
  80   (concat"^\\s-*(def[^fumag]\\(\\w\\|\\s_\\)+\\*?" find-function-space-re "%s\\(\\s-\\|$\\)")
  81   "The regexp used by `find-variable' to search for a variable definition.
  82 Note it must contain a `%s' at the place where `format'
  83 should insert the variable name.  The default value
  84 avoids `defun', `defmacro', `defalias', `defadvice', `defgroup', `defface'.
  85
  86 Please send improvements and fixes to the maintainer."
  87   :type 'regexp
  88   :group 'find-function
  89   :version "21.1")
  90
  91 (defcustom find-face-regexp
  92   (concat"^\\s-*(defface" find-function-space-re "%s\\(\\s-\\|$\\)")
  93   "The regexp used by `find-face' to search for a face definition.
  94 Note it must contain a `%s' at the place where `format'
  95 should insert the face name.
  96
  97 Please send improvements and fixes to the maintainer."
  98   :type 'regexp
  99   :group 'find-function
 100   :version "22.1")
 101
 102 (defvar find-function-regexp-alist
 103   '((nil . find-function-regexp)
 104     (defvar . find-variable-regexp)
 105     (defface . find-face-regexp))
 106   "Alist mapping definition types into regexp variables.
 107 Each regexp variable's value should actually be a format string
 108 to be used to substitute the desired symbol name into the regexp.")
 109 (put 'find-function-regexp-alist 'risky-local-variable t)
 110
 111 (defcustom find-function-source-path nil
 112   "The default list of directories where `find-function' searches.
 113
 114 If this variable is nil then `find-function' searches `load-path' by
 115 default."
 116   :type '(repeat directory)
 117   :group 'find-function)
 118
 119 (defcustom find-function-recenter-line 1
 120   "The window line-number from which to start displaying a symbol definition.
 121 A value of nil implies center the beginning of the definition.
 122 See `find-function' and `find-variable'."
 123   :type '(choice (const :tag "Center" nil)
 124                  integer)
 125   :group 'find-function
 126   :version "20.3")
 127
 128 (defcustom find-function-after-hook nil
 129   "Hook run after finding symbol definition.
 130
 131 See the functions `find-function' and `find-variable'."
 132   :group 'find-function
 133   :version "20.3")
 134
 135 ;;; Functions:
 136
 137 (defun find-library-suffixes ()
 138   (let ((suffixes nil))
 139     (dolist (suffix load-suffixes (nreverse suffixes))
 140       (unless (string-match "elc" suffix) (push suffix suffixes)))))
 141
 142 (defun find-library-name (library)
 143   "Return the full name of the elisp source of LIBRARY."
 144   ;; If the library is byte-compiled, try to find a source library by
 145   ;; the same name.
 146   (if (string-match "\\.el\\(c\\(\\..*\\)?\\)\\'" library)
 147       (setq library (replace-match "" t t library)))
 148   (or (locate-file library
 149                    (or find-function-source-path load-path)
 150                    (append (find-library-suffixes) '("")))
 151       (error "Can't find library %s" library)))
 152
 153 (defvar find-function-C-source-directory
 154   (let ((dir (expand-file-name "src" source-directory)))
 155     (when (and (file-directory-p dir) (file-readable-p dir))
 156       dir))
 157   "Directory where the C source files of Emacs can be found.
 158 If nil, do not try to find the source code of functions and variables
 159 defined in C.")
 160
 161 (defun find-function-C-source (fun-or-var file type)
 162   "Find the source location where SUBR-OR-VAR is defined in FILE.
 163 TYPE should be nil to find a function, or `defvar' to find a variable."
 164   (unless find-function-C-source-directory
 165     (setq find-function-C-source-directory
 166           (read-directory-name "Emacs C source dir: " nil nil t)))
 167   (setq file (expand-file-name file find-function-C-source-directory))
 168   (unless (file-readable-p file)
 169     (error "The C source file %s is not available"
 170            (file-name-nondirectory file)))
 171   (unless type
 172     (setq fun-or-var (indirect-function fun-or-var)))
 173   (with-current-buffer (find-file-noselect file)
 174     (goto-char (point-min))
 175     (unless (re-search-forward
 176              (if type
 177                  (concat "DEFVAR[A-Z_]*[ \t\n]*([ \t\n]*\""
 178                          (regexp-quote (symbol-name fun-or-var))
 179                          "\"")
 180                (concat "DEFUN[ \t\n]*([ \t\n]*\""
 181                        (regexp-quote (subr-name fun-or-var))
 182                        "\""))
 183              nil t)
 184       (error "Can't find source for %s" fun-or-var))
 185     (cons (current-buffer) (match-beginning 0))))
 186
 187 ;;;###autoload
 188 (defun find-library (library)
 189   "Find the elisp source of LIBRARY."
 190   (interactive
 191    (list
 192     (completing-read "Library name: "
 193                      'locate-file-completion
 194                      (cons (or find-function-source-path load-path)
 195                            (find-library-suffixes)))))
 196   (let ((buf (find-file-noselect (find-library-name library))))
 197     (condition-case nil (switch-to-buffer buf) (error (pop-to-buffer buf)))))
 198
 199 ;;;###autoload
 200 (defun find-function-search-for-symbol (symbol type library)
 201   "Search for SYMBOL's definition of type TYPE in LIBRARY.
 202 If TYPE is nil, look for a function definition.
 203 Otherwise, TYPE specifies the kind of definition,
 204 and it is interpreted via `find-function-regexp-alist'.
 205 The search is done in the source for library LIBRARY."
 206   (if (null library)
 207       (error "Don't know where `%s' is defined" symbol))
 208   ;; Some functions are defined as part of the construct
 209   ;; that defines something else.
 210   (while (and (symbolp symbol) (get symbol 'definition-name))
 211     (setq symbol (get symbol 'definition-name)))
 212   (if (string-match "\\`src/\\(.*\\.c\\)\\'" library)
 213       (find-function-C-source symbol (match-string 1 library) type)
 214     (if (string-match "\\.el\\(c\\)\\'" library)
 215         (setq library (substring library 0 (match-beginning 1))))
 216     (let* ((filename (find-library-name library))
 217            (regexp-symbol (cdr (assq type find-function-regexp-alist))))
 218       (with-current-buffer (find-file-noselect filename)
 219         (let ((regexp (format (symbol-value regexp-symbol)
 220                               (regexp-quote (symbol-name symbol))))
 221               (case-fold-search))
 222           (with-syntax-table emacs-lisp-mode-syntax-table
 223             (goto-char (point-min))
 224             (if (or (re-search-forward regexp nil t)
 225                     (re-search-forward
 226                      (concat "^([^ ]+" find-function-space-re "['(]"
 227                              (regexp-quote (symbol-name symbol))
 228                              "\\_>")
 229                      nil t))
 230                 (progn
 231                   (beginning-of-line)
 232                   (cons (current-buffer) (point)))
 233               (error "Cannot find definition of `%s' in library `%s'"
 234                      symbol library))))))))
 235
 236 ;;;###autoload
 237 (defun find-function-noselect (function)
 238   "Return a pair (BUFFER . POINT) pointing to the definition of FUNCTION.
 239
 240 Finds the Emacs Lisp library containing the definition of FUNCTION
 241 in a buffer and the point of the definition.  The buffer is
 242 not selected.
 243
 244 If the file where FUNCTION is defined is not known, then it is
 245 searched for in `find-function-source-path' if non nil, otherwise
 246 in `load-path'."
 247   (if (not function)
 248       (error "You didn't specify a function"))
 249   (and (subrp (symbol-function function))
 250        (error "%s is a primitive function" function))
 251   (let ((def (symbol-function function))
 252         aliases)
 253     (while (symbolp def)
 254       (or (eq def function)
 255           (if aliases
 256               (setq aliases (concat aliases
 257                                     (format ", which is an alias for `%s'"
 258                                             (symbol-name def))))
 259             (setq aliases (format "`%s' an alias for `%s'"
 260                                   function (symbol-name def)))))
 261       (setq function (symbol-function function)
 262             def (symbol-function function)))
 263     (if aliases
 264         (message aliases))
 265     (let ((library
 266            (cond ((eq (car-safe def) 'autoload)
 267                   (nth 1 def))
 268                  ((symbol-file function 'defun)))))
 269       (find-function-search-for-symbol function nil library))))
 270
 271 (defun find-function-read (&optional type)
 272   "Read and return an interned symbol, defaulting to the one near point.
 273
 274 If TYPE is nil, insist on a symbol with a function definition.
 275 Otherwise TYPE should be `defvar' or `defface'.
 276 If TYPE is nil, defaults using `function-called-at-point',
 277 otherwise uses `variable-at-point'."
 278   (let ((symb (if (null type)
 279                   (function-called-at-point)
 280                 (if (eq type 'defvar)
 281                     (variable-at-point)
 282                   (variable-at-point t))))
 283         (predicate (cdr (assq type '((nil . fboundp) (defvar . boundp)
 284                                      (defface . facep)))))
 285         (prompt (cdr (assq type '((nil . "function") (defvar . "variable")
 286                                   (defface . "face")))))
 287         (enable-recursive-minibuffers t)
 288         val)
 289     (if (equal symb 0)
 290         (setq symb nil))
 291     (setq val (completing-read
 292                (concat "Find "
 293                        prompt
 294                        (if symb
 295                            (format " (default %s)" symb))
 296                        ": ")
 297                obarray predicate t nil))
 298     (list (if (equal val "")
 299               symb
 300             (intern val)))))
 301
 302 (defun find-function-do-it (symbol type switch-fn)
 303   "Find Emacs Lisp SYMBOL in a buffer and display it.
 304 TYPE is nil to search for a function definition,
 305 or else `defvar' or `defface'.
 306
 307 The variable `find-function-recenter-line' controls how
 308 to recenter the display.  SWITCH-FN is the function to call
 309 to display and select the buffer.
 310 See also `find-function-after-hook'.
 311
 312 Set mark before moving, if the buffer already existed."
 313   (let* ((orig-point (point))
 314         (orig-buf (window-buffer))
 315         (orig-buffers (buffer-list))
 316         (buffer-point (save-excursion
 317                         (find-definition-noselect symbol type)))
 318         (new-buf (car buffer-point))
 319         (new-point (cdr buffer-point)))
 320     (when buffer-point
 321       (when (memq new-buf orig-buffers)
 322         (push-mark orig-point))
 323       (funcall switch-fn new-buf)
 324       (goto-char new-point)
 325       (recenter find-function-recenter-line)
 326       (run-hooks 'find-function-after-hook))))
 327
 328 ;;;###autoload
 329 (defun find-function (function)
 330   "Find the definition of the FUNCTION near point.
 331
 332 Finds the Emacs Lisp library containing the definition of the function
 333 near point (selected by `function-called-at-point') in a buffer and
 334 places point before the definition.
 335 Set mark before moving, if the buffer already existed.
 336
 337 The library where FUNCTION is defined is searched for in
 338 `find-function-source-path', if non nil, otherwise in `load-path'.
 339 See also `find-function-recenter-line' and `find-function-after-hook'."
 340   (interactive (find-function-read))
 341   (find-function-do-it function nil 'switch-to-buffer))
 342
 343 ;;;###autoload
 344 (defun find-function-other-window (function)
 345   "Find, in another window, the definition of FUNCTION near point.
 346
 347 See `find-function' for more details."
 348   (interactive (find-function-read))
 349   (find-function-do-it function nil 'switch-to-buffer-other-window))
 350
 351 ;;;###autoload
 352 (defun find-function-other-frame (function)
 353   "Find, in ananother frame, the definition of FUNCTION near point.
 354
 355 See `find-function' for more details."
 356   (interactive (find-function-read))
 357   (find-function-do-it function nil 'switch-to-buffer-other-frame))
 358
 359 ;;;###autoload
 360 (defun find-variable-noselect (variable &optional file)
 361   "Return a pair `(BUFFER . POINT)' pointing to the definition of SYMBOL.
 362
 363 Finds the Emacs Lisp library containing the definition of SYMBOL
 364 in a buffer, and the point of the definition.  It does not switch
 365 to the buffer or display it.
 366
 367 The library where VARIABLE is defined is searched for in FILE or
 368 `find-function-source-path', if non nil, otherwise in `load-path'."
 369   (if (not variable)
 370       (error "You didn't specify a variable"))
 371   (let ((library (or file (symbol-file variable 'defvar))))
 372     (find-function-search-for-symbol variable 'defvar library)))
 373
 374 ;;;###autoload
 375 (defun find-variable (variable)
 376   "Find the definition of the VARIABLE near point.
 377
 378 Finds the Emacs Lisp library containing the definition of the variable
 379 near point (selected by `variable-at-point') in a buffer and
 380 places point before the definition.
 381
 382 Set mark before moving, if the buffer already existed.
 383
 384 The library where VARIABLE is defined is searched for in
 385 `find-function-source-path', if non nil, otherwise in `load-path'.
 386 See also `find-function-recenter-line' and `find-function-after-hook'."
 387   (interactive (find-function-read 'defvar))
 388   (find-function-do-it variable 'defvar 'switch-to-buffer))
 389
 390 ;;;###autoload
 391 (defun find-variable-other-window (variable)
 392   "Find, in another window, the definition of VARIABLE near point.
 393
 394 See `find-variable' for more details."
 395   (interactive (find-function-read 'defvar))
 396   (find-function-do-it variable 'defvar 'switch-to-buffer-other-window))
 397
 398 ;;;###autoload
 399 (defun find-variable-other-frame (variable)
 400   "Find, in annother frame, the definition of VARIABLE near point.
 401
 402 See `find-variable' for more details."
 403   (interactive (find-function-read 'defvar))
 404   (find-function-do-it variable 'defvar 'switch-to-buffer-other-frame))
 405
 406 ;;;###autoload
 407 (defun find-definition-noselect (symbol type &optional file)
 408   "Return a pair `(BUFFER . POINT)' pointing to the definition of SYMBOL.
 409 TYPE says what type of definition: nil for a function,
 410 `defvar' or `defface' for a variable or face.  This functoin
 411 does not switch to the buffer or display it.
 412
 413 The library where SYMBOL is defined is searched for in FILE or
 414 `find-function-source-path', if non nil, otherwise in `load-path'."
 415   (if (not symbol)
 416       (error "You didn't specify a symbol"))
 417   (if (null type)
 418       (find-function-noselect symbol)
 419     (let ((library (or file (symbol-file symbol type))))
 420       (find-function-search-for-symbol symbol type library))))
 421
 422 ;; For symmetry, this should be called find-face; but some programs
 423 ;; assume that, if that name is defined, it means something else.
 424 ;;;###autoload
 425 (defun find-face-definition (face)
 426   "Find the definition of FACE.  FACE defaults to the name near point.
 427
 428 Finds the Emacs Lisp library containing the definition of the face
 429 near point (selected by `variable-at-point') in a buffer and
 430 places point before the definition.
 431
 432 Set mark before moving, if the buffer already existed.
 433
 434 The library where FACE is defined is searched for in
 435 `find-function-source-path', if non nil, otherwise in `load-path'.
 436 See also `find-function-recenter-line' and `find-function-after-hook'."
 437   (interactive (find-function-read 'defface))
 438   (find-function-do-it face 'defface 'switch-to-buffer))
 439
 440 ;;;###autoload
 441 (defun find-function-on-key (key)
 442   "Find the function that KEY invokes.  KEY is a string.
 443 Set mark before moving, if the buffer already existed."
 444   (interactive "kFind function on key: ")
 445   (let (defn)
 446     (save-excursion
 447       (let* ((event (and (eventp key) (aref key 0))) ; Null event OK below.
 448              (start (event-start event))
 449              (modifiers (event-modifiers event))
 450              (window (and (or (memq 'click modifiers) (memq 'down modifiers)
 451                               (memq 'drag modifiers))
 452                           (posn-window start))))
 453         ;; For a mouse button event, go to the button it applies to
 454         ;; to get the right key bindings.  And go to the right place
 455         ;; in case the keymap depends on where you clicked.
 456         (when (windowp window)
 457           (set-buffer (window-buffer window))
 458           (goto-char (posn-point start)))
 459         (setq defn (key-binding key))))
 460     (let ((key-desc (key-description key)))
 461       (if (or (null defn) (integerp defn))
 462           (message "%s is unbound" key-desc)
 463         (if (consp defn)
 464             (message "%s runs %s" key-desc (prin1-to-string defn))
 465           (find-function-other-window defn))))))
 466
 467 ;;;###autoload
 468 (defun find-function-at-point ()
 469   "Find directly the function at point in the other window."
 470   (interactive)
 471   (let ((symb (function-called-at-point)))
 472     (when symb
 473       (find-function-other-window symb))))
 474
 475 ;;;###autoload
 476 (defun find-variable-at-point ()
 477   "Find directly the function at point in the other window."
 478   (interactive)
 479   (let ((symb (variable-at-point)))
 480     (when (and symb (not (equal symb 0)))
 481       (find-variable-other-window symb))))
 482
 483 ;;;###autoload
 484 (defun find-function-setup-keys ()
 485   "Define some key bindings for the find-function family of functions."
 486   (define-key ctl-x-map "F" 'find-function)
 487   (define-key ctl-x-4-map "F" 'find-function-other-window)
 488   (define-key ctl-x-5-map "F" 'find-function-other-frame)
 489   (define-key ctl-x-map "K" 'find-function-on-key)
 490   (define-key ctl-x-map "V" 'find-variable)
 491   (define-key ctl-x-4-map "V" 'find-variable-other-window)
 492   (define-key ctl-x-5-map "V" 'find-variable-other-frame))
 493
 494 (provide 'find-func)
 495
 496 ;; arch-tag: 43ecd81c-74dc-4d9a-8f63-a61e55670d64
 497 ;;; find-func.el ends here