Diff of /internals.xmlf [b20a97] .. [d0e0b7] Maximize Restore

  Switch to unified view

a/internals.xmlf b/internals.xmlf
1
<?xml version="1.0"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
1
<?xml version="1.0" encoding="utf-8"?>
2
<book lang="en"><part id="part.internals"><title>Internals</title>
2
<!DOCTYPE book [
3
<!ENTITY % eclent SYSTEM "ecl.ent">
4
%eclent;
5
]>
6
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"><part xml:id="part.internals"><title>Internals</title>
3
<partintro>
7
<partintro>
4
 <para>&ECL; is an implementation of the Common-Lisp language that is based on a kernel
8
 <para>&ECL; is an implementation of the Common-Lisp language that is based on a kernel
5
 written in C plus a set of libraries written in Common-Lisp. The kernel includes a
9
 written in C plus a set of libraries written in Common-Lisp. The kernel includes a
6
 bytecodes compiler, an interpreter, and enough functions to create and
10
 bytecodes compiler, an interpreter, and enough functions to create and
7
 manipulate all lisp objects. The lisp libraries provide higher level constructs
11
 manipulate all lisp objects. The lisp libraries provide higher level constructs
...
...
25
 programs so that they can be invoked from &ECL;. In addition, the user can
29
 programs so that they can be invoked from &ECL;. In addition, the user can
26
 write Lisp function definitions in the C language to increase runtime
30
 write Lisp function definitions in the C language to increase runtime
27
 efficiency.</para>
31
 efficiency.</para>
28
</partintro>
32
</partintro>
29
33
30
<chapter id="Building-programs">
34
<chapter xml:id="Building-programs">
31
 <title>Building programs</title>
35
 <title>Building programs</title>
32
 <para>In this section we describe how you can use &ECL; to build programs and
36
 <para>In this section we describe how you can use &ECL; to build programs and
33
 loadable extensions that you can later on distribute to other people.</para>
37
 loadable extensions that you can later on distribute to other people.</para>
34
38
35
 <section id="Internals-What-can-ECL-do-">
39
 <section xml:id="Internals-What-can-ECL-do-">
36
  <title>What can &ECL; do?</title>
40
  <title>What can &ECL; do?</title>
37
  <para>Some day for some reasons you will be in the need to distribute code that
41
  <para>Some day for some reasons you will be in the need to distribute code that
38
  has been developed using &ECL;. In the following sections we will describe
42
  has been developed using &ECL;. In the following sections we will describe
39
  the means that &ECL; offers you to do so. Basically, these are the
43
  the means that &ECL; offers you to do so. Basically, these are the
40
  alternatives</para>
44
  alternatives</para>
...
...
100
  initialization function (<literal>mymain()</literal> in the example above). These means
104
  initialization function (<literal>mymain()</literal> in the example above). These means
101
  are explained in the following sections.</para>
105
  are explained in the following sections.</para>
102
  <!--  -->
106
  <!--  -->
103
 </section>
107
 </section>
104
108
105
 <section id="Internals-Compiling-files">
109
 <section xml:id="Internals-Compiling-files">
106
  <title>Compiling files</title>
110
  <title>Compiling files</title>
107
  <para>&ECL; supports two types of compilation. One is bytecodes compilation. This
111
  <para>&ECL; supports two types of compilation. One is bytecodes compilation. This
108
  process is performed on-the-fly, as you load source files with lisp code. This
112
  process is performed on-the-fly, as you load source files with lisp code. This
109
  leads to a series of bytes for each instruction, the so called
113
  leads to a series of bytes for each instruction, the so called
110
  "bytecodes". These bytecodes are interpreted in a virtual machine, which is
114
  "bytecodes". These bytecodes are interpreted in a virtual machine, which is
...
...
135
   </varlistentry>
139
   </varlistentry>
136
  </variablelist>
140
  </variablelist>
137
  <!--  -->
141
  <!--  -->
138
 </section>
142
 </section>
139
143
140
 <section id="Internals-Building-standalone-executables">
144
 <section xml:id="Internals-Building-standalone-executables">
141
  <title>Building standalone executables</title>
145
  <title>Building standalone executables</title>
142
  <para>To build an executable you need a working &ECL; image with the
146
  <para>To build an executable you need a working &ECL; image with the
143
  compiler. The function to build customized images is
147
  compiler. The function to build customized images is
144
  <replaceable>c::build-program</replaceable>. The description of this function is as
148
  <replaceable>c::build-program</replaceable>. The description of this function is as
145
  follows. Care should be taken that <replaceable>image-name</replaceable> differs from any
149
  follows. Care should be taken that <replaceable>image-name</replaceable> differs from any
146
  filename in <replaceable>lisp-files</replaceable>.</para>
150
  filename in <replaceable>lisp-files</replaceable>.</para>
147
  <blockquote>
151
  <blockquote>
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>
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>
149
   <para>This function builds a lisp image up from the core lisp library, plus all
153
   <para>This function builds a lisp image up from the core lisp library, plus all
150
   components listed in <replaceable>lisp-files</replaceable>.  Each component is either:</para>
154
   components listed in <replaceable>lisp-files</replaceable>.  Each component is either:</para>
151
   <itemizedlist mark="bullet">
155
   <itemizedlist mark="bullet">
152
    <listitem>
156
    <listitem>
153
     <para>A symbol: Names a statically linked library built from lisp code.</para>
157
     <para>A symbol: Names a statically linked library built from lisp code.</para>
...
...
170
   will be interpreted at run time.</para>
174
   will be interpreted at run time.</para>
171
  </blockquote>
175
  </blockquote>
172
  <!--  -->
176
  <!--  -->
173
 </section>
177
 </section>
174
178
175
 <section id="Internals-Building-libraries">
179
 <section xml:id="Internals-Building-libraries">
176
  <title>Building libraries</title>
180
  <title>Building libraries</title>
177
  <para>To build a library you proceed more or less the same way as with standalone
181
  <para>To build a library you proceed more or less the same way as with standalone
178
  executables. There are two different functions depending on whether you need
182
  executables. There are two different functions depending on whether you need
179
  to build static or shared libraries.</para>
183
  to build static or shared libraries.</para>
180
  <blockquote>
184
  <blockquote>
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>
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>
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>
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>
183
   <para>This function builds a library file up from the object files listed in
187
   <para>This function builds a library file up from the object files listed in
184
   <replaceable>lisp-files</replaceable>. Each of the arguments to <replaceable>lisp-file</replaceable> must name a single
188
   <replaceable>lisp-files</replaceable>. Each of the arguments to <replaceable>lisp-file</replaceable> must name a single
185
   object file produced with <literal>compile-file</literal>.</para>
189
   object file produced with <literal>compile-file</literal>.</para>
186
   <para><replaceable>library-name</replaceable> is the physical pathname corresponding to the library. The
190
   <para><replaceable>library-name</replaceable> is the physical pathname corresponding to the library. The
187
   value of <replaceable>library-name</replaceable> must follow some system-specific conventions.  To
191
   value of <replaceable>library-name</replaceable> must follow some system-specific conventions.  To
...
...
205
   </para>
209
   </para>
206
  </blockquote>
210
  </blockquote>
207
  <!--  -->
211
  <!--  -->
208
 </section>
212
 </section>
209
213
210
 <section id="Internals-File-names">
214
 <section xml:id="Internals-File-names">
211
  <title>File names</title>
215
  <title>File names</title>
212
  <blockquote>
216
  <blockquote>
213
   <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>
217
   <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>
214
   <para>When compiling lisp files, creating libraries, etc, a number of files are
218
   <para>When compiling lisp files, creating libraries, etc, a number of files are
215
   produced which are of interest for the user or programmer. However, the name
219
   produced which are of interest for the user or programmer. However, the name
216
   of these files will change from system to system. The purpose of the function
220
   of these files will change from system to system. The purpose of the function
217
   <literal>compile-file-pathname</literal> is to query the compiler about the name of the
221
   <literal>compile-file-pathname</literal> is to query the compiler about the name of the
218
   different files that it can produce. Possible values of the <replaceable>type</replaceable>
222
   different files that it can produce. Possible values of the <replaceable>type</replaceable>
...
...
265
   </screen></para>
269
   </screen></para>
266
  </blockquote>
270
  </blockquote>
267
  <!--  -->
271
  <!--  -->
268
 </section>
272
 </section>
269
273
270
 <section id="Internals-Compiler-examples">
274
 <section xml:id="Internals-Compiler-examples">
271
  <title>Compiler examples</title>
275
  <title>Compiler examples</title>
272
  <section>
276
  <section>
273
   <title>The <filename>hello.lisp</filename> file</title>
277
   <title>The <filename>hello.lisp</filename> file</title>
274
   <para>In the following examples we will use the same lisp program. You have to
278
   <para>In the following examples we will use the same lisp program. You have to
275
   create a file called <filename>hello.lisp</filename> which contains the following lines</para>
279
   create a file called <filename>hello.lisp</filename> which contains the following lines</para>
...
...
315
    ;;; Loading #P"/usr/lib/ecl/sysfun.lsp"
319
    ;;; Loading #P"/usr/lib/ecl/sysfun.lsp"
316
    ;;; Compiling hello.lisp.
320
    ;;; Compiling hello.lisp.
317
    ;;; End of Pass 1.
321
    ;;; End of Pass 1.
318
    ;;; Calling the C compiler...
322
    ;;; Calling the C compiler...
319
    ;;; 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"
323
    ;;; 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"
320
    ;;; 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
324
    ;;; 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
321
    ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
325
    ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
322
    ;;; Finished compiling hello.lisp.
326
    ;;; Finished compiling hello.lisp.
323
    #P"hello.fas"
327
    #P"hello.fas"
324
    Top level.
328
    Top level.
325
    &gt; <lineannotation>(load "hello")</lineannotation>
329
    &gt; <lineannotation>(load "hello")</lineannotation>
...
...
350
   </screen></para>
354
   </screen></para>
351
   <para role="continues">The final step is to build the executable using the <literal>c:build-program</literal>
355
   <para role="continues">The final step is to build the executable using the <literal>c:build-program</literal>
352
   instruction.<screen>
356
   instruction.<screen>
353
   &gt; <lineannotation>(c:build-program "myecl" :lisp-files '("hello.o"))</lineannotation>
357
   &gt; <lineannotation>(c:build-program "myecl" :lisp-files '("hello.o"))</lineannotation>
354
   ;;; 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"
358
   ;;; 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"
355
   ;;; 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
359
   ;;; 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
356
   #P"myecl"
360
   #P"myecl"
357
   Top level.
361
   Top level.
358
   </screen>Now you can execute this program from your favorite shell.</para>
362
   </screen>Now you can execute this program from your favorite shell.</para>
359
   <para role="continues"><screen>
363
   <para role="continues"><screen>
360
    % <lineannotation>./myecl</lineannotation>
364
    % <lineannotation>./myecl</lineannotation>
...
...
386
   </screen></para>
390
   </screen></para>
387
   <para role="continues">The final step is to build the library using the <literal>c:build-fasl</literal>
391
   <para role="continues">The final step is to build the library using the <literal>c:build-fasl</literal>
388
   instruction.<screen>
392
   instruction.<screen>
389
   &gt; (c:build-fasl "myecl" :lisp-files '("hello.o"))
393
   &gt; (c:build-fasl "myecl" :lisp-files '("hello.o"))
390
   ;;; 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"
394
   ;;; 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"
391
   ;;; 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
395
   ;;; 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
392
   #P"libmyecl.so"
396
   #P"libmyecl.so"
393
   </screen>Now you can load this extension from any &ECL; image, even those you produce
397
   </screen>Now you can load this extension from any &ECL; image, even those you produce
394
   with <literal>c:build-program</literal>.</para>
398
   with <literal>c:build-program</literal>.</para>
395
   <para role="continues"><screen>
399
   <para role="continues"><screen>
396
    &lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; THIS EXAMPLE IS WRONG?! &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
400
    &lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; THIS EXAMPLE IS WRONG?! &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
...
...
402
   <!--  -->
406
   <!--  -->
403
  </section>
407
  </section>
404
 </section>
408
 </section>
405
</chapter>
409
</chapter>
406
410
407
<chapter id="Lisp-objects">
411
<chapter xml:id="Lisp-objects">
408
 <title>Manipulating Lisp objects</title>
412
 <title>Manipulating Lisp objects</title>
409
 <para>If you want to extend, fix or simply customize &ECL; for your own needs,
413
 <para>If you want to extend, fix or simply customize &ECL; for your own needs,
410
 you should understand how the implementation works.</para>
414
 you should understand how the implementation works.</para>
411
415
412
 <section id="Internals-Objects-representation">
416
 <section xml:id="Internals-Objects-representation">
413
  <title>Objects representation</title>
417
  <title>Objects representation</title>
414
  <para>In &ECL; a lisp object is represented by a type called <literal>cl_object</literal>. This
418
  <para>In &ECL; a lisp object is represented by a type called <literal>cl_object</literal>. This
415
  type is a word which is long enough to host both an integer and a pointer. The
419
  type is a word which is long enough to host both an integer and a pointer. The
416
  least significant bits of this word, also called the tag bits, determine
420
  least significant bits of this word, also called the tag bits, determine
417
  whether it is a pointer to a C structure representing a complex object, or
421
  whether it is a pointer to a C structure representing a complex object, or
...
...
453
  |--------------------| 
457
  |--------------------| 
454
  ]]></screen>
458
  ]]></screen>
455
  <para>There is one important function which tells the type of an object, plus several
459
  <para>There is one important function which tells the type of an object, plus several
456
  macros which group several tests.</para>
460
  macros which group several tests.</para>
457
  <blockquote>
461
  <blockquote>
458
   <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&mdash; C type: <structname>cl_object</structname></screen>
462
   <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&#151; C type: <structname>cl_object</structname></screen>
459
   <para>This is the type of a lisp object. For your C/C++ program, a <literal>cl_object</literal>
463
   <para>This is the type of a lisp object. For your C/C++ program, a <literal>cl_object</literal>
460
   can be either a fixnum, a character, or a pointer to a union of structures (See
464
   can be either a fixnum, a character, or a pointer to a union of structures (See
461
   the header <filename>object.h</filename>). The actual interpretation of that object can be
465
   the header <filename>object.h</filename>). The actual interpretation of that object can be
462
   guessed with the macro <literal>type_of</literal>.</para>
466
   guessed with the macro <literal>type_of</literal>.</para>
463
   <para>For example, if <replaceable>x</replaceable> is of type <literal>cl_object</literal>, and it is of type fixnum,
467
   <para>For example, if <replaceable>x</replaceable> is of type <literal>cl_object</literal>, and it is of type fixnum,
...
...
477
   </screen>
481
   </screen>
478
   <para role="continues">You should see the following sections and the header <filename>object.h</filename> to learn
482
   <para role="continues">You should see the following sections and the header <filename>object.h</filename> to learn
479
   how to use the different fields of a <literal>cl_object</literal> pointer.</para>
483
   how to use the different fields of a <literal>cl_object</literal> pointer.</para>
480
  </blockquote>
484
  </blockquote>
481
  <blockquote>
485
  <blockquote>
482
   <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&mdash; C type: <structname>cl_type</structname></screen>
486
   <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&#151; C type: <structname>cl_type</structname></screen>
483
   <para>Enumeration type which distinguishes the different types of lisp objects.  The
487
   <para>Enumeration type which distinguishes the different types of lisp objects.  The
484
   most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
488
   most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
485
   t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
489
   t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
486
   t_array, t_vector, t_string, t_bitvector, t_stream, t_random, t_readtable,
490
   t_array, t_vector, t_string, t_bitvector, t_stream, t_random, t_readtable,
487
   t_pathname, t_bytecodes, t_cfun, t_cclosure, t_gfun, t_instance, t_foreign and
491
   t_pathname, t_bytecodes, t_cfun, t_cclosure, t_gfun, t_instance, t_foreign and
488
   t_thread.</para>
492
   t_thread.</para>
489
  </blockquote>
493
  </blockquote>
490
  <blockquote>
494
  <blockquote>
491
   <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>
495
   <screen><indexterm role="fn"><primary>type_of</primary></indexterm>&#151; Function: <returnvalue>cl_type</returnvalue> <function>type_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
492
   <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>type_of(<replaceable>O</replaceable>)</literal> returns an integer
496
   <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>type_of(<replaceable>O</replaceable>)</literal> returns an integer
493
   denoting the type that lisp object. That integer is one of the values of the
497
   denoting the type that lisp object. That integer is one of the values of the
494
   enumeration type <literal>cl_type</literal>.</para>
498
   enumeration type <literal>cl_type</literal>.</para>
495
  </blockquote>
499
  </blockquote>
496
  <blockquote>
500
  <blockquote>
497
   <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
501
   <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
498
   <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
502
   <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
499
   <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
503
   <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
500
   <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
504
   <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
501
   <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
505
   <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
502
   <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
506
   <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
503
   <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
507
   <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
504
   <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
508
   <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
505
   <para>Different macros that check whether <replaceable>o</replaceable> belongs to the specified type.
509
   <para>Different macros that check whether <replaceable>o</replaceable> belongs to the specified type.
506
   These checks have been optimized, and are preferred over several calls to
510
   These checks have been optimized, and are preferred over several calls to
507
   <literal>type_of</literal>.</para>
511
   <literal>type_of</literal>.</para>
508
  </blockquote>
512
  </blockquote>
509
  <blockquote>
513
  <blockquote>
510
   <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
514
   <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
511
   <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
515
   <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
512
  </blockquote>
516
  </blockquote>
513
  <!--  -->
517
  <!--  -->
514
 </section>
518
 </section>
515
519
516
 <section id="Internals-Constructing-objects">
520
 <section xml:id="Internals-Constructing-objects">
517
  <title>Constructing objects</title>
521
  <title>Constructing objects</title>
518
  <para>On each of the following sections we will document the standard interface for
522
  <para>On each of the following sections we will document the standard interface for
519
  building objects of different types. For some objects, though, it is too
523
  building objects of different types. For some objects, though, it is too
520
  difficult to make a C interface that resembles all of the functionality in the
524
  difficult to make a C interface that resembles all of the functionality in the
521
  lisp environment. In those cases you need to</para>
525
  lisp environment. In those cases you need to</para>
...
...
528
   </listitem>
532
   </listitem>
529
  </orderedlist>
533
  </orderedlist>
530
  <para role="continues">The first way makes use of a C or Lisp string to construct an object. The two
534
  <para role="continues">The first way makes use of a C or Lisp string to construct an object. The two
531
  functions you need to know are the following ones.</para>
535
  functions you need to know are the following ones.</para>
532
  <blockquote>
536
  <blockquote>
533
   <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>
537
   <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>
534
   <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>
538
   <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>
535
   <para><literal>c_string_to_object</literal> builds a lisp object from a C string which contains a
539
   <para><literal>c_string_to_object</literal> builds a lisp object from a C string which contains a
536
   suitable representation of a lisp object. <literal>string_to_object</literal> performs the
540
   suitable representation of a lisp object. <literal>string_to_object</literal> performs the
537
   same task, but uses a lisp string, and therefore it is less useful. Two
541
   same task, but uses a lisp string, and therefore it is less useful. Two
538
   examples of their use</para>
542
   examples of their use</para>
539
   <screen>
543
   <screen>
...
...
546
   </screen>
550
   </screen>
547
  </blockquote>
551
  </blockquote>
548
  <!--  -->
552
  <!--  -->
549
 </section>
553
 </section>
550
554
551
 <section id="Internals-Integers">
555
 <section xml:id="Internals-Integers">
552
  <title>Integers</title>
556
  <title>Integers</title>
553
  <para>Common-Lisp distinguishes two types of integer types: bignums and fixnums. A
557
  <para>Common-Lisp distinguishes two types of integer types: bignums and fixnums. A
554
  fixnum is a small integer, which ideally occupies only a word of memory and
558
  fixnum is a small integer, which ideally occupies only a word of memory and
555
  which is between the values <replaceable>MOST-NEGATIVE-FIXNUM</replaceable> and
559
  which is between the values <replaceable>MOST-NEGATIVE-FIXNUM</replaceable> and
556
  <replaceable>MOST-POSITIVE-FIXNUM</replaceable>. A bignum is any integer which is not a fixnum and
560
  <replaceable>MOST-POSITIVE-FIXNUM</replaceable>. A bignum is any integer which is not a fixnum and
...
...
561
  the <filename>ecl.h</filename> header to make sure that your C extensions are portable.
565
  the <filename>ecl.h</filename> header to make sure that your C extensions are portable.
562
  All other integers are stored as bignums, they are not immediate objects, they
566
  All other integers are stored as bignums, they are not immediate objects, they
563
  take up a variable amount of memory and the GNU Multiprecision Library is
567
  take up a variable amount of memory and the GNU Multiprecision Library is
564
  required to create, manipulate and calculate with them.</para>
568
  required to create, manipulate and calculate with them.</para>
565
  <blockquote>
569
  <blockquote>
566
   <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&mdash; C type: <structname>cl_fixnum</structname></screen>
570
   <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&#151; C type: <structname>cl_fixnum</structname></screen>
567
   <para>This is a C signed integer type capable of holding a whole fixnum without any
571
   <para>This is a C signed integer type capable of holding a whole fixnum without any
568
   loss of precision. The opposite is not true, and you may create a
572
   loss of precision. The opposite is not true, and you may create a
569
   <literal>cl_fixnum</literal> which exceeds the limits of a fixnum and should be stored as a
573
   <literal>cl_fixnum</literal> which exceeds the limits of a fixnum and should be stored as a
570
   bignum.</para>
574
   bignum.</para>
571
  </blockquote>
575
  </blockquote>
572
  <blockquote>
576
  <blockquote>
573
   <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&mdash; C type: <structname>cl_index</structname></screen>
577
   <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&#151; C type: <structname>cl_index</structname></screen>
574
   <para>This is a C unsigned integer type capable of holding a nonnegative fixnum without
578
   <para>This is a C unsigned integer type capable of holding a nonnegative fixnum without
575
   loss of precision. Typically, a <literal>cl_index</literal> is used as an index into an array,
579
   loss of precision. Typically, a <literal>cl_index</literal> is used as an index into an array,
576
   or into a proper list, etc.</para>
580
   or into a proper list, etc.</para>
577
  </blockquote>
581
  </blockquote>
578
  <blockquote>
582
  <blockquote>
579
   <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
583
   <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
580
   <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
584
   <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
581
   <para>These constants mark the limits of a fixnum.</para>
585
   <para>These constants mark the limits of a fixnum.</para>
582
  </blockquote>
586
  </blockquote>
583
  <blockquote>
587
  <blockquote>
584
   <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>
588
   <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>
585
   <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>
589
   <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>
586
   <para>These functions perform the checks (<replaceable>o</replaceable> &lt; 0) and (0 &lt;= <replaceable>o</replaceable>),
590
   <para>These functions perform the checks (<replaceable>o</replaceable> &lt; 0) and (0 &lt;= <replaceable>o</replaceable>),
587
   respectively.</para>
591
   respectively.</para>
588
  </blockquote>
592
  </blockquote>
589
  <blockquote>
593
  <blockquote>
590
   <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>
594
   <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>
591
   <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>
595
   <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>
592
   <para><literal>MAKE_FIXNUM</literal> and <literal>fix</literal> convert from an integer to a lisp object
596
   <para><literal>MAKE_FIXNUM</literal> and <literal>fix</literal> convert from an integer to a lisp object
593
   of fixnum type and vice versa. These functions no not check their arguments.</para>
597
   of fixnum type and vice versa. These functions no not check their arguments.</para>
594
  </blockquote>
598
  </blockquote>
595
  <blockquote>
599
  <blockquote>
596
   <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>
600
   <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>
597
   <para>Converts a lisp fixnum to a C integer of the appropriate size. Signals an error
601
   <para>Converts a lisp fixnum to a C integer of the appropriate size. Signals an error
598
   if <replaceable>o</replaceable> is not of fixnum type.</para>
602
   if <replaceable>o</replaceable> is not of fixnum type.</para>
599
  </blockquote>
603
  </blockquote>
600
  <blockquote>
604
  <blockquote>
601
   <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>
605
   <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>
602
   <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
606
   <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
603
  </blockquote>
607
  </blockquote>
604
  <!--  -->
608
  <!--  -->
605
 </section>
609
 </section>
606
610
607
 <section id="Internals-Characters">
611
 <section xml:id="Internals-Characters">
608
  <title>Characters</title>
612
  <title>Characters</title>
609
  <para>&ECL; has only one type of characters, which fits in the C type <literal>char</literal>.
613
  <para>&ECL; has only one type of characters, which fits in the C type <literal>char</literal>.
610
  The following constants and functions operate on characters.</para>
614
  The following constants and functions operate on characters.</para>
611
  <blockquote>
615
  <blockquote>
612
   <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&mdash; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
616
   <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&#151; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
613
   <para>Each character is assigned an integer code which ranges from 0 to
617
   <para>Each character is assigned an integer code which ranges from 0 to
614
   (<replaceable>CHAR_CODE_LIMIT</replaceable>-1).</para>
618
   (<replaceable>CHAR_CODE_LIMIT</replaceable>-1).</para>
615
  </blockquote>
619
  </blockquote>
616
  <blockquote>
620
  <blockquote>
617
   <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>
621
   <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>
618
   <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>
622
   <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>
619
   <para>Returns the integer code associated to a lisp character. Only <literal>char_code</literal>
623
   <para>Returns the integer code associated to a lisp character. Only <literal>char_code</literal>
620
   checks its arguments.</para>
624
   checks its arguments.</para>
621
  </blockquote>
625
  </blockquote>
622
  <blockquote>
626
  <blockquote>
623
   <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>
627
   <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>
624
   <para>Returns the lisp character associated to an integer code. It does not check
628
   <para>Returns the lisp character associated to an integer code. It does not check
625
   its arguments.</para>
629
   its arguments.</para>
626
  </blockquote>
630
  </blockquote>
627
  <blockquote>
631
  <blockquote>
628
   <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>
632
   <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>
629
   <para>Coerces a lisp object to type character. Valid arguments are a character,
633
   <para>Coerces a lisp object to type character. Valid arguments are a character,
630
   or a string designator of length 1. In all other cases an error is signaled.</para>
634
   or a string designator of length 1. In all other cases an error is signaled.</para>
631
  </blockquote>
635
  </blockquote>
632
  <blockquote>
636
  <blockquote>
633
   <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>
637
   <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>
634
   <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>
638
   <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>
635
   <para>Compare two characters for equality. <literal>char_eq</literal> take case into account and
639
   <para>Compare two characters for equality. <literal>char_eq</literal> take case into account and
636
   <literal>char_equal</literal> ignores it.</para>
640
   <literal>char_equal</literal> ignores it.</para>
637
  </blockquote>
641
  </blockquote>
638
  <blockquote>
642
  <blockquote>
639
   <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>
643
   <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>
640
   <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>
644
   <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>
641
   <para>Compare the relative order of two characters. <literal>char_cmp</literal> takes care of
645
   <para>Compare the relative order of two characters. <literal>char_cmp</literal> takes care of
642
   case and <literal>char_compare</literal> converts all characters to uppercase before
646
   case and <literal>char_compare</literal> converts all characters to uppercase before
643
   comparing them.</para>
647
   comparing them.</para>
644
  </blockquote>
648
  </blockquote>
645
  <!--  -->
649
  <!--  -->
646
 </section>
650
 </section>
647
651
648
 <section id="Internals-Arrays">
652
 <section xml:id="Internals-Arrays">
649
  <title>Arrays</title>
653
  <title>Arrays</title>
650
  <para>An array is an aggregate of data of a common type, which can be accessed with
654
  <para>An array is an aggregate of data of a common type, which can be accessed with
651
  one or more nonnegative indices. &ECL; stores arrays as a C structure with a
655
  one or more nonnegative indices. &ECL; stores arrays as a C structure with a
652
  pointer to the region of memory which contains the actual data. The cell
656
  pointer to the region of memory which contains the actual data. The cell
653
  of an array datatype varies depending on whether it is a vector, a bytevector,
657
  of an array datatype varies depending on whether it is a vector, a bytevector,
...
...
770
     <para><literal>aet_df</literal></para>
774
     <para><literal>aet_df</literal></para>
771
    </listitem>
775
    </listitem>
772
   </varlistentry>
776
   </varlistentry>
773
  </variablelist>
777
  </variablelist>
774
  <blockquote>
778
  <blockquote>
775
   <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>
779
   <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>
776
   <para>Returns the element type of the array <replaceable>o</replaceable>, which can be a string, a
780
   <para>Returns the element type of the array <replaceable>o</replaceable>, which can be a string, a
777
   bitvector, vector, or a multidimensional array. For example, the code
781
   bitvector, vector, or a multidimensional array. For example, the code
778
   <literal>array_elttype(c_string_to_object("\"AAA\""))</literal> returns <literal>aet_ch</literal>,
782
   <literal>array_elttype(c_string_to_object("\"AAA\""))</literal> returns <literal>aet_ch</literal>,
779
   while the <literal>array_elttype(c_string_to_object("#(A B C)"))</literal> returns
783
   while the <literal>array_elttype(c_string_to_object("#(A B C)"))</literal> returns
780
   <literal>aet_object</literal>.</para>
784
   <literal>aet_object</literal>.</para>
781
  </blockquote>
785
  </blockquote>
782
  <blockquote>
786
  <blockquote>
783
   <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>
787
   <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>
784
   <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>
788
   <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>
785
   <para>These functions are used to retrieve and set the elements of an array. The
789
   <para>These functions are used to retrieve and set the elements of an array. The
786
   elements are accessed with one index, <replaceable>index</replaceable>, as in the lisp function
790
   elements are accessed with one index, <replaceable>index</replaceable>, as in the lisp function
787
   <literal>ROW-MAJOR-AREF</literal>. For example</para>
791
   <literal>ROW-MAJOR-AREF</literal>. For example</para>
788
   <screen>
792
   <screen>
789
    cl_object array = c_string_to_object("#2A((1 2) (3 4))");
793
    cl_object array = c_string_to_object("#2A((1 2) (3 4))");
...
...
792
    aset(array, 3, MAKE_FIXNUM(5));
796
    aset(array, 3, MAKE_FIXNUM(5));
793
    cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
797
    cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
794
   </screen>
798
   </screen>
795
  </blockquote>
799
  </blockquote>
796
  <blockquote>
800
  <blockquote>
797
   <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>
801
   <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>
798
   <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>
802
   <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>
799
   <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
803
   <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
800
   vectors.</para>
804
   vectors.</para>
801
   <screen>
805
   <screen>
802
    cl_object array = c_string_to_object("#(1 2 3 4)");
806
    cl_object array = c_string_to_object("#(1 2 3 4)");
803
    cl_object x = aref1(array, 3);
807
    cl_object x = aref1(array, 3);
...
...
807
   </screen>
811
   </screen>
808
  </blockquote>
812
  </blockquote>
809
  <!--  -->
813
  <!--  -->
810
 </section>
814
 </section>
811
815
812
 <section id="Internals-Strings">
816
 <section xml:id="Internals-Strings">
813
  <title>Strings</title>
817
  <title>Strings</title>
814
  <para>A string, both in Common-Lisp and in &ECL; is nothing but a vector of
818
  <para>A string, both in Common-Lisp and in &ECL; is nothing but a vector of
815
  characters. Therefore, almost everything mentioned in the section of arrays
819
  characters. Therefore, almost everything mentioned in the section of arrays
816
  remains valid here. The only important difference is that &ECL; stores
820
  remains valid here. The only important difference is that &ECL; stores
817
  strings as a lisp object with a pointer to a zero terminated C string. Thus, if
821
  strings as a lisp object with a pointer to a zero terminated C string. Thus, if
...
...
844
     <para>True if <literal>x-&gt;string.fillp</literal> can be smaller than <literal>x-&gt;string.dim</literal>.</para>
848
     <para>True if <literal>x-&gt;string.fillp</literal> can be smaller than <literal>x-&gt;string.dim</literal>.</para>
845
    </listitem>
849
    </listitem>
846
   </varlistentry>
850
   </varlistentry>
847
  </variablelist>
851
  </variablelist>
848
  <blockquote>
852
  <blockquote>
849
   <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>
853
   <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>
850
   <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>
854
   <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>
851
   <para>Both routines build a lisp string from a C string. <literal>make_string_copy</literal>
855
   <para>Both routines build a lisp string from a C string. <literal>make_string_copy</literal>
852
   allocates new space and copies the content of the string to
856
   allocates new space and copies the content of the string to
853
   it. <literal>make_simple_string</literal> simply uses the memory pointed by <replaceable>s</replaceable>, which
857
   it. <literal>make_simple_string</literal> simply uses the memory pointed by <replaceable>s</replaceable>, which
854
   should not be deallocated. Both routines use <literal>strlen</literal> to calculate the
858
   should not be deallocated. Both routines use <literal>strlen</literal> to calculate the
855
   length of the string.</para>
859
   length of the string.</para>
856
  </blockquote>
860
  </blockquote>
857
 </section>
861
 </section>
858
862
859
 <section id="Internals-Bitvectors">
863
 <section xml:id="Internals-Bitvectors">
860
  <title>Bitvectors</title>
864
  <title>Bitvectors</title>
861
 </section>
865
 </section>
862
866
863
 <section id="Internals-Streams">
867
 <section xml:id="Internals-Streams">
864
  <title>Streams</title>
868
  <title>Streams</title>
865
 </section>
869
 </section>
866
870
867
 <section id="Internals-Structures">
871
 <section xml:id="Internals-Structures">
868
  <title>Structures</title>
872
  <title>Structures</title>
869
 </section>
873
 </section>
870
874
871
 <section id="Internals-Instances">
875
 <section xml:id="Internals-Instances">
872
  <title>Instances</title>
876
  <title>Instances</title>
873
  <!--  -->
877
  <!--  -->
874
 </section>
878
 </section>
875
879
876
 <section id="Internals-Bytecodes">
880
 <section xml:id="Internals-Bytecodes">
877
  <title>Bytecodes</title>
881
  <title>Bytecodes</title>
878
  <para>A bytecodes object is a lisp object with a piece of code that can be
882
  <para>A bytecodes object is a lisp object with a piece of code that can be
879
  interpreted. The objects of type <literal>t_bytecode</literal> are implicitly constructed
883
  interpreted. The objects of type <literal>t_bytecode</literal> are implicitly constructed
880
  by a call to <literal>eval</literal>, but can also be explicitly constructed with the
884
  by a call to <literal>eval</literal>, but can also be explicitly constructed with the
881
  <literal>make_lambda</literal> function.</para>
885
  <literal>make_lambda</literal> function.</para>
882
  <blockquote>
886
  <blockquote>
883
   <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>
887
   <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>
884
   <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>
888
   <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>
885
   <para><literal>cl_safe_eval</literal> evaluates <replaceable>form</replaceable> in the lexical environment <replaceable>env</replaceable>,
889
   <para><literal>cl_safe_eval</literal> evaluates <replaceable>form</replaceable> in the lexical environment <replaceable>env</replaceable>,
886
   which can be <replaceable>nil</replaceable>. Before evaluating it, the expression <replaceable>form</replaceable> must
890
   which can be <replaceable>nil</replaceable>. Before evaluating it, the expression <replaceable>form</replaceable> must
887
   be bytecompiled. <literal>cl_eval</literal> is the equivalent of <literal>cl_safe_eval</literal> but
891
   be bytecompiled. <literal>cl_eval</literal> is the equivalent of <literal>cl_safe_eval</literal> but
888
   without environment and with <replaceable>err_value</replaceable> set to <replaceable>nil</replaceable>. It exists only
892
   without environment and with <replaceable>err_value</replaceable> set to <replaceable>nil</replaceable>. It exists only
889
   for compatibility with previous versions.</para>
893
   for compatibility with previous versions.</para>
...
...
892
    cl_safe_eval(form,Cnil);
896
    cl_safe_eval(form,Cnil);
893
    cl_safe_eval(form, Cnil);
897
    cl_safe_eval(form, Cnil);
894
   </screen>
898
   </screen>
895
  </blockquote>
899
  </blockquote>
896
  <blockquote>
900
  <blockquote>
897
   <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>
901
   <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>
898
   <para>Builds an interpreted lisp function with name given by the symbol <replaceable>name</replaceable>
902
   <para>Builds an interpreted lisp function with name given by the symbol <replaceable>name</replaceable>
899
   and body given by <replaceable>def</replaceable>. For instance, we would achieve the equivalent of</para>
903
   and body given by <replaceable>def</replaceable>. For instance, we would achieve the equivalent of</para>
900
   <programlisting>
904
   <programlisting>
901
    (funcall #'(lambda (x y) (block foo (+ x y)))
905
    (funcall #'(lambda (x y) (block foo (+ x y)))
902
    1 2)
906
    1 2)
...
...
920
  </blockquote>
924
  </blockquote>
921
  <!--  -->
925
  <!--  -->
922
 </section>
926
 </section>
923
</chapter>
927
</chapter>
924
928
925
<chapter id="Internals-the-interpreter">
929
<chapter xml:id="Internals-the-interpreter">
926
 <title>The interpreter</title>
930
 <title>The interpreter</title>
927
 <section id="Internals-ECL-stacks">
931
 <section xml:id="Internals-ECL-stacks">
928
  <title>&ECL; stacks</title>
932
  <title>&ECL; stacks</title>
929
  <para>&ECL; uses the following stacks:</para>
933
  <para>&ECL; uses the following stacks:</para>
930
  <variablelist>
934
  <variablelist>
931
   <varlistentry>
935
   <varlistentry>
932
    <term>Frame Stack</term>
936
    <term>Frame Stack</term>
...
...
955
    </listitem>
959
    </listitem>
956
   </varlistentry>
960
   </varlistentry>
957
  </variablelist>
961
  </variablelist>
958
 </section>
962
 </section>
959
963
960
 <section id="Internals-Procedure-Call-Conventions">
964
 <section xml:id="Internals-Procedure-Call-Conventions">
961
  <title>Procedure Call Conventions</title>
965
  <title>Procedure Call Conventions</title>
962
  <para>&ECL; employs standard C calling conventions to achieve efficiency and
966
  <para>&ECL; employs standard C calling conventions to achieve efficiency and
963
  interoperability with other languages.
967
  interoperability with other languages.
964
  Each Lisp function is implemented as a C function which takes as many
968
  Each Lisp function is implemented as a C function which takes as many
965
  argument as the Lisp original plus one additional integer argument
969
  argument as the Lisp original plus one additional integer argument
...
...
1003
   @(return CONS(car, cdr))
1007
   @(return CONS(car, cdr))
1004
   @)
1008
   @)
1005
  </screen>
1009
  </screen>
1006
 </section>
1010
 </section>
1007
1011
1008
 <section id="Internals-The-lexical-environment">
1012
 <section xml:id="Internals-The-lexical-environment">
1009
  <title>The lexical environment</title>
1013
  <title>The lexical environment</title>
1010
  <para>The &ECL; interpreter uses two A-lists (Association lists) to
1014
  <para>The &ECL; interpreter uses two A-lists (Association lists) to
1011
  represent lexical environments.</para>
1015
  represent lexical environments.</para>
1012
  <itemizedlist mark="bullet">
1016
  <itemizedlist mark="bullet">
1013
   <listitem>
1017
   <listitem>
...
...
1021
  saved in the closure along with the lambda expression.  Later, when the
1025
  saved in the closure along with the lambda expression.  Later, when the
1022
  closure is invoked, the saved A-lists are
1026
  closure is invoked, the saved A-lists are
1023
  used to recover the lexical environment.</para>
1027
  used to recover the lexical environment.</para>
1024
 </section>
1028
 </section>
1025
1029
1026
 <section id="Internals-The-interpreter-stack">
1030
 <section xml:id="Internals-The-interpreter-stack">
1027
  <title>The interpreter stack</title>
1031
  <title>The interpreter stack</title>
1028
  <para>The bytecodes interpreter uses a stack of its own to save and restore values
1032
  <para>The bytecodes interpreter uses a stack of its own to save and restore values
1029
  from intermediate calculations. This Forth-like data stack is also used in
1033
  from intermediate calculations. This Forth-like data stack is also used in
1030
  other parts of the C kernel for various purposes, such as saving compiled code,
1034
  other parts of the C kernel for various purposes, such as saving compiled code,
1031
  keeping arguments to FORMAT, etc.</para>
1035
  keeping arguments to FORMAT, etc.</para>
...
...
1114
  </screen></para>
1118
  </screen></para>
1115
  <!--  -->
1119
  <!--  -->
1116
 </section>
1120
 </section>
1117
</chapter>
1121
</chapter>
1118
1122
1119
<chapter id="Internals-the-compiler">
1123
<chapter xml:id="Internals-the-compiler">
1120
 <title>The compiler</title>
1124
 <title>The compiler</title>
1121
 <section id="Internals-The-compiler-translates-to-C">
1125
 <section xml:id="Internals-The-compiler-translates-to-C">
1122
  <title>The compiler translates to C</title>
1126
  <title>The compiler translates to C</title>
1123
  <para>The &ECL; compiler is essentially a translator from Common-Lisp to C.  Given
1127
  <para>The &ECL; compiler is essentially a translator from Common-Lisp to C.  Given
1124
  a Lisp source file, the compiler first generates three intermediate
1128
  a Lisp source file, the compiler first generates three intermediate
1125
  files:</para>
1129
  files:</para>
1126
  <itemizedlist mark="bullet">
1130
  <itemizedlist mark="bullet">
...
...
1172
    therefore slower than compiler generating machine code directly.</para>
1176
    therefore slower than compiler generating machine code directly.</para>
1173
   </listitem>
1177
   </listitem>
1174
  </itemizedlist>
1178
  </itemizedlist>
1175
 </section>
1179
 </section>
1176
1180
1177
 <section id="Internals-The-compiler-mimics-human-C-programmer">
1181
 <section xml:id="Internals-The-compiler-mimics-human-C-programmer">
1178
  <title>The compiler mimics human C programmer</title>
1182
  <title>The compiler mimics human C programmer</title>
1179
  <para>The format of the intermediate C code generated by the &ECL; compiler is the
1183
  <para>The format of the intermediate C code generated by the &ECL; compiler is the
1180
  same as the hand-coded C code of the &ECL; source programs.  For example,
1184
  same as the hand-coded C code of the &ECL; source programs.  For example,
1181
  supposing that the Lisp source file contains the
1185
  supposing that the Lisp source file contains the
1182
  following function definition:</para>
1186
  following function definition:</para>
...
...
1229
  <screen>
1233
  <screen>
1230
   #define VM 2
1234
   #define VM 2
1231
  </screen>
1235
  </screen>
1232
 </section>
1236
 </section>
1233
1237
1234
 <section id="Internals-Implementation-of-Compiled-Closures">
1238
 <section xml:id="Internals-Implementation-of-Compiled-Closures">
1235
  <title>Implementation of Compiled Closures</title>
1239
  <title>Implementation of Compiled Closures</title>
1236
  <para>The &ECL; compiler takes two passes before it invokes the C
1240
  <para>The &ECL; compiler takes two passes before it invokes the C
1237
  compiler.  The major role of the first pass is to detect function
1241
  compiler.  The major role of the first pass is to detect function
1238
  closures and to detect, for each function closure, those lexical
1242
  closures and to detect, for each function closure, those lexical
1239
  objects (i.e., lexical variable, local function definitions, tags, and
1243
  objects (i.e., lexical variable, local function definitions, tags, and
...
...
1242
  objects to be enclosed in function closures are treated in a different
1246
  objects to be enclosed in function closures are treated in a different
1243
  way from those not enclosed.</para>
1247
  way from those not enclosed.</para>
1244
  <para>Ordinarily, lexical variables in a compiled function <emphasis>f</emphasis>
1248
  <para>Ordinarily, lexical variables in a compiled function <emphasis>f</emphasis>
1245
  are allocated on the C stack.  However, if a lexical variable is
1249
  are allocated on the C stack.  However, if a lexical variable is
1246
  to be enclosed in function closures, it is allocated on a list, called
1250
  to be enclosed in function closures, it is allocated on a list, called
1247
  the &ldquo;environment list&rdquo;, which is local to <emphasis>f</emphasis>.  In addition, a
1251
  the “environment list”, which is local to <emphasis>f</emphasis>.  In addition, a
1248
  local variable is created which points to the lexical
1252
  local variable is created which points to the lexical
1249
  variable's location (within the environment list), so that
1253
  variable's location (within the environment list), so that
1250
  the variable may be accessed through an indirection rather than by list
1254
  the variable may be accessed through an indirection rather than by list
1251
  traversal.</para>
1255
  traversal.</para>
1252
  <para>The environment list is a pushdown list: It is empty when <emphasis>f</emphasis> is called.
1256
  <para>The environment list is a pushdown list: It is empty when <emphasis>f</emphasis> is called.
...
...
1297
  * : address of the compiled code for #'(lambda () (incf x))
1301
  * : address of the compiled code for #'(lambda () (incf x))
1298
  ** : address of the compiled code for #'(lambda () (incf x y))
1302
  ** : address of the compiled code for #'(lambda () (incf x y))
1299
  ]]></screen>
1303
  ]]></screen>
1300
 </section>
1304
 </section>
1301
1305
1302
 <section id="Internals-Use-of-Declarations-to-Improve-Efficiency">
1306
 <section xml:id="Internals-Use-of-Declarations-to-Improve-Efficiency">
1303
  <title>Use of Declarations to Improve Efficiency</title>
1307
  <title>Use of Declarations to Improve Efficiency</title>
1304
  <para>Declarations, especially  type  and  function  declarations,
1308
  <para>Declarations, especially  type  and  function  declarations,
1305
  increase the efficiency of the compiled code.  For example, for the
1309
  increase the efficiency of the compiled code.  For example, for the
1306
  following Lisp source file, with two Common-Lisp declarations added,</para>
1310
  following Lisp source file, with two Common-Lisp declarations added,</para>
1307
  <programlisting>
1311
  <programlisting>
...
...
1337
   ;;; Note: Tail-recursive call of TAK was replaced by iteration.
1341
   ;;; Note: Tail-recursive call of TAK was replaced by iteration.
1338
   }
1342
   }
1339
  </screen>
1343
  </screen>
1340
 </section>
1344
 </section>
1341
1345
1342
 <section id="Internals-Inspecting-generated-C-code">
1346
 <section xml:id="Internals-Inspecting-generated-C-code">
1343
  <title>Inspecting generated C code</title>
1347
  <title>Inspecting generated C code</title>
1344
  <para>Common-Lisp defines a function disassemble, which is
1348
  <para>Common-Lisp defines a function disassemble, which is
1345
  supposed to disassemble a compiled function and to display the
1349
  supposed to disassemble a compiled function and to display the
1346
  assembler code.  According to <emphasis>Common-Lisp: The Language</emphasis>,</para>
1350
  assembler code.  According to <emphasis>Common-Lisp: The Language</emphasis>,</para>
1347
  
1351
  
...
...
1368
   }
1372
   }
1369
  </screen></para>
1373
  </screen></para>
1370
 </section>
1374
 </section>
1371
</chapter>
1375
</chapter>
1372
1376
1373
<chapter id="Porting-ECL">
1377
<chapter xml:id="Porting-ECL">
1374
 <title>Porting &ECL;</title>
1378
 <title>Porting &ECL;</title>
1375
 <para>To port &ECL; to a new architecture, the following steps are required:</para>
1379
 <para>To port &ECL; to a new architecture, the following steps are required:</para>
1376
 <orderedlist numeration="arabic">
1380
 <orderedlist numeration="arabic">
1377
  <listitem>
1381
  <listitem>
1378
   <para>Ensure that the GNU Multiprecision library supports this machine.</para>
1382
   <para>Ensure that the GNU Multiprecision library supports this machine.</para>