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

Close

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

  Switch to unified view

a/ecldev.xmlf b/ecldev.xmlf
1
<?xml version="1.0" encoding="utf-8"?>
1
<?xml version="1.0"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd">
2
<!DOCTYPE book [
2
<book lang="en">
3
<!ENTITY % eclent SYSTEM "ecl.ent">
4
%eclent;
5
]>
6
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
7
<chapter xml:id="Internals">
3
<chapter id="Internals">
8
 <title>Internals</title>
4
 <title>Internals</title>
9
 <para>&ECL; is an implementation of the Common-Lisp language that is based on a kernel
5
 <para>&ECL; is an implementation of the Common-Lisp language that is based on a kernel
10
  written in C plus a set of libraries written in Common-Lisp. The kernel includes a
6
  written in C plus a set of libraries written in Common-Lisp. The kernel includes a
11
  bytecodes compiler, an interpreter, and enough functions to create and
7
  bytecodes compiler, an interpreter, and enough functions to create and
12
  manipulate all lisp objects. The lisp libraries provide higher level constructs
8
  manipulate all lisp objects. The lisp libraries provide higher level constructs
...
...
29
  &ECL;.  With this facility, the user can arrange his or her C-language
25
  &ECL;.  With this facility, the user can arrange his or her C-language
30
  programs so that they can be invoked from &ECL;. In addition, the user can
26
  programs so that they can be invoked from &ECL;. In addition, the user can
31
  write Lisp function definitions in the C language to increase runtime
27
  write Lisp function definitions in the C language to increase runtime
32
  efficiency.</para>
28
  efficiency.</para>
33
29
34
 <section xml:id="Building-programs">
30
 <section id="Building-programs">
35
  <title>Building programs</title>
31
  <title>Building programs</title>
36
  <para>In this section we describe how you can use &ECL; to build programs and
32
  <para>In this section we describe how you can use &ECL; to build programs and
37
   loadable extensions that you can later on distribute to other people.</para>
33
   loadable extensions that you can later on distribute to other people.</para>
38
34
39
  <sect1 label="2.1" xml:id="What-can-ECL-do-">
35
  <sect1 label="2.1" id="What-can-ECL-do-">
40
   <title>What can &ECL; do?</title>
36
   <title>What can &ECL; do?</title>
41
   <para>Some day for some reasons you will be in the need to distribute code that
37
   <para>Some day for some reasons you will be in the need to distribute code that
42
    has been developed using &ECL;. In the following sections we will describe
38
    has been developed using &ECL;. In the following sections we will describe
43
    the means that &ECL; offers you to do so. Basically, these are the
39
    the means that &ECL; offers you to do so. Basically, these are the
44
    alternatives</para>
40
    alternatives</para>
...
...
104
    initialization function (<literal>mymain()</literal> in the example above). These means
100
    initialization function (<literal>mymain()</literal> in the example above). These means
105
    are explained in the following sections.</para>
101
    are explained in the following sections.</para>
106
   <!--  -->
102
   <!--  -->
107
  </sect1>
103
  </sect1>
108
104
109
  <sect1 label="2.2" xml:id="Compiling-files">
105
  <sect1 label="2.2" id="Compiling-files">
110
   <title>Compiling files</title>
106
   <title>Compiling files</title>
111
   <para>&ECL; supports two types of compilation. One is bytecodes compilation. This
107
   <para>&ECL; supports two types of compilation. One is bytecodes compilation. This
112
    process is performed on-the-fly, as you load source files with lisp code. This
108
    process is performed on-the-fly, as you load source files with lisp code. This
113
    leads to a series of bytes for each instruction, the so called
109
    leads to a series of bytes for each instruction, the so called
114
    "bytecodes". These bytecodes are interpreted in a virtual machine, which is
110
    "bytecodes". These bytecodes are interpreted in a virtual machine, which is
...
...
139
    </varlistentry>
135
    </varlistentry>
140
   </variablelist>
136
   </variablelist>
141
   <!--  -->
137
   <!--  -->
142
  </sect1>
138
  </sect1>
143
139
144
  <sect1 label="2.3" xml:id="Building-standalone-executables">
140
  <sect1 label="2.3" id="Building-standalone-executables">
145
   <title>Building standalone executables</title>
141
   <title>Building standalone executables</title>
146
   <para>To build an executable you need a working &ECL; image with the
142
   <para>To build an executable you need a working &ECL; image with the
147
    compiler. The function to build customized images is
143
    compiler. The function to build customized images is
148
    <replaceable>c::build-program</replaceable>. The description of this function is as
144
    <replaceable>c::build-program</replaceable>. The description of this function is as
149
    follows. Care should be taken that <replaceable>image-name</replaceable> differs from any
145
    follows. Care should be taken that <replaceable>image-name</replaceable> differs from any
150
    filename in <replaceable>lisp-files</replaceable>.</para>
146
    filename in <replaceable>lisp-files</replaceable>.</para>
151
   <blockquote>
147
   <blockquote>
152
    <screen><indexterm role="fn"><primary>c:build-program</primary></indexterm>&#151; Function: <function>c:build-program</function> <varname>{</varname><varname>image-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>ld-flags</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname><varname>}</varname></screen>
148
    <screen><indexterm role="fn"><primary>c:build-program</primary></indexterm>&mdash; Function: <function>c:build-program</function> <varname>{</varname><varname>image-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>ld-flags</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname><varname>}</varname></screen>
153
    <para>This function builds a lisp image up from the core lisp library, plus all
149
    <para>This function builds a lisp image up from the core lisp library, plus all
154
     components listed in <replaceable>lisp-files</replaceable>.  Each component is either:</para>
150
     components listed in <replaceable>lisp-files</replaceable>.  Each component is either:</para>
155
    <itemizedlist mark="bullet">
151
    <itemizedlist mark="bullet">
156
     <listitem>
152
     <listitem>
157
      <para>A symbol: Names a statically linked library built from lisp code.</para>
153
      <para>A symbol: Names a statically linked library built from lisp code.</para>
...
...
174
     will be interpreted at run time.</para>
170
     will be interpreted at run time.</para>
175
   </blockquote>
171
   </blockquote>
176
   <!--  -->
172
   <!--  -->
177
  </sect1>
173
  </sect1>
178
174
179
  <sect1 label="2.4" xml:id="Building-libraries">
175
  <sect1 label="2.4" id="Building-libraries">
180
   <title>Building libraries</title>
176
   <title>Building libraries</title>
181
   <para>To build a library you proceed more or less the same way as with standalone
177
   <para>To build a library you proceed more or less the same way as with standalone
182
    executables. There are two different functions depending on whether you need
178
    executables. There are two different functions depending on whether you need
183
    to build static or shared libraries.</para>
179
    to build static or shared libraries.</para>
184
   <blockquote>
180
   <blockquote>
185
    <screen><indexterm role="fn"><primary>c:build-static-library</primary></indexterm>&#151; Function: <function>c:build-static-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>init-name</varname><varname>}</varname></screen>
181
    <screen><indexterm role="fn"><primary>c:build-static-library</primary></indexterm>&mdash; Function: <function>c:build-static-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>init-name</varname><varname>}</varname></screen>
186
    <screen><indexterm role="fn"><primary>c:build-shared-library</primary></indexterm>&#151; Function: <function>c:build-shared-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>ld-flags</varname> <varname>init-name</varname><varname>}</varname></screen>
182
    <screen><indexterm role="fn"><primary>c:build-shared-library</primary></indexterm>&mdash; Function: <function>c:build-shared-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>ld-flags</varname> <varname>init-name</varname><varname>}</varname></screen>
187
    <para>This function builds a library file up from the object files listed in
183
    <para>This function builds a library file up from the object files listed in
188
     <replaceable>lisp-files</replaceable>. Each of the arguments to <replaceable>lisp-file</replaceable> must name a single
184
     <replaceable>lisp-files</replaceable>. Each of the arguments to <replaceable>lisp-file</replaceable> must name a single
189
     object file produced with <literal>compile-file</literal>.</para>
185
     object file produced with <literal>compile-file</literal>.</para>
190
    <para><replaceable>library-name</replaceable> is the physical pathname corresponding to the library. The
186
    <para><replaceable>library-name</replaceable> is the physical pathname corresponding to the library. The
191
     value of <replaceable>library-name</replaceable> must follow some system-specific conventions.  To
187
     value of <replaceable>library-name</replaceable> must follow some system-specific conventions.  To
...
...
201
     linked to a C application.</para>
197
     linked to a C application.</para>
202
   </blockquote>
198
   </blockquote>
203
   <!--  -->
199
   <!--  -->
204
  </sect1>
200
  </sect1>
205
201
206
  <sect1 label="2.5" xml:id="File-names">
202
  <sect1 label="2.5" id="File-names">
207
   <title>File names</title>
203
   <title>File names</title>
208
   <blockquote>
204
   <blockquote>
209
    <screen><indexterm role="fn"><primary>compile-file-pathname</primary></indexterm>&#151; Function: <function>compile-file-pathname</function> <varname>{</varname><varname>filename-base</varname> <varname>&amp;key</varname> <varname>output-file</varname> <varname>type</varname><varname>}</varname></screen>
205
    <screen><indexterm role="fn"><primary>compile-file-pathname</primary></indexterm>&mdash; Function: <function>compile-file-pathname</function> <varname>{</varname><varname>filename-base</varname> <varname>&amp;key</varname> <varname>output-file</varname> <varname>type</varname><varname>}</varname></screen>
210
    <para>When compiling lisp files, creating libraries, etc, a number of files are
206
    <para>When compiling lisp files, creating libraries, etc, a number of files are
211
     produced which are of interest for the user or programmer. However, the name
207
     produced which are of interest for the user or programmer. However, the name
212
     of these files will change from system to system. The purpose of the function
208
     of these files will change from system to system. The purpose of the function
213
     <literal>compile-file-pathname</literal> is to query the compiler about the name of the
209
     <literal>compile-file-pathname</literal> is to query the compiler about the name of the
214
     different files that it can produce. Possible values of the <replaceable>type</replaceable>
210
     different files that it can produce. Possible values of the <replaceable>type</replaceable>
...
...
261
     </screen></para>
257
     </screen></para>
262
   </blockquote>
258
   </blockquote>
263
   <!--  -->
259
   <!--  -->
264
  </sect1>
260
  </sect1>
265
261
266
  <sect1 label="2.6" xml:id="Compiler-examples">
262
  <sect1 label="2.6" id="Compiler-examples">
267
   <title>Compiler examples</title>
263
   <title>Compiler examples</title>
268
   <sect2 label="2.6.1">
264
   <sect2 label="2.6.1">
269
    <title>The <filename>hello.lisp</filename> file</title>
265
    <title>The <filename>hello.lisp</filename> file</title>
270
    <para>In the following examples we will use the same lisp program. You have to
266
    <para>In the following examples we will use the same lisp program. You have to
271
     create a file called <filename>hello.lisp</filename> which contains the following lines</para>
267
     create a file called <filename>hello.lisp</filename> which contains the following lines</para>
...
...
311
      ;;; Loading #P"/usr/lib/ecl/sysfun.lsp"
307
      ;;; Loading #P"/usr/lib/ecl/sysfun.lsp"
312
      ;;; Compiling hello.lisp.
308
      ;;; Compiling hello.lisp.
313
      ;;; End of Pass 1.
309
      ;;; End of Pass 1.
314
      ;;; Calling the C compiler...
310
      ;;; Calling the C compiler...
315
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "hello.c" -o "hello.o"
311
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "hello.c" -o "hello.o"
316
      ;;; Invoking external command: gcc -o "hello.fas" -L"/usr/lib/ecl/" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
312
      ;;; Invoking external command: gcc -o "hello.fas" -L"/usr/lib/ecl/" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
317
      ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
313
      ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
318
      ;;; Finished compiling hello.lisp.
314
      ;;; Finished compiling hello.lisp.
319
      #P"hello.fas"
315
      #P"hello.fas"
320
      Top level.
316
      Top level.
321
      &gt; <lineannotation>(load "hello")</lineannotation>
317
      &gt; <lineannotation>(load "hello")</lineannotation>
...
...
346
     </screen></para>
342
     </screen></para>
347
    <para role="continues">The final step is to build the executable using the <literal>c:build-program</literal>
343
    <para role="continues">The final step is to build the executable using the <literal>c:build-program</literal>
348
     instruction.<screen>
344
     instruction.<screen>
349
      &gt; <lineannotation>(c:build-program "myecl" :lisp-files '("hello.o"))</lineannotation>
345
      &gt; <lineannotation>(c:build-program "myecl" :lisp-files '("hello.o"))</lineannotation>
350
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
346
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
351
      ;;; Invoking external command: gcc -o "myecl" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/  -lecl -lgmp -lgc -ldl -lm
347
      ;;; Invoking external command: gcc -o "myecl" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/  -lecl -lgmp -lgc -ldl -lm
352
      #P"myecl"
348
      #P"myecl"
353
      Top level.
349
      Top level.
354
     </screen>Now you can execute this program from your favorite shell.</para>
350
     </screen>Now you can execute this program from your favorite shell.</para>
355
    <para role="continues"><screen>
351
    <para role="continues"><screen>
356
      % <lineannotation>./myecl</lineannotation>
352
      % <lineannotation>./myecl</lineannotation>
...
...
382
     </screen></para>
378
     </screen></para>
383
    <para role="continues">The final step is to build the library using the <literal>c:build-fasl</literal>
379
    <para role="continues">The final step is to build the library using the <literal>c:build-fasl</literal>
384
     instruction.<screen>
380
     instruction.<screen>
385
      &gt; (c:build-fasl "myecl" :lisp-files '("hello.o"))
381
      &gt; (c:build-fasl "myecl" :lisp-files '("hello.o"))
386
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
382
      ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
387
      ;;; Invoking external command: gcc -o "libmyecl.so" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
383
      ;;; Invoking external command: gcc -o "libmyecl.so" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
388
      #P"libmyecl.so"
384
      #P"libmyecl.so"
389
     </screen>Now you can load this extension from any &ECL; image, even those you produce
385
     </screen>Now you can load this extension from any &ECL; image, even those you produce
390
     with <literal>c:build-program</literal>.</para>
386
     with <literal>c:build-program</literal>.</para>
391
    <para role="continues"><screen>
387
    <para role="continues"><screen>
392
      &lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; THIS EXAMPLE IS WRONG?! &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
388
      &lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; THIS EXAMPLE IS WRONG?! &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
...
...
398
    <!--  -->
394
    <!--  -->
399
   </sect2>
395
   </sect2>
400
  </sect1>
396
  </sect1>
401
 </section>
397
 </section>
402
398
403
 <section xml:id="Lisp-objects">
399
 <section id="Lisp-objects">
404
  <title>Manipulating Lisp objects</title>
400
  <title>Manipulating Lisp objects</title>
405
  <para>If you want to extend, fix or simply customize &ECL; for your own needs,
401
  <para>If you want to extend, fix or simply customize &ECL; for your own needs,
406
   you should understand how the implementation works.</para>
402
   you should understand how the implementation works.</para>
407
403
408
  <sect1 label="3.1" xml:id="Objects-representation">
404
  <sect1 label="3.1" id="Objects-representation">
409
   <title>Objects representation</title>
405
   <title>Objects representation</title>
410
   <para>In &ECL; a lisp object is represented by a type called <literal>cl_object</literal>. This
406
   <para>In &ECL; a lisp object is represented by a type called <literal>cl_object</literal>. This
411
    type is a word which is long enough to host both an integer and a pointer. The
407
    type is a word which is long enough to host both an integer and a pointer. The
412
    least significant bits of this word, also called the tag bits, determine
408
    least significant bits of this word, also called the tag bits, determine
413
    whether it is a pointer to a C structure representing a complex object, or
409
    whether it is a pointer to a C structure representing a complex object, or
...
...
449
    |--------------------| 
445
    |--------------------| 
450
    ]]></screen>
446
    ]]></screen>
451
   <para>There is one important function which tells the type of an object, plus several
447
   <para>There is one important function which tells the type of an object, plus several
452
    macros which group several tests.</para>
448
    macros which group several tests.</para>
453
   <blockquote>
449
   <blockquote>
454
    <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&#151; C type: <structname>cl_object</structname></screen>
450
    <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&mdash; C type: <structname>cl_object</structname></screen>
455
    <para>This is the type of a lisp object. For your C/C++ program, a <literal>cl_object</literal>
451
    <para>This is the type of a lisp object. For your C/C++ program, a <literal>cl_object</literal>
456
     can be either a fixnum, a character, or a pointer to a union of structures (See
452
     can be either a fixnum, a character, or a pointer to a union of structures (See
457
     the header <filename>object.h</filename>). The actual interpretation of that object can be
453
     the header <filename>object.h</filename>). The actual interpretation of that object can be
458
     guessed with the macro <literal>ecl_t_of</literal>.</para>
454
     guessed with the macro <literal>type_of</literal>.</para>
459
    <para>For example, if <replaceable>x</replaceable> is of type <literal>cl_object</literal>, and it is of type fixnum,
455
    <para>For example, if <replaceable>x</replaceable> is of type <literal>cl_object</literal>, and it is of type fixnum,
460
     we may retrieve its value</para>
456
     we may retrieve its value</para>
461
    <screen>
457
    <screen>
462
     if (ecl_t_of(x) == t_fixnum)
458
     if (type_of(x) == t_fixnum)
463
     printf("Integer value: %d\n", fix(x));
459
     printf("Integer value: %d\n", fix(x));
464
    </screen>
460
    </screen>
465
    <para role="continues">If <replaceable>x</replaceable> is of type <literal>cl_object</literal> and it does not contain an immediate
461
    <para role="continues">If <replaceable>x</replaceable> is of type <literal>cl_object</literal> and it does not contain an immediate
466
     datatype, you may inspect the cell associated to the lisp object using <replaceable>x</replaceable>
462
     datatype, you may inspect the cell associated to the lisp object using <replaceable>x</replaceable>
467
     as a pointer. For example,</para>
463
     as a pointer. For example,</para>
468
    <screen>
464
    <screen>
469
     if (ecl_t_of(x) == t_cons)
465
     if (type_of(x) == t_cons)
470
     printf("CAR = %x, CDR = %x\n", x-&gt;cons.car, x-&gt;cons.cdr);
466
     printf("CAR = %x, CDR = %x\n", x-&gt;cons.car, x-&gt;cons.cdr);
471
     else if (ecl_t_of(x) == t_string)
467
     else if (type_of(x) == t_string)
472
     printf("String: %s\n", x-&gt;string.self);
468
     printf("String: %s\n", x-&gt;string.self);
473
    </screen>
469
    </screen>
474
    <para role="continues">You should see the following sections and the header <filename>object.h</filename> to learn
470
    <para role="continues">You should see the following sections and the header <filename>object.h</filename> to learn
475
     how to use the different fields of a <literal>cl_object</literal> pointer.</para>
471
     how to use the different fields of a <literal>cl_object</literal> pointer.</para>
476
   </blockquote>
472
   </blockquote>
477
   <blockquote>
473
   <blockquote>
478
    <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&#151; C type: <structname>cl_type</structname></screen>
474
    <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&mdash; C type: <structname>cl_type</structname></screen>
479
    <para>Enumeration type which distinguishes the different types of lisp objects.  The
475
    <para>Enumeration type which distinguishes the different types of lisp objects.  The
480
     most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
476
     most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
481
     t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
477
     t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
482
     t_array, t_vector, t_string, t_bitvector, t_stream, t_random, t_readtable,
478
     t_array, t_vector, t_string, t_bitvector, t_stream, t_random, t_readtable,
483
     t_pathname, t_bytecodes, t_cfun, t_cclosure, t_gfun, t_instance, t_foreign and
479
     t_pathname, t_bytecodes, t_cfun, t_cclosure, t_gfun, t_instance, t_foreign and
484
     t_thread.</para>
480
     t_thread.</para>
485
   </blockquote>
481
   </blockquote>
486
   <blockquote>
482
   <blockquote>
487
    <screen><indexterm role="fn"><primary>ecl_t_of</primary></indexterm>&#151; Function: <returnvalue>cl_type</returnvalue> <function>ecl_t_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
483
    <screen><indexterm role="fn"><primary>type_of</primary></indexterm>&mdash; Function: <returnvalue>cl_type</returnvalue> <function>type_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
488
    <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>ecl_t_of(<replaceable>O</replaceable>)</literal> returns an integer
484
    <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>type_of(<replaceable>O</replaceable>)</literal> returns an integer
489
     denoting the type that lisp object. That integer is one of the values of the
485
     denoting the type that lisp object. That integer is one of the values of the
490
     enumeration type <literal>cl_type</literal>.</para>
486
     enumeration type <literal>cl_type</literal>.</para>
491
   </blockquote>
487
   </blockquote>
492
   <blockquote>
488
   <blockquote>
493
    <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
489
    <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
494
    <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
490
    <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
495
    <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
491
    <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
496
    <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
492
    <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
497
    <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
493
    <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
498
    <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
494
    <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
499
    <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
495
    <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
500
    <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
496
    <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
501
    <para>Different macros that check whether <replaceable>o</replaceable> belongs to the specified type.
497
    <para>Different macros that check whether <replaceable>o</replaceable> belongs to the specified type.
502
     These checks have been optimized, and are preferred over several calls to
498
     These checks have been optimized, and are preferred over several calls to
503
     <literal>ecl_t_of</literal>.</para>
499
     <literal>type_of</literal>.</para>
504
   </blockquote>
505
   <blockquote>
500
   </blockquote>
501
   <blockquote>
506
    <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
502
    <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
507
    <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
503
    <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
508
   </blockquote>
504
   </blockquote>
509
   <!--  -->
505
   <!--  -->
510
  </sect1>
506
  </sect1>
511
507
512
  <sect1 label="3.2" xml:id="Constructing-objects">
508
  <sect1 label="3.2" id="Constructing-objects">
513
   <title>Constructing objects</title>
509
   <title>Constructing objects</title>
514
   <para>On each of the following sections we will document the standard interface for
510
   <para>On each of the following sections we will document the standard interface for
515
    building objects of different types. For some objects, though, it is too
511
    building objects of different types. For some objects, though, it is too
516
    difficult to make a C interface that resembles all of the functionality in the
512
    difficult to make a C interface that resembles all of the functionality in the
517
    lisp environment. In those cases you need to</para>
513
    lisp environment. In those cases you need to</para>
...
...
524
    </listitem>
520
    </listitem>
525
   </orderedlist>
521
   </orderedlist>
526
   <para role="continues">The first way makes use of a C or Lisp string to construct an object. The two
522
   <para role="continues">The first way makes use of a C or Lisp string to construct an object. The two
527
    functions you need to know are the following ones.</para>
523
    functions you need to know are the following ones.</para>
528
   <blockquote>
524
   <blockquote>
529
    <screen><indexterm role="fn"><primary>c_string_to_object</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>c_string_to_object</function> (<type>const</type> <varname>char</varname> <type>*</type><varname>s</varname>)</screen>
525
    <screen><indexterm role="fn"><primary>c_string_to_object</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>c_string_to_object</function> (<type>const</type> <varname>char</varname> <type>*</type><varname>s</varname>)</screen>
530
    <screen><indexterm role="fn"><primary>string_to_object</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>string_to_object</function> (<type>cl_object</type> <varname>o</varname>)</screen>
526
    <screen><indexterm role="fn"><primary>string_to_object</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>string_to_object</function> (<type>cl_object</type> <varname>o</varname>)</screen>
531
    <para><literal>c_string_to_object</literal> builds a lisp object from a C string which contains a
527
    <para><literal>c_string_to_object</literal> builds a lisp object from a C string which contains a
532
     suitable representation of a lisp object. <literal>string_to_object</literal> performs the
528
     suitable representation of a lisp object. <literal>string_to_object</literal> performs the
533
     same task, but uses a lisp string, and therefore it is less useful. Two
529
     same task, but uses a lisp string, and therefore it is less useful. Two
534
     examples of their use</para>
530
     examples of their use</para>
535
    <screen>
531
    <screen>
...
...
542
    </screen>
538
    </screen>
543
   </blockquote>
539
   </blockquote>
544
   <!--  -->
540
   <!--  -->
545
  </sect1>
541
  </sect1>
546
542
547
  <sect1 label="3.3" xml:id="Integers">
543
  <sect1 label="3.3" id="Integers">
548
   <title>Integers</title>
544
   <title>Integers</title>
549
   <para>Common-Lisp distinguishes two types of integer types: bignums and fixnums. A
545
   <para>Common-Lisp distinguishes two types of integer types: bignums and fixnums. A
550
    fixnum is a small integer, which ideally occupies only a word of memory and
546
    fixnum is a small integer, which ideally occupies only a word of memory and
551
    which is between the values <replaceable>MOST-NEGATIVE-FIXNUM</replaceable> and
547
    which is between the values <replaceable>MOST-NEGATIVE-FIXNUM</replaceable> and
552
    <replaceable>MOST-POSITIVE-FIXNUM</replaceable>. A bignum is any integer which is not a fixnum and
548
    <replaceable>MOST-POSITIVE-FIXNUM</replaceable>. A bignum is any integer which is not a fixnum and
...
...
557
    the <filename>ecl.h</filename> header to make sure that your C extensions are portable.
553
    the <filename>ecl.h</filename> header to make sure that your C extensions are portable.
558
    All other integers are stored as bignums, they are not immediate objects, they
554
    All other integers are stored as bignums, they are not immediate objects, they
559
    take up a variable amount of memory and the GNU Multiprecision Library is
555
    take up a variable amount of memory and the GNU Multiprecision Library is
560
    required to create, manipulate and calculate with them.</para>
556
    required to create, manipulate and calculate with them.</para>
561
   <blockquote>
557
   <blockquote>
562
    <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&#151; C type: <structname>cl_fixnum</structname></screen>
558
    <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&mdash; C type: <structname>cl_fixnum</structname></screen>
563
    <para>This is a C signed integer type capable of holding a whole fixnum without any
559
    <para>This is a C signed integer type capable of holding a whole fixnum without any
564
     loss of precision. The opposite is not true, and you may create a
560
     loss of precision. The opposite is not true, and you may create a
565
     <literal>cl_fixnum</literal> which exceeds the limits of a fixnum and should be stored as a
561
     <literal>cl_fixnum</literal> which exceeds the limits of a fixnum and should be stored as a
566
     bignum.</para>
562
     bignum.</para>
567
   </blockquote>
563
   </blockquote>
568
   <blockquote>
564
   <blockquote>
569
    <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&#151; C type: <structname>cl_index</structname></screen>
565
    <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&mdash; C type: <structname>cl_index</structname></screen>
570
    <para>This is a C unsigned integer type capable of holding a nonnegative fixnum without
566
    <para>This is a C unsigned integer type capable of holding a nonnegative fixnum without
571
     loss of precision. Typically, a <literal>cl_index</literal> is used as an index into an array,
567
     loss of precision. Typically, a <literal>cl_index</literal> is used as an index into an array,
572
     or into a proper list, etc.</para>
568
     or into a proper list, etc.</para>
573
   </blockquote>
569
   </blockquote>
574
   <blockquote>
570
   <blockquote>
575
    <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
571
    <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
576
    <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
572
    <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
577
    <para>These constants mark the limits of a fixnum.</para>
573
    <para>These constants mark the limits of a fixnum.</para>
578
   </blockquote>
574
   </blockquote>
579
   <blockquote>
575
   <blockquote>
580
    <screen><indexterm role="fn"><primary>FIXNUM_MINUSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_MINUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
576
    <screen><indexterm role="fn"><primary>FIXNUM_MINUSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_MINUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
581
    <screen><indexterm role="fn"><primary>FIXNUM_PLUSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_PLUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
577
    <screen><indexterm role="fn"><primary>FIXNUM_PLUSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_PLUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
582
    <para>These functions perform the checks (<replaceable>o</replaceable> &lt; 0) and (0 &lt;= <replaceable>o</replaceable>),
578
    <para>These functions perform the checks (<replaceable>o</replaceable> &lt; 0) and (0 &lt;= <replaceable>o</replaceable>),
583
     respectively.</para>
579
     respectively.</para>
584
   </blockquote>
580
   </blockquote>
585
   <blockquote>
581
   <blockquote>
586
    <screen><indexterm role="fn"><primary>MAKE_FIXNUM</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>MAKE_FIXNUM</function> (<type>cl_fixnum</type> <varname>n</varname>)</screen>
582
    <screen><indexterm role="fn"><primary>MAKE_FIXNUM</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>MAKE_FIXNUM</function> (<type>cl_fixnum</type> <varname>n</varname>)</screen>
587
    <screen><indexterm role="fn"><primary>fix</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>fix</function> (<type>cl_object</type> <varname>o</varname>)</screen>
583
    <screen><indexterm role="fn"><primary>fix</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>fix</function> (<type>cl_object</type> <varname>o</varname>)</screen>
588
    <para><literal>MAKE_FIXNUM</literal> and <literal>fix</literal> convert from an integer to a lisp object
584
    <para><literal>MAKE_FIXNUM</literal> and <literal>fix</literal> convert from an integer to a lisp object
589
     of fixnum type and vice versa. These functions no not check their arguments.</para>
585
     of fixnum type and vice versa. These functions no not check their arguments.</para>
590
   </blockquote>
586
   </blockquote>
591
   <blockquote>
587
   <blockquote>
592
    <screen><indexterm role="fn"><primary>fixint</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>fixint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
588
    <screen><indexterm role="fn"><primary>fixint</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>fixint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
593
    <para>Converts a lisp fixnum to a C integer of the appropriate size. Signals an error
589
    <para>Converts a lisp fixnum to a C integer of the appropriate size. Signals an error
594
     if <replaceable>o</replaceable> is not of fixnum type.</para>
590
     if <replaceable>o</replaceable> is not of fixnum type.</para>
595
   </blockquote>
591
   </blockquote>
596
   <blockquote>
592
   <blockquote>
597
    <screen><indexterm role="fn"><primary>fixnnint</primary></indexterm>&#151; Function: <returnvalue>cl_index</returnvalue> <function>fixnnint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
593
    <screen><indexterm role="fn"><primary>fixnnint</primary></indexterm>&mdash; Function: <returnvalue>cl_index</returnvalue> <function>fixnnint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
598
    <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
594
    <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
599
   </blockquote>
595
   </blockquote>
600
   <!--  -->
596
   <!--  -->
601
  </sect1>
597
  </sect1>
602
598
603
  <sect1 label="3.4" xml:id="Characters">
599
  <sect1 label="3.4" id="Characters">
604
   <title>Characters</title>
600
   <title>Characters</title>
605
   <para>&ECL; has only one type of characters, which fits in the C type <literal>char</literal>.
601
   <para>&ECL; has only one type of characters, which fits in the C type <literal>char</literal>.
606
    The following constants and functions operate on characters.</para>
602
    The following constants and functions operate on characters.</para>
607
   <blockquote>
603
   <blockquote>
608
    <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&#151; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
604
    <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&mdash; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
609
    <para>Each character is assigned an integer code which ranges from 0 to
605
    <para>Each character is assigned an integer code which ranges from 0 to
610
     (<replaceable>CHAR_CODE_LIMIT</replaceable>-1).</para>
606
     (<replaceable>CHAR_CODE_LIMIT</replaceable>-1).</para>
611
   </blockquote>
607
   </blockquote>
612
   <blockquote>
608
   <blockquote>
613
    <screen><indexterm role="fn"><primary>CHAR_CODE</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>CHAR_CODE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
609
    <screen><indexterm role="fn"><primary>CHAR_CODE</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>CHAR_CODE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
614
    <screen><indexterm role="fn"><primary>char_code</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>char_code</function> (<type>cl_object</type> <varname>o</varname>)</screen>
610
    <screen><indexterm role="fn"><primary>char_code</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>char_code</function> (<type>cl_object</type> <varname>o</varname>)</screen>
615
    <para>Returns the integer code associated to a lisp character. Only <literal>char_code</literal>
611
    <para>Returns the integer code associated to a lisp character. Only <literal>char_code</literal>
616
     checks its arguments.</para>
612
     checks its arguments.</para>
617
   </blockquote>
613
   </blockquote>
618
   <blockquote>
614
   <blockquote>
619
    <screen><indexterm role="fn"><primary>CODE_CHAR</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>CODE_CHAR</function> (<type>cl_fixnum</type> <varname>o</varname>)</screen>
615
    <screen><indexterm role="fn"><primary>CODE_CHAR</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>CODE_CHAR</function> (<type>cl_fixnum</type> <varname>o</varname>)</screen>
620
    <para>Returns the lisp character associated to an integer code. It does not check
616
    <para>Returns the lisp character associated to an integer code. It does not check
621
     its arguments.</para>
617
     its arguments.</para>
622
   </blockquote>
618
   </blockquote>
623
   <blockquote>
619
   <blockquote>
624
    <screen><indexterm role="fn"><primary>coerce_to_character</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>coerce_to_character</function> (<type>cl_object</type> <varname>o</varname>)</screen>
620
    <screen><indexterm role="fn"><primary>coerce_to_character</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>coerce_to_character</function> (<type>cl_object</type> <varname>o</varname>)</screen>
625
    <para>Coerces a lisp object to type character. Valid arguments are a character,
621
    <para>Coerces a lisp object to type character. Valid arguments are a character,
626
     or a string designator of length 1. In all other cases an error is signaled.</para>
622
     or a string designator of length 1. In all other cases an error is signaled.</para>
627
   </blockquote>
623
   </blockquote>
628
   <blockquote>
624
   <blockquote>
629
    <screen><indexterm role="fn"><primary>char_eq</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>char_eq</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
625
    <screen><indexterm role="fn"><primary>char_eq</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>char_eq</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
630
    <screen><indexterm role="fn"><primary>char_equal</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>char_equal</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
626
    <screen><indexterm role="fn"><primary>char_equal</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>char_equal</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
631
    <para>Compare two characters for equality. <literal>char_eq</literal> take case into account and
627
    <para>Compare two characters for equality. <literal>char_eq</literal> take case into account and
632
     <literal>char_equal</literal> ignores it.</para>
628
     <literal>char_equal</literal> ignores it.</para>
633
   </blockquote>
629
   </blockquote>
634
   <blockquote>
630
   <blockquote>
635
    <screen><indexterm role="fn"><primary>char_cmp</primary></indexterm>&#151; Function: <returnvalue>int</returnvalue> <function>char_cmp</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
631
    <screen><indexterm role="fn"><primary>char_cmp</primary></indexterm>&mdash; Function: <returnvalue>int</returnvalue> <function>char_cmp</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
636
    <screen><indexterm role="fn"><primary>char_compare</primary></indexterm>&#151; Function: <returnvalue>int</returnvalue> <function>char_compare</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
632
    <screen><indexterm role="fn"><primary>char_compare</primary></indexterm>&mdash; Function: <returnvalue>int</returnvalue> <function>char_compare</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
637
    <para>Compare the relative order of two characters. <literal>char_cmp</literal> takes care of
633
    <para>Compare the relative order of two characters. <literal>char_cmp</literal> takes care of
638
     case and <literal>char_compare</literal> converts all characters to uppercase before
634
     case and <literal>char_compare</literal> converts all characters to uppercase before
639
     comparing them.</para>
635
     comparing them.</para>
640
   </blockquote>
636
   </blockquote>
641
   <!--  -->
637
   <!--  -->
642
  </sect1>
638
  </sect1>
643
639
644
  <sect1 label="3.5" xml:id="Arrays">
640
  <sect1 label="3.5" id="Arrays">
645
   <title>Arrays</title>
641
   <title>Arrays</title>
646
   <para>An array is an aggregate of data of a common type, which can be accessed with
642
   <para>An array is an aggregate of data of a common type, which can be accessed with
647
    one or more nonnegative indices. &ECL; stores arrays as a C structure with a
643
    one or more nonnegative indices. &ECL; stores arrays as a C structure with a
648
    pointer to the region of memory which contains the actual data. The cell
644
    pointer to the region of memory which contains the actual data. The cell
649
    of an array datatype varies depending on whether it is a vector, a bytevector,
645
    of an array datatype varies depending on whether it is a vector, a bytevector,
...
...
766
      <para><literal>aet_df</literal></para>
762
      <para><literal>aet_df</literal></para>
767
     </listitem>
763
     </listitem>
768
    </varlistentry>
764
    </varlistentry>
769
   </variablelist>
765
   </variablelist>
770
   <blockquote>
766
   <blockquote>
771
    <screen><indexterm role="fn"><primary>array_elttype</primary></indexterm>&#151; Function: <returnvalue>cl_elttype</returnvalue> <function>array_elttype</function> (<type>cl_object</type> <varname>o</varname>)</screen>
767
    <screen><indexterm role="fn"><primary>array_elttype</primary></indexterm>&mdash; Function: <returnvalue>cl_elttype</returnvalue> <function>array_elttype</function> (<type>cl_object</type> <varname>o</varname>)</screen>
772
    <para>Returns the element type of the array <replaceable>o</replaceable>, which can be a string, a
768
    <para>Returns the element type of the array <replaceable>o</replaceable>, which can be a string, a
773
     bitvector, vector, or a multidimensional array. For example, the code
769
     bitvector, vector, or a multidimensional array. For example, the code
774
     <literal>array_elttype(c_string_to_object("\"AAA\""))</literal> returns <literal>aet_ch</literal>,
770
     <literal>array_elttype(c_string_to_object("\"AAA\""))</literal> returns <literal>aet_ch</literal>,
775
     while the <literal>array_elttype(c_string_to_object("#(A B C)"))</literal> returns
771
     while the <literal>array_elttype(c_string_to_object("#(A B C)"))</literal> returns
776
     <literal>aet_object</literal>.</para>
772
     <literal>aet_object</literal>.</para>
777
   </blockquote>
773
   </blockquote>
778
   <blockquote>
774
   <blockquote>
779
    <screen><indexterm role="fn"><primary>aref</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aref</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
775
    <screen><indexterm role="fn"><primary>aref</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aref</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
780
    <screen><indexterm role="fn"><primary>aset</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aset</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
776
    <screen><indexterm role="fn"><primary>aset</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aset</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
781
    <para>These functions are used to retrieve and set the elements of an array. The
777
    <para>These functions are used to retrieve and set the elements of an array. The
782
     elements are accessed with one index, <replaceable>index</replaceable>, as in the lisp function
778
     elements are accessed with one index, <replaceable>index</replaceable>, as in the lisp function
783
     <literal>ROW-MAJOR-AREF</literal>. For example</para>
779
     <literal>ROW-MAJOR-AREF</literal>. For example</para>
784
    <screen>
780
    <screen>
785
     cl_object array = c_string_to_object("#2A((1 2) (3 4))");
781
     cl_object array = c_string_to_object("#2A((1 2) (3 4))");
...
...
788
     aset(array, 3, MAKE_FIXNUM(5));
784
     aset(array, 3, MAKE_FIXNUM(5));
789
     cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
785
     cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
790
    </screen>
786
    </screen>
791
   </blockquote>
787
   </blockquote>
792
   <blockquote>
788
   <blockquote>
793
    <screen><indexterm role="fn"><primary>aref1</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aref1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
789
    <screen><indexterm role="fn"><primary>aref1</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aref1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
794
    <screen><indexterm role="fn"><primary>aset1</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aset1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
790
    <screen><indexterm role="fn"><primary>aset1</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aset1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
795
    <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
791
    <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
796
     vectors.</para>
792
     vectors.</para>
797
    <screen>
793
    <screen>
798
     cl_object array = c_string_to_object("#(1 2 3 4)");
794
     cl_object array = c_string_to_object("#(1 2 3 4)");
799
     cl_object x = aref1(array, 3);
795
     cl_object x = aref1(array, 3);
...
...
803
    </screen>
799
    </screen>
804
   </blockquote>
800
   </blockquote>
805
   <!--  -->
801
   <!--  -->
806
  </sect1>
802
  </sect1>
807
803
808
  <sect1 label="3.6" xml:id="Strings">
804
  <sect1 label="3.6" id="Strings">
809
   <title>Strings</title>
805
   <title>Strings</title>
810
   <para>A string, both in Common-Lisp and in &ECL; is nothing but a vector of
806
   <para>A string, both in Common-Lisp and in &ECL; is nothing but a vector of
811
    characters. Therefore, almost everything mentioned in the section of arrays
807
    characters. Therefore, almost everything mentioned in the section of arrays
812
    remains valid here. The only important difference is that &ECL; stores
808
    remains valid here. The only important difference is that &ECL; stores
813
    strings as a lisp object with a pointer to a zero terminated C string. Thus, if
809
    strings as a lisp object with a pointer to a zero terminated C string. Thus, if
...
...
840
      <para>True if <literal>x-&gt;string.fillp</literal> can be smaller than <literal>x-&gt;string.dim</literal>.</para>
836
      <para>True if <literal>x-&gt;string.fillp</literal> can be smaller than <literal>x-&gt;string.dim</literal>.</para>
841
     </listitem>
837
     </listitem>
842
    </varlistentry>
838
    </varlistentry>
843
   </variablelist>
839
   </variablelist>
844
   <blockquote>
840
   <blockquote>
845
    <screen><indexterm role="fn"><primary>make_simple_string</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>make_simple_string</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
841
    <screen><indexterm role="fn"><primary>make_simple_string</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>make_simple_string</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
846
    <screen><indexterm role="fn"><primary>make_string_copy</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>make_string_copy</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
842
    <screen><indexterm role="fn"><primary>make_string_copy</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>make_string_copy</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
847
    <para>Both routines build a lisp string from a C string. <literal>make_string_copy</literal>
843
    <para>Both routines build a lisp string from a C string. <literal>make_string_copy</literal>
848
     allocates new space and copies the content of the string to
844
     allocates new space and copies the content of the string to
849
     it. <literal>make_simple_string</literal> simply uses the memory pointed by <replaceable>s</replaceable>, which
845
     it. <literal>make_simple_string</literal> simply uses the memory pointed by <replaceable>s</replaceable>, which
850
     should not be deallocated. Both routines use <literal>strlen</literal> to calculate the
846
     should not be deallocated. Both routines use <literal>strlen</literal> to calculate the
851
     length of the string.</para>
847
     length of the string.</para>
852
   </blockquote>
848
   </blockquote>
853
  </sect1>
849
  </sect1>
854
850
855
  <sect1 label="3.7" xml:id="Bitvectors">
851
  <sect1 label="3.7" id="Bitvectors">
856
   <title>Bitvectors</title>
852
   <title>Bitvectors</title>
857
  </sect1>
853
  </sect1>
858
854
859
  <sect1 label="3.8" xml:id="Streams">
855
  <sect1 label="3.8" id="Streams">
860
   <title>Streams</title>
856
   <title>Streams</title>
861
  </sect1>
857
  </sect1>
862
858
863
  <sect1 label="3.9" xml:id="Structures">
859
  <sect1 label="3.9" id="Structures">
864
   <title>Structures</title>
860
   <title>Structures</title>
865
  </sect1>
861
  </sect1>
866
862
867
  <sect1 label="3.10" xml:id="Instances">
863
  <sect1 label="3.10" id="Instances">
868
   <title>Instances</title>
864
   <title>Instances</title>
869
   <!--  -->
865
   <!--  -->
870
  </sect1>
866
  </sect1>
871
867
872
  <sect1 label="3.11" xml:id="Bytecodes">
868
  <sect1 label="3.11" id="Bytecodes">
873
   <title>Bytecodes</title>
869
   <title>Bytecodes</title>
874
   <para>A bytecodes object is a lisp object with a piece of code that can be
870
   <para>A bytecodes object is a lisp object with a piece of code that can be
875
    interpreted. The objects of type <literal>t_bytecode</literal> are implicitly constructed
871
    interpreted. The objects of type <literal>t_bytecode</literal> are implicitly constructed
876
    by a call to <literal>eval</literal>, but can also be explicitly constructed with the
872
    by a call to <literal>eval</literal>, but can also be explicitly constructed with the
877
    <literal>make_lambda</literal> function.</para>
873
    <literal>make_lambda</literal> function.</para>
878
   <blockquote>
874
   <blockquote>
879
    <screen><indexterm role="fn"><primary>cl_safe_eval</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>cl_safe_eval</function> (<type>cl_object</type> <varname>form</varname>, <type>cl_object</type> <varname>env</varname>, <type>cl_object</type> <varname>err_value</varname></screen>
875
    <screen><indexterm role="fn"><primary>cl_safe_eval</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>cl_safe_eval</function> (<type>cl_object</type> <varname>form</varname>, <type>cl_object</type> <varname>env</varname>, <type>cl_object</type> <varname>err_value</varname></screen>
880
    <screen><indexterm role="fn"><primary>cl_eval</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>cl_eval</function> (<type>cl_object</type> <varname>form</varname>)</screen>
876
    <screen><indexterm role="fn"><primary>cl_eval</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>cl_eval</function> (<type>cl_object</type> <varname>form</varname>)</screen>
881
    <para><literal>cl_safe_eval</literal> evaluates <replaceable>form</replaceable> in the lexical environment <replaceable>env</replaceable>,
877
    <para><literal>cl_safe_eval</literal> evaluates <replaceable>form</replaceable> in the lexical environment <replaceable>env</replaceable>,
882
     which can be <replaceable>nil</replaceable>. Before evaluating it, the expression <replaceable>form</replaceable> must
878
     which can be <replaceable>nil</replaceable>. Before evaluating it, the expression <replaceable>form</replaceable> must
883
     be bytecompiled. <literal>cl_eval</literal> is the equivalent of <literal>cl_safe_eval</literal> but
879
     be bytecompiled. <literal>cl_eval</literal> is the equivalent of <literal>cl_safe_eval</literal> but
884
     without environment and with <replaceable>err_value</replaceable> set to <replaceable>nil</replaceable>. It exists only
880
     without environment and with <replaceable>err_value</replaceable> set to <replaceable>nil</replaceable>. It exists only
885
     for compatibility with previous versions.</para>
881
     for compatibility with previous versions.</para>
...
...
888
     cl_safe_eval(form,Cnil);
884
     cl_safe_eval(form,Cnil);
889
     cl_safe_eval(form, Cnil);
885
     cl_safe_eval(form, Cnil);
890
    </screen>
886
    </screen>
891
   </blockquote>
887
   </blockquote>
892
   <blockquote>
888
   <blockquote>
893
    <screen><indexterm role="fn"><primary>si_make_lambda</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>si_make_lambda</function> (<type>cl_object</type> <varname>name</varname>, <type>cl_object</type> <varname>def</varname>)</screen>
889
    <screen><indexterm role="fn"><primary>si_make_lambda</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>si_make_lambda</function> (<type>cl_object</type> <varname>name</varname>, <type>cl_object</type> <varname>def</varname>)</screen>
894
    <para>Builds an interpreted lisp function with name given by the symbol <replaceable>name</replaceable>
890
    <para>Builds an interpreted lisp function with name given by the symbol <replaceable>name</replaceable>
895
     and body given by <replaceable>def</replaceable>. For instance, we would achieve the equivalent of</para>
891
     and body given by <replaceable>def</replaceable>. For instance, we would achieve the equivalent of</para>
896
    <programlisting>
892
    <programlisting>
897
     (funcall #'(lambda (x y) (block foo (+ x y)))
893
     (funcall #'(lambda (x y) (block foo (+ x y)))
898
     1 2)
894
     1 2)
...
...
916
   </blockquote>
912
   </blockquote>
917
   <!--  -->
913
   <!--  -->
918
  </sect1>
914
  </sect1>
919
 </section>
915
 </section>
920
916
921
 <section xml:id="The-interpreter">
917
 <section id="The-interpreter">
922
  <title>The interpreter</title>
918
  <title>The interpreter</title>
923
  <sect1 label="4.1" xml:id="ECL-stacks">
919
  <sect1 label="4.1" id="ECL-stacks">
924
   <title>&ECL; stacks</title>
920
   <title>&ECL; stacks</title>
925
   <para>&ECL; uses the following stacks:</para>
921
   <para>&ECL; uses the following stacks:</para>
926
   <variablelist>
922
   <variablelist>
927
    <varlistentry>
923
    <varlistentry>
928
     <term>Frame Stack</term>
924
     <term>Frame Stack</term>
...
...
951
     </listitem>
947
     </listitem>
952
    </varlistentry>
948
    </varlistentry>
953
   </variablelist>
949
   </variablelist>
954
  </sect1>
950
  </sect1>
955
951
956
  <sect1 label="4.2" xml:id="Procedure-Call-Conventions">
952
  <sect1 label="4.2" id="Procedure-Call-Conventions">
957
   <title>Procedure Call Conventions</title>
953
   <title>Procedure Call Conventions</title>
958
   <para>&ECL; employs standard C calling conventions to achieve efficiency and
954
   <para>&ECL; employs standard C calling conventions to achieve efficiency and
959
    interoperability with other languages.
955
    interoperability with other languages.
960
    Each Lisp function is implemented as a C function which takes as many
956
    Each Lisp function is implemented as a C function which takes as many
961
    argument as the Lisp original plus one additional integer argument
957
    argument as the Lisp original plus one additional integer argument
...
...
999
    @(return CONS(car, cdr))
995
    @(return CONS(car, cdr))
1000
    @)
996
    @)
1001
   </screen>
997
   </screen>
1002
  </sect1>
998
  </sect1>
1003
999
1004
  <sect1 label="4.3" xml:id="The-lexical-environment">
1000
  <sect1 label="4.3" id="The-lexical-environment">
1005
   <title>The lexical environment</title>
1001
   <title>The lexical environment</title>
1006
   <para>The &ECL; interpreter uses two A-lists (Association lists) to
1002
   <para>The &ECL; interpreter uses two A-lists (Association lists) to
1007
    represent lexical environments.</para>
1003
    represent lexical environments.</para>
1008
   <itemizedlist mark="bullet">
1004
   <itemizedlist mark="bullet">
1009
    <listitem>
1005
    <listitem>
...
...
1017
    saved in the closure along with the lambda expression.  Later, when the
1013
    saved in the closure along with the lambda expression.  Later, when the
1018
    closure is invoked, the saved A-lists are
1014
    closure is invoked, the saved A-lists are
1019
    used to recover the lexical environment.</para>
1015
    used to recover the lexical environment.</para>
1020
  </sect1>
1016
  </sect1>
1021
1017
1022
  <sect1 label="4.4" xml:id="The-interpreter-stack">
1018
  <sect1 label="4.4" id="The-interpreter-stack">
1023
   <title>The interpreter stack</title>
1019
   <title>The interpreter stack</title>
1024
   <para>The bytecodes interpreter uses a stack of its own to save and restore values
1020
   <para>The bytecodes interpreter uses a stack of its own to save and restore values
1025
    from intermediate calculations. This Forth-like data stack is also used in
1021
    from intermediate calculations. This Forth-like data stack is also used in
1026
    other parts of the C kernel for various purposes, such as saving compiled code,
1022
    other parts of the C kernel for various purposes, such as saving compiled code,
1027
    keeping arguments to FORMAT, etc.</para>
1023
    keeping arguments to FORMAT, etc.</para>
...
...
1110
    </screen></para>
1106
    </screen></para>
1111
   <!--  -->
1107
   <!--  -->
1112
  </sect1>
1108
  </sect1>
1113
 </section>
1109
 </section>
1114
1110
1115
 <section xml:id="The-compiler">
1111
 <section id="The-compiler">
1116
  <title>The compiler</title>
1112
  <title>The compiler</title>
1117
  <sect1 label="5.1" xml:id="The-compiler-translates-to-C">
1113
  <sect1 label="5.1" id="The-compiler-translates-to-C">
1118
   <title>The compiler translates to C</title>
1114
   <title>The compiler translates to C</title>
1119
   <para>The &ECL; compiler is essentially a translator from Common-Lisp to C.  Given
1115
   <para>The &ECL; compiler is essentially a translator from Common-Lisp to C.  Given
1120
    a Lisp source file, the compiler first generates three intermediate
1116
    a Lisp source file, the compiler first generates three intermediate
1121
    files:</para>
1117
    files:</para>
1122
   <itemizedlist mark="bullet">
1118
   <itemizedlist mark="bullet">
...
...
1168
      therefore slower than compiler generating machine code directly.</para>
1164
      therefore slower than compiler generating machine code directly.</para>
1169
    </listitem>
1165
    </listitem>
1170
   </itemizedlist>
1166
   </itemizedlist>
1171
  </sect1>
1167
  </sect1>
1172
1168
1173
  <sect1 label="5.2" xml:id="The-compiler-mimics-human-C-programmer">
1169
  <sect1 label="5.2" id="The-compiler-mimics-human-C-programmer">
1174
   <title>The compiler mimics human C programmer</title>
1170
   <title>The compiler mimics human C programmer</title>
1175
   <para>The format of the intermediate C code generated by the &ECL; compiler is the
1171
   <para>The format of the intermediate C code generated by the &ECL; compiler is the
1176
    same as the hand-coded C code of the &ECL; source programs.  For example,
1172
    same as the hand-coded C code of the &ECL; source programs.  For example,
1177
    supposing that the Lisp source file contains the
1173
    supposing that the Lisp source file contains the
1178
    following function definition:</para>
1174
    following function definition:</para>
...
...
1225
   <screen>
1221
   <screen>
1226
    #define VM 2
1222
    #define VM 2
1227
   </screen>
1223
   </screen>
1228
  </sect1>
1224
  </sect1>
1229
1225
1230
  <sect1 label="5.3" xml:id="Implementation-of-Compiled-Closures">
1226
  <sect1 label="5.3" id="Implementation-of-Compiled-Closures">
1231
   <title>Implementation of Compiled Closures</title>
1227
   <title>Implementation of Compiled Closures</title>
1232
   <para>The &ECL; compiler takes two passes before it invokes the C
1228
   <para>The &ECL; compiler takes two passes before it invokes the C
1233
    compiler.  The major role of the first pass is to detect function
1229
    compiler.  The major role of the first pass is to detect function
1234
    closures and to detect, for each function closure, those lexical
1230
    closures and to detect, for each function closure, those lexical
1235
    objects (i.e., lexical variable, local function definitions, tags, and
1231
    objects (i.e., lexical variable, local function definitions, tags, and
...
...
1293
    * : address of the compiled code for #'(lambda () (incf x))
1289
    * : address of the compiled code for #'(lambda () (incf x))
1294
    ** : address of the compiled code for #'(lambda () (incf x y))
1290
    ** : address of the compiled code for #'(lambda () (incf x y))
1295
    ]]></screen>
1291
    ]]></screen>
1296
  </sect1>
1292
  </sect1>
1297
1293
1298
  <sect1 label="5.4" xml:id="Use-of-Declarations-to-Improve-Efficiency">
1294
  <sect1 label="5.4" id="Use-of-Declarations-to-Improve-Efficiency">
1299
   <title>Use of Declarations to Improve Efficiency</title>
1295
   <title>Use of Declarations to Improve Efficiency</title>
1300
   <para>Declarations, especially  type  and  function  declarations,
1296
   <para>Declarations, especially  type  and  function  declarations,
1301
    increase the efficiency of the compiled code.  For example, for the
1297
    increase the efficiency of the compiled code.  For example, for the
1302
    following Lisp source file, with two Common-Lisp declarations added,</para>
1298
    following Lisp source file, with two Common-Lisp declarations added,</para>
1303
   <programlisting>
1299
   <programlisting>
...
...
1333
    ;;; Note: Tail-recursive call of TAK was replaced by iteration.
1329
    ;;; Note: Tail-recursive call of TAK was replaced by iteration.
1334
    }
1330
    }
1335
   </screen>
1331
   </screen>
1336
  </sect1>
1332
  </sect1>
1337
1333
1338
  <sect1 label="5.5" xml:id="Inspecting-generated-C-code">
1334
  <sect1 label="5.5" id="Inspecting-generated-C-code">
1339
   <title>Inspecting generated C code</title>
1335
   <title>Inspecting generated C code</title>
1340
   <para>Common-Lisp defines a function disassemble, which is
1336
   <para>Common-Lisp defines a function disassemble, which is
1341
    supposed to disassemble a compiled function and to display the
1337
    supposed to disassemble a compiled function and to display the
1342
    assembler code.  According to <emphasis>Common-Lisp: The Language</emphasis>,</para>
1338
    assembler code.  According to <emphasis>Common-Lisp: The Language</emphasis>,</para>
1343
   
1339
   
...
...
1363
     RETURN(1);
1359
     RETURN(1);
1364
     }
1360
     }
1365
    </screen></para>
1361
    </screen></para>
1366
  </sect1>
1362
  </sect1>
1367
1363
1368
  <sect1 label="5.6" xml:id="Embedding-C-code">
1364
  <sect1 label="5.6" id="Embedding-C-code">
1369
   <title>Embedding C code in lisp source</title>
1365
   <title>Embedding C code in lisp source</title>
1370
   <para>There are several mechanism to integrate C code within &ECL;, but
1366
   <para>There are several mechanism to integrate C code within &ECL;, but
1371
    everything is built around two functions that allow the user to embed
1367
    everything is built around two functions that allow the user to embed
1372
    arbitrary C/C++ code into Lisp source code.</para>
1368
    arbitrary C/C++ code into Lisp source code.</para>
1373
   <para>The two mechanisms are the <literal>Clines</literal> and the <literal>c-inline</literal> special
1369
   <para>The two mechanisms are the <literal>Clines</literal> and the <literal>c-inline</literal> special
1374
    forms. The first one permits to insert code in the intermediate C/C++ file
1370
    forms. The first one permits to insert code in the intermediate C/C++ file
1375
    generated by the &ECL; compiler. Such a form outputs no value and takes
1371
    generated by the &ECL; compiler. Such a form outputs no value and takes
1376
    no arguments, except a series of strings which are inserted literally,
1372
    no arguments, except a series of strings which are inserted literally,
1377
    such as <literal>#include</literal> or <literal>#define</literal> statements, function definitions, etc.</para>
1373
    such as <literal>#include</literal> or <literal>#define</literal> statements, function definitions, etc.</para>
1378
   <blockquote>
1374
   <blockquote>
1379
    <screen><indexterm role="fn"><primary>Clines</primary></indexterm>&#151; Macro: <function>Clines</function> <varname>{</varname><varname>{</varname><varname>string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
1375
    <screen><indexterm role="fn"><primary>Clines</primary></indexterm>&mdash; Macro: <function>Clines</function> <varname>{</varname><varname>{</varname><varname>string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
1380
    <para>When the &ECL; compiler encounters a macro form <literal>(Clines <replaceable>string1
1376
    <para>When the &ECL; compiler encounters a macro form <literal>(Clines <replaceable>string1
1381
       ...  stringn</replaceable>)</literal>, it simply outputs the <replaceable>strings</replaceable> into the c-file.  The
1377
       ...  stringn</replaceable>)</literal>, it simply outputs the <replaceable>strings</replaceable> into the c-file.  The
1382
     arguments are not evaluated and each argument must be a string.  Each
1378
     arguments are not evaluated and each argument must be a string.  Each
1383
     <replaceable>string</replaceable> may consist of any number of lines, and separate lines in the
1379
     <replaceable>string</replaceable> may consist of any number of lines, and separate lines in the
1384
     <replaceable>string</replaceable> are placed in separate lines in the c-file.  In addition, each
1380
     <replaceable>string</replaceable> are placed in separate lines in the c-file.  In addition, each
...
...
1409
   <para>The second mechanism, which you already appreciate in the example above, is the
1405
   <para>The second mechanism, which you already appreciate in the example above, is the
1410
    <literal>c-inline</literal> special form. This powerful method allows the user to insert C
1406
    <literal>c-inline</literal> special form. This powerful method allows the user to insert C
1411
    code which is evaluated, and which can accept values and return values from and
1407
    code which is evaluated, and which can accept values and return values from and
1412
    to the Lisp world, with an automatic convertion taking place in both directions.</para>
1408
    to the Lisp world, with an automatic convertion taking place in both directions.</para>
1413
   <blockquote>
1409
   <blockquote>
1414
    <screen><indexterm role="fn"><primary>c-inline</primary></indexterm>&#151; Macro: <function>c-inline</function> <varname>{</varname><varname>args-list</varname> <varname>arg-C-types</varname> <varname>output-C-type</varname> <varname>C-expr</varname> <varname>&amp;key</varname> (<varname>side-effects</varname> <varname><literal>T</literal></varname>) (<varname>one-liner</varname> <varname><literal>T</literal></varname>)<varname>}</varname></screen>
1410
    <screen><indexterm role="fn"><primary>c-inline</primary></indexterm>&mdash; Macro: <function>c-inline</function> <varname>{</varname><varname>args-list</varname> <varname>arg-C-types</varname> <varname>output-C-type</varname> <varname>C-expr</varname> <varname>&amp;key</varname> (<varname>side-effects</varname> <varname><literal>T</literal></varname>) (<varname>one-liner</varname> <varname><literal>T</literal></varname>)<varname>}</varname></screen>
1415
    <para><literal>c-inline</literal> is a special form that can only be used in compiled
1411
    <para><literal>c-inline</literal> is a special form that can only be used in compiled
1416
     code.  For all purposes it behaves as a Lisp form, which takes the
1412
     code.  For all purposes it behaves as a Lisp form, which takes the
1417
     arguments given in <replaceable>args-list</replaceable> and produces a single value. Behind
1413
     arguments given in <replaceable>args-list</replaceable> and produces a single value. Behind
1418
     the curtains, the arguments of <replaceable>args-list</replaceable> (which can be any valid
1414
     the curtains, the arguments of <replaceable>args-list</replaceable> (which can be any valid
1419
     Lisp form) are coerced to the the C types given in <replaceable>arg-C-types</replaceable>,
1415
     Lisp form) are coerced to the the C types given in <replaceable>arg-C-types</replaceable>,
...
...
1455
     :one-liner nil))
1451
     :one-liner nil))
1456
    </programlisting>
1452
    </programlisting>
1457
   </blockquote>
1453
   </blockquote>
1458
  </sect1>
1454
  </sect1>
1459
1455
1460
  <sect1 label="5.7" xml:id="The-C-language-interface">
1456
  <sect1 label="5.7" id="The-C-language-interface">
1461
   <title>The C language interface</title>
1457
   <title>The C language interface</title>
1462
   <para>Using these special forms <literal>clines</literal> and <literal>c-inline</literal>, plus the ability to
1458
   <para>Using these special forms <literal>clines</literal> and <literal>c-inline</literal>, plus the ability to
1463
    handle pointers to foreign data, we have built a rather complete FFI for
1459
    handle pointers to foreign data, we have built a rather complete FFI for
1464
    interfacing with the C world. This interface is compatible with the UFFI
1460
    interfacing with the C world. This interface is compatible with the UFFI
1465
    specification, which can be found in the web. We recommend you to grab the
1461
    specification, which can be found in the web. We recommend you to grab the
...
...
1469
   <para>However, because &ECL; provides some additional functionality which escapes the
1465
   <para>However, because &ECL; provides some additional functionality which escapes the
1470
    UFFI, and also for compatibility with older versions of the &ECL; environment,
1466
    UFFI, and also for compatibility with older versions of the &ECL; environment,
1471
    we provide additional toplevel forms, which are listed in the next section.</para>
1467
    we provide additional toplevel forms, which are listed in the next section.</para>
1472
  </sect1>
1468
  </sect1>
1473
1469
1474
  <sect1 label="5.8" xml:id="The-old-C-language-interface">
1470
  <sect1 label="5.8" id="The-old-C-language-interface">
1475
   <title>The old C language interface</title>
1471
   <title>The old C language interface</title>
1476
   <para>In this section we list several macros and toplevel forms which are provided
1472
   <para>In this section we list several macros and toplevel forms which are provided
1477
    either for convenience or for compatibility with older versions of &ECL;.
1473
    either for convenience or for compatibility with older versions of &ECL;.
1478
    You should avoid using them when the UFFI-compatible interface provides
1474
    You should avoid using them when the UFFI-compatible interface provides
1479
    similar functionality.</para>
1475
    similar functionality.</para>
...
...
1486
    C-language expression.  A <emphasis>C-type</emphasis> is one of the Lisp symbols
1482
    C-language expression.  A <emphasis>C-type</emphasis> is one of the Lisp symbols
1487
    <literal>:int, :char, :float, :double,...</literal> and <literal>:object</literal>.
1483
    <literal>:int, :char, :float, :double,...</literal> and <literal>:object</literal>.
1488
    Each corresponds to a data type in the C language; <literal>:object</literal> is
1484
    Each corresponds to a data type in the C language; <literal>:object</literal> is
1489
    the type of Lisp object and other C-types are primitive data types in C.</para>
1485
    the type of Lisp object and other C-types are primitive data types in C.</para>
1490
   <blockquote>
1486
   <blockquote>
1491
    <screen><indexterm role="fn"><primary>defentry</primary></indexterm>&#151; Macro: <function>defentry</function> <varname>{</varname><varname>function</varname> <varname>parameter-list</varname> <varname>C-function</varname><varname>}</varname></screen>
1487
    <screen><indexterm role="fn"><primary>defentry</primary></indexterm>&mdash; Macro: <function>defentry</function> <varname>{</varname><varname>function</varname> <varname>parameter-list</varname> <varname>C-function</varname><varname>}</varname></screen>
1492
    <para><literal>defentry</literal> defines a Lisp function whose body consists of the calling
1488
    <para><literal>defentry</literal> defines a Lisp function whose body consists of the calling
1493
     sequence to a C-language function. <replaceable>function</replaceable> is the name of the Lisp
1489
     sequence to a C-language function. <replaceable>function</replaceable> is the name of the Lisp
1494
     function to be defined, and <replaceable>C-function</replaceable> specifies the C function to be
1490
     function to be defined, and <replaceable>C-function</replaceable> specifies the C function to be
1495
     invoked. <replaceable>C-function</replaceable> must be either a list <literal>(<replaceable>type C-id</replaceable>)</literal> or
1491
     invoked. <replaceable>C-function</replaceable> must be either a list <literal>(<replaceable>type C-id</replaceable>)</literal> or
1496
     <replaceable>C-id</replaceable>, where <replaceable>type</replaceable> and <replaceable>C-id</replaceable> are the type and the name of the C
1492
     <replaceable>C-id</replaceable>, where <replaceable>type</replaceable> and <replaceable>C-id</replaceable> are the type and the name of the C
...
...
1511
    conversion between Lisp and the C language.</para>
1507
    conversion between Lisp and the C language.</para>
1512
   <para>A <literal>defentry</literal> form is treated in the above way only when it appears as a
1508
   <para>A <literal>defentry</literal> form is treated in the above way only when it appears as a
1513
    top-level form of a Lisp source file.  Otherwise, a <literal>defentry</literal> form
1509
    top-level form of a Lisp source file.  Otherwise, a <literal>defentry</literal> form
1514
    expands to ().</para>
1510
    expands to ().</para>
1515
   <blockquote>
1511
   <blockquote>
1516
    <screen><indexterm role="fn"><primary>defla</primary></indexterm>&#151; Macro: <function>defla</function> <varname>{</varname><varname>name</varname> <varname>lambda-list</varname> <varname>{</varname><varname>declaration</varname> <varname>|</varname> <varname>doc-string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
1512
    <screen><indexterm role="fn"><primary>defla</primary></indexterm>&mdash; Macro: <function>defla</function> <varname>{</varname><varname>name</varname> <varname>lambda-list</varname> <varname>{</varname><varname>declaration</varname> <varname>|</varname> <varname>doc-string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
1517
    <para>When interpreted, <literal>defla</literal> is exactly the same as <literal>defun</literal>.  That is,
1513
    <para>When interpreted, <literal>defla</literal> is exactly the same as <literal>defun</literal>.  That is,
1518
     <literal>(defla <replaceable>name lambda-list .  body</replaceable>)</literal> expands to <literal>(defun <replaceable>name
1514
     <literal>(defla <replaceable>name lambda-list .  body</replaceable>)</literal> expands to <literal>(defun <replaceable>name
1519
       lambda-list .  body</replaceable>)</literal>.  However, <literal>defla</literal> forms are completely ignored by
1515
       lambda-list .  body</replaceable>)</literal>.  However, <literal>defla</literal> forms are completely ignored by
1520
     the compiler; no C-language code will be generated for <literal>defla</literal> forms.  The
1516
     the compiler; no C-language code will be generated for <literal>defla</literal> forms.  The
1521
     primary use of <literal>defla</literal> is to define a Lisp function in two ways within a
1517
     primary use of <literal>defla</literal> is to define a Lisp function in two ways within a
...
...
1551
   <para>When this file is loaded into &ECL;, the interpreter uses the Lisp version of
1547
   <para>When this file is loaded into &ECL;, the interpreter uses the Lisp version of
1552
    the <literal>tak</literal> definition.  Once this file has been compiled, and when the
1548
    the <literal>tak</literal> definition.  Once this file has been compiled, and when the
1553
    generated fasl file is loaded into &ECL;, a function call to <literal>tak</literal> is
1549
    generated fasl file is loaded into &ECL;, a function call to <literal>tak</literal> is
1554
    actually the call to the C version of <literal>tak</literal>.</para>
1550
    actually the call to the C version of <literal>tak</literal>.</para>
1555
   <blockquote>
1551
   <blockquote>
1556
    <screen><indexterm role="fn"><primary>defCbody</primary></indexterm>&#151; Function: <function>defCbody</function> <varname>name args-types result-type C-expr</varname></screen>
1552
    <screen><indexterm role="fn"><primary>defCbody</primary></indexterm>&mdash; Function: <function>defCbody</function> <varname>name args-types result-type C-expr</varname></screen>
1557
    <para>The &ECL; compiler produces a function named <replaceable>name</replaceable> with as many
1553
    <para>The &ECL; compiler produces a function named <replaceable>name</replaceable> with as many
1558
     arguments as <replaceable>arg-types</replaceable>.  The <replaceable>C-expr</replaceable> is an arbitrary C expression
1554
     arguments as <replaceable>arg-types</replaceable>.  The <replaceable>C-expr</replaceable> is an arbitrary C expression
1559
     where the arguments to the function are denoted by <literal>#</para>
1555
     where the arguments to the function are denoted by <literal>#</para>
1560
    <replaceable>i</replaceable></literal>
1556
    <replaceable>i</replaceable></literal>
1561
    <para>, where
1557
    <para>, where
...
...
1570
   </blockquote>
1566
   </blockquote>
1571
   <para>For example, the logical AND of two integers could be defined as:</para>
1567
   <para>For example, the logical AND of two integers could be defined as:</para>
1572
   <programlisting>(defCbody logand (fixnum fixnum) fixnum "(#0) &amp; (#1)")
1568
   <programlisting>(defCbody logand (fixnum fixnum) fixnum "(#0) &amp; (#1)")
1573
   </programlisting>
1569
   </programlisting>
1574
   <blockquote>
1570
   <blockquote>
1575
    <screen><indexterm role="fn"><primary>definline</primary></indexterm>&#151; Function: <function>definline</function> <varname>{</varname><varname>name</varname> <varname>args-types</varname> <varname>result-type</varname> <varname>C-expr</varname><varname>}</varname></screen>
1571
    <screen><indexterm role="fn"><primary>definline</primary></indexterm>&mdash; Function: <function>definline</function> <varname>{</varname><varname>name</varname> <varname>args-types</varname> <varname>result-type</varname> <varname>C-expr</varname><varname>}</varname></screen>
1576
    <para><literal>definline</literal> behaves exactly as <literal>defCbody</literal>.  Moreover, after a
1572
    <para><literal>definline</literal> behaves exactly as <literal>defCbody</literal>.  Moreover, after a
1577
     <literal>definline</literal> definition has been supplied, the &ECL; compiler will expand
1573
     <literal>definline</literal> definition has been supplied, the &ECL; compiler will expand
1578
     inline any call to function <replaceable>name</replaceable> into code corresponding to the C
1574
     inline any call to function <replaceable>name</replaceable> into code corresponding to the C
1579
     language expression <replaceable>C-expr</replaceable>, provided that the actual arguments are of the
1575
     language expression <replaceable>C-expr</replaceable>, provided that the actual arguments are of the
1580
     specified type.  If the actual arguments cannot be coerced to those types, the
1576
     specified type.  If the actual arguments cannot be coerced to those types, the
...
...
1623
    ]]></screen>
1619
    ]]></screen>
1624
   <!--  -->
1620
   <!--  -->
1625
  </sect1>
1621
  </sect1>
1626
 </section>
1622
 </section>
1627
1623
1628
 <section xml:id="The-Garbage-Collector">
1624
 <section id="The-Garbage-Collector">
1629
  <title>The Garbage Collector</title>
1625
  <title>The Garbage Collector</title>
1630
  <para>Using &ECL; in existing application sometimes involves keeping Lisp
1626
  <para>Using &ECL; in existing application sometimes involves keeping Lisp
1631
   objects where the garbage collector normally cannot see them.</para>
1627
   objects where the garbage collector normally cannot see them.</para>
1632
  <!-- FIXME: Complete this... -->
1628
  <!-- FIXME: Complete this... -->
1633
  <!--  -->
1629
  <!--  -->
1634
 </section>
1630
 </section>
1635
1631
1636
 <section xml:id="Porting-ECL">
1632
 <section id="Porting-ECL">
1637
  <title>Porting &ECL;</title>
1633
  <title>Porting &ECL;</title>
1638
  <para>To port &ECL; to a new architecture, the following steps are required:</para>
1634
  <para>To port &ECL; to a new architecture, the following steps are required:</para>
1639
  <orderedlist numeration="arabic">
1635
  <orderedlist numeration="arabic">
1640
   <listitem>
1636
   <listitem>
1641
    <para>Ensure that the GNU Multiprecision library supports this machine.</para>
1637
    <para>Ensure that the GNU Multiprecision library supports this machine.</para>