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