Commit 1a3aecc2 authored by Daniel Kochmański's avatar Daniel Kochmański

doc: add documentation as doc subdirectory

Signed-off-by: 's avatarDaniel Kochmański <daniel@turtleware.eu>
parent b16aed9e
......@@ -41,6 +41,9 @@
** Enchantments:
- Documentation is now included in main repository under toplevel
directory `doc'
- Update libffi to version 3.2.1
- Update asdf to version 3.1.4
......@@ -52,8 +55,6 @@
- Dead code removals, untiabifying sources
- Methods may now specialize on single-float and double-float
- Better quality of generated code (explicit casting when necessary)
** Issues fixed:
......
ecl2.xml
html/
tmp/
This diff is collapsed.
Instructions to edit/build this book
====================================
This is the recommended way to edit this manual. It is the one I found
most convenient both under Linux and OS X.
* Install the xmlto package. You can do it in almost any Linux machine
and also under OS X using the Fink packages.
* Install Emacs (Linux) or Aquamacs (OS X).
* Make sure you have the nxml-mode package. This is available in some
Linux distributions and comes for free with Aquamacs.
* In the nxml-mode you should replace the Docbook schemas, which go
only up to version 4.2. These are the steps to do so:
- Go to http://www.docbook.org/schemas/4x.html
- Download the RELAX NG schema. It will suffice with docbook-rng-4.4.zip
- Go to the place where nxml stores its schema files. In Debian/Ubuntu
it is /usr/share/emacs/site-lisp/nxml-mode/schema, in Aquamacs it is
in /Applications/Aquamacs.app/Content/Resources/site-lisp/nxml-mode/schema.
- Make a backup copy of these schemas.
- Unzip the previous package directly on top of the directory mentioned before.
After these steps, you should be able to edit the manual. To build it,
ensure that the "xmlto" program is in some of the directories listed
in the PATH environment variable and type "make" from the command
line. This will build the HTML version.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.arrays">
<title>Arrays</title>
<section xml:id="ansi.array-limits">
<title>Array limits</title>
<para>&ECL; arrays can have up to 64 dimensions. Common-Lisp constants
related to arrays have the following values in &ECL;.</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Constant</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row>
<entry>array-rank-limit</entry>
<entry>64</entry>
</row>
<row>
<entry>array-dimension-limit</entry>
<entry>most-positive-fixnum</entry>
</row>
<row>
<entry>array-total-size-limit</entry>
<entry>array-dimension-limit</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ansi.array-spec">
<title>Specializations</title>
<para>When the elements of an array are declared to have some precise type, such as a small or large integer, a character or a floating point number, &ECL; has means to store those elements in a more compact form, known as a <emphasis>specialized array</emphasis>. The list of types for which &ECL; specializes arrays is platform dependent, but is summarized in the following table, together with the C type which is used internally and the expected size.</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Specialized type</entry>
<entry>Element C type</entry>
<entry>Size</entry>
</row>
</thead>
<tbody>
<row>
<entry><type>bit</type></entry>
<entry>-</entry>
<entry>1 bit</entry>
</row>
<row>
<entry><type>character</type></entry>
<entry><type>unsigned char</type> or <type>uint32_t</type></entry>
<entry>Depends on character range</entry>
</row>
<row>
<entry><type>base-char</type></entry>
<entry><type>unsigned char</type></entry>
<entry></entry>
</row>
<row>
<entry><type>fixnum</type></entry>
<entry><type>cl_fixnum</type></entry>
<entry>Machine word (32 or 64 bits)</entry>
</row>
<row>
<entry><type>(signed-byte 8)</type></entry>
<entry><type>int8_t</type></entry>
<entry>8 bits</entry>
</row>
<row>
<entry><type>(unsigned-byte 8)</type></entry>
<entry><type>uint8_t</type></entry>
<entry>8 bits</entry>
</row>
<row>
<entry><type>(signed-byte 16)</type></entry>
<entry><type>int16_t</type></entry>
<entry>16 bits</entry>
</row>
<row>
<entry><type>(unsigned-byte 16)</type></entry>
<entry><type>uint16_t</type></entry>
<entry>16 bits</entry>
</row>
<row>
<entry><type>(signed-byte 32)</type></entry>
<entry><type>int32_t</type></entry>
<entry>32 bits</entry>
</row>
<row>
<entry><type>(unsigned-byte 32)</type></entry>
<entry><type>uint32_t</type></entry>
<entry>32 bits</entry>
</row>
<row>
<entry><type>(signed-byte 64)</type></entry>
<entry><type>int64_t</type></entry>
<entry>64 bits</entry>
</row>
<row>
<entry><type>(unsigned-byte 64)</type></entry>
<entry><type>uint64_t</type></entry>
<entry>64 bits</entry>
</row>
<row>
<entry><type>single-float</type> or <type>short-float</type></entry>
<entry><type>float</type></entry>
<entry>32-bits IEEE float</entry>
</row>
<row>
<entry><type>double-float</type></entry>
<entry><type>double</type></entry>
<entry>64-bits IEEE float</entry>
</row>
<row>
<entry><type>long-float</type></entry>
<entry><type>long double</type></entry>
<entry>Between 96 and 128 bits.</entry>
</row>
<row>
<entry><type>t</type></entry>
<entry><type>cl_object</type></entry>
<entry>Size of a pointer.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Let us remark that some of these specialized types might not exist in your platform. This is detected using conditional reading and features (See <xref linkend="ansi.numbers.c-types"/>).</para>
</section>
<xi:include href="ref_c_arrays.xml" xpointer="ansi.arrays.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
\ No newline at end of file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.characters">
<title>Characters</title>
<para>&ECL; is fully ANSI Common-Lisp compliant in all aspects of the character
data type, with the following peculiarities.</para>
<section xml:id="ansi.characeer.unicode">
<title>Unicode vs. POSIX locale</title>
<para>There are two ways of building &ECL;: with C or with Unicode character codes. These build modes are accessed using the <code>--disable-unicode</code> and <code>--enable-unicode</code> configuration options, the last one being the default.</para>
<para>When using C characters we are actually relying on the <type>char</type> type of the C language, using the C library functions for tasks such as character conversions, comparison, etc. In this case characters are typically 8 bit wide and the character order and collation are determines by the current POSIX or C locale. This is not very accurate, leaves out many languages and character encodings but it is sufficient for small applications that do not need multilingual support.</para>
<para>When no option is specified &ECL; builds with support for a larger character set, the Unicode 6.0 standard. This uses 24 bit large character codes, also known as <emphasis>codepoints</emphasis>, with a large database of character properties which include their nature (alphanumeric, numeric, etc), their case, their collation properties, whether they are standalone or composing characters, etc.</para>
<section xml:id="ansi.character-types">
<title>Character types</title>
<para>If compiled without Unicode support, &ECL; all characters are
implemented using 8-bit codes and the type <type>extended-char</type>
is empty. If compiled with Unicode support, characters are implemented
using 24 bits and the <type>extended-char</type> type covers characters above
code 255.</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>With Unicode</entry>
<entry>Without Unicode</entry>
</row>
</thead>
<tbody>
<row>
<entry><type>standard-char</type></entry>
<entry>#\Newline,32-126</entry>
<entry>#\Newline,32-126</entry>
</row>
<row>
<entry><type>base-char</type></entry>
<entry>0-255</entry>
<entry>0-255</entry>
</row>
<row>
<entry><type>extended-char</type></entry>
<entry>-</entry>
<entry>255-16777215</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="ansi.character-names">
<title>Character names</title>
<para>All characters have a name. For non-printing characters between 0 and 32, and for 127 we use the ordinary <acronym>ASCII</acronym> names. Characters above 127 are printed and read using hexadecimal Unicode notation, with a <literal>U</literal> followed by 24 bit hexadecimal number, as in <literal>U0126</literal>.</para>
<table xml:id="table.character-names">
<title>Examples of character names</title>
<tgroup cols="2">
<thead>
<row>
<entry>Character</entry>
<entry>Code</entry>
</row>
</thead>
<tbody>
<row><entry><literal>#\Null</literal></entry><entry>0</entry></row>
<row><entry><literal>#\Ack</literal></entry><entry>1</entry></row>
<row><entry><literal>#\Bell</literal></entry><entry>7</entry></row>
<row><entry><literal>#\Backspace</literal></entry><entry>8</entry></row>
<row><entry><literal>#\Tab</literal></entry><entry>9</entry></row>
<row><entry><literal>#\Newline</literal></entry><entry>10</entry></row>
<row><entry><literal>#\Linefeed</literal></entry><entry>10</entry></row>
<row><entry><literal>#\Page</literal></entry><entry>12</entry></row>
<row><entry><literal>#\Esc</literal></entry><entry>27</entry></row>
<row><entry><literal>#\Escape</literal></entry><entry>27</entry></row>
<row><entry><literal>#\Space</literal></entry><entry>32</entry></row>
<row><entry><literal>#\Rubout</literal></entry><entry>127</entry></row>
<row><entry><literal>#\U0080</literal></entry><entry>128</entry></row>
</tbody>
</tgroup>
</table>
<para>Note that <literal>#\Linefeed</literal> is synonymous with
<literal>#\Newline</literal> and thus is a member of
<type>standard-char</type>.</para>
</section>
</section>
<section>
<title><code>#\Newline</code> characters</title>
<para>Internally, &ECL; represents the <literal>#\Newline</literal> character by a single code. However, when using external formats, &ECL; may parse character pairs as a single <literal>#\Newline</literal>, and viceversa, use multiple characters to represent a single <literal>#\Newline</literal>. See <xref linkend="ansi.streams.formats"/>.</para>
</section>
<xi:include href="ref_c_characters.xml" xpointer="ansi.characters.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
\ No newline at end of file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.conditions">
<title>Conditions</title>
<xi:include href="ref_c_conditions.xml" xpointer="ansi.conditions.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.conses">
<title>Conses</title>
<xi:include href="ref_c_conses.xml" xpointer="ansi.conses.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
\ No newline at end of file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.data-and-control">
<title>Data and control flow</title>
<section xml:id="ansi.minimal-compilation">
<title>Minimal compilation</title>
<para>Former versions of &ECL;, as well as many other lisps, used linked
lists to represent code. Executing code thus meant traversing these lists
and performing code transformations, such as macro expansion, every time
that a statement was to be executed. The result was a slow and memory
hungry interpreter.</para>
<para>Beginning with version 0.3, &ECL; was shipped with a bytecodes
compiler and interpreter which circumvent the limitations of linked
lists. When you enter code at the lisp prompt, or when you load a source
file, &ECL; begins a process known as minimal compilation. Barely this
process consists on parsing each form, macroexpanding it and translating it
into an intermediate language made of
<emphasis>bytecodes</emphasis>.</para>
<para>The bytecodes compiler is implemented in
<filename>src/c/compiler.d</filename>. The main entry point is the lisp
function <function>si::make-lambda</function>, which takes a name for the
function and the body of the lambda lists, and produces a lisp object that
can be invoked. For instance,
<screen>&gt; (defvar fun (si::make-lambda 'f '((x) (1+ x))))
*FUN*
&gt; (funcall fun 2)
3</screen></para>
<para>&ECL; can only execute bytecodes. When a list is passed to
<literal>EVAL</literal> it must be first compiled to bytecodes and, if the
process succeeds, the resulting bytecodes are passed to the
interpreter. Similarly, every time a function object is created, such as in
<function>DEFUN</function> or <function>DEFMACRO</function>, the compiler
processes the lambda form to produce a suitable bytecodes object.</para>
<para>The fact that &ECL; performs this eager compilation means that
changes on a macro are not immediately seen in code which was already
compiled. This has subtle implications. Take the following code:</para>
<screen>&gt; (defmacro f (a b) `(+ ,a ,b))
F
&gt; (defun g (x y) (f x y))
G
&gt; (g 1 2)
3
&gt; (defmacro f (a b) `(- ,a ,b))
F
&gt; (g 1 2)
3</screen>
<para>The last statement always outputs <literal>3</literal> while in former
implementations based on simple list traversal it would produce
<literal>-1</literal>.</para>
</section>
<section xml:id="ansi.functions">
<title>Function types</title>
<para>Functions in &ECL; can be of two types: they are either compiled to
bytecodes or they have been compiled to machine code using a lisp to C
translator and a C compiler. To the first category belong function loaded
from lisp source files or entered at the toplevel. To the second category
belong all functions in the &ECL; core environment and functions in files
processed by <function>compile</function> or
<function>compile-file</function>.</para>
<para>The output of <code>(symbol-function
<replaceable>fun</replaceable>)</code> is one of the following:
<itemizedlist>
<listitem><para>a function object denoting the definition of the function <literal>fun</literal>,</para></listitem>
<listitem><para>a list of the form <literal>(macro . function-object)</literal> when <literal>fun</literal> denotes a macro,</para></listitem>
<listitem><para>or simply <literal>'special</literal>, when <literal>fun</literal> denotes a special form, such as <symbol>block</symbol>, <symbol>if</symbol>, etc.</para></listitem>
</itemizedlist></para>
<para>&ECL; usually drops the source code of a function unless the global
variable <varname>si:*keep-definitions*</varname> was true when the
function was translated into bytecodes. Therefore, if you wish to use
<function>compile</function> and <function>disassemble</function> on
defined functions, you should issue <code>(setq si:*keep-definitions*
t)</code> at the beginning of your session.</para>
<para>In <xref linkend="table.function.constants"/> we list all
&CommonLisp; values related to the limits of functions.</para>
<table xml:id="table.function.constants">
<title>Function related constants</title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>call-arguments-limit</constant></entry>
<entry>65536</entry>
</row>
<row>
<entry><constant>lambda-parameters-limit</constant></entry>
<entry>call-arguments-limit</entry>
</row>
<row>
<entry><constant>multiple-values-limit</constant></entry>
<entry>64</entry>
</row>
<row>
<entry><constant>lambda-list-keywords</constant></entry>
<entry><literal>(&optional; &rest; &key; &allow-other-keys; &aux;
&whole; &environment; &body;)</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="ansi.calling-conventions">
<title>C Calling conventions</title>
<para>&ECL; is implemented using either a C or a C++ compiler. This is not a limiting factor, but imposes some constraints on how these languages are used to implement functions, multiple values, closures, etc. In particular, while C functions can be called with a variable number of arguments, there is no facility to check how many values were actually passed. This forces us to have two types of functions in &ECL;
<itemizedlist>
<listitem><para>Functions that take a fixed number of arguments have a simple C signature, with all arguments being properly declared, as in <code>cl_object cl_not(cl_object arg1)</code>.</para></listitem>
<listitem><para>Functions with a variable number of arguments, such as those acception <symbol>&optional;</symbol>, <symbol>&rest;</symbol> or <symbol>&key;</symbol> arguments, must take as first argument the number of remaining ones, as in <code>cl_object cl_list(cl_narg narg, ...)</code>. Here <replaceable>narg</replaceable> is the number of supplied arguments.</para></listitem>
</itemizedlist>
The previous conventions set some burden on the C programmer that calls &ECL;, for she must know the type of function that is being called and supply the right number of arguments. This burden disappears for Common Lisp programmers, though.</para>
<para>As an example let us assume that the user wants to invoke two functions which are part of the &ANSI; standard and thus are exported with a C name. The first example is <function>cl_cos</function>, which takes just one argument and has a signature <code>cl_object cl_cos(cl_object)</code>.</para>
<programlisting>
#include &lt;math.h&gt;
...
cl_object angle = ecl_make_double_float(M_PI);
cl_object c = cl_cos(angle);
printf("\nThe cosine of PI is %g\n", ecl_double_float(c));
</programlisting>
<para>The second example also involves some Mathematics, but now we are going to use the C function corresponding to <symbol>+</symbol>. As described in <link linkend="ansi.numbers.c-dict.ref">the C dictionary</link>, the C name for the plus operator is <function>cl_P</function> and has a signature <code>cl_object cl_P(cl_narg narg,...)</code>. Our example now reads as follows</para>
<programlisting>
cl_object one = ecl_make_fixnum(1);
cl_object two = cl_P(2, one, one);
cl_object three = cl_P(2, one, one, one);
printf("\n1 + 1 is %d\n", ecl_fixnum(two));
printf("\n1 + 1 + 1 is %d\n", ecl_fixnum(three));
</programlisting>
<para>Note that most Common Lisp functions will not have a C name. In this case one must use the symbol that names them to actually call the functions, using <function>cl_funcall</function> or <function>cl_apply</function>. The previous examples may thus be rewritten as follows</para>
<programlisting>
/* Symbol + in package CL */
cl_object plus = ecl_make_symbol("+","CL");
cl_object one = ecl_make_fixnum(1);
cl_object two = cl_funcall(3, plus, one, one);
cl_object three = cl_funcall(4, plus, one, one, one);
printf("\n1 + 1 is %d\n", ecl_fixnum(two));
printf("\n1 + 1 + 1 is %d\n", ecl_fixnum(three));
</programlisting>
<para>Another restriction of C and C++ is that functions can only take a limited number of arguments. In order to cope with this problem, &ECL; uses an internal stack to pass any argument above a hardcoded limit, <constant>ECL_C_CALL_ARGUMENTS_LIMIT</constant>, which is as of this writing 63. The use of this stack is transparently handled by the Common Lisp functions, such as <symbol>apply</symbol>, <symbol>funcall</symbol> and their C equivalents, and also by a set of macros, <link linkend="ref.ecl_va_arg"><function>cl_va_arg</function></link>, which can be used for coding functions that take an arbitrary name of arguments.</para>
</section>
<xi:include href="ref_c_data_flow.xml" xpointer="ansi.data-and-control.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
\ No newline at end of file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.environment">
<title>Environment</title>
<section xml:id="ansi.environment.dict">
<title>Dictionary</title>
<refentry xml:id="ansi.environment.disassemble">
<refnamediv>
<refname><function>disassemble</function></refname>
<refpurpose>Display the assembly code of a function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>disassemble</funcdef>
<paramdef><parameter>function-designator</parameter>*</paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term><replaceable>function-designator</replaceable></term>
<listitem><para>A symbol which is bound to a function in the global environment, or a lambda form
</para></listitem>
</varlistentry>
</variablelist>
</refsynopsisdiv>
<refsect1>
<title>Function</title>
<para>As specified in &ANSI; this function outputs the internal represention of a compiled function, or of a lambda form, as it would look after being compiled.</para>
<para>&ECL; only has a particular difference: it has two different compilers, one based on bytecodes and one based on the C language. The output will thus depend on the arguments and on which compiler is active at the moment in which this function is run.</para>
<itemizedlist>
<listitem><para>If the argument is a bytecompiled function, the output will be bytecodes.</para></listitem>
<listitem><para>If the argument is a lambda form, it will be processed by the active compiler and the appropriate output (bytecodes or C) will be shown.</para></listitem>
<listitem><para>If the argument is a C-compiled form, &ECL; will retrieve its original lambda form and process it with the currently active compiler.</para></listitem>
</itemizedlist>
</refsect1>
</refentry>
<refentry xml:id="ansi.environment.trace">
<refnamediv>
<refname><function>trace</function></refname>
<refpurpose>Follow execution of functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>trace</funcdef>
<paramdef><parameter>function-name</parameter>*</paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term><replaceable>function-name</replaceable></term>
<listitem><para>
<synopsis>{<replaceable>symbol</replaceable> | (<replaceable>symbol</replaceable> [<replaceable>option</replaceable> <replaceable>form</replaceable>]*)}</synopsis>
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>symbol</replaceable></term>
<listitem><para>A symbol which is bound to a function in the global
environment. Not evaluated.</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>option</replaceable></term>
<listitem><para>One of <symbol>:BREAK</symbol>,
<symbol>:BREAK-AFTER</symbol>, <symbol>:COND-BEFORE</symbol>,
<symbol>:COND-AFTER</symbol>, <symbol>:COND</symbol>,
<symbol>:PRINT</symbol>, <symbol>:PRINT-AFTER</symbol>,
<symbol>:STEP</symbol></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>form</replaceable></term>
<listitem><para>A lisp form evaluated in an special
environment.</para></listitem>
</varlistentry>
<varlistentry>
<term>returns</term>
<listitem><para>List of symbols with traced functions.</para></listitem>
</varlistentry>
</variablelist>
</refsynopsisdiv>
<refsect1>
<title>Macro</title>
<para>Causes one or more functions to be traced. Each
<replaceable>function-name</replaceable> can be a symbol which is bound to
a function, or a list containing that symbol plus additional options. If
the function bound to that symbol is called, information about the
argumetns and output of this function will be printed. Trace options will
modify the amount of information and when it is printed.</para>
<para>Not that if the function is called from another function compiled in
the same file, tracing might not be enabled. If this is the case, to
enable tracing, recompile the caller with a <literal>notinline</literal>
declaration for the called function.</para>
<para><function>trace</function> returns a name list of those functions
that were traced by the call to trace. If no
<replaceable>function-name</replaceable> is given, <literal>trace</literal>
simply returns a name list of all the currently traced functions.</para>
<para>Trace options cause the normal printout to be suppressed, or cause
extra information to be printed. Each option is a pair of an option keyword
and a value form. If an already traced function is traced again, any new
options replace the old options and a warning might be printed. The lisp
<replaceable>form</replaceable> accompanying the option is evaluated in an
environment where <replaceable>sys::arglist</replaceable> is contains the
list of arguments to the function.</para>
<para>The following options are defined:</para>
<variablelist>
<varlistentry>
<term><symbol>:cond</symbol></term>
<term><symbol>:cond-before</symbol></term>
<term><symbol>:cond-after</symbol></term>
<listitem>
<para>If <symbol>:cond-before</symbol> is specified, then
<function>trace</function> does nothing unless
<replaceable>form</replaceable> evaluates to true at the time of the
call. <symbol>:cond-after</symbol> is similar, but suppresses the
initial printout, and is tested when the function returns.
<symbol>:cond</symbol> tries both before and after.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><symbol>:step</symbol></term>
<listitem>
<para>If <replaceable>form</replaceable> evaluates to true, the stepper
is entered.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><symbol>:break</symbol></term>
<term><symbol>:break-after</symbol></term>
<listitem>
<para>If specified, and <replaceable>form</replaceable> evaluates to
true, then the debugger is invoked at the start of the function or at
the end of the function according to the respective option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><symbol>:print</symbol></term>
<term><symbol>:print-after</symbol></term>
<listitem>
<para>In addition to the usual printout, the result of evaluating
<replaceable>form</replaceable> is printed at the start of the function
or at the end of the function, depending on the option. Multiple print
options cause multiple values to be output, in the order in which they
were introduced.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</section>
<xi:include href="ref_c_environment.xml" xpointer="ansi.environment.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>
</book>
\ No newline at end of file
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter xml:id="ansi.evaluation-and-compilation">
<title>Evaluation and compilation</title>
<section xml:id="ansi.declarations">
<title>Declarations</title>
<section xml:id="ansi.declarations.optimize">
<title><function>OPTIMIZE</function></title>
<para>The <function>OPTIMIZE</function> declaration includes three concepts:
<function>DEBUG</function>, <function>SPEED</function>,
<function>SAFETY</function> and <function>SPACE</function>. Each of these
declarations can take one of the integer values 0, 1, 2 and 3. According to
these values, the implementation may decide how to compie or interpret a
given lisp form.</para>
<para>&ECL; currently does not use all these declarations, but some of them
definitely affect the speed and behavior of compiled functions. For
instance, the <function>DEBUG</function> declaration, as shown in <xref
linkend="table.optimize.debug"/>, if the value of debugging is zero, the
function will not appear in the debugger and, if redefined, some functions
might not see the redefinition.</para>
<table xml:id="table.optimize.debug">
<title>Behavior for different levels of DEBUG</title>
<tgroup cols="5">
<thead>
<row>
<entry>Behavior</entry>
<entry>0</entry>
<entry>1</entry>
<entry>2</entry>
<entry>3</entry>
</row>
</thead>
<tbody>
<row>