| blob | 5f481f54e57e68a58932cccbd3859e5d2dc6d546 |
1 ;;; apropos.el --- apropos commands for users and programmers
3 ;; Copyright (C) 1989, 1994-1995, 2001-2013 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-variable' will search all variables, not just user variables.
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 miscellaneous object type in Apropos."
125 "Face for matching text in Apropos documentation/value, or nil for none.
126 This applies when you look for matches in the documentation or variable value
127 for the pattern; the part that matches gets displayed in this font."
132 "Non-nil means sort matches by scores; best match is shown first.
133 This applies to all `apropos' commands except `apropos-documentation'.
134 If value is `verbose', the computed score is shown for each match."
141 "Non-nil means sort matches by scores; best match is shown first.
142 This applies to `apropos-documentation' only.
143 If value is `verbose', the computed score is shown for each match."
152 ;; Use `apropos-follow' instead of just using the button
153 ;; definition of RET, so that users can use it anywhere in an
154 ;; apropos item, not just on top of a button.
156 map)
184 "Alist of symbols already found in current apropos run.
185 Each element has the form
187 (SYMBOL SCORE FUN-DOC VAR-DOC PLIST WIDGET-DOC FACE-DOC CUS-GROUP-DOC)
189 where SYMBOL is the symbol name, SCORE is its relevance score (a
190 number), FUN-DOC is the function docstring, VAR-DOC is the
191 variable docstring, PLIST is the list of the symbols names in the
192 property list, WIDGET-DOC is the widget docstring, FACE-DOC is
193 the face docstring, and CUS-GROUP-DOC is the custom group
204 "List of synonyms known by apropos.
205 Each element is a list of words where the first word is the standard Emacs
208 \f
209 ;;; Button types used by apropos
214 'follow-link t
218 "Display further help for the `apropos-symbol' button BUTTON."
228 'follow-link t
237 'follow-link t
246 'follow-link t
250 ;; We used to use `customize-variable-other-window' instead for a
251 ;; customizable variable, but that is slow. It is better to show an
252 ;; ordinary help buffer and let the user click on the customization
253 ;; button in that buffer, if he wants to.
254 ;; Likewise for `customize-face-other-window'.
260 'follow-link t
269 'follow-link t
278 'follow-link t
288 'follow-link t
297 'follow-link t
303 'follow-link t
308 "Return the next apropos label button after POS, or nil if there's none.
309 Will also return nil if more than one `apropos-symbol' button is encountered
310 before finding a label."
327 \f
329 "Make regexp matching any two of the words in WORDS."
340 ;;;###autoload
342 "Read an apropos pattern, either a word list or a regexp.
343 Returns the user pattern, either a list of words which are matched
344 literally, or a string which is used as a regexp to search for.
346 SUBJECT is a string that is included in the prompt to identify what
347 kind of objects to search."
351 ;; Split into words
353 pattern)))
356 "Rewrite a list of words to a regexp matching all permutations.
357 If PATTERN is a string, that means it is already a regexp.
358 This updates variables `apropos-pattern', `apropos-pattern-quoted',
359 `apropos-regexp', `apropos-words', and `apropos-all-words-regexp'."
361 apropos-all-words nil)
363 ;; We don't actually make a regexp matching all permutations.
364 ;; Instead, for e.g. "a b c", we make a regexp matching
365 ;; any combination of two or more words like this:
366 ;; (a|b|c).*(a|b|c) which may give some false matches,
367 ;; but as long as it also gives the right ones, that's ok.
388 apropos-all-words-regexp pattern
389 apropos-pattern pattern
390 apropos-regexp pattern)))
394 "Return apropos scores for string STR matching WORDS.
395 Value is a list of offsets of the words into the string."
401 ;; Return list of start and end position of regexp
406 "Return apropos score for string STR."
415 "Return apropos score for documentation string DOC."
426 "Return apropos score for SYMBOL."
434 "Return t if STR is a genuine hit.
435 This may fail if only one of the keywords is matched more than once.
436 This requires that at least 2 keywords (unless only one was given)."
443 "Return t if SYMBOL is not really matched by the current keywords."
447 "Return t if STR is not really matched by the current keywords."
451 "Return t if DOC is really matched by the current keywords."
455 "Major mode for following hyperlinks in output of apropos commands.
460 "If non-nil, this apropos query concerns multiple types.
463 ;;;###autoload
465 "Show user variables that match PATTERN.
466 PATTERN can be a word, a list of words (separated by spaces),
467 or a regexp (using some regexp special characters). If it is a word,
468 search for matches for that word as a substring. If it is a list of words,
469 search for matches for any two (or more) of those words.
472 normal variables."
476 current-prefix-arg))
484 ;; For auld lang syne:
485 ;;;###autoload
487 ;;;###autoload
489 "Show commands (interactively callable functions) that match PATTERN.
490 PATTERN can be a word, a list of words (separated by spaces),
491 or a regexp (using some regexp special characters). If it is a word,
492 search for matches for that word as a substring. If it is a list of words,
493 search for matches for any two (or more) of those words.
496 noninteractive functions.
498 If VAR-PREDICATE is non-nil, show only variables, and only those that
499 satisfy the predicate VAR-PREDICATE.
501 When called from a Lisp program, a string PATTERN is used as a regexp,
502 while a list of strings is used as a word list."
506 current-prefix-arg))
515 ;; We used to use `functionp' here, but this
516 ;; rules out macros. `fboundp' rules in
517 ;; keymaps, but it seems harmless.
526 doc symbol score)
536 ;; Eg alias to undefined function.
538 "(documentation error)"
554 message
558 ;;;###autoload
560 "Like (documentation-property SYMBOL PROPERTY RAW) but handle errors."
568 ;;;###autoload
570 "Show all meaningful Lisp symbols whose names match PATTERN.
571 Symbols are shown if they are defined as functions, variables, or
572 faces, or if they have nonempty property lists.
574 PATTERN can be a word, a list of words (separated by spaces),
575 or a regexp (using some regexp special characters). If it is a word,
576 search for matches for that word as a substring. If it is a list of words,
577 search for matches for any two (or more) of those words.
580 consider all symbols (if they match PATTERN).
582 Returns list of symbols and documentation found."
584 current-prefix-arg))
599 "<nothing>"
605 name)))
607 ;;;###autoload
609 "List the variables and functions defined by library FILE.
610 FILE should be one of the libraries currently loaded and should
611 thus be found in `load-history'. If `apropos-do-all' is non-nil,
612 the output includes key-bindings of commands."
622 l)))
623 l)
624 libs))
625 libs)))
628 ;; (autoloads nil)
633 ;; `file' may be the "shortname".
644 ;; (autoload (push (cdr x) autoloads))
650 symbols apropos-do-all
653 file
660 ;; Filter out entries that are marked as apropos-inhibit.
671 symbol
699 "Obsolete a"
701 alias)
702 ;; Never happens in practice because fails
703 ;; (facep symbol) test.
710 symbols)))
714 ;;;###autoload
716 "Show all symbols whose value's printed representation matches PATTERN.
717 PATTERN can be a word, a list of words (separated by spaces),
718 or a regexp (using some regexp special characters). If it is a word,
719 search for matches for that word as a substring. If it is a list of words,
720 search for matches for any two (or more) of those words.
723 at function definitions (arguments, documentation and body) and at the
724 names and values of properties.
726 Returns list of symbols and values found."
728 current-prefix-arg))
737 apropos-pattern apropos-all-words-regexp
738 apropos-words apropos-all-words
739 do-all apropos-accumulator
740 symbol f v p))
756 f v p)
757 apropos-accumulator))))))
762 ;;;###autoload
764 "Show symbols whose documentation contains matches for PATTERN.
765 PATTERN can be a word, a list of words (separated by spaces),
766 or a regexp (using some regexp special characters). If it is a word,
767 search for matches for that word as a substring. If it is a list of words,
768 search for matches for any two (or more) of those words.
770 Note that by default this command only searches in the file specified by
772 or if `apropos-do-all' is non-nil, it searches all currently defined
773 documentation strings.
775 Returns list of symbols and documentation found."
776 ;; The doc used to say that DO-ALL includes key-bindings info in the
777 ;; output, but I cannot see that that is true.
779 current-prefix-arg))
785 f v sf sv)
814 f v)
815 apropos-accumulator)))))))
819 \f
828 'face apropos-match-face
829 symbol))
830 symbol)))))
845 doc))))
860 'face apropos-match-face
861 p))
864 p-out))
867 ;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
890 ;; The DOC file lists all built-in funcs and vars.
891 ;; If any are not currently bound, they can
892 ;; only be platform-specific stuff (eg NS) not
893 ;; in use on the current platform.
894 ;; So we exclude them.
903 nil nil)
905 apropos-accumulator)))
918 nil
924 ;; Read the comment length, and advance over it.
930 ;; match ^ and $ relative to doc string
946 symbol))
957 nil nil)
959 apropos-accumulator)))
968 apropos-item)
969 doc))))))))))
974 "Like `documentation', except it avoids calling `get_doc_string'.
975 Will return nil instead."
992 nil
993 function))
996 "If non-nil, use a single line per binding."
1000 "Output result of apropos searching into buffer `*Apropos*'.
1001 The value of `apropos-accumulator' is the list of items to output.
1002 Each element should have the format
1003 (SYMBOL SCORE FN-DOC VAR-DOC [PLIST-DOC WIDGET-DOC FACE-DOC GROUP-DOC]).
1004 The return value is the list that was in `apropos-accumulator', sorted
1005 alphabetically by symbol name; but this function also sets
1006 `apropos-accumulator' to nil before returning.
1008 If SPACING is non-nil, it should be a string; separate items with that string.
1009 If non-nil TEXT is a string that will be printed as a heading."
1015 ;; Don't sort by score if user can't see the score.
1016 ;; It would be confusing. -- rms.
1026 symbol item)
1037 ;; Insert dummy score element for backwards compatibility with 21.x
1038 ;; apropos-item format.
1045 'skip apropos-multi-type
1050 ;; Calculate key-bindings if we want them.
1059 filtered)
1060 ;; Copy over the list of key sequences,
1061 ;; omitting any that contain a buffer or a frame.
1062 ;; FIXME: Why omit keys that contain buffers and
1063 ;; frames? This looks like a bad workaround rather
1064 ;; than a proper fix. Does anybody know what problem
1065 ;; this is trying to address? --Stef
1068 loser)
1077 ;; Convert the remaining keys to a string and insert.
1086 key)
1087 key)
1097 'apropos-command
1099 'apropos-macro
1113 "Return t if SYMBOL is a Lisp macro."
1137 'type type
1141 ;; If the query is only for a single type, there's no point
1142 ;; writing it over and over again. Insert a blank button, and
1143 ;; put the 'apropos-label property there (needed by
1144 ;; apropos-symbol-button-display-help).
1158 ;; The labeling buttons might make the line too long, so fill it if
1159 ;; necessary.
1161 emacs-lisp-docstring-fill-column
1162 fill-column)))
1168 "Invokes any button at point, otherwise invokes the nearest label button."
1176 "Display a pretty listing of SYMBOL's plist."
1192 ;;; apropos.el ends here