annotate lisp/emacs-lisp/trace.el @ 111741:40c5518fe5b3

sendmail.el trivia. * lisp/mail/sendmail.el (build-mail-aliases): Doc fix for autoload. (expand-mail-aliases): Remove unnecessary autoload.
author Glenn Morris <rgm@gnu.org>
date Fri, 26 Nov 2010 19:29:06 -0800
parents ed16fdd2685a
children 376148b31b5e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 ;;; trace.el --- tracing facility for Emacs Lisp functions
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2
74466
1d4b1a32fd66 Update copyright years.
Glenn Morris <rgm@gnu.org>
parents: 72586
diff changeset
3 ;; Copyright (C) 1993, 1998, 2000, 2001, 2002, 2003, 2004,
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 105870
diff changeset
4 ;; 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 ;; Author: Hans Chalupsky <hans@cs.buffalo.edu>
28574
23e11bfcfc21 Change maintainer. Use new backquote
Dave Love <fx@gnu.org>
parents: 21365
diff changeset
7 ;; Maintainer: FSF
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 ;; Created: 15 Dec 1992
5140
9cde7d7fea1f Comment change.
Richard M. Stallman <rms@gnu.org>
parents: 2854
diff changeset
9 ;; Keywords: tools, lisp
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 ;; This file is part of GNU Emacs.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 94179
diff changeset
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 ;; it under the terms of the GNU General Public License as published by
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 94179
diff changeset
15 ;; the Free Software Foundation, either version 3 of the License, or
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 94179
diff changeset
16 ;; (at your option) any later version.
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 ;; GNU Emacs is distributed in the hope that it will be useful,
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 ;; GNU General Public License for more details.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 ;; You should have received a copy of the GNU General Public License
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 94179
diff changeset
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 ;; LCD Archive Entry:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 ;; trace|Hans Chalupsky|hans@cs.buffalo.edu|
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 ;; Tracing facility for Emacs Lisp functions|
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 ;; 1993/05/18 00:41:16|2.0|~/packages/trace.el.Z|
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 ;;; Commentary:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 ;; Introduction:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 ;; =============
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
36 ;; A simple trace package that utilizes advice.el. It generates trace
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 ;; information in a Lisp-style fashion and inserts it into a trace output
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 ;; buffer. Tracing can be done in the background (or silently) so that
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 ;; generation of trace output won't interfere with what you are currently
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 ;; doing.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 ;; Requirement:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 ;; ============
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 ;; trace.el needs advice.el version 2.0 or later which you can get from the
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 ;; same place from where you got trace.el.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 ;; Restrictions:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 ;; =============
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 ;; - Traced subrs when called interactively will always show nil as the
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 ;; value of their arguments.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 ;; - Only functions/macros/subrs that are called via their function cell will
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 ;; generate trace output, hence, you won't get trace output for:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 ;; + Subrs called directly from other subrs/C-code
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 ;; + Compiled calls to subrs that have special byte-codes associated
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 ;; with them (e.g., car, cdr, ...)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 ;; + Macros that were expanded during compilation
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 ;; - All the restrictions that apply to advice.el
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 ;; Installation:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 ;; =============
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 ;; Put this file together with advice.el (version 2.0 or later) somewhere
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 ;; into your Emacs `load-path', byte-compile it/them for efficiency, and
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 ;; put the following autoload declarations into your .emacs
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 ;; (autoload 'trace-function "trace" "Trace a function" t)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 ;; (autoload 'trace-function-background "trace" "Trace a function" t)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 ;; or explicitly load it with (require 'trace) or (load "trace").
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 ;; Usage:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 ;; ======
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 ;; - To trace a function say `M-x trace-function' which will ask you for the
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 ;; name of the function/subr/macro to trace, as well as for the buffer
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 ;; into which trace output should go.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 ;; - If you want to trace a function that switches buffers or does other
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 ;; display oriented stuff use `M-x trace-function-background' which will
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 ;; generate the trace output silently in the background without popping
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 ;; up windows and doing other irritating stuff.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 ;; - To untrace a function say `M-x untrace-function'.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 ;; - To untrace all currently traced functions say `M-x untrace-all'.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 ;; Examples:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 ;; =========
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 ;; (defun fact (n)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 ;; (if (= n 0) 1
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 ;; (* n (fact (1- n)))))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 ;; fact
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
89 ;;
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 ;; (trace-function 'fact)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 ;; fact
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 ;; Now, evaluating this...
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 ;; (fact 4)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 ;; 24
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 ;; ...will generate the following in *trace-buffer*:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 ;; 1 -> fact: n=4
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 ;; | 2 -> fact: n=3
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 ;; | | 3 -> fact: n=2
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 ;; | | | 4 -> fact: n=1
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 ;; | | | | 5 -> fact: n=0
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 ;; | | | | 5 <- fact: 1
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 ;; | | | 4 <- fact: 1
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 ;; | | 3 <- fact: 2
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 ;; | 2 <- fact: 6
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 ;; 1 <- fact: 24
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 ;; (defun ack (x y z)
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
113 ;; (if (= x 0)
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 ;; (+ y z)
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
115 ;; (if (and (<= x 2) (= z 0))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 ;; (1- x)
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
117 ;; (if (and (> x 2) (= z 0))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 ;; y
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 ;; (ack (1- x) y (ack x y (1- z)))))))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 ;; ack
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 ;; (trace-function 'ack)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 ;; ack
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 ;; Try this for some interesting trace output:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 ;; (ack 3 3 1)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 ;; 27
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 ;;
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
130 ;;
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 ;; The following does something similar to the functionality of the package
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 ;; log-message.el by Robert Potter, which is giving you a chance to look at
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 ;; messages that might have whizzed by too quickly (you won't see subr
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 ;; generated messages though):
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 ;; (trace-function-background 'message "*Message Log*")
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 ;;; Change Log:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 ;; Revision 2.0 1993/05/18 00:41:16 hans
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 ;; * Adapted for advice.el 2.0; it now also works
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 ;; for GNU Emacs-19 and Lemacs
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 ;; * Separate function `trace-function-background'
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 ;; * Separate pieces of advice for foreground and background tracing
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 ;; * Less insane handling of interactive trace buffer specification
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 ;; * String arguments and values are now printed properly
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 ;;
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 ;; Revision 1.1 1992/12/15 22:45:15 hans
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 ;; * Created, first public release
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 ;;; Code:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 (require 'advice)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
157 (defgroup trace nil
64032
85b597997ef0 (trace): Finish `defgroup' description with period.
Juanma Barranquero <lekktu@gmail.com>
parents: 60276
diff changeset
158 "Tracing facility for Emacs Lisp functions."
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
159 :prefix "trace-"
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
160 :group 'lisp)
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
161
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 ;;;###autoload
105870
26baacb565b0 * textmodes/tex-mode.el (tex-alt-dvi-print-command)
Dan Nicolaescu <dann@ics.uci.edu>
parents: 104024
diff changeset
163 (defcustom trace-buffer (purecopy "*trace-output*")
104024
cce8d50c4566 Remove leading * from defcustom docs.
Glenn Morris <rgm@gnu.org>
parents: 100908
diff changeset
164 "Trace output will by default go to that buffer."
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
165 :type 'string
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
166 :group 'trace)
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 ;; Current level of traced function invocation:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 (defvar trace-level 0)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 ;; Semi-cryptic name used for a piece of trace advice:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 (defvar trace-advice-name 'trace-function\ )
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 ;; Used to separate new trace output from previous traced runs:
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 (defvar trace-separator (format "%s\n" (make-string 70 ?=)))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
177 (defvar inhibit-trace nil
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
178 "If non-nil, all tracing is temporarily inhibited.")
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
179
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 (defun trace-entry-message (function level argument-bindings)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 ;; Generates a string that describes that FUNCTION has been entered at
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 ;; trace LEVEL with ARGUMENT-BINDINGS.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 (format "%s%s%d -> %s: %s\n"
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 (mapconcat 'char-to-string (make-string (1- level) ?|) " ")
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 (if (> level 1) " " "")
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 level
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 function
95577
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
188 (let ((print-circle t))
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
189 (mapconcat (lambda (binding)
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
190 (concat
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
191 (symbol-name (ad-arg-binding-field binding 'name))
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
192 "="
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
193 ;; do this so we'll see strings:
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
194 (prin1-to-string
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
195 (ad-arg-binding-field binding 'value))))
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
196 argument-bindings
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
197 " "))))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 (defun trace-exit-message (function level value)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 ;; Generates a string that describes that FUNCTION has been exited at
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 ;; trace LEVEL and that it returned VALUE.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 (format "%s%s%d <- %s: %s\n"
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 (mapconcat 'char-to-string (make-string (1- level) ?|) " ")
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 (if (> level 1) " " "")
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 level
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 function
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 ;; do this so we'll see strings:
95577
e283d325f1bc (trace-entry-message, trace-exit-message): Use print-circle.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 94655
diff changeset
208 (let ((print-circle t)) (prin1-to-string value))))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 (defun trace-make-advice (function buffer background)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 ;; Builds the piece of advice to be added to FUNCTION's advice info
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 ;; so that it will generate the proper trace output in BUFFER
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 ;; (quietly if BACKGROUND is t).
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 (ad-make-advice
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 trace-advice-name nil t
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
216 `(advice
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
217 lambda ()
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
218 (let ((trace-level (1+ trace-level))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
219 (trace-buffer (get-buffer-create ,buffer)))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
220 (unless inhibit-trace
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
221 (with-current-buffer trace-buffer
95777
edc51d72cb17 * window.c (Vwindow_point_insertion_type): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 95577
diff changeset
222 (set (make-local-variable 'window-point-insertion-type) t)
edc51d72cb17 * window.c (Vwindow_point_insertion_type): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 95577
diff changeset
223 ,(unless background '(display-buffer trace-buffer))
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
224 (goto-char (point-max))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
225 ;; Insert a separator from previous trace output:
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
226 (if (= trace-level 1) (insert trace-separator))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
227 (insert
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
228 (trace-entry-message
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
229 ',function trace-level ad-arg-bindings))))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
230 ad-do-it
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
231 (unless inhibit-trace
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
232 (with-current-buffer trace-buffer
94179
d55e28c98546 (trace-make-advice): Don't change selected-window.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 79704
diff changeset
233 ,(unless background '(display-buffer trace-buffer))
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
234 (goto-char (point-max))
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
235 (insert
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
236 (trace-exit-message
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
237 ',function trace-level ad-return-value))))))))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 (defun trace-function-internal (function buffer background)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 ;; Adds trace advice for FUNCTION and activates it.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 (ad-add-advice
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 function
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 (trace-make-advice function (or buffer trace-buffer) background)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 'around 'last)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 (ad-activate function nil))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 (defun trace-is-traced (function)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 (ad-find-advice function 'around trace-advice-name))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 ;;;###autoload
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 (defun trace-function (function &optional buffer)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 "Traces FUNCTION with trace output going to BUFFER.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 For every call of FUNCTION Lisp-style trace messages that display argument
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
254 and return values will be inserted into BUFFER. This function generates the
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 trace advice for FUNCTION and activates it together with any other advice
107517
ed16fdd2685a Fix typos in docstrings.
Juanma Barranquero <lekktu@gmail.com>
parents: 106815
diff changeset
256 there might be!! The trace BUFFER will popup whenever FUNCTION is called.
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 Do not use this to trace functions that switch buffers or do any other
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 display oriented stuff, use `trace-function-background' instead."
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 (interactive
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 (list
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 (intern (completing-read "Trace function: " obarray 'fboundp t))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 (read-buffer "Output to buffer: " trace-buffer)))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 (trace-function-internal function buffer nil))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 ;;;###autoload
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 (defun trace-function-background (function &optional buffer)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 "Traces FUNCTION with trace output going quietly to BUFFER.
72586
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
268 When this tracing is enabled, every call to FUNCTION writes
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
269 a Lisp-style trace message (showing the arguments and return value)
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
270 into BUFFER. This function generates advice to trace FUNCTION
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
271 and activates it together with any other advice there might be.
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
272 The trace output goes to BUFFER quietly, without changing
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
273 the window or buffer configuration.
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
274
6ad55ad9813c (trace-function-background): Doc fix.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
275 BUFFER defaults to `trace-buffer'."
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 (interactive
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 (list
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 (intern
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 (completing-read "Trace function in background: " obarray 'fboundp t))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 (read-buffer "Output to buffer: " trace-buffer)))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 (trace-function-internal function buffer t))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 (defun untrace-function (function)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 "Untraces FUNCTION and possibly activates all remaining advice.
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 Activation is performed with `ad-update', hence remaining advice will get
47609
9c74f4f1d1c0 Add/remove spaces.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 28574
diff changeset
286 activated only if the advice of FUNCTION is currently active. If FUNCTION
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 was not traced this is a noop."
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 (interactive
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 (list (ad-read-advised-function "Untrace function: " 'trace-is-traced)))
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
290 (when (trace-is-traced function)
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
291 (ad-remove-advice function 'around trace-advice-name)
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
292 (ad-update function)))
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 (defun untrace-all ()
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 "Untraces all currently traced functions."
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 (interactive)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 (ad-do-advised-functions (function)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 (untrace-function function)))
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 (provide 'trace)
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301
60276
eeb966123ab7 (inhibit-trace): New var.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
302 ;; arch-tag: cfd170a7-4932-4331-8c8b-b7151942e5a1
2854
6ed299f80cbb entered into RCS
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 ;;; trace.el ends here