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

Last change on this file since 13106 was 13106, checked in by rme, 10 years ago

Document code coverage in manual.

File size: 109.1 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
3          <!ENTITY rest "<varname>&amp;rest</varname>">
4          <!ENTITY key "<varname>&amp;key</varname>">
5          <!ENTITY optional "<varname>&amp;optional</varname>">
6          <!ENTITY body "<varname>&amp;body</varname>">
7          <!ENTITY aux "<varname>&amp;aux</varname>">
8          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9          <!ENTITY CCL "Clozure CL">
10          ]>
11
12<chapter id="using-ccl"><title>Using &CCL;</title>
13 
14  <!-- ============================================================ -->
15  <sect1 id="using-ccl-introduction"><title>Introduction</title>
16   
17    <para>The Common Lisp standard allows considerable latitude in the
18      details of an implementation, and each particular Common Lisp
19      system has some idiosyncrasies. This chapter describes ordinary
20      user-level features of &CCL;, including features that may be
21      part of the Common Lisp standard, but which may have quirks or
22      details in the &CCL; implementation that are not described by
23      the standard. It also describes extensions to the standard; that
24      is, features of &CCL; that are not part of the Common Lisp
25      standard at all.</para>
26
27  </sect1>
28
29  <!-- ============================================================ -->
30  <sect1 id="Trace"><title>Trace</title>
31
32    <para>
33      &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
34      <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
35      over tracing actions.
36    </para>
37
38    <para>
39      <indexterm zone="trace"/>
40      <command><varname id="trace">TRACE</varname> {<replaceable>keyword</replaceable>
41        <replaceable>global-value</replaceable>}* {<replaceable>spec</replaceable> |
42        (<replaceable>spec</replaceable> {<replaceable>keyword</replaceable>
43        <replaceable>local-value</replaceable>}*)}* [Macro]</command>
44    </para>
45
46    <para>
47      The <varname>trace</varname> macro encapsulates the functions named by
48      <replaceable>spec</replaceable>s, causing trace actions to take place on entry and
49      exit from each function.  The default actions print a message on function entry and
50      exit. <replaceable>Keyword</replaceable>/<replaceable>value</replaceable> options
51      can be used to specify changes in the default behavior.
52    </para>
53
54    <para>
55      Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
56    </para>
57   
58    <para>
59      A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
60      expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
61      specific method of a generic function in the form <varname>(:method
62        <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}*
63        ({<replaceable>specializer</replaceable>}*))</varname>, where a
64      <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
65      specializer.
66    </para>
67
68    <para>
69      A <replaceable>spec</replaceable> can also be a string naming a package, or equivalently a
70      list <varname>(:package <replaceable>package-name</replaceable>)</varname>, in order to
71      request that all functions in the package to be traced.
72    </para>
73
74    <para>
75      By default, whenever a traced function is entered or exited, a short message is
76      printed on <varname>*trace-output*</varname> showing the arguments on entry and
77      values on exit.  Options specified as key/value pairs can be used to modify this
78      behavior.  Options preceding the function <replaceable>spec</replaceable>s apply to
79      all the functions being traced.  Options specified along with a
80      <replaceable>spec</replaceable> apply to that spec only and override any
81      global options. The following options are supported:
82    </para>
83
84    <variablelist>
85
86      <varlistentry>
87            <term><varname>:methods {T | nil}</varname></term>
88            <listitem>
89              <para> If true, and if applied to a <replaceable>spec</replaceable> naming a generic
90                function, arranges to trace all the methods of the generic function in addition to the
91                generic function itself.
92              </para>
93            </listitem>
94      </varlistentry>
95
96      <varlistentry>
97            <term><varname>:inside <replaceable>outside-spec</replaceable>
98                | ({<replaceable>outside-spec</replaceable>}*)</varname></term>
99            <listitem>
100              <para>Inhibits all trace actions unless the current
101                invocation of the function being traced is inside one of the
102                <replaceable>outside-spec</replaceable>'s, i.e. unless a function named by one of the
103                <replaceable>outside-spec</replaceable>'s is currently on the stack.
104                <replaceable>outside-spec</replaceable> can name a function, a
105                method, or a package, as above.
106              </para>
107            </listitem>
108      </varlistentry>
109
110      <varlistentry>
111            <term><varname>:if <replaceable>form</replaceable></varname></term>
112            <term><varname>:condition <replaceable>form</replaceable></varname></term>
113            <listitem>
114              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
115                about to be entered, and inhibits all trace actions if <replaceable>form</replaceable>
116                returns nil. The form may reference the lexical variable <varname>ccl::args</varname>,
117                which is a list of the arguments in this call. <varname>:condition</varname> is just a
118                synonym for <varname>:if</varname>, though if both are specified, both must return non-nil.
119              </para>
120            </listitem>
121      </varlistentry>
122
123      <varlistentry>
124            <term><varname>:before-if <replaceable>form</replaceable></varname></term>
125            <listitem>
126              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
127                about to be entered, and inhibits the entry trace actions if
128                <replaceable>form</replaceable> returns nil.  The form may reference the lexical variable
129                <varname>ccl::args</varname>, which is a list of the arguments in this call. If both
130                <varname>:if</varname> and <varname>:before-if</varname> are specified, both must return
131                non-nil in order for the before entry actions to happen.
132              </para>
133            </listitem>
134      </varlistentry>
135
136      <varlistentry>
137            <term><varname>:after-if <replaceable>form</replaceable></varname></term>
138            <listitem>
139              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
140                just exited, and inhibits the exit trace actions if <replaceable>form</replaceable>
141                returns nil.  The form may reference the lexical variable <varname>ccl::vals</varname>,
142                which is a list of values returned by this call. If both <varname>:if</varname> and
143                <varname>:after-if</varname> are specified, both must return non-nil in order for the
144                after exit actions to happen.
145              </para>
146            </listitem>
147      </varlistentry>
148
149      <varlistentry>
150            <term><varname>:print-before <replaceable>form</replaceable></varname></term>
151            <listitem>
152              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
153                about to be entered, and prints the result before printing the standard entry message.
154                The form may reference the lexical variable <varname>ccl::args</varname>, which is a list
155                of the arguments in this call.  To see multiple forms, use <varname>values</varname>:
156                <varname>:print-before (values (one-thing) (another-thing))</varname>.
157              </para>
158            </listitem>
159      </varlistentry>
160
161      <varlistentry>
162            <term><varname>:print-after <replaceable>form</replaceable></varname></term>
163            <listitem>
164              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
165                just exited, and prints the result after printing the standard exit message.  The form may
166                reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
167                returned by this call. To see multiple forms, use <varname>values</varname>:
168                <varname>:print-after (values (one-thing) (another-thing))</varname>.
169              </para>
170            </listitem>
171      </varlistentry>
172
173      <varlistentry>
174            <term><varname>:print <replaceable>form</replaceable></varname></term>
175            <listitem>
176              <para>Equivalent to <varname>:print-before <replaceable>form</replaceable> :print-after <replaceable>form</replaceable></varname>.
177              </para>
178            </listitem>
179      </varlistentry>
180
181      <varlistentry>
182            <term><varname>:eval-before <replaceable>form</replaceable></varname></term>
183            <listitem>
184              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
185                about to be entered.  The form may reference the lexical variable
186                <varname>ccl::args</varname>, which is a list of the arguments in this call.
187              </para>
188            </listitem>
189      </varlistentry>
190
191      <varlistentry>
192            <term><varname>:eval-after <replaceable>form</replaceable></varname></term>
193            <listitem>
194              <para>Evaluates <replaceable>form</replaceable> whenever the function being has just
195                exited.  The form may reference the lexical variable <varname>ccl::vals</varname>, which
196                is a list of values returned by this call.
197              </para>
198            </listitem>
199      </varlistentry>
200
201      <varlistentry>
202            <term><varname>:eval <replaceable>form</replaceable></varname></term>
203            <listitem>
204              <para>Equivalent to <varname>:eval-before <replaceable>form</replaceable>
205                  :eval-after <replaceable>form</replaceable></varname>.
206              </para>
207            </listitem>
208      </varlistentry>
209
210      <varlistentry>
211            <term><varname>:break-before <replaceable>form</replaceable></varname></term>
212            <listitem>
213              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
214                about to be entered, and if the result is non-nil, enters a debugger break loop.  The form
215                may reference the lexical variable <varname>ccl::args</varname>, which is a list of the
216                arguments in this call.
217              </para>
218            </listitem>
219      </varlistentry>
220
221      <varlistentry>
222            <term><varname>:break-after <replaceable>form</replaceable></varname></term>
223            <listitem>
224              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
225                just exited, and if the result is non-nil, enters a debugger break loop. The form may
226                reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
227                returned by this call.
228              </para>
229            </listitem>
230      </varlistentry>
231
232      <varlistentry>
233            <term><varname>:break <replaceable>form</replaceable></varname></term>
234            <listitem>
235              <para>Equivalent to <varname>:break-before <replaceable>form</replaceable> :break-after <replaceable>form</replaceable></varname>.
236              </para>
237            </listitem>
238      </varlistentry>
239
240      <varlistentry>
241            <term><varname>:backtrace-before <replaceable>form</replaceable></varname></term>
242            <term><varname>:backtrace <replaceable>form</replaceable></varname></term>
243            <listitem>
244              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
245                about to be entered.  The form may reference the lexical variable
246                <varname>ccl::args</varname>, which is a list of the arguments in this call. The value
247                returned by <replaceable>form</replaceable> is intepreted as follows:
248              </para>
249
250              <variablelist>
251
252                <varlistentry>
253                  <term><varname>nil</varname></term>
254                  <listitem><para>does nothing</para></listitem>
255                </varlistentry>
256
257                <varlistentry>
258                  <term><varname>:detailed</varname></term>
259                  <listitem><para>prints a detailed backtrace to
260                      <varname>*trace-output*</varname>.</para></listitem>
261                </varlistentry>
262
263                <varlistentry>
264                  <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
265                  <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
266                      backtrace to <varname>*trace-output*</varname>.
267                  </para></listitem>
268                </varlistentry>
269
270                <varlistentry>
271                  <term><replaceable>integer</replaceable></term>
272                  <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
273                      backtrace to <varname>*trace-output*</varname>.
274                  </para></listitem>
275                </varlistentry>
276
277                <varlistentry>
278                  <term>anything else</term>
279                  <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
280                  </para></listitem>
281                </varlistentry>
282              </variablelist>
283              <para>
284                Note that unlike with the other options, <varname>:backtrace</varname> is equivalent to
285                <varname>:backtrace-before</varname> only, not both before and after, since it's usually
286                not helpful to print the same backtrace both before and after the function call.
287              </para>
288            </listitem>
289      </varlistentry>
290
291      <varlistentry>
292            <term><varname>:backtrace-after <replaceable>form</replaceable></varname></term>
293            <listitem>
294              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
295                just exited.  The form may reference the lexical variable <varname>ccl::vals</varname>,
296                which is a list of values returned by this call. The value returned by
297                <replaceable>form</replaceable> is intepreted as follows:
298              </para>
299
300              <variablelist>
301
302                <varlistentry>
303                  <term><varname>nil</varname></term>
304                  <listitem><para>does nothing</para></listitem>
305                </varlistentry>
306
307                <varlistentry>
308                  <term><varname>:detailed</varname></term>
309                  <listitem><para>prints a detailed backtrace to
310                      <varname>*trace-output*</varname>.</para></listitem>
311                </varlistentry>
312
313                <varlistentry>
314                  <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
315                  <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
316                      backtrace to <varname>*trace-output*</varname>.
317                  </para></listitem>
318                </varlistentry>
319
320                <varlistentry>
321                  <term><replaceable>integer</replaceable></term>
322                  <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
323                      backtrace to <varname>*trace-output*</varname>.
324                  </para></listitem>
325                </varlistentry>
326
327                <varlistentry>
328                  <term>anything else</term>
329                  <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
330                  </para></listitem>
331                </varlistentry>
332              </variablelist>
333            </listitem>
334      </varlistentry>
335
336      <varlistentry>
337        <term><varname>:before</varname> <replaceable>action</replaceable></term>
338        <listitem>
339              <para>specifies the action to be taken just before the traced function is entered.  <replaceable>action</replaceable> is one of:</para>
340
341              <variablelist>
342                <varlistentry>
343                  <term><varname>:print</varname></term>
344                  <listitem>
345                        <para>The default, prints a short indented message showing the function name and the invocation arguments</para>
346                  </listitem>
347                </varlistentry>
348
349                <varlistentry>
350                  <term><varname>:break</varname></term>
351                  <listitem>
352                        <para>Equivalent to <varname>:before :print :break-before t</varname></para>
353                  </listitem>
354                </varlistentry>
355
356                <varlistentry>
357                  <term><varname>:backtrace</varname></term>
358                  <listitem>
359                        <para>Equivalent to <varname>:before :print :backtrace-before t</varname></para>
360                  </listitem>
361                </varlistentry>
362
363
364                <varlistentry>
365                  <term><replaceable>function</replaceable></term>
366                  <listitem>
367                        <para>
368                  Any other value is interpreted as a function to call on entry instead of
369                  printing the standard entry message.  It is called with its first
370                  argument being the name of the function being traced, the remaining
371                  arguments being all the arguments to the function being traced, and
372                  <varname>ccl:*trace-level*</varname> bound to the current nesting level
373                  of trace actions. </para>
374                  </listitem>
375                </varlistentry>
376              </variablelist>
377            </listitem>
378      </varlistentry>
379
380      <varlistentry>
381
382        <term><varname>:after</varname> <replaceable>action</replaceable></term>
383        <listitem>
384
385              <para>specifies the action to be taken just after the traced function exits.  <replaceable>action</replaceable> is one of:</para>
386
387              <variablelist>
388                <varlistentry>
389                  <term><varname>:print</varname></term>
390                  <listitem>
391                    <para>The default, prints a short indented message showing the function name and the
392                      returned values </para>
393                  </listitem>
394                </varlistentry>
395
396                <varlistentry>
397                  <term><varname>:break</varname></term>
398                  <listitem>
399                    <para>Equivalent to <varname>:after :print :break-after t</varname></para>
400                  </listitem>
401                </varlistentry>
402
403                    <varlistentry>
404                      <term><varname>:backtrace</varname></term>
405                      <listitem>
406                        <para>Equivalent to <varname>:after :print :backtrace-after t</varname></para>
407                      </listitem>
408                    </varlistentry>
409
410                <varlistentry>
411                  <term><replaceable>function</replaceable></term>
412                  <listitem>
413                    <para>Any other value is interpreted as a function to
414                      call on exit instead of printing the standard exit
415                      message.  It is called with its first argument being
416                      the name of the function being traced, the
417                      remaining arguments being all the values returned by the function
418                      being traced, and ccl:*trace-level* bound to the current
419                      nesting level of trace actions.
420                    </para>
421                  </listitem>
422                </varlistentry>
423              </variablelist>
424        </listitem>
425      </varlistentry>
426
427    </variablelist>
428
429
430    <para>
431      <indexterm zone="trace-level"/>
432      <command><varname id="trace-level">CCL:*TRACE-LEVEL*</varname>    [Variable]</command>
433    </para>
434
435    <para>Variable bound to the current nesting level during execution of before and after trace actions.  The default printing actions use it to determine the amount of indentation.</para>
436
437    <para>
438      <indexterm zone="trace-max-indent"/>
439      <command><varname id="trace-max-indent">CCL:*TRACE-MAX-INDENT*</varname>    [Variable]</command>
440    </para>
441
442    <para>The default before and after print actions will not indent by more than the value of <varname>ccl:*trace-max-indent*</varname> regardless of the current trace level.</para>
443
444    <para>
445      <indexterm zone="trace-function"/>
446      <command><varname id="trace-function">CCL:TRACE-FUNCTION</varname> <replaceable>spec</replaceable> &key; {<replaceable>keyword</replaceable> <replaceable>value</replaceable>}*    [Function]</command>
447    </para>
448   
449    <para>
450      This is a functional version of the TRACE macro.  <replaceable>spec</replaceable> and
451      <replaceable>keyword</replaceable>s are as for TRACE, except that all arguments are evaluated.
452    </para>
453
454    <para>
455      <indexterm zone="trace-print-level"/>
456      <command><varname id="trace-print-level">CCL:*TRACE-PRINT-LEVEL*</varname>   [Variable]</command>
457    </para>
458
459    <para>The default print actions bind <varname>CL:*PRINT-LEVEL*</varname> to this value while
460      printing. Note that this rebinding is only in effect during the default entry and exit messages.
461      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
462      explicit printing done by user code.</para>
463
464    <para>
465      <indexterm zone="trace-print-length"/>
466      <command><varname id="trace-print-length">CCL:*TRACE-PRINT-LENGTH*</varname>    [Variable]</command>
467    </para>
468   
469    <para>The default print actions bind <varname>CL:*PRINT-LENGTH*</varname> to this value while
470      printing. Note that this rebinding is only in effect during the default entry and exit messages.
471      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
472      explicit printing done by user code.</para>
473
474    <para>
475      <indexterm zone="trace-bar-frequency"/>
476      <command><varname id="trace-bar-frequency">CCL:*TRACE-BAR-FREQUENCY*</varname>    [Variable]</command>
477    </para>
478
479    <para>By default, this is nil. If non-nil it should be a integer,
480    and the default entry and exit messages will print a | instead of
481    space every this many levels of indentation.</para>
482
483
484  </sect1>
485
486  <sect1 id="Unicode"><title>Unicode</title>
487
488    <para>All characters and strings in &CCL; fully support Unicode by
489    using UTF-32. There is only one <literal>CHARACTER</literal> type
490    and one <literal>STRING</literal> type in &CCL;.  There has been a
491    lot of discussion about this decision which can be found by
492    searching the openmcl-devel archives at <ulink
493    url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it
494    to say that we decided that the simplicity and speed advantages of
495    only supporting UTF-32 outweigh the space disadvantage.</para>
496
497
498
499  <sect2 id="unicode-characters"><title>Characters</title>
500    <para>There is one <literal>CHARACTER</literal> type in &CCL;.
501    All <literal>CHARACTER</literal>s are
502    <literal>BASE-CHAR</literal>s.  <varname>CHAR-CODE-LIMIT</varname>
503    is now <literal>#x110000</literal>, which means that all Unicode
504    characters can be directly represented.  As of Unicode 5.0, only
505    about 100,000 of 1,114,112 possible <literal>CHAR-CODE</literal>s
506    are actually defined. The function <function>CODE-CHAR</function>
507    knows that certain ranges of code values (notably
508    <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
509    valid character codes and will return <literal>NIL</literal> for
510    arguments in that range, but may return a
511    non-<literal>NIL</literal> value (an undefined/non-standard
512    <literal>CHARACTER</literal> object) for other unassigned code
513    values.</para>
514
515    <para>&CCL; supports character names of the form
516    <literal>u+xxxx</literal>&mdash;where <literal>x</literal> is a
517    sequence of one or more hex digits.  The value of the hex digits
518    denotes the code of the character.  The <literal>+</literal>
519    character is optional, so <literal>#\u+0020</literal>,
520    <literal>#\U0020</literal>, and <literal>#\U+20</literal> all
521    refer to the <literal>#\Space</literal> character.</para>
522
523    <para>Characters with codes in the range
524    <literal>#xa0</literal>-<literal>#x7ff</literal> also have
525    symbolic names These are the names from the Unicode standard with
526    spaces replaced by underscores.  So
527    <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
528    refer to the character whose <function>CHAR-CODE</function> is
529    <literal>#x395</literal>.  To see the complete list of supported
530    character names, look just below the definition for
531    <function>register-character-name</function> in
532    <literal>ccl:level-1;l1-reader.lisp</literal>.</para>
533  </sect2>
534
535
536  <sect2 id="External-Formats"><title>External Formats</title>
537    <para><function>OPEN</function>, <function>LOAD</function>, and
538    <function>COMPILE-FILE</function> all take an
539    <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value
540    of <literal>:EXTERNAL-FORMAT</literal> can be
541    <literal>:DEFAULT</literal> (the default value), a line
542    termination keyword (see <xref
543    linkend="Line-Termination-Keywords"/>), a character encoding
544    keyword (see <xref linkend="Character-Encodings"/>), an
545    external-format object created using
546    <function>CCL::MAKE-EXTERNAL-FORMAT</function> (see <xref
547    linkend="f_make-external-format"/>), or a plist with keys:
548    <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
549    and <literal>:LINE-TERMINATION</literal>.  If
550    <parameter>argument</parameter> is a plist, the result of
551    <literal>(APPLY #'MAKE-EXTERNAL-FORMAT
552    <parameter>argument</parameter>)</literal> will be used.</para>
553
554    <para>If <literal>:DEFAULT</literal> is specified, then the value
555    of <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If
556    no line-termination is specified, then the value of
557    <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used, which
558    defaults to <literal>:UNIX</literal>.  If no character encoding is
559    specified, then
560    <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used
561    for file streams and
562    <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
563    for socket streams.  The default, default character encoding is
564    <literal>NIL</literal> which is a synonym for
565    <literal>:ISO-8859-1</literal>.</para>
566
567    <para>Note that the set of keywords used to denote
568    CHARACTER-ENCODINGs and the set of keywords used to denote
569    line-termination conventions is disjoint: a keyword denotes at
570    most a character encoding or a line termination convention, but
571    never both.</para>
572
573    <para>EXTERNAL-FORMATs are objects (structures) with three
574    read-only fields that can be accessed via the functions:
575    <function>EXTERNAL-FORMAT-DOMAIN</function>,
576    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
577    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
578
579 
580    <refentry id="f_make-external-format">
581      <indexterm zone="f_make-external-format">
582        <primary>make-external-format</primary>
583      </indexterm>
584     
585      <refnamediv>
586        <refname>MAKE-EXTERNAL-FORMAT</refname>
587        <refpurpose>Either creates a new external format object, or
588        return an existing one with the same specified slot
589        values.</refpurpose>
590        <refclass>Function</refclass>
591      </refnamediv>
592
593      <refsynopsisdiv>
594        <synopsis>
595          <function>make-external-format</function>
596          &key; domain character-encoding line-termination
597          => external-format
598        </synopsis>
599      </refsynopsisdiv>
600
601      <refsect1>
602        <title>Arguments and Values</title>
603       
604        <variablelist>
605          <varlistentry>
606            <term>domain</term>
607            <listitem>
608              <para>This is used to indicate where the external
609              format is to be used.  Its value can be almost
610              anything.  It defaults to <literal>NIL</literal>.
611              There are two domains that have a pre-defined meaning in
612              &CCL;: <literal>:FILE</literal> indicates
613              encoding for a file in the file system and
614              <literal>:SOCKET</literal> indicates i/o to/from a
615              socket.  The value of <parameter>domain</parameter>
616              affects the default values for
617              <parameter>character-encoding</parameter> and
618              <parameter>line-termination</parameter>.</para>
619            </listitem>
620          </varlistentry>
621          <varlistentry>
622            <term>character-encoding</term>
623            <listitem>
624              <para>A keyword that specifies the character encoding
625              for the external format. <xref
626              linkend="Character-Encodings"/>.  Defaults to
627              <literal>:DEFAULT</literal> which means if
628              <parameter>domain</parameter> is
629              <literal>:FILE</literal> use the value of the variable
630              <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
631              and if <parameter>domain</parameter> is
632              <literal>:SOCKET</literal>, use the value of the
633              variable
634              <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
635              The initial value of both of these variables is
636              <literal>NIL</literal>, which means the
637              <literal>:ISO-8859-1</literal> encoding.</para>
638            </listitem>
639          </varlistentry>
640          <varlistentry>
641            <term>line-termination</term>
642            <listitem>
643              <para>A keyword that indicates a line termination
644              keyword <xref linkend="Line-Termination-Keywords"/>.
645              Defaults to <literal>:DEFAULT</literal> which means
646              use the value of the variable
647              <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
648            </listitem>
649          </varlistentry>
650          <varlistentry>
651            <term>external-format</term>
652            <listitem>
653              <para>An external-format object as described above.</para>
654            </listitem>
655          </varlistentry>
656        </variablelist>
657      </refsect1>
658     
659      <refsect1>
660        <title>Description</title>
661       
662        <para>Despite the function's name, it doesn't necessarily create a
663        new, unique EXTERNAL-FORMAT object: two calls to
664        MAKE-EXTERNAL-FORMAT with the same arguments made in the same
665        dynamic environment return the same (eq) object.
666        </para>
667      </refsect1>
668    </refentry>
669
670  </sect2>
671
672  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
673  <para>Line termination keywords indicate which characters are used
674  to indicate the end of a line.  On input, the external line
675  termination characters are replaced by <literal>#\Newline</literal>
676  and on output, <literal>#\Newline</literal>s are converted to the
677  external line termination characters.</para>
678  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
679  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
680    <thead>
681      <row>
682        <entry>keyword</entry>
683        <entry>character(s)</entry>
684      </row>
685    </thead>
686    <tbody>
687      <row>
688        <entry><literal>:UNIX</literal></entry>
689        <entry><literal>#\Linefeed</literal></entry>
690      </row>
691      <row>
692        <entry><literal>:MACOS</literal></entry>
693        <entry><literal>#\Return</literal></entry>
694      </row>
695      <row>
696        <entry><literal>:CR</literal></entry>
697        <entry><literal>#\Return</literal></entry>
698      </row>
699      <row>
700        <entry><literal>:CRLF</literal></entry>
701        <entry><literal>#\Return #\Linefeed</literal></entry>
702      </row>
703      <row>
704        <entry><literal>:CP/M</literal></entry>
705        <entry><literal>#\Return #\Linefeed</literal></entry>
706      </row>
707      <row>
708        <entry><literal>:MSDOS</literal></entry>
709        <entry><literal>#\Return #\Linefeed</literal></entry>
710      </row>
711      <row>
712        <entry><literal>:DOS</literal></entry>
713        <entry><literal>#\Return #\Linefeed</literal></entry>
714      </row>
715      <row>
716        <entry><literal>:WINDOWS</literal></entry>
717        <entry><literal>#\Return #\Linefeed</literal></entry>
718      </row>
719      <row>
720        <entry><literal>:INFERRED</literal></entry>
721        <entry>see below</entry>
722      </row>
723      <row>
724        <entry><literal>:UNICODE</literal></entry>
725        <entry><literal>#\Line_Separator</literal></entry>
726      </row>
727    </tbody>
728  </tgroup>
729  </table>
730  <para><literal>:INFERRED</literal> means that a stream's
731  line-termination convention is determined by looking at the contents
732  of a file.  It is only useful for <literal>FILE-STREAM</literal>s
733  that're open for <literal>:INPUT</literal> or
734  <literal>:IO</literal>.  The first buffer full of data is examined,
735  and if a <literal>#\Return</literal> character occurs before any
736  <literal>#\Linefeed</literal> character, then the line termination
737  type is set to <literal>:MACOS</literal>, otherwise it is set to
738  <literal>:UNIX</literal>.</para>
739  </sect2>
740 
741
742
743  <sect2 id="Character-Encodings"><title>Character Encodings</title>
744    <para>Internally, all characters and strings in &CCL; are in
745    UTF-32.  Externally, files or socket streams may encode characters
746    in a wide variety of ways.  The International Organization for
747    Standardization, widely known as ISO, defines many of these
748    character encodings.  &CCL; implements some of these encodings as
749    detailed below.  These encodings are part of the specification of
750    external formats <xref linkend="External-Formats"/>.  When reading
751    from a stream, characters are converted from the specified
752    external character encoding to UTF-32.  When writing to a stream,
753    characters are converted from UTF-32 to the specified character
754    encoding.</para>
755
756    <para>Internally, CHARACTER-ENCODINGs are objects (structures)
757    that are named by character encoding keywords (:ISO-8859-1,
758    :UTF-8, etc.).  The structures contain attributes of the encoding
759    and functions used to encode/decode external data, but unless
760    you're trying to define or debug an encoding there's little reason
761    to know much about the CHARACTER-ENCODING objects and it's usually
762    preferable to refer to a character encoding by its name.
763    </para>
764
765    <para>
766    </para>
767
768    <sect3><title>Encoding Problems</title>
769      <para>On output to streams with character encodings that can
770      encode the full range of Unicode&mdash;and on input from any
771      stream&mdash;"unencodable characters" are represented using the
772      Unicode #\Replacement_Character (= #\U+fffd); the presence of
773      such a character usually indicates that something got lost in
774      translation.  Either data wasn't encoded properly or there was a
775      bug in the decoding process.</para>
776    </sect3>
777
778    <sect3><title>Byte Order Marks</title>
779      <para>The endianness of a character encoding is sometimes
780      explicit, and sometimes not.  For example,
781      <literal>:UTF-16BE</literal> indicates big-endian, but
782      <literal>:UTF-16</literal> does not specify endianness.  A byte
783      order mark is a special character that may appear at the
784      beginning of a stream of encoded characters to specify the
785      endianness of a multi-byte character encoding.  (It may also be
786      used with UTF-8 character encodings, where it is simply used to
787      indicate that the encoding is UTF-8.)</para>
788
789      <para>&CCL; writes a byte order mark as the first character
790      of a file or socket stream when the endianness of the character
791      encoding is not explicit.  &CCL; also expects a byte order
792      mark on input from streams where the endianness is not
793      explicit. If a byte order mark is missing from input data, that
794      data is assumed to be in big-endian order.</para>
795
796      <para>A byte order mark from a UTF-8 encoded input stream is not
797      treated specially and just appears as a normal character from
798      the input stream.  It is probably a good idea to skip over this
799      character.</para>
800    </sect3>
801
802  <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
803    <para>The set of character encodings supported by &CCL; can be
804    retrieved by calling
805    <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>
806
807
808      <refentry id="f_describe-character-encodings">
809        <indexterm zone="f_describe-character-encodings">
810          <primary>[fn-name]</primary>
811        </indexterm>
812
813        <refnamediv>
814          <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
815          <refpurpose>Writes descriptions of defined character
816          encodings to <varname>*terminal-io*</varname>.</refpurpose>
817          <refclass>Function</refclass>
818        </refnamediv>
819
820        <refsynopsisdiv>
821          <synopsis>
822            <function>describe-character-encodings</function>
823          </synopsis>
824        </refsynopsisdiv>
825
826        <refsect1>
827          <title>Description</title>
828
829          <para>Writes descriptions of all defined character encodings
830          to <varname>*terminal-io*</varname>.  These descriptions
831          include the names of the encoding's aliases and a doc string
832          which briefly describes each encoding's properties and
833          intended use.</para>
834        </refsect1>
835
836        <refsect1>
837          <title>See Also</title>
838         
839          <simplelist type="inline">
840            <member><xref linkend="Character-Encodings"/></member>
841            <member><xref linkend="External-Formats"/></member>
842            <member><xref linkend="Supported-Character-Encodings"/></member>
843          </simplelist>
844        </refsect1>
845      </refentry>
846  </sect3>
847
848  <sect3 id="Supported-Character-Encodings"><title>Supported Character Encodings</title>
849     <para>The list of supported encodings is reproduced here.  Most
850     encodings have aliases, e.g. the encoding named
851     <literal>:ISO-8859-1</literal> can also be referred to by the
852     names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
853     among others.  Where possible, the keywordized name of an
854     encoding is equivalent to the preferred MIME charset name (and
855     the aliases are all registered IANA charset names.)</para>
856
857  <variablelist>
858    <varlistentry><term><literal>:ISO-8859-1</literal></term>
859       <listitem><para>An 8-bit, fixed-width character encoding in
860       which all character codes map to their Unicode
861       equivalents. Intended to support most characters used in most
862       Western European languages.</para>
863       <para>&CCL; uses ISO-8859-1 encoding for
864       <varname>*TERMINAL-IO*</varname> and for all streams whose
865       EXTERNAL-FORMAT isn't explicitly specified.  The default for
866       <varname>*TERMINAL-IO*</varname> can be set via the
867       <literal>-K</literal> command-line argument (see <xref
868       linkend="Command-Line-Options"/>).
869       </para>
870       <para>ISO-8859-1 just covers the first 256 Unicode code
871       points, where the first 128 code points are equivalent to
872       US-ASCII.  That should be pretty much equivalent to what
873       earliers versions of &CCL; did that only supported 8-bit characters,
874       but it may not be optimal for users working in a particular
875       locale.</para>
876       <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
877       :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
878     </varlistentry>
879    <varlistentry><term><literal>:ISO-8859-2</literal></term>
880       <listitem><para>An 8-bit, fixed-width character encoding in
881       which codes #x00-#x9f map to their Unicode equivalents and
882       other codes map to other Unicode character values.  Intended to
883       provide most characters found in most languages used in
884       Central/Eastern Europe.</para>
885       <para>Aliases: <literal>:ISO_8859-2, :LATIN-2, :L2,
886       :CSISOLATIN2</literal></para></listitem>
887     </varlistentry>
888    <varlistentry><term><literal>:ISO-8859-3</literal></term>
889       <listitem><para>An 8-bit, fixed-width character encoding in
890       which codes #x00-#x9f map to their Unicode equivalents and
891       other codes map to other Unicode character values.  Intended to
892       provide most characters found in most languages used in
893       Southern Europe.</para>
894       <para>Aliases: <literal>:ISO_8859-3, :LATIN,3 :L3,
895       :CSISOLATIN3</literal></para></listitem>
896     </varlistentry>
897    <varlistentry><term><literal>:ISO-8859-4</literal></term>
898       <listitem><para>An 8-bit, fixed-width character encoding in
899       which codes #x00-#x9f map to their Unicode equivalents and
900       other codes map to other Unicode character values.  Intended to
901       provide most characters found in most languages used in
902       Northern Europe.</para>
903       <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</literal></para></listitem>
904     </varlistentry>
905    <varlistentry><term><literal>:ISO-8859-5</literal></term>
906       <listitem><para>An 8-bit, fixed-width character encoding in
907       which codes #x00-#x9f map to their Unicode equivalents and
908       other codes map to other Unicode character values.  Intended to
909       provide most characters found in the Cyrillic
910       alphabet.</para>
911       <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
912       :ISO-IR-144</literal></para></listitem>
913     </varlistentry>
914    <varlistentry><term><literal>:ISO-8859-6</literal></term>
915       <listitem><para>An 8-bit, fixed-width character encoding in
916       which codes #x00-#x9f map to their Unicode equivalents and
917       other codes map to other Unicode character values.  Intended to
918       provide most characters found in the Arabic
919       alphabet.</para>
920       <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
921       :ISO-IR-127</literal></para></listitem>
922     </varlistentry>
923    <varlistentry><term><literal>:ISO-8859-7</literal></term>
924       <listitem><para>An 8-bit, fixed-width character encoding in
925       which codes #x00-#x9f map to their Unicode equivalents and
926       other codes map to other Unicode character values.  Intended to
927       provide most characters found in the Greek
928       alphabet.</para>
929       <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGREEK,
930       :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
931     </varlistentry>
932    <varlistentry><term><literal>:ISO-8859-8</literal></term>
933       <listitem><para>An 8-bit, fixed-width character encoding in
934       which codes #x00-#x9f map to their Unicode equivalents and
935       other codes map to other Unicode character values.  Intended to
936       provide most characters found in the Hebrew
937       alphabet.</para>
938       <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
939       :ISO-IR-138</literal></para></listitem>
940     </varlistentry>
941    <varlistentry><term><literal>:ISO-8859-9</literal></term>
942       <listitem><para>An 8-bit, fixed-width character encoding in
943       which codes #x00-#xcf map to their Unicode equivalents and
944       other codes map to other Unicode character values.  Intended to
945       provide most characters found in the Turkish
946       alphabet.</para>
947       <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
948       :ISO-IR-148</literal></para></listitem>
949     </varlistentry>
950    <varlistentry><term><literal>:ISO-8859-10</literal></term>
951       <listitem><para>An 8-bit, fixed-width character encoding in
952       which codes #x00-#x9f map to their Unicode equivalents and
953       other codes map to other Unicode character values.  Intended to
954       provide most characters found in Nordic
955       alphabets.</para>
956       <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
957       :ISO-IR-157</literal></para></listitem>
958     </varlistentry>
959    <varlistentry><term><literal>:ISO-8859-11</literal></term>
960       <listitem><para>An 8-bit, fixed-width character encoding in
961       which codes #x00-#x9f map to their Unicode equivalents and
962       other codes map to other Unicode character values.  Intended to
963       provide most characters found the Thai
964       alphabet.</para></listitem>
965     </varlistentry>
966    <varlistentry><term><literal>:ISO-8859-13</literal></term>
967       <listitem><para>An 8-bit, fixed-width character encoding in
968       which codes #x00-#x9f map to their Unicode equivalents and
969       other codes map to other Unicode character values.  Intended to
970       provide most characters found in Baltic
971       alphabets.</para></listitem>
972     </varlistentry>
973    <varlistentry><term><literal>:ISO-8859-14</literal></term>
974       <listitem><para>An 8-bit, fixed-width character encoding in
975       which codes #x00-#x9f map to their Unicode equivalents and
976       other codes map to other Unicode character values.  Intended to
977       provide most characters found in Celtic
978       languages.</para>
979       <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
980       :ISO-CELTIC</literal></para></listitem>
981     </varlistentry>
982    <varlistentry><term><literal>:ISO-8859-15</literal></term>
983       <listitem><para>An 8-bit, fixed-width character encoding in
984       which codes #x00-#x9f map to their Unicode equivalents and
985       other codes map to other Unicode character values.  Intended to
986       provide most characters found in Western European languages
987       (including the Euro sign and some other characters missing from
988       ISO-8859-1.</para>
989       <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></listitem>
990     </varlistentry>
991    <varlistentry><term><literal>:ISO-8859-16</literal></term>
992       <listitem><para>An 8-bit, fixed-width character encoding in
993       which codes #x00-#x9f map to their Unicode equivalents and
994       other codes map to other Unicode character values.  Intended to
995       provide most characters found in Southeast European
996       languages.</para>
997       <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
998       :ISO-CELTIC</literal></para></listitem>
999     </varlistentry>
1000    <varlistentry><term><literal>:MACINTOSH</literal></term>
1001       <listitem><para>An 8-bit, fixed-width character encoding in
1002       which codes #x00-#x7f map to their Unicode equivalents and
1003       other codes map to other Unicode character values.
1004       Traditionally used on Classic MacOS to encode characters used
1005       in western languages.</para>
1006       <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
1007       :MACROMAN</literal></para></listitem>
1008     </varlistentry>
1009    <varlistentry><term><literal>:UCS-2</literal></term>
1010       <listitem><para>A 16-bit, fixed-length encoding in which
1011       characters with CHAR-CODEs less than #x10000 can be encoded in
1012       a single 16-bit word.  The endianness of the encoded data is
1013       indicated by the endianness of a byte-order-mark character
1014       (#u+feff) prepended to the data; in the absence of such a
1015       character on input, the data is assumed to be in big-endian
1016       order.</para></listitem>
1017     </varlistentry>
1018    <varlistentry><term><literal>:UCS-2BE</literal></term>
1019       <listitem><para>A 16-bit, fixed-length encoding in which
1020       characters with CHAR-CODEs less than #x10000 can be encoded in
1021       a single 16-bit big-endian word. The encoded data is implicitly
1022       big-endian; byte-order-mark characters are not interpreted on
1023       input or prepended to output.</para></listitem>
1024     </varlistentry>
1025    <varlistentry><term><literal>:UCS-2LE</literal></term>
1026       <listitem><para>A 16-bit, fixed-length encoding in which
1027       characters with CHAR-CODEs less than #x10000 can be encoded in
1028       a single 16-bit little-endian word. The encoded data is
1029       implicitly little-endian; byte-order-mark characters are not
1030       interpreted on input or prepended to output.</para></listitem>
1031     </varlistentry>
1032    <varlistentry><term><literal>:US-ASCII</literal></term>
1033       <listitem><para>An 7-bit, fixed-width character encoding in
1034       which all character codes map to their Unicode
1035       equivalents. </para>
1036       <para>Aliases: <literal>:CSASCII, :CP63,7 :IBM637, :US,
1037       :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
1038     </varlistentry>
1039    <varlistentry><term><literal>:UTF-16</literal></term>
1040       <listitem><para>A 16-bit, variable-length encoding in which
1041       characters with CHAR-CODEs less than #x10000 can be encoded in
1042       a single 16-bit word and characters with larger codes can be
1043       encoded in a pair of 16-bit words.  The endianness of the
1044       encoded data is indicated by the endianness of a
1045       byte-order-mark character (#u+feff) prepended to the data; in
1046       the absence of such a character on input, the data is assumed
1047       to be in big-endian order. Output is written in native
1048       byte-order with a leading byte-order mark.</para></listitem>
1049     </varlistentry>
1050    <varlistentry><term><literal>:UTF-16BE</literal></term>
1051       <listitem><para>A 16-bit, variable-length encoding in which
1052       characters with CHAR-CODEs less than #x10000 can be encoded in
1053       a single 16-bit big-endian word and characters with larger
1054       codes can be encoded in a pair of 16-bit big-endian words.  The
1055       endianness of the encoded data is implicit in the encoding;
1056       byte-order-mark characters are not interpreted on input or
1057       prepended to output.</para></listitem>
1058     </varlistentry>
1059    <varlistentry><term><literal>:UTF-16LE</literal></term>
1060       <listitem><para>A 16-bit, variable-length encoding in which
1061       characters with CHAR-CODEs less than #x10000 can be encoded in
1062       a single 16-bit little-endian word and characters with larger
1063       codes can be encoded in a pair of 16-bit little-endian words.
1064       The endianness of the encoded data is implicit in the encoding;
1065       byte-order-mark characters are not interpreted on input or
1066       prepended to output.</para></listitem>
1067     </varlistentry>
1068    <varlistentry><term><literal>:UTF-32</literal></term>
1069       <listitem><para>A 32-bit, fixed-length encoding in which all
1070       Unicode characters can be encoded in a single 32-bit word.  The
1071       endianness of the encoded data is indicated by the endianness
1072       of a byte-order-mark character (#u+feff) prepended to the data;
1073       in the absence of such a character on input, input data is
1074       assumed to be in big-endian order.  Output is written in native
1075       byte order with a leading byte-order mark.</para>
1076       <para>Alias: <literal>:UTF-4</literal></para></listitem>
1077     </varlistentry>
1078    <varlistentry><term><literal>:UTF-32BE</literal></term>
1079       <listitem><para>A 32-bit, fixed-length encoding in which all
1080       Unicode characters encoded in a single 32-bit word. The encoded
1081       data is implicitly big-endian; byte-order-mark characters are
1082       not interpreted on input or prepended to
1083       output.</para>
1084       <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
1085     </varlistentry>
1086    <varlistentry><term><literal>:UTF-8</literal></term>
1087       <listitem><para>An 8-bit, variable-length character encoding in
1088       which characters with CHAR-CODEs in the range #x00-#x7f can be
1089       encoded in a single octet; characters with larger code values
1090       can be encoded in 2 to 4 bytes.</para></listitem>
1091     </varlistentry>
1092    <varlistentry><term><literal>:UTF-32LE</literal></term>
1093       <listitem><para>A 32-bit, fixed-length encoding in which all
1094       Unicode characters can encoded in a single 32-bit word. The
1095       encoded data is implicitly little-endian; byte-order-mark
1096       characters are not interpreted on input or prepended to
1097       output.</para>
1098       <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
1099     </varlistentry>
1100     <varlistentry><term><literal>:Windows-31j</literal></term>
1101     <listitem><para>An 8-bit, variable-length character encoding in
1102     which character code points in the range #x00-#x7f can be encoded
1103     in a single octet; characters with larger code values can be
1104     encoded in 2 bytes.</para>
1105     <para>Aliases: <literal>:CP932, :CSWINDOWS31J</literal></para></listitem>
1106     </varlistentry>
1107     <varlistentry><term><literal>:EUC-JP</literal></term>
1108     <listitem><para>An 8-bit, variable-length character encoding in
1109     which character code points in the range #x00-#x7f can be encoded
1110     in a single octet; characters with larger code values can be
1111     encoded in 2 bytes.</para>
1112     <para>Alias: <literal>:EUCJP</literal></para></listitem>
1113     </varlistentry>
1114   </variablelist>
1115 </sect3>
1116
1117 <sect3><title>Encoding and Decoding Strings</title>
1118 <para>&CCL; provides functions to encode and decode strings
1119to and from vectors of type (simple-array (unsigned-byte 8)).</para>
1120
1121<refentry id="count-characters-in-octet-vector">
1122  <indexterm zone="count-characters-in-octet-vector">
1123    <primary>count-characters-in-octet-vector</primary>
1124  </indexterm>
1125
1126  <refnamediv>
1127    <refname>count-characters-in-octet-vector</refname>
1128    <refpurpose></refpurpose>
1129    <refclass>Function</refclass>
1130  </refnamediv>
1131
1132  <refsynopsisdiv>
1133    <synopsis>
1134        <function>count-characters-in-octet-vector</function>
1135        <parameter>vector</parameter>
1136        <parameter>&key;</parameter>
1137        <parameter>start</parameter>
1138        <parameter>end</parameter>
1139        <parameter>external-format</parameter>
1140    </synopsis>
1141  </refsynopsisdiv>
1142
1143  <refsect1><title>Description</title>
1144  <para>
1145    Returns the number of characters that would be produced by
1146    decoding <varname>vector</varname> (or the subsequence thereof
1147    delimited by <varname>start</varname> and <varname>end</varname>)
1148    according to <varname>external-format</varname>.
1149  </para>
1150  </refsect1>
1151</refentry>
1152
1153<refentry id="decode-string-from-octets">
1154  <indexterm zone="decode-string-from-octets">
1155    <primary>"decode-string-from-octets</primary>
1156  </indexterm>
1157
1158  <refnamediv>
1159    <refname>decode-string-from-octets</refname>
1160    <refpurpose></refpurpose>
1161    <refclass>Function</refclass>
1162  </refnamediv>
1163
1164  <refsynopsisdiv>
1165    <synopsis>
1166        <function>decode-string-from-octets</function>
1167        <parameter>vector</parameter>
1168        <parameter>&key;</parameter>
1169        <parameter>start</parameter>
1170        <parameter>end</parameter>
1171        <parameter>external-format</parameter>
1172        <parameter>string</parameter>
1173    </synopsis>
1174  </refsynopsisdiv>
1175
1176
1177  <refsect1><title>Description</title>
1178  <para>
1179    Decodes the octets in <varname>vector</varname> (or the subsequence
1180    of it delimited by <varname>start</varname> and
1181    <varname>end</varname>) into a string according
1182    to <varname>external-format</varname>.
1183  </para>
1184  <para>
1185    If <varname>string</varname> is supplied, output will be written into it.
1186    It must be large enough to hold the decoded characters.  If <varname>
1187    string</varname> is not supplied, a new string will be allocated to
1188    hold the decoded characters.
1189  </para>
1190  <para>
1191    Returns, as multiple values, the decoded string and the position in
1192    <varname>vector</varname> where the decoding ended.
1193  </para>
1194  </refsect1>
1195</refentry>
1196
1197<refentry id="encode-string-to-octets">
1198  <indexterm zone="encode-string-to-octets">
1199    <primary>encode-string-to-octets</primary>
1200  </indexterm>
1201
1202  <refnamediv>
1203    <refname>encode-string-to-octets</refname>
1204    <refpurpose></refpurpose>
1205    <refclass>Function</refclass>
1206  </refnamediv>
1207
1208  <refsynopsisdiv>
1209    <synopsis>
1210        <function>encode-string-to-octets</function>
1211        <parameter>string</parameter>
1212        <parameter>&key;</parameter>
1213        <parameter>start</parameter>
1214        <parameter>end</parameter>
1215        <parameter>external-format</parameter>
1216        <parameter>use-byte-order-mark</parameter>
1217        <parameter>vector</parameter>
1218        <parameter>vector-offset</parameter>
1219    </synopsis>
1220  </refsynopsisdiv>
1221
1222
1223  <refsect1><title>Description</title>
1224  <para>
1225    Encodes <varname>string</varname> (or the substring delimited by
1226    <varname>start</varname> and <varname>end</varname>)
1227    into <varname>external-format</varname> and returns, as multiple
1228    values, a vector of octets containing the encoded data and an integer
1229    that specifies the offset into the vector where the encoded data ends.
1230  </para>
1231  <para>
1232    When <varname>use-byte-order-mark</varname> is true, a byte-order mark
1233    will be included in the encoded data.
1234  </para>
1235  <para>
1236    If <varname>vector</varname> is supplied, output will be written
1237    to it.  It must be of type (simple-array (unsigned-byte 8)) and be
1238    large enough to hold the encoded data.  If it is not supplied, the function
1239    will allocate a new vector.
1240  </para>
1241  <para>
1242    If <varname>vector-offset</varname> is supplied, data will be written
1243    into the output vector starting at that offset.
1244  </para>
1245  </refsect1>
1246</refentry>
1247
1248<refentry id="string-size-in-octets">
1249  <indexterm zone="string-size-in-octets">
1250    <primary>string-size-in-octets</primary>
1251  </indexterm>
1252
1253  <refnamediv>
1254    <refname>string-size-in-octets</refname>
1255    <refpurpose></refpurpose>
1256    <refclass>Function</refclass>
1257  </refnamediv>
1258
1259  <refsynopsisdiv>
1260    <synopsis>
1261        <function>string-size-in-octets</function>
1262        <parameter>string</parameter>
1263        <parameter>&key;</parameter>
1264        <parameter>start</parameter>
1265        <parameter>end</parameter>
1266        <parameter>external-format</parameter>
1267        <parameter>use-byte-order-mark</parameter>
1268    </synopsis>
1269  </refsynopsisdiv>
1270
1271
1272  <refsect1><title>Description</title>
1273  <para>
1274    Returns the number of octets required to encode
1275    <varname>string</varname> (or the substring delimited by
1276    <varname>start</varname> and <varname>end</varname>) into
1277    <varname>external-format</varname>.
1278  </para>
1279  <para>
1280    When <varname>use-byte-order-mark</varname> is true, the returned
1281    size will include space for a byte-order marker.
1282  </para>
1283  </refsect1>
1284</refentry>
1285
1286 </sect3>
1287
1288
1289  </sect2>
1290
1291  </sect1>
1292
1293  <sect1 id="Pathanmes"><title>Pathnames</title>
1294
1295    <sect2 id="pathname-tilde-expansion">
1296      <title>Pathname Expansion</title>
1297      <para>Leading tilde (~) characters in physical pathname namestrings
1298        are expanded in the way that most shells do:</para>
1299     
1300      <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
1301        at the home directory of the user named "user".</para>
1302     
1303      <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
1304        the home directory of the current user.</para>
1305    </sect2>
1306
1307    <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>
1308
1309      <para>&CCL; sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>
1310
1311      <indexterm><primary>CCL Logical Host</primary></indexterm>
1312      <para>The <literal>CCL</literal> logical host should point to the
1313        <literal>ccl</literal> directory.  It is used for a variety of
1314        purposes by &CCL; including: locating &CCL; source code,
1315        <literal>require</literal> and <literal>provide</literal>, accessing
1316        foreign function information, and the &CCL; build process. It
1317        is set to the value of the environment variable
1318        <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
1319        openmcl shell script <xref linkend="The-ccl-Shell-Script"/>.  If
1320        <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
1321        to the directory containing the current heap image.</para>
1322    </sect2>
1323   
1324   
1325    <sect2 id="pathnames-on-darwin">
1326      <title>OS X (Darwin)</title>
1327     
1328      <para>&CCL; assumes that pathname strings are decomposed UTF-8.</para>
1329    </sect2>
1330    <sect2 id="pathnames-on-linux">
1331      <title>Linux</title>
1332     
1333      <para>Pathname strings are treated as null-terminated strings
1334        coded in the encoding named by the value returned by the function
1335      <varname>CCL:PATHNAME-ENCODING-NAME</varname>.  This value may be changed
1336      with <varname>SETF</varname>.</para>
1337    </sect2>
1338    <sect2 id="pathnames-on-freebsd">
1339      <title>FreeBSD</title>
1340     
1341      <para>Pathname strings are treated as null-terminated strings
1342        encoded according to the current locale; a future release may
1343        change this convention to use UTF-8.</para>
1344    </sect2>
1345  </sect1>
1346
1347  <sect1 id="Memory-Mapped-Files">
1348    <title>Memory-mapped Files</title>
1349    <para>In release 1.2 and later, &CCL;
1350      supports <glossterm linkend="memory_mapped_file">memory-mapped
1351        files</glossterm>. On operating systems that support memory-mapped
1352      files (including Mac OS X, Linux, and FreeBSD), the operating
1353      system can arrange for a range of virtual memory addresses to
1354      refer to the contents of an open file. As long as the file remains
1355      open, programs can read values from the file by reading addresses
1356      in the mapped range.</para>
1357
1358    <para>Using memory-mapped files may in some cases be more
1359      efficient than reading the contents of a file into a data
1360      structure in memory.</para>
1361
1362    <para>&CCL; provides the
1363      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1364      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
1365      memory-mapping. These functions return vectors whose contents are
1366      the contents of memory-mapped files. Reading an element of such a
1367      vector returns data from the corresponding position in the
1368      file.</para>
1369
1370    <para>Without memory-mapped files, a common idiom for reading the
1371      contents of files might be something like this:</para>
1372
1373    <programlisting>
1374(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
1375       (vector (make-array (file-size-to-vector-size stream)
1376                           :element-type '(unsigned-byte 8))))
1377  (read-sequence vector stream))
1378    </programlisting>
1379
1380    <para>Using a memory-mapped files has a result that is the same in
1381      that, like the above example, it returns a vector whose contents are
1382      the same as the contents of the file. It differs in that the above
1383      example creates a new vector in memory and copies the file's
1384      contents into it; using a memory-mapped file instead arranges for
1385      the vector's elements to point to the file's contents on disk
1386      directly, without copying them into memory first.</para>
1387
1388    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1389      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
1390      attempt to change an element of a vector returned by these
1391      functions results in a memory-access error. &CCL; does not
1392      currently support writing data to memory-mapped files.</para>
1393
1394    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1395      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
1396      respect &CCL;'s limit on the total size of an array. That means
1397      that you cannot use these functions to create a vector longer
1398      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
1399      supports file sizes that are larger. The value
1400      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
1401      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
1402      platforms.</para>
1403
1404    <para>
1405      <indexterm zone="map-file-to-ivector"/>
1406      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
1407        <parameter>pathname</parameter>
1408        <parameter>element-type</parameter>
1409        [Function]</command>
1410    </para>
1411
1412    <variablelist>
1413      <varlistentry>
1414        <term><varname>pathname</varname></term>
1415        <listitem>
1416          <para>The pathname of the file to be memory-mapped.</para>
1417        </listitem>
1418      </varlistentry>
1419     
1420      <varlistentry>
1421        <term><varname>element-type</varname></term>
1422        <listitem>
1423          <para>The element-type of the vector to be
1424            created. Specified as
1425            a <glossterm linkend="type-specifier">type-specifier</glossterm>
1426            that names a subtype of either <varname>SIGNED-BYTE</varname>
1427            or <varname>UNSIGNED-BYTE</varname>.</para>
1428        </listitem>
1429      </varlistentry>
1430    </variablelist>
1431
1432
1433    <para>
1434      The <varname>map-file-to-ivector</varname> function tries to
1435      open the file at <parameter>pathname</parameter> for reading. If
1436      successful, the function maps the file's contents to a range of
1437      virtual addresses. If successful, it returns a read-only vector
1438      whose element-type is given
1439      by <parameter>element-type</parameter>, and whose contents are
1440      the contents of the memory-mapped file.
1441    </para>
1442
1443    <para>The returned vector is
1444      a <glossterm linkend="displaced-array">displaced-array</glossterm>
1445      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
1446        element-type)</varname>. The target of the displaced array is a
1447      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
1448      elements are the contents of the memory-mapped file.</para>
1449
1450    <para>Because of alignment issues, the mapped file's contents
1451      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
1452      64-bit platforms) into the vector. The displaced array returned
1453      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
1454      it's usually more efficient to operate on the underlying simple
1455      1-dimensional array.  Given a displaced array (like the value
1456      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
1457      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
1458      the displacement index in elements.
1459    </para>
1460
1461    <para>Currently, &CCL; supports only read operations on
1462      memory-mapped files. If you try to change the contents of an array
1463      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
1464      a memory error.</para>
1465
1466    <para>
1467      <indexterm zone="unmap-ivector"/>
1468      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
1469        <parameter>displaced-array</parameter>
1470        [Function]</command>
1471    </para>
1472
1473    <para>If the argument is a displaced-array returned
1474      by <varname>map-file-to-ivector</varname>, and if it has not yet
1475      been unmapped by this function,
1476      then <varname>unmap-ivector</varname> undoes the memory mapping,
1477      closes the mapped file, and changes the displaced-array so that its
1478      target is an empty vector (of length zero).</para>
1479
1480    <para>
1481      <indexterm zone="map-file-to-octet-vector"/>
1482      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
1483        <parameter>pathname</parameter>
1484        [Function]</command>
1485    </para>
1486
1487    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
1488        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
1489      for the common case of memory-mapping a file as a vector of
1490      bytes.</para>
1491
1492    <para>
1493      <indexterm zone="unmap-octet-vector"/>
1494      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
1495        <parameter>displaced-array</parameter>
1496        [Function]</command>
1497    </para>
1498
1499    <para>This function is a synonym
1500      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
1501  </sect1>
1502
1503  <!-- ============================================================ -->
1504  <sect1 id="Static_Variables">
1505    <title>Static Variables</title>
1506
1507    <para>&CCL; supports the definition
1508      of <glossterm linkend="static_variable">static
1509        variables</glossterm>, whose values are the same across threads,
1510      and which may not be dynamically bound. The value of a static
1511      variable is thus the same across all threads; changing the value
1512      in one thread changes it for all threads.</para> 
1513
1514    <para>Attempting to dynamically rebind a static variable (for
1515      instance, by using <varname>LET</varname>, or using the variable name as
1516      a parameter in a <varname>LAMBDA</varname> form) signals an
1517      error. Static variables are shared global resources; a dynamic
1518      binding is private to a single thread.</para>
1519
1520    <para>Static variables therefore provide a simple way to share
1521      mutable state across threads. They also provide a simple way to
1522      introduce race conditions and obscure bugs into your code, since
1523      every thread reads and writes the same instance of a given static
1524      variable. You must take care, therefore, in how you change the
1525      values of static variables, and use normal multithreaded
1526      programming techniques, such as locks or semaphores, to protect
1527      against race conditions.</para>
1528
1529    <para>In &CCL;, access to a static variable is usually faster than
1530      access to a special variable that has not been declared
1531      static.</para>
1532
1533    <para>
1534      <indexterm zone="defstatic"/>
1535      <command><varname id="defstatic">DEFSTATIC</varname>
1536        <parameter>var</parameter>
1537        <parameter>value</parameter>
1538        &key;
1539        <parameter>doc-string</parameter>
1540        [Macro]</command>
1541    </para>
1542   
1543    <variablelist>
1544      <varlistentry>
1545        <term><varname>var</varname></term>
1546        <listitem>
1547          <para>The name of the new static variable.</para>
1548        </listitem>
1549      </varlistentry>
1550     
1551      <varlistentry>
1552        <term><varname>value</varname></term>
1553        <listitem>
1554          <para>The initial value of the new static variable.</para>
1555        </listitem>
1556      </varlistentry>
1557     
1558      <varlistentry>
1559        <term><varname>doc-string</varname></term>
1560        <listitem>
1561          <para>A documentation string that is assigned to the new
1562            variable.</para>
1563        </listitem>
1564      </varlistentry>
1565    </variablelist>
1566
1567    <para>Proclaims the
1568      variable <glossterm linkend="special_variable">special</glossterm>,
1569      assigns the variable the supplied value, and assigns
1570      the <varname>doc-string</varname> to the
1571      variable's <varname>VARIABLE</varname> documentation. Marks the
1572      variable static, preventing any attempt to dynamically rebind
1573      it. Any attempt to dynamically rebind <varname>var</varname>
1574      signals an error.</para>
1575  </sect1>
1576
1577  <!-- ============================================================ -->
1578  <sect1 id="Saving-Applications">
1579    <title>Saving Applications</title>
1580    <indexterm zone="Saving-Applications">
1581      <primary>save-application</primary>
1582    </indexterm>
1583
1584    <para>&CCL; provides the
1585      function <literal>CCL:SAVE-APPLICATION</literal>, which creates a file
1586      containing an archived Lisp memory image.</para>
1587
1588    <para>&CCL; consists of a small executable called the
1589      Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
1590      implements the very lowest level features of the Lisp system, and
1591      an <glossterm linkend="lisp_image">image</glossterm>, which
1592      contains the in-memory representation of most of the Lisp system,
1593      including functions, data structures, variables, and so on. When
1594      you start &CCL;, you are launching the kernel, which then locates
1595      and reads an image file, restoring the archived image in
1596      memory. Once the image is fully restored, the Lisp system is
1597      running.</para>
1598
1599    <para>Using <literal>CCL:SAVE-APPLICATION</literal>, you can create a
1600      file that contains a modified image, one that includes any changes
1601      you've made to the running Lisp system. If you later pass your
1602      image file to the &CCL; kernel as a command-line parameter, it
1603      then loads your image file instead of its default one, and &CCL;
1604      starts up with your modifications.</para>
1605
1606    <para>If this scenario seems to you like a convenient way to
1607      create an application, that's just as intended. You can create an
1608      application by modifying the running Lisp until it does what you
1609      want, then use <literal>CCL:SAVE-APPLICATION</literal> to preserve your
1610      changes and later load them for use.</para>
1611
1612    <para>In fact, you can go further than that. You can replace
1613      &CCL;'s <glossterm linkend="toplevel_function">toplevel
1614        function</glossterm> with your own, and then, when the image is
1615      loaded, the Lisp system immediately performs your tasks rather
1616      than the default tasks that make it a Lisp development system. If
1617      you save an image in which you have done this, the resulting Lisp
1618      system is your tool rather than a Lisp development system.</para>
1619
1620    <para>You can go a step further still. You can
1621      tell <literal>CCL:SAVE-APPLICATION</literal> to prepend the Lisp kernel
1622      to the image file. Doing this makes the resulting image into a
1623      self-contained executable binary. When you run the resulting file,
1624      the Lisp kernel immediately loads the attached image file and runs
1625      your saved system. The Lisp system that starts up can have any
1626      behavior you choose. It can be a Lisp development system, but with
1627      your customizations; or it can immediately perform some task of
1628      your design, making it a specialized tool rather than a general
1629      development system.</para>
1630
1631    <para>In other words, you can develop any application you like by
1632      interactively modifying &CCL; until it does what you want, then
1633      using <literal>CCL:SAVE-APPLICATION</literal> to preserve your changes
1634      in an executable image.</para>
1635
1636    <para>On Mac OS X,
1637      the <link linkend="application_builder">application builder</link>
1638      uses <literal>CCL:SAVE-APPLICATION</literal> to create the executable
1639      portion of the <glossterm linkend="application_bundle">application
1640        bundle</glossterm>. Double-clicking the application bundle runs
1641      the executable image created
1642      by <literal>CCL:SAVE-APPLICATION</literal>.</para>
1643
1644    <para>Also on Mac OS X, &CCL; supports an object type
1645      called <literal>MACPTR</literal>, which is the type of pointers into the
1646      foreign (Mac OS) heap. Examples of
1647      commonly-user <literal>MACPTR</literal> objects are Cocoa windows and
1648      other dynamically-allocated Mac OS system objects.</para>
1649
1650    <para>Because a <literal>MACPTR</literal> object is a pointer into a
1651      foreign heap that exists for the lifetime of the running Lisp
1652      process, and because a saved image is used by loading it into a
1653      brand new Lisp process, saved <literal>MACPTR</literal> objects cannot
1654      be relied on to point to the same things when reconstituted from a
1655      saved image. In fact, a restored <literal>MACPTR</literal> object might
1656      point to anything at all&mdash;for example an arbitrary location
1657      in the middle of a block of code, or a completely nonexistent
1658      virtual address.</para> 
1659
1660    <para>For that reason, <literal>CCL:SAVE-APPLICATION</literal> converts
1661      all <literal>MACPTR</literal> objects to <literal>DEAD-MACPTR</literal>
1662      objects when writing them to an image
1663      file. A <literal>DEAD-MACPTR</literal> is functionally identical to
1664      a <literal>MACPTR</literal>, except that code that operates
1665      on <literal>MACPTR</literal> objects distinguishes them
1666      from <literal>DEAD-MACPTR</literal> objects and can handle them
1667      appropriately&mdash;signaling errors, for example.</para>
1668
1669    <para>As of &CCL; 1.2, there is one exception to the conversion
1670      of <literal>MACPTR</literal> to <literal>DEAD-MACPTR</literal> objects:
1671      a <literal>MACPTR</literal> object that points to the address 0 is not
1672      converted, because address 0 can always be relied upon to refer to
1673      the same thing.</para>
1674
1675        <indexterm zone="Saving-Applications">
1676          <primary>+NULL-PTR+</primary>
1677        </indexterm>
1678    <para>As of &CCL; 1.2, the constant <literal>CCL:+NULL-PTR+</literal>
1679      refers to a <literal>MACPTR</literal> object that points to address 0.</para>
1680
1681    <para>On all supported platforms, you can
1682      use <literal>CCL:SAVE-APPLICATION</literal> to create a command-line
1683      tool that runs the same way any command-line program
1684      does. Alternatively, if you choose not to prepend the kernel, you
1685      can save an image and then later run it by passing it as a
1686      command-line parameter to the <literal>opencml</literal>
1687      or <literal>opencml64</literal> script.</para>
1688
1689    <para>
1690      <indexterm zone="save-application"/>
1691      <command><varname id="save-application">SAVE-APPLICATION</varname>
1692        <parameter>filename</parameter>
1693        &key;
1694        <parameter>toplevel-function</parameter>
1695        <parameter>init-file</parameter>
1696        <parameter>error-handler</parameter>
1697        <parameter>application-class</parameter>
1698        <parameter>clear-clos-caches</parameter>
1699        <parameter>(purify t)</parameter>
1700        <parameter>impurify</parameter>
1701        <parameter>(mode #o644)</parameter>
1702        <parameter>prepend-kernel</parameter>
1703        [Function]</command>
1704    </para>
1705   
1706    <variablelist>
1707      <varlistentry>
1708        <term><varname>filename</varname></term>
1709        <listitem>
1710          <para>The pathname of the file to be created when &CCL;
1711            saves the application.</para>
1712        </listitem>
1713      </varlistentry>
1714     
1715      <varlistentry>
1716        <term><varname>toplevel-function</varname></term>
1717        <listitem>
1718          <para>The function to be executed after startup is
1719            complete. The toplevel is a function of no arguments that
1720            performs whatever actions the lisp system should perform
1721            when launched with this image.</para>
1722          <para>If this parameter is not supplied, &CCL; uses its
1723            default toplevel. The default toplevel runs
1724            the <glossterm linkend="REPL">read-eval-print
1725              loop</glossterm>.</para>
1726        </listitem>
1727      </varlistentry>
1728
1729      <varlistentry>
1730        <term><varname>init-file</varname></term>
1731        <listitem>
1732          <para>The pathname of a Lisp file to be loaded when the
1733            image starts up. You can place initialization expressions in
1734            this file, and use it to customize the behavior of the Lisp
1735            system when it starts up.</para>
1736        </listitem>
1737      </varlistentry>
1738     
1739      <varlistentry>
1740        <term><varname>error-handler</varname></term>
1741        <listitem>
1742          <para>The error-handling mode for the saved image. The
1743            supplied value determines what happens when an error is not
1744            handled by the saved image. Valid values
1745            are <literal>:quit</literal> (Lisp exits with an error
1746            message); <literal>:quit-quietly</literal> (Lisp exits without an
1747            error message); or <literal>:listener</literal> (Lisp enters a
1748            break loop, enabling you to debug the problem by interacting
1749            in a listener). If you don't supply this parameter, the
1750            saved image uses the default error handler
1751            (<literal>:listener</literal>).</para>
1752        </listitem>
1753      </varlistentry>
1754
1755      <varlistentry>
1756        <term><varname>application-class</varname></term>
1757        <listitem>
1758          <para>The CLOS class that represents the saved Lisp
1759            application. Normally you don't need to supply this
1760            parameter; <literal>CCL:SAVE-APPLICATION</literal> uses the
1761            class <literal>CCL:LISP-DEVELOPMENT-SYSTEM</literal>. In some
1762            cases you may choose to create a custom application class;
1763            in that case, pass the name of the class as the value for
1764            this parameter.</para>
1765        </listitem>
1766      </varlistentry>
1767     
1768      <varlistentry>
1769        <term><varname>clear-clos-caches</varname></term>
1770        <listitem>
1771          <para>If true, ensures that CLOS caches are emptied before
1772            saving the image. Normally you don't need to supply this
1773            parameter, but if for some reason you want to ensure the
1774            CLOS caches are clear when the image starts up, you can pass
1775            any true value.</para>
1776        </listitem>
1777      </varlistentry>
1778     
1779     
1780    </variablelist>
1781
1782    <para></para>
1783  </sect1>
1784
1785  <sect1 id="floating-point">
1786    <title>Floating Point Numbers</title>
1787
1788    <para>
1789      In &CCL;, the Common Lisp types short-float and single-float are
1790      implemented as IEEE single precision values; double-float and
1791      long-float are IEEE double precision values.  On 64-bit
1792      platforms, single-floats are immediate values (like fixnums and
1793      characters).
1794    </para>
1795
1796  <para>
1797    Floating-point exceptions are generally enabled and detected.  By
1798    default, threads start up with overflow, division-by-zero, and
1799    invalid enabled, and the rounding mode is set to nearest. The
1800    functions <varname>SET-FPU-MODE</varname> and
1801    <varname>GET-FPU-MODE</varname> provide user control over
1802    floating-point behavior.
1803  </para>
1804
1805  <refentry id="f_get-fpu-mode">
1806    <indexterm zone="f_get-fpu-mode">
1807      <primary>get-fpu-mode</primary>
1808    </indexterm>
1809
1810    <refnamediv>
1811      <refname>GET-FPU-MODE</refname>
1812      <refpurpose>
1813        Return the state of exception-enable and rounding-mode control
1814        flags for the current thread.
1815      </refpurpose>
1816      <refclass>Function</refclass>
1817    </refnamediv>
1818   
1819    <refsynopsisdiv>
1820      <synopsis><function>get-fpu-mode</function> &optional; mode</synopsis>
1821    </refsynopsisdiv>
1822
1823    <refsect1>
1824      <title>Arguments and Values</title>
1825      <variablelist>
1826        <varlistentry>
1827          <term>mode</term>
1828          <listitem>
1829            <para>
1830              One of the keywords :rounding-mode, :overflow,
1831              :underflow, :division-by-zero, :invalid, :inexact.
1832            </para>
1833          </listitem>
1834        </varlistentry>
1835      </variablelist>
1836    </refsect1>
1837   
1838    <refsect1>
1839      <title>Description</title>
1840      <para>
1841        If <varname>mode</varname> is supplied, returns the value of
1842        the corresponding control flag for the current thread.
1843      </para>
1844      <para>
1845        Otherwise, returns a list of keyword/value pairs which
1846        describe the floating-point exception-enable and rounding-mode
1847        control flags for the current thread.
1848      </para>
1849      <variablelist>
1850        <varlistentry>
1851          <term>rounding-mode</term>
1852          <listitem>
1853            <para>
1854              One of :nearest, :zero, :positive, :negative
1855            </para>
1856          </listitem>
1857        </varlistentry>
1858        <varlistentry>
1859          <term>overflow, underflow, division-by-zero, invalid, inexact
1860          </term>
1861          <listitem>
1862            <para>
1863              If true, the floating-point exception is signaled.
1864              If NIL, it is masked.
1865            </para>
1866          </listitem>
1867        </varlistentry>
1868      </variablelist>
1869    </refsect1>
1870  </refentry>
1871
1872  <refentry id="f_set-fpu-mode">
1873    <indexterm zone="f_set-fpu-mode">
1874      <primary>set-fpu-mode</primary>
1875    </indexterm>
1876
1877    <refnamediv>
1878      <refname>SET-FPU-MODE</refname>
1879      <refpurpose>
1880        Set the state of exception-enable and rounding-mode control
1881        flags for the current thread.
1882      </refpurpose>
1883      <refclass>Function</refclass>
1884    </refnamediv>
1885   
1886    <refsynopsisdiv>
1887      <synopsis><function>set-fpu-mode</function> &key;
1888      rounding-mode overflow underflow division-by-zero
1889      invalid inexact</synopsis>
1890    </refsynopsisdiv>
1891
1892    <refsect1>
1893      <title>Arguments and Values</title>
1894      <variablelist>
1895        <varlistentry>
1896          <term>rounding-mode</term>
1897          <listitem>
1898            <para>
1899              If supplied, must be one of :nearest, :zero, :positive, or
1900              :negative.
1901            </para>
1902          </listitem>
1903        </varlistentry>
1904        <varlistentry>
1905          <term>overflow, underflow, division-by-zero, invalid, inexact</term>
1906          <listitem>
1907            <para>NIL to mask the exception, T to signal it.</para>
1908          </listitem>
1909        </varlistentry>
1910      </variablelist>
1911    </refsect1>
1912   
1913    <refsect1>
1914      <title>Description</title>
1915      <para>
1916        Sets the current thread's exception-enable and rounding-mode
1917        control flags to the indicated values for arguments that are
1918        supplied, and preserves the values assoicated with those
1919        that aren't supplied.
1920      </para>
1921    </refsect1>
1922  </refentry>
1923  </sect1>
1924
1925  <sect1 id="watched-objects"><title>Watched Objects</title>
1926  <para>
1927    As of release 1.4, Clozure CL provides a way for lisp objects to
1928    be watched so that a condition will be signaled when a thread
1929    attempts to write to the watched object. For a certain class of
1930    bugs (someone is changing this value, but I don't know who), this
1931    can be extremely helpful.
1932  </para>
1933  <sect2 id="watched-watch"><title>WATCH</title>
1934  <refentry id="f_watch">
1935    <indexterm zone="f_watch">
1936      <primary>watch</primary>
1937    </indexterm>
1938   
1939    <refnamediv>
1940      <refname>WATCH</refname>
1941      <refpurpose>
1942        Monitor a lisp object for writes.
1943      </refpurpose>
1944      <refclass>Function</refclass>
1945    </refnamediv>
1946   
1947    <refsynopsisdiv>
1948      <synopsis><function>watch</function> &optional; object</synopsis>
1949    </refsynopsisdiv>
1950   
1951    <refsect1>
1952      <title>Arguments and Values</title>
1953      <variablelist>
1954        <varlistentry>
1955          <term>object</term>
1956          <listitem>
1957            <para>
1958              Any memory-allocated lisp object.
1959            </para>
1960          </listitem>
1961        </varlistentry>
1962      </variablelist>
1963    </refsect1>
1964
1965    <refsect1>
1966      <title>Description</title>
1967      <para>
1968        The WATCH function arranges for the specified object to be
1969        monitored for writes. This is accomplished by copying the
1970        object to its own set of virtual memory pages, which are then
1971        write-protected. This protection is enforced by the computer's
1972        memory-management hardware; the write-protection does not slow
1973        down reads at all.
1974      </para>
1975      <para>
1976        When any write to the object is attempted, a
1977        WRITE-TO-WATCHED-OBJECT condition will be signaled.
1978      </para>
1979      <para>
1980        When called with no arguments, WATCH returns a freshly-consed
1981        list of the objects currently being watched.
1982      </para>
1983      <para>
1984        WATCH returns NIL if the object cannot be watched (typically
1985        because the object is in a static or pure memory area).
1986      </para>
1987    </refsect1>
1988    <refsect1 id="watch-dwim"><title>DWIM</title>
1989    <para>
1990      WATCH operates at a fairly low level; it is not possible to
1991      avoid the details of the internal representation of objects.
1992      Nevertheless, as a convenience, WATCHing a standard-instance,
1993      a hash-table, or a multi-dimensional or non-simple CL array
1994      will watch the underlying slot-vector, hash-table-vector, or
1995      data-vector, respectively.
1996      </para>
1997    </refsect1>
1998    <refsect1 id="watch-discuss"><title>Discussion</title>
1999    <para>
2000      WATCH can monitor any memory-allocated lisp object.
2001    </para>
2002    <para>
2003      In Clozure CL, a memory-allocated object is either a cons cell
2004      or a uvector.
2005    </para>
2006    <para>
2007      WATCH operates on cons cells, not lists. In order to watch a
2008      chain of cons cells, each cons cell must be watched
2009      individually. Because each watched cons cell takes up its own
2010      own virtual memory page (4 Kbytes), it's only feasible to watch
2011      relatively short lists.
2012    </para>
2013    <para>
2014      If a memory-allocated object isn't a cons cell, then it is a
2015      vector-like object called a uvector. A uvector is a
2016      memory-allocated lisp object whose first word is a header that
2017      describes the object's type and the number of elements that it
2018      contains.
2019    </para>
2020    <para>
2021      So, a hash table is a uvector, as is a string, a standard
2022      instance, a double-float, a CL array or vector, and so forth.
2023    </para>
2024    <para>
2025      Some CL objects, like strings and other simple vectors, map in a
2026      straightforward way onto the uvector representation. It is easy
2027      to understand what happens in such cases. The uvector index
2028      corresponds directly to the vector index:
2029    </para>
2030    <programlisting>
2031<![CDATA[
2032? (defvar *s* "xxxxx")
2033*S*
2034? (watch *s*)
2035"xxxxx"
2036? (setf (char *s* 3) #\o)
2037> Error: Write to watched uvector "xxxxx" at index 3
2038>        Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx)))
2039> While executing: SET-CHAR, in process listener(1).
2040> Type :POP to abort, :R for a list of available restarts.
2041> Type :? for other options.
2042]]>
2043    </programlisting>
2044    <para>
2045      In the case of more complicated objects (e.g., a hash-table, a
2046      standard-instance, a package, etc.), the elements of the uvector
2047      are like slots in a structure. It's necessary to know which one
2048      of those "slots" contains the data that will be changed when the
2049      object is written to.
2050    </para>
2051    <para>
2052      As mentioned above, watch knows about arrays, hash-tables, and
2053      standard-instances, and will automatically watch the appropriate
2054      data-containing element.
2055    </para>
2056    <para>
2057      An example might make this clearer.
2058    </para>
2059    <programlisting>
2060<![CDATA[
2061? (defclass foo ()
2062    (slot-a slot-b slot-c))
2063#<STANDARD-CLASS FOO>
2064? (defvar *a-foo* (make-instance 'foo))
2065*A-FOO*
2066? (watch *a-foo*)
2067#<SLOT-VECTOR #xDB00D>
2068;;; Note that WATCH has watched the internal slot-vector object
2069? (setf (slot-value *a-foo* 'slot-a) 'foo)
2070> Error: Write to watched uvector #<SLOT-VECTOR #xDB00D> at index 1
2071>        Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi)))
2072> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1).
2073> Type :POP to abort, :R for a list of available restarts.
2074> Type :? for other options.
2075]]>
2076    </programlisting>
2077    <para>
2078      Looking at a backtrace would presumably show what object and
2079      slot name were written.
2080    </para>
2081    <para>
2082      Note that even though the write was to slot-a, the uvector index
2083      was 1 (not 0). This is because the first element of a
2084      slot-vector is a pointer to the instance that owns the slots. We
2085      can retrieve that to look at the object that was modified:
2086    </para>
2087    <programlisting>
2088<![CDATA[
20891 > (uvref (write-to-watched-object-object *break-condition*) 0)
2090#<FOO #x30004113502D>
20911 > (describe *)
2092#<FOO #x30004113502D>
2093Class: #<STANDARD-CLASS FOO>
2094Wrapper: #<CLASS-WRAPPER FOO #x300041135EBD>
2095Instance slots
2096SLOT-A: #<Unbound>
2097SLOT-B: #<Unbound>
2098SLOT-C: #<Unbound>
20991 >
2100]]> 
2101    </programlisting>
2102    </refsect1>
2103  </refentry>
2104</sect2>
2105<sect2 id="watched-unwatch"><title>UNWATCH</title>
2106<refentry id="f_unwatch">
2107  <indexterm zone="f_unwatch">
2108    <primary>unwatch</primary>
2109  </indexterm>
2110 
2111  <refnamediv>
2112    <refname>UNWATCH</refname>
2113      <refpurpose>
2114        Stop monitoring a lisp object for writes.
2115      </refpurpose>
2116      <refclass>Function</refclass>
2117  </refnamediv>
2118 
2119  <refsynopsisdiv>
2120    <synopsis><function>unwatch</function> object</synopsis>
2121  </refsynopsisdiv>
2122 
2123  <refsect1><title>Description</title>
2124  <para>
2125    The UNWATCH function ensures that the specified object is in
2126    normal, non-monitored memory. If the object is not currently
2127    being watched, UNWATCH does nothing and returns NIL. Otherwise,
2128    the newly unwatched object is returned.
2129  </para>
2130  </refsect1>
2131</refentry>
2132</sect2>
2133<sect2 id="watched-write-to-watched-object">
2134  <title>WRITE-TO-WATCHED-OBJECT</title>
2135  <refentry id="c_write-to-watched-object">
2136    <indexterm zone="c_write-to-watched-object">
2137      <primary>write-to-watched-object</primary>
2138    </indexterm>
2139   
2140    <refnamediv>
2141      <refname>WRITE-TO-WATCHED-OBJECT</refname>
2142      <refpurpose>
2143        Condition signaled when a write to a watched object is attempted.
2144      </refpurpose>
2145      <refclass>Condition</refclass>
2146    </refnamediv>
2147
2148    <refsect1><title>Discussion</title>
2149    <para>
2150      This condition is signaled when a watched object is written
2151      to. There are three slots of interest:
2152    </para>
2153    <variablelist>
2154      <varlistentry>
2155        <term>object</term>
2156        <listitem>
2157          <para>
2158            The actual object that was the destination of the write.
2159          </para>
2160        </listitem>
2161      </varlistentry>
2162      <varlistentry>
2163        <term>offset</term>
2164        <listitem>
2165          <para>
2166            The byte offset from the tagged object pointer to the
2167            address of the write.
2168          </para>
2169        </listitem>
2170      </varlistentry>
2171      <varlistentry>
2172        <term>instruction</term>
2173        <listitem>
2174          <para>
2175            The disassembled machine instruction that attempted the write.
2176          </para>
2177        </listitem>
2178      </varlistentry>
2179    </variablelist>
2180    </refsect1>
2181
2182    <refsect1><title>Restarts</title>
2183    <para>
2184      A few restarts are provided: one will skip over the faulting
2185      write instruction and proceed; another offers to unwatch the
2186      object and continue.
2187    </para>
2188    <para>
2189      There is also an emulate restart. In some common cases, the
2190      faulting write instruction can be emulated, enabling the write
2191      to be performed without having to unwatch the object (and
2192      therefore let other threads potentially write to it). If the
2193      faulting instruction isn't recognized, the emulate restart will
2194      not be offered.
2195    </para>
2196    </refsect1>
2197  </refentry>
2198</sect2>
2199<sect2 id="watch-notes"><title>Notes</title>
2200<para>
2201  Although some care has been taken to minimize potential problems
2202  arising from watching and unwatching objects from multiple
2203  threads, there may well be subtle race conditions present that
2204  could cause bad behavior.
2205</para>
2206<para>
2207  For example, suppose that a thread attempts to write to a watched
2208  object. This causes the operating system to generate an
2209  exception. The lisp kernel figures out what the exception is, and
2210  calls back into lisp to signal the write-to-watched-object
2211  condition and perhaps handle the error.
2212</para>
2213<para>
2214  Now, as soon lisp code starts running again (for the callback),
2215  it's possible that some other thread could unwatch the very
2216  watched object that caused the exception, perhaps before we even
2217  have a chance to signal the condition, much less respond to it.
2218</para>
2219<para>
2220  Having the object unwatched out from underneath a handler may at
2221  least confuse it, if not cause deeper trouble. Use caution with
2222  unwatch.
2223</para>
2224</sect2>
2225<sect2 id="watch-examples"><title>Examples</title>
2226<para>
2227  Here are a couple more examples in addition to the above examples
2228  of watching a string and a standard-instance.
2229</para>
2230<sect3><title>Fancy arrays</title>
2231<programlisting>
2232?  (defvar *f* (make-array '(2 3) :element-type 'double-float))
2233*F*
2234? (watch *f*)
2235#(0.0D0 0.0D0 0.0D0 0.0D0 0.0D0 0.0D0)
2236;;; Note that the above vector is the underlying data-vector for the array
2237? (setf (aref *f* 1 2) pi)
2238> Error: Write to watched uvector #&lt;VECTOR 6 type DOUBLE-FLOAT, simple> at index 5
2239>        Faulting instruction: (movq (% rax) (@ -5 (% r8) (% rdi)))
2240> While executing: ASET, in process listener(1).
2241> Type :POP to abort, :R for a list of available restarts.
2242> Type :? for other options.
22431 >
2244  </programlisting>
2245  <para>
2246    In this case, uvector index in the report is the row-major index
2247    of the element that was written to.
2248  </para>
2249  </sect3>
2250  <sect3><title>Hash tables</title>
2251  <para>
2252    Hash tables are surprisingly complicated. The representation of a
2253    hash table includes an element called a hash-table-vector. The
2254    keys and values of the elements are stored pairwise in this
2255    vector.
2256  </para>
2257  <para>
2258    One problem with trying to monitor hash tables for writes is that
2259    the underlying hash-table-vector is replaced with an entirely new
2260    one when the hash table is rehashed. A previously-watched
2261    hash-table-vector will not be the used by the hash table after
2262    rehashing, and writes to the new vector will not be caught.
2263  </para>
2264  <programlisting>
2265? (defvar *h* (make-hash-table))
2266*H*
2267? (setf (gethash 'noise *h*) 'feep)
2268FEEP
2269? (watch *h*)
2270#&lt;HASH-TABLE-VECTOR #xDD00D>
2271;;; underlying hash-table-vector
2272? (setf (gethash 'noise *h*) 'ding)
2273> Error: Write to watched uvector #&lt;HASH-TABLE-VECTOR #xDD00D> at index 35
2274>        Faulting instruction: (lock)
2275>          (cmpxchgq (% rsi) (@ (% r8) (% rdx)))
2276> While executing: %STORE-NODE-CONDITIONAL, in process listener(1).
2277> Type :POP to abort, :R for a list of available restarts.
2278> Type :? for other options.
2279;;; see what value is being replaced...
22801 > (uvref (write-to-watched-object-object *break-condition*) 35)
2281FEEP
2282;;; backtrace shows useful context
22831 > :b
2284*(1A109F8) : 0 (%STORE-NODE-CONDITIONAL ???) NIL
2285 (1A10A50) : 1 (LOCK-FREE-PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 653
2286 (1A10AC8) : 2 (CALL-CHECK-REGS PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 229
2287 (1A10B00) : 3 (TOPLEVEL-EVAL (SETF (GETHASH # *H*) 'DING) NIL) 709
2288 ...
2289  </programlisting>
2290  </sect3>
2291  <sect3><title>Lists</title>
2292  <para>
2293    As previously mentioned, WATCH only watches individual cons cells.
2294  </para>
2295  <programlisting>
2296? (defun watch-list (list)
2297    (maplist #'watch list))
2298WATCH-LIST
2299? (defvar *l* (list 1 2 3))
2300*L*
2301? (watch-list *l*)
2302((1 2 3) (2 3) (3))
2303? (setf (nth 2 *l*) 'foo)
2304> Error: Write to the CAR of watched cons cell (3)
2305>        Faulting instruction: (movq (% rsi) (@ 5 (% rdi)))
2306> While executing: %SETNTH, in process listener(1).
2307> Type :POP to abort, :R for a list of available restarts.
2308> Type :? for other options.
2309  </programlisting>
2310  </sect3>
2311  </sect2>
2312</sect1>
2313
2314<sect1 id="code-coverage"><title>Code Coverage</title>
2315<sect2 id="code-coverage-overview"><title>Overview</title>
2316<para>
2317  In Clozure CL 1.4 and later, code coverage provides information
2318  about which paths through generated code have been executed and
2319  which haven't. For each source form, it can report one of three
2320  possible outcomes:
2321</para>
2322<itemizedlist>
2323  <listitem>
2324    <para>
2325      Not covered: this form was never entered.
2326    </para>
2327  </listitem>
2328  <listitem>
2329    <para>
2330      Partly covered: This form was entered, and some parts were
2331      executed and some weren't.
2332    </para>
2333  </listitem>
2334  <listitem>
2335    <para>
2336      Fully covered: Every bit of code generated from this form was
2337      executed.
2338    </para>
2339  </listitem>
2340</itemizedlist>
2341</sect2>
2342
2343<sect2 id="code-coverage-limitations"><title>Limitations</title>
2344<para>
2345  While the information gathered for coverage of generated code is
2346  complete and precise, the mapping back to source forms is of
2347  necessity heuristic, and depends a great deal on the behavior of
2348  macros and the path of the source forms through compiler
2349  transforms. Source information is not recorded for variables, which
2350  further limits the source mapping. In practice, there is often
2351  enough information scattered about a partially covered function to
2352  figure out which logical path through the code was taken and which
2353  wasn't. If that doesn't work, you can try disassembling to see which
2354  parts of the compiled code were not executed: in the disassembled
2355  code there will be references to #&lt;CODE-NOTE [xxx] ...> where xxx
2356  is NIL if the code that follows was never executed and non-NIL if it
2357  was.
2358</para>
2359<para>
2360  Sometimes the situation can be improved by modifying macros to try
2361  to preserve more of the input forms, rather than destructuring and
2362  rebuilding them.
2363</para>
2364<para>
2365  Because the code coverage information is associated with compiled
2366  functions, load-time toplevel expressions do not get reported
2367  on. You can work around this by creating a function and calling
2368  it. I.e. instead of
2369  <programlisting>
2370(progn
2371  (do-this)
2372  (setq that ...) ...))
2373  </programlisting>
2374  do:
2375  <programlisting>
2376(defun init-this-and-that ()
2377  (do-this)
2378  (setq that ...)  ...)
2379(init-this-and-that)
2380  </programlisting>
2381Then you can see the coverage information in the definition of
2382init-this-and-that.
2383</para>
2384</sect2>
2385
2386<sect2 id="code-coverage-usage"><title>Usage</title>
2387<para>
2388  In order to gather code coverage information, you first have to
2389  recompile all your code to include code coverage
2390  instrumentation. Compiling files will generate code coverage
2391  instrumentation if <literal>CCL:*COMPILE-CODE-COVERAGE*</literal>
2392  is true:
2393  <programlisting>
2394(setq ccl:*compile-code-coverage* t)
2395(recompile-all-your-files)
2396  </programlisting>
2397</para>
2398<para>
2399  The compilation process will be many times slower than normal, and
2400  the fasl files will be many times bigger.
2401</para>
2402<para>
2403  When you execute function loaded from instrumented fasl files, they
2404  will record coverage information every time they are executed. The
2405  system keeps track of which instrumented files have been loaded.
2406</para>
2407<para>
2408  The following functions can be used to manage the coverage data:
2409</para>
2410
2411<refentry id="f_report-coverage">
2412  <indexterm zone="f_report-coverage">
2413    <primary>report-coverage</primary>
2414  </indexterm>
2415 
2416  <refnamediv>
2417    <refname>REPORT-COVERAGE</refname>
2418    <refpurpose>Generate code coverage report</refpurpose>
2419    <refclass>Function</refclass>
2420  </refnamediv>
2421
2422  <refsynopsisdiv>
2423    <synopsis><function>report-coverage</function> &key;
2424    (external-format :default) (statistics t) (html t)
2425    </synopsis>
2426  </refsynopsisdiv>
2427
2428  <refsect1><title>Arguments and Values</title>
2429  <variablelist>
2430    <varlistentry>
2431      <term>html</term>
2432      <listitem>
2433        <para>
2434          If non-nil, this will generate an HTML report, consisting of
2435          an index file and one html file for each instrumented source
2436          file that has been loaded in the current session. The
2437          individual source file reports are stored in the same
2438          directory as the index file.
2439        </para>
2440      </listitem>
2441    </varlistentry>
2442    <varlistentry>
2443      <term>external-format</term>
2444      <listitem>
2445        <para>
2446          Controls the external format of the html files.
2447        </para>
2448      </listitem>
2449    </varlistentry>
2450    <varlistentry>
2451      <term>statistics</term>
2452      <listitem>
2453        <para>
2454          If :statistics is non-nil, a comma-separated file is also
2455          generated with the summary of statistics. You can specify a
2456          filename for the statistics argument, otherwise
2457          "statistics.csv" is created in the output directory. See
2458          documentation of ccl:coverage-statistics below for a
2459          description of the values in the statistics file.
2460        </para>
2461      </listitem>
2462    </varlistentry>
2463  </variablelist>
2464  </refsect1>
2465  <refsect1><title>Example</title>
2466    <para>
2467      If you've loaded <filename>foo.lx64fsl</filename> and
2468      <filename>bar.lx64fsl</filename>, and have run some tests, you could
2469      do
2470    <programlisting>
2471(CCL:REPORT-COVERAGE "/my/dir/coverage/report.html")
2472    </programlisting>
2473    and this would generate <filename>report.html</filename>,
2474    <filename>foo_lisp.html</filename> and
2475    <filename>bar_lisp.html</filename>, and
2476    <filename>statistics.csv</filename> all in
2477    <filename>/my/dir/coverage/</filename>.
2478    </para>
2479  </refsect1>
2480</refentry>
2481
2482<refentry id="f_reset-coverage">
2483  <indexterm zone="f_reset-coverage">
2484    <primary>reset-coverage</primary>
2485  </indexterm>
2486 
2487  <refnamediv>
2488    <refname>reset-coverage</refname>
2489    <refpurpose>
2490      Resets all coverage data back to the "Not Executed" state
2491    </refpurpose>
2492    <refclass>Function</refclass>
2493  </refnamediv>
2494
2495  <refsect1><title>Summary</title>
2496    <para>
2497      Resets all coverage data back to the "Not Executed" state
2498    </para>
2499  </refsect1>
2500</refentry>
2501
2502<refentry id="f_clear-coverage">
2503  <indexterm zone="f_clear-coverage">
2504    <primary>clear-coverage</primary>
2505  </indexterm>
2506 
2507  <refnamediv>
2508    <refname>clear-coverage</refname>
2509    <refpurpose>
2510      Forget about all instrumented files that have been loaded.
2511    </refpurpose>
2512    <refclass>Function</refclass>
2513  </refnamediv>
2514
2515  <refsect1><title>Summary</title>
2516    <para>
2517      Gets rid of the information about which instrumented files have
2518      been loaded, so ccl:report-coverage will not report any files,
2519      and ccl:save-coverage-in-file will not save any info, until more
2520      instrumented files are loaded.
2521    </para>
2522  </refsect1>
2523</refentry>
2524
2525<refentry id="f_save-coverage-in-file">
2526  <indexterm zone="f_save-coverage-in-file">
2527    <primary>save-coverage-in-file</primary>
2528  </indexterm>
2529 
2530  <refnamediv>
2531    <refname>save-coverage-in-file</refname>
2532    <refpurpose>
2533      Save all coverage into to a file so you can restore it later.
2534    </refpurpose>
2535    <refclass>Function</refclass>
2536  </refnamediv>
2537
2538  <refsynopsisdiv>
2539    <synopsis><function>save-coverage-in-file</function> pathname
2540    </synopsis>
2541  </refsynopsisdiv>
2542
2543  <refsect1><title>Summary</title>
2544    <para>
2545      Saves all coverage info in a file, so you can restore the
2546      coverage state later. This allows you to combine multiple runs
2547      or continue in a later session. Equivalent to
2548      (ccl:write-coverage-to-file (ccl:save-coverage) pathname).
2549    </para>
2550  </refsect1>
2551</refentry>
2552
2553<refentry id="f_restore-coverage-from-file">
2554  <indexterm zone="f_restore-coverage-from-file">
2555    <primary>restore-coverage-from-file</primary>
2556  </indexterm>
2557 
2558  <refnamediv>
2559    <refname>restore-coverage-from-file</refname>
2560    <refpurpose>
2561      Load coverage state from a file.
2562    </refpurpose>
2563    <refclass>Function</refclass>
2564  </refnamediv>
2565
2566  <refsynopsisdiv>
2567    <synopsis><function>restore-coverage-from-file</function> pathname
2568    </synopsis>
2569  </refsynopsisdiv>
2570
2571  <refsect1><title>Summary</title>
2572    <para>
2573      Restores the coverage data previously saved with
2574      CCL:SAVE-COVERAGE-IN-FILE, for the set of instrumented fasls
2575      that were loaded both at save and restore time. I.e. coverage
2576      info is only restored for files that have been loaded in this
2577      session. For example if in a previous session you had loaded
2578      "foo.lx86fsl" and then saved the coverage info, in this session
2579      you must load the same "foo.lx86fsl" before calling
2580      ccl:restore-coverage-from-file in order to retrieve the stored
2581      coverage info for "foo".  Equivalent to (ccl:restore-coverage
2582      (ccl:read-coverage-from-file pathname)).
2583    </para>
2584  </refsect1>
2585</refentry>
2586
2587<refentry id="f_save-coverage">
2588  <indexterm zone="f_save-coverage">
2589    <primary>save-coverage</primary>
2590  </indexterm>
2591 
2592  <refnamediv>
2593    <refname>save-coverage</refname>
2594    <refpurpose>
2595      Returns a snapshot of the current coverage data.
2596    </refpurpose>
2597    <refclass>Function</refclass>
2598  </refnamediv>
2599
2600  <refsect1><title>Summary</title>
2601    <para>
2602      Returns a snapshot of the current coverage data. A snapshot is a
2603      copy of the current coverage state. It can be saved in a file
2604      with ccl:write-coverage-to-file, reinstated back as the current
2605      state with ccl:restore-coverage, or combined with other
2606      snapshots with ccl:combine-coverage.
2607    </para>
2608  </refsect1>
2609</refentry>
2610
2611<refentry id="f_restore-coverage">
2612  <indexterm zone="f_restore-coverage">
2613    <primary>restore-coverage</primary>
2614  </indexterm>
2615 
2616  <refnamediv>
2617    <refname>RESTORE-COVERAGE</refname>
2618    <refpurpose>
2619      Reinstalls a coverage snapshot as the current coverage state.
2620    </refpurpose>
2621    <refclass>Function</refclass>
2622  </refnamediv>
2623
2624  <refsynopsisdiv>
2625    <synopsis><function>restore-coverage</function> snapshot
2626    </synopsis>
2627  </refsynopsisdiv>
2628
2629  <refsect1><title>Summary</title>
2630    <para>
2631      Reinstalls a coverage snapshot as the current coverage state.
2632    </para>
2633  </refsect1>
2634</refentry>
2635
2636<refentry id="f_write-coverage-to-file">
2637  <indexterm zone="f_write-coverage-to-file">
2638    <primary>write-coverage-to-file</primary>
2639  </indexterm>
2640 
2641  <refnamediv>
2642    <refname>WRITE-COVERAGE-TO-FILE</refname>
2643    <refpurpose>
2644      Save a coverage snapshot in a file.
2645    </refpurpose>
2646    <refclass>Function</refclass>
2647  </refnamediv>
2648
2649  <refsynopsisdiv>
2650    <synopsis><function>write-coverage-to-file</function> snapshot pathname
2651    </synopsis>
2652  </refsynopsisdiv>
2653
2654  <refsect1><title>Summary</title>
2655    <para>
2656      Saves the coverage snapshot in a file. The snapshot can be
2657      loaded back with ccl:read-coverage-from-file or loaded and
2658      restored with ccl:restore-coverage-from-file. Note that the file
2659      created is actually a lisp source file and can be compiled for
2660      faster loading.
2661    </para>
2662  </refsect1>
2663</refentry>
2664
2665<refentry id="f_read-coverage-from-file">
2666  <indexterm zone="f_read-coverage-from-file">
2667    <primary>read-coverage-from-file</primary>
2668  </indexterm>
2669 
2670  <refnamediv>
2671    <refname>READ-COVERAGE-FROM-FILE</refname>
2672    <refpurpose>
2673      Return the coverage snapshot saved in a file.
2674    </refpurpose>
2675    <refclass>Function</refclass>
2676  </refnamediv>
2677
2678  <refsynopsisdiv>
2679    <synopsis><function>read-coverage-from-file</function> pathname
2680    </synopsis>
2681  </refsynopsisdiv>
2682
2683  <refsect1><title>Summary</title>
2684    <para>
2685      Returns the snapshot saved in pathname. Doesn't affect the
2686      current coverage state. pathname can be the file previously
2687      created with ccl:write-coverage-to-file or
2688      ccl:save-coverage-in-file, or it can be the name of the fasl
2689      created from compiling such a file.
2690    </para>
2691  </refsect1>
2692</refentry>
2693
2694<refentry id="f_coverage-statistics">
2695  <indexterm zone="f_coverage-statistics">
2696    <primary>coverage-statistics</primary>
2697  </indexterm>
2698 
2699  <refnamediv>
2700    <refname>COVERAGE-STATISTICS</refname>
2701    <refpurpose>
2702      Returns a sequence of coverage-statistics objects, one per source file.
2703    </refpurpose>
2704    <refclass>Function</refclass>
2705  </refnamediv>
2706
2707  <refsynopsisdiv>
2708    <synopsis><function>coverage-statistics</function>
2709    </synopsis>
2710  </refsynopsisdiv>
2711
2712  <refsect1><title>Summary</title>
2713    <para>
2714      Returns a sequence ccl:coverage-statistics objects, one for each
2715      source file, containing the same information as that written to
2716      the statistics file by ccl:report-coverage. The following
2717      accessors are defined for ccl:coverage-statistics objects:
2718      <variablelist>
2719      <varlistentry>
2720        <term><function>ccl:coverage-source-file</function></term>
2721        <listitem>
2722          <para>
2723            the name of the source file corresponding to this information
2724          </para>
2725        </listitem>
2726      </varlistentry>
2727      <varlistentry>
2728        <term><function>ccl:coverage-expressions-total</function></term>
2729        <listitem>
2730          <para>
2731            the total number of expressions
2732          </para>
2733        </listitem>
2734      </varlistentry>
2735      <varlistentry>
2736        <term><function>ccl:coverage-expressions-entered</function></term>
2737        <listitem>
2738          <para>
2739            the number of source expressions that have been entered
2740            (i.e. at least partially covered)
2741          </para>
2742        </listitem>
2743      </varlistentry>
2744      <varlistentry>
2745        <term><function>ccl:coverage-expressions-covered</function></term>
2746        <listitem>
2747          <para>
2748            the number of source expressions that were fully covered
2749          </para>
2750        </listitem>
2751      </varlistentry>
2752      <varlistentry>
2753        <term><function>ccl:coverage-unreached-branches</function></term>
2754        <listitem>
2755          <para>
2756            the number of conditionals with one branch taken and one not taken
2757          </para>
2758        </listitem>
2759      </varlistentry>
2760      <varlistentry>
2761        <term><function>ccl:coverage-code-forms-total</function></term>
2762        <listitem>
2763          <para>
2764            the total number of code forms. A code form is an
2765            expression in the final stage of compilation, after all
2766            macroexpansion and compiler transforms and simplification
2767          </para>
2768        </listitem>
2769      </varlistentry>
2770      <varlistentry>
2771        <term><function>ccl:coverage-code-forms-covered</function></term>
2772        <listitem>
2773          <para>
2774            the number of code forms that have been entered
2775          </para>
2776        </listitem>
2777      </varlistentry>
2778      <varlistentry>
2779        <term><function>ccl:coverage-functions-total</function></term>
2780        <listitem>
2781          <para>
2782            the total number of functions
2783          </para>
2784        </listitem>
2785      </varlistentry>
2786      <varlistentry>
2787        <term><function>ccl:coverage-functions-fully-covered</function></term>
2788        <listitem>
2789          <para>
2790            the number of functions that were fully covered
2791          </para>
2792        </listitem>
2793      </varlistentry>
2794      <varlistentry>
2795        <term><function>ccl:coverage-functions-partly-covered</function></term>
2796        <listitem>
2797          <para>
2798            the number of functions that were partly covered
2799          </para>
2800        </listitem>
2801      </varlistentry>
2802      <varlistentry>
2803        <term><function>ccl:coverage-functions-not-entered</function></term>
2804        <listitem>
2805          <para>
2806            the number of functions never entered
2807          </para>
2808        </listitem>
2809      </varlistentry>
2810      </variablelist>
2811    </para>
2812  </refsect1>
2813</refentry>
2814
2815<refentry id="v_compile-code-coverage">
2816  <indexterm zone="v_compile-code-coverage">
2817    <primary>*COMPILE-CODE-COVERAGE*</primary>
2818  </indexterm>
2819 
2820  <refnamediv>
2821    <refname>*COMPILE-CODE-COVERAGE*</refname>
2822    <refpurpose>
2823      When true, instrument functions for code coverage.
2824    </refpurpose>
2825    <refclass>Variable</refclass>
2826  </refnamediv>
2827
2828  <refsynopsisdiv>
2829    <synopsis><varname>*compile-code-coverage*</varname>
2830    </synopsis>
2831  </refsynopsisdiv>
2832
2833  <refsect1><title>Summary</title>
2834    <para>
2835      This variable controls whether functions are instrumented for
2836      code coverage. Files compiled while this variable is true will
2837      contain code coverage instrumentation.
2838    </para>
2839  </refsect1>
2840</refentry>
2841
2842<refentry id="v_without-compiling-code-coverage">
2843  <indexterm zone="v_without-compiling-code-coverage">
2844    <primary>without-compiling-code-coverage</primary>
2845  </indexterm>
2846 
2847  <refnamediv>
2848    <refname>WITHOUT-COMPILING-CODE-COVERAGE</refname>
2849    <refpurpose>
2850      Don't record code coverange for forms within the body.
2851    </refpurpose>
2852    <refclass>Macro</refclass>
2853  </refnamediv>
2854
2855  <refsynopsisdiv>
2856    <synopsis><function>without-compiling-code-coverage</function>
2857    </synopsis>
2858  </refsynopsisdiv>
2859
2860  <refsect1><title>Summary</title>
2861    <para>
2862      This macro arranges so that body doesn't record internal details
2863      of code coverage. It will be considered totally covered if it's
2864      entered at all. The Common Lisp macros ASSERT and CHECK-TYPE use
2865      this macro.
2866    </para>
2867  </refsect1>
2868</refentry>
2869
2870</sect2>
2871</sect1>
2872</chapter>
Note: See TracBrowser for help on using the repository browser.