mirror of
https://gitlab.com/embeddable-common-lisp/ecl.git
synced 2026-01-21 12:03:40 -08:00
doc: verify "1. Overview", wrap some lines to 75 characters
Signed-off-by: Daniel Kochmański <daniel@turtleware.eu>
This commit is contained in:
Daniel Kochmański
parent
a7a217afc2
commit
17a912d8b4
1 changed files with 74 additions and 15 deletions
|
|
@ -13,7 +13,13 @@
|
|||
<section>
|
||||
<title>Common Lisp users</title>
|
||||
|
||||
<para>&ECL; supports all Common-Lisp data types exactly as defined in the &ANSI;. All functions and macros are expected to behave as described in that document and in the HyperSpec &HyperSpec; which is the online version of &ANSI;. In other words, the Standard is the basic reference for Common Lisp and also for &ECL;, and this first part of the book just complements it, describing implementation-specific features such as
|
||||
<para>&ECL; supports all Common-Lisp data types exactly as defined
|
||||
in the &ANSI;. All functions and macros are expected to behave as
|
||||
described in that document and in the HyperSpec &HyperSpec; which
|
||||
is the online version of &ANSI;. In other words, the Standard is
|
||||
the basic reference for Common Lisp and also for &ECL;, and this
|
||||
first part of the book just complements it, describing
|
||||
implementation-specific features such as
|
||||
<itemizedlist>
|
||||
<listitem><para>Platform dependent limits.</para></listitem>
|
||||
<listitem><para>Behavior which is marked as <quote>implementation specific</quote> in the standard.</para></listitem>
|
||||
|
|
@ -22,18 +28,36 @@
|
|||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>In order to aid in locating these differences, this first part of the manual copies the structure of the &ANSI; standard, having the same number of chapters, each one with a set of sections documenting the implementation-specific details.</para>
|
||||
<para>In order to aid in locating these differences, this first
|
||||
part of the manual copies the structure of the &ANSI; standard,
|
||||
having the same number of chapters, each one with a set of sections
|
||||
documenting the implementation-specific details.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>C/C++ programmers</title>
|
||||
|
||||
<para>The second goal of this document is to provide a reference for C programmers that want to create, manipulate and operate with Common Lisp programs at a lower level, or simply embedding &ECL; as a library.</para>
|
||||
<para>The second goal of this document is to provide a reference
|
||||
for C programmers that want to create, manipulate and operate with
|
||||
Common Lisp programs at a lower level, or simply embedding &ECL; as
|
||||
a library.</para>
|
||||
|
||||
<para>The C/C++ reference evolves in parallel with the Common Lisp one, in the form of one section with the name "C Reference" for each chapter of the &ANSI; standard. Much of what is presented in those sections is redundant with the Common Lisp specification. In particular, there is a one-to-one mapping between types and functions which should be obvious given the rules explained in <xref linkend="ansi.overview.c-dict"/>.</para>
|
||||
<para>The C/C++ reference evolves in parallel with the Common Lisp
|
||||
one, in the form of one section with the name "C Reference" for
|
||||
each chapter of the &ANSI; standard. Much of what is presented in
|
||||
those sections is redundant with the Common Lisp specification. In
|
||||
particular, there is a one-to-one mapping between types and
|
||||
functions which should be obvious given the rules explained in
|
||||
<xref linkend="ansi.overview.c-dict"/>.</para>
|
||||
|
||||
<para>We must remark that the reference in this part of the manual is not enough to know how to embed &ECL; in a program. In practice the user or developer will also have to learn how to <link linkend="ext.asdf">build programs</link>, <link linkend="ext.ffi">interface with foreign libraries</link>, <link linkend="ext.memory">manage memory</link>, etc. These concepts are explained in a different part of the book.</para>
|
||||
<para>We must remark that the reference in this part of the manual
|
||||
is not enough to know how to embed &ECL; in a program. In practice
|
||||
the user or developer will also have to learn how to <link
|
||||
linkend="ext.asdf">build programs</link>, <link
|
||||
linkend="ext.ffi">interface with foreign libraries</link>, <link
|
||||
linkend="ext.memory">manage memory</link>, etc. These concepts are
|
||||
explained in a different part of the book.</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
|
@ -43,15 +67,37 @@
|
|||
<section xml:id="cl_object">
|
||||
<title>One type for everything: <type>cl_object</type></title>
|
||||
|
||||
<para>&ECL; is designed around the basic principle that Common Lisp already provides everything that a programmer could need, orienting itself around the creation and manipulation of Common Lisp objects: conses, arrays, strings, characters, ... When embedding &ECL; there should be no need to use other C/C++ types, except when interfacing data to and from those other languages.</para>
|
||||
<para>&ECL; is designed around the basic principle that Common Lisp
|
||||
already provides everything that a programmer could need, orienting
|
||||
itself around the creation and manipulation of Common Lisp objects:
|
||||
conses, arrays, strings, characters, ... When embedding &ECL; there
|
||||
should be no need to use other C/C++ types, except when interfacing
|
||||
data to and from those other languages.</para>
|
||||
|
||||
<para>All Common Lisp objects are represented internally through the same C type, <type>cl_object</type>, which is either a pointer to a union type or an integer, depending on the situation. While the inner guts of this type are exposed through various headers, the user should never rely on these details but rather use the macros and functions that are listed in this manual</para>
|
||||
<para>All Common Lisp objects are represented internally through
|
||||
the same C type, <type>cl_object</type>, which is either a pointer
|
||||
to a union type or an integer, depending on the situation. While
|
||||
the inner guts of this type are exposed through various headers,
|
||||
the user should never rely on these details but rather use the
|
||||
macros and functions that are listed in this manual</para>
|
||||
|
||||
<para>There are two types of Common Lisp objects: immediate and memory allocated ones. Immediate types fit in the bits of the <type>cl_object</type> word, and do not require the garbage collector to be created. The list of such types may depend on the platform, but it includes at least the <type>fixnum</type> and <type>character</type> types.</para>
|
||||
<para>There are two types of Common Lisp objects: immediate and
|
||||
memory allocated ones. Immediate types fit in the bits of the
|
||||
<type>cl_object</type> word, and do not require the garbage
|
||||
collector to be created. The list of such types may depend on the
|
||||
platform, but it includes at least the <type>fixnum</type> and
|
||||
<type>character</type> types.</para>
|
||||
|
||||
<para>Memory allocated types on the other hand require the use of the garbage collector to be created. &ECL; abstracts this from the user providing enough constructors, either in the form of Common Lisp functions (<function>cl_make_array()</function>, <function>cl_complex()</function>,...), or in the form of C/C++ constructors (<function>ecl_make_symbol()</function>, etc).</para>
|
||||
<para>Memory allocated types on the other hand require the use of
|
||||
the garbage collector to be created. &ECL; abstracts this from the
|
||||
user providing enough constructors, either in the form of Common
|
||||
Lisp functions (<function>cl_make_array()</function>,
|
||||
<function>cl_complex()</function>,...), or in the form of C/C++
|
||||
constructors (<function>ecl_make_symbol()</function>, etc).</para>
|
||||
|
||||
<para>Memory allocated types must always be kept alive so that the garbage collector does not reclaim them. This involves referencing the object from one of the places that the collector scans:
|
||||
<para>Memory allocated types must always be kept alive so that the
|
||||
garbage collector does not reclaim them. This involves referencing
|
||||
the object from one of the places that the collector scans:
|
||||
<itemizedlist>
|
||||
<listitem><para>The fields of an object (array, structure, etc) whic is itself alive.</para></listitem>
|
||||
<listitem><para>A special variable or a constant.</para></listitem>
|
||||
|
|
@ -64,7 +110,10 @@
|
|||
<section>
|
||||
<title>Naming conventions</title>
|
||||
|
||||
<para>As explained in the introduction, each of the chapters in the Common Lisp standard can also be implemented using C functions and types. The mapping between both languages is done using a small set of rules described below.</para>
|
||||
<para>As explained in the introduction, each of the chapters in the
|
||||
Common Lisp standard can also be implemented using C functions and
|
||||
types. The mapping between both languages is done using a small set
|
||||
of rules described below.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Functions in the Common Lisp ("CL") package are prefixed with the characters "cl_", functions in the System ("SI") package are prefix with "si_", etc, etc.</para></listitem>
|
||||
<listitem><para>If a function takes only a fixed number of arguments, it is mapped to a C function with also a fixed number of arguments. For instance, <symbol>COS</symbol> maps to <code>cl_object cl_cos(cl_object)</code>, which takes a single Lisp object and returns a Lisp object of type <type>FLOAT</type>.</para></listitem>
|
||||
|
|
@ -77,7 +126,12 @@
|
|||
<section xml:id="ansi.OCL">
|
||||
<title>Only in Common Lisp</title>
|
||||
|
||||
<para>Some parts of the language are not available as C functions, even though they can be used in Common Lisp programs. These parts are either marked in the "ANSI Dictionary" sections using the tag &OCL;, or they are simply not mentioned (macros and special constructs). This typically happens with non-translatable constructs such as</para>
|
||||
<para>Some parts of the language are not available as C functions,
|
||||
even though they can be used in Common Lisp programs. These parts
|
||||
are either marked in the "ANSI Dictionary" sections using the tag
|
||||
&OCL;, or they are simply not mentioned (macros and special
|
||||
constructs). This typically happens with non-translatable
|
||||
constructs such as</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Common Lisp macros such as <symbol>with-open-files</symbol>.</para></listitem>
|
||||
<listitem><para>Common Lisp special forms, such as <symbol>cond</symbol></para></listitem>
|
||||
|
|
@ -94,14 +148,19 @@ CL_UNWIND_PROTECT_BEGIN(env) {
|
|||
} CL_UNWIND_PROTECT_END;
|
||||
</programlisting>
|
||||
|
||||
<para>Common Lisp generic functions can be directly accessed using <symbol>funcall</symbol> or <symbol>apply</symbol> and the function name, as shown in the code below</para>
|
||||
<para>Common Lisp generic functions can be directly accessed using
|
||||
<symbol>funcall</symbol> or <symbol>apply</symbol> and the function
|
||||
name, as shown in the code below</para>
|
||||
<programlisting>
|
||||
cl_object name = ecl_make_symbol("MY-GENERIC-FUNCTION","CL-USER");
|
||||
cl_object output = cl_funcall(2, name, argument);
|
||||
</programlisting>
|
||||
|
||||
<para>Identifying these alternatives requires some knowledge of Common Lisp, which is why it is recommended to approach the embeddable components in &ECL; only when there is some familiarity with the language.</para>
|
||||
<para>Identifying these alternatives requires some knowledge of
|
||||
Common Lisp, which is why it is recommended to approach the
|
||||
embeddable components in &ECL; only when there is some familiarity
|
||||
with the language.</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
</book>
|
||||
</book>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue