lisp/mail/reporter.el

   1 ;;; reporter.el --- customizable bug reporting of lisp programs
   2
   3 ;; Author: 1993 Barry A. Warsaw, Century Computing Inc. <bwarsaw@cen.com>
   4 ;; Maintainer:      bwarsaw@cen.com
   5 ;; Created:         19-Apr-1993
   6 ;; Version:         1.18
   7 ;; Last Modified:   1993/05/22 00:29:49
   8 ;; Keywords: bug reports lisp
   9
  10 ;; Copyright (C) 1993 Free Software Foundation, Inc.
  11
  12 ;; This file is not yet part of GNU Emacs.
  13 ;;
  14 ;; This program is free software; you can redistribute it and/or modify
  15 ;; it under the terms of the GNU General Public License as published by
  16 ;; the Free Software Foundation; either version 2 of the License, or
  17 ;; (at your option) any later version.
  18 ;;
  19 ;; This program is distributed in the hope that it will be useful,
  20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 ;; GNU General Public License for more details.
  23 ;;
  24 ;; You should have received a copy of the GNU General Public License
  25 ;; along with this program; if not, write to the Free Software
  26 ;; Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  27
  28 ;; Introduction
  29 ;; ============
  30 ;; This program is for lisp package authors and is used to ease
  31 ;; reporting of bugs.  When invoked, reporter-submit-bug-report will
  32 ;; set up a mail buffer with the appropriate bug report address,
  33 ;; including a lisp expression the maintainer of the package can use
  34 ;; to completely reproduce the environment in which the bug was
  35 ;; observed (e.g. by using eval-last-sexp). This package is especially
  36 ;; useful for my development of c++-mode.el, which is highly dependent
  37 ;; on its configuration variables.
  38 ;;
  39 ;; Do a "C-h f reporter-submit-bug-report" for more information.
  40 ;; Here's an example usage:
  41 ;;
  42 ;; (defconst mypkg-version "9.801")
  43 ;; (defconst mypkg-maintainer-address "mypkg-help@foo.com")
  44 ;; (defun mypkg-submit-bug-report ()
  45 ;;   "Submit via mail a bug report on mypkg"
  46 ;;   (interactive)
  47 ;;   (require 'reporter)
  48 ;;   (and (y-or-n-p "Do you really want to submit a report on mypkg? ")
  49 ;;        (reporter-submit-bug-report
  50 ;;          mypkg-maintainer-address
  51 ;;          (concat "mypkg.el " mypkg-version)
  52 ;;          (list 'mypkg-variable-1
  53 ;;                'mypkg-variable-2
  54 ;;                ;; ...
  55 ;;                'mypkg-variable-last))))
  56
  57 ;; Mailing List
  58 ;; ============
  59 ;; I've set up a mailing list to report bugs or suggest enhancements,
  60 ;; etc. This list's intended audience is elisp package authors who are
  61 ;; using reporter and want to stay current with releases. Here are the
  62 ;; relevant addresses:
  63 ;;
  64 ;; Administrivia: reporter-request@anthem.nlm.nih.gov
  65 ;; Submissions:   reporter@anthem.nlm.nih.gov
  66
  67 ;; LCD Archive Entry:
  68 ;; reporter|Barry A. Warsaw|warsaw@cen.com|
  69 ;; Customizable bug reporting of lisp programs.|
  70 ;; 1993/05/22 00:29:49|1.18|~/misc/reporter.el.Z|
  71
  72 ;;; Code:
  73
  74 \f
  75 ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
  76 ;; user defined variables
  77
  78 (defvar reporter-mailer 'mail
  79   "*Mail package to use to generate bug report buffer.")
  80
  81 ;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82 ;; end of user defined variables
  83
  84 \f
  85 (defun reporter-dump-variable (varsym)
  86   "Pretty-print the value of the variable in symbol VARSYM."
  87   (let ((val (eval varsym))
  88         (sym (symbol-name varsym))
  89         (print-escape-newlines t))
  90     (insert "     " sym " "
  91             (cond
  92              ((memq val '(t nil)) "")
  93              ((listp val) "'")
  94              ((symbolp val) "'")
  95              (t ""))
  96             (prin1-to-string val)
  97             "\n")))
  98
  99 (defun reporter-dump-state (pkgname varlist pre-hooks post-hooks)
 100   "Dump the state of the mode specific variables.
 101 PKGNAME contains the name of the mode as it will appear in the bug
 102 report (you must explicitly concat any version numbers).
 103
 104 VARLIST is the list of variables to dump.  Each element in VARLIST can
 105 be a variable symbol, or a cons cell.  If a symbol, this will be
 106 passed to `reporter-dump-variable' for insertion into the mail buffer.
 107 If a cons cell, the car must be a variable symbol and the cdr must be
 108 a function which will be `funcall'd with the symbol. Use this to write
 109 your own custom variable value printers for specific variables.
 110
 111 PRE-HOOKS is run after the emacs-version and PKGNAME are inserted, but
 112 before the VARLIST is dumped.  POST-HOOKS is run after the VARLIST is
 113 dumped."
 114   (let ((buffer (current-buffer)))
 115     (set-buffer buffer)
 116     (insert "Emacs  : " (emacs-version) "\nPackage: " pkgname "\n")
 117     (run-hooks 'pre-hooks)
 118     (insert "\ncurrent state:\n==============\n(setq\n")
 119     (mapcar
 120      (function
 121       (lambda (varsym-or-cons-cell)
 122         (let ((varsym (or (car-safe varsym-or-cons-cell)
 123                           varsym-or-cons-cell))
 124               (printer (or (cdr-safe varsym-or-cons-cell)
 125                            'reporter-dump-variable)))
 126           (funcall printer varsym)
 127           )))
 128      varlist)
 129     (insert "     )\n")
 130     (run-hooks 'post-hooks)
 131     ))
 132
 133 (defun reporter-submit-bug-report
 134   (address pkgname varlist &optional pre-hooks post-hooks salutation)
 135   "Submit a bug report via mail.
 136
 137 ADDRESS is the email address for the package's maintainer. PKGNAME is
 138 the name of the mode (you must explicitly concat any version numbers).
 139 VARLIST is the list of variables to dump (do a `\\[describe-function] reporter-dump-state'
 140 for details). Optional PRE-HOOKS and POST-HOOKS are passed to
 141 `reporter-dump-state'. Optional SALUTATION is inserted at the top of the
 142 mail buffer, and point is left after the salutation.
 143
 144 The mailer used is described in the variable `reporter-mailer'."
 145
 146   (let ((curbuf (current-buffer))
 147         (mailbuf (progn (call-interactively reporter-mailer)
 148                         (current-buffer))))
 149     (require 'sendmail)
 150     (pop-to-buffer curbuf)
 151     (pop-to-buffer mailbuf)
 152     (goto-char (point-min))
 153     ;; different mailers use different separators, some may not even
 154     ;; use m-h-s, but sendmail.el stuff must have m-h-s bound.
 155     (let ((mail-header-separator
 156            (save-excursion
 157              (re-search-forward
 158               (concat
 159                "^\\("                   ;beginning of line
 160                (mapconcat
 161                 'identity
 162                 (list "[\t ]*"          ;simple SMTP form
 163                       "-+"              ;mh-e form
 164                       (regexp-quote
 165                        mail-header-separator)) ;sendmail.el form
 166                 "\\|")                  ;or them together
 167                "\\)$")                  ;end of line
 168               nil
 169               'move)                    ;search for and move
 170              (buffer-substring (match-beginning 0) (match-end 0)))))
 171       (mail-position-on-field "to")
 172       (insert address)
 173       (mail-position-on-field "subject")
 174       (insert "Report on package " pkgname)
 175       (re-search-forward mail-header-separator (point-max) 'move)
 176       (forward-line 1)
 177       (and salutation (insert "\n" salutation "\n\n"))
 178       (set-mark (point))                ;user should see mark change
 179       (insert "\n\n")
 180       (reporter-dump-state pkgname varlist pre-hooks post-hooks)
 181       (exchange-point-and-mark))
 182     (let* ((sendkey "C-c C-c")          ;can this be generalized like below?
 183            (killkey-whereis (where-is-internal 'kill-buffer nil t))
 184            (killkey (if killkey-whereis
 185                         (key-description killkey-whereis)
 186                       "M-x kill-buffer")))
 187       (message "Please type in your report. Hit %s to send, %s to abort."
 188                sendkey killkey))
 189     ))
 190
 191 ;; this is useful
 192 (provide 'reporter)
 193
 194 ;;; reporter.el ends here