lisp/emacs-lisp/helper.el

   1 ;; helper - utility help package for modes which want to provide help
   2 ;; without relinquishing control, e.g. `electric' modes.
   3
   4 ;; Copyright (C) 1985 Free Software Foundation, Inc.
   5 ;; Principal author K. Shane Hartman
   6
   7 ;; This file is part of GNU Emacs.
   8
   9 ;; GNU Emacs is free software; you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation; either version 1, or (at your option)
  12 ;; any later version.
  13
  14 ;; GNU Emacs is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs; see the file COPYING.  If not, write to
  21 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  22
  23
  24 (provide 'helper)                       ; hey, here's a helping hand.
  25
  26 ;; Bind this to a string for <blank> in "... Other keys <blank>".
  27 ;; Helper-help uses this to construct help string when scrolling.
  28 ;; Defaults to "return"
  29 (defvar Helper-return-blurb nil)
  30
  31 ;; Keymap implementation doesn't work too well for non-standard loops.
  32 ;; But define it anyway for those who can use it.  Non-standard loops
  33 ;; will probably have to use Helper-help.  You can't autoload the
  34 ;; keymap either.
  35
  36
  37 (defvar Helper-help-map nil)
  38 (if Helper-help-map
  39     nil
  40   (setq Helper-help-map (make-keymap))
  41   ;(fillarray Helper-help-map 'undefined)
  42   (define-key Helper-help-map "m" 'Helper-describe-mode)
  43   (define-key Helper-help-map "b" 'Helper-describe-bindings)
  44   (define-key Helper-help-map "c" 'Helper-describe-key-briefly)
  45   (define-key Helper-help-map "k" 'Helper-describe-key)
  46   ;(define-key Helper-help-map "f" 'Helper-describe-function)
  47   ;(define-key Helper-help-map "v" 'Helper-describe-variable)
  48   (define-key Helper-help-map "?" 'Helper-help-options)
  49   (define-key Helper-help-map (char-to-string help-char) 'Helper-help-options)
  50   (fset 'Helper-help-map Helper-help-map))
  51
  52 (defun Helper-help-scroller ()
  53   (let ((blurb (or (and (boundp 'Helper-return-blurb)
  54                         Helper-return-blurb)
  55                    "return")))
  56     (save-window-excursion
  57       (goto-char (window-start (selected-window)))
  58       (if (get-buffer-window "*Help*")
  59           (pop-to-buffer "*Help*")
  60         (switch-to-buffer "*Help*"))
  61       (goto-char (point-min))
  62       (let ((continue t) state)
  63         (while continue
  64           (setq state (+ (* 2 (if (pos-visible-in-window-p (point-max)) 1 0))
  65                          (if (pos-visible-in-window-p (point-min)) 1 0)))
  66           (message
  67             (nth state
  68                  '("Space forward, Delete back. Other keys %s"
  69                    "Space scrolls forward. Other keys %s"
  70                    "Delete scrolls back. Other keys %s"
  71                    "Type anything to %s"))
  72             blurb)
  73           (setq continue (read-char))
  74           (cond ((and (memq continue '(?\ ?\C-v)) (< state 2))
  75                  (scroll-up))
  76                 ((= continue ?\C-l)
  77                  (recenter))
  78                 ((and (= continue ?\177) (zerop (% state 2)))
  79                  (scroll-down))
  80                 (t (setq continue nil))))))))
  81
  82 (defun Helper-help-options ()
  83   "Describe help options."
  84   (interactive)
  85   (message "c (key briefly), m (mode), k (key), b (bindings)")
  86   ;(message "c (key briefly), m (mode), k (key), v (variable), f (function)")
  87   (sit-for 4))
  88
  89 (defun Helper-describe-key-briefly (key)
  90   "Briefly describe binding of KEY."
  91   (interactive "kDescribe key briefly: ")
  92   (describe-key-briefly key)
  93   (sit-for 4))
  94
  95 (defun Helper-describe-key (key)
  96   "Describe binding of KEY."
  97   (interactive "kDescribe key: ")
  98   (save-window-excursion (describe-key key))
  99   (Helper-help-scroller))
 100
 101 (defun Helper-describe-function ()
 102   "Describe a function.  Name read interactively."
 103   (interactive)
 104   (save-window-excursion (call-interactively 'describe-function))
 105   (Helper-help-scroller))
 106
 107 (defun Helper-describe-variable ()
 108   "Describe a variable.  Name read interactively."
 109   (interactive)
 110   (save-window-excursion (call-interactively 'describe-variable))
 111   (Helper-help-scroller))
 112
 113 (defun Helper-describe-mode ()
 114   "Describe the current mode."
 115   (interactive)
 116   (let ((name mode-name)
 117         (documentation (documentation major-mode)))
 118     (save-excursion
 119       (set-buffer (get-buffer-create "*Help*"))
 120       (erase-buffer)
 121       (insert name " Mode\n" documentation)))
 122   (Helper-help-scroller))
 123
 124 (defun Helper-describe-bindings ()
 125   "Describe local key bindings of current mode."
 126   (interactive)
 127   (message "Making binding list...")
 128   (save-window-excursion (describe-bindings))
 129   (Helper-help-scroller))
 130
 131 (defun Helper-help ()
 132   "Provide help for current mode."
 133   (interactive)
 134   (let ((continue t) c)
 135     (while continue
 136       (message "Help (Type ? for further options)")
 137       (setq c (char-to-string (downcase (read-char))))
 138       (setq c (lookup-key Helper-help-map c))
 139       (cond ((eq c 'Helper-help-options)
 140              (Helper-help-options))
 141             ((commandp c)
 142              (call-interactively c)
 143              (setq continue nil))
 144             (t
 145              (ding)
 146              (setq continue nil))))))
 147