ViewVC logotype

Contents of /ecl-doc/pde.xmlf

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (show annotations)
Wed Oct 25 15:32:28 2006 UTC (7 years, 5 months ago) by jgarcia
Branch: MAIN
Changes since 1.1: +1 -81 lines
Added a license, the UFFI reference, and several manual pages. Improved CSS with respect to padding, table widths and look of <pre> sections.
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 <book lang="en">
3 <chapter id="Program-development">
4 <title>Program Development Facilities</title>
6 <section id="The-stepper">
7 <title>The Stepper</title>
8 <blockquote>
9 <screen><indexterm role="fn"><primary>step</primary></indexterm>&mdash; Macro: <function>step</function> <varname>form</varname></screen>
10 <para>Starts evaluating the <replaceable>form</replaceable> in the single-step mode. In this mode, before
11 any form is evaluated, the Stepper will print the form and prompt the user for
12 a Stepper command. The Stepper binds the two variables print-level
13 and print-length both to <literal>2</literal>, so that the current form may not
14 occupy too much space on the screen. A Stepper command will be executed when
15 the user types the single character for the command followed by the required
16 arguments, if any, and presses the newline key. If the user presses the
17 newline key without having typed any character, then the Stepper will assume
18 that the Stepper command <literal>n</literal> was abbreviated.</para>
19 </blockquote>
20 <para>The stepper commands are:</para>
21 <variablelist>
22 <varlistentry>
23 <term><literal>Newline</literal></term>
24 <listitem>
25 <para>Next. Evaluates the current form in the single-step mode.</para>
26 </listitem>
27 </varlistentry>
28 <varlistentry>
29 <term><replaceable>:s</replaceable>, <replaceable>:skip</replaceable></term>
30 <listitem>
31 <para>Skip. Evaluates the current form in the ordinary mode. The single-step mode
32 will be resumed at completion of the evaluation.</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><replaceable>:b</replaceable>, <replaceable>:back</replaceable></term>
37 <listitem>
38 <para>Backwards. Steps back to previous step form.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><replaceable>:pr</replaceable>, <replaceable>:print</replaceable></term>
43 <listitem>
44 <para>Print. Pretty-prints the current form.</para>
45 </listitem>
46 </varlistentry>
47 <varlistentry>
48 <term><replaceable>:form</replaceable></term>
49 <listitem>
50 <para>Form. Return the current form. Nothing is done, but the current form is
51 returned as the value of this command. As a consequence, it is printed by the
52 top level in the usual way and saved in the variable <literal>*</literal>. The main
53 purpose of this command is to allow the current form to be examined further by
54 accessing <literal>*</literal>.</para>
55 </listitem>
56 </varlistentry>
57 <varlistentry>
58 <term><replaceable>:ret</replaceable>, <replaceable>:return</replaceable></term>
59 <listitem>
60 <para>Return. Return without evaluating the current form.</para>
61 </listitem>
62 </varlistentry>
63 <varlistentry>
64 <term><replaceable>:x</replaceable>, <replaceable>:exit</replaceable></term>
65 <listitem>
66 <para>Exit. Evaluates the current form and any other forms in the ordinary mode.</para>
67 </listitem>
68 </varlistentry>
69 <varlistentry>
70 <term><literal>?</literal></term>
71 <listitem>
72 <para>Help. Lists the commands.</para>
73 </listitem>
74 </varlistentry>
75 </variablelist>
76 </section>
78 <section id="Errors">
79 <title>Errors</title>
80 <blockquote>
81 <screen><indexterm role="vr"><primary>*break-enable*</primary></indexterm>&mdash; Variable: <varname>*break-enable*</varname></screen>
82 <para>This variable is used to determine whether to enter the break loop (see Section
83 5.4) when an error occurs. Even the function <literal>break</literal> checks this
84 variable. Initially, this variable is set to <replaceable>T</replaceable>, and thus an error will
85 invoke the break loop. If the value is (), functions that cause fatal
86 errors, such as <literal> error</literal>, will just print an error message and control
87 will return to the top-level loop (or to the current break loop, if already in
88 the break loop). Functions that cause correctable errors, such as <literal>
89 cerror</literal>, will print an error message and a &ldquo;continue message&rdquo;, and control
90 will return to the next form. In &ECL;, backtrace is not part of an error
91 message, but a break loop command will print backtrace. Therefore, if
92 break-enable is (), no backtrace appears on the screen.</para>
93 <para>When the break loop is entered, break-enable will be bound to
94 ().</para>
95 </blockquote>
96 </section>
98 <section id="The-break-loop">
99 <title>The Break Loop</title>
100 <para>The break loop is a read-eval-print loop similar to the top-level loop. In
101 addition to ordinary Lisp forms, the break loop accepts various commands with
102 which the user can inspect and modify the state of the program execution. Each
103 break loop command is identified with a keyword (i.e., a symbol in the
104 <literal>keyword</literal> package). A break loop command is executed when the user inputs
105 a list whose first element is the keyword that identifies the command. The
106 rest of the list is the arguments to the command. They are evaluated before
107 being passed to the command. If the command needs no arguments, then the user
108 may input only the keyword. It is an error if the given keyword does not
109 identify any command. Any other input to the break loop is regarded as an
110 ordinary Lisp form; the form will be evaluated and the resulting values will be
111 printed on the terminal.</para>
112 <para>There can be several instances of the break loop at the same time, and each
113 such instance is identified by a <emphasis>level number</emphasis>. When the break loop is
114 entered during execution in the top-level loop, the break loop instance is
115 given the level number 1. The break loop instance that is entered from the
116 level <emphasis>n</emphasis> break loop is given the level number <replaceable>n</replaceable><literal>+1</literal>. The
117 prompt of the level <emphasis>n</emphasis> break loop is <replaceable>n</replaceable><literal>+1</literal> consecutive
118 <literal>&gt;</literal>'s, occasionally prefixed with the name of the current package.</para>
119 <para>The break loop keeps track of the invocation sequence of functions (including
120 special forms and macro expansion functions), which led up to the break loop
121 from the previous break loop (or from the top-level loop, if the current break
122 loop is level 1). The invocation sequence is maintained in a pushdown stack of
123 <emphasis>events</emphasis>. An event consists of an <emphasis>event function</emphasis> and an
124 <emphasis>event environment</emphasis>. An event function is:</para>
125 <orderedlist numeration="arabic">
126 <listitem>
127 <para>an interpreted (i.e., not compiled) function (global function, local function, lambda-expression, or closure),</para>
128 </listitem>
129 <listitem>
130 <para>a special form within an interpreted function,</para>
131 </listitem>
132 <listitem>
133 <para>a macro expansion function called from an interpreted function,</para>
134 </listitem>
135 <listitem>
136 <para>a compiled function called from an interpreted function, or</para>
137 </listitem>
138 <listitem>
139 <para>a compiled function called from another compiled function which
140 was compiled while the <literal>safety</literal> optimize level is 3 or with a
141 <literal>notinline</literal> declaration for the called function (see Chapter 7).</para>
142 </listitem>
143 </orderedlist>
144 <para>An event is pushed on the event stack when execution of its event function
145 begins, and is popped away at the completion of the execution. An event
146 environment is the `environment' of the event function at the time the next
147 event is pushed. Actually, an event environment is a pointer to the main stack
148 of &ECL;. For each interpreted event function (i.e., event function in
149 classes 1, 2, and 3), the pointer points to the first entry of the three
150 contiguous main stack entries that hold the lexical environment of the event
151 function. For each compiled event function (i.e., event function in classes 4
152 and 5), the pointer is set to the first entry of the main stack area that is
153 used locally by the compiled code. In most cases, the first argument to the
154 compiled function is saved in the first entry, the second argument in the
155 second entry, and so on. The local variables of the function are allocated in
156 the entries following the arguments. However, this is not always the case.
157 Refer to Section 7.3 for variable allocations in compiled functions.</para>
158 <para>By break level commands, the user can choose one of the events as the
159 <emphasis>current event</emphasis>. If the current event function is an interpreted event
160 function, then the break loop evaluates Lisp forms in the lexical environment
161 retrieved from the event environment. In particular, local variables may be
162 referenced by the variable names, local functions and local macros may be
163 invoked as usual, established blocks may be exited from, and tags may be used
164 as the destination of <literal>go</literal>. If the current function is a compiled
165 function, Lisp forms are evaluated in the null environment.</para>
166 <para>Within the break loop, each event is represented by the <emphasis>event symbol</emphasis>.
167 The <replaceable>:backtrace</replaceable> command, for example, lists events in terms of their event
168 symbols. If the event function is a named function (global or local) or a
169 macro expansion function, then the function or macro name is used as the event
170 symbol. If the event function is a special form, then the name of the special
171 form is used. If the event function is a lambda-expression (or a closure),
172 then the symbol lambda (or lambda-closure) is used.</para>
173 <para>To suppress unnecessary information, the user can hide (or make invisible) some
174 of the events. Invisible events do not appear in the backtrace, for example.
175 Initially, only those events are invisible whose event symbols belong to the
176 system internal package system. When the break loop is entered, the last
177 visible event becomes the current event.</para>
178 <para>The break loop commands are described below. Some of the commands allow
179 abbreviation in the keywords that identify them. For example, the user may
180 abbreviate <replaceable>:current</replaceable> as <replaceable>:c</replaceable>. The break loop commands return no values
181 at all.</para>
182 <blockquote>
183 <screen><indexterm role="fn"><primary>:current</primary></indexterm>&mdash; Break Command: <function>:current</function></screen>
184 <screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
185 <para>Prints the event symbol of the current event.</para>
186 </blockquote>
187 <blockquote>
188 <screen><indexterm role="fn"><primary>:previous</primary></indexterm>&mdash; Break Command: <function>:previous</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
189 <screen><indexterm role="fn"><primary>:p</primary></indexterm>&mdash; Break Command: <function>:p</function> <varname>&amp;optional n</varname></screen>
190 <para>Makes the <replaceable>n</replaceable>-th previous visible event the
191 new current event. Invisible events are not counted. If there are
192 less than <replaceable>n</replaceable> previous events, then the first visible event in the
193 invocation sequence becomes the new current event. <replaceable>n</replaceable> must be a
194 positive integer and the default is <literal>1</literal>.</para>
195 </blockquote>
196 <blockquote>
197 <screen><indexterm role="fn"><primary>:next</primary></indexterm>&mdash; Break Command: <function>:next</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
198 <screen><indexterm role="fn"><primary>:n</primary></indexterm>&mdash; Break Command: <function>:n</function> <varname>&amp;optional n</varname></screen>
199 <para>Makes the <replaceable>n</replaceable>-th next visible event the
200 new current event. If there are less than <replaceable>n</replaceable> next events,
201 then the last visible event in the invocation sequence
202 becomes the new current event. <replaceable>n</replaceable> must be a positive integer and the
203 default is <literal>1</literal>.</para>
204 </blockquote>
205 <blockquote>
206 <screen><indexterm role="fn"><primary>:backtrace</primary></indexterm>&mdash; Break Command: <function>:backtrace</function></screen>
207 <screen><indexterm role="fn"><primary>:b</primary></indexterm>&mdash; Break Command: <function>:b</function> <varname></varname></screen>
208 <para>Prints the event symbols of all visible events in order. The symbol of
209 the current event is printed
210 in upper-case letters and the event symbols of other events are in lower-case.</para>
211 </blockquote>
212 <blockquote>
213 <screen><indexterm role="fn"><primary>:help</primary></indexterm>&mdash; Break Command: <function>:help</function></screen>
214 <screen><indexterm role="fn"><primary>:h</primary></indexterm>&mdash; Break Command: <function>:h</function> <varname></varname></screen>
215 <para>Lists the break loop commands.</para>
216 </blockquote>
217 <blockquote>
218 <screen><indexterm role="fn"><primary>:quit</primary></indexterm>&mdash; Break Command: <function>:quit</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
219 <screen><indexterm role="fn"><primary>:q</primary></indexterm>&mdash; Break Command: <function>:q</function> <varname>&amp;optional n</varname></screen>
220 <para>Returns control to the level <replaceable>n</replaceable> break loop. If <replaceable>n</replaceable> is 0 or if <replaceable>n</replaceable>
221 is omitted, then control will return to the top-level loop. <replaceable>n</replaceable> must be a
222 non-negative integer smaller than the current break level.</para>
223 </blockquote>
224 <blockquote>
225 <screen><indexterm role="fn"><primary>:continue</primary></indexterm>&mdash; Break Command: <function>:continue</function></screen>
226 <screen><indexterm role="fn"><primary>:c</primary></indexterm>&mdash; Break Command: <function>:c</function> <varname></varname></screen>
227 <para>Returns control to the caller of the break loop. If the break loop has been
228 entered from <literal>cerror</literal>, <literal>cerror</literal> returns () as its value and
229 control will resume at that point. Otherwise, this command returns control to
230 the previous break loop (or to the top-level loop, if the current break level
231 is <literal>1</literal>).</para>
232 </blockquote>
233 <blockquote>
234 <screen><indexterm role="fn"><primary>:variables</primary></indexterm>&mdash; Break Command: <function>:variables</function></screen>
235 <screen><indexterm role="fn"><primary>:v</primary></indexterm>&mdash; Break Command: <function>:v</function> <varname></varname></screen>
236 <para>Prints the names of the bound variables in the current
237 environment. To see the value of a bound variable, just type the
238 variable name.</para>
239 </blockquote>
240 <blockquote>
241 <screen><indexterm role="fn"><primary>:functions</primary></indexterm>&mdash; Break Command: <function>:functions</function></screen>
242 <para>Prints the names of the local functions and local macros in the current
243 environment. To see the definition of a local function or macro, use the
244 function special form in the usual way. That is, <literal>(function <replaceable>name</replaceable>)</literal>
245 will return the definition of the local function or macro whose name is
246 <replaceable>name</replaceable>. Local functions and local macros may be invoked as usual.</para>
247 </blockquote>
248 <blockquote>
249 <screen><indexterm role="fn"><primary>:blocks</primary></indexterm>&mdash; Break Command: <function>:blocks</function></screen>
250 <para>Prints the names of the blocks established in the current environment. If a
251 block <replaceable>block</replaceable> is established, then the <literal>return-from</literal> form
252 <literal>(return-from <replaceable>block value</replaceable>)</literal> works as usual. That is, the block form
253 that established <replaceable>block</replaceable> will return <replaceable>value</replaceable> as its value and control
254 will resume at that point.</para>
255 </blockquote>
256 <blockquote>
257 <screen><indexterm role="fn"><primary>:tags</primary></indexterm>&mdash; Break Command: <function>:tags</function></screen>
258 <para>Prints the tags established in the current environment. If a tag <replaceable>tag</replaceable> is
259 established, then the <literal>go</literal> form <literal>(go <replaceable>tag</replaceable>)</literal> works as usual.
260 That is, control will resume at the position of <replaceable>tag</replaceable> in the surrounding
261 <literal>tagbody</literal>.</para>
262 </blockquote>
263 <blockquote>
264 <screen><indexterm role="fn"><primary>:local</primary></indexterm>&mdash; Break Command: <function>:local</function> <varname>&amp;optional</varname> <varname>n</varname></screen>
265 <screen><indexterm role="fn"><primary>:l</primary></indexterm>&mdash; Break Command: <function>:l</function> <varname>&amp;optional n</varname></screen>
266 <para>If <replaceable>n</replaceable> is <literal>0</literal> or if it is omitted, then this command prints the value
267 stored in the main stack entry that is pointed to by the current event
268 environment. <replaceable>n</replaceable> is an offset from that entry. If <replaceable>n</replaceable> is positive,
269 then the value of the <emphasis>n</emphasis>-th next (i.e., toward the top of the main stack)
270 entry is printed. If <replaceable>n</replaceable> is negative, then the value of the <replaceable>n</replaceable>-th
271 previous (i.e., toward the bottom of the main stack) entry is printed. <replaceable>n</replaceable>
272 must be an integer. It is an error if the specified entry does not lie between
273 the bottom and the top of the stack.</para>
274 </blockquote>
275 <blockquote>
276 <screen><indexterm role="fn"><primary>:hide</primary></indexterm>&mdash; Break Command: <function>:hide</function> <varname>symbol</varname></screen>
277 <para>Hides all events whose event symbol is <replaceable>symbol</replaceable>. In particular, by
278 <literal>:hide 'lambda</literal> and <literal>hide 'lambda-closure</literal>, all events become
279 invisible whose event functions are lambda-expressions and closures,
280 respectively. If the event symbol of the current event happens to be
281 <replaceable>symbol</replaceable>, then the last previous visible event will become the new current
282 event. <replaceable>symbol</replaceable> must be a symbol.</para>
283 <para>Events of <literal>eval</literal> and <literal>evalhook</literal> may never become invisible and
284 attempts to hide them are simply ignored. It is always the case that the first
285 event function is either <literal>eval</literal> or <literal>evalhook</literal>. Keeping both of them
286 visible is the simplest way to avoid the silly attempts of the user to hide all
287 events.</para>
288 </blockquote>
289 <blockquote>
290 <screen><indexterm role="fn"><primary>:hide-package</primary></indexterm>&mdash; Break Command: <function>:hide-package</function> <varname>package</varname></screen>
291 <para>Hides all events whose event symbol belongs to the package
292 <replaceable>package</replaceable>. <replaceable>package</replaceable> may be any object that represents a package, i.e.,
293 a package object, a symbol, or a string. If the event symbol of the current
294 event happens to belong to the package <replaceable>package</replaceable>, then the last previous
295 visible event will become the new current event. Even if <literal>lisp</literal> package
296 was specified as <replaceable>package</replaceable>, events of <literal>eval</literal> and <literal>evalhook</literal> do
297 not become invisible. See the description of <replaceable>:hide</replaceable> above.</para>
298 </blockquote>
299 <blockquote>
300 <screen><indexterm role="fn"><primary>:unhide</primary></indexterm>&mdash; Break Command: <function>:unhide</function> <varname>symbol</varname></screen>
301 <para><replaceable>:unhide</replaceable> is the inverse command of <replaceable>:hide</replaceable>. If, however, <replaceable> symbol</replaceable>
302 belongs to one of the <replaceable>:hide-package</replaceable>d packages, events of <replaceable>symbol</replaceable>
303 become visible only after the package is <literal>:unhide-package
304 'd</literal>. <replaceable>symbol</replaceable> must be a symbol.</para>
305 </blockquote>
306 <blockquote>
307 <screen><indexterm role="fn"><primary>:unhide-package</primary></indexterm>&mdash; Break Command: <function>:unhide-package</function> <varname>package</varname></screen>
308 <para><replaceable>:unhide-package</replaceable> is the inverse command of <replaceable>:hide-package</replaceable>. However, an
309 event whose event symbol belongs to <replaceable>package</replaceable> becomes visible only after
310 the symbol is <literal>unhide 'd</literal>, if the symbol was <replaceable>:code 'd</replaceable>
311 before. <replaceable>package</replaceable> may be any object that represents a package, i.e., a
312 package object, a symbol, or a string.</para>
313 </blockquote>
314 <para>Example:</para>
315 <para><screen>
316 &gt; (defun fact (x) (if (= x 0) one (* x (fact (1- x)))))
317 fact ;;; Wrong definition for fact, the factorial.
319 &gt; (fact 6) ;;; Tries to calculate factorial 6.
321 Error: The variable ONE is unbound.
322 Error signalled by IF.
324 Broken at IF: ;;; Enters the break-loop.
325 &gt;&gt; :h ;;; Help.
327 Break commands:
328 :q(uit) Return to some previous break level.
329 :pop Pop to previous break level.
330 :c(ontinue) Continue execution.
331 :b(acktrace) Print backtrace.
332 :f(unction) Show current function.
333 :p(revious) Go to previous function.
334 :n(ext) Go to next function.
335 :g(o) Go to next function.
336 :fs Search forward for function.
337 :bs Search backward for function.
338 :v(ariables) Show local variables, functions, blocks, and tags.
339 :l(ocal) Return the nth local value on the stack.
340 :hide Hide function.
341 :unhide Unhide function.
342 :hp Hide package.
343 :unhp Unhide package.
344 :unhide-all Unhide all variables and packages.
345 :vs Show value stack.
346 :bds Show binding stack.
347 :m(essage) Show error message.
348 :hs Help stack.
350 Top level commands:
351 :cf Compile file.
352 :exit or ^D Exit Lisp.
353 :ld Load file.
354 :step Single step form.
355 :tr(ace) Trace function.
356 :untr(ace) Untrace function.
358 Help commands:
359 :apropos Apropos.
360 :doc(ument) Document.
361 :h(elp) or ? Help. Type ":help help" for more information.
363 &gt;&gt; :b ;;; Backtrace.
364 Backtrace: eval &gt; fact &gt; if &gt; fact &gt; if &gt; fact &gt; if &gt; fact &gt;
365 if &gt; fact &gt; if &gt; fact &gt; if &gt; fact &gt; IF
367 &gt;&gt;: p ;;; Moves to the previous event.
368 Broken at FACT.
370 &gt;&gt; :b ;;; Now inside of fact but outside of if.
371 Backtrace: eval &gt; fact &gt; if &gt; fact &gt; if &gt; fact &gt; if &gt; fact &gt;
372 if &gt; fact &gt; if &gt; fact &gt; if &gt; FACT &gt; if
374 &gt;&gt; :v ;;; Shows local variables.
375 Local variables:
376 X: 1
377 Block names: FACT.
379 &gt;&gt; x ;;; The value of x is 1.
380 1
382 &gt;&gt; (return-from fact 1) ;;; Returns from the fact block with value 1.
383 720 ;;; Now the correct answer.
385 &gt; ;;; Top-level.
386 </screen></para>
387 </section>
389 <section id="Describe-and-inspect">
390 <title>Describe and Inspect</title>
391 <blockquote>
392 <screen><indexterm role="fn"><primary>describe</primary></indexterm>&mdash; Function: <function>describe</function> <varname>object</varname></screen>
393 <para>Prints the information about <replaceable>object</replaceable> to the stream that is the value of
394 <literal>*standard-output*</literal>. The description of an object consists of several
395 fields, each of which is described in a recursive manner. For example, a
396 symbol may have fields such as home package, variable documentation, value,
397 function documentation, function binding, type documentation, <literal>deftype</literal>
398 definition, properties.</para>
399 </blockquote>
400 <blockquote>
401 <screen><indexterm role="fn"><primary>inspect</primary></indexterm>&mdash; Function: <function>inspect</function> <varname>object</varname></screen>
402 <para>Prints the information about <replaceable>object</replaceable> in an interactive manner. The output
403 of inspect is similar to that of <literal>describe</literal>, but after printing the label
404 and the value of a field (the value itself is not <literal>describe 'd</literal>), it
405 prompts the user to input a one-character command. The input to <literal>inspect</literal>
406 is taken from the stream that is the value of <literal>*query-io*</literal>. Normally, the
407 inspection of <replaceable>object</replaceable> terminates after all of its fields have been
408 inspected. The following commands are supported:</para>
409 <variablelist>
410 <varlistentry>
411 <term><literal>n</literal></term>
412 <listitem>
413 <para>Next. Goes to the next level; the field is inspected recursively.</para>
414 </listitem>
415 </varlistentry>
416 <varlistentry>
417 <term><literal>s</literal></term>
418 <listitem>
419 <para>Skip. Skips the inspection of the field. <literal>inspect</literal> proceeds to the next
420 field.</para>
421 </listitem>
422 </varlistentry>
423 <varlistentry>
424 <term><literal>p</literal></term>
425 <listitem>
426 <para>Print. Pretty-prints the field and prompts again.</para>
427 </listitem>
428 </varlistentry>
429 <varlistentry>
430 <term><literal>u</literal> <replaceable>form</replaceable></term>
431 <listitem>
432 <para>Update. The <replaceable>form</replaceable> is evaluated and the field is replaced by the resulting
433 value. If the field cannot be updated, the message <literal>Not updated.</literal> will
434 be printed.</para>
435 </listitem>
436 </varlistentry>
437 <varlistentry>
438 <term><literal>a</literal></term>
439 <listitem>
440 <para>Abort. Aborts the inspection of the current object. The field and
441 the rest of the fields are not inspected.</para>
442 </listitem>
443 </varlistentry>
444 <varlistentry>
445 <term><literal>e</literal> <replaceable>form</replaceable></term>
446 <listitem>
447 <para>Eval. Evaluates the specified form in the null environment and prints the
448 resulting values. Then prompts again with the same field.</para>
449 </listitem>
450 </varlistentry>
451 <varlistentry>
452 <term><literal>q</literal></term>
453 <listitem>
454 <para>Quit. Aborts the entire inspection.</para>
455 </listitem>
456 </varlistentry>
457 <varlistentry>
458 <term><literal>?</literal></term>
459 <listitem>
460 <para>Help. Lists the <literal>inspect</literal> commands.</para>
461 </listitem>
462 </varlistentry>
463 </variablelist>
464 </blockquote>
465 </section>
467 <section id="The-profiler">
468 <title>The Profiler</title>
469 <para>The profiler tool is enabled by default in the basic &ECL; configuration. It
470 can be disabled with the <literal>configure</literal> option <literal>--disable-profiler</literal>.</para>
471 <blockquote>
472 <screen><indexterm role="fn"><primary>profile</primary></indexterm>&mdash; sys: <function>profile</function> <varname>grain</varname> <varname>&amp;optional</varname> <varname>address</varname></screen>
473 <para>This function activates the profiling of subsequent executions. <replaceable>grain</replaceable> is
474 a value between 1 and 16384 which indicates the granularity of code segments to
475 consider. There is a counter for each such segment. With each clock tick, the
476 current segment is identified and its corresponding histogram count is
477 incremented. A value of 0 for <replaceable>grain</replaceable> means stop profiling. <replaceable>address</replaceable>
478 indicates the base address for the code being profiled.</para>
479 </blockquote>
480 <blockquote>
481 <screen><indexterm role="fn"><primary>display-profile</primary></indexterm>&mdash; sys: <function>display-profile</function></screen>
482 <para>Displays the histogram of accumulated tick counts. The ticks are attributed to
483 the compiled Lisp function whose base address is closest to the start of the
484 segment. This may not be totally accurate for system functions which invoke
485 some auxiliary function to do the job.</para>
486 </blockquote>
487 <blockquote>
488 <screen><indexterm role="fn"><primary>clear-profile</primary></indexterm>&mdash; sys: <function>clear-profile</function></screen>
489 <para>Clears the profile histogram.</para>
490 </blockquote>
491 <blockquote>
492 <screen><indexterm role="vr"><primary>sys</primary></indexterm>&mdash; Variable: <varname>sys</varname> <type>*profile-array*</type></screen>
493 <para>Contains the profile histogram: two short integer counters are packed in each
494 value of this array of fixnums.</para>
495 </blockquote>
496 </section>
498 <section id="Online-help">
499 <title>Online Help</title>
500 <para>Online help is provided by the following functions.</para>
501 <blockquote>
502 <screen><indexterm role="fn"><primary>help</primary></indexterm>&mdash; Function: <function>help</function> <varname>&amp;optional symbol</varname></screen>
503 <para><literal>help</literal> with no arguments prints a greeting message to &ECL; beginners.
504 <literal>help</literal> with a symbol argument prints the documentation associated
505 with the symbol.</para>
506 </blockquote>
507 <blockquote>
508 <screen><indexterm role="fn"><primary>help*</primary></indexterm>&mdash; Function: <function>help*</function> <varname>string &amp;optional package</varname></screen>
509 <para>Prints the documentation associated with those symbols in the specified
510 <replaceable>package</replaceable> whose print names contain <replaceable>string</replaceable> as substring.
511 <replaceable>string</replaceable> may be a symbol, in which case the print name of that symbol is
512 used. <replaceable>package</replaceable> is optional and defaults to the LISP package.
513 If <replaceable>package</replaceable> is (), then all packages are searched.</para>
514 </blockquote>
515 </section>
516 </chapter>
517 <!-- Keep this comment at the end of the file
518 Local variables:
519 sgml-parent-document: "ecl.xml"
520 sgml-indent-step: 1
521 nxml-child-indent: 1
522 nxml-outline-child-indent:1
523 fill-column: 79
524 End:
525 --></book>

  ViewVC Help
Powered by ViewVC 1.1.5