Commit 0b0c7594 authored by Marius Gerbershagen's avatar Marius Gerbershagen

doc: improvements to developer's guide

    Document the defun preprocessor, remove use of deprecated names,
    fix errors and typos.
parent 2575218c
......@@ -40,8 +40,7 @@
*
* } @)
*
* name can be either an identifier or a full C procedure header
* enclosed in quotes (').
* name is the name of the lisp function
*
* &optional may be abbreviated as &o.
* &rest may be abbreviated as &r.
......@@ -67,6 +66,18 @@
* use sole @(return);, because ";" will be treated as the next
* instruction.
*
* Symbols:
*
* @'name'
*
* Expands into a C statement, whole value is the given symbol
* from symbols_list.h
*
* @[name]
*
* Expands into a C statement, whole value is a fixnum
* corresponding to the index in the builtin symbols table of the
* given symbol from symbols_list.h. Used for handling type errors.
*/
#include <stdlib.h>
......
......@@ -2,7 +2,7 @@
/* vim: set filetype=c tabstop=2 shiftwidth=2 expandtab: */
/*
* features.h - names of features compiled into ECL
* ecl_features.h - names of features compiled into ECL
*
* Copyright (c) 1984 Taiichi Yuasa and Masami Hagiya
* Copyright (c) 1990 Giuseppe Attardi
......
......@@ -2,7 +2,7 @@
/* vim: set filetype=c tabstop=8 shiftwidth=4 expandtab: */
/*
unixint.c -- Unix interrupt interface.
unixint.d -- Unix interrupt interface.
*/
/*
Copyright (c) 1984, Taiichi Yuasa and Masami Hagiya.
......
......@@ -4,7 +4,9 @@
@cindex Defun preprocessor
Usage:
@verbatim
dpp [in-file [out-file]]
@end verbatim
The file named in-file is preprocessed and the output will be
written to the file whose name is out-file. If in-file is "-"
......@@ -14,7 +16,7 @@ C-program is written to standard output.
The function definition:
@exindex dpp: function definition
@lisp
@verbatim
@(defun name ({var}*
[&optional {var | (var [initform [svar]])}*]
[&rest var]
......@@ -30,32 +32,48 @@ The function definition:
C-body
} @)
@end lisp
@end verbatim
name can be either an identifier or a full C procedure header
enclosed in quotes (').
name is the name of the lisp function
&optional may be abbreviated as &o.
&rest may be abbreviated as &r.
&key may be abbreviated as &k.
&allow_other_keys may be abbreviated as &aok.
&aux may be abbreviated as &a.
&optional may be abbreviated as &o.@*
&rest may be abbreviated as &r.@*
&key may be abbreviated as &k.@*
&allow_other_keys may be abbreviated as &aok.@*
&aux may be abbreviated as &a.
Each variable becomes a C variable.
Each variable becomes a C variable.
Each supplied-p parameter becomes a boolean C variable.
Each supplied-p parameter becomes a boolean C variable.
Initforms are C expressions.
If an expression contains non-alphanumeric characters,
it should be surrounded by backquotes (`).
Initforms are C expressions.
If an expression contains non-alphanumeric characters,
it should be surrounded by backquotes (`).
Function return:
Function return:
@verbatim
@(return {form}*);
@end verbatim
@(return {form}*);
Return function expands into a lexical block @verb{|{}|}, so if it's
used inside IF/ELSE, then it should be enclosed, even if we
use sole @verb{|@(return);|}, because ";" will be treated as the next
instruction.
Return function expands into a lexical block {}, so if it's
used inside IF/ELSE, then it should be enclosed, even if we
use sole @(return);, because ";" will be treated as the next
instruction.
Symbols:
@verbatim
@'name'
@end verbatim
Expands into a C statement, whole value is the given symbol
from symbols_list.h
@verbatim
@[name]
@end verbatim
Expands into a C statement, whole value is a fixnum
corresponding to the index in the builtin symbols table of the
given symbol from symbols_list.h. Used for handling type errors.
......@@ -6,7 +6,7 @@
* Contributing:: How to contribute to the ECL project
@c * Modules hierarchy::
@c * Testing and benchmarking::
@c * Defun preprocessor:: Preprocessor for the Lisp constructs in C
* Defun preprocessor:: Preprocessor for the Lisp constructs in C
* Manipulating Lisp objects::
* Environment implementation::
* The interpreter::
......@@ -19,7 +19,7 @@
@include developer-guide/sources.txi
@include developer-guide/contributing.txi
@c @include developer-guide/dpp.txi
@include developer-guide/dpp.txi
@include developer-guide/objects.txi
@include developer-guide/environment.txi
@include developer-guide/interpreter.txi
......
......@@ -108,23 +108,23 @@ retrieve its value:
@example
if (ecl_t_of(x) == t_fixnum)
printf("Integer value: %d\n", fix(x));
printf("Integer value: %d\n", ecl_fixnum(x));
@end example
@subsubheading Example
@exindex Accessing underlying @code{cl_object} structure
If @code{x} is of type cl_object and it does not contain an immediate
datatype, you may inspect the cell associated to the lisp object using
@code{x} as a pointer. For example:
If @code{x} is of type @code{cl_object} and it does not contain an
immediate datatype, you may inspect the cell associated to the lisp
object using @code{x} as a pointer. For example:
@example
if (ecl_t_of(x) == t_vector)
printf("Vector's dimension is: %d\n", x->dim);
printf("Vector's dimension is: %d\n", x->vector.dim);
@end example
You should see the following sections and the header object.h to learn
how to use the different fields of a cl_object pointer.
how to use the different fields of a @code{cl_object} pointer.
@end deftp
@deftp @cind{} cl_type
......@@ -200,15 +200,17 @@ denoting the type that lisp object. That integer is one of the values of
the enumeration type @code{cl_type}.
@end deftypefun
@c XXX: add all predicate macros to the index
@cppindex ECL_FIXNUMP
@cppindex ECL_CHARACTERP
@cppindex CODE_CHAR_P
@cppindex ECL_BASE_CHAR_P
@cppindex ECL_BASE_CHAR_CODE_P
@cppindex ECL_NUMBER_TYPE_P
@cppindex ECL_COMPLEXP
@cppindex ECL_REAL_TYPE_P
@cppindex ECL_REAL_TYPE_P
@cppindex ECL_FIXNUMP
@cppindex ECL_BIGNUMP
@cppindex ECL_SINGLE_FLOAT_P
@cppindex ECL_DOUBLE_FLOAT_P
@cppindex ECL_LONG_FLOAT_P
@cppindex ECL_CONSP
@cppindex ECL_LISTP
@cppindex ECL_ATOM
......@@ -217,14 +219,25 @@ the enumeration type @code{cl_type}.
@cppindex ECL_VECTORP
@cppindex ECL_BIT_VECTOR_P
@cppindex ECL_STRINGP
@deftypefun bool ECL_FIXNUMP (cl_object o)
@deftypefunx bool ECL_CHARACTERP (cl_object o)
@cppindex ECL_HASH_TABLE_P
@cppindex ECL_RANDOM_STATE_P
@cppindex ECL_PACKAGEP
@cppindex ECL_PATHNAMEP
@cppindex ECL_READTABLEP
@cppindex ECL_FOREIGN_DATA_P
@cppindex ECL_SSE_PACK_P
@deftypefun bool ECL_CHARACTERP (cl_object o)
@deftypefunx bool ECL_BASE_CHAR_P (cl_object o)
@deftypefunx bool ECL_CODE_CHAR_P (cl_object o)
@deftypefunx bool ECL_BASE_CHAR_CODE_P (cl_object o)
@deftypefunx bool ECL_BASE_CHAR_CODE_P (ecl_character o)
@deftypefunx bool ECL_NUMBER_TYPE_P (cl_object o)
@deftypefunx bool ECL_COMPLEXP (cl_object o)
@deftypefunx bool ECL_REAL_TYPE_P (cl_object o)
@deftypefunx bool ECL_FIXNUMP (cl_object o)
@deftypefunx bool ECL_BIGNUMP (cl_object o)
@deftypefunx bool ECL_SINGLE_FLOAT_P (cl_object o)
@deftypefunx bool ECL_DOUBLE_FLOAT_P (cl_object o)
@deftypefunx bool ECL_LONG_FLOAT_P (cl_object o)
@deftypefunx bool ECL_CONSP (cl_object o)
@deftypefunx bool ECL_LISTP (cl_object o)
@deftypefunx bool ECL_ATOM (cl_object o)
......@@ -233,6 +246,13 @@ the enumeration type @code{cl_type}.
@deftypefunx bool ECL_VECTORP (cl_object o)
@deftypefunx bool ECL_BIT_VECTOR_P (cl_object o)
@deftypefunx bool ECL_STRINGP (cl_object o)
@deftypefunx bool ECL_HASH_TABLE_P (cl_object o)
@deftypefunx bool ECL_RANDOM_STATE_P (cl_object o)
@deftypefunx bool ECL_PACKAGEP (cl_object o)
@deftypefunx bool ECL_PATHNAMEP (cl_object o)
@deftypefunx bool ECL_READTABLEP (cl_object o)
@deftypefunx bool ECL_FOREIGN_DATA_P (cl_object o)
@deftypefunx bool ECL_SSE_PACK_P (cl_object o)
Different macros that check whether @var{o} belongs to the specified
type. These checks have been optimized, and are preferred over several
......@@ -261,26 +281,33 @@ The first way makes use of a C or Lisp string to construct an
object. The two functions you need to know are the following ones.
@cppindex c_string_to_object
@cppindex string_to_object
@deftypefun cl_object c_string_to_object (const char *s)
@deftypefunx cl_object string_to_object (cl_object o)
@code{c_string_to_object} builds a lisp object from a C string which
contains a suitable representation of a lisp
object. @code{string_to_object} performs the same task, but uses a lisp
string, and therefore it is less useful.
@cppindex ecl_read_from_cstring
@cppindex si_string_to_object
@defun si::string-to-object string &optional (err-value nil)
@end defun
@deftypefun cl_object si_string_to_object (cl_narg narg, cl_object str, ...)
@deftypefunx cl_object ecl_read_from_cstring (const char *s)
@code{ecl_read_from_cstring} builds a lisp object from a C string
which contains a suitable representation of a lisp
object. @code{si_string_to_object} performs the same task, but uses a
lisp string, and therefore it is less useful.
@itemize @bullet
@item @strong{DEPRECATED} @code{c_string_to_object} – equivalent to @code{ecl_read_from_cstring}
@end itemize
@subsubheading Example
@exindex @code{c_string_to_object} constructing Lisp objects in C
@exindex @code{ecl_read_from_cstring} constructing Lisp objects in C
Using a C string
@example
cl_object array1 = c_string_to_object("#(1 2 3 4)");
cl_object array1 = ecl_read_from_cstring("#(1 2 3 4)");
@end example
Using a Lisp string
@example
cl_object string = make_simple_string("#(1 2 3 4)");
cl_object array2 = string_to_object(string);
cl_object string = make_simple_base_string("#(1 2 3 4)");
cl_object array2 = si_string_to_object(string);
@end example
@end deftypefun
......@@ -345,13 +372,13 @@ Operations on @code{fixnums} (comparison and predicates).
@cppindex MAKE_FIXNUM
@cppindex fix
@deftypefun cl_object ecl_make_fixnum (cl_fixnum n)
@deftypefunx cl_fixnum ecl_unfix (cl_object o)
@deftypefunx cl_fixnum ecl_fixnum (cl_object o)
@code{ecl_make_fixnum} converts from an integer to a lisp object, while
the @code{ecl_fixnum} does the opposite (converts lisp object fixnum to
integer). These functions do @strong{not} check their arguments.
@itemize @bullet
@item @strong{DEPRECATED} @code{MAKE_FIXNUM} – equivalent to @code{cl_make_fixnum}
@item @strong{DEPRECATED} @code{fix} – equivalent to @code{cl_fixnum}
@item @strong{DEPRECATED} @code{MAKE_FIXNUM} – equivalent to @code{ecl_make_fixnum}
@item @strong{DEPRECATED} @code{fix} – equivalent to @code{ecl_fixnum}
@end itemize
@end deftypefun
......@@ -408,14 +435,15 @@ Each character is assigned an integer code which ranges from 0 to
@cppindex ECL_CODE_CHAR
@cppindex CODE_CHAR
@cppindex CHAR_CODE
@deftypefun cl_fixnum ECL_CHAR_CODE (cl_object o)
@deftypefunx cl_fixnum ECL_CODE_CHAR (cl_object o)
@deftypefun cl_object ECL_CODE_CHAR (ecl_character o)
@deftypefunx ecl_character ECL_CHAR_CODE (cl_object o)
@deftypefunx ecl_character ecl_char_code (cl_object o)
@deftypefunx ecl_base_char ecl_base_char_code (cl_object o)
@code{ECL_CHAR_CODE}, @code{ecl_char_code} and @code{ecl_base_char_code}
return the integer code associated to a lisp
character. @code{ecl_char_code} and @code{ecl_base_char_code} perform a
safe conversion, while ECL_CHAR_CODE doesn't check it's
argument. @code{ecl_base_char_code} is an optimized version for base
chars. Checks it's argument.
safe conversion, while @code{ECL_CHAR_CODE} doesn't check its
argument.
@code{ECL_CODE_CHAR} returns the lisp character associated to an integer
code. It does not check its arguments.
......@@ -457,7 +485,7 @@ vector, a bit-vector, a multidimensional array or a string.
@deftypefunx bool ECL_ARRAY_HAS_FILL_POINTER_P (cl_object x)
All arrays (arrays, strings and bit-vectors) may be tested for being
adjustable and whenever they have a fill pointer with this two
functions.
macros. They don't check the type of their arguments.
@end deftypefun
@cppindex ecl_vector
......@@ -468,7 +496,8 @@ If @code{x} contains a vector, you can access the following fields:
@item x->vector.elttype
The type of the elements of the vector.
@item x->vector.displaced
Boolean indicating if it is displaced.
List storing the vectors that x is displaced from and that x displaces
to.
@item x->vector.dim
The maximum number of elements.
@item x->vector.fillp
......@@ -490,8 +519,9 @@ The type of the elements of the array.
@item x->array.rank
The number of array dimensions.
@item x->array.displaced
Boolean indicating if it is displaced.
@item x->vector.dim
List storing the arrays that x is displaced from and that x displaces
to.
@item x->array.dim
The maximum number of elements.
@item x->array.dims[]
Array with the dimensions of the array. The elements range from
......@@ -516,8 +546,6 @@ some of those types together with the C constant that denotes that type:
@table @var
@item T
@code{ecl_aet_object}
@item BASE-CHAR
@code{ecl_aet_object}
@item SINGLE-FLOAT
@code{ecl_aet_sf}
@item DOUBLE-FLOAT
......@@ -545,8 +573,8 @@ bit-vector, vector, or a multidimensional array.
For example, the code
@example
ecl_array_elttype(c_string_to_object("\"AAA\"")); /* returns ecl_aet_ch */
ecl_array_elttype(c_string_to_object("#(A B C)")); /* returns ecl_aet_object */
ecl_array_elttype(ecl_read_from_cstring("\"AAA\"")); /* returns ecl_aet_ch */
ecl_array_elttype(ecl_read_from_cstring("#(A B C)")); /* returns ecl_aet_object */
@end example
@end deftypefun
......@@ -561,27 +589,27 @@ function ROW-MAJOR-AREF.
@subsubheading Example
@exindex @code{ecl_aref} and @code{ecl_aset} accessing arrays
@example
cl_object array = c_string_to_object("#2A((1 2) (3 4))");
cl_object x = aref(array, 3);
cl_object array = ecl_read_from_cstring("#2A((1 2) (3 4))");
cl_object x = ecl_aref(array, 3);
cl_print(1, x); /* Outputs 4 */
aset(array, 3, MAKE_FIXNUM(5));
ecl_aset(array, 3, ecl_make_fixnum(5));
cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
@end example
@end deftypefun
@cppindex ecl_aref1
@cppindex ecl_aset1
@deftypefun cl_object ecl_aref (cl_object x, cl_index index)
@deftypefunx cl_object ecl_aset (cl_object x, cl_index index, cl_object value)
These functions are similar to aref and aset, but they operate on vectors.
@deftypefun cl_object ecl_aref1 (cl_object x, cl_index index)
@deftypefunx cl_object ecl_aset1 (cl_object x, cl_index index, cl_object value)
These functions are similar to @code{aref} and @code{aset}, but they operate on vectors.
@subsubheading Example
@exindex @code{ecl_aref1} and @code{ecl_aset1} accessing vectors
@example
cl_object array = c_string_to_object("#(1 2 3 4)");
cl_object x = aref1(array, 3);
cl_object array = ecl_read_from_cstring("#(1 2 3 4)");
cl_object x = ecl_aref1(array, 3);
cl_print(1, x); /* Outputs 4 */
aset1(array, 3, MAKE_FIXNUM(5));
ecl_aset1(array, 3, ecl_make_fixnum(5));
cl_print(1, array); /* Outputs #(1 2 3 5) */
@end example
@end deftypefun
......@@ -610,7 +638,7 @@ Actual number of characters in the string.
@item x->string.fillp x->base_string.fillp
Actual number of characters in the string.
@item x->string.self x->base_string.self
Pointer to the characters (appropriately integers and chars).
Pointer to the characters (appropriately @code{ecl_character}'s and @code{ecl_base_char}'s).
@end table
@end deftp
......@@ -691,14 +719,13 @@ Character table, flags, etc
@cppindex ECL_ANSI_STREAM_P
@deftypefun bool ECL_ANSI_STREAM_P (cl_object o)
Predicate determining if @code{o} is a first-class stream
object. Doesn't check type of it's argument.
Predicate determining if @code{o} is a first-class stream object.
@end deftypefun
@cppindex ECL_ANSI_STREAM_TYPE_P
@deftypefun bool ECL_ANSI_STREAM_TYPE_P (cl_object o, ecl_smmode m)
Predicate determining if @code{o} is a first-class stream
object of type @code{m}.
Predicate determining if @code{o} is a first-class stream object of
type @code{m}.
@end deftypefun
@subheading Structures
......@@ -747,36 +774,38 @@ Convenience functions for the structures.
@subheading Bytecodes
A bytecodes object is a lisp object with a piece of code that can be
interpreted. The objects of type t_bytecode are implicitly constructed
by a call to eval, but can also be explicitly constructed with the
make_lambda function.
interpreted. The objects of type @code{t_bytecodes} are implicitly
constructed by a call to eval, but can also be explicitly constructed
with the @code{si_make_lambda} function.
@cppindex si_safe_eval
@cppindex cl_safe_eval
@cppindex cl_eval
@deftypefun cl_object si_safe_eval (cl_object form, cl_object env, ...)
@defun si:safe-eval form env &optional err-value
@end defun
@deftypefun cl_object si_safe_eval (cl_narg narg, cl_object form, cl_object env, ...)
@code{si_safe_eval} evaluates @code{form} in the lexical
environment@footnote{Note that @code{env} must be a lexical
environment as used in the interpreter, @xref{The lexical environment}}
@code{env}, which can be @var{ECL_NIL}. Before evaluating it, the
@code{env}, which can be @code{ECL_NIL}. Before evaluating it, the
expression form must be bytecompiled.
@table @code
@item @strong{DEPRECATED} cl_object cl_eval (cl_object form)
@itemize @bullet
@item @strong{DEPRECATED} @code{cl_object cl_eval (cl_object form)} -
@code{cl_eval} is the equivalent of @code{si_safe_eval} but without
environment and with err_value set to nil. It exists only for
compatibility with previous versions.
@item @strong{DEPRECATED} cl_object cl_safe_eval (cl_object form)
Equivalent of @code{si_safe_eval} (macro define).
@end table
@item @strong{DEPRECATED} @code{cl_object cl_safe_eval (cl_object form, cl_object env, cl_object err_value)} -
Equivalent of @code{si_safe_eval}.
@end itemize
@subheading Example
@exindex @code{cl_safe_eval}
@exindex @code{si_safe_eval}
@example
si_object form = c_string_to_object("(print 1)");
si_safe_eval(form, ECL_NIL);
si_safe_eval(form, ECL_NIL, 3); /* on error function will return 3 */
si_object form = ecl_read_from_cstring("(print 1)");
si_safe_eval(2, form, ECL_NIL);
si_safe_eval(3, form, ECL_NIL, 3); /* on error function will return 3 */
@end example
@end deftypefun
......@@ -799,10 +828,10 @@ For instance, we would achieve the equivalent of
with the following code
@example
cl_object def = c_string_to_object("((x y) (+ x y))");
cl_object name = _intern("foo")
cl_object def = ecl_read_from_cstring("((x y) (+ x y))");
cl_object name = ecl_make_symbol("FOO", "COMMON-LISP-USER");
cl_object fun = si_make_lambda(name, def);
return funcall(fun, MAKE_FIXNUM(1), MAKE_FIXNUM(2));
return cl_funcall(3, fun, ecl_make_fixnum(1), ecl_make_fixnum(2));
@end example
Notice that @code{si_make_lambda} performs a bytecodes compilation of
......
......@@ -64,6 +64,9 @@
@item compiler.d
@tab bytecode compiler
@item cons.d
@tab list manipulation macros & functions (auto generated)
@item disassembler.d
@tab bytecodes disassembler utilities
......@@ -73,7 +76,7 @@
@item ecl_constants.h
@tab constant values for all_symbols.d
@item features.h
@item ecl_features.h
@tab names of features compiled into ECL
@item error.d
......@@ -130,6 +133,9 @@
@item mapfun.d
@tab mapping
@item multival.d
@tab multiple values
@item newhash.d
@tab hashing routines
......@@ -171,7 +177,7 @@
@tab printer utilities and object representations
@item read.d
@tab read.d - reader
@tab reader
@item reader/parse_integer.d
@item reader/parse_number.d
......@@ -220,6 +226,9 @@ symbols on the system which aren't local.
@item unixfsys.d
@tab Unix file system interface
@item unixint.d
@tab Unix interrupt interface.
@item unixsys.d
@tab Unix shell interface
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment