1 ;;; trace.el --- tracing facility for Emacs Lisp functions
3 ;; Copyright (C) 1993, 1998, 2000, 2001, 2002, 2003, 2004,
4 ;; 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
6 ;; Author: Hans Chalupsky <hans@cs.buffalo.edu>
8 ;; Created: 15 Dec 1992
9 ;; Keywords: tools, lisp
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 3, or (at your option)
18 ;; GNU Emacs is distributed in the hope that it will be useful,
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.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to the
25 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
26 ;; Boston, MA 02110-1301, USA.
29 ;; trace|Hans Chalupsky|hans@cs.buffalo.edu|
30 ;; Tracing facility for Emacs Lisp functions|
31 ;; 1993/05/18 00:41:16|2.0|~/packages/trace.el.Z|
38 ;; A simple trace package that utilizes advice.el. It generates trace
39 ;; information in a Lisp-style fashion and inserts it into a trace output
40 ;; buffer. Tracing can be done in the background (or silently) so that
41 ;; generation of trace output won't interfere with what you are currently
46 ;; trace.el needs advice.el version 2.0 or later which you can get from the
47 ;; same place from where you got trace.el.
51 ;; - Traced subrs when called interactively will always show nil as the
52 ;; value of their arguments.
53 ;; - Only functions/macros/subrs that are called via their function cell will
54 ;; generate trace output, hence, you won't get trace output for:
55 ;; + Subrs called directly from other subrs/C-code
56 ;; + Compiled calls to subrs that have special byte-codes associated
57 ;; with them (e.g., car, cdr, ...)
58 ;; + Macros that were expanded during compilation
59 ;; - All the restrictions that apply to advice.el
63 ;; Put this file together with advice.el (version 2.0 or later) somewhere
64 ;; into your Emacs `load-path', byte-compile it/them for efficiency, and
65 ;; put the following autoload declarations into your .emacs
67 ;; (autoload 'trace-function "trace" "Trace a function" t)
68 ;; (autoload 'trace-function-background "trace" "Trace a function" t)
70 ;; or explicitly load it with (require 'trace) or (load "trace").
74 ;; - To trace a function say `M-x trace-function' which will ask you for the
75 ;; name of the function/subr/macro to trace, as well as for the buffer
76 ;; into which trace output should go.
77 ;; - If you want to trace a function that switches buffers or does other
78 ;; display oriented stuff use `M-x trace-function-background' which will
79 ;; generate the trace output silently in the background without popping
80 ;; up windows and doing other irritating stuff.
81 ;; - To untrace a function say `M-x untrace-function'.
82 ;; - To untrace all currently traced functions say `M-x untrace-all'.
89 ;; (* n (fact (1- n)))))
92 ;; (trace-function 'fact)
95 ;; Now, evaluating this...
100 ;; ...will generate the following in *trace-buffer*:
104 ;; | | 3 -> fact: n=2
105 ;; | | | 4 -> fact: n=1
106 ;; | | | | 5 -> fact: n=0
107 ;; | | | | 5 <- fact: 1
108 ;; | | | 4 <- fact: 1
114 ;; (defun ack (x y z)
117 ;; (if (and (<= x 2) (= z 0))
119 ;; (if (and (> x 2) (= z 0))
121 ;; (ack (1- x) y (ack x y (1- z)))))))
124 ;; (trace-function 'ack)
127 ;; Try this for some interesting trace output:
133 ;; The following does something similar to the functionality of the package
134 ;; log-message.el by Robert Potter, which is giving you a chance to look at
135 ;; messages that might have whizzed by too quickly (you won't see subr
136 ;; generated messages though):
138 ;; (trace-function-background 'message "*Message Log*")
143 ;; Revision 2.0 1993/05/18 00:41:16 hans
144 ;; * Adapted for advice.el 2.0; it now also works
145 ;; for GNU Emacs-19 and Lemacs
146 ;; * Separate function `trace-function-background'
147 ;; * Separate pieces of advice for foreground and background tracing
148 ;; * Less insane handling of interactive trace buffer specification
149 ;; * String arguments and values are now printed properly
151 ;; Revision 1.1 1992/12/15 22:45:15 hans
152 ;; * Created, first public release
160 "Tracing facility for Emacs Lisp functions."
165 (defcustom trace-buffer
"*trace-output*"
166 "*Trace output will by default go to that buffer."
170 ;; Current level of traced function invocation:
171 (defvar trace-level
0)
173 ;; Semi-cryptic name used for a piece of trace advice:
174 (defvar trace-advice-name
'trace-function\
)
176 ;; Used to separate new trace output from previous traced runs:
177 (defvar trace-separator
(format "%s\n" (make-string 70 ?
=)))
179 (defvar inhibit-trace nil
180 "If non-nil, all tracing is temporarily inhibited.")
182 (defun trace-entry-message (function level argument-bindings
)
183 ;; Generates a string that describes that FUNCTION has been entered at
184 ;; trace LEVEL with ARGUMENT-BINDINGS.
185 (format "%s%s%d -> %s: %s\n"
186 (mapconcat 'char-to-string
(make-string (1- level
) ?|
) " ")
187 (if (> level
1) " " "")
190 (mapconcat (lambda (binding)
192 (symbol-name (ad-arg-binding-field binding
'name
))
194 ;; do this so we'll see strings:
196 (ad-arg-binding-field binding
'value
))))
200 (defun trace-exit-message (function level value
)
201 ;; Generates a string that describes that FUNCTION has been exited at
202 ;; trace LEVEL and that it returned VALUE.
203 (format "%s%s%d <- %s: %s\n"
204 (mapconcat 'char-to-string
(make-string (1- level
) ?|
) " ")
205 (if (> level
1) " " "")
208 ;; do this so we'll see strings:
209 (prin1-to-string value
)))
211 (defun trace-make-advice (function buffer background
)
212 ;; Builds the piece of advice to be added to FUNCTION's advice info
213 ;; so that it will generate the proper trace output in BUFFER
214 ;; (quietly if BACKGROUND is t).
216 trace-advice-name nil t
219 (let ((trace-level (1+ trace-level
))
220 (trace-buffer (get-buffer-create ,buffer
)))
221 (unless inhibit-trace
222 (with-current-buffer trace-buffer
223 ,(unless background
'(pop-to-buffer trace-buffer
))
224 (goto-char (point-max))
225 ;; Insert a separator from previous trace output:
226 (if (= trace-level
1) (insert trace-separator
))
229 ',function trace-level ad-arg-bindings
))))
231 (unless inhibit-trace
232 (with-current-buffer trace-buffer
233 ,(unless background
'(pop-to-buffer trace-buffer
))
234 (goto-char (point-max))
237 ',function trace-level ad-return-value
))))))))
239 (defun trace-function-internal (function buffer background
)
240 ;; Adds trace advice for FUNCTION and activates it.
243 (trace-make-advice function
(or buffer trace-buffer
) background
)
245 (ad-activate function nil
))
247 (defun trace-is-traced (function)
248 (ad-find-advice function
'around trace-advice-name
))
251 (defun trace-function (function &optional buffer
)
252 "Traces FUNCTION with trace output going to BUFFER.
253 For every call of FUNCTION Lisp-style trace messages that display argument
254 and return values will be inserted into BUFFER. This function generates the
255 trace advice for FUNCTION and activates it together with any other advice
256 there might be!! The trace BUFFER will popup whenever FUNCTION is called.
257 Do not use this to trace functions that switch buffers or do any other
258 display oriented stuff, use `trace-function-background' instead."
261 (intern (completing-read "Trace function: " obarray
'fboundp t
))
262 (read-buffer "Output to buffer: " trace-buffer
)))
263 (trace-function-internal function buffer nil
))
266 (defun trace-function-background (function &optional buffer
)
267 "Traces FUNCTION with trace output going quietly to BUFFER.
268 When this tracing is enabled, every call to FUNCTION writes
269 a Lisp-style trace message (showing the arguments and return value)
270 into BUFFER. This function generates advice to trace FUNCTION
271 and activates it together with any other advice there might be.
272 The trace output goes to BUFFER quietly, without changing
273 the window or buffer configuration.
275 BUFFER defaults to `trace-buffer'."
279 (completing-read "Trace function in background: " obarray
'fboundp t
))
280 (read-buffer "Output to buffer: " trace-buffer
)))
281 (trace-function-internal function buffer t
))
283 (defun untrace-function (function)
284 "Untraces FUNCTION and possibly activates all remaining advice.
285 Activation is performed with `ad-update', hence remaining advice will get
286 activated only if the advice of FUNCTION is currently active. If FUNCTION
287 was not traced this is a noop."
289 (list (ad-read-advised-function "Untrace function: " 'trace-is-traced
)))
290 (when (trace-is-traced function
)
291 (ad-remove-advice function
'around trace-advice-name
)
292 (ad-update function
)))
294 (defun untrace-all ()
295 "Untraces all currently traced functions."
297 (ad-do-advised-functions (function)
298 (untrace-function function
)))
302 ;; arch-tag: cfd170a7-4932-4331-8c8b-b7151942e5a1
303 ;;; trace.el ends here