343 lines
15 KiB
HTML
343 lines
15 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<title>Overview (ECL Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Overview (ECL Manual)">
|
||
|
|
<meta name="keywords" content="Overview (ECL Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Indexes.html" rel="index" title="Indexes">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Standards.html" rel="up" title="Standards">
|
||
|
|
<link href="Evaluation-and-compilation.html" rel="next" title="Evaluation and compilation">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
/* colors */
|
||
|
|
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span.r {font-family: initial; font-weight: normal; font-style: normal}
|
||
|
|
ul.mark-bullet {list-style-type: disc}
|
||
|
|
@media (prefers-color-scheme: dark) {
|
||
|
|
/* dark theme */
|
||
|
|
html { color: seashell;
|
||
|
|
background: #1A1A1A; }
|
||
|
|
body { background: #1A1A1A; }
|
||
|
|
th { border-bottom: 2px solid lightgray; }
|
||
|
|
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
|
||
|
|
code, var, code a { color: darkorange;
|
||
|
|
background: #2A2A2A; }
|
||
|
|
a { color: seashell; }
|
||
|
|
pre { background: #2A2A2A;
|
||
|
|
color: seashell;
|
||
|
|
/* mark longer code block with stripe on the left */
|
||
|
|
border-left: 5px solid darkorange;
|
||
|
|
padding-left: 10px; }
|
||
|
|
pre.screen { background: #2A2A2A;
|
||
|
|
border: 1px solid lightgray; }
|
||
|
|
pre.programlisting { background: #2A2A2A;
|
||
|
|
border-left: 1px solid lightgray;
|
||
|
|
border-top: 1px solid lightgray; }
|
||
|
|
/* we need a light background in order for the images to be readable */
|
||
|
|
img { background: white }
|
||
|
|
}
|
||
|
|
@media (prefers-color-scheme: light) {
|
||
|
|
/* light theme */
|
||
|
|
html { background: white }
|
||
|
|
body { background: white }
|
||
|
|
th { border-bottom: 2px solid gray; }
|
||
|
|
h1, h2, h3, h4, h5 { background: lightgray; }
|
||
|
|
code, var, code a { color: darkred;
|
||
|
|
background: whitesmoke; }
|
||
|
|
a { color: #000; }
|
||
|
|
pre { background: whitesmoke;
|
||
|
|
color: black;
|
||
|
|
/* mark longer code block with stripe on the left */
|
||
|
|
border-left: 5px solid darkred;
|
||
|
|
padding-left: 10px; }
|
||
|
|
pre.screen { background: #EEE;
|
||
|
|
border: 1px solid black; }
|
||
|
|
pre.programlisting { background: #EEEEEE;
|
||
|
|
border-left: 1px solid black;
|
||
|
|
border-top: 1px solid black; }
|
||
|
|
}
|
||
|
|
|
||
|
|
body {
|
||
|
|
margin: 1em 125px 0 10%;
|
||
|
|
line-height: 1.5em;
|
||
|
|
padding: 0 2em 1em 2em;
|
||
|
|
font: 13px Verdana,Arial, sans-serif
|
||
|
|
}
|
||
|
|
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
|
||
|
|
p, code, td, dl, dt {
|
||
|
|
line-height: 1.5em;
|
||
|
|
}
|
||
|
|
table {
|
||
|
|
font: inherit;
|
||
|
|
border-collapse: collapse;
|
||
|
|
}
|
||
|
|
th, td {
|
||
|
|
vertical-align: top;
|
||
|
|
}
|
||
|
|
h1, h2, h3 { padding-left: 15px; }
|
||
|
|
h4, h5 { padding-left: 5px; }
|
||
|
|
code, pre {
|
||
|
|
font-size: 1em;
|
||
|
|
font-family: monospace;
|
||
|
|
}
|
||
|
|
var {
|
||
|
|
font-size: 1em;
|
||
|
|
}
|
||
|
|
/* links inside code appear the same as the code itself */
|
||
|
|
code a {
|
||
|
|
font-weight: normal;
|
||
|
|
text-decoration: none;
|
||
|
|
}
|
||
|
|
/* but get an underline when hovering */
|
||
|
|
code a:hover {
|
||
|
|
text-decoration: underline;
|
||
|
|
}
|
||
|
|
/* ordinary links appear in bold */
|
||
|
|
a { font-weight: bold; }
|
||
|
|
pre.verbatim {
|
||
|
|
margin: 0 0 0 0;
|
||
|
|
}
|
||
|
|
pre {
|
||
|
|
overflow: auto;
|
||
|
|
}
|
||
|
|
pre.screen {
|
||
|
|
font-weight: bold;
|
||
|
|
padding: 0.5em;
|
||
|
|
}
|
||
|
|
pre.programlisting {
|
||
|
|
padding: 0.5em;
|
||
|
|
}
|
||
|
|
div p { padding: 0 2em }
|
||
|
|
li p { padding: 0; margin: 0 }
|
||
|
|
hr { display: none; }
|
||
|
|
div.funcsynopsis p {
|
||
|
|
text-indent: -2em;
|
||
|
|
}
|
||
|
|
div.variablelist {
|
||
|
|
padding: 0 2em;
|
||
|
|
}
|
||
|
|
.type, .funcsynopsis, .symbol {
|
||
|
|
font-family: monospace;
|
||
|
|
}
|
||
|
|
.type, .symbol, .replaceable {
|
||
|
|
white-space: nowrap;
|
||
|
|
}
|
||
|
|
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="section-level-extent" id="Overview">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Evaluation-and-compilation.html" accesskey="n" rel="next">Evaluation and compilation</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<h3 class="section" id="Overview-1">2.1 Overview</h3>
|
||
|
|
|
||
|
|
<ul class="mini-toc">
|
||
|
|
<li><a href="Overview.html#Reading-this-manual" accesskey="1">Reading this manual</a></li>
|
||
|
|
<li><a href="Overview.html#C-Reference-1" accesskey="2">C Reference</a></li>
|
||
|
|
</ul>
|
||
|
|
<div class="subsection-level-extent" id="Reading-this-manual">
|
||
|
|
<h4 class="subsection">2.1.1 Reading this manual</h4>
|
||
|
|
|
||
|
|
<h4 class="subsubheading" id="Common-Lisp-users">Common Lisp users</h4>
|
||
|
|
<p><b class="b"><span class="r">Embeddable Common Lisp</span></b> supports all Common-Lisp data types exactly as defined in the
|
||
|
|
[see <a class="pxref" href="Bibliography.html">ANSI</a>]. All functions and macros are expected to behave as
|
||
|
|
described in that document and in the HyperSpec [see <a class="pxref" href="Bibliography.html">HyperSpec</a>]
|
||
|
|
which is the online version of [see <a class="pxref" href="Bibliography.html">ANSI</a>]. In other words, the
|
||
|
|
Standard is the basic reference for Common Lisp and also for <b class="b"><span class="r">Embeddable Common Lisp</span></b>,
|
||
|
|
and this part of the manual just complements it, describing
|
||
|
|
implementation-specific features such as:
|
||
|
|
</p>
|
||
|
|
<ul class="itemize mark-bullet">
|
||
|
|
<li>Platform dependent limits.
|
||
|
|
</li><li>Behavior which is marked as <em class="emph">implementation specific</em> in the
|
||
|
|
standard.
|
||
|
|
</li><li>Some corner cases which are not described in [see <a class="pxref" href="Bibliography.html">ANSI</a>].
|
||
|
|
</li><li>The philosophy behind certain implementation choices, etc.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>In order to aid in locating these differences, this first part of
|
||
|
|
the manual copies the structure of the <span class="r">ANSI Common-Lisp</span> standard, having
|
||
|
|
the same number of chapters, each one with a set of sections
|
||
|
|
documenting the implementation-specific details.
|
||
|
|
</p>
|
||
|
|
<h4 class="subsubheading" id="C_002fC_002b_002b-programmers">C/C++ programmers</h4>
|
||
|
|
<p>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 <b class="b"><span class="r">Embeddable Common Lisp</span></b> as a library.
|
||
|
|
</p>
|
||
|
|
<p>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
|
||
|
|
<span class="r">ANSI Common-Lisp</span> 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 <em class="emph">C Reference</em>.
|
||
|
|
</p>
|
||
|
|
<p>We must remark that the reference in this part of the manual is not
|
||
|
|
enough to know how to embed <b class="b"><span class="r">Embeddable Common Lisp</span></b> in a program. In practice the user or
|
||
|
|
developer will also have to learn how to build programs (<a class="ref" href="System-building.html#System-building">System building</a>), interface with foreign libraries (<a class="ref" href="Foreign-Function-Interface.html#Foreign-Function-Interface">Foreign Function Interface</a>), manage memory (<a class="ref" href="Memory-Management.html#Memory-Management">Memory Management</a>), etc. These
|
||
|
|
concepts are explained in a different (<a class="ref" href="Embedding-ECL.html#Embedding-ECL">Embedding ECL</a>) part of the
|
||
|
|
book.
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<div class="subsection-level-extent" id="C-Reference-1">
|
||
|
|
<h4 class="subsection">2.1.2 C Reference</h4>
|
||
|
|
<h4 class="subsubheading" id="One-type-for-everything_003a-cl_005fobject">One type for everything: <code class="code">cl_object</code></h4>
|
||
|
|
<a class="index-entry-id" id="index-One-type-for-everything_003a-cl_005fobject"></a>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<p>All Common Lisp objects are represented internally through the same C
|
||
|
|
type, <code class="code">cl_object</code>, 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.
|
||
|
|
</p>
|
||
|
|
<p>There are two types of Common Lisp objects: immediate and memory
|
||
|
|
allocated ones. Immediate types fit in the bits of the <code class="code">cl_object</code>
|
||
|
|
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 class="code">fixnum</code> and <code class="code">character</code> types.
|
||
|
|
</p>
|
||
|
|
<p>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 class="code">cl_make_array</code>, <code class="code">cl_complex</code>,...), or in the form of
|
||
|
|
C/C++ constructors (<code class="code"><a class="ref" href="Symbols.html#ecl_005fmake_005fsymbol">ecl_make_symbol</a></code>, etc).
|
||
|
|
</p>
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<ul class="itemize mark-bullet">
|
||
|
|
<li>The fields of an object (array, structure, etc) which is itself
|
||
|
|
alive.
|
||
|
|
</li><li>A special variable or a constant.
|
||
|
|
</li><li>The C stack (i.e. automatic variables in a function).
|
||
|
|
</li><li>Global variables or pointers that have been registered with the garbage
|
||
|
|
collector.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>For memory allocation details See <a class="xref" href="Memory-Management.html#Memory-Management">Memory Management</a>.
|
||
|
|
For object implementation details See <a class="xref" href="Manipulating-Lisp-objects.html#Manipulating-Lisp-objects">Manipulating Lisp objects</a>.
|
||
|
|
</p>
|
||
|
|
<h4 class="subsubheading" id="Naming-conventions">Naming conventions</h4>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<ul class="itemize mark-bullet">
|
||
|
|
<li>Functions in the Common Lisp (<code class="code">cl</code>) package are prefixed with the
|
||
|
|
characters <code class="code">cl_</code>, functions in the System (<code class="code">si</code>) and
|
||
|
|
Extensions (<code class="code">ext</code>) package are prefix with <code class="code">si_</code>, etc, etc.
|
||
|
|
|
||
|
|
</li><li>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 class="code">cos</code> maps to <code class="code">cl_object cl_cos(cl_object)</code>, which takes a
|
||
|
|
single Lisp object and returns a Lisp object of type <code class="code">float</code>.
|
||
|
|
|
||
|
|
</li><li>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 class="code">cl_object cl_list(cl_narg narg, ...)</code>, which can be invoked
|
||
|
|
without arguments, as in <code class="code">cl_list(0)</code>, with one, <code class="code">cl_list(1,
|
||
|
|
a)</code>, etc.
|
||
|
|
|
||
|
|
</li><li>Functions return at least one value, which is either the first value
|
||
|
|
output by the function, or <code class="code">nil</code>. The extra values may be retrieved
|
||
|
|
immediately after the function call using the function
|
||
|
|
<code class="code"><a class="ref" href="Data-and-control-flow.html#ecl_005fnth_005fvalue">ecl_nth_value</a></code>.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>In addition to the Common Lisp core functions (<code class="code">cl_*</code>), 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 class="code">ecl_</code> or <code class="code">ECL_</code> and only return one value, if any.
|
||
|
|
</p>
|
||
|
|
<a class="index-entry-id" id="index-ANSI-Dictionary"></a>
|
||
|
|
<p>Most (if not all) Common Lisp functions and constructs available from
|
||
|
|
C/C++ are available in “ANSI Dictionary” sections which are part of
|
||
|
|
the [<a class="ref" href="Standards.html">Standards</a>] entries.
|
||
|
|
</p>
|
||
|
|
<h4 class="subsubheading" id="Only-in-Common-Lisp">Only in Common Lisp</h4>
|
||
|
|
<a class="index-entry-id" id="index-Only-in-Common-Lisp"></a>
|
||
|
|
|
||
|
|
<p>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 <em class="emph">Only in Common Lisp</em>, or they are
|
||
|
|
simply not mentioned (macros and special constructs). This typically
|
||
|
|
happens with non-translatable constructs such as
|
||
|
|
</p>
|
||
|
|
<ul class="itemize mark-bullet">
|
||
|
|
<li>Common Lisp macros such as <code class="code">with-open-files</code>
|
||
|
|
|
||
|
|
</li><li>Common Lisp special forms, such as <code class="code">cond</code>
|
||
|
|
|
||
|
|
</li><li>Common Lisp generic functions, which cannot be written in C because of
|
||
|
|
their dynamical dispatch and automatic redefinition properties.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>In most of those cases there exist straightforward alternatives using
|
||
|
|
the constructs and functions in ECL. For example, <code class="code">unwind-protect</code>
|
||
|
|
can be implemented using a C macro which is provided by ECL
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="verbatim">cl_env_ptr env = ecl_process_env();
|
||
|
|
ECL_UNWIND_PROTECT_BEGIN(env) {
|
||
|
|
/* protected code goes here */
|
||
|
|
} ECL_UNWIND_PROTECT_EXIT {
|
||
|
|
/* exit code goes here */
|
||
|
|
} ECL_UNWIND_PROTECT_END;
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Common Lisp generic functions can be directly accessed using
|
||
|
|
<code class="code">funcall</code> or <code class="code">apply</code> and the function name, as shown in the
|
||
|
|
code below
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">cl_object name = ecl_make_symbol("MY-GENERIC-FUNCTION","CL-USER");
|
||
|
|
cl_object output = cl_funcall(2, name, argument);
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Evaluation-and-compilation.html" accesskey="n" rel="next">Evaluation and compilation</a>, Up: <a href="Standards.html" accesskey="u" rel="up">Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|