4.3BSD/usr/lib/lisp/manual/ch1.r
CHAPTER 1
FRANZ LISP
1.1. FRANZ LISP[|-] was created as a tool to further
research in symbolic and algebraic manipulation,
artificial intelligence, and programming languages at
the University of California at Berkeley. Its roots
are in a PDP-11 Lisp system which originally came from
Harvard. As it grew it adopted features of Maclisp
and Lisp Machine Lisp. Substantial compatibility with
other Lisp dialects (Interlisp, UCILisp, CMULisp) is
achieved by means of support packages and compiler
switches. The heart of FRANZ LISP is written almost
entirely in the programming language C. Of course, it
has been greatly extended by additions written in
Lisp. A small part is written in the assembly
language for the current host machines, VAXen and a
couple of flavors of 68000. Because FRANZ LISP is
written in C, it is relatively portable and easy to
comprehend.
FRANZ LISP is capable of running large lisp pro-
grams in a timesharing environment, has facilities for
arrays and user defined structures, has a user con-
trolled reader with character and word macro capabil-
ities, and can interact directly with compiled Lisp,
C, Fortran, and Pascal code.
This document is a reference manual for the FRANZ
LISP system. It is not a Lisp primer or introduction
to the language. Some parts will be of interest pri-
marily to those maintaining FRANZ LISP at their com-
puter site. There is an additional document entitled
_T_h_e _F_r_a_n_z _L_i_s_p _S_y_s_t_e_m, _b_y _J_o_h_n _F_o_d_e_r_a_r_o, _w_h_i_c_h _p_a_r_-
_t_i_a_l_l_y _d_e_s_c_r_i_b_e_s _t_h_e _s_y_s_t_e_m _i_m_p_l_e_m_e_n_t_a_t_i_o_n. _F_R_A_N_Z
_L_I_S_P, _a_s _d_e_l_i_v_e_r_e_d _b_y _B_e_r_k_e_l_e_y, _i_n_c_l_u_d_e_s _a_l_l _s_o_u_r_c_e
_c_o_d_e _a_n_d _m_a_c_h_i_n_e _r_e_a_d_a_b_l_e _v_e_r_s_i_o_n _o_f _t_h_i_s _m_a_n_u_a_l _a_n_d
_s_y_s_t_e_m _d_o_c_u_m_e_n_t. _T_h_e _s_y_s_t_e_m _d_o_c_u_m_e_n_t _i_s _i_n _a _s_i_n_g_l_e
_f_i_l_e _n_a_m_e_d "_f_r_a_n_z._n" _i_n _t_h_e "_d_o_c" _s_u_b_d_i_r_e_c_t_o_r_y.
____________________
9 [|-]It is rumored that this name has something to do with
Franz Liszt [F_rants List] (1811-1886) a Hungarian composer
and keyboard virtuoso. These allegations have never been
proven.
9FRANZ LISP 1-1
FRANZ LISP 1-2
This document is divided into four Movements. In
the first one we will attempt to describe the language
of FRANZ LISP precisely and completely as it now
stands (Opus 38.69, June 1983). In the second Move-
ment we will look at the reader, function types,
arrays and exception handling. In the third Movement
we will look at several large support packages written
to help the FRANZ LISP user, namely the trace package,
compiler, fixit and stepping package. Finally the
fourth movement contains an index into the other
movements. In the rest of this chapter we shall exam-
ine the data types of FRANZ LISP. The conventions
used in the description of the FRANZ LISP functions
will be given in 1.3 -- it is very important that
these conventions are understood.
1.2. Data Types FRANZ LISP has fourteen data types.
In this section we shall look in detail at each type
and if a type is divisible we shall look inside it.
There is a Lisp function _t_y_p_e which will return the
type name of a lisp object. This is the official
FRANZ LISP name for that type and we will use this
name and this name only in the manual to avoid confus-
ing the reader. The types are listed in terms of
importance rather than alphabetically.
1.2.0. lispval This is the name we use to describe
any Lisp object. The function _t_y_p_e will never
return `lispval'.
1.2.1. symbol This object corresponds to a variable
in most other programming languages. It may have a
value or may be `unbound'. A symbol may be _l_a_m_b_d_a
_b_o_u_n_d meaning that its current value is stored away
somewhere and the symbol is given a new value for
the duration of a certain context. When the Lisp
processor leaves that context, the symbol's
current value is thrown away and its old value is
restored.
9 A symbol may also have a _f_u_n_c_t_i_o_n _b_i_n_d_i_n_g. This
function binding is static; it cannot be lambda
bound. Whenever the symbol is used in the func-
tional position of a Lisp expression the function
binding of the symbol is examined (see Chapter 4
for more details on evaluation).
9 A symbol may also have a _p_r_o_p_e_r_t_y _l_i_s_t, another
Printed: January 31, 1984
FRANZ LISP 1-3
static data structure. The property list consists
of a list of an even number of elements, considered
to be grouped as pairs. The first element of the
pair is the _i_n_d_i_c_a_t_o_r the second the _v_a_l_u_e of that
indicator.
9 Each symbol has a print name (_p_n_a_m_e) which is how
this symbol is accessed from input and referred to
on (printed) output.
9 A symbol also has a hashlink used to link symbols
together in the oblist -- this field is inaccessi-
ble to the lisp user.
9 Symbols are created by the reader and by the func-
tions _c_o_n_c_a_t, _m_a_k_n_a_m and their derivatives. Most
symbols live on FRANZ LISP's sole _o_b_l_i_s_t, and
therefore two symbols with the same print name are
usually the exact same object (they are _e_q). Sym-
bols which are not on the oblist are said to be
_u_n_i_n_t_e_r_n_e_d. The function _m_a_k_n_a_m creates uninterned
symbols while _c_o_n_c_a_t creates _i_n_t_e_r_n_e_d ones.
8 ____________________________________________________________
Subpart name Get value Set value Type
8 ________________________________________________________________________________________________________________________
value eval set lispval
setq
8 ____________________________________________________________
property plist setplist list or nil
list get putprop
defprop
8 ____________________________________________________________
function getd putd array, binary, list
binding def or nil
8 ____________________________________________________________
print name get_pname string
8 ____________________________________________________________
hash link
8 ____________________________________________________________
7 |7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|
1.2.2. list A list cell has two parts, called the
car and cdr. List cells are created by the func-
tion _c_o_n_s.
8 ________________________________________________
Subpart name Get value Set value Type
8 ________________________________________________________________________________________________
car car rplaca lispval
8 ________________________________________________
cdr cdr rplacd lispval
9 Printed: January 31, 1984
FRANZ LISP 1-4
8 ________________________________________________
799 |99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777777777799 |99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777777777799 |99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777777777799 |99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777777777799 |99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
777777777777777777777777777777777777777777777
1.2.3. binary This type acts as a function header
for machine coded functions. It has two parts, a
pointer to the start of the function and a symbol
whose print name describes the argument _d_i_s_c_i_p_l_i_n_e.
The discipline (if _l_a_m_b_d_a, _m_a_c_r_o or _n_l_a_m_b_d_a) deter-
mines whether the arguments to this function will
be evaluated by the caller before this function is
called. If the discipline is a string (specifi-
cally "_s_u_b_r_o_u_t_i_n_e", "_f_u_n_c_t_i_o_n", "_i_n_t_e_g_e_r-_f_u_n_c_t_i_o_n",
"_r_e_a_l-_f_u_n_c_t_i_o_n", "_c-_f_u_n_c_t_i_o_n", "_d_o_u_b_l_e-_c-_f_u_n_c_t_i_o_n",
or "_v_e_c_t_o_r-_c-_f_u_n_c_t_i_o_n" ) then this function is a
foreign subroutine or function (see 8.5 for more
details on this). Although the type of the _e_n_t_r_y
field of a binary type object is usually string or
other, the object pointed to is actually a sequence
of machine instructions.
Objects of type binary are created by _m_f_u_n_c_t_i_o_n,
_c_f_a_s_l, and _g_e_t_a_d_d_r_e_s_s.
8 _________________________________________________________
Subpart name Get value Set value Type
8 __________________________________________________________________________________________________________________
entry getentry string or fixnum
8 _________________________________________________________
discipline getdisc putdisc symbol or fixnum
8 _________________________________________________________
7 |8|7|7|7|7|
9 |8|7|7|7|7|
9 |8|7|7|7|7|
9 |8|7|7|7|7|
9 |8|7|7|7|7|
9
1.2.4. fixnum A fixnum is an integer constant in
the range -2[31] to 2[31]-1. Small fixnums (-1024
to 1023) are stored in a special table so they
needn't be allocated each time one is needed. In
principle, the range for fixnums is machine depen-
dent, although all current implementations for
franz have this range.
1.2.5. flonum A flonum is a double precision real
number. On the VAX, the range is +_2.9x10[-37] to
+_1.7x10[38]. There are approximately sixteen
decimal digits of precision. Other machines may
have other ranges.
9 Printed: January 31, 1984
FRANZ LISP 1-5
1.2.6. bignum A bignum is an integer of potentially
unbounded size. When integer arithmetic exceeds
the limits of fixnums mentioned above, the calcula-
tion is automatically done with bignums. Should
calculation with bignums give a result which can be
represented as a fixnum, then the fixnum represen-
tation will be used[|-]. This contraction is known
as _i_n_t_e_g_e_r _n_o_r_m_a_l_i_z_a_t_i_o_n. Many Lisp functions
assume that integers are normalized. Bignums are
composed of a sequence of list cells and a cell
known as an sdot. The user should consider a big-
num structure indivisible and use functions such as
_h_a_i_p_a_r_t, and _b_i_g_n_u_m-_l_e_f_t_s_h_i_f_t to extract parts of
it.
1.2.7. string A string is a null terminated
sequence of characters. Most functions of symbols
which operate on the symbol's print name will also
work on strings. The default reader syntax is set
so that a sequence of characters surrounded by dou-
ble quotes is a string.
1.2.8. port A port is a structure which the system
I/O routines can reference to transfer data between
the Lisp system and external media. Unlike other
Lisp objects there are a very limited number of
ports (20). Ports are allocated by _i_n_f_i_l_e and _o_u_t_-
_f_i_l_e and deallocated by _c_l_o_s_e and _r_e_s_e_t_i_o. The
_p_r_i_n_t function prints a port as a percent sign fol-
lowed by the name of the file it is connected to
(if the port was opened by _f_i_l_e_o_p_e_n, _i_n_f_i_l_e, _o_r
_o_u_t_f_i_l_e). During initialization, FRANZ LISP binds
the symbol piport to a port attached to the stan-
dard input stream. This port prints as %$stdin.
There are ports connected to the standard output
and error streams, which print as %$stdout and
%$stderr. This is discussed in more detail at the
beginning of Chapter 5.
____________________
9 [|-]The current algorithms for integer arithmetic opera-
tions will return (in certain cases) a result between +_2[30]
and 2[31] as a bignum although this could be represented as
a fixnum.
9 Printed: January 31, 1984
FRANZ LISP 1-6
1.2.9. vector Vectors are indexed sequences of
data. They can be used to implement a notion of
user-defined types via their associated property
list. They make hunks (see below) logically
unnecessary, although hunks are very efficiently
garbage collected. There is a second kind of vec-
tor, called an immediate-vector, which stores
binary data. The name that the function _t_y_p_e
returns for immediate-vectors is vectori.
Immediate-vectors could be used to implement
strings and block-flonum arrays, for example. Vec-
tors are discussed in chapter 9. The functions
_n_e_w-_v_e_c_t_o_r, and _v_e_c_t_o_r, can be used to create vec-
tors.
8 ________________________________________________
Subpart name Get value Set value Type
8 ________________________________________________________________________________________________
datum[_i] vref vset lispval
8 ________________________________________________
property vprop vsetprop lispval
vputprop
8 ________________________________________________
size vsize - fixnum
8 ________________________________________________
7 |7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|
1.2.10. array Arrays are rather complicated types
and are fully described in Chapter 9. An array
consists of a block of contiguous data, a function
to access that data, and auxiliary fields for use
by the accessing function. Since an array's
accessing function is created by the user, an array
can have any form the user chooses (e.g. n-
dimensional, triangular, or hash table).
Arrays are created by the function _m_a_r_r_a_y.
8 _______________________________________________________________
Subpart name Get value Set value Type
8 ______________________________________________________________________________________________________________________________
access function getaccess putaccess binary, list
or symbol
8 _______________________________________________________________
auxiliary getaux putaux lispval
8 _______________________________________________________________
data arrayref replace block of contiguous
set lispval
8 _______________________________________________________________
length getlength putlength fixnum
8 _______________________________________________________________
delta getdelta putdelta fixnum
9 Printed: January 31, 1984
FRANZ LISP 1-7
8 _______________________________________________________________
799 |9|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777899 |9|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777899 |9|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777899 |9|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
7777777777777777777777777777777777777777899 |9|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|99|
777777777777777777777777777777777777778
1.2.11. value A value cell contains a pointer to a
lispval. This type is used mainly by arrays of
general lisp objects. Value cells are created with
the _p_t_r function. A value cell containing a
pointer to the symbol `foo' is printed as
`(ptr to)foo'
1.2.12. hunk A hunk is a vector of from 1 to 128
lispvals. Once a hunk is created (by _h_u_n_k or
_m_a_k_h_u_n_k) it cannot grow or shrink. The access time
for an element of a hunk is slower than a list cell
element but faster than an array. Hunks are really
only allocated in sizes which are powers of two,
but can appear to the user to be any size in the 1
to 128 range. Users of hunks must realize that
(_n_o_t (_a_t_o_m '_l_i_s_p_v_a_l)) will return true if _l_i_s_p_v_a_l
is a hunk. Most lisp systems do not have a direct
test for a list cell and instead use the above test
and assume that a true result means _l_i_s_p_v_a_l is a
list cell. In FRANZ LISP you can use _d_t_p_r to check
for a list cell. Although hunks are not list
cells, you can still access the first two hunk ele-
ments with _c_d_r and _c_a_r and you can access any hunk
element with _c_x_r[|-]. You can set the value of the
first two elements of a hunk with _r_p_l_a_c_d and _r_p_l_a_c_a
and you can set the value of any element of the
hunk with _r_p_l_a_c_x. A hunk is printed by printing
its contents surrounded by { and }. However a hunk
cannot be read in in this way in the standard lisp
system. It is easy to write a reader macro to do
this if desired.
1.2.13. other Occasionally, you can obtain a
pointer to storage not allocated by the lisp sys-
tem. One example of this is the entry field of
those FRANZ LISP functions written in C. Such
objects are classified as of type other. Foreign
functions which call malloc to allocate their own
space, may also inadvertantly create such objects.
The garbage collector is supposed to ignore such
____________________
9 [|-]In a hunk, the function _c_d_r references the first ele-
ment and _c_a_r the second.
Printed: January 31, 1984
FRANZ LISP 1-8
objects.
1.3. Documentation The conventions used in the follow-
ing chapters were designed to give a great deal of
information in a brief space. The first line of a
function description contains the function name in
bold face and then lists the arguments, if any. The
arguments all have names which begin with a letter or
letters and an underscore. The letter(s) gives the
allowable type(s) for that argument according to this
table.
8 _______________________________________________________
Letter Allowable type(s)
8 ______________________________________________________________________________________________________________
g any type
8 _______________________________________________________
s symbol (although nil may not be allowed)
8 _______________________________________________________
t string
8 _______________________________________________________
l list (although nil may be allowed)
8 _______________________________________________________
n number (fixnum, flonum, bignum)
8 _______________________________________________________
i integer (fixnum, bignum)
8 _______________________________________________________
x fixnum
8 _______________________________________________________
b bignum
8 _______________________________________________________
f flonum
8 _______________________________________________________
u function type (either binary or lambda body)
8 _______________________________________________________
y binary
8 _______________________________________________________
v vector
8 _______________________________________________________
V vectori
8 _______________________________________________________
a array
8 _______________________________________________________
e value
8 _______________________________________________________
p port (or nil)
8 _______________________________________________________
h hunk
8 _______________________________________________________
7 |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|
In the first line of a function description, those
arguments preceded by a quote mark are evaluated (usu-
ally before the function is called). The quoting con-
vention is used so that we can give a name to the
result of evaluating the argument and we can describe
the allowable types. If an argument is not quoted it
does not mean that that argument will not be
9 Printed: January 31, 1984
FRANZ LISP 1-9
evaluated, but rather that if it is evaluated, the
time at which it is evaluated will be specifically
mentioned in the function description. Optional argu-
ments are surrounded by square brackets. An ellipsis
(...) means zero or more occurrences of an argument of
the directly preceding type.
9
9 Printed: January 31, 1984