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 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 \[^cgv\W]\\w+\\*?\\)\\|define-minor-mode\
  66 \\|easy-mmode-define-global-mode\\)" find-function-space-re
  67    "\\('\\|\(quote \\)?%s\\(\\s-\\|$\\|\(\\|\)\\)")
  68   "The regexp used by `find-function' to search for a function definition.
  69 Note it must contain a `%s' at the place where `format'
  70 should insert the function name.  The default value avoids `defconst',
  71 `defgroup', `defvar'.
  72
  73 Please send improvements and fixes to the maintainer."
  74   :type 'regexp
  75   :group 'find-function
  76   :version "21.1")
  77
  78 (defcustom find-variable-regexp
  79   (concat"^\\s-*(def[^umag]\\(\\w\\|\\s_\\)+\\*?" find-function-space-re "%s\\(\\s-\\|$\\)")
  80   "The regexp used by `find-variable' to search for a variable definition.
  81 It should match right up to the variable name.  The default value
  82 avoids `defun', `defmacro', `defalias', `defadvice', `defgroup'.
  83
  84 Please send improvements and fixes to the maintainer."
  85   :type 'regexp
  86   :group 'find-function
  87   :version "21.1")
  88
  89 (defcustom find-function-source-path nil
  90   "The default list of directories where `find-function' searches.
  91
  92 If this variable is nil then `find-function' searches `load-path' by
  93 default."
  94   :type '(repeat directory)
  95   :group 'find-function)
  96
  97 (defcustom find-function-recenter-line 1
  98   "The window line-number from which to start displaying a symbol definition.
  99 A value of nil implies center the beginning of the definition.
 100 See the function `center-to-window-line' for more information, and
 101 `find-function' and `find-variable'."
 102   :group 'find-function
 103   :version "20.3")
 104
 105 (defcustom find-function-after-hook nil
 106   "Hook run after finding symbol definition.
 107
 108 See the functions `find-function' and `find-variable'."
 109   :group 'find-function
 110   :version "20.3")
 111
 112 ;;; Functions:
 113
 114 ;;;###autoload
 115 (defun find-function-search-for-symbol (symbol variable-p library)
 116   "Search for SYMBOL.
 117 If VARIABLE-P is nil, `find-function-regexp' is used, otherwise
 118 `find-variable-regexp' is used.   The search is done in library LIBRARY."
 119   (if (null library)
 120       (error "Don't know where `%s' is defined" symbol))
 121   (save-match-data
 122     (if (string-match "\\.el\\(c\\)\\'" library)
 123         (setq library (substring library 0 (match-beginning 1))))
 124     (let* ((path find-function-source-path)
 125            (compression (or (rassq 'jka-compr-handler file-name-handler-alist)
 126                             (member 'crypt-find-file-hook find-file-hooks)))
 127            (filename (progn
 128                        ;; use `file-name-sans-extension' here? (if it gets fixed)
 129                        (if (string-match "\\(\\.el\\)\\'" library)
 130                            (setq library (substring library 0
 131                                                     (match-beginning 1))))
 132                        (or (locate-library (concat library ".el") t path)
 133                            (locate-library library t path)
 134                            (if compression
 135                                (or (locate-library (concat library ".el.gz")
 136                                                    t path)
 137                                    (locate-library (concat library ".gz")
 138                                                    t path)))))))
 139       (if (not filename)
 140           (error "The library `%s' is not in the path" library))
 141       (with-current-buffer (find-file-noselect filename)
 142         (let ((regexp (format (if variable-p
 143                                   find-variable-regexp
 144                                 find-function-regexp)
 145                               (regexp-quote (symbol-name symbol))))
 146               (case-fold-search))
 147           (with-syntax-table emacs-lisp-mode-syntax-table
 148             (goto-char (point-min))
 149             (if (or (re-search-forward regexp nil t)
 150                     (re-search-forward
 151                      (concat "^([^ ]+" find-function-space-re "['(]"
 152                              (regexp-quote (symbol-name symbol))
 153                              "\\>")
 154                      nil t))
 155                 (progn
 156                   (beginning-of-line)
 157                   (cons (current-buffer) (point)))
 158               (error "Cannot find definition of `%s' in library `%s'"
 159                      symbol library))))))))
 160
 161 ;;;###autoload
 162 (defun find-function-noselect (function)
 163   "Return a pair (BUFFER . POINT) pointing to the definition of FUNCTION.
 164
 165 Finds the Emacs Lisp library containing the definition of FUNCTION
 166 in a buffer and the point of the definition.  The buffer is
 167 not selected.
 168
 169 If the file where FUNCTION is defined is not known, then it is
 170 searched for in `find-function-source-path' if non nil, otherwise
 171 in `load-path'."
 172   (if (not function)
 173       (error "You didn't specify a function"))
 174   (and (subrp (symbol-function function))
 175        (error "%s is a primitive function" function))
 176   (let ((def (symbol-function function))
 177         aliases)
 178     (while (symbolp def)
 179       (or (eq def function)
 180           (if aliases
 181               (setq aliases (concat aliases
 182                                     (format ", which is an alias for `%s'"
 183                                             (symbol-name def))))
 184             (setq aliases (format "`%s' an alias for `%s'"
 185                                   function (symbol-name def)))))
 186       (setq function (symbol-function function)
 187             def (symbol-function function)))
 188     (if aliases
 189         (message aliases))
 190     (let ((library
 191            (cond ((eq (car-safe def) 'autoload)
 192                   (nth 1 def))
 193                  ((symbol-file function)))))
 194       (find-function-search-for-symbol function nil library))))
 195
 196 (defalias 'function-at-point 'function-called-at-point)
 197
 198 (defun find-function-read (&optional variable-p)
 199   "Read and return an interned symbol, defaulting to the one near point.
 200
 201 If the optional VARIABLE-P is nil, then a function is gotten
 202 defaulting to the value of the function `function-at-point', otherwise
 203 a variable is asked for, with the default coming from
 204 `variable-at-point'."
 205   (let ((symb (funcall (if variable-p
 206                            'variable-at-point
 207                          'function-at-point)))
 208         (enable-recursive-minibuffers t)
 209         val)
 210     (if (equal symb 0)
 211         (setq symb nil))
 212     (setq val (if variable-p
 213                   (completing-read
 214                    (concat "Find variable"
 215                            (if symb
 216                                (format " (default %s)" symb))
 217                            ": ")
 218                    obarray 'boundp t nil)
 219                 (completing-read
 220                  (concat "Find function"
 221                          (if symb
 222                              (format " (default %s)" symb))
 223                          ": ")
 224                  obarray 'fboundp t nil)))
 225     (list (if (equal val "")
 226               symb
 227             (intern val)))))
 228
 229 (defun find-function-do-it (symbol variable-p switch-fn)
 230   "Find Emacs Lisp SYMBOL in a buffer and display it.
 231 If VARIABLE-P is nil, a function definition is searched for, otherwise
 232 a variable definition is searched for.  The start of a definition is
 233 centered according to the variable `find-function-recenter-line'.
 234 See also `find-function-after-hook'  It is displayed with function SWITCH-FN.
 235
 236 Point is saved in the buffer if it is one of the current buffers."
 237   (let* ((orig-point (point))
 238         (orig-buf (window-buffer))
 239         (orig-buffers (buffer-list))
 240         (buffer-point (save-excursion
 241                         (funcall (if variable-p
 242                                       'find-variable-noselect
 243                                     'find-function-noselect)
 244                                   symbol)))
 245         (new-buf (car buffer-point))
 246         (new-point (cdr buffer-point)))
 247     (when buffer-point
 248       (when (memq new-buf orig-buffers)
 249         (push-mark orig-point))
 250       (funcall switch-fn new-buf)
 251       (goto-char new-point)
 252       (recenter find-function-recenter-line)
 253       (run-hooks 'find-function-after-hook))))
 254
 255 ;;;###autoload
 256 (defun find-function (function)
 257   "Find the definition of the FUNCTION near point.
 258
 259 Finds the Emacs Lisp library containing the definition of the function
 260 near point (selected by `function-at-point') in a buffer and
 261 places point before the definition.  Point is saved in the buffer if
 262 it is one of the current buffers.
 263
 264 The library where FUNCTION is defined is searched for in
 265 `find-function-source-path', if non nil, otherwise in `load-path'.
 266 See also `find-function-recenter-line' and `find-function-after-hook'."
 267   (interactive (find-function-read))
 268   (find-function-do-it function nil 'switch-to-buffer))
 269
 270 ;;;###autoload
 271 (defun find-function-other-window (function)
 272   "Find, in another window, the definition of FUNCTION near point.
 273
 274 See `find-function' for more details."
 275   (interactive (find-function-read))
 276   (find-function-do-it function nil 'switch-to-buffer-other-window))
 277
 278 ;;;###autoload
 279 (defun find-function-other-frame (function)
 280   "Find, in ananother frame, the definition of FUNCTION near point.
 281
 282 See `find-function' for more details."
 283   (interactive (find-function-read))
 284   (find-function-do-it function nil 'switch-to-buffer-other-frame))
 285
 286 ;;;###autoload
 287 (defun find-variable-noselect (variable &optional file)
 288   "Return a pair `(BUFFER . POINT)' pointing to the definition of SYMBOL.
 289
 290 Finds the Emacs Lisp library containing the definition of SYMBOL
 291 in a buffer and the point of the definition.  The buffer is
 292 not selected.
 293
 294 The library where VARIABLE is defined is searched for in FILE or
 295 `find-function-source-path', if non nil, otherwise in `load-path'."
 296   (if (not variable)
 297       (error "You didn't specify a variable"))
 298   (let ((library (or file (symbol-file variable))))
 299     (find-function-search-for-symbol variable 'variable library)))
 300
 301 ;;;###autoload
 302 (defun find-variable (variable)
 303   "Find the definition of the VARIABLE near point.
 304
 305 Finds the Emacs Lisp library containing the definition of the variable
 306 near point (selected by `variable-at-point') in a buffer and
 307 places point before the definition.  Point is saved in the buffer if
 308 it is one of the current buffers.
 309
 310 The library where VARIABLE is defined is searched for in
 311 `find-function-source-path', if non nil, otherwise in `load-path'.
 312 See also `find-function-recenter-line' and `find-function-after-hook'."
 313   (interactive (find-function-read 'variable))
 314   (find-function-do-it variable t 'switch-to-buffer))
 315
 316 ;;;###autoload
 317 (defun find-variable-other-window (variable)
 318   "Find, in another window, the definition of VARIABLE near point.
 319
 320 See `find-variable' for more details."
 321   (interactive (find-function-read 'variable))
 322   (find-function-do-it variable t 'switch-to-buffer-other-window))
 323
 324 ;;;###autoload
 325 (defun find-variable-other-frame (variable)
 326   "Find, in annother frame, the definition of VARIABLE near point.
 327
 328 See `find-variable' for more details."
 329   (interactive (find-function-read 'variable))
 330   (find-function-do-it variable t 'switch-to-buffer-other-frame))
 331
 332 ;;;###autoload
 333 (defun find-function-on-key (key)
 334   "Find the function that KEY invokes.  KEY is a string.
 335 Point is saved if FUNCTION is in the current buffer."
 336   (interactive "kFind function on key: ")
 337   (save-excursion
 338     (let* ((event (and (eventp key) (aref key 0))) ; Null event OK below.
 339            (start (event-start event))
 340            (modifiers (event-modifiers event))
 341            (window (and (or (memq 'click modifiers) (memq 'down modifiers)
 342                             (memq 'drag modifiers))
 343                         (posn-window start))))
 344       ;; For a mouse button event, go to the button it applies to
 345       ;; to get the right key bindings.  And go to the right place
 346       ;; in case the keymap depends on where you clicked.
 347       (when (windowp window)
 348         (set-buffer (window-buffer window))
 349         (goto-char (posn-point start)))
 350       (let ((defn (key-binding key))
 351             (key-desc (key-description key)))
 352         (if (or (null defn) (integerp defn))
 353             (message "%s is unbound" key-desc)
 354           (if (consp defn)
 355               (message "%s runs %s" key-desc (prin1-to-string defn))
 356             (find-function-other-window defn)))))))
 357
 358 ;;;###autoload
 359 (defun find-function-at-point ()
 360   "Find directly the function at point in the other window."
 361   (interactive)
 362   (let ((symb (function-at-point)))
 363     (when symb
 364       (find-function-other-window symb))))
 365
 366 ;;;###autoload
 367 (defun find-variable-at-point ()
 368   "Find directly the function at point in the other window."
 369   (interactive)
 370   (let ((symb (variable-at-point)))
 371     (when (and symb (not (equal symb 0)))
 372       (find-variable-other-window symb))))
 373
 374 ;;;###autoload
 375 (defun find-function-setup-keys ()
 376   "Define some key bindings for the find-function family of functions."
 377   (define-key ctl-x-map "F" 'find-function)
 378   (define-key ctl-x-4-map "F" 'find-function-other-window)
 379   (define-key ctl-x-5-map "F" 'find-function-other-frame)
 380   (define-key ctl-x-map "K" 'find-function-on-key)
 381   (define-key ctl-x-map "V" 'find-variable)
 382   (define-key ctl-x-4-map "V" 'find-variable-other-window)
 383   (define-key ctl-x-5-map "V" 'find-variable-other-frame))
 384
 385 (provide 'find-func)
 386
 387 ;;; find-func.el ends here