Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

Diff of /pde.xmlf [f587e9] .. [9e7c20] Maximize Restore

  Switch to side-by-side view

--- a/pde.xmlf
+++ b/pde.xmlf
@@ -1,16 +1,92 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book [
-<!ENTITY % eclent SYSTEM "ecl.ent">
-%eclent;
-]>
-<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<chapter xml:id="Program-development">
- <title>Program Development Facilities</title>
-
-<section xml:id="The-stepper">
+<?xml version="1.0"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd">
+<book lang="en">
+<chapter id="Program-development">
+<title>Program Development Facilities</title>
+<section id="The-tracer">
+<title>The Tracer</title>
+<para>The Tracer causes selected <literal>functions</literal> to be traced.  When such a traced
+<literal>function</literal> is invoked, it prints</para>
+<screen>
+<replaceable>level</replaceable> &gt; (<replaceable>name   arg1   ...   argn</replaceable>)
+</screen>
+<para>On return from a traced <literal>function</literal>, it prints</para>
+<screen>
+&lt; <replaceable>level</replaceable>  (<replaceable>name   value1   ...   valuen</replaceable>)
+</screen>
+<para><replaceable>name</replaceable> is the name of the traced <literal>function</literal>, <replaceable>args</replaceable> are the
+arguments, and <replaceable>values</replaceable> are the return values.  <replaceable>level</replaceable> is a number
+which is incremented each time a traced <literal>function</literal> is invoked and is
+decremented at the completion of the invocation.  Trace print-outs are indented
+according to the <replaceable>level</replaceable>.</para>
+<para>In the current version of &ECL;, macros and special forms cannot be traced.</para>
+<blockquote>
+<screen><indexterm role="fn"><primary>trace</primary></indexterm>&mdash; Macro: <function>trace</function> <varname>{function-name | (function-name {&amp;key form}*)}*</varname></screen>
+<para>Causes one or more functions to be traced.  Each <replaceable>function-name</replaceable> must be a
+symbol which is not evaluated.  If a function is called from a compiled
+function in the same file, tracing will not be enabled.  If this is the case,
+to enable tracing, recompile the caller with a <literal>notinline</literal> declaration for
+the called function. <literal>trace</literal> returns a name list of those functions that
+were traced by the call to trace.  If no <replaceable>function-name</replaceable> is given,
+<literal>trace</literal> simply returns a name list of all the currently traced functions.</para>
+<para>Trace options can cause the normal printout to be suppressed, or cause extra
+information to be printed.  Each option is a pair of an option keyword and a
+value form. If an already traced function is traced again, any new options
+replace the old options.  <replaceable>form</replaceable> is an expression to be evaluated in an
+environment where <replaceable>sys::arglist</replaceable> is bound to the current list of arguments
+to the function.</para>
+<para>The following options are defined:</para>
+<variablelist>
+<varlistentry>
+<term><replaceable>:cond</replaceable> <replaceable>form</replaceable></term>
+<term><replaceable>:cond-before</replaceable> <replaceable>form</replaceable></term>
+<term><replaceable>:cond-after</replaceable> <replaceable>form</replaceable></term>
+<listitem>
+<para>If <replaceable>:cond-before</replaceable> is specified, then <literal>trace</literal> does nothing unless
+<replaceable>form</replaceable> evaluates to true at the time of the call.  <replaceable>:cond-after</replaceable> is
+similar, but suppresses the initial printout, and is tested when the function
+returns.  <replaceable>:cond</replaceable> tries both before and after.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><replaceable>:step</replaceable> <replaceable>form</replaceable></term>
+<listitem>
+<para>If <replaceable>form</replaceable> evaluates to true, the stepper is entered.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><replaceable>:break</replaceable> <replaceable>form</replaceable></term>
+<term><replaceable>:break-after</replaceable> <replaceable>form</replaceable></term>
+<listitem>
+<para>If specified, and <replaceable>form</replaceable> evaluates to true, then the debugger is invoked at
+the start of the function or at the end of the function according to the
+respective option.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><replaceable>:print</replaceable> <replaceable>form</replaceable></term>
+<term><replaceable>:print-after</replaceable> <replaceable>form</replaceable></term>
+<listitem>
+<para>In addition to the usual printout, the result of evaluating <replaceable>form</replaceable> is
+printed at the start of the function or at the end of the function, according
+to the respective option.  Multiple print options cause multiple values to be</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</blockquote>
+<blockquote>
+<screen><indexterm role="fn"><primary>untrace</primary></indexterm>&mdash; Macro: <function>untrace</function> <varname>{function-name}*</varname></screen>
+<para>Causes the specified functions to be not traced any more.  <replaceable>function-names</replaceable>
+must be symbols and they are not evaluated. <literal>untrace</literal> returns a name list
+of those functions that were untraced by the call to <literal>untrace</literal>.  If no
+<replaceable>function-name</replaceable> is given, <literal>untrace</literal> will untrace all the currently
+traced functions and will return a list of their names.</para>
+</blockquote>
+</section>
+
+<section id="The-stepper">
 <title>The Stepper</title>
 <blockquote>
-<screen><indexterm role="fn"><primary>step</primary></indexterm>&#151; Macro: <function>step</function> <varname>form</varname></screen>
+<screen><indexterm role="fn"><primary>step</primary></indexterm>&mdash; Macro: <function>step</function> <varname>form</varname></screen>
 <para>Starts evaluating the <replaceable>form</replaceable> in the single-step mode.  In this mode, before
 any form is evaluated, the Stepper will print the form and prompt the user for
 a Stepper command.  The Stepper binds the two variables print-level
@@ -79,10 +155,10 @@
 </variablelist>
 </section>
 
-<section xml:id="Errors">
+<section id="Errors">
 <title>Errors</title>
 <blockquote>
-<screen><indexterm role="vr"><primary>*break-enable*</primary></indexterm>&#151; Variable: <varname>*break-enable*</varname></screen>
+<screen><indexterm role="vr"><primary>*break-enable*</primary></indexterm>&mdash; Variable: <varname>*break-enable*</varname></screen>
 <para>This variable is used to determine whether to enter the break loop (see Section
 5.4) when an error occurs.  Even the function <literal>break</literal> checks this
 variable.  Initially, this variable is set to <replaceable>T</replaceable>, and thus an error will
@@ -99,7 +175,7 @@
 </blockquote>
 </section>
 
-<section xml:id="The-break-loop">
+<section id="The-break-loop">
 <title>The Break Loop</title>
 <para>The break loop is a read-eval-print loop similar to the top-level loop.  In
 addition to ordinary Lisp forms, the break loop accepts various commands with
@@ -184,13 +260,13 @@
 abbreviate <replaceable>:current</replaceable> as <replaceable>:c</replaceable>.  The break loop commands return no values
 at all.</para>
 <blockquote>
-<screen><indexterm role="fn"><primary>:current</primary></indexterm>&#151; Break Command: <function>:current</function></screen>
-<screen><indexterm role="fn"><primary>:c</primary></indexterm>&#151; Break Command: <function>:c</function> <varname></varname></screen>
+<screen><indexterm role="fn"><primary>:current</primary></indexterm>&mdash; Break Command: <function>:current</function></screen>
+<screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
 <para>Prints the event symbol of the current event.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:previous</primary></indexterm>&#151; Break Command: <function>:previous</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
-<screen><indexterm role="fn"><primary>:p</primary></indexterm>&#151; Break Command: <function>:p</function> <varname>&amp;optional n</varname></screen>
+<screen><indexterm role="fn"><primary>:previous</primary></indexterm>&mdash; Break Command: <function>:previous</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
+<screen><indexterm role="fn"><primary>:p</primary></indexterm>&mdash; Break Command: <function>:p</function> <varname>&amp;optional n</varname></screen>
 <para>Makes the <replaceable>n</replaceable>-th previous visible event the
 new current event.  Invisible events are not counted.  If there are
 less than <replaceable>n</replaceable> previous events, then the first visible event in the
@@ -198,8 +274,8 @@
 positive integer and the default is <literal>1</literal>.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:next</primary></indexterm>&#151; Break Command: <function>:next</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
-<screen><indexterm role="fn"><primary>:n</primary></indexterm>&#151; Break Command: <function>:n</function> <varname>&amp;optional n</varname></screen>
+<screen><indexterm role="fn"><primary>:next</primary></indexterm>&mdash; Break Command: <function>:next</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
+<screen><indexterm role="fn"><primary>:n</primary></indexterm>&mdash; Break Command: <function>:n</function> <varname>&amp;optional n</varname></screen>
 <para>Makes the <replaceable>n</replaceable>-th next visible event the
 new current event.  If there are less than <replaceable>n</replaceable> next events,
 then the last visible event in the invocation sequence
@@ -207,27 +283,27 @@
 default is <literal>1</literal>.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:backtrace</primary></indexterm>&#151; Break Command: <function>:backtrace</function></screen>
-<screen><indexterm role="fn"><primary>:b</primary></indexterm>&#151; Break Command: <function>:b</function> <varname></varname></screen>
+<screen><indexterm role="fn"><primary>:backtrace</primary></indexterm>&mdash; Break Command: <function>:backtrace</function></screen>
+<screen><indexterm role="fn"><primary>:b</primary></indexterm>&mdash; Break Command: <function>:b</function> <varname></varname></screen>
 <para>Prints the event symbols of all visible events in order.  The symbol of
 the current event is printed
 in upper-case letters and the event symbols of other events are in lower-case.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:help</primary></indexterm>&#151; Break Command: <function>:help</function></screen>
-<screen><indexterm role="fn"><primary>:h</primary></indexterm>&#151; Break Command: <function>:h</function> <varname></varname></screen>
+<screen><indexterm role="fn"><primary>:help</primary></indexterm>&mdash; Break Command: <function>:help</function></screen>
+<screen><indexterm role="fn"><primary>:h</primary></indexterm>&mdash; Break Command: <function>:h</function> <varname></varname></screen>
 <para>Lists the break loop commands.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:quit</primary></indexterm>&#151; Break Command: <function>:quit</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
-<screen><indexterm role="fn"><primary>:q</primary></indexterm>&#151; Break Command: <function>:q</function> <varname>&amp;optional n</varname></screen>
+<screen><indexterm role="fn"><primary>:quit</primary></indexterm>&mdash; Break Command: <function>:quit</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
+<screen><indexterm role="fn"><primary>:q</primary></indexterm>&mdash; Break Command: <function>:q</function> <varname>&amp;optional n</varname></screen>
 <para>Returns control to the level <replaceable>n</replaceable> break loop.  If <replaceable>n</replaceable> is 0 or if <replaceable>n</replaceable>
 is omitted, then control will return to the top-level loop. <replaceable>n</replaceable> must be a
 non-negative integer smaller than the current break level.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:continue</primary></indexterm>&#151; Break Command: <function>:continue</function></screen>
-<screen><indexterm role="fn"><primary>:c</primary></indexterm>&#151; Break Command: <function>:c</function> <varname></varname></screen>
+<screen><indexterm role="fn"><primary>:continue</primary></indexterm>&mdash; Break Command: <function>:continue</function></screen>
+<screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
 <para>Returns control to the caller of the break loop.  If the break loop has been
 entered from <literal>cerror</literal>, <literal>cerror</literal> returns () as its value and
 control will resume at that point.  Otherwise, this command returns control to
@@ -235,14 +311,14 @@
 is <literal>1</literal>).</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:variables</primary></indexterm>&#151; Break Command: <function>:variables</function></screen>
-<screen><indexterm role="fn"><primary>:v</primary></indexterm>&#151; Break Command: <function>:v</function> <varname></varname></screen>
+<screen><indexterm role="fn"><primary>:variables</primary></indexterm>&mdash; Break Command: <function>:variables</function></screen>
+<screen><indexterm role="fn"><primary>:v</primary></indexterm>&mdash; Break Command: <function>:v</function> <varname></varname></screen>
 <para>Prints the names of the bound variables in the current
 environment.  To see the value of a bound variable, just type the
 variable name.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:functions</primary></indexterm>&#151; Break Command: <function>:functions</function></screen>
+<screen><indexterm role="fn"><primary>:functions</primary></indexterm>&mdash; Break Command: <function>:functions</function></screen>
 <para>Prints the names of the local functions and local macros in the current
 environment.  To see the definition of a local function or macro, use the
 function special form in the usual way.  That is, <literal>(function <replaceable>name</replaceable>)</literal>
@@ -250,7 +326,7 @@
 <replaceable>name</replaceable>.  Local functions and local macros may be invoked as usual.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:blocks</primary></indexterm>&#151; Break Command: <function>:blocks</function></screen>
+<screen><indexterm role="fn"><primary>:blocks</primary></indexterm>&mdash; Break Command: <function>:blocks</function></screen>
 <para>Prints the names of the blocks established in the current environment.  If a
 block <replaceable>block</replaceable> is established, then the <literal>return-from</literal> form
 <literal>(return-from <replaceable>block value</replaceable>)</literal> works as usual.  That is, the block form
@@ -258,15 +334,15 @@
 will resume at that point.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:tags</primary></indexterm>&#151; Break Command: <function>:tags</function></screen>
+<screen><indexterm role="fn"><primary>:tags</primary></indexterm>&mdash; Break Command: <function>:tags</function></screen>
 <para>Prints the tags established in the current environment.  If a tag <replaceable>tag</replaceable> is
 established, then the <literal>go</literal> form <literal>(go <replaceable>tag</replaceable>)</literal> works as usual.
 That is, control will resume at the position of <replaceable>tag</replaceable> in the surrounding
 <literal>tagbody</literal>.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:local</primary></indexterm>&#151; Break Command: <function>:local</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
-<screen><indexterm role="fn"><primary>:l</primary></indexterm>&#151; Break Command: <function>:l</function> <varname>&amp;optional n</varname></screen>
+<screen><indexterm role="fn"><primary>:local</primary></indexterm>&mdash; Break Command: <function>:local</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
+<screen><indexterm role="fn"><primary>:l</primary></indexterm>&mdash; Break Command: <function>:l</function> <varname>&amp;optional n</varname></screen>
 <para>If <replaceable>n</replaceable> is <literal>0</literal> or if it is omitted, then this command prints the value
 stored in the main stack entry that is pointed to by the current event
 environment. <replaceable>n</replaceable> is an offset from that entry.  If <replaceable>n</replaceable> is positive,
@@ -277,7 +353,7 @@
 the bottom and the top of the stack.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:hide</primary></indexterm>&#151; Break Command: <function>:hide</function> <varname>symbol</varname></screen>
+<screen><indexterm role="fn"><primary>:hide</primary></indexterm>&mdash; Break Command: <function>:hide</function> <varname>symbol</varname></screen>
 <para>Hides all events whose event symbol is <replaceable>symbol</replaceable>.  In particular, by
 <literal>:hide 'lambda</literal> and <literal>hide 'lambda-closure</literal>, all events become
 invisible whose event functions are lambda-expressions and closures,
@@ -291,7 +367,7 @@
 events.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:hide-package</primary></indexterm>&#151; Break Command: <function>:hide-package</function> <varname>package</varname></screen>
+<screen><indexterm role="fn"><primary>:hide-package</primary></indexterm>&mdash; Break Command: <function>:hide-package</function> <varname>package</varname></screen>
 <para>Hides all events whose event symbol belongs to the package
 <replaceable>package</replaceable>. <replaceable>package</replaceable> may be any object that represents a package, i.e.,
 a package object, a symbol, or a string.  If the event symbol of the current
@@ -301,14 +377,14 @@
 not become invisible.  See the description of <replaceable>:hide</replaceable> above.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:unhide</primary></indexterm>&#151; Break Command: <function>:unhide</function> <varname>symbol</varname></screen>
+<screen><indexterm role="fn"><primary>:unhide</primary></indexterm>&mdash; Break Command: <function>:unhide</function> <varname>symbol</varname></screen>
 <para><replaceable>:unhide</replaceable> is the inverse command of <replaceable>:hide</replaceable>.  If, however, <replaceable> symbol</replaceable>
 belongs to one of the <replaceable>:hide-package</replaceable>d packages, events of <replaceable>symbol</replaceable>
 become visible only after the package is <literal>:unhide-package
 'd</literal>. <replaceable>symbol</replaceable> must be a symbol.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>:unhide-package</primary></indexterm>&#151; Break Command: <function>:unhide-package</function> <varname>package</varname></screen>
+<screen><indexterm role="fn"><primary>:unhide-package</primary></indexterm>&mdash; Break Command: <function>:unhide-package</function> <varname>package</varname></screen>
 <para><replaceable>:unhide-package</replaceable> is the inverse command of <replaceable>:hide-package</replaceable>.  However, an
 event whose event symbol belongs to <replaceable>package</replaceable> becomes visible only after
 the symbol is <literal>unhide 'd</literal>, if the symbol was <replaceable>:code 'd</replaceable>
@@ -390,10 +466,10 @@
 </screen></para>
 </section>
 
-<section xml:id="Describe-and-inspect">
+<section id="Describe-and-inspect">
 <title>Describe and Inspect</title>
 <blockquote>
-<screen><indexterm role="fn"><primary>describe</primary></indexterm>&#151; Function: <function>describe</function> <varname>object</varname></screen>
+<screen><indexterm role="fn"><primary>describe</primary></indexterm>&mdash; Function: <function>describe</function> <varname>object</varname></screen>
 <para>Prints the information about <replaceable>object</replaceable> to the stream that is the value of
 <literal>*standard-output*</literal>.  The description of an object consists of several
 fields, each of which is described in a recursive manner.  For example, a
@@ -402,7 +478,7 @@
 definition, properties.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>inspect</primary></indexterm>&#151; Function: <function>inspect</function> <varname>object</varname></screen>
+<screen><indexterm role="fn"><primary>inspect</primary></indexterm>&mdash; Function: <function>inspect</function> <varname>object</varname></screen>
 <para>Prints the information about <replaceable>object</replaceable> in an interactive manner.  The output
 of inspect is similar to that of <literal>describe</literal>, but after printing the label
 and the value of a field (the value itself is not <literal>describe 'd</literal>), it
@@ -468,12 +544,12 @@
 </blockquote>
 </section>
 
-<section xml:id="The-profiler">
+<section id="The-profiler">
 <title>The Profiler</title>
 <para>The profiler tool is enabled by default in the basic &ECL; configuration.  It
 can be disabled with the <literal>configure</literal> option <literal>--disable-profiler</literal>.</para>
 <blockquote>
-<screen><indexterm role="fn"><primary>profile</primary></indexterm>&#151; sys: <function>profile</function> <varname>grain</varname> <varname>&amp;optional</varname> <varname>address</varname></screen>
+<screen><indexterm role="fn"><primary>profile</primary></indexterm>&mdash; sys: <function>profile</function> <varname>grain</varname> <varname>&amp;optional</varname> <varname>address</varname></screen>
 <para>This function activates the profiling of subsequent executions.  <replaceable>grain</replaceable> is
 a value between 1 and 16384 which indicates the granularity of code segments to
 consider. There is a counter for each such segment.  With each clock tick, the
@@ -482,34 +558,34 @@
 indicates the base address for the code being profiled.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>display-profile</primary></indexterm>&#151; sys: <function>display-profile</function></screen>
+<screen><indexterm role="fn"><primary>display-profile</primary></indexterm>&mdash; sys: <function>display-profile</function></screen>
 <para>Displays the histogram of accumulated tick counts.  The ticks are attributed to
 the compiled Lisp function whose base address is closest to the start of the
 segment.  This may not be totally accurate for system functions which invoke
 some auxiliary function to do the job.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>clear-profile</primary></indexterm>&#151; sys: <function>clear-profile</function></screen>
+<screen><indexterm role="fn"><primary>clear-profile</primary></indexterm>&mdash; sys: <function>clear-profile</function></screen>
 <para>Clears the profile histogram.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="vr"><primary>sys</primary></indexterm>&#151; Variable: <varname>sys</varname> <type>*profile-array*</type></screen>
+<screen><indexterm role="vr"><primary>sys</primary></indexterm>&mdash; Variable: <varname>sys</varname> <type>*profile-array*</type></screen>
 <para>Contains the profile histogram: two short integer counters are packed in each
 value of this array of fixnums.</para>
 </blockquote>
 </section>
 
-<section xml:id="Online-help">
+<section id="Online-help">
 <title>Online Help</title>
 <para>Online help is provided by the following functions.</para>
 <blockquote>
-<screen><indexterm role="fn"><primary>help</primary></indexterm>&#151; Function: <function>help</function> <varname>&amp;optional symbol</varname></screen>
+<screen><indexterm role="fn"><primary>help</primary></indexterm>&mdash; Function: <function>help</function> <varname>&amp;optional symbol</varname></screen>
 <para><literal>help</literal> with no arguments prints a greeting message to &ECL; beginners.
 <literal>help</literal> with a symbol argument prints the documentation associated
 with the symbol.</para>
 </blockquote>
 <blockquote>
-<screen><indexterm role="fn"><primary>help*</primary></indexterm>&#151; Function: <function>help*</function> <varname>string &amp;optional package</varname></screen>
+<screen><indexterm role="fn"><primary>help*</primary></indexterm>&mdash; Function: <function>help*</function> <varname>string &amp;optional package</varname></screen>
 <para>Prints the documentation associated with those symbols in the specified
 <replaceable>package</replaceable> whose print names contain <replaceable>string</replaceable> as substring.
 <replaceable>string</replaceable> may be a symbol, in which case the print name of that symbol is