Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

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

  Switch to unified view

a/pde.xmlf b/pde.xmlf
1
<?xml version="1.0" encoding="utf-8"?>
1
<?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">
2
<!DOCTYPE book [
2
<book lang="en">
3
<!ENTITY % eclent SYSTEM "ecl.ent">
4
%eclent;
5
]>
6
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
7
<chapter xml:id="Program-development">
3
<chapter id="Program-development">
8
 <title>Program Development Facilities</title>
4
<title>Program Development Facilities</title>
5
<section id="The-tracer">
6
<title>The Tracer</title>
7
<para>The Tracer causes selected <literal>functions</literal> to be traced.  When such a traced
8
<literal>function</literal> is invoked, it prints</para>
9
<screen>
10
<replaceable>level</replaceable> &gt; (<replaceable>name   arg1   ...   argn</replaceable>)
11
</screen>
12
<para>On return from a traced <literal>function</literal>, it prints</para>
13
<screen>
14
&lt; <replaceable>level</replaceable>  (<replaceable>name   value1   ...   valuen</replaceable>)
15
</screen>
16
<para><replaceable>name</replaceable> is the name of the traced <literal>function</literal>, <replaceable>args</replaceable> are the
17
arguments, and <replaceable>values</replaceable> are the return values.  <replaceable>level</replaceable> is a number
18
which is incremented each time a traced <literal>function</literal> is invoked and is
19
decremented at the completion of the invocation.  Trace print-outs are indented
20
according to the <replaceable>level</replaceable>.</para>
21
<para>In the current version of &ECL;, macros and special forms cannot be traced.</para>
22
<blockquote>
23
<screen><indexterm role="fn"><primary>trace</primary></indexterm>&mdash; Macro: <function>trace</function> <varname>{function-name | (function-name {&amp;key form}*)}*</varname></screen>
24
<para>Causes one or more functions to be traced.  Each <replaceable>function-name</replaceable> must be a
25
symbol which is not evaluated.  If a function is called from a compiled
26
function in the same file, tracing will not be enabled.  If this is the case,
27
to enable tracing, recompile the caller with a <literal>notinline</literal> declaration for
28
the called function. <literal>trace</literal> returns a name list of those functions that
29
were traced by the call to trace.  If no <replaceable>function-name</replaceable> is given,
30
<literal>trace</literal> simply returns a name list of all the currently traced functions.</para>
31
<para>Trace options can cause the normal printout to be suppressed, or cause extra
32
information to be printed.  Each option is a pair of an option keyword and a
33
value form. If an already traced function is traced again, any new options
34
replace the old options.  <replaceable>form</replaceable> is an expression to be evaluated in an
35
environment where <replaceable>sys::arglist</replaceable> is bound to the current list of arguments
36
to the function.</para>
37
<para>The following options are defined:</para>
38
<variablelist>
39
<varlistentry>
40
<term><replaceable>:cond</replaceable> <replaceable>form</replaceable></term>
41
<term><replaceable>:cond-before</replaceable> <replaceable>form</replaceable></term>
42
<term><replaceable>:cond-after</replaceable> <replaceable>form</replaceable></term>
43
<listitem>
44
<para>If <replaceable>:cond-before</replaceable> is specified, then <literal>trace</literal> does nothing unless
45
<replaceable>form</replaceable> evaluates to true at the time of the call.  <replaceable>:cond-after</replaceable> is
46
similar, but suppresses the initial printout, and is tested when the function
47
returns.  <replaceable>:cond</replaceable> tries both before and after.</para>
48
</listitem>
49
</varlistentry>
50
<varlistentry>
51
<term><replaceable>:step</replaceable> <replaceable>form</replaceable></term>
52
<listitem>
53
<para>If <replaceable>form</replaceable> evaluates to true, the stepper is entered.</para>
54
</listitem>
55
</varlistentry>
56
<varlistentry>
57
<term><replaceable>:break</replaceable> <replaceable>form</replaceable></term>
58
<term><replaceable>:break-after</replaceable> <replaceable>form</replaceable></term>
59
<listitem>
60
<para>If specified, and <replaceable>form</replaceable> evaluates to true, then the debugger is invoked at
61
the start of the function or at the end of the function according to the
62
respective option.</para>
63
</listitem>
64
</varlistentry>
65
<varlistentry>
66
<term><replaceable>:print</replaceable> <replaceable>form</replaceable></term>
67
<term><replaceable>:print-after</replaceable> <replaceable>form</replaceable></term>
68
<listitem>
69
<para>In addition to the usual printout, the result of evaluating <replaceable>form</replaceable> is
70
printed at the start of the function or at the end of the function, according
71
to the respective option.  Multiple print options cause multiple values to be</para>
72
</listitem>
73
</varlistentry>
74
</variablelist>
75
</blockquote>
76
<blockquote>
77
<screen><indexterm role="fn"><primary>untrace</primary></indexterm>&mdash; Macro: <function>untrace</function> <varname>{function-name}*</varname></screen>
78
<para>Causes the specified functions to be not traced any more.  <replaceable>function-names</replaceable>
79
must be symbols and they are not evaluated. <literal>untrace</literal> returns a name list
80
of those functions that were untraced by the call to <literal>untrace</literal>.  If no
81
<replaceable>function-name</replaceable> is given, <literal>untrace</literal> will untrace all the currently
82
traced functions and will return a list of their names.</para>
83
</blockquote>
84
</section>
9
85
10
<section xml:id="The-stepper">
86
<section id="The-stepper">
11
<title>The Stepper</title>
87
<title>The Stepper</title>
12
<blockquote>
88
<blockquote>
13
<screen><indexterm role="fn"><primary>step</primary></indexterm>&#151; Macro: <function>step</function> <varname>form</varname></screen>
89
<screen><indexterm role="fn"><primary>step</primary></indexterm>&mdash; Macro: <function>step</function> <varname>form</varname></screen>
14
<para>Starts evaluating the <replaceable>form</replaceable> in the single-step mode.  In this mode, before
90
<para>Starts evaluating the <replaceable>form</replaceable> in the single-step mode.  In this mode, before
15
any form is evaluated, the Stepper will print the form and prompt the user for
91
any form is evaluated, the Stepper will print the form and prompt the user for
16
a Stepper command.  The Stepper binds the two variables print-level
92
a Stepper command.  The Stepper binds the two variables print-level
17
and print-length both to <literal>2</literal>, so that the current form may not
93
and print-length both to <literal>2</literal>, so that the current form may not
18
occupy too much space on the screen.  A Stepper command will be executed when
94
occupy too much space on the screen.  A Stepper command will be executed when
...
...
77
</listitem>
153
</listitem>
78
</varlistentry>
154
</varlistentry>
79
</variablelist>
155
</variablelist>
80
</section>
156
</section>
81
157
82
<section xml:id="Errors">
158
<section id="Errors">
83
<title>Errors</title>
159
<title>Errors</title>
84
<blockquote>
160
<blockquote>
85
<screen><indexterm role="vr"><primary>*break-enable*</primary></indexterm>&#151; Variable: <varname>*break-enable*</varname></screen>
161
<screen><indexterm role="vr"><primary>*break-enable*</primary></indexterm>&mdash; Variable: <varname>*break-enable*</varname></screen>
86
<para>This variable is used to determine whether to enter the break loop (see Section
162
<para>This variable is used to determine whether to enter the break loop (see Section
87
5.4) when an error occurs.  Even the function <literal>break</literal> checks this
163
5.4) when an error occurs.  Even the function <literal>break</literal> checks this
88
variable.  Initially, this variable is set to <replaceable>T</replaceable>, and thus an error will
164
variable.  Initially, this variable is set to <replaceable>T</replaceable>, and thus an error will
89
invoke the break loop.  If the value is (), functions that cause fatal
165
invoke the break loop.  If the value is (), functions that cause fatal
90
errors, such as <literal> error</literal>, will just print an error message and control
166
errors, such as <literal> error</literal>, will just print an error message and control
...
...
97
<para>When the break loop is entered, break-enable will be bound to
173
<para>When the break loop is entered, break-enable will be bound to
98
().</para>
174
().</para>
99
</blockquote>
175
</blockquote>
100
</section>
176
</section>
101
177
102
<section xml:id="The-break-loop">
178
<section id="The-break-loop">
103
<title>The Break Loop</title>
179
<title>The Break Loop</title>
104
<para>The break loop is a read-eval-print loop similar to the top-level loop.  In
180
<para>The break loop is a read-eval-print loop similar to the top-level loop.  In
105
addition to ordinary Lisp forms, the break loop accepts various commands with
181
addition to ordinary Lisp forms, the break loop accepts various commands with
106
which the user can inspect and modify the state of the program execution.  Each
182
which the user can inspect and modify the state of the program execution.  Each
107
break loop command is identified with a keyword (i.e., a symbol in the
183
break loop command is identified with a keyword (i.e., a symbol in the
...
...
182
<para>The break loop commands are described below.  Some of the commands allow
258
<para>The break loop commands are described below.  Some of the commands allow
183
abbreviation in the keywords that identify them.  For example, the user may
259
abbreviation in the keywords that identify them.  For example, the user may
184
abbreviate <replaceable>:current</replaceable> as <replaceable>:c</replaceable>.  The break loop commands return no values
260
abbreviate <replaceable>:current</replaceable> as <replaceable>:c</replaceable>.  The break loop commands return no values
185
at all.</para>
261
at all.</para>
186
<blockquote>
262
<blockquote>
187
<screen><indexterm role="fn"><primary>:current</primary></indexterm>&#151; Break Command: <function>:current</function></screen>
263
<screen><indexterm role="fn"><primary>:current</primary></indexterm>&mdash; Break Command: <function>:current</function></screen>
188
<screen><indexterm role="fn"><primary>:c</primary></indexterm>&#151; Break Command: <function>:c</function> <varname></varname></screen>
264
<screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
189
<para>Prints the event symbol of the current event.</para>
265
<para>Prints the event symbol of the current event.</para>
190
</blockquote>
266
</blockquote>
191
<blockquote>
267
<blockquote>
192
<screen><indexterm role="fn"><primary>:previous</primary></indexterm>&#151; Break Command: <function>:previous</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
268
<screen><indexterm role="fn"><primary>:previous</primary></indexterm>&mdash; Break Command: <function>:previous</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
193
<screen><indexterm role="fn"><primary>:p</primary></indexterm>&#151; Break Command: <function>:p</function> <varname>&amp;optional n</varname></screen>
269
<screen><indexterm role="fn"><primary>:p</primary></indexterm>&mdash; Break Command: <function>:p</function> <varname>&amp;optional n</varname></screen>
194
<para>Makes the <replaceable>n</replaceable>-th previous visible event the
270
<para>Makes the <replaceable>n</replaceable>-th previous visible event the
195
new current event.  Invisible events are not counted.  If there are
271
new current event.  Invisible events are not counted.  If there are
196
less than <replaceable>n</replaceable> previous events, then the first visible event in the
272
less than <replaceable>n</replaceable> previous events, then the first visible event in the
197
invocation sequence becomes the new current event. <replaceable>n</replaceable> must be a
273
invocation sequence becomes the new current event. <replaceable>n</replaceable> must be a
198
positive integer and the default is <literal>1</literal>.</para>
274
positive integer and the default is <literal>1</literal>.</para>
199
</blockquote>
275
</blockquote>
200
<blockquote>
276
<blockquote>
201
<screen><indexterm role="fn"><primary>:next</primary></indexterm>&#151; Break Command: <function>:next</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
277
<screen><indexterm role="fn"><primary>:next</primary></indexterm>&mdash; Break Command: <function>:next</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
202
<screen><indexterm role="fn"><primary>:n</primary></indexterm>&#151; Break Command: <function>:n</function> <varname>&amp;optional n</varname></screen>
278
<screen><indexterm role="fn"><primary>:n</primary></indexterm>&mdash; Break Command: <function>:n</function> <varname>&amp;optional n</varname></screen>
203
<para>Makes the <replaceable>n</replaceable>-th next visible event the
279
<para>Makes the <replaceable>n</replaceable>-th next visible event the
204
new current event.  If there are less than <replaceable>n</replaceable> next events,
280
new current event.  If there are less than <replaceable>n</replaceable> next events,
205
then the last visible event in the invocation sequence
281
then the last visible event in the invocation sequence
206
becomes the new current event. <replaceable>n</replaceable>  must be a positive integer and the
282
becomes the new current event. <replaceable>n</replaceable>  must be a positive integer and the
207
default is <literal>1</literal>.</para>
283
default is <literal>1</literal>.</para>
208
</blockquote>
284
</blockquote>
209
<blockquote>
285
<blockquote>
210
<screen><indexterm role="fn"><primary>:backtrace</primary></indexterm>&#151; Break Command: <function>:backtrace</function></screen>
286
<screen><indexterm role="fn"><primary>:backtrace</primary></indexterm>&mdash; Break Command: <function>:backtrace</function></screen>
211
<screen><indexterm role="fn"><primary>:b</primary></indexterm>&#151; Break Command: <function>:b</function> <varname></varname></screen>
287
<screen><indexterm role="fn"><primary>:b</primary></indexterm>&mdash; Break Command: <function>:b</function> <varname></varname></screen>
212
<para>Prints the event symbols of all visible events in order.  The symbol of
288
<para>Prints the event symbols of all visible events in order.  The symbol of
213
the current event is printed
289
the current event is printed
214
in upper-case letters and the event symbols of other events are in lower-case.</para>
290
in upper-case letters and the event symbols of other events are in lower-case.</para>
215
</blockquote>
291
</blockquote>
216
<blockquote>
292
<blockquote>
217
<screen><indexterm role="fn"><primary>:help</primary></indexterm>&#151; Break Command: <function>:help</function></screen>
293
<screen><indexterm role="fn"><primary>:help</primary></indexterm>&mdash; Break Command: <function>:help</function></screen>
218
<screen><indexterm role="fn"><primary>:h</primary></indexterm>&#151; Break Command: <function>:h</function> <varname></varname></screen>
294
<screen><indexterm role="fn"><primary>:h</primary></indexterm>&mdash; Break Command: <function>:h</function> <varname></varname></screen>
219
<para>Lists the break loop commands.</para>
295
<para>Lists the break loop commands.</para>
220
</blockquote>
296
</blockquote>
221
<blockquote>
297
<blockquote>
222
<screen><indexterm role="fn"><primary>:quit</primary></indexterm>&#151; Break Command: <function>:quit</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
298
<screen><indexterm role="fn"><primary>:quit</primary></indexterm>&mdash; Break Command: <function>:quit</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
223
<screen><indexterm role="fn"><primary>:q</primary></indexterm>&#151; Break Command: <function>:q</function> <varname>&amp;optional n</varname></screen>
299
<screen><indexterm role="fn"><primary>:q</primary></indexterm>&mdash; Break Command: <function>:q</function> <varname>&amp;optional n</varname></screen>
224
<para>Returns control to the level <replaceable>n</replaceable> break loop.  If <replaceable>n</replaceable> is 0 or if <replaceable>n</replaceable>
300
<para>Returns control to the level <replaceable>n</replaceable> break loop.  If <replaceable>n</replaceable> is 0 or if <replaceable>n</replaceable>
225
is omitted, then control will return to the top-level loop. <replaceable>n</replaceable> must be a
301
is omitted, then control will return to the top-level loop. <replaceable>n</replaceable> must be a
226
non-negative integer smaller than the current break level.</para>
302
non-negative integer smaller than the current break level.</para>
227
</blockquote>
303
</blockquote>
228
<blockquote>
304
<blockquote>
229
<screen><indexterm role="fn"><primary>:continue</primary></indexterm>&#151; Break Command: <function>:continue</function></screen>
305
<screen><indexterm role="fn"><primary>:continue</primary></indexterm>&mdash; Break Command: <function>:continue</function></screen>
230
<screen><indexterm role="fn"><primary>:c</primary></indexterm>&#151; Break Command: <function>:c</function> <varname></varname></screen>
306
<screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
231
<para>Returns control to the caller of the break loop.  If the break loop has been
307
<para>Returns control to the caller of the break loop.  If the break loop has been
232
entered from <literal>cerror</literal>, <literal>cerror</literal> returns () as its value and
308
entered from <literal>cerror</literal>, <literal>cerror</literal> returns () as its value and
233
control will resume at that point.  Otherwise, this command returns control to
309
control will resume at that point.  Otherwise, this command returns control to
234
the previous break loop (or to the top-level loop, if the current break level
310
the previous break loop (or to the top-level loop, if the current break level
235
is <literal>1</literal>).</para>
311
is <literal>1</literal>).</para>
236
</blockquote>
312
</blockquote>
237
<blockquote>
313
<blockquote>
238
<screen><indexterm role="fn"><primary>:variables</primary></indexterm>&#151; Break Command: <function>:variables</function></screen>
314
<screen><indexterm role="fn"><primary>:variables</primary></indexterm>&mdash; Break Command: <function>:variables</function></screen>
239
<screen><indexterm role="fn"><primary>:v</primary></indexterm>&#151; Break Command: <function>:v</function> <varname></varname></screen>
315
<screen><indexterm role="fn"><primary>:v</primary></indexterm>&mdash; Break Command: <function>:v</function> <varname></varname></screen>
240
<para>Prints the names of the bound variables in the current
316
<para>Prints the names of the bound variables in the current
241
environment.  To see the value of a bound variable, just type the
317
environment.  To see the value of a bound variable, just type the
242
variable name.</para>
318
variable name.</para>
243
</blockquote>
319
</blockquote>
244
<blockquote>
320
<blockquote>
245
<screen><indexterm role="fn"><primary>:functions</primary></indexterm>&#151; Break Command: <function>:functions</function></screen>
321
<screen><indexterm role="fn"><primary>:functions</primary></indexterm>&mdash; Break Command: <function>:functions</function></screen>
246
<para>Prints the names of the local functions and local macros in the current
322
<para>Prints the names of the local functions and local macros in the current
247
environment.  To see the definition of a local function or macro, use the
323
environment.  To see the definition of a local function or macro, use the
248
function special form in the usual way.  That is, <literal>(function <replaceable>name</replaceable>)</literal>
324
function special form in the usual way.  That is, <literal>(function <replaceable>name</replaceable>)</literal>
249
will return the definition of the local function or macro whose name is
325
will return the definition of the local function or macro whose name is
250
<replaceable>name</replaceable>.  Local functions and local macros may be invoked as usual.</para>
326
<replaceable>name</replaceable>.  Local functions and local macros may be invoked as usual.</para>
251
</blockquote>
327
</blockquote>
252
<blockquote>
328
<blockquote>
253
<screen><indexterm role="fn"><primary>:blocks</primary></indexterm>&#151; Break Command: <function>:blocks</function></screen>
329
<screen><indexterm role="fn"><primary>:blocks</primary></indexterm>&mdash; Break Command: <function>:blocks</function></screen>
254
<para>Prints the names of the blocks established in the current environment.  If a
330
<para>Prints the names of the blocks established in the current environment.  If a
255
block <replaceable>block</replaceable> is established, then the <literal>return-from</literal> form
331
block <replaceable>block</replaceable> is established, then the <literal>return-from</literal> form
256
<literal>(return-from <replaceable>block value</replaceable>)</literal> works as usual.  That is, the block form
332
<literal>(return-from <replaceable>block value</replaceable>)</literal> works as usual.  That is, the block form
257
that established <replaceable>block</replaceable> will return <replaceable>value</replaceable> as its value and control
333
that established <replaceable>block</replaceable> will return <replaceable>value</replaceable> as its value and control
258
will resume at that point.</para>
334
will resume at that point.</para>
259
</blockquote>
335
</blockquote>
260
<blockquote>
336
<blockquote>
261
<screen><indexterm role="fn"><primary>:tags</primary></indexterm>&#151; Break Command: <function>:tags</function></screen>
337
<screen><indexterm role="fn"><primary>:tags</primary></indexterm>&mdash; Break Command: <function>:tags</function></screen>
262
<para>Prints the tags established in the current environment.  If a tag <replaceable>tag</replaceable> is
338
<para>Prints the tags established in the current environment.  If a tag <replaceable>tag</replaceable> is
263
established, then the <literal>go</literal> form <literal>(go <replaceable>tag</replaceable>)</literal> works as usual.
339
established, then the <literal>go</literal> form <literal>(go <replaceable>tag</replaceable>)</literal> works as usual.
264
That is, control will resume at the position of <replaceable>tag</replaceable> in the surrounding
340
That is, control will resume at the position of <replaceable>tag</replaceable> in the surrounding
265
<literal>tagbody</literal>.</para>
341
<literal>tagbody</literal>.</para>
266
</blockquote>
342
</blockquote>
267
<blockquote>
343
<blockquote>
268
<screen><indexterm role="fn"><primary>:local</primary></indexterm>&#151; Break Command: <function>:local</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
344
<screen><indexterm role="fn"><primary>:local</primary></indexterm>&mdash; Break Command: <function>:local</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
269
<screen><indexterm role="fn"><primary>:l</primary></indexterm>&#151; Break Command: <function>:l</function> <varname>&amp;optional n</varname></screen>
345
<screen><indexterm role="fn"><primary>:l</primary></indexterm>&mdash; Break Command: <function>:l</function> <varname>&amp;optional n</varname></screen>
270
<para>If <replaceable>n</replaceable> is <literal>0</literal> or if it is omitted, then this command prints the value
346
<para>If <replaceable>n</replaceable> is <literal>0</literal> or if it is omitted, then this command prints the value
271
stored in the main stack entry that is pointed to by the current event
347
stored in the main stack entry that is pointed to by the current event
272
environment. <replaceable>n</replaceable> is an offset from that entry.  If <replaceable>n</replaceable> is positive,
348
environment. <replaceable>n</replaceable> is an offset from that entry.  If <replaceable>n</replaceable> is positive,
273
then the value of the <emphasis>n</emphasis>-th next (i.e., toward the top of the main stack)
349
then the value of the <emphasis>n</emphasis>-th next (i.e., toward the top of the main stack)
274
entry is printed.  If <replaceable>n</replaceable> is negative, then the value of the <replaceable>n</replaceable>-th
350
entry is printed.  If <replaceable>n</replaceable> is negative, then the value of the <replaceable>n</replaceable>-th
275
previous (i.e., toward the bottom of the main stack) entry is printed. <replaceable>n</replaceable>
351
previous (i.e., toward the bottom of the main stack) entry is printed. <replaceable>n</replaceable>
276
must be an integer.  It is an error if the specified entry does not lie between
352
must be an integer.  It is an error if the specified entry does not lie between
277
the bottom and the top of the stack.</para>
353
the bottom and the top of the stack.</para>
278
</blockquote>
354
</blockquote>
279
<blockquote>
355
<blockquote>
280
<screen><indexterm role="fn"><primary>:hide</primary></indexterm>&#151; Break Command: <function>:hide</function> <varname>symbol</varname></screen>
356
<screen><indexterm role="fn"><primary>:hide</primary></indexterm>&mdash; Break Command: <function>:hide</function> <varname>symbol</varname></screen>
281
<para>Hides all events whose event symbol is <replaceable>symbol</replaceable>.  In particular, by
357
<para>Hides all events whose event symbol is <replaceable>symbol</replaceable>.  In particular, by
282
<literal>:hide 'lambda</literal> and <literal>hide 'lambda-closure</literal>, all events become
358
<literal>:hide 'lambda</literal> and <literal>hide 'lambda-closure</literal>, all events become
283
invisible whose event functions are lambda-expressions and closures,
359
invisible whose event functions are lambda-expressions and closures,
284
respectively.  If the event symbol of the current event happens to be
360
respectively.  If the event symbol of the current event happens to be
285
<replaceable>symbol</replaceable>, then the last previous visible event will become the new current
361
<replaceable>symbol</replaceable>, then the last previous visible event will become the new current
...
...
289
event function is either <literal>eval</literal> or <literal>evalhook</literal>.  Keeping both of them
365
event function is either <literal>eval</literal> or <literal>evalhook</literal>.  Keeping both of them
290
visible is the simplest way to avoid the silly attempts of the user to hide all
366
visible is the simplest way to avoid the silly attempts of the user to hide all
291
events.</para>
367
events.</para>
292
</blockquote>
368
</blockquote>
293
<blockquote>
369
<blockquote>
294
<screen><indexterm role="fn"><primary>:hide-package</primary></indexterm>&#151; Break Command: <function>:hide-package</function> <varname>package</varname></screen>
370
<screen><indexterm role="fn"><primary>:hide-package</primary></indexterm>&mdash; Break Command: <function>:hide-package</function> <varname>package</varname></screen>
295
<para>Hides all events whose event symbol belongs to the package
371
<para>Hides all events whose event symbol belongs to the package
296
<replaceable>package</replaceable>. <replaceable>package</replaceable> may be any object that represents a package, i.e.,
372
<replaceable>package</replaceable>. <replaceable>package</replaceable> may be any object that represents a package, i.e.,
297
a package object, a symbol, or a string.  If the event symbol of the current
373
a package object, a symbol, or a string.  If the event symbol of the current
298
event happens to belong to the package <replaceable>package</replaceable>, then the last previous
374
event happens to belong to the package <replaceable>package</replaceable>, then the last previous
299
visible event will become the new current event.  Even if <literal>lisp</literal> package
375
visible event will become the new current event.  Even if <literal>lisp</literal> package
300
was specified as <replaceable>package</replaceable>, events of <literal>eval</literal> and <literal>evalhook</literal> do
376
was specified as <replaceable>package</replaceable>, events of <literal>eval</literal> and <literal>evalhook</literal> do
301
not become invisible.  See the description of <replaceable>:hide</replaceable> above.</para>
377
not become invisible.  See the description of <replaceable>:hide</replaceable> above.</para>
302
</blockquote>
378
</blockquote>
303
<blockquote>
379
<blockquote>
304
<screen><indexterm role="fn"><primary>:unhide</primary></indexterm>&#151; Break Command: <function>:unhide</function> <varname>symbol</varname></screen>
380
<screen><indexterm role="fn"><primary>:unhide</primary></indexterm>&mdash; Break Command: <function>:unhide</function> <varname>symbol</varname></screen>
305
<para><replaceable>:unhide</replaceable> is the inverse command of <replaceable>:hide</replaceable>.  If, however, <replaceable> symbol</replaceable>
381
<para><replaceable>:unhide</replaceable> is the inverse command of <replaceable>:hide</replaceable>.  If, however, <replaceable> symbol</replaceable>
306
belongs to one of the <replaceable>:hide-package</replaceable>d packages, events of <replaceable>symbol</replaceable>
382
belongs to one of the <replaceable>:hide-package</replaceable>d packages, events of <replaceable>symbol</replaceable>
307
become visible only after the package is <literal>:unhide-package
383
become visible only after the package is <literal>:unhide-package
308
'd</literal>. <replaceable>symbol</replaceable> must be a symbol.</para>
384
'd</literal>. <replaceable>symbol</replaceable> must be a symbol.</para>
309
</blockquote>
385
</blockquote>
310
<blockquote>
386
<blockquote>
311
<screen><indexterm role="fn"><primary>:unhide-package</primary></indexterm>&#151; Break Command: <function>:unhide-package</function> <varname>package</varname></screen>
387
<screen><indexterm role="fn"><primary>:unhide-package</primary></indexterm>&mdash; Break Command: <function>:unhide-package</function> <varname>package</varname></screen>
312
<para><replaceable>:unhide-package</replaceable> is the inverse command of <replaceable>:hide-package</replaceable>.  However, an
388
<para><replaceable>:unhide-package</replaceable> is the inverse command of <replaceable>:hide-package</replaceable>.  However, an
313
event whose event symbol belongs to <replaceable>package</replaceable> becomes visible only after
389
event whose event symbol belongs to <replaceable>package</replaceable> becomes visible only after
314
the symbol is <literal>unhide 'd</literal>, if the symbol was <replaceable>:code 'd</replaceable>
390
the symbol is <literal>unhide 'd</literal>, if the symbol was <replaceable>:code 'd</replaceable>
315
before. <replaceable>package</replaceable> may be any object that represents a package, i.e., a
391
before. <replaceable>package</replaceable> may be any object that represents a package, i.e., a
316
package object, a symbol, or a string.</para>
392
package object, a symbol, or a string.</para>
...
...
388
464
389
&gt;                      ;;;  Top-level.
465
&gt;                      ;;;  Top-level.
390
</screen></para>
466
</screen></para>
391
</section>
467
</section>
392
468
393
<section xml:id="Describe-and-inspect">
469
<section id="Describe-and-inspect">
394
<title>Describe and Inspect</title>
470
<title>Describe and Inspect</title>
395
<blockquote>
471
<blockquote>
396
<screen><indexterm role="fn"><primary>describe</primary></indexterm>&#151; Function: <function>describe</function> <varname>object</varname></screen>
472
<screen><indexterm role="fn"><primary>describe</primary></indexterm>&mdash; Function: <function>describe</function> <varname>object</varname></screen>
397
<para>Prints the information about <replaceable>object</replaceable> to the stream that is the value of
473
<para>Prints the information about <replaceable>object</replaceable> to the stream that is the value of
398
<literal>*standard-output*</literal>.  The description of an object consists of several
474
<literal>*standard-output*</literal>.  The description of an object consists of several
399
fields, each of which is described in a recursive manner.  For example, a
475
fields, each of which is described in a recursive manner.  For example, a
400
symbol may have fields such as home package, variable documentation, value,
476
symbol may have fields such as home package, variable documentation, value,
401
function documentation, function binding, type documentation, <literal>deftype</literal>
477
function documentation, function binding, type documentation, <literal>deftype</literal>
402
definition, properties.</para>
478
definition, properties.</para>
403
</blockquote>
479
</blockquote>
404
<blockquote>
480
<blockquote>
405
<screen><indexterm role="fn"><primary>inspect</primary></indexterm>&#151; Function: <function>inspect</function> <varname>object</varname></screen>
481
<screen><indexterm role="fn"><primary>inspect</primary></indexterm>&mdash; Function: <function>inspect</function> <varname>object</varname></screen>
406
<para>Prints the information about <replaceable>object</replaceable> in an interactive manner.  The output
482
<para>Prints the information about <replaceable>object</replaceable> in an interactive manner.  The output
407
of inspect is similar to that of <literal>describe</literal>, but after printing the label
483
of inspect is similar to that of <literal>describe</literal>, but after printing the label
408
and the value of a field (the value itself is not <literal>describe 'd</literal>), it
484
and the value of a field (the value itself is not <literal>describe 'd</literal>), it
409
prompts the user to input a one-character command.  The input to <literal>inspect</literal>
485
prompts the user to input a one-character command.  The input to <literal>inspect</literal>
410
is taken from the stream that is the value of <literal>*query-io*</literal>.  Normally, the
486
is taken from the stream that is the value of <literal>*query-io*</literal>.  Normally, the
...
...
466
</varlistentry>
542
</varlistentry>
467
</variablelist>
543
</variablelist>
468
</blockquote>
544
</blockquote>
469
</section>
545
</section>
470
546
471
<section xml:id="The-profiler">
547
<section id="The-profiler">
472
<title>The Profiler</title>
548
<title>The Profiler</title>
473
<para>The profiler tool is enabled by default in the basic &ECL; configuration.  It
549
<para>The profiler tool is enabled by default in the basic &ECL; configuration.  It
474
can be disabled with the <literal>configure</literal> option <literal>--disable-profiler</literal>.</para>
550
can be disabled with the <literal>configure</literal> option <literal>--disable-profiler</literal>.</para>
475
<blockquote>
551
<blockquote>
476
<screen><indexterm role="fn"><primary>profile</primary></indexterm>&#151; sys: <function>profile</function> <varname>grain</varname> <varname>&amp;optional</varname> <varname>address</varname></screen>
552
<screen><indexterm role="fn"><primary>profile</primary></indexterm>&mdash; sys: <function>profile</function> <varname>grain</varname> <varname>&amp;optional</varname> <varname>address</varname></screen>
477
<para>This function activates the profiling of subsequent executions.  <replaceable>grain</replaceable> is
553
<para>This function activates the profiling of subsequent executions.  <replaceable>grain</replaceable> is
478
a value between 1 and 16384 which indicates the granularity of code segments to
554
a value between 1 and 16384 which indicates the granularity of code segments to
479
consider. There is a counter for each such segment.  With each clock tick, the
555
consider. There is a counter for each such segment.  With each clock tick, the
480
current segment is identified and its corresponding histogram count is
556
current segment is identified and its corresponding histogram count is
481
incremented.  A value of 0 for <replaceable>grain</replaceable> means stop profiling.  <replaceable>address</replaceable>
557
incremented.  A value of 0 for <replaceable>grain</replaceable> means stop profiling.  <replaceable>address</replaceable>
482
indicates the base address for the code being profiled.</para>
558
indicates the base address for the code being profiled.</para>
483
</blockquote>
559
</blockquote>
484
<blockquote>
560
<blockquote>
485
<screen><indexterm role="fn"><primary>display-profile</primary></indexterm>&#151; sys: <function>display-profile</function></screen>
561
<screen><indexterm role="fn"><primary>display-profile</primary></indexterm>&mdash; sys: <function>display-profile</function></screen>
486
<para>Displays the histogram of accumulated tick counts.  The ticks are attributed to
562
<para>Displays the histogram of accumulated tick counts.  The ticks are attributed to
487
the compiled Lisp function whose base address is closest to the start of the
563
the compiled Lisp function whose base address is closest to the start of the
488
segment.  This may not be totally accurate for system functions which invoke
564
segment.  This may not be totally accurate for system functions which invoke
489
some auxiliary function to do the job.</para>
565
some auxiliary function to do the job.</para>
490
</blockquote>
566
</blockquote>
491
<blockquote>
567
<blockquote>
492
<screen><indexterm role="fn"><primary>clear-profile</primary></indexterm>&#151; sys: <function>clear-profile</function></screen>
568
<screen><indexterm role="fn"><primary>clear-profile</primary></indexterm>&mdash; sys: <function>clear-profile</function></screen>
493
<para>Clears the profile histogram.</para>
569
<para>Clears the profile histogram.</para>
494
</blockquote>
570
</blockquote>
495
<blockquote>
571
<blockquote>
496
<screen><indexterm role="vr"><primary>sys</primary></indexterm>&#151; Variable: <varname>sys</varname> <type>*profile-array*</type></screen>
572
<screen><indexterm role="vr"><primary>sys</primary></indexterm>&mdash; Variable: <varname>sys</varname> <type>*profile-array*</type></screen>
497
<para>Contains the profile histogram: two short integer counters are packed in each
573
<para>Contains the profile histogram: two short integer counters are packed in each
498
value of this array of fixnums.</para>
574
value of this array of fixnums.</para>
499
</blockquote>
575
</blockquote>
500
</section>
576
</section>
501
577
502
<section xml:id="Online-help">
578
<section id="Online-help">
503
<title>Online Help</title>
579
<title>Online Help</title>
504
<para>Online help is provided by the following functions.</para>
580
<para>Online help is provided by the following functions.</para>
505
<blockquote>
581
<blockquote>
506
<screen><indexterm role="fn"><primary>help</primary></indexterm>&#151; Function: <function>help</function> <varname>&amp;optional symbol</varname></screen>
582
<screen><indexterm role="fn"><primary>help</primary></indexterm>&mdash; Function: <function>help</function> <varname>&amp;optional symbol</varname></screen>
507
<para><literal>help</literal> with no arguments prints a greeting message to &ECL; beginners.
583
<para><literal>help</literal> with no arguments prints a greeting message to &ECL; beginners.
508
<literal>help</literal> with a symbol argument prints the documentation associated
584
<literal>help</literal> with a symbol argument prints the documentation associated
509
with the symbol.</para>
585
with the symbol.</para>
510
</blockquote>
586
</blockquote>
511
<blockquote>
587
<blockquote>
512
<screen><indexterm role="fn"><primary>help*</primary></indexterm>&#151; Function: <function>help*</function> <varname>string &amp;optional package</varname></screen>
588
<screen><indexterm role="fn"><primary>help*</primary></indexterm>&mdash; Function: <function>help*</function> <varname>string &amp;optional package</varname></screen>
513
<para>Prints the documentation associated with those symbols in the specified
589
<para>Prints the documentation associated with those symbols in the specified
514
<replaceable>package</replaceable> whose print names contain <replaceable>string</replaceable> as substring.
590
<replaceable>package</replaceable> whose print names contain <replaceable>string</replaceable> as substring.
515
<replaceable>string</replaceable> may be a symbol, in which case the print name of that symbol is
591
<replaceable>string</replaceable> may be a symbol, in which case the print name of that symbol is
516
used. <replaceable>package</replaceable> is optional and defaults to the LISP package.
592
used. <replaceable>package</replaceable> is optional and defaults to the LISP package.
517
If <replaceable>package</replaceable> is (), then all packages are searched.</para>
593
If <replaceable>package</replaceable> is (), then all packages are searched.</para>