apropos.el 30.8 KB
Newer Older
1
;;; apropos.el --- apropos commands for users and programmers
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3
;; Copyright (C) 1989, 1994, 1995, 2001, 2002 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
4

Eric S. Raymond's avatar
Eric S. Raymond committed
5
;; Author: Joe Wells <jbw@bigbird.bu.edu>
Karl Heuer's avatar
Karl Heuer committed
6
;; Rewritten: Daniel Pfeiffer <occitan@esperanto.org>
Eric S. Raymond's avatar
Eric S. Raymond committed
7
;; Keywords: help
Eric S. Raymond's avatar
Eric S. Raymond committed
8

Richard M. Stallman's avatar
Richard M. Stallman committed
9 10 11 12
;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
Eric S. Raymond's avatar
Eric S. Raymond committed
13
;; the Free Software Foundation; either version 2, or (at your option)
Richard M. Stallman's avatar
Richard M. Stallman committed
14 15 16 17 18 19 20 21
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
Erik Naggum's avatar
Erik Naggum committed
22 23 24
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
Richard M. Stallman's avatar
Richard M. Stallman committed
25

Eric S. Raymond's avatar
Eric S. Raymond committed
26
;;; Commentary:
Richard M. Stallman's avatar
Richard M. Stallman committed
27 28 29 30 31 32 33 34 35 36 37 38 39

;; The ideas for this package were derived from the C code in
;; src/keymap.c and elsewhere.  The functions in this file should
;; always be byte-compiled for speed.  Someone should rewrite this in
;; C (as part of src/keymap.c) for speed.

;; The idea for super-apropos is based on the original implementation
;; by Lynn Slater <lrs@esl.com>.

;; History:
;; Fixed bug, current-local-map can return nil.
;; Change, doesn't calculate key-bindings unless needed.
;; Added super-apropos capability, changed print functions.
40 41
;;; Made fast-apropos and super-apropos share code.
;;; Sped up fast-apropos again.
Richard M. Stallman's avatar
Richard M. Stallman committed
42
;; Added apropos-do-all option.
43
;;; Added fast-command-apropos.
Richard M. Stallman's avatar
Richard M. Stallman committed
44
;; Changed doc strings to comments for helping functions.
45
;;; Made doc file buffer read-only, buried it.
Richard M. Stallman's avatar
Richard M. Stallman committed
46 47
;; Only call substitute-command-keys if do-all set.

48 49
;; Optionally use configurable faces to make the output more legible.
;; Differentiate between command, function and macro.
50 51 52 53 54 55 56 57
;; Apropos-command (ex command-apropos) does cmd and optionally user var.
;; Apropos shows all 3 aspects of symbols (fn, var and plist)
;; Apropos-documentation (ex super-apropos) now finds all it should.
;; New apropos-value snoops through all values and optionally plists.
;; Reading DOC file doesn't load nroff.
;; Added hypertext following of documentation, mouse-2 on variable gives value
;;   from buffer in active window.

Eric S. Raymond's avatar
Eric S. Raymond committed
58 59
;;; Code:

Miles Bader's avatar
Miles Bader committed
60 61
(require 'button)

Richard M. Stallman's avatar
Richard M. Stallman committed
62 63
(defgroup apropos nil
  "Apropos commands for users and programmers"
64
  :group 'help
Richard M. Stallman's avatar
Richard M. Stallman committed
65 66
  :prefix "apropos")

67
;; I see a degradation of maybe 10-20% only.
Richard M. Stallman's avatar
Richard M. Stallman committed
68
(defcustom apropos-do-all nil
69
  "*Whether the apropos commands should do more.
Richard M. Stallman's avatar
Richard M. Stallman committed
70 71 72 73

Slows them down more or less.  Set this non-nil if you have a fast machine."
  :group 'apropos
  :type 'boolean)
74 75


76 77
(defcustom apropos-symbol-face 'bold
  "*Face for symbol name in Apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
78 79
  :group 'apropos
  :type 'face)
80

81 82
(defcustom apropos-keybinding-face 'underline
  "*Face for lists of keybinding in Apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
83 84
  :group 'apropos
  :type 'face)
85

86 87 88 89
(defcustom apropos-label-face 'italic
  "*Face for label (`Command', `Variable' ...) in Apropos output.
A value of nil means don't use any special font for them, and also
turns off mouse highlighting."
Richard M. Stallman's avatar
Richard M. Stallman committed
90 91
  :group 'apropos
  :type 'face)
92

93 94
(defcustom apropos-property-face 'bold-italic
  "*Face for property name in apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
95 96
  :group 'apropos
  :type 'face)
97

98 99 100 101
(defcustom apropos-match-face 'secondary-selection
  "*Face for matching text in Apropos documentation/value, or nil for none.
This applies when you look for matches in the documentation or variable value
for the regexp; the part that matches gets displayed in this font."
Richard M. Stallman's avatar
Richard M. Stallman committed
102 103
  :group 'apropos
  :type 'face)
104

105 106 107
(defcustom apropos-sort-by-scores nil
  "*Non-nil means sort matches by scores; best match is shown first.
The computed score is shown for each match."
108 109
  :group 'apropos
  :type 'boolean)
Richard M. Stallman's avatar
Richard M. Stallman committed
110

111
(defvar apropos-mode-map
112
  (let ((map (make-sparse-keymap)))
113 114 115 116
    (set-keymap-parent map button-buffer-map)
    ;; Use `apropos-follow' instead of just using the button
    ;; definition of RET, so that users can use it anywhere in an
    ;; apropos item, not just on top of a button.
117
    (define-key map "\C-m" 'apropos-follow)
118 119 120
    (define-key map " "    'scroll-up)
    (define-key map "\177" 'scroll-down)
    (define-key map "q"    'quit-window)
121
    map)
122
  "Keymap used in Apropos mode.")
123

Gerd Moellmann's avatar
Gerd Moellmann committed
124 125
(defvar apropos-mode-hook nil
  "*Hook run when mode is turned on.")
126

127 128 129
(defvar apropos-regexp nil
  "Regexp used in current apropos run.")

130 131 132 133 134 135
(defvar apropos-orig-regexp nil
  "Regexp as entered by user.")

(defvar apropos-all-regexp nil
  "Regexp matching apropos-all-words.")

136
(defvar apropos-files-scanned ()
Karl Heuer's avatar
Karl Heuer committed
137
  "List of elc files already scanned in current run of `apropos-documentation'.")
138 139 140

(defvar apropos-accumulator ()
  "Alist of symbols already found in current apropos run.")
141

142
(defvar apropos-item ()
Dave Love's avatar
Dave Love committed
143
  "Current item in or for `apropos-accumulator'.")
144

145 146 147 148 149 150 151 152 153 154 155 156 157 158
(defvar apropos-synonyms '(
  ("find" "open" "edit")
  ("kill" "cut")
  ("yank" "paste"))
  "List of synonyms known by apropos.
Each element is a list of words where the first word is the standard emacs
term, and the rest of the words are alternative terms.")

(defvar apropos-words ()
  "Current list of words.")

(defvar apropos-all-words ()
  "Current list of words and synonyms.")

159 160 161 162 163

;;; Button types used by apropos

(define-button-type 'apropos-symbol
  'face apropos-symbol-face
164 165 166
  'help-echo "mouse-2, RET: Display more help on this symbol"
  'action #'apropos-symbol-button-display-help
  'skip t)
167 168 169 170 171 172 173

(defun apropos-symbol-button-display-help (button)
  "Display further help for the `apropos-symbol' button BUTTON."
  (button-activate
   (or (apropos-next-label-button (button-start button))
       (error "There is nothing to follow for `%s'" (button-label button)))))

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
(define-button-type 'apropos-function
  'apropos-label "Function"
  'action (lambda (button)
	    (describe-function (button-get button 'apropos-symbol)))
  'help-echo "mouse-2, RET: Display more help on this function")
(define-button-type 'apropos-macro
  'apropos-label "Macro"
  'action (lambda (button)
	    (describe-function (button-get button 'apropos-symbol)))
  'help-echo "mouse-2, RET: Display more help on this macro")
(define-button-type 'apropos-command
  'apropos-label "Command"
  'action (lambda (button)
	    (describe-function (button-get button 'apropos-symbol)))
  'help-echo "mouse-2, RET: Display more help on this command")
Pavel Janík's avatar
Pavel Janík committed
189

190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
;; We used to use `customize-variable-other-window' instead for a
;; customizable variable, but that is slow.  It is better to show an
;; ordinary help buffer and let the user click on the customization
;; button in that buffer, if he wants to.
;; Likewise for `customize-face-other-window'.
(define-button-type 'apropos-variable
  'apropos-label "Variable"
  'help-echo "mouse-2, RET: Display more help on this variable"
  'action (lambda (button)
	    (describe-variable (button-get button 'apropos-symbol))))

(define-button-type 'apropos-face
  'apropos-label "Face"
  'help-echo "mouse-2, RET: Display more help on this face"
  'action (lambda (button)
	    (describe-face (button-get button 'apropos-symbol))))

(define-button-type 'apropos-group
  'apropos-label "Group"
  'help-echo "mouse-2, RET: Display more help on this group"
  'action (lambda (button)
211
	    (customize-group-other-window
212 213 214 215 216 217 218 219 220 221 222 223 224
	     (button-get button 'apropos-symbol))))

(define-button-type 'apropos-widget
  'apropos-label "Widget"
  'help-echo "mouse-2, RET: Display more help on this widget"
  'action (lambda (button)
	    (widget-browse-other-window (button-get button 'apropos-symbol))))

(define-button-type 'apropos-plist
  'apropos-label "Plist"
  'help-echo "mouse-2, RET: Display more help on this plist"
  'action (lambda (button)
	    (apropos-describe-plist (button-get button 'apropos-symbol))))
225 226

(defun apropos-next-label-button (pos)
227
  "Return the next apropos label button after POS, or nil if there's none.
228 229
Will also return nil if more than one `apropos-symbol' button is encountered
before finding a label."
230
  (let* ((button (next-button pos t))
231
	 (already-hit-symbol nil)
232 233
	 (label (and button (button-get button 'apropos-label)))
	 (type (and button (button-get button 'type))))
234
    (while (and button
235 236
		(not label)
		(or (not (eq type 'apropos-symbol))
237
		    (not already-hit-symbol)))
238
      (when (eq type 'apropos-symbol)
239 240 241
	(setq already-hit-symbol t))
      (setq button (next-button (button-start button)))
      (when button
242 243 244
	(setq label (button-get button 'apropos-label))
	(setq type (button-get button 'type))))
    (and label button)))
245

246

247 248 249 250 251
(defun apropos-words-to-regexp (words wild)
  "Make regexp matching any two of the words in WORDS."
  (concat "\\("
	  (mapconcat 'identity words "\\|")
	  "\\)" wild
252
	  (if (cdr words)
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
	      (concat "\\("
		      (mapconcat 'identity words "\\|")
		      "\\)")
	    "")))

(defun apropos-rewrite-regexp (regexp)
  "Rewrite a list of words to a regexp matching all permutations.
If REGEXP is already a regexp, don't modify it."
  (setq apropos-orig-regexp regexp)
  (setq apropos-words () apropos-all-words ())
  (if (string-equal (regexp-quote regexp) regexp)
      ;; We don't actually make a regexp matching all permutations.
      ;; Instead, for e.g. "a b c", we make a regexp matching
      ;; any combination of two or more words like this:
      ;; (a|b|c).*(a|b|c) which may give some false matches,
      ;; but as long as it also gives the right ones, that's ok.
      (let ((words (split-string regexp "[ \t]+")))
	(dolist (word words)
	  (let ((syn apropos-synonyms) (s word) (a word))
	    (while syn
	      (if (member word (car syn))
		  (progn
		    (setq a (mapconcat 'identity (car syn) "\\|"))
		    (if (member word (cdr (car syn)))
			(setq s a))
		    (setq syn nil))
		(setq syn (cdr syn))))
	    (setq apropos-words (cons s apropos-words)
		  apropos-all-words (cons a apropos-all-words))))
	(setq apropos-all-regexp (apropos-words-to-regexp apropos-all-words ".+"))
	(apropos-words-to-regexp apropos-words ".*?"))
    (setq apropos-all-regexp regexp)))

(defun apropos-calc-scores (str words)
  "Return apropos scores for string STR matching WORDS.
Value is a list of offsets of the words into the string."
  (let ((scores ())
	i)
    (if words
	(dolist (word words scores)
	  (if (setq i (string-match word str))
	      (setq scores (cons i scores))))
      ;; Return list of start and end position of regexp
      (string-match apropos-regexp str)
      (list (match-beginning 0) (match-end 0)))))

(defun apropos-score-str (str)
  "Return apropos score for string STR."
  (if str
302 303 304
      (let* (
	     (l (length str))
	     (score (- (/ l 10)))
305 306
	    i)
	(dolist (s (apropos-calc-scores str apropos-all-words) score)
307
	  (setq score (+ score 1000 (/ (* (- l s) 1000) l)))))
308 309 310 311 312 313 314 315 316 317 318
      0))

(defun apropos-score-doc (doc)
  "Return apropos score for documentation string DOC."
  (if doc
      (let ((score 0)
	    (l (length doc))
	    i)
	(dolist (s (apropos-calc-scores doc apropos-all-words) score)
	  (setq score (+ score 50 (/ (* (- l s) 50) l)))))
      0))
319

320 321 322 323 324 325 326 327 328
(defun apropos-score-symbol (symbol &optional weight)
  "Return apropos score for SYMBOL."
  (setq symbol (symbol-name symbol))
  (let ((score 0)
	(l (length symbol))
	i)
    (dolist (s (apropos-calc-scores symbol apropos-words) (* score (or weight 3)))
      (setq score (+ score (- 60 l) (/ (* (- l s) 60) l))))))

329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
(defun apropos-true-hit (str words)
  "Return t if STR is a genuine hit.
This may fail if only one of the keywords is matched more than once.
This requires that at least 2 keywords (unless only one was given)."
  (or (not str)
      (not words)
      (not (cdr words))
      (> (length (apropos-calc-scores str words)) 1)))

(defun apropos-false-hit-symbol (symbol)
  "Return t if SYMBOL is not really matched by the current keywords."
  (not (apropos-true-hit (symbol-name symbol) apropos-words)))

(defun apropos-false-hit-str (str)
  "Return t if STR is not really matched by the current keywords."
  (not (apropos-true-hit str apropos-words)))

(defun apropos-true-hit-doc (doc)
  "Return t if DOC is really matched by the current keywords."
  (apropos-true-hit doc apropos-all-words))

350
;;;###autoload
351
(define-derived-mode apropos-mode fundamental-mode "Apropos"
352 353
  "Major mode for following hyperlinks in output of apropos commands.

354
\\{apropos-mode-map}")
355

356
;;;###autoload
357 358
(defun apropos-variable (regexp &optional do-all)
  "Show user variables that match REGEXP.
Dave Love's avatar
Dave Love committed
359
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also show
360 361 362 363 364 365
normal variables."
  (interactive (list (read-string
                      (concat "Apropos "
                              (if (or current-prefix-arg apropos-do-all)
				  "variable"
				"user option")
366
                              " (regexp or words): "))
367 368
                     current-prefix-arg))
  (apropos-command regexp nil
369
		   (if (or do-all apropos-do-all)
370 371 372 373
		       #'(lambda (symbol)
			   (and (boundp symbol)
				(get symbol 'variable-documentation)))
		     'user-variable-p)))
374

375 376
;; For auld lang syne:
;;;###autoload
377
(defalias 'command-apropos 'apropos-command)
Richard M. Stallman's avatar
Richard M. Stallman committed
378
;;;###autoload
379
(defun apropos-command (apropos-regexp &optional do-all var-predicate)
Dave Love's avatar
Dave Love committed
380 381
  "Show commands (interactively callable functions) that match APROPOS-REGEXP.
With optional prefix DO-ALL, or if `apropos-do-all' is non-nil, also show
382
noninteractive functions.
383

384
If VAR-PREDICATE is non-nil, show only variables, and only those that
385
satisfy the predicate VAR-PREDICATE."
386 387 388 389
  (interactive (list (read-string (concat
				   "Apropos command "
				   (if (or current-prefix-arg
					   apropos-do-all)
390
				       "or function ")
391
				   "(regexp or words): "))
392
		     current-prefix-arg))
393
  (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
394
  (let ((message
395
	 (let ((standard-output (get-buffer-create "*Apropos*")))
396
	   (print-help-return-message 'identity))))
397 398 399
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator
	  (apropos-internal apropos-regexp
400 401
			    (or var-predicate
				(if do-all 'functionp 'commandp))))
402 403
    (let ((tem apropos-accumulator))
      (while tem
404 405
	(if (or (get (car tem) 'apropos-inhibit)
		(apropos-false-hit-symbol (car tem)))
406 407
	    (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
	(setq tem (cdr tem))))
408
    (let ((p apropos-accumulator)
409
	  doc symbol score)
410 411 412
      (while p
	(setcar p (list
		   (setq symbol (car p))
413
		   (setq score (apropos-score-symbol symbol))
414 415 416
		   (unless var-predicate
		     (if (functionp symbol)
			 (if (setq doc (documentation symbol t))
417
			     (progn
418
			       (setq score (+ score (apropos-score-doc doc)))
419
			       (substring doc 0 (string-match "\n" doc)))
420 421 422 423 424
			   "(not documented)")))
		   (and var-predicate
			(funcall var-predicate symbol)
			(if (setq doc (documentation-property
				       symbol 'variable-documentation t))
425 426 427 428 429
			     (progn
			       (setq score (+ score (apropos-score-doc doc)))
			       (substring doc 0
					  (string-match "\n" doc)))))))
	(setcar (cdr (car p)) score)
430 431 432 433
	(setq p (cdr p))))
    (and (apropos-print t nil)
	 message
	 (message message))))
434 435 436


;;;###autoload
437 438 439 440 441 442 443 444
(defun apropos-documentation-property (symbol property raw)
  "Like (documentation-property SYMBOL PROPERTY RAW) but handle errors."
  (condition-case ()
      (let ((doc (documentation-property symbol property raw)))
	(if doc (substring doc 0 (string-match "\n" doc))
	  "(not documented)"))
    (error "(error retrieving documentation)")))

445 446

;;;###autoload
447
(defun apropos (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
448 449 450 451
  "Show all bound symbols whose names match APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also
show unbound symbols and key bindings, which is a little more
time-consuming.  Returns list of symbols and documentation found."
452 453
  (interactive "sApropos symbol (regexp or words): \nP")
  (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
454 455 456 457 458 459 460
  (setq apropos-accumulator
	(apropos-internal apropos-regexp
			  (and (not do-all)
			       (not apropos-do-all)
			       (lambda (symbol)
				 (or (fboundp symbol)
				     (boundp symbol)
461
				     (facep symbol)
462
				     (symbol-plist symbol))))))
463 464 465 466 467
  (let ((tem apropos-accumulator))
    (while tem
      (if (get (car tem) 'apropos-inhibit)
	  (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
      (setq tem (cdr tem))))
468 469 470 471 472
  (let ((p apropos-accumulator)
	symbol doc properties)
    (while p
      (setcar p (list
		 (setq symbol (car p))
473
		 (apropos-score-symbol symbol)
474 475 476 477
		 (when (fboundp symbol)
		   (if (setq doc (condition-case nil
				     (documentation symbol t)
				   (void-function
478 479
				    "(alias for undefined function)")
				   (error
480
				    "(error retrieving function documentation)")))
481 482 483
		       (substring doc 0 (string-match "\n" doc))
		     "(not documented)"))
		 (when (boundp symbol)
484 485
		   (apropos-documentation-property
		    symbol 'variable-documentation t))
486 487 488 489 490 491
		 (when (setq properties (symbol-plist symbol))
		   (setq doc (list (car properties)))
		   (while (setq properties (cdr (cdr properties)))
		     (setq doc (cons (car properties) doc)))
		   (mapconcat #'symbol-name (nreverse doc) " "))
		 (when (get symbol 'widget-type)
492 493
		   (apropos-documentation-property
		    symbol 'widget-documentation t))
494
		 (when (facep symbol)
495 496
		   (apropos-documentation-property
		    symbol 'face-documentation t))
497
		 (when (get symbol 'custom-group)
498 499
		   (apropos-documentation-property
		    symbol 'group-documentation t))))
500
      (setq p (cdr p))))
501
  (apropos-print
502
   (or do-all apropos-do-all)
503 504 505
   nil))


Richard M. Stallman's avatar
Richard M. Stallman committed
506
;;;###autoload
507
(defun apropos-value (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
508 509
  "Show all symbols whose value's printed image matches APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also looks
510
at the function and at the names and values of properties.
511
Returns list of symbols and values found."
512 513
  (interactive "sApropos value (regexp or words): \nP")
  (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
514 515 516
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator ())
   (let (f v p)
517 518 519
     (mapatoms
      (lambda (symbol)
	(setq f nil v nil p nil)
520 521 522 523 524
	(or (memq symbol '(apropos-regexp
			   apropos-orig-regexp apropos-all-regexp
			   apropos-words apropos-all-words
			   do-all apropos-accumulator
			   symbol f v p))
525
	    (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
526
	(if do-all
527 528
	    (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
		  p (apropos-format-plist symbol "\n    " t)))
529 530 531 532 533 534
	(if (apropos-false-hit-str v)
	    (setq v nil))
	(if (apropos-false-hit-str f)
	    (setq f nil))
	(if (apropos-false-hit-str p)
	    (setq p nil))
535
	(if (or f v p)
536
	    (setq apropos-accumulator (cons (list symbol
537 538 539 540
						  (+ (apropos-score-str f)
						     (apropos-score-str v)
						     (apropos-score-str p))
						  f v p)
541
					    apropos-accumulator))))))
542
  (apropos-print nil "\n----------------\n"))
543 544


545 546
;;;###autoload
(defun apropos-documentation (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
547 548
  "Show symbols whose documentation contain matches for APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also use
549 550 551
documentation that is not stored in the documentation file and show key
bindings.
Returns list of symbols and documentation found."
552 553
  (interactive "sApropos documentation (regexp or words): \nP")
  (setq apropos-regexp (apropos-rewrite-regexp apropos-regexp))
554 555 556
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator () apropos-files-scanned ())
  (let ((standard-input (get-buffer-create " apropos-temp"))
557
	f v sf sv)
558 559 560 561 562 563 564 565
    (unwind-protect
	(save-excursion
	  (set-buffer standard-input)
	  (apropos-documentation-check-doc-file)
	  (if do-all
	      (mapatoms
	       (lambda (symbol)
		 (setq f (apropos-safe-documentation symbol)
566 567 568 569
		       v (get symbol 'variable-documentation))
		 (if (integerp v) (setq v))
		 (setq f (apropos-documentation-internal f)
		       v (apropos-documentation-internal v))
570 571
		 (setq sf (apropos-score-doc f)
		       sv (apropos-score-doc v))
572 573 574 575 576
		 (if (or f v)
		     (if (setq apropos-item
			       (cdr (assq symbol apropos-accumulator)))
			 (progn
			   (if f
577 578 579
			       (progn
				 (setcar (nthcdr 1 apropos-item) f)
				 (setcar apropos-item (+ (car apropos-item) sf))))
580
			   (if v
581 582 583
			       (progn
				 (setcar (nthcdr 2 apropos-item) v)
				 (setcar apropos-item (+ (car apropos-item) sv)))))
584
		       (setq apropos-accumulator
585
			     (cons (list symbol
586 587
					 (+ (apropos-score-symbol symbol 2) sf sv)
					 f v)
588
				   apropos-accumulator)))))))
589
	  (apropos-print nil "\n----------------\n"))
590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608
      (kill-buffer standard-input))))


(defun apropos-value-internal (predicate symbol function)
  (if (funcall predicate symbol)
      (progn
	(setq symbol (prin1-to-string (funcall function symbol)))
	(if (string-match apropos-regexp symbol)
	    (progn
	      (if apropos-match-face
		  (put-text-property (match-beginning 0) (match-end 0)
				     'face apropos-match-face
				     symbol))
	      symbol)))))

(defun apropos-documentation-internal (doc)
  (if (consp doc)
      (apropos-documentation-check-elc-file (car doc))
    (and doc
609
	 (string-match apropos-all-regexp doc)
610
	 (save-match-data (apropos-true-hit-doc doc))
611 612 613 614 615 616 617 618 619
	 (progn
	   (if apropos-match-face
	       (put-text-property (match-beginning 0)
				  (match-end 0)
				  'face apropos-match-face
				  (setq doc (copy-sequence doc))))
	   doc))))

(defun apropos-format-plist (pl sep &optional compare)
620 621 622 623
  (setq pl (symbol-plist pl))
  (let (p p-out)
    (while pl
      (setq p (format "%s %S" (car pl) (nth 1 pl)))
624 625
      (if (or (not compare) (string-match apropos-regexp p))
	  (if apropos-property-face
626
	      (put-text-property 0 (length (symbol-name (car pl)))
627
				 'face apropos-property-face p))
628
	(setq p nil))
629 630 631 632 633 634 635
      (if p
	  (progn
	    (and compare apropos-match-face
		 (put-text-property (match-beginning 0) (match-end 0)
				    'face apropos-match-face
				    p))
	    (setq p-out (concat p-out (if p-out sep) p))))
636 637 638
      (setq pl (nthcdr 2 pl)))
    p-out))

Richard M. Stallman's avatar
Richard M. Stallman committed
639

640
;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
641

642
(defun apropos-documentation-check-doc-file ()
643 644 645
  (let (type symbol (sepa 2) sepb beg end)
    (insert ?\^_)
    (backward-char)
646
    (insert-file-contents (concat doc-directory internal-doc-file-name))
647 648 649 650 651 652 653
    (forward-char)
    (while (save-excursion
	     (setq sepb (search-forward "\^_"))
	     (not (eobp)))
      (beginning-of-line 2)
      (if (save-restriction
	    (narrow-to-region (point) (1- sepb))
654
	    (re-search-forward apropos-all-regexp nil t))
655 656 657 658
	  (progn
	    (setq beg (match-beginning 0)
		  end (point))
	    (goto-char (1+ sepa))
659 660 661 662 663 664 665 666 667 668 669
	    (setq type (if (eq ?F (preceding-char))
			   2	; function documentation
			 3)		; variable documentation
		  symbol (read)
		  beg (- beg (point) 1)
		  end (- end (point) 1)
		  doc (buffer-substring (1+ (point)) (1- sepb)))
	    (when (apropos-true-hit-doc doc)
	      (or (and (setq apropos-item (assq symbol apropos-accumulator))
		       (setcar (cdr apropos-item)
			       (+ (cadr apropos-item) (apropos-score-doc doc))))
670
		  (setq apropos-item (list symbol
671 672 673 674 675 676 677 678
					   (+ (apropos-score-symbol symbol 2)
					      (apropos-score-doc doc))
					   nil nil)
			apropos-accumulator (cons apropos-item
						  apropos-accumulator)))
	      (if apropos-match-face
		  (put-text-property beg end 'face apropos-match-face doc))
	      (setcar (nthcdr type apropos-item) doc))))
679
      (setq sepa (goto-char sepb)))))
680 681 682 683

(defun apropos-documentation-check-elc-file (file)
  (if (member file apropos-files-scanned)
      nil
684
    (let (symbol doc beg end this-is-a-variable)
685 686 687 688 689 690
      (setq apropos-files-scanned (cons file apropos-files-scanned))
      (erase-buffer)
      (insert-file-contents file)
      (while (search-forward "\n#@" nil t)
	;; Read the comment length, and advance over it.
	(setq end (read)
691 692 693 694 695 696
	      beg (1+ (point))
	      end (+ (point) end -1))
	(forward-char)
	(if (save-restriction
	      ;; match ^ and $ relative to doc string
	      (narrow-to-region beg end)
697
	      (re-search-forward apropos-all-regexp nil t))
698
	    (progn
699 700 701
	      (goto-char (+ end 2))
	      (setq doc (buffer-substring beg end)
		    end (- (match-end 0) beg)
702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730
		    beg (- (match-beginning 0) beg))
	      (when (apropos-true-hit-doc doc)
		(setq this-is-a-variable (looking-at "(def\\(var\\|const\\) ")
		      symbol (progn
			       (skip-chars-forward "(a-z")
			       (forward-char)
			       (read))
		      symbol (if (consp symbol)
				 (nth 1 symbol)
			       symbol))
		(if (if this-is-a-variable
			(get symbol 'variable-documentation)
		      (and (fboundp symbol) (apropos-safe-documentation symbol)))
		    (progn
		      (or (and (setq apropos-item (assq symbol apropos-accumulator))
			       (setcar (cdr apropos-item)
				       (+ (cadr apropos-item) (apropos-score-doc doc))))
			  (setq apropos-item (list symbol
						   (+ (apropos-score-symbol symbol 2)
						      (apropos-score-doc doc))
						   nil nil)
				apropos-accumulator (cons apropos-item
							  apropos-accumulator)))
		      (if apropos-match-face
			  (put-text-property beg end 'face apropos-match-face
					     doc))
		      (setcar (nthcdr (if this-is-a-variable 3 2)
				      apropos-item)
			      doc))))))))))
731 732 733 734



(defun apropos-safe-documentation (function)
Dave Love's avatar
Dave Love committed
735
  "Like `documentation', except it avoids calling `get_doc_string'.
Richard M. Stallman's avatar
Richard M. Stallman committed
736
Will return nil instead."
737
  (while (and function (symbolp function))
Richard M. Stallman's avatar
Richard M. Stallman committed
738
    (setq function (if (fboundp function)
739
		       (symbol-function function))))
740 741
  (if (eq (car-safe function) 'macro)
      (setq function (cdr function)))
742
  (setq function (if (byte-code-function-p function)
743 744 745 746 747 748 749 750 751 752 753 754 755 756
		     (if (> (length function) 4)
			 (aref function 4))
		   (if (eq (car-safe function) 'autoload)
		       (nth 2 function)
		     (if (eq (car-safe function) 'lambda)
			 (if (stringp (nth 2 function))
			     (nth 2 function)
			   (if (stringp (nth 3 function))
			       (nth 3 function)))))))
  (if (integerp function)
      nil
    function))


757 758 759
(defun apropos-print (do-keys spacing)
  "Output result of apropos searching into buffer `*Apropos*'.
The value of `apropos-accumulator' is the list of items to output.
760
Each element should have the format
761
 (SYMBOL SCORE FN-DOC VAR-DOC [PLIST-DOC WIDGET-DOC FACE-DOC GROUP-DOC]).
762 763
The return value is the list that was in `apropos-accumulator', sorted
alphabetically by symbol name; but this function also sets
764 765 766 767
`apropos-accumulator' to nil before returning.

If SPACING is non-nil, it should be a string;
separate items with that string."
768
  (if (null apropos-accumulator)
769
      (message "No apropos matches for `%s'" apropos-orig-regexp)
770
    (setq apropos-accumulator
771 772 773 774
	  (sort apropos-accumulator
		(lambda (a b)
		  ;; Don't sort by score if user can't see the score.
		  ;; It would be confusing.  -- rms.
775
		  (if apropos-sort-by-scores
776 777 778 779
		      (or (> (cadr a) (cadr b))
			  (and (= (cadr a) (cadr b))
			       (string-lessp (car a) (car b))))
		    (string-lessp (car a) (car b))))))
780
    (with-output-to-temp-buffer "*Apropos*"
781
      (let ((p apropos-accumulator)
782
	    (old-buffer (current-buffer))
783
	    symbol item)
784 785
	(set-buffer standard-output)
	(apropos-mode)
786
	(if (display-mouse-p)
787 788 789 790 791
	    (insert
	     "If moving the mouse over text changes the text's color, "
	     "you can click\n"
	     "mouse-2 (second button from right) on that text to "
	     "get more information.\n"))
792
	(insert "In this buffer, go to the name of the command, or function,"
793 794 795
		" or variable,\n"
		(substitute-command-keys
		 "and type \\[apropos-follow] to get full documentation.\n\n"))
796
	(while (consp p)
797 798
	  (when (and spacing (not (bobp)))
	    (princ spacing))
799 800
	  (setq apropos-item (car p)
		symbol (car apropos-item)
801 802 803 804 805 806 807
		p (cdr p))
	  (insert-text-button (symbol-name symbol)
			      'type 'apropos-symbol
			      ;; Can't use default, since user may have
			      ;; changed the variable!
			      ;; Just say `no' to variables containing faces!
			      'face apropos-symbol-face)
808
	  (if apropos-sort-by-scores
809
	      (insert " (" (number-to-string (cadr apropos-item)) ") "))
810
	  ;; Calculate key-bindings if we want them.
811 812 813
	  (and do-keys
	       (commandp symbol)
	       (indent-to 30 1)
814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835
	       (if (let ((keys
			  (save-excursion
			    (set-buffer old-buffer)
			    (where-is-internal symbol)))
			 filtered)
		     ;; Copy over the list of key sequences,
		     ;; omitting any that contain a buffer or a frame.
		     (while keys
		       (let ((key (car keys))
			     (i 0)
			     loser)
			 (while (< i (length key))
			   (if (or (framep (aref key i))
				   (bufferp (aref key i)))
			       (setq loser t))
			   (setq i (1+ i)))
			 (or loser
			     (setq filtered (cons key filtered))))
		       (setq keys (cdr keys)))
		     (setq item filtered))
		   ;; Convert the remaining keys to a string and insert.
		   (insert
836
		    (mapconcat
837
		     (lambda (key)
Dave Love's avatar
Dave Love committed
838
		       (setq key (condition-case ()
839 840
				     (key-description key)
				   (error)))
841
		       (if apropos-keybinding-face
842 843
			   (put-text-property 0 (length key)
					      'face apropos-keybinding-face
844 845 846
					      key))
		       key)
		     item ", "))
847 848 849 850 851 852 853
		 (insert "M-x")
		 (put-text-property (- (point) 3) (point)
				    'face apropos-keybinding-face)
		 (insert " " (symbol-name symbol) " ")
		 (insert "RET")
		 (put-text-property (- (point) 3) (point)
				    'face apropos-keybinding-face)))
854
	  (terpri)
855
	  (apropos-print-doc 2
856
			     (if (commandp symbol)
857
				 'apropos-command
858
			       (if (apropos-macrop symbol)
859 860
				   'apropos-macro
				 'apropos-function))
861
			     t)
862 863 864 865 866
	  (apropos-print-doc 3 'apropos-variable t)
	  (apropos-print-doc 7 'apropos-group t)
	  (apropos-print-doc 6 'apropos-face t)
	  (apropos-print-doc 5 'apropos-widget t)
	  (apropos-print-doc 4 'apropos-plist nil))
867
	(setq buffer-read-only t))))
868 869 870
  (prog1 apropos-accumulator
    (setq apropos-accumulator ())))	; permit gc

871

872 873 874 875 876 877 878 879 880
(defun apropos-macrop (symbol)
  "T if SYMBOL is a Lisp macro."
  (and (fboundp symbol)
       (consp (setq symbol
		    (symbol-function symbol)))
       (or (eq (car symbol) 'macro)
	   (if (eq (car symbol) 'autoload)
	       (memq (nth 4 symbol)
		     '(macro t))))))
881

882

883
(defun apropos-print-doc (i type do-keys)
884
  (if (stringp (setq i (nth i apropos-item)))
885 886
      (progn
	(insert "  ")
887 888
	(insert-text-button (button-type-get type 'apropos-label)
			    'type type
889 890 891 892
			    ;; Can't use the default button face, since
			    ;; user may have changed the variable!
			    ;; Just say `no' to variables containing faces!
			    'face apropos-label-face
893
			    'apropos-symbol (car apropos-item))
894
	(insert ": ")
895 896
	(insert (if do-keys (substitute-command-keys i) i))
	(or (bolp) (terpri)))))
897 898


899 900
(defun apropos-follow ()
  "Invokes any button at point, otherwise invokes the nearest label button."
901
  (interactive)
902 903 904
  (button-activate
   (or (apropos-next-label-button (line-beginning-position))
       (error "There is nothing to follow here"))))
905 906 907 908 909 910 911 912 913


(defun apropos-describe-plist (symbol)
  "Display a pretty listing of SYMBOL's plist."
  (with-output-to-temp-buffer "*Help*"
    (set-buffer standard-output)
    (princ "Symbol ")
    (prin1 symbol)
    (princ "'s plist is\n (")
914 915
    (if apropos-symbol-face
	(put-text-property 8 (- (point) 14) 'face apropos-symbol-face))
916
    (insert (apropos-format-plist symbol "\n  "))
917 918
    (princ ")")
    (print-help-return-message)))
Richard M. Stallman's avatar
Richard M. Stallman committed
919

920

Richard M. Stallman's avatar
Richard M. Stallman committed
921 922
(provide 'apropos)

Eric S. Raymond's avatar
Eric S. Raymond committed
923
;;; apropos.el ends here