source: trunk/source/doc/src/using.xml @ 8669

Last change on this file since 8669 was 8669, checked in by gz, 14 years ago

document TRACE

File size: 5.7 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
4          <!ENTITY rest "<varname>&amp;rest</varname>">
5          <!ENTITY key "<varname>&amp;key</varname>">
6          <!ENTITY optional "<varname>&amp;optional</varname>">
7          <!ENTITY body "<varname>&amp;body</varname>">
8          <!ENTITY aux "<varname>&amp;aux</varname>">
9          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
10          <!ENTITY CCL "<literal>CCL</literal>">
11          ]>
12
13<chapter><title>Using &CCL;</title>
14 
15  <sect1><title>Introduction</title>
16   
17    <para>The Common Lisp standard allows considerable latitude in the
18      details of an implementation, and each particular Common Lisp
19      system has some idiosyncracies. This chapter describes ordinary
20      user-level features of &CCL;, including features that may be
21      part of the Common Lisp standard, but which may have quirks or
22      details in the &CCL; implementation that are not described by
23      the standard.</para>
24  </sect1>
25
26  <sect1 id="Trace"><title>Trace</title>
27
28  <para>
29    &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
30    <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
31    over tracing actions.
32  </para>
33
34
35  <para>
36  <command><varname>TRACE</varname> {<replaceable>spec</replaceable> |
37  (<replaceable>spec</replaceable> {<replaceable>option-key</replaceable>
38  <replaceable>value</replaceable>}*)}* [Macro]</command>
39  </para>
40
41  <para>
42    The <varname>trace</varname> macro encapsulates the function named by
43    <replaceable>spec</replaceable>, causing trace actions to take place on entry and exit from the
44    function.  The default actions print a message on function entry and exit.
45  </para>
46
47  <para>
48    Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
49  </para>
50     
51  <para>
52    A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
53    expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
54    specific method of a generic function in the form <varname>(:method
55    <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}* (
56    {<replaceable>specializer</replaceable>}* ) )</varname>, where a
57    <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
58    specializer.
59  </para>
60
61   <para>By default, whenever a traced function is entered or exited, a short message is printed
62   on <varname>*trace-output*</varname> showing the arguments on entry and values on exit.
63   The following <replaceable>option-keys</replaceable> can be used to modify this behavior:</para>
64
65   <variablelist>
66     <varlistentry>
67       <term><varname>:before</varname></term>
68       <listitem>
69         <para>specifies the action to be taken just before the traced function is entered.  The
70         value is one of:</para>
71         <variablelist>
72           <varlistentry>
73             <term><varname>:print</varname></term>
74             <listitem>
75               <para>The default, prints a short indented message showing the function name and the invocation arguments </para>
76             </listitem>
77           </varlistentry>
78           <varlistentry>
79             <term><varname>:break</varname></term>
80             <listitem>
81             <para>Enters the debugger after printing the standard function entry message</para>
82             </listitem>
83           </varlistentry>
84           <varlistentry>
85             <term><replaceable>function</replaceable></term>
86             <listitem>
87               <para>Any other value is interpreted as a function to
88               call on entry instead of printing the standard entry
89               message.  It is called with its first argument being
90               the name of the function being traced, the
91               remaining arguments being all the arguments to the function
92               being traced, and ccl:*trace-level* bound to the current
93               nesting level of trace actions.
94               </para>
95             </listitem>
96           </varlistentry>
97         </variablelist>
98       </listitem>
99     </varlistentry>
100
101     <varlistentry>
102       <term><varname>:after</varname></term>
103       <listitem>
104         <para>specifies the action to be taken just after the traced function exits.  The
105         value is one of:</para>
106         <variablelist>
107           <varlistentry>
108             <term><varname>:print</varname></term>
109             <listitem>
110               <para>The default, prints a short indented message showing the function name and the
111               returned values </para>
112             </listitem>
113           </varlistentry>
114           <varlistentry>
115             <term><varname>:break</varname></term>
116             <listitem>
117             <para>Enters the debugger after printing the standard function exit message</para>
118             </listitem>
119           </varlistentry>
120           <varlistentry>
121             <term><replaceable>function</replaceable></term>
122             <listitem>
123               <para>Any other value is interpreted as a function to
124               call on exit instead of printing the standard exit
125               message.  It is called with its first argument being
126               the name of the function being traced, the
127               remaining arguments being all the values returned by the function
128               being traced, and ccl:*trace-level* bound to the current
129               nesting level of trace actions.
130               </para>
131             </listitem>
132           </varlistentry>
133         </variablelist>
134       </listitem>
135     </varlistentry>
136
137
138     <varlistentry>
139       <term><varname>:backtrace</varname></term>
140       <listitem>
141         <para>If true, requests that a stack backtrace (in brief format) be printed whenever the function is
142         invoked. The value can be an integer, in which case it is the maximum number of frames to
143         print. Otherwise, all frames are shown.
144         </para>
145       </listitem>
146     </varlistentry>
147
148
149
150   </variablelist>
151  </sect1>
152
153</chapter>
Note: See TracBrowser for help on using the repository browser.