apropos.el 19.2 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 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>
6
;; Rewritten: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389
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 22 23 24
;; 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
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

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

;; 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.
39 40
;;; Made fast-apropos and super-apropos share code.
;;; Sped up fast-apropos again.
Richard M. Stallman's avatar
Richard M. Stallman committed
41
;; Added apropos-do-all option.
42
;;; Added fast-command-apropos.
Richard M. Stallman's avatar
Richard M. Stallman committed
43
;; Changed doc strings to comments for helping functions.
44
;;; Made doc file buffer read-only, buried it.
Richard M. Stallman's avatar
Richard M. Stallman committed
45 46
;; Only call substitute-command-keys if do-all set.

47 48
;; Optionally use configurable faces to make the output more legible.
;; Differentiate between command, function and macro.
49 50 51 52 53 54 55 56
;; 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
57 58
;;; Code:

59
;; I see a degradation of maybe 10-20% only.
Richard M. Stallman's avatar
Richard M. Stallman committed
60
(defvar apropos-do-all nil
61 62 63 64
  "*Whether the apropos commands should do more.
Slows them down more or less.  Set this non-nil if you have a fast machine.")


65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
(defvar apropos-symbol-face (if window-system 'bold)
  "*Face for symbol name in apropos output or `nil'.  
This looks good, but slows down the commands several times.")

(defvar apropos-keybinding-face (if window-system 'underline)
  "*Face for keybinding display in apropos output or `nil'.  
This looks good, but slows down the commands several times.")

(defvar apropos-label-face (if window-system 'italic)
  "*Face for label (Command, Variable ...) in apropos output or `nil'.
If this is `nil' no mouse highlighting occurs.
This looks good, but slows down the commands several times.
When this is a face name, as it is initially, it gets transformed to a
text-property list for efficiency.")

(defvar apropos-property-face (if window-system 'bold-italic)
  "*Face for property name in apropos output or `nil'.  
This looks good, but slows down the commands several times.")

84
(defvar apropos-match-face (if window-system 'secondary-selection)
85
  "*Face for matching part in apropos-documentation/value output or `nil'.  
86 87
This looks good, but slows down the commands several times.")

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

89
(defvar apropos-mode-map
90 91 92 93 94
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-m" 'apropos-follow)
    (define-key map [mouse-2] 'apropos-mouse-follow)
    (define-key map [down-mouse-2] nil)
    map)
95
  "Keymap used in Apropos mode.")
96

97

98 99 100 101
(defvar apropos-regexp nil
  "Regexp used in current apropos run.")

(defvar apropos-files-scanned ()
Karl Heuer's avatar
Karl Heuer committed
102
  "List of elc files already scanned in current run of `apropos-documentation'.")
103 104 105

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

107 108 109
(defvar apropos-item ()
  "Current item in or for apropos-accumulator.")

110 111 112 113 114 115 116 117 118 119 120
(defun apropos-mode ()
  "Major mode for following hyperlinks in output of apropos commands.

\\{apropos-mode-map}"
  (interactive)
  (kill-all-local-variables)
  (use-local-map apropos-mode-map)
  (setq major-mode 'apropos-mode
	mode-name "Apropos"))


121 122 123
;; For auld lang syne:
;;;###autoload
(fset 'command-apropos 'apropos-command)
Richard M. Stallman's avatar
Richard M. Stallman committed
124
;;;###autoload
125
(defun apropos-command (apropos-regexp &optional do-all)
126 127 128 129 130
  "Shows commands (interactively callable functions) that match REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also show
variables."
  (interactive (list (read-string (concat "Apropos command "
					  (if (or current-prefix-arg
131
						  apropos-do-all)
132 133
					      "or variable ")
					  "(regexp): "))
134
		     current-prefix-arg))
135
  (let ((message
136
	 (let ((standard-output (get-buffer-create "*Apropos*")))
137
	   (print-help-return-message 'identity))))
138 139 140 141 142 143 144
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator
	  (apropos-internal apropos-regexp
			    (if do-all
				(lambda (symbol) (or (commandp symbol)
						     (user-variable-p symbol)))
			      'commandp)))
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
    (if (apropos-print
	 t
	 (lambda (p)
	   (let (doc symbol)
	     (while p
	       (setcar p (list
			  (setq symbol (car p))
			  (if (commandp symbol)
			      (if (setq doc (documentation symbol t))
				  (substring doc 0 (string-match "\n" doc))
				"(not documented)"))
			  (and do-all
			       (user-variable-p symbol)
			       (if (setq doc (documentation-property
					      symbol 'variable-documentation t))
				   (substring doc 0
					      (string-match "\n" doc))))))
	       (setq p (cdr p)))))
	 nil)
	(and message (message message)))))


;;;###autoload
168 169 170 171
(defun apropos (apropos-regexp &optional do-all)
  "Show all bound symbols whose names match REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also show unbound
symbols and key bindings, which is a little more time-consuming.
Richard M. Stallman's avatar
Richard M. Stallman committed
172
Returns list of symbols and documentation found."
173
  (interactive "sApropos symbol (regexp): \nP")
174 175 176 177 178 179 180 181
  (setq apropos-accumulator
	(apropos-internal apropos-regexp
			  (and (not do-all)
			       (not apropos-do-all)
			       (lambda (symbol)
				 (or (fboundp symbol)
				     (boundp symbol)
				     (symbol-plist symbol))))))
182
  (apropos-print
183
   (or do-all apropos-do-all)
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
   (lambda (p)
     (let (symbol doc)
       (while p
	 (setcar p (list
		    (setq symbol (car p))
		    (if (fboundp symbol)
			(if (setq doc (documentation symbol t))
			    (substring doc 0 (string-match "\n" doc))
			  "(not documented)"))
		    (if (boundp symbol)
			(if (setq doc (documentation-property
				       symbol 'variable-documentation t))
			    (substring doc 0
				       (string-match "\n" doc))
			  "(not documented)"))
		    (if (setq doc (symbol-plist symbol))
200 201 202
			(if (eq (/ (length doc) 2) 1)
			    (format "1 property (%s)" (car doc))
			  (concat (/ (length doc) 2) " properties")))))
203 204 205 206
	 (setq p (cdr p)))))
   nil))


Richard M. Stallman's avatar
Richard M. Stallman committed
207
;;;###autoload
208
(defun apropos-value (apropos-regexp &optional do-all)
209 210 211
  "Show all symbols whose value's printed image matches REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also looks
at the function and at the names and values of properties.
212
Returns list of symbols and values found."
213
  (interactive "sApropos value (regexp): \nP")
214 215 216
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator ())
   (let (f v p)
217 218 219
     (mapatoms
      (lambda (symbol)
	(setq f nil v nil p nil)
220 221 222
	(or (memq symbol '(apropos-regexp do-all apropos-accumulator
					  symbol f v p))
	    (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
223
	(if do-all
224 225
	    (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
		  p (apropos-format-plist symbol "\n    " t)))
226
	(if (or f v p)
227 228 229
	    (setq apropos-accumulator (cons (list symbol f v p)
					    apropos-accumulator))))))
  (apropos-print nil nil t))
230 231


232 233
;;;###autoload
(defun apropos-documentation (apropos-regexp &optional do-all)
234
  "Show symbols whose documentation contain matches for REGEXP.
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
With optional prefix ARG or if `apropos-do-all' is non-nil, also use
documentation that is not stored in the documentation file and show key
bindings.
Returns list of symbols and documentation found."
  (interactive "sApropos documentation (regexp): \nP")
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator () apropos-files-scanned ())
  (let ((standard-input (get-buffer-create " apropos-temp"))
	f v)
    (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)
252 253 254 255
		       v (get symbol 'variable-documentation))
		 (if (integerp v) (setq v))
		 (setq f (apropos-documentation-internal f)
		       v (apropos-documentation-internal v))
256 257 258 259 260 261 262 263 264 265 266
		 (if (or f v)
		     (if (setq apropos-item
			       (cdr (assq symbol apropos-accumulator)))
			 (progn
			   (if f
			       (setcar apropos-item f))
			   (if v
			       (setcar (cdr apropos-item) v)))
		       (setq apropos-accumulator
			     (cons (list symbol f v)
				   apropos-accumulator)))))))
267
	  (apropos-print nil nil t))
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
      (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
	 (string-match apropos-regexp doc)
	 (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)
297 298 299 300
  (setq pl (symbol-plist pl))
  (let (p p-out)
    (while pl
      (setq p (format "%s %S" (car pl) (nth 1 pl)))
301 302
      (if (or (not compare) (string-match apropos-regexp p))
	  (if apropos-property-face
303
	      (put-text-property 0 (length (symbol-name (car pl)))
304
				 'face apropos-property-face p))
305
	(setq p nil))
306 307 308 309 310 311 312
      (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))))
313 314 315
      (setq pl (nthcdr 2 pl)))
    p-out))

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

317
;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
318

319
(defun apropos-documentation-check-doc-file ()
320 321 322
  (let (type symbol (sepa 2) sepb beg end)
    (insert ?\^_)
    (backward-char)
323
    (insert-file-contents (concat doc-directory internal-doc-file-name))
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
    (forward-char)
    (while (save-excursion
	     (setq sepb (search-forward "\^_"))
	     (not (eobp)))
      (beginning-of-line 2)
      (if (save-restriction
	    (narrow-to-region (point) (1- sepb))
	    (re-search-forward apropos-regexp nil t))
	  (progn
	    (setq beg (match-beginning 0)
		  end (point))
	    (goto-char (1+ sepa))
	    (or (setq type (if (eq ?F (preceding-char))
			       1	; function documentation
			     2)		; variable documentation
		      symbol (read)
		      beg (- beg (point) 1)
		      end (- end (point) 1)
		      doc (buffer-substring (1+ (point)) (1- sepb))
		      apropos-item (assq symbol apropos-accumulator))
		(setq apropos-item (list symbol 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)))
      (setq sepa (goto-char sepb)))))
351 352 353 354

(defun apropos-documentation-check-elc-file (file)
  (if (member file apropos-files-scanned)
      nil
355
    (let (symbol doc beg end this-is-a-variable)
356 357 358 359 360 361
      (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)
362 363 364 365 366 367 368
	      beg (1+ (point))
	      end (+ (point) end -1))
	(forward-char)
	(if (save-restriction
	      ;; match ^ and $ relative to doc string
	      (narrow-to-region beg end)
	      (re-search-forward apropos-regexp nil t))
369
	    (progn
370 371 372 373 374
	      (goto-char (+ end 2))
	      (setq doc (buffer-substring beg end)
		    end (- (match-end 0) beg)
		    beg (- (match-beginning 0) beg)
		    this-is-a-variable (looking-at "(def\\(var\\|const\\) ")
375 376
		    symbol (progn
			     (skip-chars-forward "(a-z")
377
			     (forward-char)
378 379 380 381 382 383 384 385 386 387 388 389 390
			     (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 (setq apropos-item (assq symbol apropos-accumulator))
			(setq apropos-item (list symbol nil nil)
			      apropos-accumulator (cons apropos-item
							apropos-accumulator)))
		    (if apropos-match-face
391
			(put-text-property beg end 'face apropos-match-face
392 393 394
					   doc))
		    (setcar (nthcdr (if this-is-a-variable 2 1)
				    apropos-item)
395
			    doc)))))))))
396 397 398 399



(defun apropos-safe-documentation (function)
Richard M. Stallman's avatar
Richard M. Stallman committed
400 401
  "Like documentation, except it avoids calling `get_doc_string'.
Will return nil instead."
402
  (while (and function (symbolp function))
Richard M. Stallman's avatar
Richard M. Stallman committed
403
    (setq function (if (fboundp function)
404
		       (symbol-function function))))
405 406
  (if (eq (car-safe function) 'macro)
      (setq function (cdr function)))
407
  (setq function (if (byte-code-function-p function)
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426
		     (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))



(defun apropos-print (do-keys doc-fn spacing)
  "Output result of various apropos commands with `apropos-regexp'.
APROPOS-ACCUMULATOR is a list.  Optional DOC-FN is called for each element
of apropos-accumulator and may modify it resulting in (symbol fn-doc
427 428
var-doc [plist-doc]).  Returns sorted list of symbols and documentation
found."
429 430
  (if (null apropos-accumulator)
      (message "No apropos matches for `%s'" apropos-regexp)
431
    (if doc-fn
432 433 434
	(funcall doc-fn apropos-accumulator))
    (setq apropos-accumulator
	  (sort apropos-accumulator (lambda (a b)
435
				      (string-lessp (car a) (car b)))))
436 437 438 439
    (and apropos-label-face
	 (symbolp apropos-label-face)
	 (setq apropos-label-face `(face ,apropos-label-face
					 mouse-face highlight)))
440
    (with-output-to-temp-buffer "*Apropos*"
441
      (let ((p apropos-accumulator)
442
	    (old-buffer (current-buffer))
443
	    symbol item point1 point2)
444 445 446
	(set-buffer standard-output)
	(apropos-mode)
	(if window-system
447 448
	    (insert "If you move the mouse over text that changes color,\n"
		    (substitute-command-keys
449
		     "you can click \\[apropos-mouse-follow] to get more information.\n")))
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497
	(insert (substitute-command-keys
		 "In this buffer, type \\[apropos-follow] to get full documentation.\n\n"))
	(while (consp p)
	  (or (not spacing) (bobp) (terpri))
	  (setq apropos-item (car p)
		symbol (car apropos-item)
		p (cdr p)
		point1 (point))
	  (princ symbol)		        ; print symbol name
	  (setq point2 (point))
	  ;; don't calculate key-bindings unless needed
	  (and do-keys
	       (commandp symbol)
	       (indent-to 30 1)
	       (insert
		(if (setq item (save-excursion
				 (set-buffer old-buffer)
				 (where-is-internal symbol)))
		    (mapconcat
		     (if apropos-keybinding-face
			 (lambda (key)
			   (setq key (key-description key))
			   (put-text-property 0 (length key)
					      'face apropos-keybinding-face
					      key)
			   key)
		       'key-description)
		     item ", ")
		  "(not bound to any keys)")))
	  (terpri)
	  ;; only now so we don't propagate text attributes all over
	  (put-text-property point1 point2 'item
			     (if (eval `(or ,@(cdr apropos-item)))
				 (car apropos-item)
			       apropos-item))
	  (if apropos-symbol-face
	      (put-text-property point1 point2 'face apropos-symbol-face))
	  (apropos-print-doc 'describe-function 1
			     (if (commandp symbol)
				 "Command"
			       (if (apropos-macrop symbol)
				   "Macro"
				 "Function"))
			     do-keys)
	  (apropos-print-doc 'describe-variable 2
			     "Variable" do-keys)
	  (apropos-print-doc 'apropos-describe-plist 3
			     "Plist" nil)))))
498 499 500
  (prog1 apropos-accumulator
    (setq apropos-accumulator ())))	; permit gc

501

502 503 504 505 506 507 508 509 510
(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))))))
511

512 513 514

(defun apropos-print-doc (action i str do-keys)
  (if (stringp (setq i (nth i apropos-item)))
515 516 517 518
      (progn
	(insert "  ")
	(put-text-property (- (point) 2) (1- (point))
			   'action action)
519 520 521
	(insert str ": ")
	(if apropos-label-face
	    (add-text-properties (- (point) (length str) 2)
522
				 (1- (point))
523 524 525
				 apropos-label-face))
	(insert (if do-keys (substitute-command-keys i) i))
	(or (bolp) (terpri)))))
526 527 528 529


(defun apropos-mouse-follow (event)
  (interactive "e")
530
  (let ((other (if (eq (current-buffer) (get-buffer "*Apropos*"))
531 532
		   ()
		 (current-buffer))))
533 534 535 536 537 538 539
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-start event))))
      (goto-char (posn-point (event-start event)))
      (or (and (not (eobp)) (get-text-property (point) 'mouse-face))
	  (and (not (bobp)) (get-text-property (1- (point)) 'mouse-face))
	  (error "There is nothing to follow here"))
      (apropos-follow other))))
540 541 542 543


(defun apropos-follow (&optional other)
  (interactive)
544 545 546 547 548 549 550 551 552 553 554 555 556
  (let* (;; Properties are always found at the beginning of the line.
	 (bol (save-excursion (beginning-of-line) (point)))
	 ;; If there is no `item' property here, look behind us.
	 (item (get-text-property bol 'item))
	 (item-at (if item nil (previous-single-property-change bol 'item)))
	 ;; Likewise, if there is no `action' property here, look in front.
	 (action (get-text-property bol 'action))
	 (action-at (if action nil (next-single-property-change bol 'action))))
    (and (null item) item-at
	 (setq item (get-text-property (1- item-at) 'item)))
    (and (null action) action-at
	 (setq action (get-text-property action-at 'action)))
    (if (not (and item action))
557
	(error "There is nothing to follow here"))
558 559 560
    (if (consp item) (error "There is nothing to follow in `%s'" (car item)))
    (if other (set-buffer other))
    (funcall action item)))
561 562 563 564 565 566 567 568 569 570



(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 (")
571 572
    (if apropos-symbol-face
	(put-text-property 8 (- (point) 14) 'face apropos-symbol-face))
573
    (insert (apropos-format-plist symbol "\n  "))
574 575
    (princ ")")
    (print-help-return-message)))
Richard M. Stallman's avatar
Richard M. Stallman committed
576

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