| blob | d3d66f2a0703034a760a2263f663227de0321e9a |
1 ;;; apropos.el --- apropos commands for users and programmers
3 ;; Copyright (C) 1989, 1994-1995, 2001-2011 Free Software Foundation, Inc.
5 ;; Author: Joe Wells <jbw@bigbird.bu.edu>
6 ;; Daniel Pfeiffer <occitan@esperanto.org> (rewrite)
7 ;; Keywords: help
8 ;; Package: emacs
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;; The ideas for this package were derived from the C code in
28 ;; src/keymap.c and elsewhere. The functions in this file should
29 ;; always be byte-compiled for speed. Someone should rewrite this in
30 ;; C (as part of src/keymap.c) for speed.
32 ;; The idea for super-apropos is based on the original implementation
33 ;; by Lynn Slater <lrs@esl.com>.
35 ;; History:
36 ;; Fixed bug, current-local-map can return nil.
37 ;; Change, doesn't calculate key-bindings unless needed.
38 ;; Added super-apropos capability, changed print functions.
39 ;;; Made fast-apropos and super-apropos share code.
40 ;;; Sped up fast-apropos again.
41 ;; Added apropos-do-all option.
42 ;;; Added fast-command-apropos.
43 ;; Changed doc strings to comments for helping functions.
44 ;;; Made doc file buffer read-only, buried it.
45 ;; Only call substitute-command-keys if do-all set.
47 ;; Optionally use configurable faces to make the output more legible.
48 ;; Differentiate between command, function and macro.
49 ;; Apropos-command (ex command-apropos) does cmd and optionally user var.
50 ;; Apropos shows all 3 aspects of symbols (fn, var and plist)
51 ;; Apropos-documentation (ex super-apropos) now finds all it should.
52 ;; New apropos-value snoops through all values and optionally plists.
53 ;; Reading DOC file doesn't load nroff.
54 ;; Added hypertext following of documentation, mouse-2 on variable gives value
55 ;; from buffer in active window.
57 ;;; Code:
63 "Apropos commands for users and programmers."
67 ;; I see a degradation of maybe 10-20% only.
69 "Whether the apropos commands should do more.
71 Slows them down more or less. Set this non-nil if you have a fast machine."
77 "Face for symbol name in Apropos output, or nil for none."
82 "Face for lists of keybinding in Apropos output, or nil for none."
87 "Face for label (`Command', `Variable' ...) in Apropos output.
88 A value of nil means don't use any special font for them, and also
89 turns off mouse highlighting."
94 "Face for property name in apropos output, or nil for none."
99 "Face for matching text in Apropos documentation/value, or nil for none.
100 This applies when you look for matches in the documentation or variable value
101 for the pattern; the part that matches gets displayed in this font."
106 "Non-nil means sort matches by scores; best match is shown first.
107 This applies to all `apropos' commands except `apropos-documentation'.
108 If value is `verbose', the computed score is shown for each match."
115 "Non-nil means sort matches by scores; best match is shown first.
116 This applies to `apropos-documentation' only.
117 If value is `verbose', the computed score is shown for each match."
126 ;; Use `apropos-follow' instead of just using the button
127 ;; definition of RET, so that users can use it anywhere in an
128 ;; apropos item, not just on top of a button.
130 map)
158 "Alist of symbols already found in current apropos run.
159 Each element has the form
161 (SYMBOL SCORE FUN-DOC VAR-DOC PLIST WIDGET-DOC FACE-DOC CUS-GROUP-DOC)
163 where SYMBOL is the symbol name, SCORE is its relevance score (a
164 number), FUN-DOC is the function docstring, VAR-DOC is the
165 variable docstring, PLIST is the list of the symbols names in the
166 property list, WIDGET-DOC is the widget docstring, FACE-DOC is
167 the face docstring, and CUS-GROUP-DOC is the custom group
178 "List of synonyms known by apropos.
179 Each element is a list of words where the first word is the standard Emacs
182 \f
183 ;;; Button types used by apropos
186 'face apropos-symbol-face
188 'follow-link t
192 "Display further help for the `apropos-symbol' button BUTTON."
202 'follow-link t
211 'follow-link t
220 'follow-link t
224 ;; We used to use `customize-variable-other-window' instead for a
225 ;; customizable variable, but that is slow. It is better to show an
226 ;; ordinary help buffer and let the user click on the customization
227 ;; button in that buffer, if he wants to.
228 ;; Likewise for `customize-face-other-window'.
234 'follow-link t
243 'follow-link t
252 'follow-link t
262 'follow-link t
271 'follow-link t
277 'follow-link t
282 "Return the next apropos label button after POS, or nil if there's none.
283 Will also return nil if more than one `apropos-symbol' button is encountered
284 before finding a label."
301 \f
303 "Make regexp matching any two of the words in WORDS."
314 ;;;###autoload
316 "Read an apropos pattern, either a word list or a regexp.
317 Returns the user pattern, either a list of words which are matched
318 literally, or a string which is used as a regexp to search for.
320 SUBJECT is a string that is included in the prompt to identify what
321 kind of objects to search."
325 ;; Split into words
327 pattern)))
330 "Rewrite a list of words to a regexp matching all permutations.
331 If PATTERN is a string, that means it is already a regexp.
332 This updates variables `apropos-pattern', `apropos-pattern-quoted',
333 `apropos-regexp', `apropos-words', and `apropos-all-words-regexp'."
335 apropos-all-words nil)
337 ;; We don't actually make a regexp matching all permutations.
338 ;; Instead, for e.g. "a b c", we make a regexp matching
339 ;; any combination of two or more words like this:
340 ;; (a|b|c).*(a|b|c) which may give some false matches,
341 ;; but as long as it also gives the right ones, that's ok.
362 apropos-all-words-regexp pattern
363 apropos-pattern pattern
364 apropos-regexp pattern)))
368 "Return apropos scores for string STR matching WORDS.
369 Value is a list of offsets of the words into the string."
375 ;; Return list of start and end position of regexp
380 "Return apropos score for string STR."
389 "Return apropos score for documentation string DOC."
400 "Return apropos score for SYMBOL."
408 "Return t if STR is a genuine hit.
409 This may fail if only one of the keywords is matched more than once.
410 This requires that at least 2 keywords (unless only one was given)."
417 "Return t if SYMBOL is not really matched by the current keywords."
421 "Return t if STR is not really matched by the current keywords."
425 "Return t if DOC is really matched by the current keywords."
429 "Major mode for following hyperlinks in output of apropos commands.
434 "If non-nil, this apropos query concerns multiple types.
437 ;;;###autoload
439 "Show user variables that match PATTERN.
440 PATTERN can be a word, a list of words (separated by spaces),
441 or a regexp (using some regexp special characters). If it is a word,
442 search for matches for that word as a substring. If it is a list of words,
443 search for matches for any two (or more) of those words.
446 normal variables."
450 current-prefix-arg))
458 ;; For auld lang syne:
459 ;;;###autoload
461 ;;;###autoload
463 "Show commands (interactively callable functions) that match PATTERN.
464 PATTERN can be a word, a list of words (separated by spaces),
465 or a regexp (using some regexp special characters). If it is a word,
466 search for matches for that word as a substring. If it is a list of words,
467 search for matches for any two (or more) of those words.
470 noninteractive functions.
472 If VAR-PREDICATE is non-nil, show only variables, and only those that
473 satisfy the predicate VAR-PREDICATE.
475 When called from a Lisp program, a string PATTERN is used as a regexp,
476 while a list of strings is used as a word list."
480 current-prefix-arg))
489 ;; We used to use `functionp' here, but this
490 ;; rules out macros. `fboundp' rules in
491 ;; keymaps, but it seems harmless.
500 doc symbol score)
510 ;; Eg alias to undefined function.
512 "(documentation error)"
528 message
532 ;;;###autoload
534 "Like (documentation-property SYMBOL PROPERTY RAW) but handle errors."
542 ;;;###autoload
544 "Show all meaningful Lisp symbols whose names match PATTERN.
545 Symbols are shown if they are defined as functions, variables, or
546 faces, or if they have nonempty property lists.
548 PATTERN can be a word, a list of words (separated by spaces),
549 or a regexp (using some regexp special characters). If it is a word,
550 search for matches for that word as a substring. If it is a list of words,
551 search for matches for any two (or more) of those words.
554 consider all symbols (if they match PATTERN).
556 Returns list of symbols and documentation found."
558 current-prefix-arg))
573 "<nothing>"
577 'face apropos-symbol-face
579 name)))
581 ;;;###autoload
583 "List the variables and functions defined by library FILE.
584 FILE should be one of the libraries currently loaded and should
585 thus be found in `load-history'."
595 l)))
596 l)
597 libs))
598 libs)))
601 ;; (autoloads nil)
606 ;; `file' may be the "shortname".
617 ;; (autoload (push (cdr x) autoloads))
623 symbols apropos-do-all
626 file
633 ;; Filter out entries that are marked as apropos-inhibit.
644 symbol
672 "Obsolete a"
674 alias)
675 ;; Never happens in practice because fails
676 ;; (facep symbol) test.
683 symbols)))
687 ;;;###autoload
689 "Show all symbols whose value's printed representation matches PATTERN.
690 PATTERN can be a word, a list of words (separated by spaces),
691 or a regexp (using some regexp special characters). If it is a word,
692 search for matches for that word as a substring. If it is a list of words,
693 search for matches for any two (or more) of those words.
696 at the function and at the names and values of properties.
697 Returns list of symbols and values found."
699 current-prefix-arg))
708 apropos-pattern apropos-all-words-regexp
709 apropos-words apropos-all-words
710 do-all apropos-accumulator
711 symbol f v p))
727 f v p)
728 apropos-accumulator))))))
733 ;;;###autoload
735 "Show symbols whose documentation contains matches for PATTERN.
736 PATTERN can be a word, a list of words (separated by spaces),
737 or a regexp (using some regexp special characters). If it is a word,
738 search for matches for that word as a substring. If it is a list of words,
739 search for matches for any two (or more) of those words.
742 documentation that is not stored in the documentation file and show key
743 bindings.
744 Returns list of symbols and documentation found."
746 current-prefix-arg))
752 f v sf sv)
781 f v)
782 apropos-accumulator)))))))
786 \f
795 'face apropos-match-face
796 symbol))
797 symbol)))))
812 doc))))
828 'face apropos-match-face
829 p))
832 p-out))
835 ;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
858 ;; The DOC file lists all built-in funcs and vars.
859 ;; If any are not currently bound, they can
860 ;; only be platform-specific stuff (eg NS) not
861 ;; in use on the current platform.
862 ;; So we exclude them.
871 nil nil)
873 apropos-accumulator)))
886 nil
892 ;; Read the comment length, and advance over it.
898 ;; match ^ and $ relative to doc string
914 symbol))
925 nil nil)
927 apropos-accumulator)))
936 apropos-item)
937 doc))))))))))
942 "Like `documentation', except it avoids calling `get_doc_string'.
943 Will return nil instead."
960 nil
961 function))
964 "If non-nil, use a single line per binding."
968 "Output result of apropos searching into buffer `*Apropos*'.
969 The value of `apropos-accumulator' is the list of items to output.
970 Each element should have the format
971 (SYMBOL SCORE FN-DOC VAR-DOC [PLIST-DOC WIDGET-DOC FACE-DOC GROUP-DOC]).
972 The return value is the list that was in `apropos-accumulator', sorted
973 alphabetically by symbol name; but this function also sets
974 `apropos-accumulator' to nil before returning.
976 If SPACING is non-nil, it should be a string; separate items with that string.
977 If non-nil TEXT is a string that will be printed as a heading."
983 ;; Don't sort by score if user can't see the score.
984 ;; It would be confusing. -- rms.
994 symbol item)
1005 ;; Insert dummy score element for backwards compatibility with 21.x
1006 ;; apropos-item format.
1013 'skip apropos-multi-type
1014 ;; Can't use default, since user may have
1015 ;; changed the variable!
1016 ;; Just say `no' to variables containing faces!
1021 ;; Calculate key-bindings if we want them.
1030 filtered)
1031 ;; Copy over the list of key sequences,
1032 ;; omitting any that contain a buffer or a frame.
1033 ;; FIXME: Why omit keys that contain buffers and
1034 ;; frames? This looks like a bad workaround rather
1035 ;; than a proper fix. Does anybod know what problem
1036 ;; this is trying to address? --Stef
1039 loser)
1048 ;; Convert the remaining keys to a string and insert.
1057 'face apropos-keybinding-face
1058 key))
1059 key)
1070 'apropos-command
1072 'apropos-macro
1086 "Return t if SYMBOL is a Lisp macro."
1110 'type type
1111 ;; Can't use the default button face, since user may have changed the
1112 ;; variable! Just say `no' to variables containing faces!
1117 ;; If the query is only for a single type, there's no point
1118 ;; writing it over and over again. Insert a blank button, and
1119 ;; put the 'apropos-label property there (needed by
1120 ;; apropos-symbol-button-display-help).
1134 ;; The labeling buttons might make the line too long, so fill it if
1135 ;; necessary.
1137 emacs-lisp-docstring-fill-column
1138 fill-column)))
1144 "Invokes any button at point, otherwise invokes the nearest label button."
1152 "Display a pretty listing of SYMBOL's plist."
1169 ;;; apropos.el ends here