193 lines
7.5 KiB
Text
193 lines
7.5 KiB
Text
@node Overview
|
|
@section Overview
|
|
|
|
@subsection Reading this manual
|
|
|
|
@subsubheading Common Lisp users
|
|
@ecl{} supports all Common-Lisp data types exactly as defined in the
|
|
@bibcite{ANSI}. All functions and macros are expected to behave as
|
|
described in that document and in the HyperSpec @bibcite{HyperSpec}
|
|
which is the online version of @bibcite{ANSI}. In other words, the
|
|
Standard is the basic reference for Common Lisp and also for @ecl{},
|
|
and this part of the manual just complements it, describing
|
|
implementation-specific features such as:
|
|
|
|
@itemize
|
|
@item
|
|
Platform dependent limits.
|
|
@item
|
|
Behavior which is marked as @emph{implementation specific} in the
|
|
standard.
|
|
@item
|
|
Some corner cases which are not described in @bibcite{ANSI}.
|
|
@item
|
|
The philosophy behind certain implementation choices, etc.
|
|
@end itemize
|
|
|
|
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.
|
|
|
|
@subsubheading C/C++ programmers
|
|
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.
|
|
|
|
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 the next section @emph{C Reference}.
|
|
|
|
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 build programs (@ref{System
|
|
building}), interface with foreign libraries (@ref{Foreign Function
|
|
Interface}), manage memory (@ref{Memory Management}), etc. These
|
|
concepts are explained in a different (@ref{Embedding ECL}) part of the
|
|
book.
|
|
|
|
@subsection C Reference
|
|
@subsubheading One type for everything: @code{cl_object}
|
|
@cindex One type for everything: @code{cl_object}
|
|
|
|
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.
|
|
|
|
All Common Lisp objects are represented internally through the same C
|
|
type, @code{cl_object}, 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.
|
|
|
|
There are two types of Common Lisp objects: immediate and memory
|
|
allocated ones. Immediate types fit in the bits of the @code{cl_object}
|
|
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
|
|
@code{fixnum} and @code{character} types.
|
|
|
|
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
|
|
(@code{cl_make_array()}, @code{cl_complex()},...), or in the form of
|
|
C/C++ constructors (@code{ecl_make_symbol()}, etc).
|
|
|
|
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:
|
|
|
|
@itemize
|
|
@item
|
|
The fields of an object (array, structure, etc) which is itself
|
|
alive.
|
|
@item
|
|
A special variable or a constant.
|
|
@item
|
|
The C stack (i.e. automatic variables in a function).
|
|
@item
|
|
Global variables or pointers that have been registered with the garbage
|
|
collector.
|
|
@end itemize
|
|
|
|
For memory allocation details @xref{Memory Management}.
|
|
For object implementation details @xref{Manipulating Lisp objects}.
|
|
|
|
@subsubheading Naming conventions
|
|
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.
|
|
|
|
@itemize
|
|
@item
|
|
Functions in the Common Lisp (@code{CL}) package are prefixed with the
|
|
characters @code{cl_}, functions in the System (@code{SI}) package are
|
|
prefix with @code{si_}, etc, etc.
|
|
|
|
@item
|
|
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,
|
|
@code{COS} maps to @code{cl_object cl_cos(cl_object)}, which takes a
|
|
single Lisp object and returns a Lisp object of type @code{FLOAT}.
|
|
|
|
@item
|
|
If the function takes a variable number of arguments, its signature
|
|
consists on an integer with the number of arguments and zero or more of
|
|
required arguments and then a C vararg. This is the case of
|
|
@code{cl_object cl_list(cl_narg narg, ...)}, which can be invoked
|
|
without arguments, as in @code{cl_list(0)}, with one, @code{cl_list(1,
|
|
a)}, etc.
|
|
|
|
@item
|
|
Functions return at least one value, which is either the first value
|
|
output by the function, or @code{NIL}. The extra values may be retrieved
|
|
immediately after the function call using the function
|
|
@code{ecl_nth_value}.
|
|
@end itemize
|
|
|
|
In addition to the Common Lisp core functions (@code{cl_*}), there exist
|
|
functions which are devoted only to C/C++ programming, with tasks such
|
|
as coercion of objects to and from C types, optimized functions, inlined
|
|
macroexpansions, etc. These functions and macros typically carry the
|
|
prefix @code{ecl_} or @code{ECL_} and only return one value, if any.
|
|
|
|
@cindex ANSI Dictionary
|
|
Most (if not all) Common Lisp functions and constructs available from
|
|
C/C++ are available in ``ANSI Dictionary'' sections which are part of
|
|
the [@ref{Standards}] entries.
|
|
|
|
@subsubheading Only in Common Lisp
|
|
@cindex Only in Common Lisp
|
|
|
|
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
|
|
|
|
@itemize
|
|
@item
|
|
Common Lisp macros such as @code{with-open-files}
|
|
|
|
@item
|
|
Common Lisp special forms, such as @code{cond}
|
|
|
|
@item
|
|
Common Lisp generic functions, which cannot be written in C because of
|
|
their dynamical dispatch and automatic redefinition properties.
|
|
@end itemize
|
|
|
|
In most of those cases there exist straightforward alternatives using
|
|
the constructs and functions in ECL. For example, @code{unwind-protect}
|
|
can be implemented using a C macro which is provided by ECL
|
|
|
|
@example
|
|
@verbatim
|
|
cl_env_ptr env = ecl_process_env();
|
|
CL_UNWIND_PROTECT_BEGIN(env) {
|
|
/* protected code goes here */
|
|
} CL_UNWIND_PROTECT_EXIT {
|
|
/* exit code goes here */
|
|
} CL_UNWIND_PROTECT_END;
|
|
@end verbatim
|
|
@end example
|
|
|
|
Common Lisp generic functions can be directly accessed using
|
|
@code{funcall} or @code{apply} and the function name, as shown in the
|
|
code below
|
|
|
|
@example
|
|
cl_object name = ecl_make_symbol("MY-GENERIC-FUNCTION","CL-USER");
|
|
cl_object output = cl_funcall(2, name, argument);
|
|
@end example
|
|
|
|
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.
|