Commit | Line | Data |
---|---|---|
2c989468 RS |
1 | ;;; libc.el -- lookup C symbols in the GNU C Library Reference Manual. |
2 | ||
1275407e | 3 | ;; Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc. |
2c989468 RS |
4 | |
5 | ;;; Author: Ralph Schleicher <rs@purple.UL.BaWue.DE> | |
6 | ;;; Keywords: local c info | |
7 | ||
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 | |
12 | ;; the Free Software Foundation; either version 2, or (at your option) | |
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 the | |
22 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
23 | ;; Boston, MA 02111-1307, USA. | |
24 | ||
25 | ;;; Commentary: | |
26 | ||
27 | ;; This code has a long history. It started as a minor | |
28 | ;; mode for C mode. This era ended with the release of version 2 | |
29 | ;; of the GNU C Library in 1997. The code was therefore rewritten | |
30 | ;; more or less from scratch so that all lookups are performed via | |
31 | ;; indices. Not finding an existing symbol in an index means that | |
32 | ;; there is an error in the manual. Long missed features like a | |
33 | ;; separate input history, symbol name completion in the mini-buffer, | |
34 | ;; highlighting of looked up symbol names in the Info buffer, and | |
35 | ;; implicitly prepending `struct', `union' or `enum' to data types | |
36 | ;; were added in this phase too. | |
37 | ||
38 | ;;; Code: | |
39 | ||
40 | (require 'info) | |
41 | ||
42 | \f | |
43 | (defvar libc-info-file-name "libc" | |
44 | "Basename of the Info file of the GNU C Library Reference Manual.") | |
45 | ||
46 | (defvar libc-highlight-face 'highlight | |
63f125ee | 47 | "*Face for highlighting looked up symbol names in the Info buffer. |
2c989468 RS |
48 | `nil' disables highlighting.") |
49 | ||
63f125ee RS |
50 | (defvar libc-highlight-overlay nil |
51 | "Overlay object used for highlighting.") | |
52 | ||
2c989468 RS |
53 | (defconst libc-symbol-completions nil |
54 | "Alist of documented C symbols.") | |
55 | ||
56 | (defconst libc-file-completions nil | |
57 | "Alist of documented programs or files.") | |
58 | ||
59 | (defvar libc-history nil | |
60 | "History of previous input lines.") | |
61 | ||
62 | ;;;###autoload | |
63 | (defun libc-describe-symbol (symbol-name) | |
64 | "Display the documentation of a C symbol in another window. | |
65 | SYMBOL-NAME must be documented in the GNU C Library Reference Manual. | |
66 | ||
67 | If called interactively, SYMBOL-NAME will be read from the mini-buffer. | |
68 | Optional prefix argument means insert the default symbol (if any) into | |
69 | the mini-buffer so that it can be edited. The default symbol is the | |
70 | one found at point. | |
71 | ||
72 | If SYMBOL-NAME is a public function, variable, or data type of the GNU | |
73 | C Library but `libc-describe-symbol' fails to display it's documentation, | |
74 | then you have found a bug in the manual. Please report that to the mail | |
75 | address `bug-glibc-manual@prep.ai.mit.edu' so that it can be fixed." | |
76 | (interactive | |
77 | (let* ((completion-ignore-case nil) | |
78 | (enable-recursive-minibuffers t) | |
79 | (symbol (libc-symbol-at-point)) | |
80 | (value (completing-read | |
81 | (if symbol | |
82 | (format "Describe symbol (default %s): " symbol) | |
83 | (format "Describe symbol: ")) | |
84 | libc-symbol-completions nil nil | |
85 | (and current-prefix-arg symbol) 'libc-history))) | |
86 | (list (if (equal value "") symbol value)))) | |
87 | (or (assoc symbol-name libc-symbol-completions) | |
88 | (error "Not documented as a C symbol: %s" (or symbol-name ""))) | |
89 | (or (libc-lookup-function symbol-name) | |
90 | (libc-lookup-variable symbol-name) | |
91 | (libc-lookup-type symbol-name))) | |
92 | ||
93 | ;;;###autoload | |
94 | (defun libc-describe-file (file-name) | |
95 | "Display the documentation of a program or file in another window. | |
96 | FILE-NAME must be documented in the GNU C Library Reference Manual." | |
97 | (interactive | |
98 | (let* ((completion-ignore-case nil) | |
99 | (enable-recursive-minibuffers t)) | |
100 | (list (completing-read | |
101 | "Describe program or file: " | |
102 | libc-file-completions nil nil nil 'libc-history)))) | |
103 | (or (assoc file-name libc-file-completions) | |
104 | (error "Not documented as a program or file: %s" (or file-name ""))) | |
105 | (libc-lookup-file file-name)) | |
106 | ||
107 | ;;;###autoload | |
108 | (defun libc-search (regexp &optional arg) | |
109 | "Search in the GNU C Library Reference Manual for REGEXP. | |
110 | Prefix argument means search should ignore case." | |
111 | (interactive "sSearch `libc.info' for regexp: \nP") | |
112 | (or (get-buffer "*info*") | |
113 | (save-window-excursion | |
114 | (info))) | |
115 | (switch-to-buffer-other-window "*info*") | |
116 | (Info-goto-node (concat "(" libc-info-file-name ")")) | |
117 | (let ((case-fold-search arg)) | |
118 | (Info-search regexp))) | |
119 | ||
120 | \f | |
121 | (defun libc-make-completion-alist (info-nodes &optional regexp) | |
122 | "Create a unique alist from all menu items in the Info nodes INFO-NODES | |
123 | of the GNU C Reference Manual. | |
124 | ||
125 | Optional second argument REGEXP means include only menu items matching the | |
126 | regular expression REGEXP." | |
127 | (condition-case nil | |
128 | (let (completions item) | |
129 | (save-window-excursion | |
130 | (info libc-info-file-name) | |
131 | (while info-nodes | |
132 | (Info-goto-node (car info-nodes)) | |
133 | (goto-char (point-min)) | |
134 | (and (search-forward "\n* Menu:" nil t) | |
135 | (while (re-search-forward "\n\\* \\([^:\t\n]*\\):" nil t) | |
136 | (setq item (buffer-substring | |
137 | (match-beginning 1) (match-end 1))) | |
138 | (and (not (assoc item completions)) | |
139 | (if regexp (string-match regexp item) t) | |
140 | (setq completions (cons (cons item nil) | |
141 | completions))))) | |
142 | (setq info-nodes (cdr info-nodes))) | |
143 | (Info-directory)) | |
144 | completions) | |
145 | (error nil))) | |
146 | ||
147 | (defun libc-after-manual-update () | |
148 | "This function must only be called after a new version of the | |
149 | GNU C Library Reference Manual was installed on your system." | |
150 | (setq libc-symbol-completions (libc-make-completion-alist | |
151 | '("Function Index" | |
152 | "Variable Index" | |
153 | "Type Index")) | |
154 | libc-file-completions (libc-make-completion-alist | |
155 | '("File Index") "^[^ \t]+$"))) | |
156 | ||
157 | (or (and libc-symbol-completions | |
158 | libc-file-completions) | |
159 | (libc-after-manual-update)) | |
160 | ||
161 | (defun libc-symbol-at-point () | |
162 | "Get the C symbol at point." | |
163 | (condition-case nil | |
164 | (save-excursion | |
165 | (backward-sexp) | |
166 | (let ((start (point)) | |
167 | prefix name) | |
168 | ;; Test for a leading `struct', `union', or `enum' keyword | |
169 | ;; but ignore names like `foo_struct'. | |
170 | (setq prefix (and (< (skip-chars-backward " \t\n") 0) | |
171 | (< (skip-chars-backward "_a-zA-Z0-9") 0) | |
172 | (looking-at "\\(struct\\|union\\|enum\\)\\s ") | |
173 | (concat (buffer-substring | |
174 | (match-beginning 1) (match-end 1)) | |
175 | " "))) | |
176 | (goto-char start) | |
177 | (and (looking-at "[_a-zA-Z][_a-zA-Z0-9]*") | |
178 | (setq name (buffer-substring | |
179 | (match-beginning 0) (match-end 0)))) | |
180 | ;; Caveat! Look forward if point is at `struct' etc. | |
181 | (and (not prefix) | |
182 | (or (string-equal name "struct") | |
183 | (string-equal name "union") | |
184 | (string-equal name "enum")) | |
185 | (looking-at "[a-z]+\\s +\\([_a-zA-Z][_a-zA-Z0-9]*\\)") | |
186 | (setq prefix (concat name " ") | |
187 | name (buffer-substring | |
188 | (match-beginning 1) (match-end 1)))) | |
189 | (and (or prefix name) | |
190 | (concat prefix name)))) | |
191 | (error nil))) | |
192 | ||
193 | (defun libc-lookup-function (function) | |
194 | (libc-search-index "Function Index" function | |
195 | "^[ \t]+- \\(Function\\|Macro\\): .*\\<" "\\>")) | |
196 | ||
197 | (defun libc-lookup-variable (variable) | |
198 | (libc-search-index "Variable Index" variable | |
199 | "^[ \t]+- \\(Variable\\|Macro\\): .*\\<" "\\>")) | |
200 | ||
201 | (defun libc-lookup-type (data-type) | |
202 | (libc-search-index "Type Index" data-type | |
203 | "^[ \t]+- Data Type: \\<" "\\>")) | |
204 | ||
205 | (defun libc-lookup-file (file-name) | |
206 | (libc-search-index "File Index" file-name)) | |
207 | ||
208 | (defun libc-search-index (index item &optional prefix suffix) | |
209 | "Search ITEM in the Info index INDEX and go to that Info node. | |
210 | ||
211 | Value is ITEM or `nil' if an error occurs. | |
212 | ||
213 | If PREFIX and/or SUFFIX are non-`nil', then search the Info node for | |
214 | the first occurrence of the regular expression `PREFIX ITEM SUFFIX' and | |
215 | leave point at the beginning of the first line of the match. ITEM will | |
216 | be highlighted with `libc-highlight-face' iff `libc-highlight-face' is | |
217 | not `nil'." | |
218 | (condition-case nil | |
219 | (save-selected-window | |
220 | (or (get-buffer "*info*") | |
221 | (save-window-excursion | |
222 | (info))) | |
223 | (switch-to-buffer-other-window "*info*") | |
224 | (Info-goto-node (concat "(" libc-info-file-name ")" index)) | |
225 | (Info-menu item) | |
226 | (if (or prefix suffix) | |
227 | (let ((case-fold-search nil) | |
228 | (buffer-read-only nil)) | |
229 | (goto-char (point-min)) | |
230 | (re-search-forward | |
231 | (concat prefix (regexp-quote item) suffix)) | |
232 | (goto-char (match-beginning 0)) | |
233 | (and window-system libc-highlight-face | |
234 | ;; Search again for ITEM so that the first | |
235 | ;; occurence of ITEM will be highlighted. | |
236 | (save-excursion | |
237 | (re-search-forward (regexp-quote item)) | |
63f125ee RS |
238 | (let ((start (match-beginning 0)) |
239 | (end (match-end 0))) | |
240 | (if (overlayp libc-highlight-overlay) | |
241 | (move-overlay libc-highlight-overlay | |
242 | start end (current-buffer)) | |
243 | (setq libc-highlight-overlay | |
244 | (make-overlay start end)))) | |
245 | (overlay-put libc-highlight-overlay | |
246 | 'face libc-highlight-face))) | |
2c989468 RS |
247 | (beginning-of-line))) |
248 | item) | |
249 | (error nil))) | |
250 | ||
251 | \f | |
252 | (provide 'libc) | |
253 | ||
254 | ;;; libc.el ends here |