Mercurial > emacs
annotate lisp/apropos.el @ 1803:5752a95053f2
* xterm.c (x_window_to_scrollbar): Search frames'
condemned_scrollbars list as well; input might arrive during
redisplay.
(x_scrollbar_report_motion): Don't forget to BLOCK_INPUT.
(XTjudge_scrollbars): Clear the condemned scrollbar list before
traversing it, so we don't try to process an event on a scrollbar
we've killed.
author | Jim Blandy <jimb@redhat.com> |
---|---|
date | Sat, 16 Jan 1993 05:58:15 +0000 |
parents | d85a2ab89e09 |
children | 73a56a618d25 |
rev | line source |
---|---|
662
8a533acedb77
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
444
diff
changeset
|
1 ;;; apropos.el --- faster apropos commands. |
8a533acedb77
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
444
diff
changeset
|
2 |
845 | 3 ;; Copyright (C) 1989 Free Software Foundation, Inc. |
4 | |
807
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
5 ;; Author: Joe Wells <jbw@bigbird.bu.edu> |
811
e694e0879463
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
807
diff
changeset
|
6 ;; Keyword: help |
807
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
7 |
367 | 8 ;; This file is part of GNU Emacs. |
9 | |
10 ;; GNU Emacs is free software; you can redistribute it and/or modify | |
11 ;; it under the terms of the GNU General Public License as published by | |
807
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
12 ;; the Free Software Foundation; either version 2, or (at your option) |
367 | 13 ;; any later version. |
14 | |
15 ;; GNU Emacs is distributed in the hope that it will be useful, | |
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 ;; GNU General Public License for more details. | |
19 | |
20 ;; You should have received a copy of the GNU General Public License | |
21 ;; along with GNU Emacs; see the file COPYING. If not, write to | |
22 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
23 | |
807
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
24 ;;; Commentary: |
367 | 25 |
26 ;; The ideas for this package were derived from the C code in | |
27 ;; src/keymap.c and elsewhere. The functions in this file should | |
28 ;; always be byte-compiled for speed. Someone should rewrite this in | |
29 ;; C (as part of src/keymap.c) for speed. | |
30 | |
31 ;; The idea for super-apropos is based on the original implementation | |
32 ;; by Lynn Slater <lrs@esl.com>. | |
33 | |
34 ;; History: | |
35 ;; Fixed bug, current-local-map can return nil. | |
36 ;; Change, doesn't calculate key-bindings unless needed. | |
37 ;; Added super-apropos capability, changed print functions. | |
38 ;; Made fast-apropos and super-apropos share code. | |
39 ;; Sped up fast-apropos again. | |
40 ;; Added apropos-do-all option. | |
41 ;; Added fast-command-apropos. | |
42 ;; Changed doc strings to comments for helping functions. | |
43 ;; Made doc file buffer read-only, buried it. | |
44 ;; Only call substitute-command-keys if do-all set. | |
45 | |
807
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
46 ;;; Code: |
4f28bd14272c
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
662
diff
changeset
|
47 |
367 | 48 (defvar apropos-do-all nil |
49 "*Whether `apropos' and `super-apropos' should do everything that they can. | |
50 Makes them run 2 or 3 times slower. Set this non-nil if you have a fast | |
51 machine.") | |
52 | |
53 ;; If there isn't already a lisp variable named internal-doc-file-name, create | |
54 ;; it and document it. This is so the code will work right after RMS adds | |
55 ;; internal-doc-file-name. | |
56 ;(or (boundp 'internal-doc-file-name) | |
444 | 57 ; (setq internal-doc-file-name (concat data-directory "DOC"))) |
367 | 58 ;(or (documentation-property 'internal-doc-file-name 'variable-documentation) |
59 ; (put 'internal-doc-file-name 'variable-documentation | |
60 ; "The complete pathname of the documentation file that contains all | |
61 ;documentation for functions and variables defined before Emacs is dumped.")) | |
62 | |
63 ;;;###autoload | |
64 (defun apropos (regexp &optional do-all pred) | |
65 "Show all symbols whose names contain matches for REGEXP. | |
66 If optional argument DO-ALL is non-nil, does more (time-consuming) work such as | |
67 showing key bindings. Optional argument PRED is called with each symbol, and | |
68 if it returns nil, the symbol is not shown. | |
69 | |
70 Returns list of symbols and documentation found." | |
71 (interactive "sApropos (regexp): \nP") | |
72 (setq do-all (or apropos-do-all do-all)) | |
73 (let ((apropos-accumulate (apropos-internal regexp pred))) | |
74 (if (null apropos-accumulate) | |
75 (message "No apropos matches for `%s'" regexp) | |
76 (apropos-get-doc apropos-accumulate) | |
77 (with-output-to-temp-buffer "*Help*" | |
78 (apropos-print-matches apropos-accumulate regexp nil do-all))) | |
79 apropos-accumulate)) | |
80 | |
81 ;; If "C-h a" still has its original binding of command-apropos, change it to | |
82 ;; use fast-command-apropos. I don't use substitute-key-definition because | |
83 ;; it's slow. | |
84 ;(if (eq 'command-apropos (lookup-key help-map "a")) | |
85 ; (define-key help-map "a" 'fast-command-apropos)) | |
86 | |
87 ;; Takes LIST of symbols and adds documentation. Modifies LIST in place. | |
88 ;; Resulting alist is of form ((symbol fn-doc var-doc) ...). Should only be | |
89 ;; called by apropos. Returns LIST. | |
90 | |
91 (defun apropos-get-doc (list) | |
92 (let ((p list) | |
93 fn-doc var-doc symbol) | |
94 (while (consp p) | |
95 (setq symbol (car p) | |
96 fn-doc (and (fboundp symbol) | |
97 (documentation symbol)) | |
98 var-doc (documentation-property symbol 'variable-documentation) | |
99 fn-doc (and fn-doc | |
100 (substring fn-doc 0 (string-match "\n" fn-doc))) | |
101 var-doc (and var-doc | |
102 (substring var-doc 0 (string-match "\n" var-doc)))) | |
103 (setcar p (list symbol fn-doc var-doc)) | |
104 (setq p (cdr p))) | |
105 list)) | |
106 | |
107 ;;;###autoload | |
108 (defun super-apropos (regexp &optional do-all) | |
109 "Show symbols whose names/documentation contain matches for REGEXP. | |
110 If optional argument DO-ALL is non-nil, does more (time-consuming) work such as | |
111 showing key bindings and documentation that is not stored in the documentation | |
112 file. | |
113 | |
114 Returns list of symbols and documentation found." | |
115 (interactive "sSuper Apropos: \nP") | |
116 (setq do-all (or apropos-do-all do-all)) | |
117 (let (apropos-accumulate fn-doc var-doc item) | |
118 (setq apropos-accumulate (super-apropos-check-doc-file regexp)) | |
119 (if (null apropos-accumulate) | |
120 (message "No apropos matches for `%s'" regexp) | |
121 (if do-all (mapatoms 'super-apropos-accumulate)) | |
122 (with-output-to-temp-buffer "*Help*" | |
123 (apropos-print-matches apropos-accumulate nil t do-all))) | |
124 apropos-accumulate)) | |
125 | |
126 ;; Finds all documentation related to REGEXP in internal-doc-file-name. | |
127 ;; Returns an alist of form ((symbol fn-doc var-doc) ...). | |
128 | |
129 (defun super-apropos-check-doc-file (regexp) | |
130 (let ((doc-buffer (find-file-noselect internal-doc-file-name t)) | |
131 ;; (doc-buffer (or (get-file-buffer internal-doc-file-name) | |
132 ;; (find-file-noselect internal-doc-file-name))) | |
133 type symbol doc sym-list) | |
134 (save-excursion | |
135 (set-buffer doc-buffer) | |
136 ;; a user said he might accidentally edit the doc file | |
137 (setq buffer-read-only t) | |
138 (bury-buffer doc-buffer) | |
139 (goto-char (point-min)) | |
140 (while (re-search-forward regexp nil t) | |
141 (search-backward "\C-_") | |
142 (setq type (if (eq ?F (char-after (1+ (point)))) | |
143 1 ;function documentation | |
144 2) ;variable documentation | |
145 symbol (progn | |
146 (forward-char 2) | |
147 (read doc-buffer)) | |
148 doc (buffer-substring | |
149 (point) | |
150 (progn | |
151 (if (search-forward "\C-_" nil 'move) | |
152 (1- (point)) | |
153 (point)))) | |
154 item (assq symbol sym-list)) | |
155 (or item | |
156 (setq item (list symbol nil nil) | |
157 sym-list (cons item sym-list))) | |
158 (setcar (nthcdr type item) doc))) | |
159 sym-list)) | |
160 | |
161 ;; This is passed as the argument to map-atoms, so it is called once for every | |
162 ;; symbol in obarray. Takes one argument SYMBOL, and finds any memory-resident | |
163 ;; documentation on that symbol if it matches a variable regexp. WARNING: this | |
164 ;; function depends on the symbols fn-doc var-doc regexp and item being bound | |
165 ;; correctly when it is called!" | |
166 | |
167 (defun super-apropos-accumulate (symbol) | |
168 (cond ((string-match regexp (symbol-name symbol)) | |
169 (setq item (apropos-get-accum-item symbol)) | |
170 (setcar (cdr item) (or (safe-documentation symbol) | |
171 (nth 1 item))) | |
172 (setcar (nthcdr 2 item) (or (safe-documentation-property symbol) | |
173 (nth 2 item)))) | |
174 (t | |
175 (and (setq fn-doc (safe-documentation symbol)) | |
176 (string-match regexp fn-doc) | |
177 (setcar (cdr (apropos-get-accum-item symbol)) fn-doc)) | |
178 (and (setq var-doc (safe-documentation-property symbol)) | |
179 (string-match regexp var-doc) | |
180 (setcar (nthcdr 2 (apropos-get-accum-item symbol)) var-doc)))) | |
181 nil) | |
182 | |
183 ;; Prints the symbols and documentation in alist MATCHES of form ((symbol | |
184 ;; fn-doc var-doc) ...). Uses optional argument REGEXP to speed up searching | |
185 ;; for keybindings. The names of all symbols in MATCHES must match REGEXP. | |
186 ;; Displays in the buffer pointed to by standard-output. Optional argument | |
187 ;; SPACING means put blank lines in between each symbol's documentation. | |
188 ;; Optional argument DO-ALL means do more time-consuming work, specifically, | |
189 ;; consulting key bindings. Should only be called within a | |
190 ;; with-output-to-temp-buffer. | |
191 | |
192 (defun apropos-print-matches (matches &optional regexp spacing do-all) | |
193 (setq matches (sort matches (function | |
194 (lambda (a b) | |
195 (string-lessp (car a) (car b)))))) | |
196 (let ((p matches) | |
197 (old-buffer (current-buffer)) | |
198 item keys-done symbol) | |
199 (save-excursion | |
200 (set-buffer standard-output) | |
201 (or matches (princ "No matches found.")) | |
202 (while (consp p) | |
203 (setq item (car p) | |
204 symbol (car item) | |
205 p (cdr p)) | |
206 (or (not spacing) (bobp) (terpri)) | |
207 (princ symbol) ;print symbol name | |
208 ;; don't calculate key-bindings unless needed | |
209 (cond ((and do-all (commandp symbol) (not keys-done)) | |
210 (save-excursion | |
211 (set-buffer old-buffer) | |
212 (apropos-match-keys matches regexp)) | |
213 (setq keys-done t))) | |
214 (cond ((and do-all | |
215 (or (setq tem (nthcdr 3 item)) | |
216 (commandp symbol))) | |
217 (indent-to 30 1) | |
218 (if tem | |
219 (princ (mapconcat 'key-description tem ", ")) | |
220 (princ "(not bound to any keys)")))) | |
221 (terpri) | |
222 (cond ((setq tem (nth 1 item)) | |
223 (princ " Function: ") | |
224 (princ (if do-all (substitute-command-keys tem) tem)))) | |
225 (or (bolp) (terpri)) | |
226 (cond ((setq tem (nth 2 item)) | |
227 (princ " Variable: ") | |
228 (princ (if do-all (substitute-command-keys tem) tem)))) | |
229 (or (bolp) (terpri))))) | |
230 t) | |
231 | |
232 ;; Find key bindings for symbols that are cars in ALIST. Optionally, first | |
233 ;; match the symbol name against REGEXP. Modifies ALIST in place. Each key | |
234 ;; binding is added as a string to the end of the list in ALIST whose car is | |
235 ;; the corresponding symbol. The pointer to ALIST is returned. | |
236 | |
237 (defun apropos-match-keys (alist &optional regexp) | |
238 (let* ((current-local-map (current-local-map)) | |
239 (maps (append (and current-local-map | |
240 (accessible-keymaps current-local-map)) | |
241 (accessible-keymaps (current-global-map)))) | |
242 map ;map we are now inspecting | |
243 sequence ;key sequence to reach map | |
244 i ;index into vector map | |
245 command ;what is bound to current keys | |
246 key ;last key to reach command | |
247 local ;local binding for sequence + key | |
248 item) ;symbol data item in alist | |
249 ;; examine all reachable keymaps | |
250 (while (consp maps) | |
251 (setq map (cdr (car maps)) | |
252 sequence (car (car maps)) ;keys to reach this map | |
253 maps (cdr maps)) | |
254 (setq i 0) | |
255 ;; In an alist keymap, skip the leading `keymap', doc string, etc. | |
256 (while (and (consp map) (not (consp (car map)))) | |
257 (setq map (cdr map))) | |
258 (while (and map (< i 128)) ;vector keymaps have 128 entries | |
259 (cond ((consp map) | |
260 (setq command (cdr (car map)) | |
261 key (car (car map)) | |
262 map (cdr map)) | |
263 ;; Skip any atoms in the keymap. | |
264 (while (and (consp map) (not (consp (car map)))) | |
265 (setq map (cdr map)))) | |
266 ((vectorp map) | |
267 (setq command (aref map i) | |
268 key i | |
269 i (1+ i)))) | |
270 ;; Skip any menu prompt in this key binding. | |
271 (and (consp command) (symbolp (cdr command)) | |
272 (setq command (cdr command))) | |
273 ;; if is a symbol, and matches optional regexp, and is a car | |
274 ;; in alist, and is not shadowed by a different local binding, | |
275 ;; record it | |
276 (and (symbolp command) | |
277 (if regexp (string-match regexp (symbol-name command))) | |
278 (setq item (assq command alist)) | |
1734
d85a2ab89e09
(apropos-match-keys): Handle non-chars as keys.
Richard M. Stallman <rms@gnu.org>
parents:
845
diff
changeset
|
279 (if (or (vectorp sequence) (not (integerp key))) |
d85a2ab89e09
(apropos-match-keys): Handle non-chars as keys.
Richard M. Stallman <rms@gnu.org>
parents:
845
diff
changeset
|
280 (setq key (vconcat sequence (vector key))) |
d85a2ab89e09
(apropos-match-keys): Handle non-chars as keys.
Richard M. Stallman <rms@gnu.org>
parents:
845
diff
changeset
|
281 (setq key (concat sequence (char-to-string key)))) |
367 | 282 ;; checking if shadowed by local binding. |
283 ;; either no local map, no local binding, or runs off the | |
284 ;; binding tree (number), or is the same binding | |
285 (or (not current-local-map) | |
286 (not (setq local (lookup-key current-local-map key))) | |
287 (numberp local) | |
288 (eq command local)) | |
289 ;; add this key binding to the item in alist | |
290 (nconc item (cons key nil)))))) | |
291 alist) | |
292 | |
293 ;; Get an alist item in alist apropos-accumulate whose car is SYMBOL. Creates | |
294 ;; the item if not already present. Modifies apropos-accumulate in place. | |
295 | |
296 (defun apropos-get-accum-item (symbol) | |
297 (or (assq symbol apropos-accumulate) | |
298 (progn | |
299 (setq apropos-accumulate | |
300 (cons (list symbol nil nil) apropos-accumulate)) | |
301 (assq symbol apropos-accumulate)))) | |
302 | |
303 (defun safe-documentation (function) | |
304 "Like documentation, except it avoids calling `get_doc_string'. | |
305 Will return nil instead." | |
306 (while (symbolp function) | |
307 (setq function (if (fboundp function) | |
308 (symbol-function function) | |
309 0))) | |
310 (if (not (consp function)) | |
311 nil | |
312 (if (eq (car function) 'macro) | |
313 (setq function (cdr function))) | |
314 (if (not (memq (car function) '(lambda autoload))) | |
315 nil | |
316 (setq function (nth 2 function)) | |
317 (if (stringp function) | |
318 function | |
319 nil)))) | |
320 | |
321 (defun safe-documentation-property (symbol) | |
322 "Like documentation-property, except it avoids calling `get_doc_string'. | |
323 Will return nil instead." | |
324 (setq symbol (get symbol 'variable-documentation)) | |
325 (if (numberp symbol) | |
326 nil | |
327 symbol)) | |
328 | |
662
8a533acedb77
*** empty log message ***
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
444
diff
changeset
|
329 ;;; apropos.el ends here |