Merge from trunk; up to 2014-02-23T23:41:17Z!lekktu@gmail.com.
[emacs.git] / lisp / apropos.el
blob47e44485c627a55165c5b633f4781f74befc5a6b
1 ;;; apropos.el --- apropos commands for users and programmers
3 ;; Copyright (C) 1989, 1994-1995, 2001-2014 Free Software Foundation,
4 ;; Inc.
6 ;; Author: Joe Wells <jbw@bigbird.bu.edu>
7 ;; Daniel Pfeiffer <occitan@esperanto.org> (rewrite)
8 ;; Keywords: help
9 ;; Package: emacs
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 ;;; Commentary:
28 ;; The ideas for this package were derived from the C code in
29 ;; src/keymap.c and elsewhere. The functions in this file should
30 ;; always be byte-compiled for speed. Someone should rewrite this in
31 ;; C (as part of src/keymap.c) for speed.
33 ;; The idea for super-apropos is based on the original implementation
34 ;; by Lynn Slater <lrs@esl.com>.
36 ;; History:
37 ;; Fixed bug, current-local-map can return nil.
38 ;; Change, doesn't calculate key-bindings unless needed.
39 ;; Added super-apropos capability, changed print functions.
40 ;; Made fast-apropos and super-apropos share code.
41 ;; Sped up fast-apropos again.
42 ;; Added apropos-do-all option.
43 ;; Added fast-command-apropos.
44 ;; Changed doc strings to comments for helping functions.
45 ;; Made doc file buffer read-only, buried it.
46 ;; Only call substitute-command-keys if do-all set.
48 ;; Optionally use configurable faces to make the output more legible.
49 ;; Differentiate between command, function and macro.
50 ;; Apropos-command (ex command-apropos) does cmd and optionally user var.
51 ;; Apropos shows all 3 aspects of symbols (fn, var and plist)
52 ;; Apropos-documentation (ex super-apropos) now finds all it should.
53 ;; New apropos-value snoops through all values and optionally plists.
54 ;; Reading DOC file doesn't load nroff.
55 ;; Added hypertext following of documentation, mouse-2 on variable gives value
56 ;; from buffer in active window.
58 ;;; Code:
60 (require 'button)
62 (defgroup apropos nil
63 "Apropos commands for users and programmers."
64 :group 'help
65 :prefix "apropos")
67 ;; I see a degradation of maybe 10-20% only.
68 (defcustom apropos-do-all nil
69 "Non nil means apropos commands will search more extensively.
70 This may be slower. This option affects the following commands:
72 `apropos-user-option' will search all variables, not just user options.
73 `apropos-command' will also search non-interactive functions.
74 `apropos' will search all symbols, not just functions, variables, faces,
75 and those with property lists.
76 `apropos-value' will also search in property lists and functions.
77 `apropos-documentation' will search all documentation strings, not just
78 those in the etc/DOC documentation file.
80 This option only controls the default behavior. Each of the above
81 commands also has an optional argument to request a more extensive search.
83 Additionally, this option makes the function `apropos-library'
84 include key-binding information in its output."
85 :group 'apropos
86 :type 'boolean)
88 (defface apropos-symbol
89 '((t (:inherit bold)))
90 "Face for the symbol name in Apropos output."
91 :group 'apropos
92 :version "24.3")
94 (defface apropos-keybinding
95 '((t (:inherit underline)))
96 "Face for lists of keybinding in Apropos output."
97 :group 'apropos
98 :version "24.3")
100 (defface apropos-property
101 '((t (:inherit font-lock-builtin-face)))
102 "Face for property name in Apropos output, or nil for none."
103 :group 'apropos
104 :version "24.3")
106 (defface apropos-function-button
107 '((t (:inherit (font-lock-function-name-face button))))
108 "Button face indicating a function, macro, or command in Apropos."
109 :group 'apropos
110 :version "24.3")
112 (defface apropos-variable-button
113 '((t (:inherit (font-lock-variable-name-face button))))
114 "Button face indicating a variable in Apropos."
115 :group 'apropos
116 :version "24.3")
118 (defface apropos-user-option-button
119 '((t (:inherit (font-lock-variable-name-face button))))
120 "Button face indicating a user option in Apropos."
121 :group 'apropos
122 :version "24.4")
124 (defface apropos-misc-button
125 '((t (:inherit (font-lock-constant-face button))))
126 "Button face indicating a miscellaneous object type in Apropos."
127 :group 'apropos
128 :version "24.3")
130 (defcustom apropos-match-face 'match
131 "Face for matching text in Apropos documentation/value, or nil for none.
132 This applies when you look for matches in the documentation or variable value
133 for the pattern; the part that matches gets displayed in this font."
134 :type '(choice (const nil) face)
135 :group 'apropos
136 :version "24.3")
138 (defcustom apropos-sort-by-scores nil
139 "Non-nil means sort matches by scores; best match is shown first.
140 This applies to all `apropos' commands except `apropos-documentation'.
141 If value is `verbose', the computed score is shown for each match."
142 :group 'apropos
143 :type '(choice (const :tag "off" nil)
144 (const :tag "on" t)
145 (const :tag "show scores" verbose)))
147 (defcustom apropos-documentation-sort-by-scores t
148 "Non-nil means sort matches by scores; best match is shown first.
149 This applies to `apropos-documentation' only.
150 If value is `verbose', the computed score is shown for each match."
151 :group 'apropos
152 :type '(choice (const :tag "off" nil)
153 (const :tag "on" t)
154 (const :tag "show scores" verbose)))
156 (defvar apropos-mode-map
157 (let ((map (copy-keymap button-buffer-map)))
158 (set-keymap-parent map special-mode-map)
159 ;; Use `apropos-follow' instead of just using the button
160 ;; definition of RET, so that users can use it anywhere in an
161 ;; apropos item, not just on top of a button.
162 (define-key map "\C-m" 'apropos-follow)
163 map)
164 "Keymap used in Apropos mode.")
166 (defvar apropos-mode-hook nil
167 "Hook run when mode is turned on.")
169 (defvar apropos-pattern nil
170 "Apropos pattern as entered by user.")
172 (defvar apropos-pattern-quoted nil
173 "Apropos pattern passed through `regexp-quote'.")
175 (defvar apropos-words ()
176 "Current list of apropos words extracted from `apropos-pattern'.")
178 (defvar apropos-all-words ()
179 "Current list of words and synonyms.")
181 (defvar apropos-regexp nil
182 "Regexp used in current apropos run.")
184 (defvar apropos-all-words-regexp nil
185 "Regexp matching `apropos-all-words'.")
187 (defvar apropos-files-scanned ()
188 "List of elc files already scanned in current run of `apropos-documentation'.")
190 (defvar apropos-accumulator ()
191 "Alist of symbols already found in current apropos run.
192 Each element has the form
194 (SYMBOL SCORE FUN-DOC VAR-DOC PLIST WIDGET-DOC FACE-DOC CUS-GROUP-DOC)
196 where SYMBOL is the symbol name, SCORE is its relevance score (a
197 number), FUN-DOC is the function docstring, VAR-DOC is the
198 variable docstring, PLIST is the list of the symbols names in the
199 property list, WIDGET-DOC is the widget docstring, FACE-DOC is
200 the face docstring, and CUS-GROUP-DOC is the custom group
201 docstring. Each docstring is either nil or a string.")
203 (defvar apropos-item ()
204 "Current item in or for `apropos-accumulator'.")
206 (defvar apropos-synonyms '(
207 ("find" "open" "edit")
208 ("kill" "cut")
209 ("yank" "paste")
210 ("region" "selection"))
211 "List of synonyms known by apropos.
212 Each element is a list of words where the first word is the standard Emacs
213 term, and the rest of the words are alternative terms.")
216 ;;; Button types used by apropos
218 (define-button-type 'apropos-symbol
219 'face 'apropos-symbol
220 'help-echo "mouse-2, RET: Display more help on this symbol"
221 'follow-link t
222 'action #'apropos-symbol-button-display-help)
224 (defun apropos-symbol-button-display-help (button)
225 "Display further help for the `apropos-symbol' button BUTTON."
226 (button-activate
227 (or (apropos-next-label-button (button-start button))
228 (error "There is nothing to follow for `%s'" (button-label button)))))
230 (define-button-type 'apropos-function
231 'apropos-label "Function"
232 'apropos-short-label "f"
233 'face 'apropos-function-button
234 'help-echo "mouse-2, RET: Display more help on this function"
235 'follow-link t
236 'action (lambda (button)
237 (describe-function (button-get button 'apropos-symbol))))
239 (define-button-type 'apropos-macro
240 'apropos-label "Macro"
241 'apropos-short-label "m"
242 'face 'apropos-function-button
243 'help-echo "mouse-2, RET: Display more help on this macro"
244 'follow-link t
245 'action (lambda (button)
246 (describe-function (button-get button 'apropos-symbol))))
248 (define-button-type 'apropos-command
249 'apropos-label "Command"
250 'apropos-short-label "c"
251 'face 'apropos-function-button
252 'help-echo "mouse-2, RET: Display more help on this command"
253 'follow-link t
254 'action (lambda (button)
255 (describe-function (button-get button 'apropos-symbol))))
257 ;; We used to use `customize-variable-other-window' instead for a
258 ;; customizable variable, but that is slow. It is better to show an
259 ;; ordinary help buffer and let the user click on the customization
260 ;; button in that buffer, if he wants to.
261 ;; Likewise for `customize-face-other-window'.
262 (define-button-type 'apropos-variable
263 'apropos-label "Variable"
264 'apropos-short-label "v"
265 'face 'apropos-variable-button
266 'help-echo "mouse-2, RET: Display more help on this variable"
267 'follow-link t
268 'action (lambda (button)
269 (describe-variable (button-get button 'apropos-symbol))))
271 (define-button-type 'apropos-user-option
272 'apropos-label "User option"
273 'apropos-short-label "o"
274 'face 'apropos-user-option-button
275 'help-echo "mouse-2, RET: Display more help on this user option"
276 'follow-link t
277 'action (lambda (button)
278 (describe-variable (button-get button 'apropos-symbol))))
280 (define-button-type 'apropos-face
281 'apropos-label "Face"
282 'apropos-short-label "F"
283 'face '(font-lock-variable-name-face button)
284 'help-echo "mouse-2, RET: Display more help on this face"
285 'follow-link t
286 'action (lambda (button)
287 (describe-face (button-get button 'apropos-symbol))))
289 (define-button-type 'apropos-group
290 'apropos-label "Group"
291 'apropos-short-label "g"
292 'face 'apropos-misc-button
293 'help-echo "mouse-2, RET: Display more help on this group"
294 'follow-link t
295 'action (lambda (button)
296 (customize-group-other-window
297 (button-get button 'apropos-symbol))))
299 (define-button-type 'apropos-widget
300 'apropos-label "Widget"
301 'apropos-short-label "w"
302 'face 'apropos-misc-button
303 'help-echo "mouse-2, RET: Display more help on this widget"
304 'follow-link t
305 'action (lambda (button)
306 (widget-browse-other-window (button-get button 'apropos-symbol))))
308 (define-button-type 'apropos-plist
309 'apropos-label "Properties"
310 'apropos-short-label "p"
311 'face 'apropos-misc-button
312 'help-echo "mouse-2, RET: Display more help on this plist"
313 'follow-link t
314 'action (lambda (button)
315 (apropos-describe-plist (button-get button 'apropos-symbol))))
317 (define-button-type 'apropos-library
318 'help-echo "mouse-2, RET: Display more help on this library"
319 'follow-link t
320 'action (lambda (button)
321 (apropos-library (button-get button 'apropos-symbol))))
323 (defun apropos-next-label-button (pos)
324 "Return the next apropos label button after POS, or nil if there's none.
325 Will also return nil if more than one `apropos-symbol' button is encountered
326 before finding a label."
327 (let* ((button (next-button pos t))
328 (already-hit-symbol nil)
329 (label (and button (button-get button 'apropos-label)))
330 (type (and button (button-get button 'type))))
331 (while (and button
332 (not label)
333 (or (not (eq type 'apropos-symbol))
334 (not already-hit-symbol)))
335 (when (eq type 'apropos-symbol)
336 (setq already-hit-symbol t))
337 (setq button (next-button (button-start button)))
338 (when button
339 (setq label (button-get button 'apropos-label))
340 (setq type (button-get button 'type))))
341 (and label button)))
344 (defun apropos-words-to-regexp (words wild)
345 "Make regexp matching any two of the words in WORDS.
346 WILD should be a subexpression matching wildcards between matches."
347 (setq words (delete-dups (copy-sequence words)))
348 (if (null (cdr words))
349 (car words)
350 (mapconcat
351 (lambda (w)
352 (concat "\\(?:" w "\\)" ;; parens for synonyms
353 wild "\\(?:"
354 (mapconcat 'identity
355 (delq w (copy-sequence words))
356 "\\|")
357 "\\)"))
358 words
359 "\\|")))
361 ;;;###autoload
362 (defun apropos-read-pattern (subject)
363 "Read an apropos pattern, either a word list or a regexp.
364 Returns the user pattern, either a list of words which are matched
365 literally, or a string which is used as a regexp to search for.
367 SUBJECT is a string that is included in the prompt to identify what
368 kind of objects to search."
369 (let ((pattern
370 (read-string (concat "Search for " subject " (word list or regexp): "))))
371 (if (string-equal (regexp-quote pattern) pattern)
372 ;; Split into words
373 (or (split-string pattern "[ \t]+" t)
374 (user-error "No word list given"))
375 pattern)))
377 (defun apropos-parse-pattern (pattern)
378 "Rewrite a list of words to a regexp matching all permutations.
379 If PATTERN is a string, that means it is already a regexp.
380 This updates variables `apropos-pattern', `apropos-pattern-quoted',
381 `apropos-regexp', `apropos-words', and `apropos-all-words-regexp'."
382 (setq apropos-words nil
383 apropos-all-words nil)
384 (if (consp pattern)
385 ;; We don't actually make a regexp matching all permutations.
386 ;; Instead, for e.g. "a b c", we make a regexp matching
387 ;; any combination of two or more words like this:
388 ;; (a|b|c).*(a|b|c) which may give some false matches,
389 ;; but as long as it also gives the right ones, that's ok.
390 (let ((words pattern))
391 (setq apropos-pattern (mapconcat 'identity pattern " ")
392 apropos-pattern-quoted (regexp-quote apropos-pattern))
393 (dolist (word words)
394 (let ((syn apropos-synonyms) (s word) (a word))
395 (while syn
396 (if (member word (car syn))
397 (progn
398 (setq a (mapconcat 'identity (car syn) "\\|"))
399 (if (member word (cdr (car syn)))
400 (setq s a))
401 (setq syn nil))
402 (setq syn (cdr syn))))
403 (setq apropos-words (cons s apropos-words)
404 apropos-all-words (cons a apropos-all-words))))
405 (setq apropos-all-words-regexp
406 (apropos-words-to-regexp apropos-all-words ".+"))
407 (setq apropos-regexp
408 (apropos-words-to-regexp apropos-words ".*?")))
409 (setq apropos-pattern-quoted (regexp-quote pattern)
410 apropos-all-words-regexp pattern
411 apropos-pattern pattern
412 apropos-regexp pattern)))
414 (defun apropos-calc-scores (str words)
415 "Return apropos scores for string STR matching WORDS.
416 Value is a list of offsets of the words into the string."
417 (let (scores i)
418 (if words
419 (dolist (word words scores)
420 (if (setq i (string-match word str))
421 (setq scores (cons i scores))))
422 ;; Return list of start and end position of regexp
423 (and (string-match apropos-pattern str)
424 (list (match-beginning 0) (match-end 0))))))
426 (defun apropos-score-str (str)
427 "Return apropos score for string STR."
428 (if str
429 (let* ((l (length str))
430 (score (- (/ l 10))))
431 (dolist (s (apropos-calc-scores str apropos-all-words) score)
432 (setq score (+ score 1000 (/ (* (- l s) 1000) l)))))
435 (defun apropos-score-doc (doc)
436 "Return apropos score for documentation string DOC."
437 (let ((l (length doc)))
438 (if (> l 0)
439 (let ((score 0))
440 (when (string-match apropos-pattern-quoted doc)
441 (setq score 10000))
442 (dolist (s (apropos-calc-scores doc apropos-all-words) score)
443 (setq score (+ score 50 (/ (* (- l s) 50) l)))))
444 0)))
446 (defun apropos-score-symbol (symbol &optional weight)
447 "Return apropos score for SYMBOL."
448 (setq symbol (symbol-name symbol))
449 (let ((score 0)
450 (l (length symbol)))
451 (dolist (s (apropos-calc-scores symbol apropos-words) (* score (or weight 3)))
452 (setq score (+ score (- 60 l) (/ (* (- l s) 60) l))))))
454 (defun apropos-true-hit (str words)
455 "Return t if STR is a genuine hit.
456 This may fail if only one of the keywords is matched more than once.
457 This requires at least two keywords (unless only one was given)."
458 (or (not str)
459 (not words)
460 (not (cdr words))
461 (> (length (apropos-calc-scores str words)) 1)))
463 (defun apropos-false-hit-symbol (symbol)
464 "Return t if SYMBOL is not really matched by the current keywords."
465 (not (apropos-true-hit (symbol-name symbol) apropos-words)))
467 (defun apropos-false-hit-str (str)
468 "Return t if STR is not really matched by the current keywords."
469 (not (apropos-true-hit str apropos-words)))
471 (defun apropos-true-hit-doc (doc)
472 "Return t if DOC is really matched by the current keywords."
473 (apropos-true-hit doc apropos-all-words))
475 (define-derived-mode apropos-mode special-mode "Apropos"
476 "Major mode for following hyperlinks in output of apropos commands.
478 \\{apropos-mode-map}")
480 (defvar apropos-multi-type t
481 "If non-nil, this apropos query concerns multiple types.
482 This is used to decide whether to print the result's type or not.")
484 ;;;###autoload
485 (defun apropos-user-option (pattern &optional do-all)
486 "Show user options that match PATTERN.
487 PATTERN can be a word, a list of words (separated by spaces),
488 or a regexp (using some regexp special characters). If it is a word,
489 search for matches for that word as a substring. If it is a list of words,
490 search for matches for any two (or more) of those words.
492 With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil, also show
493 variables, not just user options."
494 (interactive (list (apropos-read-pattern
495 (if (or current-prefix-arg apropos-do-all)
496 "variable" "user option"))
497 current-prefix-arg))
498 (apropos-command pattern nil
499 (if (or do-all apropos-do-all)
500 #'(lambda (symbol)
501 (and (boundp symbol)
502 (get symbol 'variable-documentation)))
503 'custom-variable-p)))
505 ;;;###autoload
506 (defun apropos-variable (pattern &optional do-not-all)
507 "Show variables that match PATTERN.
508 When DO-NOT-ALL is non-nil, show user options only, i.e. behave
509 like `apropos-user-option'."
510 (interactive (list (apropos-read-pattern
511 (if current-prefix-arg "user option" "variable"))
512 current-prefix-arg))
513 (let ((apropos-do-all (if do-not-all nil t)))
514 (apropos-user-option pattern)))
516 ;; For auld lang syne:
517 ;;;###autoload
518 (defalias 'command-apropos 'apropos-command)
519 ;;;###autoload
520 (defun apropos-command (pattern &optional do-all var-predicate)
521 "Show commands (interactively callable functions) that match PATTERN.
522 PATTERN can be a word, a list of words (separated by spaces),
523 or a regexp (using some regexp special characters). If it is a word,
524 search for matches for that word as a substring. If it is a list of words,
525 search for matches for any two (or more) of those words.
527 With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil, also show
528 noninteractive functions.
530 If VAR-PREDICATE is non-nil, show only variables, and only those that
531 satisfy the predicate VAR-PREDICATE.
533 When called from a Lisp program, a string PATTERN is used as a regexp,
534 while a list of strings is used as a word list."
535 (interactive (list (apropos-read-pattern
536 (if (or current-prefix-arg apropos-do-all)
537 "command or function" "command"))
538 current-prefix-arg))
539 (apropos-parse-pattern pattern)
540 (let ((message
541 (let ((standard-output (get-buffer-create "*Apropos*")))
542 (help-print-return-message 'identity))))
543 (or do-all (setq do-all apropos-do-all))
544 (setq apropos-accumulator
545 (apropos-internal apropos-regexp
546 (or var-predicate
547 ;; We used to use `functionp' here, but this
548 ;; rules out macros. `fboundp' rules in
549 ;; keymaps, but it seems harmless.
550 (if do-all 'fboundp 'commandp))))
551 (let ((tem apropos-accumulator))
552 (while tem
553 (if (or (get (car tem) 'apropos-inhibit)
554 (apropos-false-hit-symbol (car tem)))
555 (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
556 (setq tem (cdr tem))))
557 (let ((p apropos-accumulator)
558 doc symbol score)
559 (while p
560 (setcar p (list
561 (setq symbol (car p))
562 (setq score (apropos-score-symbol symbol))
563 (unless var-predicate
564 (if (fboundp symbol)
565 (if (setq doc (condition-case nil
566 (documentation symbol t)
567 (error 'error)))
568 ;; Eg alias to undefined function.
569 (if (eq doc 'error)
570 "(documentation error)"
571 (setq score (+ score (apropos-score-doc doc)))
572 (substring doc 0 (string-match "\n" doc)))
573 "(not documented)")))
574 (and var-predicate
575 (funcall var-predicate symbol)
576 (if (setq doc (documentation-property
577 symbol 'variable-documentation t))
578 (progn
579 (setq score (+ score (apropos-score-doc doc)))
580 (substring doc 0
581 (string-match "\n" doc)))))))
582 (setcar (cdr (car p)) score)
583 (setq p (cdr p))))
584 (and (let ((apropos-multi-type do-all))
585 (apropos-print t nil nil t))
586 message
587 (message "%s" message))))
590 ;;;###autoload
591 (defun apropos-documentation-property (symbol property raw)
592 "Like (documentation-property SYMBOL PROPERTY RAW) but handle errors."
593 (condition-case ()
594 (let ((doc (documentation-property symbol property raw)))
595 (if doc (substring doc 0 (string-match "\n" doc))
596 "(not documented)"))
597 (error "(error retrieving documentation)")))
600 ;;;###autoload
601 (defun apropos (pattern &optional do-all)
602 "Show all meaningful Lisp symbols whose names match PATTERN.
603 Symbols are shown if they are defined as functions, variables, or
604 faces, or if they have nonempty property lists.
606 PATTERN can be a word, a list of words (separated by spaces),
607 or a regexp (using some regexp special characters). If it is a word,
608 search for matches for that word as a substring. If it is a list of words,
609 search for matches for any two (or more) of those words.
611 With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil,
612 consider all symbols (if they match PATTERN).
614 Returns list of symbols and documentation found."
615 (interactive (list (apropos-read-pattern "symbol")
616 current-prefix-arg))
617 (apropos-parse-pattern pattern)
618 (apropos-symbols-internal
619 (apropos-internal apropos-regexp
620 (and (not do-all)
621 (not apropos-do-all)
622 (lambda (symbol)
623 (or (fboundp symbol)
624 (boundp symbol)
625 (facep symbol)
626 (symbol-plist symbol)))))
627 (or do-all apropos-do-all)))
629 (defun apropos-library-button (sym)
630 (if (null sym)
631 "<nothing>"
632 (let ((name (copy-sequence (symbol-name sym))))
633 (make-text-button name nil
634 'type 'apropos-library
635 'face 'apropos-symbol
636 'apropos-symbol name)
637 name)))
639 ;;;###autoload
640 (defun apropos-library (file)
641 "List the variables and functions defined by library FILE.
642 FILE should be one of the libraries currently loaded and should
643 thus be found in `load-history'. If `apropos-do-all' is non-nil,
644 the output includes key-bindings of commands."
645 (interactive
646 (let* ((libs (delq nil (mapcar 'car load-history)))
647 (libs
648 (nconc (delq nil
649 (mapcar
650 (lambda (l)
651 (setq l (file-name-nondirectory l))
652 (while
653 (not (equal (setq l (file-name-sans-extension l))
654 l)))
656 libs))
657 libs)))
658 (list (completing-read "Describe library: " libs nil t))))
659 (let ((symbols nil)
660 ;; (autoloads nil)
661 (provides nil)
662 (requires nil)
663 (lh-entry (assoc file load-history)))
664 (unless lh-entry
665 ;; `file' may be the "shortname".
666 (let ((lh load-history)
667 (re (concat "\\(?:\\`\\|[\\/]\\)" (regexp-quote file)
668 "\\(\\.\\|\\'\\)")))
669 (while (and lh (null lh-entry))
670 (if (and (caar lh) (string-match re (caar lh)))
671 (setq lh-entry (car lh))
672 (setq lh (cdr lh)))))
673 (unless lh-entry (error "Unknown library `%s'" file)))
674 (dolist (x (cdr lh-entry))
675 (pcase (car-safe x)
676 ;; (autoload (push (cdr x) autoloads))
677 (`require (push (cdr x) requires))
678 (`provide (push (cdr x) provides))
679 (_ (push (or (cdr-safe x) x) symbols))))
680 (let ((apropos-pattern "")) ;Dummy binding for apropos-symbols-internal.
681 (apropos-symbols-internal
682 symbols apropos-do-all
683 (concat
684 (format "Library `%s' provides: %s\nand requires: %s"
685 file
686 (mapconcat 'apropos-library-button
687 (or provides '(nil)) " and ")
688 (mapconcat 'apropos-library-button
689 (or requires '(nil)) " and ")))))))
691 (defun apropos-symbols-internal (symbols keys &optional text)
692 ;; Filter out entries that are marked as apropos-inhibit.
693 (let ((all nil))
694 (dolist (symbol symbols)
695 (unless (get symbol 'apropos-inhibit)
696 (push symbol all)))
697 (setq symbols all))
698 (let ((apropos-accumulator
699 (mapcar
700 (lambda (symbol)
701 (let (doc properties)
702 (list
703 symbol
704 (apropos-score-symbol symbol)
705 (when (fboundp symbol)
706 (if (setq doc (condition-case nil
707 (documentation symbol t)
708 (void-function
709 "(alias for undefined function)")
710 (error
711 "(can't retrieve function documentation)")))
712 (substring doc 0 (string-match "\n" doc))
713 "(not documented)"))
714 (when (boundp symbol)
715 (apropos-documentation-property
716 symbol 'variable-documentation t))
717 (when (setq properties (symbol-plist symbol))
718 (setq doc (list (car properties)))
719 (while (setq properties (cdr (cdr properties)))
720 (setq doc (cons (car properties) doc)))
721 (mapconcat #'symbol-name (nreverse doc) " "))
722 (when (get symbol 'widget-type)
723 (apropos-documentation-property
724 symbol 'widget-documentation t))
725 (when (facep symbol)
726 (let ((alias (get symbol 'face-alias)))
727 (if alias
728 (if (facep alias)
729 (format "%slias for the face `%s'."
730 (if (get symbol 'obsolete-face)
731 "Obsolete a"
732 "A")
733 alias)
734 ;; Never happens in practice because fails
735 ;; (facep symbol) test.
736 "(alias for undefined face)")
737 (apropos-documentation-property
738 symbol 'face-documentation t))))
739 (when (get symbol 'custom-group)
740 (apropos-documentation-property
741 symbol 'group-documentation t)))))
742 symbols)))
743 (apropos-print keys nil text)))
746 ;;;###autoload
747 (defun apropos-value (pattern &optional do-all)
748 "Show all symbols whose value's printed representation matches PATTERN.
749 PATTERN can be a word, a list of words (separated by spaces),
750 or a regexp (using some regexp special characters). If it is a word,
751 search for matches for that word as a substring. If it is a list of words,
752 search for matches for any two (or more) of those words.
754 With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil, also looks
755 at function definitions (arguments, documentation and body) and at the
756 names and values of properties.
758 Returns list of symbols and values found."
759 (interactive (list (apropos-read-pattern "value")
760 current-prefix-arg))
761 (apropos-parse-pattern pattern)
762 (or do-all (setq do-all apropos-do-all))
763 (setq apropos-accumulator ())
764 (let (f v p)
765 (mapatoms
766 (lambda (symbol)
767 (setq f nil v nil p nil)
768 (or (memq symbol '(apropos-regexp
769 apropos-pattern apropos-all-words-regexp
770 apropos-words apropos-all-words
771 do-all apropos-accumulator
772 symbol f v p))
773 (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
774 (if do-all
775 (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
776 p (apropos-format-plist symbol "\n " t)))
777 (if (apropos-false-hit-str v)
778 (setq v nil))
779 (if (apropos-false-hit-str f)
780 (setq f nil))
781 (if (apropos-false-hit-str p)
782 (setq p nil))
783 (if (or f v p)
784 (setq apropos-accumulator (cons (list symbol
785 (+ (apropos-score-str f)
786 (apropos-score-str v)
787 (apropos-score-str p))
788 f v p)
789 apropos-accumulator))))))
790 (let ((apropos-multi-type do-all))
791 (apropos-print nil "\n----------------\n")))
794 ;;;###autoload
795 (defun apropos-documentation (pattern &optional do-all)
796 "Show symbols whose documentation contains matches for PATTERN.
797 PATTERN can be a word, a list of words (separated by spaces),
798 or a regexp (using some regexp special characters). If it is a word,
799 search for matches for that word as a substring. If it is a list of words,
800 search for matches for any two (or more) of those words.
802 Note that by default this command only searches in the file specified by
803 `internal-doc-file-name'; i.e., the etc/DOC file. With \\[universal-argument] prefix,
804 or if `apropos-do-all' is non-nil, it searches all currently defined
805 documentation strings.
807 Returns list of symbols and documentation found."
808 ;; The doc used to say that DO-ALL includes key-bindings info in the
809 ;; output, but I cannot see that that is true.
810 (interactive (list (apropos-read-pattern "documentation")
811 current-prefix-arg))
812 (apropos-parse-pattern pattern)
813 (or do-all (setq do-all apropos-do-all))
814 (setq apropos-accumulator () apropos-files-scanned ())
815 (let ((standard-input (get-buffer-create " apropos-temp"))
816 (apropos-sort-by-scores apropos-documentation-sort-by-scores)
817 f v sf sv)
818 (unwind-protect
819 (with-current-buffer standard-input
820 (apropos-documentation-check-doc-file)
821 (if do-all
822 (mapatoms
823 (lambda (symbol)
824 (setq f (apropos-safe-documentation symbol)
825 v (get symbol 'variable-documentation))
826 (if (integerp v) (setq v))
827 (setq f (apropos-documentation-internal f)
828 v (apropos-documentation-internal v))
829 (setq sf (apropos-score-doc f)
830 sv (apropos-score-doc v))
831 (if (or f v)
832 (if (setq apropos-item
833 (cdr (assq symbol apropos-accumulator)))
834 (progn
835 (if f
836 (progn
837 (setcar (nthcdr 1 apropos-item) f)
838 (setcar apropos-item (+ (car apropos-item) sf))))
839 (if v
840 (progn
841 (setcar (nthcdr 2 apropos-item) v)
842 (setcar apropos-item (+ (car apropos-item) sv)))))
843 (setq apropos-accumulator
844 (cons (list symbol
845 (+ (apropos-score-symbol symbol 2) sf sv)
846 f v)
847 apropos-accumulator)))))))
848 (apropos-print nil "\n----------------\n" nil t))
849 (kill-buffer standard-input))))
852 (defun apropos-value-internal (predicate symbol function)
853 (if (funcall predicate symbol)
854 (progn
855 (setq symbol (prin1-to-string (funcall function symbol)))
856 (if (string-match apropos-regexp symbol)
857 (progn
858 (if apropos-match-face
859 (put-text-property (match-beginning 0) (match-end 0)
860 'face apropos-match-face
861 symbol))
862 symbol)))))
864 (defun apropos-documentation-internal (doc)
865 (if (consp doc)
866 (apropos-documentation-check-elc-file (car doc))
867 (if (and doc
868 (string-match apropos-all-words-regexp doc)
869 (apropos-true-hit-doc doc))
870 (when apropos-match-face
871 (setq doc (substitute-command-keys (copy-sequence doc)))
872 (if (or (string-match apropos-pattern-quoted doc)
873 (string-match apropos-all-words-regexp doc))
874 (put-text-property (match-beginning 0)
875 (match-end 0)
876 'face apropos-match-face doc))
877 doc))))
879 (defun apropos-format-plist (pl sep &optional compare)
880 (setq pl (symbol-plist pl))
881 (let (p p-out)
882 (while pl
883 (setq p (format "%s %S" (car pl) (nth 1 pl)))
884 (if (or (not compare) (string-match apropos-regexp p))
885 (put-text-property 0 (length (symbol-name (car pl)))
886 'face 'apropos-property p)
887 (setq p nil))
888 (if p
889 (progn
890 (and compare apropos-match-face
891 (put-text-property (match-beginning 0) (match-end 0)
892 'face apropos-match-face
894 (setq p-out (concat p-out (if p-out sep) p))))
895 (setq pl (nthcdr 2 pl)))
896 p-out))
899 ;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
901 (defun apropos-documentation-check-doc-file ()
902 (let (type symbol (sepa 2) sepb doc)
903 (insert ?\^_)
904 (backward-char)
905 (insert-file-contents (concat doc-directory internal-doc-file-name))
906 (forward-char)
907 (while (save-excursion
908 (setq sepb (search-forward "\^_"))
909 (not (eobp)))
910 (beginning-of-line 2)
911 (if (save-restriction
912 (narrow-to-region (point) (1- sepb))
913 (re-search-forward apropos-all-words-regexp nil t))
914 (progn
915 (goto-char (1+ sepa))
916 (setq type (if (eq ?F (preceding-char))
917 2 ; function documentation
918 3) ; variable documentation
919 symbol (read)
920 doc (buffer-substring (1+ (point)) (1- sepb)))
921 (when (and (apropos-true-hit-doc doc)
922 ;; The DOC file lists all built-in funcs and vars.
923 ;; If any are not currently bound, they can
924 ;; only be platform-specific stuff (eg NS) not
925 ;; in use on the current platform.
926 ;; So we exclude them.
927 (cond ((= 3 type) (boundp symbol))
928 ((= 2 type) (fboundp symbol))))
929 (or (and (setq apropos-item (assq symbol apropos-accumulator))
930 (setcar (cdr apropos-item)
931 (apropos-score-doc doc)))
932 (setq apropos-item (list symbol
933 (+ (apropos-score-symbol symbol 2)
934 (apropos-score-doc doc))
935 nil nil)
936 apropos-accumulator (cons apropos-item
937 apropos-accumulator)))
938 (when apropos-match-face
939 (setq doc (substitute-command-keys doc))
940 (if (or (string-match apropos-pattern-quoted doc)
941 (string-match apropos-all-words-regexp doc))
942 (put-text-property (match-beginning 0)
943 (match-end 0)
944 'face apropos-match-face doc)))
945 (setcar (nthcdr type apropos-item) doc))))
946 (setq sepa (goto-char sepb)))))
948 (defun apropos-documentation-check-elc-file (file)
949 (if (member file apropos-files-scanned)
951 (let (symbol doc beg end this-is-a-variable)
952 (setq apropos-files-scanned (cons file apropos-files-scanned))
953 (erase-buffer)
954 (insert-file-contents file)
955 (while (search-forward "\n#@" nil t)
956 ;; Read the comment length, and advance over it.
957 (setq end (read)
958 beg (1+ (point))
959 end (+ (point) end -1))
960 (forward-char)
961 (if (save-restriction
962 ;; match ^ and $ relative to doc string
963 (narrow-to-region beg end)
964 (re-search-forward apropos-all-words-regexp nil t))
965 (progn
966 (goto-char (+ end 2))
967 (setq doc (buffer-substring beg end)
968 end (- (match-end 0) beg)
969 beg (- (match-beginning 0) beg))
970 (when (apropos-true-hit-doc doc)
971 (setq this-is-a-variable (looking-at "(def\\(var\\|const\\) ")
972 symbol (progn
973 (skip-chars-forward "(a-z")
974 (forward-char)
975 (read))
976 symbol (if (consp symbol)
977 (nth 1 symbol)
978 symbol))
979 (if (if this-is-a-variable
980 (get symbol 'variable-documentation)
981 (and (fboundp symbol) (apropos-safe-documentation symbol)))
982 (progn
983 (or (and (setq apropos-item (assq symbol apropos-accumulator))
984 (setcar (cdr apropos-item)
985 (+ (cadr apropos-item) (apropos-score-doc doc))))
986 (setq apropos-item (list symbol
987 (+ (apropos-score-symbol symbol 2)
988 (apropos-score-doc doc))
989 nil nil)
990 apropos-accumulator (cons apropos-item
991 apropos-accumulator)))
992 (when apropos-match-face
993 (setq doc (substitute-command-keys doc))
994 (if (or (string-match apropos-pattern-quoted doc)
995 (string-match apropos-all-words-regexp doc))
996 (put-text-property (match-beginning 0)
997 (match-end 0)
998 'face apropos-match-face doc)))
999 (setcar (nthcdr (if this-is-a-variable 3 2)
1000 apropos-item)
1001 doc))))))))))
1005 (defun apropos-safe-documentation (function)
1006 "Like `documentation', except it avoids calling `get_doc_string'.
1007 Will return nil instead."
1008 (while (and function (symbolp function))
1009 (setq function (symbol-function function)))
1010 (if (eq (car-safe function) 'macro)
1011 (setq function (cdr function)))
1012 (setq function (if (byte-code-function-p function)
1013 (if (> (length function) 4)
1014 (aref function 4))
1015 (if (autoloadp function)
1016 (nth 2 function)
1017 (if (eq (car-safe function) 'lambda)
1018 (if (stringp (nth 2 function))
1019 (nth 2 function)
1020 (if (stringp (nth 3 function))
1021 (nth 3 function)))))))
1022 (if (integerp function)
1024 function))
1026 (defcustom apropos-compact-layout nil
1027 "If non-nil, use a single line per binding."
1028 :type 'boolean)
1030 (defun apropos-print (do-keys spacing &optional text nosubst)
1031 "Output result of apropos searching into buffer `*Apropos*'.
1032 The value of `apropos-accumulator' is the list of items to output.
1033 Each element should have the format
1034 (SYMBOL SCORE FN-DOC VAR-DOC [PLIST-DOC WIDGET-DOC FACE-DOC GROUP-DOC]).
1035 The return value is the list that was in `apropos-accumulator', sorted
1036 alphabetically by symbol name; but this function also sets
1037 `apropos-accumulator' to nil before returning.
1039 If SPACING is non-nil, it should be a string; separate items with that string.
1040 If non-nil, TEXT is a string that will be printed as a heading."
1041 (if (null apropos-accumulator)
1042 (message "No apropos matches for `%s'" apropos-pattern)
1043 (setq apropos-accumulator
1044 (sort apropos-accumulator
1045 (lambda (a b)
1046 (if apropos-sort-by-scores
1047 (or (> (cadr a) (cadr b))
1048 (and (= (cadr a) (cadr b))
1049 (string-lessp (car a) (car b))))
1050 (string-lessp (car a) (car b))))))
1051 (with-output-to-temp-buffer "*Apropos*"
1052 (let ((p apropos-accumulator)
1053 (old-buffer (current-buffer))
1054 (inhibit-read-only t)
1055 symbol item)
1056 (set-buffer standard-output)
1057 (apropos-mode)
1058 (insert (substitute-command-keys "Type \\[apropos-follow] on ")
1059 (if apropos-multi-type "a type label" "an entry")
1060 " to view its full documentation.\n\n")
1061 (if text (insert text "\n\n"))
1062 (dolist (apropos-item p)
1063 (when (and spacing (not (bobp)))
1064 (princ spacing))
1065 (setq symbol (car apropos-item))
1066 ;; Insert dummy score element for backwards compatibility with 21.x
1067 ;; apropos-item format.
1068 (if (not (numberp (cadr apropos-item)))
1069 (setq apropos-item
1070 (cons (car apropos-item)
1071 (cons nil (cdr apropos-item)))))
1072 (insert-text-button (symbol-name symbol)
1073 'type 'apropos-symbol
1074 'skip apropos-multi-type
1075 'face 'apropos-symbol)
1076 (if (and (eq apropos-sort-by-scores 'verbose)
1077 (cadr apropos-item))
1078 (insert " (" (number-to-string (cadr apropos-item)) ") "))
1079 ;; Calculate key-bindings if we want them.
1080 (unless apropos-compact-layout
1081 (and do-keys
1082 (commandp symbol)
1083 (not (eq symbol 'self-insert-command))
1084 (indent-to 30 1)
1085 (if (let ((keys
1086 (with-current-buffer old-buffer
1087 (where-is-internal symbol)))
1088 filtered)
1089 ;; Copy over the list of key sequences,
1090 ;; omitting any that contain a buffer or a frame.
1091 ;; FIXME: Why omit keys that contain buffers and
1092 ;; frames? This looks like a bad workaround rather
1093 ;; than a proper fix. Does anybody know what problem
1094 ;; this is trying to address? --Stef
1095 (dolist (key keys)
1096 (let ((i 0)
1097 loser)
1098 (while (< i (length key))
1099 (if (or (framep (aref key i))
1100 (bufferp (aref key i)))
1101 (setq loser t))
1102 (setq i (1+ i)))
1103 (or loser
1104 (push key filtered))))
1105 (setq item filtered))
1106 ;; Convert the remaining keys to a string and insert.
1107 (insert
1108 (mapconcat
1109 (lambda (key)
1110 (setq key (condition-case ()
1111 (key-description key)
1112 (error)))
1113 (put-text-property 0 (length key)
1114 'face 'apropos-keybinding
1115 key)
1116 key)
1117 item ", "))
1118 (insert "M-x ... RET")
1119 (put-text-property (- (point) 11) (- (point) 8)
1120 'face 'apropos-keybinding)
1121 (put-text-property (- (point) 3) (point)
1122 'face 'apropos-keybinding)))
1123 (terpri))
1124 (apropos-print-doc 2
1125 (if (commandp symbol)
1126 'apropos-command
1127 (if (macrop symbol)
1128 'apropos-macro
1129 'apropos-function))
1130 (not nosubst))
1131 (apropos-print-doc 3
1132 (if (custom-variable-p symbol)
1133 'apropos-user-option
1134 'apropos-variable)
1135 (not nosubst))
1136 (apropos-print-doc 7 'apropos-group t)
1137 (apropos-print-doc 6 'apropos-face t)
1138 (apropos-print-doc 5 'apropos-widget t)
1139 (apropos-print-doc 4 'apropos-plist nil))
1140 (set (make-local-variable 'truncate-partial-width-windows) t)
1141 (set (make-local-variable 'truncate-lines) t))))
1142 (prog1 apropos-accumulator
1143 (setq apropos-accumulator ()))) ; permit gc
1145 (defun apropos-print-doc (i type do-keys)
1146 (let ((doc (nth i apropos-item)))
1147 (when (stringp doc)
1148 (if apropos-compact-layout
1149 (insert (propertize "\t" 'display '(space :align-to 32)) " ")
1150 (insert " "))
1151 (if apropos-multi-type
1152 (let ((button-face (button-type-get type 'face)))
1153 (unless (consp button-face)
1154 (setq button-face (list button-face)))
1155 (insert-text-button
1156 (if apropos-compact-layout
1157 (format "<%s>" (button-type-get type 'apropos-short-label))
1158 (button-type-get type 'apropos-label))
1159 'type type
1160 'apropos-symbol (car apropos-item))
1161 (insert (if apropos-compact-layout " " ": ")))
1163 ;; If the query is only for a single type, there's no point
1164 ;; writing it over and over again. Insert a blank button, and
1165 ;; put the 'apropos-label property there (needed by
1166 ;; apropos-symbol-button-display-help).
1167 (insert-text-button
1168 " " 'type type 'skip t
1169 'face 'default 'apropos-symbol (car apropos-item)))
1171 (let ((opoint (point))
1172 (ocol (current-column)))
1173 (cond ((equal doc "")
1174 (setq doc "(not documented)"))
1175 (do-keys
1176 (setq doc (substitute-command-keys doc))))
1177 (insert doc)
1178 (if (equal doc "(not documented)")
1179 (put-text-property opoint (point) 'font-lock-face 'shadow))
1180 ;; The labeling buttons might make the line too long, so fill it if
1181 ;; necessary.
1182 (let ((fill-column (+ 5 (if (integerp emacs-lisp-docstring-fill-column)
1183 emacs-lisp-docstring-fill-column
1184 fill-column)))
1185 (fill-prefix (make-string ocol ?\s)))
1186 (fill-region opoint (point) nil t)))
1187 (or (bolp) (terpri)))))
1189 (defun apropos-follow ()
1190 "Invokes any button at point, otherwise invokes the nearest label button."
1191 (interactive)
1192 (button-activate
1193 (or (apropos-next-label-button (line-beginning-position))
1194 (error "There is nothing to follow here"))))
1197 (defun apropos-describe-plist (symbol)
1198 "Display a pretty listing of SYMBOL's plist."
1199 (help-setup-xref (list 'apropos-describe-plist symbol)
1200 (called-interactively-p 'interactive))
1201 (with-help-window (help-buffer)
1202 (set-buffer standard-output)
1203 (princ "Symbol ")
1204 (prin1 symbol)
1205 (princ "'s plist is\n (")
1206 (put-text-property (+ (point-min) 7) (- (point) 14)
1207 'face 'apropos-symbol)
1208 (insert (apropos-format-plist symbol "\n "))
1209 (princ ")")))
1212 (provide 'apropos)
1214 ;;; apropos.el ends here