| 1 | ;;; reporter.el --- customizable bug reporting of lisp programs |
| 2 | |
| 3 | ;; Copyright (C) 1993-1998, 2001-2011 Free Software Foundation, Inc. |
| 4 | |
| 5 | ;; Author: 1993-1998 Barry A. Warsaw |
| 6 | ;; Maintainer: FSF |
| 7 | ;; Created: 19-Apr-1993 |
| 8 | ;; Keywords: maint mail tools |
| 9 | |
| 10 | ;; This file is part of GNU Emacs. |
| 11 | |
| 12 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
| 13 | ;; it under the terms of the GNU General Public License as published by |
| 14 | ;; the Free Software Foundation, either version 3 of the License, or |
| 15 | ;; (at your option) any later version. |
| 16 | |
| 17 | ;; GNU Emacs is distributed in the hope that it will be useful, |
| 18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 20 | ;; GNU General Public License for more details. |
| 21 | |
| 22 | ;; You should have received a copy of the GNU General Public License |
| 23 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
| 24 | |
| 25 | ;;; Commentary: |
| 26 | |
| 27 | ;; End User Interface |
| 28 | ;; ================== |
| 29 | ;; The variable `mail-user-agent' contains a symbol indicating which |
| 30 | ;; Emacs mail package end users would like to use to compose outgoing |
| 31 | ;; mail. See that variable for details (it is no longer defined in |
| 32 | ;; this file). |
| 33 | |
| 34 | ;; Lisp Package Authors |
| 35 | ;; ==================== |
| 36 | ;; reporter.el was written primarily for Emacs Lisp package authors so |
| 37 | ;; that their users can more easily report bugs. When invoked, |
| 38 | ;; `reporter-submit-bug-report' will set up an outgoing mail buffer |
| 39 | ;; with the appropriate bug report address, including a lisp |
| 40 | ;; expression the maintainer of the package can evaluate to completely |
| 41 | ;; reproduce the environment in which the bug was observed (e.g. by |
| 42 | ;; using `eval-last-sexp'). This package proved especially useful |
| 43 | ;; during my development of CC Mode, which is highly dependent on its |
| 44 | ;; configuration variables. |
| 45 | ;; |
| 46 | ;; Do a "C-h f reporter-submit-bug-report" for more information. |
| 47 | ;; Here's an example usage: |
| 48 | ;; |
| 49 | ;;(defconst mypkg-version "9.801") |
| 50 | ;;(defconst mypkg-maintainer-address "mypkg-help@foo.com") |
| 51 | ;;(defun mypkg-submit-bug-report () |
| 52 | ;; "Submit via mail a bug report on mypkg" |
| 53 | ;; (interactive) |
| 54 | ;; (require 'reporter) |
| 55 | ;; (reporter-submit-bug-report |
| 56 | ;; mypkg-maintainer-address |
| 57 | ;; (concat "mypkg.el " mypkg-version) |
| 58 | ;; (list 'mypkg-variable-1 |
| 59 | ;; 'mypkg-variable-2 |
| 60 | ;; ;; ... |
| 61 | ;; 'mypkg-variable-last))) |
| 62 | |
| 63 | ;;; Code: |
| 64 | |
| 65 | \f |
| 66 | ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv |
| 67 | ;; Package author interface variables |
| 68 | |
| 69 | (defvar reporter-prompt-for-summary-p nil |
| 70 | "Interface variable controlling prompting for problem summary. |
| 71 | When non-nil, `reporter-submit-bug-report' prompts the user for a |
| 72 | brief summary of the problem, and puts this summary on the Subject: |
| 73 | line. If this variable is a string, that string is used as the prompt |
| 74 | string. |
| 75 | |
| 76 | Default behavior is to not prompt (i.e. nil). If you want reporter to |
| 77 | prompt, you should `let' bind this variable before calling |
| 78 | `reporter-submit-bug-report'. Note that this variable is not |
| 79 | buffer-local so you should never just `setq' it.") |
| 80 | |
| 81 | (defvar reporter-dont-compact-list nil |
| 82 | "Interface variable controlling compacting of list values. |
| 83 | When non-nil, this must be a list of variable symbols. When a |
| 84 | variable containing a list value is formatted in the bug report mail |
| 85 | buffer, it normally is compacted so that its value fits one the fewest |
| 86 | number of lines. If the variable's symbol appears in this list, its |
| 87 | value is printed in a more verbose style, specifically, one elemental |
| 88 | sexp per line. |
| 89 | |
| 90 | Note that this variable is not buffer-local so you should never just |
| 91 | `setq' it. If you want to changes its default value, you should `let' |
| 92 | bind it.") |
| 93 | |
| 94 | ;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 95 | ;; End of editable variables |
| 96 | |
| 97 | \f |
| 98 | (defvar reporter-eval-buffer nil |
| 99 | "Buffer to retrieve variable's value from. |
| 100 | This is necessary to properly support the printing of buffer-local |
| 101 | variables. Current buffer will always be the mail buffer being |
| 102 | composed.") |
| 103 | |
| 104 | (defvar reporter-initial-text nil |
| 105 | "The automatically created initial text of a bug report.") |
| 106 | (make-variable-buffer-local 'reporter-initial-text) |
| 107 | |
| 108 | |
| 109 | \f |
| 110 | ;; status feedback to the user |
| 111 | (defvar reporter-status-message nil) |
| 112 | (defvar reporter-status-count nil) |
| 113 | |
| 114 | (defun reporter-update-status () |
| 115 | "Periodically output a status message." |
| 116 | (if (zerop (% reporter-status-count 10)) |
| 117 | (progn |
| 118 | (message "%s" reporter-status-message) |
| 119 | (setq reporter-status-message (concat reporter-status-message ".")))) |
| 120 | (setq reporter-status-count (1+ reporter-status-count))) |
| 121 | |
| 122 | \f |
| 123 | ;; dumping/pretty printing of values |
| 124 | (defun reporter-beautify-list (maxwidth compact-p) |
| 125 | "Pretty print a list." |
| 126 | (reporter-update-status) |
| 127 | (let ((move t) |
| 128 | linebreak indent-enclosing-p indent-p here) |
| 129 | (condition-case nil ;loop exit |
| 130 | (progn |
| 131 | (down-list 1) |
| 132 | (setq indent-enclosing-p t) |
| 133 | (while move |
| 134 | (setq here (point)) |
| 135 | ;; The following line is how we break out of the while |
| 136 | ;; loop, in one of two ways. Either we've hit the end of |
| 137 | ;; the buffer, in which case scan-sexps returns nil, or |
| 138 | ;; we've crossed unbalanced parens and it will raise an |
| 139 | ;; error we're expecting to catch. |
| 140 | (setq move (scan-sexps (point) 1)) |
| 141 | (goto-char move) |
| 142 | (if (<= maxwidth (current-column)) |
| 143 | (if linebreak |
| 144 | (progn |
| 145 | (goto-char linebreak) |
| 146 | (newline-and-indent) |
| 147 | (setq linebreak nil)) |
| 148 | (goto-char here) |
| 149 | (setq indent-p (reporter-beautify-list maxwidth compact-p)) |
| 150 | (goto-char here) |
| 151 | (forward-sexp 1) |
| 152 | (if indent-p |
| 153 | (newline-and-indent)) |
| 154 | t) |
| 155 | (if compact-p |
| 156 | (setq linebreak (point)) |
| 157 | (newline-and-indent)) |
| 158 | )) |
| 159 | t) |
| 160 | (error indent-enclosing-p)))) |
| 161 | |
| 162 | (defun reporter-lisp-indent (indent-point state) |
| 163 | "A better lisp indentation style for bug reporting." |
| 164 | (save-excursion |
| 165 | (goto-char (1+ (nth 1 state))) |
| 166 | (current-column))) |
| 167 | |
| 168 | (declare-function mail-position-on-field "sendmail" (field &optional soft)) |
| 169 | (declare-function mail-text "sendmail" ()) |
| 170 | |
| 171 | (defun reporter-dump-variable (varsym mailbuf) |
| 172 | "Pretty-print the value of the variable in symbol VARSYM. |
| 173 | MAILBUF is the mail buffer being composed." |
| 174 | (reporter-update-status) |
| 175 | (condition-case nil |
| 176 | (let ((val (with-current-buffer reporter-eval-buffer |
| 177 | (symbol-value varsym))) |
| 178 | (sym (symbol-name varsym)) |
| 179 | (print-escape-newlines t) |
| 180 | (maxwidth (1- (window-width))) |
| 181 | (here (point))) |
| 182 | (insert " " sym " " |
| 183 | (cond |
| 184 | ((memq val '(t nil)) "") |
| 185 | ((listp val) "'") |
| 186 | ((symbolp val) "'") |
| 187 | (t "")) |
| 188 | (prin1-to-string val)) |
| 189 | (lisp-indent-line) |
| 190 | ;; clean up lists, but only if the line as printed was long |
| 191 | ;; enough to wrap |
| 192 | (if (and val ;nil is a list, but short |
| 193 | (listp val) |
| 194 | (<= maxwidth (current-column))) |
| 195 | (save-excursion |
| 196 | (let ((compact-p (not (memq varsym reporter-dont-compact-list))) |
| 197 | (lisp-indent-function 'reporter-lisp-indent)) |
| 198 | (goto-char here) |
| 199 | (reporter-beautify-list maxwidth compact-p)))) |
| 200 | (insert "\n")) |
| 201 | (void-variable |
| 202 | (with-current-buffer mailbuf |
| 203 | (mail-position-on-field "X-Reporter-Void-Vars-Found") |
| 204 | (end-of-line) |
| 205 | (insert (symbol-name varsym) " "))) |
| 206 | (error |
| 207 | (error "")))) |
| 208 | |
| 209 | (defun reporter-dump-state (pkgname varlist pre-hooks post-hooks) |
| 210 | "Dump the state of the mode specific variables. |
| 211 | PKGNAME contains the name of the mode as it will appear in the bug |
| 212 | report (you must explicitly concat any version numbers). |
| 213 | |
| 214 | VARLIST is the list of variables to dump. Each element in |
| 215 | VARLIST can be a variable symbol, or a cons cell. If a symbol, |
| 216 | this will be passed to `reporter-dump-variable' for insertion |
| 217 | into the mail buffer. If a cons cell, the car must be a variable |
| 218 | symbol and the cdr must be a function which will be `funcall'd |
| 219 | with arguments the symbol and the mail buffer being composed. Use |
| 220 | this to write your own custom variable value printers for |
| 221 | specific variables. |
| 222 | |
| 223 | Note that the global variable `reporter-eval-buffer' will be bound to |
| 224 | the buffer in which `reporter-submit-bug-report' was invoked. If you |
| 225 | want to print the value of a buffer local variable, you should wrap |
| 226 | the `eval' call in your custom printer inside a `set-buffer' (and |
| 227 | probably a `save-excursion'). `reporter-dump-variable' handles this |
| 228 | properly. |
| 229 | |
| 230 | PRE-HOOKS is run after the Emacs version and PKGNAME are inserted, but |
| 231 | before the VARLIST is dumped. POST-HOOKS is run after the VARLIST is |
| 232 | dumped." |
| 233 | (let ((buffer (current-buffer))) |
| 234 | (set-buffer buffer) |
| 235 | (insert "Emacs : " (emacs-version) "\n") |
| 236 | (and pkgname |
| 237 | (insert "Package: " pkgname "\n")) |
| 238 | (run-hooks 'pre-hooks) |
| 239 | (if (not varlist) |
| 240 | nil |
| 241 | (insert "\ncurrent state:\n==============\n") |
| 242 | ;; create an emacs-lisp-mode buffer to contain the output, which |
| 243 | ;; we'll later insert into the mail buffer |
| 244 | (condition-case fault |
| 245 | (let ((mailbuf (current-buffer)) |
| 246 | (elbuf (get-buffer-create " *tmp-reporter-buffer*"))) |
| 247 | (with-current-buffer elbuf |
| 248 | (emacs-lisp-mode) |
| 249 | (erase-buffer) |
| 250 | (insert "(setq\n") |
| 251 | (lisp-indent-line) |
| 252 | (mapc |
| 253 | (function |
| 254 | (lambda (varsym-or-cons-cell) |
| 255 | (let ((varsym (or (car-safe varsym-or-cons-cell) |
| 256 | varsym-or-cons-cell)) |
| 257 | (printer (or (cdr-safe varsym-or-cons-cell) |
| 258 | 'reporter-dump-variable))) |
| 259 | (funcall printer varsym mailbuf) |
| 260 | ))) |
| 261 | varlist) |
| 262 | (lisp-indent-line) |
| 263 | (insert ")\n")) |
| 264 | (insert-buffer-substring elbuf)) |
| 265 | (error |
| 266 | (insert "State could not be dumped due to the following error:\n\n" |
| 267 | (format "%s" fault) |
| 268 | "\n\nYou should still send this bug report.")))) |
| 269 | (run-hooks 'post-hooks) |
| 270 | )) |
| 271 | |
| 272 | \f |
| 273 | (defun reporter-compose-outgoing () |
| 274 | "Compose the outgoing mail buffer. |
| 275 | |
| 276 | Return the selected paradigm, with the current buffer tacked onto the |
| 277 | beginning of the list." |
| 278 | (let* ((agent mail-user-agent) |
| 279 | (compose (get mail-user-agent 'composefunc))) |
| 280 | ;; Sanity check. If this fails then we'll try to use the SENDMAIL |
| 281 | ;; protocol, otherwise we must signal an error. |
| 282 | (if (not (and compose (functionp compose))) |
| 283 | (progn |
| 284 | (setq agent 'sendmail-user-agent |
| 285 | compose (get agent 'composefunc)) |
| 286 | (if (not (and compose (functionp compose))) |
| 287 | (error "Could not find a valid `mail-user-agent'") |
| 288 | (ding) |
| 289 | (message "`%s' is an invalid `mail-user-agent'; using `sendmail-user-agent'" |
| 290 | mail-user-agent) |
| 291 | ))) |
| 292 | (funcall compose) |
| 293 | agent)) |
| 294 | |
| 295 | \f |
| 296 | ;;;###autoload |
| 297 | (defun reporter-submit-bug-report |
| 298 | (address pkgname varlist &optional pre-hooks post-hooks salutation) |
| 299 | "Begin submitting a bug report via email. |
| 300 | |
| 301 | ADDRESS is the email address for the package's maintainer. PKGNAME is |
| 302 | the name of the package (if you want to include version numbers, |
| 303 | you must put them into PKGNAME before calling this function). |
| 304 | Optional PRE-HOOKS and POST-HOOKS are passed to `reporter-dump-state'. |
| 305 | Optional SALUTATION is inserted at the top of the mail buffer, |
| 306 | and point is left after the salutation. |
| 307 | |
| 308 | VARLIST is the list of variables to dump (see `reporter-dump-state' |
| 309 | for details). The optional argument PRE-HOOKS and POST-HOOKS are |
| 310 | passed to `reporter-dump-state'. Optional argument SALUTATION is text |
| 311 | to be inserted at the top of the mail buffer; in that case, point is |
| 312 | left after that text. |
| 313 | |
| 314 | This function prompts for a summary if `reporter-prompt-for-summary-p' |
| 315 | is non-nil. |
| 316 | |
| 317 | This function does not send a message; it uses the given information |
| 318 | to initialize a message, which the user can then edit and finally send |
| 319 | \(or decline to send). The variable `mail-user-agent' controls which |
| 320 | mail-sending package is used for editing and sending the message." |
| 321 | (let ((reporter-eval-buffer (current-buffer)) |
| 322 | final-resting-place |
| 323 | after-sep-pos |
| 324 | (reporter-status-message "Formatting bug report buffer...") |
| 325 | (reporter-status-count 0) |
| 326 | (problem (and reporter-prompt-for-summary-p |
| 327 | (read-string (if (stringp reporter-prompt-for-summary-p) |
| 328 | reporter-prompt-for-summary-p |
| 329 | "(Very) brief summary of problem: ")))) |
| 330 | (agent (reporter-compose-outgoing)) |
| 331 | (mailbuf (current-buffer)) |
| 332 | hookvar) |
| 333 | ;; do the work |
| 334 | (require 'sendmail) |
| 335 | ;; If mailbuf did not get made visible before, make it visible now. |
| 336 | (let (same-window-buffer-names same-window-regexps) |
| 337 | (pop-to-buffer mailbuf) |
| 338 | ;; Just in case the original buffer is not visible now, bring it |
| 339 | ;; back somewhere |
| 340 | (and pop-up-windows (display-buffer reporter-eval-buffer))) |
| 341 | (goto-char (point-min)) |
| 342 | (mail-position-on-field "to") |
| 343 | (insert address) |
| 344 | ;; insert problem summary if available |
| 345 | (if (and reporter-prompt-for-summary-p problem pkgname) |
| 346 | (progn |
| 347 | (mail-position-on-field "subject") |
| 348 | (insert pkgname "; " problem))) |
| 349 | ;; move point to the body of the message |
| 350 | (mail-text) |
| 351 | (forward-line 1) |
| 352 | (setq after-sep-pos (point)) |
| 353 | (and salutation (insert "\n" salutation "\n\n")) |
| 354 | (unwind-protect |
| 355 | (progn |
| 356 | (setq final-resting-place (point-marker)) |
| 357 | (insert "\n\n") |
| 358 | (reporter-dump-state pkgname varlist pre-hooks post-hooks) |
| 359 | (goto-char final-resting-place)) |
| 360 | (set-marker final-resting-place nil)) |
| 361 | |
| 362 | ;; save initial text and set up the `no-empty-submission' hook. |
| 363 | ;; This only works for mailers that support a pre-send hook, and |
| 364 | ;; for which the paradigm has a non-nil value for the `hookvar' |
| 365 | ;; key in its agent (i.e. sendmail.el's mail-send-hook). |
| 366 | (save-excursion |
| 367 | (goto-char (point-max)) |
| 368 | (skip-chars-backward " \t\n") |
| 369 | (setq reporter-initial-text (buffer-substring after-sep-pos (point)))) |
| 370 | (if (setq hookvar (get agent 'hookvar)) |
| 371 | (add-hook hookvar 'reporter-bug-hook nil t)) |
| 372 | |
| 373 | ;; compose the minibuf message and display this. |
| 374 | (let* ((sendkey-whereis (where-is-internal |
| 375 | (get agent 'sendfunc) nil t)) |
| 376 | (abortkey-whereis (where-is-internal |
| 377 | (get agent 'abortfunc) nil t)) |
| 378 | (sendkey (if sendkey-whereis |
| 379 | (key-description sendkey-whereis) |
| 380 | "C-c C-c")) ; TBD: BOGUS hardcode |
| 381 | (abortkey (if abortkey-whereis |
| 382 | (key-description abortkey-whereis) |
| 383 | "M-x kill-buffer")) ; TBD: BOGUS hardcode |
| 384 | ) |
| 385 | (message "Please enter your report. Type %s to send, %s to abort." |
| 386 | sendkey abortkey)) |
| 387 | )) |
| 388 | |
| 389 | (defun reporter-bug-hook () |
| 390 | "Prohibit sending mail if empty bug report." |
| 391 | (let ((after-sep-pos |
| 392 | (save-excursion |
| 393 | (rfc822-goto-eoh) |
| 394 | (forward-line 1) |
| 395 | (point)))) |
| 396 | (save-excursion |
| 397 | (goto-char (point-max)) |
| 398 | (skip-chars-backward " \t\n") |
| 399 | (if (and (= (- (point) after-sep-pos) |
| 400 | (length reporter-initial-text)) |
| 401 | (string= (buffer-substring after-sep-pos (point)) |
| 402 | reporter-initial-text)) |
| 403 | (error "Empty bug report cannot be sent")) |
| 404 | ))) |
| 405 | |
| 406 | \f |
| 407 | (provide 'reporter) |
| 408 | |
| 409 | ;;; reporter.el ends here |