This report describes research done at the Artificial Intelligence
Laboratory of the Massachusetts Institute of Technology. Support for the
laboratory's artificial intelligence research is provided in part by the
Advanced Research Projects Agency of the Department of Defense under Office
of Naval Research Contract number N00014-80-C-0505.

The Lisp Machine manual describes both the language and the "operating system"
of the Lisp Machine. The language, a dialect of Lisp called Zetalisp,
is completely documented
by this manual. The software environment and operating-system-like parts of
the system contain many things which are still in a state of flux.
This manual confines itself primarily to the stabler parts of the
system, and does not address the window system and user interface at all.
That documentation will be released as a separate volume at a later time.

Any comments, suggestions, or criticisms will be welcomed. Please send
Arpa network mail to BUG-LMMAN@MIT-AI.

The Lisp Machine is a product of the efforts of many people too numerous to list here
and of the unique environment of the M.I.T. Artificial Intelligence Laboratory.

Portions of this manual were written by Richard Stallman, Mike McMahon, and
Alan Bawden. The chapter on the LOOP iteration macro is a reprint of Laboratory for
Computer Science memo TM-169, by Glenn Burke.

1. "Introduction"

1.1 "General Information"

The Lisp Machine is a new computer system designed to provide a
high performance and economical implementation of the Lisp language. It
is a personal computation system, which means that processors and main
memories are not time-multiplexed: when using a Lisp Machine, you get
your own processor and memory system for the duration of the session.
It is designed this way to relieve the problems of the running of large
Lisp programs on time-sharing systems. Everything on the Lisp Machine
is written in Lisp, including all system programs; there is never any
need to program in machine language. The system is highly interactive.

The Lisp Machine executes a new dialect of Lisp called
Zetalisp, developed at the M.I.T. Artificial Intelligence
Laboratory for use in artificial intelligence research and related
fields. It is closely related to the Maclisp dialect, and attempts to
maintain a good degree of compatibility with Maclisp, while also
providing many improvements and new features. Maclisp, in turn, is
based on Lisp 1.5.

This document is the reference manual for the Zetalisp
language. This document is not a tutorial, and it sometimes refers to
functions and concepts that are not explained until later in the manual.
It is assumed that you have a basic working knowledge of some Lisp
dialect; you will be able to figure out the rest of the language from
this manual.

There are also facilities explained in this manual that are not
really part of the Lisp language. Some of these are subroutine packages
of general use, and others are tools used in writing programs. However,
the Lisp Machine window system, and the major utility programs, are not
documented here.

1.2 "Structure of the Manual"

The manual starts out with an explanation of the language. Chapter
(object-chapter) explains the different primitive types of Lisp object,
and presents some basic predicate functions for testing types.
Chapter (evaluator-chapter) explains the process of evaluation, which
is the heart of the Lisp language. Chapter (flow-chapter) introduces
the basic Lisp control structures.

The next several chapters explain the details of the various
primitive data-types of the language, and the functions that deal with
them. Chapter (cons-chapter) deals with conses and the higher-level
structures that can be built out of them, such as trees, lists,
association lists, and property lists. Chapter (symbol-chapter) deals
with symbols, chapter (number-chapter) with the various kinds of
numbers, and chapter (array-chapter) with arrays. Chapter
(string-chapter) explains character strings, which are a special kind
of array.

After this there are some chapters that explain more about functions,
function-calling, and related matters. Chapter (function-chapter) presents
all the kinds of functions in the language, explains function-specs, and
tells how to manipulate definitions of functions. Chapters (closure-chapter)
and (stack-group-chapter) discuss closures and stack-groups, two facilities
useful for creating coroutines and other advanced control and access structures.

Next, a few lower-level issues are dealt with. Chapter
(locative-chapter) explains locatives, which are a kind of pointer to
memory cells. Chapter (subprimitive-chapter) explains the "subprimitive"
functions, which are primarily useful for implementation of the Lisp
language itself and the Lisp Machine's "operating system". Chapter
(area-chapter) discusses areas, which give you control over storage
allocation and locality of reference.

Chapter (compiler-chapter) discusses the Lisp compiler, which
converts Lisp programs into "machine language". Chapter
(macros-chapter) explains the Lisp macro facility, which allows users
to write their own extensions to Lisp, extending both the interpreter
and the compiler. The next two chapters go into detail about two such
extensions, one that provides a powerful iteration control structure
(chapter (loop-chapter)), and one that provides a powerful data
structure facility (chapter (defstruct-chapter)).

Chapter (flavor-chapter) documents flavors, a language facility
to provide generic functions using the paradigm used in Smalltalk and the
Actor families of languages, called "object-oriented programming" or
"message passing". Flavors are widely used by the system programs of
the Lisp Machine, as well as being available to the user as a language
feature.

Chapter (io-chapter) explains the Lisp Machine's Input/Output system, including
streams and the printed representation of Lisp objects. Chapter
(pathname-chapter) documents how to deal with pathnames (the names of
files).

Chapter (package-chapter)
describes the package system, which allows many name spaces within
a single Lisp environment. Chapter (system-chapter) documents the
"system" facility, which helps you create and maintain programs
that reside in many files.

Chapter (process-chapter) discusses the facilities for
multiple processes and how to write programs that use concurrent
computation. Chapter (error-chapter) explains how exceptional
conditions (errors) can be handled by programs, handled by users, and
debugged. Chapter (code-chapter) explains the instruction set of the
Lisp Machine, and tells you how to examine the output of the compiler.
Chapter (query-chapter) documents some functions for querying the
user, chapter (time-chapter) explains some functions for manipulating
dates and times, and chapter (misc-chapter) contains other
miscellaneous functions and facilities.

1.3 "Notational Conventions and Helpful Notes"

There are several conventions of notation, and various points
that should be understood before reading the manual to avoid confusion.
This section explains those conventions.

The symbol "=>" will be used to indicate evaluation in
examples. Thus, when you see "foo => nil", this means the
same thing as "the result of evaluating foo is (or would have
been) nil".

The symbol "==>" will be used to indicate macro expansion
in examples. This, when you see "(foo bar) ==> (aref bar 0)",
this means the same thing as "the result of macro-expanding (foo bar)
is (or would have been) (aref bar 0)".

A typical description of a Lisp function looks like this:

Function:function-namearg1 arg2 &optional arg3 (arg4 (foo 3))

The function-name function adds together arg1 and arg2,
and then multiplies the result by arg3. If arg3 is not provided,
the multiplication isn't done. function-name then returns a list
whose first element is this result and whose second element is arg4.
Examples:

(function-name 3 4) => (7 4)
(function-name 1 2 2 'bar) => (6 bar)

Note the use of fonts (typefaces). The name of the function is
in bold-face in the first line of the description, and the arguments are
in italics. Within the text, printed representations of Lisp objects
are in a different bold-face font, such as (+ foo 56), and argument
references are italicized, such as arg1 and arg2. A different,
fixed-width font, such as 7function-name, is used for Lisp examples
that are set off from the text.

The word "&optional" in the list of arguments tells you that all
of the arguments past this point are optional. The default value can be
specified explicitly, as with arg4 whose default value is the result
of evaluating the form (foo 3). If no default value is specified,
it is the symbol nil. This syntax is used in lambda-lists in the
language, which are explained in (lambda-list). Argument lists may
also contain "&rest", which is part of the same syntax.

The descriptions of special forms and macros look like this:

Special Form:do-three-timesform

This evaluates form three times and returns the result of the third
evaluation.

Macro:with-foo-bound-to-nilform...

This evaluates the forms with the symbol foo bound to nil.
It expands as follows:

Since special forms and macros are the mechanism by which the syntax of Lisp
is extended, their descriptions must describe both their syntax and their
semantics; functions follow a simple consistent set of rules, but each
special form is idiosyncratic. The syntax is displayed on the first line
of the description using the following conventions. Italicized words are
names of parts of the form which are referred to in the descriptive text.
They are not arguments, even though they resemble the italicized words in
the first line of a function description. Parentheses ("( )") stand for themselves.
Square brackets ("[ ]") indicate that what they enclose is optional.
Ellipses ("...") indicate that the subform (italicized word or parenthesized
list) which precedes them may be repeated any number of times (possibly no times at all).
Curly brackets followed by ellipses ("{ }...") indicate that what they
enclose may be repeated any number of times. Thus the first line of the
description of a special form is a "template" for what an instance of that
special form would look like, with the surrounding parentheses removed.
The syntax of some special forms is sufficiently complicated
that it does not fit comfortably into this style; the first line of the
description of such a special form contains only the name, and the syntax is
given by example in the body of the description.

The semantics of a special form includes not only what it "does for a living",
but also which subforms are evaluated and what the returned value is. Usually
this will be clarified with one or more examples.

A convention used by many special forms is that all of their subforms after
the first few are described as "body...". This means that the remaining
subforms constitute the "body" of this special form; they are Lisp forms which
are evaluated one after another in some environment established by the special
form.

This ridiculous special form exhibits all of the syntactic features:

Special Form:twiddle-frob[(frob option...)] {parameter value}...

This twiddles the parameters of frob, which defaults to default-frob
if not specified. Each parameter is the name of one of the adjustable parameters of
a frob; each value is what value to set that parameter to. Any number
of parameter/value pairs may be specified. If any options are specified,
they are keywords which select which safety checks to override while twiddling
the parameters. If neither frob nor any options are specified, the
list of them may be omitted and the form may begin directly with the first
parameter name.

frob and the values are evaluated; the parameters and options
are syntactic keywords and not evaluated. The returned value is the frob
whose parameters were adjusted. An error is signalled if any safety checks
are violated.

Methods, the message-passing equivalent of ordinary Lisp's functions,
are described in this style:

Method: flavor-name message-namearg1 arg2 &optional arg3

This is the documentation of the effect of sending a message
named message-name, with arguments arg1, arg2, and arg3,
to an instance of flavor flavor-name.

Descriptions of variables ("special" or "global" variables) look like this:

Variable:typical-variable

The variable typical-variable has a typical value....

Most numbers shown are in octal radix (base eight). Spelled out
numbers and numbers followed by a decimal point are in decimal. This is
because, by default, Zetalisp types out numbers in base 8; don't
be surprised by this. If you wish to change it, see the documentation on the variables
ibase and base ((ibase-var)).

All uses of the phrase "Lisp reader", unless further qualified,
refer to the part of Lisp which reads characters from I/O streams
(the read function), and not the person reading this manual.

There are several terms which are used widely in other
references on Lisp, but are not used much in this document since they have become
largely obsolete and misleading. For the benefit of those who may
have seen them before, they are: "S-expression", which means a Lisp
object; "Dotted pair", which means a cons; and "Atom", which means,
roughly, symbols and numbers and sometimes other things, but not
conses. The terms "list" and "tree" are defined in (list-and-tree).

The characters acute accent (') (also called "single quote") and
semicolon (;) have special meanings when typed to Lisp; they are
examples of what are called macro characters. Though the
mechanism of macro characters is not of immediate interest to the new
user, it is important to understand the effect of these two, which are
used in the examples.
When the Lisp reader encounters a "'", it reads in the next
Lisp object and encloses it in a quote special form. That
is, 'foo-symbol turns into (quote foo-symbol), and '(cons 'a 'b)
turns into (quote (cons (quote a) (quote b))). The reason
for this is that "quote" would otherwise have to be typed in very
frequently, and would look ugly.
The semicolon is used as a commenting character. When the
Lisp reader sees one, the remainder of the line is
discarded.
The character "/" is used for quoting strange characters so
that they are not interpreted in their usual way by the Lisp reader,
but rather are treated the way normal alphabetic characters are treated.
So, for example, in order to give a "/" to the reader, you must type "//",
the first "/" quoting the second one. When a character
is preceeded by a "/" it is said to be slashified. Slashifying
also turns off the effects of macro characters such as "'" and ";".
The following characters also have special meanings,
and may not be used in symbols without slashification. These characters
are explained in detail in the section on printed-representation
((reader)).

"

Double-quote delimits character strings.

#

Number-sign introduces miscellaneous reader macros.

`

Backquote is used to construct list structure.

,

Comma is used in conjunction with backquote.

:

Colon is the package prefix.

|

Characters between pairs of vertical-bars are quoted.

Circle-cross lets you type in characters using their octal codes.

All Lisp code in this manual is written in lower case.
In fact, the reader turns all symbols into upper-case, and consequently
everything prints out in upper case. You may write programs in whichever
case you prefer.

You will see various symbols that have the colon (:)
character in their names. By convention, all "keyword" symbols in the
Lisp Machine system have names starting with a colon. The colon
character is not actually part of the print name, but is a package
prefix indicating that the symbol belongs to the package with a null
name, which means the user package. So, when you print such a
symbol, you won't see the colon if the current package is user.
However, you should always type in the colons where the manual tells you
to. This is all explained in chapter (package-chapter); until you read
that, just make believe that the colons are part of the names of the
symbols, and don't worry that they sometimes don't get printed out for keyword
symbols.

This manual documents a number of internal functions and variables,
which can be identified by the "si:" prefix in their names. The "si"
stands for "system internals". These functions and variables are documented
here because they are things you sometimes need to know about. However,
they are considered internal to the system and their behavior is not as
guaranteed as that of everything else. They may be changed in the future.

Zetalisp is descended from Maclisp, and a good deal
of effort was expended to try to allow Maclisp programs to run
in Zetalisp. Throughout the manual, there are notes about
differences between the dialects. For the new user, it is important
to note that many functions herein exist solely for Maclisp compatibility;
they should not be used in new programs. Such functions are
clearly marked in the text.

The Lisp Machine character set is not quite the same as that used
on I.T.S. nor on Multics; it is described in full detail elsewhere
in the manual. The important thing to note for now is that the
character "newline" is the same as "return", and is represented by
the number 215 octal. (This number should not be built into any programs.)

When the text speaks of "typing Control-Q" (for example),
this means to hold down the CTRL key on the keyboard (either of
the two), and, while holding it down, to strike the "Q" key.
Similarly, to type "Meta-P", hold down either of the META keys
and strike "P". To type "Control-Meta-T" hold down both CTRL
and META. Unlike ASCII, there are no "control characters"
in the character set; Control and Meta are merely things
that can be typed on the keyboard.

Many of the functions refer to "areas". The area feature
is only of interest to writers of large systems, and can be safely
disregarded by the casual user. It is described in chapter (area-chapter).