| blob | 47e44485c627a55165c5b633f4781f74befc5a6b |
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:
63 "Apropos commands for users and programmers."
67 ;; I see a degradation of maybe 10-20% only.
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."
90 "Face for the symbol name in Apropos output."
96 "Face for lists of keybinding in Apropos output."
102 "Face for property name in Apropos output, or nil for none."
108 "Button face indicating a function, macro, or command in Apropos."
114 "Button face indicating a variable in Apropos."
120 "Button face indicating a user option in Apropos."
126 "Button face indicating a miscellaneous object type in Apropos."
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."
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."
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."
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.
163 map)
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
211 "List of synonyms known by apropos.
212 Each element is a list of words where the first word is the standard Emacs
215 \f
216 ;;; Button types used by apropos
221 'follow-link t
225 "Display further help for the `apropos-symbol' button BUTTON."
235 'follow-link t
244 'follow-link t
253 'follow-link t
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'.
267 'follow-link t
276 'follow-link t
285 'follow-link t
294 'follow-link t
304 'follow-link t
313 'follow-link t
319 'follow-link t
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."
343 \f
345 "Make regexp matching any two of the words in WORDS.
346 WILD should be a subexpression matching wildcards between matches."
358 words
361 ;;;###autoload
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."
372 ;; Split into words
375 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'."
383 apropos-all-words nil)
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.
410 apropos-all-words-regexp pattern
411 apropos-pattern pattern
412 apropos-regexp pattern)))
415 "Return apropos scores for string STR matching WORDS.
416 Value is a list of offsets of the words into the string."
422 ;; Return list of start and end position of regexp
427 "Return apropos score for string STR."
436 "Return apropos score for documentation string DOC."
447 "Return apropos score for SYMBOL."
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)."
464 "Return t if SYMBOL is not really matched by the current keywords."
468 "Return t if STR is not really matched by the current keywords."
472 "Return t if DOC is really matched by the current keywords."
476 "Major mode for following hyperlinks in output of apropos commands.
481 "If non-nil, this apropos query concerns multiple types.
484 ;;;###autoload
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.
493 variables, not just user options."
497 current-prefix-arg))
505 ;;;###autoload
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'."
512 current-prefix-arg))
516 ;; For auld lang syne:
517 ;;;###autoload
519 ;;;###autoload
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.
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."
538 current-prefix-arg))
547 ;; We used to use `functionp' here, but this
548 ;; rules out macros. `fboundp' rules in
549 ;; keymaps, but it seems harmless.
558 doc symbol score)
568 ;; Eg alias to undefined function.
570 "(documentation error)"
586 message
590 ;;;###autoload
592 "Like (documentation-property SYMBOL PROPERTY RAW) but handle errors."
600 ;;;###autoload
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.
612 consider all symbols (if they match PATTERN).
614 Returns list of symbols and documentation found."
616 current-prefix-arg))
631 "<nothing>"
637 name)))
639 ;;;###autoload
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."
654 l)))
655 l)
656 libs))
657 libs)))
660 ;; (autoloads nil)
665 ;; `file' may be the "shortname".
676 ;; (autoload (push (cdr x) autoloads))
682 symbols apropos-do-all
685 file
692 ;; Filter out entries that are marked as apropos-inhibit.
703 symbol
731 "Obsolete a"
733 alias)
734 ;; Never happens in practice because fails
735 ;; (facep symbol) test.
742 symbols)))
746 ;;;###autoload
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.
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."
760 current-prefix-arg))
769 apropos-pattern apropos-all-words-regexp
770 apropos-words apropos-all-words
771 do-all apropos-accumulator
772 symbol f v p))
788 f v p)
789 apropos-accumulator))))))
794 ;;;###autoload
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
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.
811 current-prefix-arg))
817 f v sf sv)
846 f v)
847 apropos-accumulator)))))))
851 \f
860 'face apropos-match-face
861 symbol))
862 symbol)))))
877 doc))))
892 'face apropos-match-face
893 p))
896 p-out))
899 ;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
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.
935 nil nil)
937 apropos-accumulator)))
950 nil
956 ;; Read the comment length, and advance over it.
962 ;; match ^ and $ relative to doc string
978 symbol))
989 nil nil)
991 apropos-accumulator)))
1000 apropos-item)
1001 doc))))))))))
1006 "Like `documentation', except it avoids calling `get_doc_string'.
1007 Will return nil instead."
1023 nil
1024 function))
1027 "If non-nil, use a single line per binding."
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."
1055 symbol item)
1066 ;; Insert dummy score element for backwards compatibility with 21.x
1067 ;; apropos-item format.
1074 'skip apropos-multi-type
1079 ;; Calculate key-bindings if we want them.
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
1097 loser)
1106 ;; Convert the remaining keys to a string and insert.
1115 key)
1116 key)
1126 'apropos-command
1128 'apropos-macro
1133 'apropos-user-option
1159 'type type
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).
1180 ;; The labeling buttons might make the line too long, so fill it if
1181 ;; necessary.
1183 emacs-lisp-docstring-fill-column
1184 fill-column)))
1190 "Invokes any button at point, otherwise invokes the nearest label button."
1198 "Display a pretty listing of SYMBOL's plist."
1214 ;;; apropos.el ends here