[bpt/emacs.git] / lisp / libc.el

;;; libc.el -- lookup C symbols in the GNU C Library Reference Manual.

;; Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.

;;; Author: Ralph Schleicher <rs@purple.UL.BaWue.DE>
;;; Keywords: local c info

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:

;; This code has a long history.  It started as a minor
;; mode for C mode.  This era ended with the release of version 2
;; of the GNU C Library in 1997.  The code was therefore rewritten
;; more or less from scratch so that all lookups are performed via
;; indices.  Not finding an existing symbol in an index means that
;; there is an error in the manual.  Long missed features like a
;; separate input history, symbol name completion in the mini-buffer,
;; highlighting of looked up symbol names in the Info buffer, and
;; implicitly prepending `struct', `union' or `enum' to data types
;; were added in this phase too.

;;; Code:

(require 'info)

\f
(defvar libc-info-file-name "libc"
  "Basename of the Info file of the GNU C Library Reference Manual.")

(defvar libc-highlight-face 'highlight
  "*Face for highlighting looked up symbol names in the Info buffer.
`nil' disables highlighting.")

(defvar libc-highlight-overlay nil
  "Overlay object used for highlighting.")

(defconst libc-symbol-completions nil
  "Alist of documented C symbols.")

(defconst libc-file-completions nil
  "Alist of documented programs or files.")

(defvar libc-history nil
  "History of previous input lines.")

;;;###autoload
(defun libc-describe-symbol (symbol-name)
  "Display the documentation of a C symbol in another window.
SYMBOL-NAME must be documented in the GNU C Library Reference Manual.

If called interactively, SYMBOL-NAME will be read from the mini-buffer.
Optional prefix argument means insert the default symbol (if any) into
the mini-buffer so that it can be edited.  The default symbol is the
one found at point.

If SYMBOL-NAME is a public function, variable, or data type of the GNU
C Library but `libc-describe-symbol' fails to display it's documentation,
then you have found a bug in the manual.  Please report that to the mail
address `bug-glibc-manual@prep.ai.mit.edu' so that it can be fixed."
  (interactive
   (let* ((completion-ignore-case nil)
	  (enable-recursive-minibuffers t)
	  (symbol (libc-symbol-at-point))
	  (value (completing-read
		  (if symbol
		      (format "Describe symbol (default %s): " symbol)
		    (format "Describe symbol: "))
		  libc-symbol-completions nil nil
		  (and current-prefix-arg symbol) 'libc-history)))
     (list (if (equal value "") symbol value))))
  (or (assoc symbol-name libc-symbol-completions)
      (error "Not documented as a C symbol: %s" (or symbol-name "")))
  (or (libc-lookup-function symbol-name)
      (libc-lookup-variable symbol-name)
      (libc-lookup-type symbol-name)))

;;;###autoload
(defun libc-describe-file (file-name)
  "Display the documentation of a program or file in another window.
FILE-NAME must be documented in the GNU C Library Reference Manual."
  (interactive
   (let* ((completion-ignore-case nil)
	  (enable-recursive-minibuffers t))
     (list (completing-read
	    "Describe program or file: "
	    libc-file-completions nil nil nil 'libc-history))))
  (or (assoc file-name libc-file-completions)
      (error "Not documented as a program or file: %s" (or file-name "")))
  (libc-lookup-file file-name))

;;;###autoload
(defun libc-search (regexp &optional arg)
  "Search in the GNU C Library Reference Manual for REGEXP.
Prefix argument means search should ignore case."
  (interactive "sSearch `libc.info' for regexp: \nP")
  (or (get-buffer "*info*")
      (save-window-excursion
	(info)))
  (switch-to-buffer-other-window "*info*")
  (Info-goto-node (concat "(" libc-info-file-name ")"))
  (let ((case-fold-search arg))
    (Info-search regexp)))

\f
(defun libc-make-completion-alist (info-nodes &optional regexp)
  "Create a unique alist from all menu items in the Info nodes INFO-NODES
of the GNU C Reference Manual.

Optional second argument REGEXP means include only menu items matching the
regular expression REGEXP."
  (condition-case nil
      (let (completions item)
	(save-window-excursion
	  (info libc-info-file-name)
	  (while info-nodes
	    (Info-goto-node (car info-nodes))
	    (goto-char (point-min))
	    (and (search-forward "\n* Menu:" nil t)
		 (while (re-search-forward "\n\\* \\([^:\t\n]*\\):" nil t)
		   (setq item (buffer-substring
			       (match-beginning 1) (match-end 1)))
		   (and (not (assoc item completions))
			(if regexp (string-match regexp item) t)
			(setq completions (cons (cons item nil)
						completions)))))
	    (setq info-nodes (cdr info-nodes)))
	  (Info-directory))
	completions)
    (error nil)))

(defun libc-after-manual-update ()
  "This function must only be called after a new version of the
GNU C Library Reference Manual was installed on your system."
  (setq libc-symbol-completions (libc-make-completion-alist
				 '("Function Index"
				   "Variable Index"
				   "Type Index"))
	libc-file-completions (libc-make-completion-alist
			       '("File Index") "^[^ \t]+$")))

(or (and libc-symbol-completions
	 libc-file-completions)
    (libc-after-manual-update))

(defun libc-symbol-at-point ()
  "Get the C symbol at point."
  (condition-case nil
      (save-excursion
	(backward-sexp)
	(let ((start (point))
	      prefix name)
	  ;; Test for a leading `struct', `union', or `enum' keyword
	  ;; but ignore names like `foo_struct'.
	  (setq prefix (and (< (skip-chars-backward " \t\n") 0)
			    (< (skip-chars-backward "_a-zA-Z0-9") 0)
			    (looking-at "\\(struct\\|union\\|enum\\)\\s ")
			    (concat (buffer-substring
				     (match-beginning 1) (match-end 1))
				    " ")))
	  (goto-char start)
	  (and (looking-at "[_a-zA-Z][_a-zA-Z0-9]*")
	       (setq name (buffer-substring
			   (match-beginning 0) (match-end 0))))
	  ;; Caveat!  Look forward if point is at `struct' etc.
	  (and (not prefix)
	       (or (string-equal name "struct")
		   (string-equal name "union")
		   (string-equal name "enum"))
	       (looking-at "[a-z]+\\s +\\([_a-zA-Z][_a-zA-Z0-9]*\\)")
	       (setq prefix (concat name " ")
		     name (buffer-substring
			   (match-beginning 1) (match-end 1))))
	  (and (or prefix name)
	       (concat prefix name))))
    (error nil)))

(defun libc-lookup-function (function)
  (libc-search-index "Function Index" function
		     "^[ \t]+- \\(Function\\|Macro\\): .*\\<" "\\>"))

(defun libc-lookup-variable (variable)
  (libc-search-index "Variable Index" variable
		     "^[ \t]+- \\(Variable\\|Macro\\): .*\\<" "\\>"))

(defun libc-lookup-type (data-type)
  (libc-search-index "Type Index" data-type
		     "^[ \t]+- Data Type: \\<" "\\>"))

(defun libc-lookup-file (file-name)
  (libc-search-index "File Index" file-name))

(defun libc-search-index (index item &optional prefix suffix)
  "Search ITEM in the Info index INDEX and go to that Info node.

Value is ITEM or `nil' if an error occurs.

If PREFIX and/or SUFFIX are non-`nil', then search the Info node for
the first occurrence of the regular expression `PREFIX ITEM SUFFIX' and
leave point at the beginning of the first line of the match.  ITEM will
be highlighted with `libc-highlight-face' iff `libc-highlight-face' is
not `nil'."
  (condition-case nil
      (save-selected-window
	(or (get-buffer "*info*")
	    (save-window-excursion
	      (info)))
	(switch-to-buffer-other-window "*info*")
	(Info-goto-node (concat "(" libc-info-file-name ")" index))
	(Info-menu item)
	(if (or prefix suffix)
	    (let ((case-fold-search nil)
		  (buffer-read-only nil))
	      (goto-char (point-min))
	      (re-search-forward
	       (concat prefix (regexp-quote item) suffix))
	      (goto-char (match-beginning 0))
	      (and window-system libc-highlight-face
		   ;; Search again for ITEM so that the first
		   ;; occurence of ITEM will be highlighted.
		   (save-excursion
		     (re-search-forward (regexp-quote item))
		     (let ((start (match-beginning 0))
			   (end (match-end 0)))
		       (if (overlayp libc-highlight-overlay)
			   (move-overlay libc-highlight-overlay
					 start end (current-buffer))
			 (setq libc-highlight-overlay
			       (make-overlay start end))))
		     (overlay-put libc-highlight-overlay
				  'face libc-highlight-face)))
	      (beginning-of-line)))
	item)
    (error nil)))

\f
(provide 'libc)

;;; libc.el ends here
Commit	Line	Data
2c989468 RS	1	;;; libc.el -- lookup C symbols in the GNU C Library Reference Manual.
2c989468 RS	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.")
2c989468 RS	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