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