lisp/libc.el

   1 ;;; libc.el -- lookup C symbols in the GNU C Library Reference Manual.
   2
   3 ;; Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
   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
  47   "*Face for highlighting looked up symbol names in the Info buffer.
  48 `nil' disables highlighting.")
  49
  50 (defvar libc-highlight-overlay nil
  51   "Overlay object used for highlighting.")
  52
  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))
 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)))
 247               (beginning-of-line)))
 248         item)
 249     (error nil)))
 250
 251 \f
 252 (provide 'libc)
 253
 254 ;;; libc.el ends here