.c	Wednesday  Sept 14,1983  19:25  FQ+8H.22M.44S.  -*- Bolio -*-
.headings off
.c These little horseshow frobs are until Moon fixes .space to work at
.c the top of a page ***
 
.space 8
.center 9Introduction to NIL*
.space 2
.center Revision 1
.space 7
.center 2This Month*
.space 2
.center 5Glenn Burke*
.space 10
.nopara
This report describes research done at the Laboratory for Computer
Science of the Massachusetts Institute of Technology.  Support for
this research was provided in part by the National Institutes of
Health grant no. 1 P01 LM 03374-04 from the National Library of
Medicine, the U. S. Air Force under grant F49620-79-C-020, the
National Aeronautics and Space Administration under grant NSG 1323,
the U. S. Department of Energy under grant ET-78-C-02-4687, and
the Digital Equipment Corporation of Maynard, Massachusetts, with
grants of equipment.
.space 3
.center "MASSACHUSETTS INSTITUTE OF TECHNOLOGY"
.center "LABORATORY FOR COMPUTER SCIENCE"
.space 1
.spread /CAMBRIDGE//MASSACHUSETTS 02139/
.page
.c These little horseshow frobs are until Moon fixes .space to work at the top of a page ***
 

.center 5Abstract*
This document is a primer for lan{nil}, a New Implementation of
Lisp.  It is not a description or overview of the language, but rather
documentation of some of the "ordinary" facilities available, so that
those with some small lan{lisp} experience can use lan{nil} in a
basic way.

.space 2

.center 5Acknowledgments*

Most of the lan{nil} system development for the past year has been
performed by myself and George Carrette, who is also the primary
source of lan{vms} expertise within Tech Square.  The implementation
of the lan{nil} editor is solely the result of the efforts of
Christopher Eliot, who is also responsible for much of the numerical
(especially bignum) code now available in lan{nil}.  Inaccuracies in
the over-simplified documentation of the editor here, however, are totally
the fault of GSB.

The AI Lab Robotics Group deserves credit for just "being there" as
potential lan{nil} users.  In particular, Patric Sobalvarro has been
extremely helpful with both lan{nil} implementation, and
documentation writing and proofreading.

Peter Szolovits has been (and will continue to be) a sounding board
for problems of all sorts, and additionally deserves
credit, along with Michael Dertouzos, Al Vezza, and Joel Moses, for
continuing support of the project.

The lan{nil} language is being converted to conform to the (as yet
not officially complete) lan{common lisp} standard.  This effort is
the result of the work of a great many people (see
ref{CommonLisp-Overview}).



.space 2
.center 5Note*
This document should be considered an informal paper for internal use.
It is not intended for formal distribution or reference in its current
form.
.space 14
.nopara
  c    Copyright by the Massachusetts Institute of Technology; Cambridge, Mass. 02139
.br
All rights reserved.
.page
.headings on


.chapter "Introduction"

lan{Nil} is a dialect of lan{lisp} which runs on DEC VAXes under the
VMS operating system.  It is destined to be compatible with
lan{common lisp} ref{CommonLisp-Overview}.  lan{common lisp} is a
sufficiently complete specification of Lisp that many programs should
be able to be written conforming to that standard, and thus be able to
be transported to other lan{common lisp} implementations.  At this
time, the "final draft" of the lan{common lisp} manual has not been
published, and also certain fine points are not finalized.  lan{nil},
although not nearly complete, conforms closely to much of the existing
and known lan{common lisp} functionality.

The lan{nil} system provides a lexical interpreter complete with
closures, a compiler, a primitive interactive debugger, and (under
development now) an editor (written in lan{nil}).  lan{nil} is
compatible with lan{maclisp} to whatever extent is possible, given
that the interpreter uses lexical scoping rules, and that certain fine
incompatibility points between lan{common lisp} and lan{maclisp} exist.
Certain of these will be described later.

This document is oriented towards someone who has some knowledge of
lan{lisp}, such as lan{lisp 1.5} or (even better) lan{maclisp}.
It is not in itself a lan{lisp} primer.  It deliberately ignores
or downplays many complicated and esoteric features.  In other areas,
the documentation is simply abbreviated to what are (hopefully) the
more useful points.  Neither should this document be considered to be
an "overview" of lan{nil};  there are many facilities which are
totally omitted, yet which are integral parts of the lan{nil}
language.  Rather, it is both a primer and reference source with which
someone with some minor lan{lisp} experience should be able to
derive what knowledge is needed to do a fair amount of programming
using the lan{nil} interpreter.  The hordes of
special-case functions which are used to produce efficient
production systems, have all been overlooked here.  The compiler has
been overlooked also, partly for simplicity, and partly because it is
not capable of handling all of the control and binding constructs
which the interpreter does.
Highly sophisticated lan{lisp} users, or those
familiar with a large and complex system such as lan{zetalisp}, may
still find some things here useful (although perhaps tedious reading)
because of incompatibilities.

The lan{nil} system is still incomplete and under active
development.  It does not yet have a garbage collector.  It has a
compiler which produces pretty good lan{vax} code directly, and
which is expected to be eventually replaced by an even better one
which will handle both more complicated lexical control and binding
constructs, and type declarations for better numeric and string
crunching.  Eventually, lan{nil} will support at least four
different floating-point formats to allow numeric crunching of various
flavors, and more sophisticated handling of complex numbers than it
does now.  It is expected to be able to talk to the lan{chaos}
network itself, allowing it to directly access files on other hosts
the way a Lisp Machine does.  The editor in lan{nil} is still fairly
new, having only recently been released for use within the lan{mit}
community.

.chapter "Style, Conventions, Etc."

.section "Documentation Conventions"

The conventions used in this manual are essentially the same as those
used in the Lisp Machine Manual ref{LMMan}.

In this document, all numbers are decimal.  In this it differs from
both the Lisp Machine Manual, and the Maclisp Reference Manual
ref{Moonual}.

In lisp code examples, the symbol 3=>* should be read as
"evaluates to", and 3==>* as "macroexpands to".  The latter should
usually be taken as a paraphrase (or functional equivalence) rather
than a literal expansion, as the actual expansion will usually be
something more obscure and implementation-dependent.

Function documentation typically looks like
.defun_no_index sample-function string &optional (stream standard-output) &rest other-things
3sample-function* takes one or more arguments.  The first should
be a string.  The second, if it is supplied, should be a stream;  if
it is not supplied, the value of the variable 3standard-output* is
used instead. It outputs the characters of 2string* to
2stream*, immediately followed by the number of 2other-things*
supplied, in hexidecimal.  Thus, the call
.lisp
(sample-function "foo" terminal-io 'a 'b 'c)
.end_lisp
would produce the output
.lisp
foo3
.end_lisp
.end_defun

In function documentation, the lambda-list keywords such as
3&optional*, 3&rest*, and 3&key* are used, similar to the
way they are used in 3defun*.  The exact meaning of them is
described in (lambda-list-section-page).

Variable definition looks like
.defvar_no_index *sample-variable*
The value of this variable is the number of times the lan{nil}
language has broken due to DEC field service modifying the VMS system
parameters.
.end_defvar

Special forms and macros are sometimes documented using lambda-list
keywords like function documentation, but more often using a slightly
different description of how they expect their forms:
.defspec_no_index sample-specform (var form) {declaration}* forms...
The special form 3sample-specform* binds 2var* to a stream
which will broadcast its output to both the terminal and the stream
which 2form* evaluates to.  The 2declarations* are used just
as with 3lambda* or 3let*.  It evaluates 2forms* in this
environment.  Thus,
.lisp
(sample-specform (*stream* *disk-file*)
   (declare (special *stream*))
   (princ "The findings are:" *stream*)
   (display-findings))
.end_lisp
prints "The findings are:" to both the terminal and the stream which
is the value of 3*disk-file**.  Presumably, 3display-findings*
uses the variable 3*stream** free, and prints the findings to that
stream.
.end_defspec
The format 3{2foo*}** means any number of 2foo*s;
3{2foo*}+* means one or more 2foo*s.  3[2foo*]*
means an optional 2foo*, and 32foo*...* is the
same as 3{2foo*}**.

.section "Major Implementation Points"

lan{Nil}, like lan{zetalisp}, utilizes a function cell in which
to define functions and macros.  It does not use the property list the
way lan{maclisp} does.  Interpretation of whether a name is a
function or a variable is done purely syntactically;  in, for example,
.lisp
(fact number)
.end_lisp
3fact* is interpreted as a function, and 3number* as a
variable.  Doing a 3setq* of 3fact* will not affect this
interpretation, and neither will doing a 3defun* of 3number*.

lan{nil} is one of the few "production" Lisps around now which
utilize lexical scoping rules in the interpreter, as opposed to that
only being the default interpretation when the code is compiled (as is
the case in lan{maclisp} and lan{zetalisp}).  The lan{nil}
interpreter thus behaves somewhat like the compiler, and heeds
variable declarations.  This also has an impact on the efficiency of
interpreted code, but no comparisons of its speed have been made
with any comparable Lisp implementations.  
The lexical scoping (which is discussed in
(binding-and-scoping-section-page)) also affects the ways in which
one must debug interpreted code.  This is because lexically scoped
variables may only be validly referenced from within the lexical
(textual) scope where they were bound.  As a result, it is
difficult (if not impossible) to find their values from "outside" of
the function they are bound in.
'c One of the major impacts of
'c lexical scoping within the interpreter is on debugging interpreted
'c code, because outside of a function, variable values may no longer be
'c lexically apparent.
The debugger ((debug-fun)) and exhibitor
((exhibit-fun)) are capable of compensating for this somewhat.

.section "NIL and T"

In lan{nil}, the canonical objects for representing boolean true and
false are atomic symbols, just as they are in lan{maclisp},
lan{zetalisp}, and as specified by lan{common lisp}.  (This
differs from earlier implementations of lan{nil} including the one,
made in December 1982, which was distributed as Release 0.)  One
may not bind or setq these symbols.  They do, however, have values and
potentially functions associated with them, just as all other symbols
do.  The mechanism by which they have values which are not allowed to
be modified is available to the user by use of the 3defconstant*
special form ((defconstant-fun)).

.section "Syntax and Symbols"

lan{nil} by default "comes up" using the reader syntax specified by
lan{common lisp}.  The primary difference of note involves the
3/* and 3\* characters:  the "quoting" or "slashification"
character in lan{common lisp} is backslash (3\*), rather than
slash (3/*) as it is in lan{maclisp} and lan{zetalisp}.
Thus, the division function whose print name consists of the single
character 3/* may be typed in as just that single character,
unlike (for instance) lan{maclisp} where the slashes needed to be
doubled;  conversely, the function in lan{nil} which performs the
3gcd* operation on fixnums only (for lan{maclisp}
compatibility), and which has a print name consisting of two
backslashes (3\\*), must be typed in as 3\\\\*.
In documentation text, symbols are displayed without the (back)slashes
which may be necessary for them to be typed in.  Within lisp examples,
lisp expressions are displayed with the necessary slashification,
utilizing lan{common lisp} syntax.

One other syntax difference is that lan{nil} has a special data type
to represent term_i{characters}.  Those who use the sharpsign
(3#*) reader macro should note that in lan{common lisp}
syntax, there is no 3#/* syntax, only 3#\* which can
accept both character names and single characters, and that the object
represented is a 3character*, not the fixnum representation of the
character.


.chapter "NIL and VMS"
.setq vms-section-page section-page

lan{nil} runs as a separate process under lan{vms}.  In
lan{tops-20} terminology, it "keeps";  it does not disappear when
exited the way many other programs do.

.section "Getting In and Out of NIL"

The 7nil* command to the command language interpreter (7CLI*)
runs a program which "manages" the lan{nil}.  Essentially, saying
7nil* with no options will resume an existing lan{nil} if there is
one, or create and start one if there is not.  If one is "in"
lan{nil}, control-Y (the sort of general lan{vms} "interrupt
process" command) will suspend the execution of the lan{nil}, and
return to the command language interpreter.
.english 500 2
There is some (probably timing) bug such that occasionally after a
control-Y is typed, the lan{nil} gets suspended but the command
interpreter does not return and prompt.  When this happens, the next
line of input may "get lost".  If the "$" prompt does not appear in
reasonable time after typing of control-Y, then a couple more control-Ys
and maybe a carriage-return or two will get it, and avoid having the
next line of input get ignored.  If this does not work, then something
more serious is wrong.
.end_english

The 7nil* command may be given other arguments which are only
meaningful if there is a lan{nil} process around already:
.table 7 250 250
.item nil/kill
This kills the lan{nil}.  It is the same as executing 3(quit)*
from within the lan{nil}.
.item nil/proceed
Resumes the lan{nil} process, but does not enable the lan{nil} to
perform terminal input and output.  If the lan{nil} attempts to do
them, it will wait until it is resumed.  Similarly, if the lan{nil}
calls any of the functions which interact with its superior while
the it is proceeded, it will wait until it is resumed.
.end_table

.section "Terminal Interrupts"

lan{vms} does not provide a very general mechanism for receiving
interrupts by typing a character on the terminal.  The only available
option is to get an interrupt when control-C is typed.  So, what
lan{nil} does is to handle control-C interrupts, and then prompt for
input:  you type a character to tell it what interrupt function to
perform.  Some of the more interesting characters are
.table 3 250 250
.item 2control-G*
Quit to top-level Lisp.  Aborts whatever was running.
.item B
Enters a break loop (see 3break*, (break-fun)).  When the break
loop is exited, program execution resumes.
.item D
Enters the Lisp debugger.  The stack and program environment can then
be examined.  If the debugger is exited with the Q command, then
program execution resumes as before.
.item ?
Lists the characters available and what they do.
.item N
Ignore the interrupt and continue whatever was happening before.
.item X
Also control-X but you probably can't type that (as explained below).
Modeled after the lan{maclisp} control-X interrupt, this quits
somewhat less fatally than control-G:  it aborts back to the most
recently established 3errset* (therefore 3break* loop), or to
top-level.
.end_table
It should be noted that the control-C interrupt is handled by
lan{nil} at Lisp-level.  If the lan{nil} is busy doing something
uninterruptibly, it will ignore the control-C until it is done.
Typing multiple control-Cs will only make the lan{nil} think that it
is broken, and call up the VMS debugger, which is generally fatal to
the lan{nil}.
.english 500 2
VMS does not provide a notion of "which job is using the terminal".
Because of this, often a NIL which is not running will have its
control-C interrupt triggered when control-C is typed at some other
program.  This generally does 1not* happen to a NIL which is
running without-the-terminal (as by 7nil/proceed*), however.  All
that can be done is to type N at the "7INTERRUPT>*" prompt when it
occurs.  This will be fixed when the interrupt system is revamped.
.end_english

.section "Other Perversities"

There are several other characters which lan{vms} places special
interpretations on.
.table 2 250 500
.item xon/xoff
Control-S and control-Q block and continue output from lan{vms},
respectively.  This is allegedly for "flow control", even though it
is impossible for it to work in all but the simplest cases.
Supposedly your terminal sends control-S when it is getting too much output
from the host, which then shuts up for a while (until control-Q is
sent).  More conveniently, it is something you can type to
stop the output in its tracks, so you can read it;  you can then type
control-Q to get output to resume.  lan{Nil}
normally does not disable this, except when within the editor.
.item Control-T
This displays some information about what is running, similar to the
lan{tops-20} control-T.  Unfortunately, lan{vms} does not handle
cursor control itself (forcing lan{nil} to), and prints out this
information causing lan{nil} to get confused about where the cursor
is.  You will also notice that lan{vms} prefers not to clear lines it
types on before it types there.
.item control-O
This aborts output.  It causes output to the terminal to be discarded,
until some input is performed (or certain other exceptional conditions
occur like a control-C interrupt).  lan{nil} does not recognize this
situation, and lan{vms} again types something which confuses
lan{nil} about where the cursor is.  If you wish to abort output, it
is probably (depending on the context) better to use control-C and
type "X" at the interrupt prompt;  this will abort back to the most
recently established 3break* loop, or to top-level.
.item control-U
When standard buffered input is being done (as when you are typing at
the command interpreter), control-U flushes the input buffer.  The
lan{nil} input processor uses this to delete a line of input (not
the whole expression).
.item control-R
When standard buffered input is being done (as when you are typing at
the command interpreter), control-R reprompts and retypes the buffered
input.
.item control-X
To the lan{vms} buffered input reader, this means both control-U,
and flush typeahead (the characters which have been typed but not read
yet).  In order that this functionality be implemented in a completely
general way, the lan{vms} terminal input driver is kind enough to
translate this character into control-U.  Thus, when you type
control-X at lan{nil}, it sees control-U.
.end_table

lan{vms} offers a way around all of the above randomness, known as
'setq passall-mode-page page
term_i{passall mode}.  This mode disables 2everything*,
including both control-Y and control-C.  It also apparently disables
"broadcast messages", such as announcements that the system is about
to go down.  When the lan{nil} editor is
entered, it enters this mode.  It leaves it temporarily at certain
strategic points, but not too frequently.  What this means is that if
the editor gets into an infinite loop, you get totally wedged, and
will probably need external help (with privileges) to even be able to
log out.  Maybe DEC can get it right next time.

.chapter "Data Type Overview"

.section "Conses"
The data type 3list* is called 3cons* in lan{nil}, to
distinguish it from the meaning of 3list* in which 3nil* is
the empty list.  Other than that, all is ordinary.

.section "Symbols"
Symbols serve as names for variables, functions, or simply as
keywords.  Every symbol has a term_i{property list} or
term_i{plist}, a list of alternating property indicators and
values.  It has a term_i{print name} or term_i{pname}, which is a
string that "is" the printed representation of the symbol.  It can
have both a value and a function associated with it.  It also has a
package ((package-data-type-overview-section-page)).

The symbol 3nil* is somewhat special.  It has the data type
3null* (a subtype of 3symbol*), is the only object
of that type, and is also considered to be the empty list.  
Functions which operate on symbols treat it as an ordinary symbol.

.section "Numbers"

lan{Nil} provides representations for and operations on both
rational and floating-point numbers.  It also provides a complex
number representation, but only the simpler arithmetic operations know
how to deal with it right now.  Similarly, many operations on
non-integer rational numbers are deficient.

.subsection "Rationals"
An integer is a rational number whose denominator is 31*.  If an
integer is within a particular range (is representable in
twos-complement notation in 30 bits), then it is the special type
3fixnum*, otherwise it is a 3bignum*.  Conversion between the
two is automatically performed by the arithmetic functions.

Non-integer rational numbers are of the type 3ratio*.  The
"top" and "bottom" of a ratio are its term_i{numerator} and
term_i{denominator}, and may be accessed with the fun_i{numerator}
and fun_i{denominator} functions, which work on integers also.  (The
numerator of an integer is itself, and its denominator is 1.)  The
numerator and denomimator of a ratio will always be returned in
reduced form, and the denomimator will always be positive.  Ratios are
notated by typing the (possibly signed) numerator, a slash, and the
(unsigned) denominator, as in 3-4/3*.

Ratios are typically created by rational number division.  This
can occur when integer division is being performed using the
lan{common lisp} 3/* function, and the dividend is not an exact
multiple of the divisor.  Thus, 
.lisp
(/ 8 6)	  =>   4/3
.end_lisp
To get truncation, the lan{maclisp} compatible 3quotient*
function can be used;  it will produce a ratio only if one of the
inputs is a ratio.

.subsection "Floating Point Numbers"

lan{nil} currently offers one floating-point format, which is
double-precision, having an 8-bit exponent and 56-bit mantissa
(significand) (including the hidden bit).  This type is
3double-float*.  For various historical reasons, it is also called
3flonum* (from Maclisp).  Note that in lan{nil} (as in all MIT
lisp dialects), suffixing a sequence of digits by a decimal point does
not produce a floating-point number, but rather forces the integer to
read in in radix 10;  to force floating-point, the decimal point must
be followed by digits.  Thus, 3"10."* is the fixnum ten, but
3"10.0"* is floating-point ten.  The other syntax is to use
exponential notation, as in 31.0e+10*.  In this too, in
lan{nil}, at least one digit is required after the decimal point,
although none are required 2before* the decimal point.

.subsection "Contagion and Conversion"

Most of the standard arithmetic functions operate on any/all numeric
types, and convert from one to another as necessary.  In general,
rationals convert to floating-point, and non-complex to complex.  Note that
it is not significant to talk about interconversion of ratios,
integers, and fixnums;  an integer is just a special case of a
rational number, as is a ratio.

Unlike with rationals, complex numbers with imaginary parts are never
reduced back to non-complex numbers.  Otherwise, the operations on the
real and imaginary parts undergo contagious conversion in the same
way.

For example:
.lisp
(+ 2 3.0)	=>  5.0
(+ 2 3)		=>  5
(/ 2 3)		=>  2/3
(/ 2 3.0)	=>  0.6666666666666667
.end_lisp

.section "Characters"
lan{nil} provides a data type for representing characters.
Characters are the things one manipulates when doing "character I/O"
on streams.  They are the things one gets out of, and puts into,
strings.  Having a separate data type allows them to maintain their
identity within the lisp (as opposed to being an interpretation placed
on fixnums, for instance).

Characters in lan{nil} have three different attributes:  their
term{code},
'cindex character code
their term{bits},
'cindex character bits
and their term{font}.
'cindex character font
The code defines the basic ("root") character.  The bits are used as
modifiers.  Typically, an input processor (such as the editor, or even
the prescan for the toplevel Lisp read-eval-print loop) will treat a
character without any bits as "ordinary" and assume it is part of the
text being typed in, but treat a character with some bits as being a
command.  Four of the special bits are named:  they are 3control*,
3meta*, 3super*, and 3hyper*.
The font is not used for anything by lan{nil} right now,
but the information can be there if anyone wants to make use of it.

Characters in lan{nil} use 3#\* syntax for input and output, as
shown below.  Note that if the character after the 3#\* stands
alone, it is taken literally.  If it occurs after a prefix such as
"control-", then it will be treated like an ordinary token, so may
need to have a preceding backslash to inhibit case translation or just
to allow proper token parsing.
.lisp
#\a			;1Lowercase "a".*
#\A			;1Uppercase "a".*
#\Control-a		;1Uppercase "a", with the control bit.*
#\Meta-\a		;1Lowercase "a", with the meta bit.*
.end_lisp
Some characters have names, which may be used in place of the
character itself:
.lisp
#\Rubout		;1The "rubout" or "delete" character*
#\Hyper-Space		;1The "space" character with the hyper bit.*
.end_lisp

Only a subset of all possible characters are allowed to be contained
in strings.  These comprise the 3string-char* data type.  It
happens that in lan{nil} these are those characters which have no
font or bits attributes (both are 0).

The lan{nil} character set has not yet been cleaned up with respect
to the confusion between the lan{ascii} control characters and the
characters it uses with the 3control* bit.  The lan{ascii}
control characters read from files or the terminal are not mapped into
characters with the 3control* bit, except in special situations
(like by the editor itself).  They are left as-is, and in principle
these characters would make up an extended graphic character set like
lan{lisp machine lisp} uses.  These characters however do not have
printed representations on standard lan{ascii} terminals, so they
have their own naming syntax:  the character object for lan{ascii}
control-A, for instance, will display as 3#\^A*, and may be typed
in as such.  Essentially, this "uparrow" syntax does a logical
2xor* of the following character (code) with 3100* octal.

.section "Arrays"

Most of the remaining types of interest in lan{nil} are various
sorts of term_i{array}.  Arrays in lan{nil} may have any rank from
0 to (about) 250.  The indexing is always zero-origined.
Arrays specialize in various ways.  One-dimensional arrays are also of
type 3vector*, and may be used
(interchangeably with lists) as sequences with various sequence
operations.  Arrays also specialize according to what types of data
may be stored in them.  In particular, there are special array types
which can only hold the fixnums 30* and 31*, known as
3bit-array*s, and some which can only store objects of type
3string-char*;  one-dimensional arrays (i.e., vectors) with this
element-type restriction are term_i{string}s.

Vectors which can hold objects of any types, called term_i{general
vectors}, may be typed in by starting the sequence of objects with
3#(* and ending it with 3)*.  For instance,
.lisp
#(foo (bar) #\A)
.end_lisp
is a vector with three elements:  the symbol 3foo*, a list of the
symbol 3bar*, and the character uppercase 3a*.  Such a vector
may be empty (have zero length):
.lisp
#()
.end_lisp

Strings are typed in and printed out by enclosing the characters of
the string with doublequotes.  If the string is to contain doublequote
or backslash characters, they must be preceded by a backslash
character.  The syntax
.lisp
"foo\\\""
.end_lisp
is the printed representation  for a string with five characters:
3f*, 3o*, 3o*, backslash, and doublequote.

Bit vectors are displayed as the characters 3#** followed by a
sequence of 31* and 30* characters.  Thus
.lisp
#*001110
.end_lisp
is a bit-vector of length 6;  its elements numbered zero to five are
30*, 30*, 31*, 31*, 31*, and 30*.

lan{Nil} arrays can support various hair dealing with indirection,
sharing, overlaying of datastructures, and adjustable sizes.  Some of
these are incomplete or undebugged, others are in use, but none will
be discussed further in this document.

.section "Packages and Readtables"

Details of these are not fit for this document.  However, they need to
be mentioned, because they will probably be encountered in some
context or another.

.subsection "Readtables"

A term_i{readtable} is the datastructure which defines the syntax
used by 3read*.  The lan{nil} environment contains a few for
various purposes.  Two in particular are of interest:  these are the
lan{common lisp} readtable, and the lan{nil} readtable.  The
default readtable used by lan{nil} is the lan{common lisp}
readtable.  The lan{nil} readtable is the one utilizing the syntax
designed for lan{nil} several years ago, which is incompatible with
lan{common lisp} syntax.  The irony here is that the lan{nil}
readtable is more compatible with the default lan{maclisp} and
lan{zetalisp} reader syntax than the lan{common lisp} readtable
is, due to the interchange of slash and backslash for character
quoting within tokens.  For this reason, certain otherwise-vanilla
source files will sometimes explicitly specify the lan{nil}
readtable.  There are other disparities having to do with the reading
of characters as both fixnums and as character objects, but the point
is to note why a specification of the readtable might be necessary.

.subsection "Packages"
.setq package-data-type-overview-section-page section-page

In lan{nil}, as in lan{zetalisp}, not all symbols share the same
"name space".  They are organized into term_i{packages}, which are a
structured organization of symbol tables.  (This is like having
multiple term_i{obarrays} (of lan{maclisp}) or term_i{oblists}
(of lan{lisp 1.5}), but there is more structure imposed on it.)
Packages will not be documented here, other than what their existence
may imply even when they are not used.  Knowledge of
term_i{interning} (at least in the lan{lisp 1.5} sense) is assumed.

The colon (3:*) character is reserved for specifying the package
into which the following symbol is to be interned.  In fact, the
package system provides inheritance, so the symbol may actually be
inherited from some "superior" package.  There is a "root" package,
called 3global*, which the symbols which are for use by everyone
are inherited, for instance.  It contains the symbols which name
system functions (like 3car*), variables (like the constants
3most-positive-fixnum* and 3pi*), and some just used as
symbols (like the type name 3double-float*).  The syntax
3si:internal-eval* means "the symbol 3internal-eval* read in
(as if from) within the package named 3si*".  (3si* is the
short name for 3system-internals*, where most of the random
innards of lan{nil} reside.)

There is a special package which is referred to with an empty "package
prefix";  this is used for keywords, those symbols which are tested
for equality with 3eq* and must remain so no matter which package
they are read into.  Many functions take arguments "by keyword" so
that there is less confusion about which arguments go in which
position.  For convenience, these keywords self-evaluate (and are
constants).  Thus, one can type both
.lisp
(fill frobozz something :start 4 :end 5)
.end_lisp
or
.lisp
(fill frobozz something :end 5 :start 4)
.end_lisp
equivalently.

For simple applications, it is usually not necessary to interact with
the package system other than to use colons to type keywords (as
above), and to avoid them in other contexts.  lan{nil} starts up in
the 3user* package, which is itself empty but provides access to
all the globally defined symbols.  Restricted applications can usually
function entirely from one package and not refer to any others.  For
instance, when lan{mycin} is loaded with 3(load-mycin)*, it
creates the 3mycin* package, loads up the lan{mycin} files into
it, and makes that the current package.  From then on, all
interactions can be performed from there;  all of the functions and
variables of lan{mycin} are available.

.chapter "Interpretation"

.section "Binding and Scoping"
.setq binding-and-scoping-section-page section-page

The lan{nil} interpreter uses lexical scoping.  What this means,
simply, is that variable references which are "textually within" the
code which binds them, are valid.  Those references which are not
"textually within" the binding form are not, and will (typically)
cause unbound-variable errors.  Consider the definition
.lisp
(defun make-associations (keys single-value)
   (mapcar #'(lambda (key) (cons key single-value)) keys))
.end_lisp
which takes a list of keys (perhaps for use by 3assoc*), and
returns an association list associating all of those keys with the
same single value.  The first argument to 3mapcar*, the lambda
expression, is technically a function.  (The 3#'* construct is
explained below.)  It is, however, textually
within the binding of the argument 3single-value*, so that
variable reference is lexical, and that function works in lan{nil}
as desired.  Consider the alternative form
.lisp
(defun make-associations (keys single-value)
   (mapcar #'make-one-association keys))
(defun make-one-association (key)
   (cons key single-value))
.end_lisp
which might appear to be equivalent.  The reference to
3single-value* in the definition of 3make-one-association* is
2not* textually within the binding of that variable, hence appears
"free".  Although this function (in the absence of extra declarations,
as described below) would function "properly" in the lan{maclisp} or
lan{zetalisp} interpreters, it will not in lan{nil}.  It is
interesting to note that  (again without special declarative
information) both the lan{maclisp} and lan{zetalisp} compilers
will treat the second example as an error (or at least produce
incorrect code), because although the interpreters do not enforce
lexical scoping rules, code is compiled that way.

A short note may be in order on the 3#'* construct which appeared
above.  3#'* is an abbreviation for 3(function ...)*, just as
3'* is an abbreviation for 3(quote ...)*.  In lan{maclisp}, the
two are equivalent.  However, in lan{nil} (and to some extent in
lan{zetalisp} too), use of this special form is necessary to cause
the proper (functional) interpretation of the form being evaluated.
In fact, in the 3make-associations* example, it is that special
interpretation which makes the lexical reference to 3single-value*
"work".  If 3quote* was used instead of 3function*, the example
would not work as desired.  3function* (or 3#'*) need not just be
used around lambda expressions.  It may also be used around function
names (as in the second 3make-associations* example).  The effect of
evaluating 3(function 2name*)* is equivalent to what the
interpreter does when it "evaluates" 2name* in the function position
of a list being evaluated.

lan{nil} does not restrict one to using only lexical scoping rules.
It is possible to declare to lan{nil} that a variable is
term_i{special}, and should be able to be referenced by code
2not* textually within the binding construct.  Or, perhaps a
variable should have a global toplevel value and not be bound
anywhere, or maybe even have a toplevel value, and be bound in some
places.  This is the purpose of the 3special* declaration, which
lan{nil} implements compatibly with lan{common lisp}, and which is
about the same as it is in lan{zetalisp} and lan{maclisp}.

Most of the time, term_i{special variables} are declared to be
special globally.  This means that the lan{nil} interpreter (and
compiler) will always treat the variable as being special, even if
there is no declaration for it at the place it is bound.  As a matter
of style, variables declared 3special* are usually given names
which begin and end with the character 3** so that they can be
visually distinguished from more "ordinary" lexically scoped
variables.  One way to globally declare a variable 3special* is
with 3defvar* ((defvar-fun)).  For instance,
.lisp
(defvar *leaves*)
(defun find-all-leaves (tree)
  (let ((*leaves* nil))		;1Empty set of leaves*
    (find-all-leaves-1 tree)	;1Grovel over the tree*
    *leaves*			;1And return the leaves found*
    ))
(defun find-all-leaves-1 (tree)
  (cond ((atom tree)
	   (cond ((not (memq tree *leaves*))
		  (setq *leaves* (cons tree *leaves*)))))
	(t (find-all-leaves-1 (car tree))
	   (find-all-leaves-1 (cdr tree)))))
.end_lisp
There are more esoteric (or lan{scheme}-like) ways in which the
above could have been performed, without the use of the special
variable 3*leaves**, but the above is fairly straightforward,
fairly efficient, and will run (both interpreted and compiled) compatibly
in lan{maclisp} and lan{zetalisp}.

The above intuitive (or, if you prefer, hand-waving and vague)
description can now be used to more formally define the terms of
term_i{scope} and term_i{extent} which are used to describe the
accessibility and lifetimes of things, of which variable bindings are
one instance.  The 2scope* of something tells 2where* it may
be validly referred to.  To say that something has term_i{lexical
scope} then means that it may be used anywhere "textually" within the
construct which "creates" the object (e.g., the lambda-expression
which binds a variable).  Note that this does not in itself imply that
the reference becomes invalid if that construct is exited.  That
dimension is the term_i{extent} of the object, which tells the
2time* during which the object (e.g., variable binding) is valid.
term_i{dynamic extent} means that the object (reference) is only
valid during the execution of the construct.  term_i{indefinite
extent} means that there is no such limitation.  Variable bindings in
the lan{nil} interpreter (which are not 3special*) have lexical
scope and indefinite extent.  This means upward funarg capability.

term_i{indefinite scope} means that there is no restriction on where
a valid reference may occur from.  This is the case with 3special*
variables;  the "free" references may be made from any piece of code.
The bindings of such variables, however, have only term_i{dynamic
extent};  they become invalid (are "unbound") when the binding
construct is exited.  This combination of scope and extent, which is
quite common, is referred to as term_i{dynamic scope}.

.chapter "Variables and Definitions"

.section "Lambda List Interpretation"
.setq lambda-list-section-page section-page

Application of a lambda expression in lan{nil} is much like that of
lan{zetalisp}.  A lambda expression is of the general form
.lisp
(lambda 2lambda-list* {2declaration*}* {2form*}*)
.end_lisp
In the simplest case, 2lambda-list* is a (possibly empty) list of
variable names, which are the formal parameters to the lambda
expression when it is treated as a function.  There must be as many
arguments to the lambda-expression as there are variables.  Thus,
.lisp
((lambda (a b c) (list a b c)) 1 2 (+ 3 4))
 => (1 2 7)
.end_lisp

The lambda-list may also contain special keywords which begin with the
character 3&*.  They are typically used to drive the matching of
the formal parameters (variables) in the lambda list with the values
they should be bound to.  There are basically just four such keywords,
each of which is optional, and which should appear in the order they
are shown in:
.table 3 250 250
.item &optional
The items from the 3&optional* to the next &-keyword (or end of
the lambda-list) describe optional arguments to the function.  Each
such item may be of one of the following forms:
.table 2 250 250
.item variable
If a corresponding argument is supplied, then 2variable* will be
bound to that.  Otherwise, it will be bound to 3nil*.
.item (variable)
Same as an isolated 2variable*.
.item (variable init-form)
If there is a corresponding argument, then 2variable* is bound to
that.  If not, then 2init-form* is evaluated, and 2variable*
bound to that result.  The evaluation of 2init-form* is performed
in an environment where all of the variables in the lambda list to the
left of this one have been bound already.
.item (variable init-form init-p-var)
Just like the previous format.  Additionally, 2init-p-var* will be
bound to 3t* if there was an argument supplied, 3nil* if not.
.end_table
.item &rest
There must be exactly one item between an 3&rest* keyword and the
next &-keyword (or the end of the lambda-list).  This variable is
bound to a list of all the remaining arguments to the function.
.item &key
The items between 3&key* and either 3&aux* or the end of the
lambda-list describe term_i{keyworded arguments} to the function.
These are arguments which are passed by keyword rather than by
position:  when given, it must be preceded by the keyword naming which
argument it is.  For example, the calls
.lisp
(fill sequence new-item :start start :end end)
(fill sequence new-item :end end :start start)
.end_lisp
are effectively the same.  All keyworded arguments are by default
optional.  The specification of a keyworded argument in the lambda
list is normally the same as that of an optional argument.  The name
of the variable is used to generate the keyword which flags that
particular parameter.
For instance, 3fill* is defined with the lambda-list
.lisp
(sequence item &key (start 0) end)
.end_lisp
Additionally, with the non-atomic forms of optional parameter
specification, a list of the actual keyword
which should be used and the variable to bind the argument to may be
used instead.  For example, if it were desired that the keyword
3:start* be used to flag the starting index, but that the formal
parameter be named 3i*, then the lambda-list could have been
written as
.lisp
(sequence item &key ((:start i) 0) end)
.end_lisp
It is important to note that if both 3&key* and 3&rest* are
given, then the list the 3&rest* variable is bound to is 2the
same* list from which the keyworded arguments are extracted.  This
is sometimes useful if the arguments are going to be passed en-mass to
some other function using 3apply*, and is rarely used.
.end_table

.section "Defining Functions"

.defspec defun name lambda-list {declarations}* forms...
3defun* is pretty much like a lan{maclisp} or lan{zetalisp}
3defun*.  In lan{nil}, in case you are interested, a 3defun*
in the interpreter globally defines the function 2name* as a
closure over the lexical environment in which the 3defun* is
performed.  The 2lambda-list* is a lan{common lisp} compatible
lambda-list, which is mostly the same as that used by lan{zetalisp};
the special keywords 3&optional*, 3&rest*, 3&aux*, and
3&key* are interpreted accordingly, as described above;
3defun* simply associates the function name with a corresponding
lambda-expression constructed from the lambda-list, declarations, and
forms.
.end_defspec

.defmac defmacro name pattern forms...
3defmacro* is used for defining macros...  It is described in the
Maclisp Extensions Manual ref{Maclisp-Extensions}.
.end_defmac

.section "Defining Variables"

Because of the lexical nature of the lan{nil} interpreter, those
variables which are going to be used "free" from functions, or which
are going to be globally assigned values, are usually best "defined"
at top-level.  Global declaration that a variable with a particular
name will be 3special* avoids problems with subtleties of local
declarations.  For the same reason, it is conventional for special
variables (which are not constants defined with 3defconstant*) to
begin and end with the character 3**.  (Note that most lan{nil}
system variables do not obey this convention, mainly because they have
not been converted yet.)

.defmac defvar variable [init] [documentation]
3defvar* is used for "defining" variables.  It should only be used
"at top level" in a source file, not from within code.  If there is no
2init* form specified, then it simply globally declares
2variable* to be special.  If there 2is* an 2init* form
specified, then, if 2variable* does not have a value already, the
2init* form will be evaluated and 2variable* set to that.
2documentation*, if present, should be a string which "documents"
the variable.  It will be remembered somewhere where no one is likely
to find it.
.end_defmac

.defmac defparameter variable init [documentation]
This is like 3defvar*, except that 2variable* is
unconditionally set to the value of 2init*.  Thus, the 2init*
form must always be specified.
.end_defmac

.defmac defconstant variable init [documentation]
This is like 3defparameter*, but additionally states that
2variable* is a constant.  It is an error to bind or 3setq*
that variable.  Sometimes the lan{nil} compiler may take advantage
of this information.  If, when a 3defconstant* form is evaluated,
2variable* already has a value which is different from what
2init* evaluates to, a correctable error is signalled.

3defconstant* will fail to make 2variable* truly constant if
it already has a value not assigned by 3defconstant*, or even if
there is compiled code which references 2variable*.
.end_defmac

.chapter "Predicates"

.section "Equality"

.defun eq object1 object2
Returns 3t* if 2object1* and 2object2* are "the same".
In general,
.lisp
(setq x (compute-something))
(eq x x)
  => t
.end_lisp
Equal numbers are not necessarily 3eq*, however.  For numeric
equality, one should use 3eql*, or, if arithmetic equality
irrespective of type is desired (i.e., conversion from integer to
floating may be needed), 3=* ((=-fun)) should be used.
.end_defun

.defun eql object1 object2
This predicate is a slight extension of 3eq*.  It is used as the
default equality predicate by many lan{nil} functions.  Essentially,
it is 3equal* for non-structured objects:  two numbers are
3eql* if they are of the same type and numerically equal,
character objects are 3eql* if they represent the same characters,
etc.  However, structured objects, such as lists, strings, vectors,
and arrays, are 3eql* only if they are 3eq*.  Thus,
.lisp
(eql (add1 (sub1 0.0)) 0.0)	=>	t
(eq (add1 (sub1 0.0)) 0.0)	=>	nil
(eql (cons 'a 'b) (cons 'a 'b)) =>	nil
.end_lisp
.end_defun

.defun equal object1 object2
This is the more traditional (and more general, in some sense)
equality predicate.  If 2object1* and 2object2* are not
structured, then they are compared like 3eql* (above) does.
Two lists are 3equal* if their 3car*s and 3cdr*s are
respectively 3equal*.  Otherwise, if they are both arrays (which
includes strings, vectors, and bit-vectors), they are 3equal* if
they have the same rank and dimensions, the same element types (a
string cannot be equal to a non-string array of characters), and
3equal* elements.

Note that in lan{maclisp} and lan{zetalisp}, 3equal* never
descends into arrays other than strings.  In lan{nil}, it is more
consistent in its handling of the various types of array.  Note also
that in lan{zetalisp}, the special treatment of strings is
different in that it performs a case 2independent* comparison,
which is inconsistent with both the ideas of simply recursively
descending into the object and performing recursive 3equal* tests,
and the heuristic that two objects are 3equal* if the "print" the
same.
.end_defun

.section "Types"

.defun null x
Returns 3t* if 2x* is 3nil*, 3nil* otherwise.
.end_defun

.defun not x
Same as 3null*.  3not* implies that 3nil* is representing
boolean 2false*, 3null* implies that it represents the empty
list.
.end_defun

.defun atom x
3t* if 2x* is not a cons, 3nil* if it is.  Note that
arrays (and strings and vectors) are all atoms, even though they have
structure (which may be descended by such functions as 3equal*).
.end_defun

.defun listp x
3t* if 2x* is a cons or 3nil* (the empty list), 3nil*
otherwise.  Note that 3listp* does not examine anything but the
type of the object;  it does not verify that 2x* is actually a
"proper list", one whose last 3cdr* is 3nil*.

Note that in lan{zetalisp}, 3listp* is false for 3nil*.
lan{nil} is compatible with lan{maclisp} (and lan{common lisp})
here.
.end_defun

.defun consp x
3t* if 2x* is a 3cons*, 3nil* otherwise.
.end_defun

.defun integerp x
.defun1 fixp x
3t* if 2x* is an integer, 3nil* otherwise.  3fixp* is
provided for lan{maclisp} compatibility.  It is entirely identical
to 3integerp*.
.end_defun

.defun floatp x
3t* if 2x* is any kind of floating-point number, 3nil*
otherwise.
.end_defun

.defun numberp x
.defun1 arrayp x
.defun1 vectorp x
.defun1 stringp x
The list goes on and on.
.end_defun

.defun typep object &optional type
If no 2type* argument is supplied, this returns the name of the
type of 2object*.  This returned result is almost always something
much too internal for practical use, and is certainly not compatible
with lan{maclisp}.  In this case 3typep* isn't even a predicate.

If the 2type* argument 2is* supplied, then 3typep* returns
3t* if 2object* is of the type 2type*, 3nil*
otherwise.  2type* may be a general lan{common lisp} type
specifier.  Typically it is a symbol which names a type.  An
exhaustive list of the allowable types is not provided here (and is,
in fact, extensible anyway).  It includes such type names as
3null*, 3cons*, 3list*, 3integer*, 3rational*,
3number*, 3character*, 3string*, 3array*,
3closure*, 3vector*, 3function*, 3hash-table*, and
3stream*.  3typep* will complain if 2type* is not a valid
type specifier.
.end_defun

.chapter "Control and Program Structure"

.section "Binding"

.defspec let letlist {declaration}* forms...
3let* binds the variables to the values specified in
2letlist*, and evaluates 2forms* in that environment,
returning the value(s) resulting from the evaluation of the last
2form*.  The 2letlist* is a list of the form
.lisp
({2variable* | (2variable*) | (2variable* 2init-form*)}*)
.end_lisp
In the first two variants, the variable will be bound to 3nil*;
in the last, to the evaluation of 2init-form*.  All of the
2init-form*s in the letlist are evaluated before any of the
variables are bound.  For example,
.lisp
(let ((x 1) (y 2))
  (let ((x y) (y x))
    (list x y)))
  ==>  (2 1)
.end_lisp
That form is equivalent to
.lisp
((lambda (x y)
   ((lambda (x y)
      (list x y))
    y x)))
 1 2)
.end_lisp
.end_defspec

.defspec let* letlist {declaration}* forms...
3let** is like 3let* syntactically, but the variables are
bound sequentially rather than in parallel.  That is, first the first
init-form is evaluated and the first variable bound to that, then the
second init-form is evaluated in that new environment, etc.  So,
.lisp
(let* ((x 1) (y 2))
  (let* ((x y) (y x))
    (list x y)))
  => (2 2)
.end_lisp
.end_defspec


.section "Flow of Control"

.defspec cond {(predicate-form {consequent}*)}*
Ordinary everyday lan{lisp} 3cond*.  Each "clause" is examined
in succession:  the predicate-form is evaluated, and if the result is not
3nil*, then the 2consequent*s of that clause are evaluated,
and the value(s) of the last are returned as the value(s) of the
3cond*, without further examination of any other clauses.  If
there are no 2consequent*s in the clause, the value the predicate
form returned is returned instead.  If no predicate-form "succeeds",
3cond* returns 3nil*.
.lisp
(defun fact (n)
   (cond ((= n 0) 1)
	 (t (times n (fact (sub1 n)))))
.end_lisp
.end_defspec

.defspec if predicate-form then-form [else-form]
A simpler binary 3cond*.
.lisp
(defun fact (n)
  (if (= n 0) 1 (times n (fact (sub1 n)))))
.end_lisp
.end_defspec

.defspec case item {(keyspec {consequent}+)}*
This is similar to, but somewhat more general than, the fun_i{caseq}
and fun_i{selectq} macros of lan{maclisp} and lan{zetalisp}
(which lan{nil} define in terms of 3case*).  The
2item* is evaluated, then is matched against 2keyspec* of each
clause in turn.  If it matches, then the 2consequent*s of that
clause are evaluated, and the value(s) of the last returned as the
value of the 3case*;  if none match, the 3case* form evaluates
to 3nil*.

A 2keyspec* may be an atom or a list.  The key matches if
2keyspec* is a list and the value of 2item* is a member (using
the predicate 3eql*--see (eql-fun)) of
that list, or if 2keyspec* is the atom 3t* (allowing an
"otherwise" clause), or if 2keyspec* is an atom and is 3eql*
to the value of 2item*.
.lisp
(defun integer-description (n)
  (case n
    (0 "none at all")
    (1 "just one")
    (2 "a couple")
    ((3 4) "a few")
    ((5 6 7) "several")
    (t "many")))
.end_lisp
.end_defspec

.section "Iteration"

.defun mapl function &rest lists
.defun1 mapc function &rest lists
.defun1 maplist function &rest lists
.defun1 mapcar function &rest lists
.defun1 mapcon function &rest lists
.defun1 mapcan function &rest lists
These are the "traditional" functions for iteration down lists.  There
must be at least one list specified;  the iteration terminates when
any list "runs out".  The function is called on as
many arguments as there are lists.  3mapl*, 3maplist*, and
3mapcon* apply the function to successive sublists of the lists;
3mapc*, 3mapcar*, and 3mapcan* to successive elements.

3mapl* and 3mapc* are primarily for effect;  they both return
the first 2list* argument given to them.

3maplist* and 3mapcar* return a new list, the elements of
which are the results of applications of 2function*.  That list
will thus have as many elements as the shortest of the 2lists*.

3mapcon* and 3mapcan* "splice together" the results of the
applications of 2function*, (as if) by 3nconc*.  This allows
multiple new elements (or none) to be returned.

.lisp
(mapc #'print '(a b c))
1prints*
a
b
c
1and returns*
(a b c)
.end_lisp
.lisp
(mapl #'print '(a b c))
1prints*
(a b c)
(b c)
(c)
1and returns*
(a b c)
.end_lisp
.lisp
(mapcar #'(lambda (x y) (plus (times x 2) y))
	'(1 2 3) '(4 5 6))
  => (6 9 12)
.end_lisp
.lisp
(defun odd-ones (l)
  (mapcan #'(lambda (x) (and (oddp x) (list x))) l))
(odd-ones '(1 2 3 4))
  => (1 3)
.end_lisp
.lisp
(defun destructively-remove-duplicates (l)
  (mapl #'(lambda (sublist)
	     (rplacd sublist
		     (delq (car sublist) (cdr sublist))))
        l))
(destructively-remove-duplicates '(a b b c b d e c))
 => (a b c d e)
.end_lisp

Note that 3mapl* is the same as the lan{maclisp} and
lan{zetalisp} function 3map*.  In lan{nil}, the function
3map* is a more general sequence iteration function, which takes
different arguments.
.end_defun

.defspec dotimes (var count) {declaration}* body...
Evaluates the forms in 2body* in an environment where 2var* is
stepped from 0 up to (but not including) the value of 2count*.
2body* is actually a 3tagbody* body, and 3dotimes*
establishes an implicit block named 3nil*, thus 3return* may
be used to return a value from the 3dotimes* before the iteration
terminates;  see (block-tagbody-section-page).
.end_defspec

.defspec dolist (var list) {declaration}* body...
2body* is evaluated with 2var* bound to the successive
elements of the value of the form 2list*.   2body* is actually
a 3tagbody* body, and 3dolist* establishes an implicit block
named 3nil*, thus 3return* may be used to return a value from
the 3dolist* before the iteration terminates;  see
(block-tagbody-section-page).
.end_defspec

.defspec dovector (var vector) {declaration}* body...
Similar to 3dolist*, but for vectors.
.end_defspec

.section "Block and Tagbody"
.setq block-tagbody-section-page section-page

3block* and 3tagbody* together implement the flow-of-control
functionality provided by standard 3prog*.  3prog* could have
been implemented as a macro in terms of these and 3let*,
and in fact is described in that fashion by lan{common lisp}.

.defspec block name {declaration}* {form}*
3block* evaluates the 2forms*.  If a lexically apparent
3return-from* is evaluated with a tag of 2name* (or 2name*
is 3nil* and a 3return* is evaluated), then the value(s) of
the form given to 3return* or 3return-from* are returned as
the value of the 3block* form.  Otherwise, the 3block* form
returns the value(s) of the evaluation of the last 2form*.
.end_defspec

.defspec return form
Evaluates 2form*, and returns the value(s) it returns from the
nearest lexically apparent 3block* with a name of 3nil*.  Many
special forms implicitly establish blocks named 3nil*, such as
3do*, 3dolist*, 3dotimes*, 3dovector*.

Note that this differs subtly from lan{zetalisp}.  In
lan{zetalisp}, 3return* returns from the innermost 3prog*
(i.e., block) which is 2not* named 3t*.  In lan{nil} (and
lan{common lisp}), a 3return* to a block name of 3nil* only
matches a block name of 3nil*, and the block name 3t* is not
distinguished in any way.
.end_defspec

.defspec return-from name form
Evaluates 2form*, and returns the value(s) it returns from the
nearest lexically apparent 3block* with a name of 2name*.
2name* is not evaluated.
.end_defspec

.defspec tagbody {tag | form}*
The body of a tagbody is examined sequentially.  If a form is atomic,
then it is a tag and is ignored, otherwise it is evaluated.  If during the
evaluation a lexically apparent call to 3go* is evaluated with an
argument of one of the tags, then control is returned to that point
within the 3tagbody* form, which resumes its interpretation.  If
the interpretation reaches the end of the 3tagbody*, the result is
3nil*.
.end_defspec

.defspec go tag
2tag* is not evaluated.  Control is returned to the nearest
lexically apparent 3tagbody* form with a tag name of 2tag*,
which resumes interpretation of the tagbody at the form following that
tag.
.end_defspec

.defspec prog varlist {declaration}* {tag | form}*
Standard 3prog*.  2varlist* may be a list of variables, or a
list of lists of variables and their initial values.  They will be
bound in parallel.  3prog* can be built from the above primitives:
.lisp
(let 2varlist*
   2the declarations*
   (block nil
     (tagbody 2the tags and forms*)))
.end_lisp

For compatibility with lan{zetalisp}, if the first "argument" to
3prog* is a non-null atom, then that is used as the name of the
block, with the varlist following.
.end_defspec


.defmac loop gubbish...
3loop* is described in another document ref{LOOP}.  It is noted
here because it deals correctly with the incompatibilities between
lan{zetalisp} and lan{common lisp} blocks and returns.
.end_defmac

.section "Generalized Variables"

.defmac setf place value
3setf* is a general macro which is used to modify things.
2place* is a form which describes the place to be modified;  it
may be something like 3x*, a variable, 3(car
2something*)*, or even a user-defined structure reference.  It
expands into code which will modify that 2place* to be
2value*, additionally guaranteeing that the return value of the
3setf* form is that value.  Thus, one may use
.lisp
(setf (car l) 'foo)
.end_lisp
instead of 
.lisp
(rplaca l 'foo)
.end_lisp
The utility of this is that the special functions (if indeed there are
any) necessary to perform the specified updating need not be known
about.  In fact, lan{common lisp} does not even define most updating
functions, only that the referencing functions may be used with
3setf*.

If 2place* is a variable, then 3setf* is equivalent to
3setq*.  2place* may also be any car/cdr function, sequence
function (such as 3nth*, 3elt*, 3vref*, and 3bit*), or
any structure accessor defined by either 3defflavor* (which is not
described here) or 3defstruct* (in the Maclisp Extensions Manual,
ref{Maclisp-Extensions}).
.end_defspec


.chapter "List Manipulation"

.defun car
.defun1 cdr
.defun1 c****r
3car* and 3cdr* combinations to 4 deep, as in lan{maclisp}.
.end_defun

.defun cons x y
.defun1 ncons x
.defun1 xcons x y
.defun1 list* e1 e2 e3 ... en last-cdr
.defun1 list e1 e2 e3 ... en
.end_defun

.defun append {list}*
.lisp
(append '(a b c) '(d e f)) => (a b c d e f)
.end_lisp
All but the last of the 2list*s are copied.
.end_defun

.defun nconc {list}*
Concatentates the lists, destructively;  the last 3cdr* of each is
bashed to point to the following list.
.lisp
(setq a '(a b c))
(setq b nil)
(setq c '(d e f))
(nconc a b c)
   => (a b c d e f)
a  => (a b c d e f)
b  => nil
c  => (d e f)
.end_lisp
.end_defun

.defun nth index list
Returns the 2index*th element of 2list*, zero-origined.
3nth* is compatible with the 3nth* of lan{maclisp} and
lan{zetalisp}, and differs from that of lan{interlisp}.  Note that
the argument order differs from that used for most other
sequence-accessing functions defined by lan{nil} and lan{common
lisp}.
.end_defun

.defun nthcdr index list
Returns the result of 3cdr*ing 2list* 2index* times.
.end_defun

.defun last list
Returns the last 3cons* of 2list*, unless 2list* is
3nil* in which case 3nil* is returned.
.end_defun


.defun nreconc list other
This destructively reverses 2list* and bashes its last 3cdr*
to be 2other*;  that is, it is like doing
.lisp
(nconc (nreverse list) other)
.end_lisp
.end_defun

Certain other list operations, such as fun_i{reverse} and
fun_i{nreverse}, are actually generic sequence operations, described
in (sequence-section-page).

.section "Using Lists as Sets"

One common use of lists is as sets of objects.  lan{nil} (and
lan{common lisp}) provide a complement of functions for doing this.

All of the functions take similar arguments.  Normally, they use
3eql* as their predicate, so that they work on numbers properly
also.  If this is not suitable for the purpose, then a predicate may
be specified by giving it as the 3:test* keyworded argument.  For
instance,
.lisp
(union '((a b) (b) (c)) '((d) (e) (a b) (b)) :test #'equal)
  => ((a b) (b) (c) (d) (e))
.end_lisp
The sense of the predicate can be reversed by using 3:test-not*
instead of 3:test*.

Sometimes the elements of the set are datastructures of some sort, and
one desires to only compare one part of the datastructure, but not
write a predicate to compare things.  If the 3:key* keyworded
argument is used, then that is a function which will be applied to
each element as it is tested, and the results of that will be given to
the equality predicate, rather than the elements themselves.  For
example,
.lisp
(union '((a) (b) (c)) '((d) (e) (a) (b)) :key #'car)
  => ((a) (b) (c) (d) (e))
.end_lisp
The ordering of the result may not be depended on;  neither may the
result if either of the inputs contains duplicate elements (as defined
by the predicate).

.defun union list1 list2 &key :test :test-not :key
Returns the union of 2list1* and 2list2*.
.end_defun

.defun intersection list1 list2 &key :test :test-not :key
Returns the intersection of 2list1* and 2list2*.
.end_defun

.defun set-difference list1 list2 &key :test :test-not :key
Returns the set difference of 2list1* and 2list2* (a list of
the elements of 2list1* which are not present in 2list2*,
according to the predicate).
.end_defun

.defun set-exclusive-or list1 list2 &key :test :test-not :key
Returns a list of the elements which occur in either 2list1* or
2list2*, but not both, according to the predicate.
.end_defun


.defun subsetp list1 list2 &key :test :test-not
Returns 3t* if 2list1* is a subset of (but not necessarily a
proper subset of) 2list2*, 3nil* otherwise.
.end_defun


.chapter "Symbols"

.defun get symbol indicator
Although 3get* works on "disembodied property lists" for
lan{maclisp} and lan{zetalisp} compatibility, it treats a first
argument which is neither a symbol nor a list as an error.
(lan{maclisp} 3get* will return 3nil* for other objects.)
.end_defun

.defun putprop symbol value indicator
As in lan{maclisp}, works on both symbols and disembodied property
lists.
.end_defun

.defun remprop symbol indicator
lan{maclisp}-compatible 3remprop*.  If 2symbol* (which may
also be a disembodied property list) has an 2indicator* property,
it is spliced out of the property list, and the subpart of the
property list whose 3car* is (was) the value for that indicator is
returned.  If there is none, 3nil* is returned.
.end_defun

.defun plist symbol
Returns the propertly list of 2symbol*.  Does 2not* work on
disembodied property lists.
.end_defun

.defun setplist symbol new-plist
Bashes the property list of 2symbol* to be 2new-plist*.  Does
2not* work on disembodied property lists.  Use of this should
normally be left to only those functions which carefully interlock
addition and deletion from the property list, to avoid both timing
screws and elimination of properties needed by "someone else".
.end_defun


.chapter "Numbers"

lan{nil} numbers may be integers, floating-point, ratios, or even
complex.  Most arithmetic functions operate on any types, and convert
as necessary;  in general, contagion proceeds from integer -> ratio ->
float -> complex.  For the operations performed on the real and
imaginary parts of complex numbers, the conversion is similar.

Complex numbers in lan{nil} are on the order of days old.  Although
they exist, they will not be supported by most functions in lan{nil}
for some time.

.defun = number &rest more-numbers
.defun1 /= number &rest more-numbers
Return 3t* if all of the numbers (in all pairwise combinations)
are equal or not-equal respectively.  Performs type conversions as
necessary to do the comparisons.
.end_defun

.defun < number &rest more-numbers
.defun1 <= number &rest more-numbers
.defun1 >= number &rest more-numbers
.defun1 > number &rest more-numbers
The numbers must all be real numbers.  Each function returns 3t*
if all consequetive pairs of arguments satisfy the appropriate
comparison.  Type conversions are performed as necessary to do the
comparisons.
.end_defun

.defun zerop number
3t* if 2number* is integer, floating, or complex 30*,
3nil* otherwise.
.end_defun

.defun plusp real-number
.defun1 minusp real-number
.end_defun


.defun 1+ number
.defun1 add1 number
Adds one to 2number*.
.end_defun

.defun 1- number
.defun1 sub1 number
Subtracts one from 2number*.
.end_defun

.defun + &rest numbers
.defun1 plus numbers
Adds together the numbers.
.end_defun

.defun - number &rest more-numbers
3(- 2number*)* performs unary negation on 2number*.
With more than one argument, it subtracts the sum of the rest from the
first.
.end_defun

.defun difference &rest numbers
Subtly different from 3-*; 3difference* is lan{maclisp}
compatible.  If there are no 2numbers*, 30* (the identity) is
returned. Otherwise, the sum of all the numbers but the first is
subtracted from the first.  That is, 3(difference 2x*)* =>
2x*, not 3(- 2x*)*.
.end_defun

.defun * &rest numbers
.defun1 times &rest numbers
Returns the product of all the 2numbers*.  If none are given,
3** returns 31*, the multiplicative identity.
.end_defun

.defun / number &rest more-numbers
3(/ 2number*)* returns the inverse of 2number*.
Otherwise, 3/* divides the first by the product of the rest.  If
all of the involved quantities are integers, then 3/* will produce
a ratio rather than truncating the answer (as 3quotient* does).
.end_defun

.defun quotient &rest numbers
If there are no 2numbers*, then 2quotient* returns 31*,
the multiplicative identity.  Otherwise, it divides the first by the
product of the rest;  with exactly one argument, that argument is
returned.  If all of the involved quantities are integers, then
3quotient* will return a truncated integer result, rather than
convert to either a ratio or a floating result.  This is compatible
with lan{maclisp}.
.end_defun

.defun remainder integer1 integer2
3(remainder 2n1* 2n2*)* => 2r*, such that
.lisp
(plus (times (quotient 2n1* 2n2*) 2n2*) 2r*) => 2n1*
.end_lisp
This is lan{maclisp} compatible.
.end_defun

.defun expt base power
Raises 2base* to the power 2power*.  If both are integers the
result will be an integer.  If either are floating, then the result
will be floating, computed by logarithms.
.end_defun

.defun exp number
Raises 2e*, the base of natural logarithms, to the power
2number*.  This currently always uses floating point, and
2number* must be real.
.end_defun

.defun log number &optional base
Returns the logarithm of 2number* in 2base*, which defaults to
2e*.  This currently always uses floating point, so 2number*
and 2base* must be real numbers.
.end_defun

.defun sqrt number
Returns the (principal) square root of 2number*.  This currently
uses only floating point, so 2number* must be real although the
result may be complex.
.end_defun

.defun isqrt integer
Integer square root.  Returns an integer (truncates).
.end_defun

.defun sin radians
.defun1 cos radians
.defun1 tan radians
.defun1 sinh radians
.defun1 cosh radians
.defun1 tanh radians
.defun1 asin real
.defun1 acos real
Standard trig.  Only deal with floating point, hence the arguments
must be real.
.end_defun

.defun atan x &optional y
.end_defun

.section "Logical Operations"

Integers in lan{nil} are all represented in twos-complement
notation.  They may be viewed as a vector of bits extended infinitely;
a negative integer extended with ones, a non-negative integer extended
with zeros.

.defun logbitp bit-number integer
Returns 3t* if the bit at position 2bit-number* is on in
2integer*, 3nil* otherwise.  2bit-number* is
zero-origined, with 0 being the least significant bit.  Thus,
.lisp
(logbitp 0 1)		=>  t
(logbitp 0 -2)		=>  nil
(logbitp 1 1)		=>  nil
(logbitp 259259259 15)  =>  nil
(logbitp 259259259 -2)  =>  t
.end_lisp
.end_defun

.defun logand &rest integers
.defun1 logior &rest integers
.defun1 logxor &rest integers
.defun1 logeqv &rest integers
.defun1 lognand integer1 integer2
.defun1 lognor integer1 integer2
.defun1 logandc1 integer1 integer2
.defun1 logandc2 integer1 integer2
.defun1 logorc1 integer1 integer2
.defun1 logorc2 integer1 integer2
.defun1 lognot integer
These routines supercede the use of the 3boole* function,
providing more mnemonic names.  "c1" and "c2" suffixes can be read as
"-complement-first-arg" and "-complement-second-arg";  thus,
3logandc2* is logical 3and* of the first argument with the
complement of the second argument.
.end_defun

.defun integer-length integer
This returns the size of 2integer*.  This is defined such that
2integer* in twos-complement notation can fit in a field that long
plus one.
.lisp
(integer-length 0)	=>  0
(integer-length -1)	=>  0
(integer-length 1)	=>  1
(integer-length -2)	=>  1
.end_lisp
.end_defun


.section "Conversions"

.defun float number
Converts number to floating-point.
.end_defun

.defun fix number
Converts 2number* to an integer, by 3floor*ing (rounding
towards negative infinity).  This is compatible with lan{maclisp}.
.end_defun


.chapter "Characters"

Here are some of the functions on characters which may be useful.

.defun char-equal character1 character2
Returns 3t* if 2character1* and 2character2* are the same
character, ignoring case, font, and bits, 3nil* otherwise.
.end_defun

.defun char-greaterp character1 character2
Returns 3t* if 2character1* is "strictly less than"
2character2*, ignoring case, font, and bits.  All alphabetic
characters, and all digits, collate in the obvious way with respect to
one another.
.end_defun

.defun character frobozz
Coerces 2frobozz* into a character.
.end_defun

.defun char-code character
.defun1 char-bits character
.defun1 char-font character
These functions return the 2code*, 2bits*, and 2font*
attributes of their argument, as an integer.
.end_defun

.defun code-char code &optional bits font
Returns a character with code attribute 2code*, bits attribute
2bits*, and font attribute 2font*.  2bits* and 2font*
default to 30*.  If it is not possible to construct such a
character (possibly because lan{nil} does not support code, bits, or
font attributes of the values given) then 3nil* is returned.
.end_defun

.defun make-char character &optional bits font
Just like
.lisp
(code-char (char-code 2character*) 2bits* 2font*)
.end_lisp
.end_defun

All characters have unique integer representations.  The following two
functions convert back and forth from integers to characters.  They
are what are used to provide that mapping for the lan{maclisp} I/O
functions which deal with integers rather than characters.

.defun char-int character
Converts 2character* to its integer representation.  By
definition, if 2character* has no (i.e., 30*) 2bits* and
2font* attributes, then 3char-int* is the same as
3char-code*.  3char-int* can be used as a fast hash function
on characters.
.end_defun

.defun int-char integer
This is the inverse of 3char-int*.  If 2integer* is in the
range which might be returned by 3char-int* on some character,
then that character is returned;  otherwise, 3nil* is returned.
.end_defun

There is also a large number of predicates on characters for testing
such things as alphabetic-ness, digit-ness, and for converting back
and forth from digits to integer-weights.  These are all documented in
the lan{nil} release notes and the lan{common lisp} manual
ref{CommonLisp}.

.chapter "Sequences, Strings, and Arrays"

The parts of lan{nil} dealing with sequences, strings, and arrays,
are gradually being brought up to lan{common lisp} specifications.
If more information is needed than is presented here, either the NIL
Release Notes or a bootleg Common Lisp Manual should be consulted.

.section "Sequences"

.setq sequence-section-page section-page
.cindex sequences
A sequence is considered to be either a list or a vector (which is by
definition a one-dimensional array).  A few functions which might be
useful are presented here.

Many sequence function take 2start* and
2end* arguments to delimit some subpart of the sequence being
operated on.  As a general rule, the 2start* is 2inclusive*,
and the 2end* is 2exclusive*;  thus the length of the
subsequence is the difference of the 2end* and the 2start*.
The 2start* typically defaults to 30*, and the 2end* to
the length of the sequence.
Also, the 2end*, where it is an optional argument, may be
explicitly specified as 3nil*, and will still default to the
length of the sequence.

.defun elt sequence index
This is the general sequence access function.  It returns the
2index*th element of 2sequence*;  the index is taken to be
zero-origined.  This will work generally on lists, vectors, strings
(which are by definition vectors anyway), etc.  One may modify an
element of a sequence by using 3setf*.  For instance,
.lisp
(setq v (make-vector 10))
  => #(nil nil nil nil nil nil nil nil nil nil)
(setf (elt v 5) 'foo)
  => foo
.end_lisp
And now,
.lisp
v => #(nil nil nil nil nil foo nil nil nil nil)
.end_lisp
.end_defun

.defun length sequence
Returns the length of 2sequence*.
.end_defun

.defun subseq sequence start &optional end
Returns a sequence of the same type as 2sequence*, containing
elements from 2start* up to (but not including) 2end*.
.lisp
(subseq "foo on you" 4)		=>  "on you"
(subseq "foo on you" 4 6)	=>  "on"
(subseq "foo on you" 4 3)	=>  2is an error*
(subseq '(a b c d) 1 3)		=>  (b c)
.end_lisp
Note that the result of 3subseq* never shares with the original
sequence.  Thus, 3(subseq 2list* 5)* is not the same as
3(nthcdr 5 2list*)*.  In fact, 3subseq* would signal an
error in this case if the 2list* did not have at least 5 elements.
.end_defun

.defun copy-seq sequence
Copies the sequence 2sequence*.  This might be necessary if the
result is going to be modified, for instance.
.end_defun

.defun reverse sequence
Returns a copy of 2sequence*, with the elements in the opposite
order.
.end_defun

.defun nreverse sequence
Reverses 2sequence*, destructively;  it does not create a copy.
Note that if 2sequence* is a list, one should always use the
return value of 3nreverse*;  that is, do something like
.lisp
(setq l (nreverse l))
.end_lisp
rather than just
.lisp
(nreverse l)
.end_lisp
This is in general true for all destructive list operations, such as
3sort* and 3delq*.  The reason is that although the cons cells
of the input list are reused, the pointer returned is not necessarily
the same as the original "first" cons of the list.
.end_defun

.defun make-sequence type size &key :initial-element
Makes a sequence of the given type and size.  The types of most
interest are 3list*, 3string*, 3vector*, and
3bit-vector*.  If the 3:initial-element* keyworded argument is
given, then the sequence is initialized with that element.  Otherwise,
the initialization depends on the type of the sequence.  For instance,
.lisp
(make-sequence 'list 5 :initial-element t)
  => (t t t t t)
(make-sequence 'string 5 :initial-element #\*)
  => "*****"
.end_lisp
.end_defun


.defun concatenate result-type &rest sequences
Creates a sequence of type 2result-type* (as might be given to
3make-sequence*), and stores in it the concatenation of all the
elements of 2sequences*.  For instance,
.lisp
(concatentate 'string "foo" "bar" "baz")
  =>  "foobarbaz"
(concatenate 'list "foo" "bar" '(1 2))
  => (#\f #\o #\o #\b #\a #\r 1 2)
.end_lisp
.end_defun

.defun map result-type function &rest sequences
This is the general sequence mapping function.  Note that this is
different from the lan{maclisp} and lan{zetalisp} 3map*
function, which is renamed to 3mapl* by lan{common lisp}.

The result is a new sequence of type 2result-type* (cf.
3make-sequence*), containing the results of applying
2function* to the elements of 2sequences*.  There must be at
least one 2sequence* specified;  2function* gets as many
arguments as there are sequences--first it gets called on all of the
first (index 0) elements, then on all the second elements, etc.  The
iteration terminates when the end of any of the sequences is reached,
so the result will have the same length as the shortest input
sequence.
.lisp
(map 'list #'cons "abc" '(a b c))
  => ((#\a . a) (#\b . b) (#\c . c))
.end_lisp
.end_defun


.defun some predicate &rest sequences
If the result of applying 2predicate* to the corresponding
elements of 2sequences* is not 3nil*, that value is returned;
otherwise, 3nil* is returned.  The predicate is called with as
many arguments as there are sequences;  first on all of the first
(index 0) elements, etc.  Only the parts of the sequences up to the
length of the shortest are considered.
.end_defun

.defun every predicate &rest sequences
Like 3some*, but returns 3t* if the result of applying
2predicate* to the elements of 2sequences* is never 3nil*,
3nil* otherwise.
.end_defun

.defun notany predicate &rest sequences
Returns 3t* if the result of applying 2predicate* to the
corresponding elements of 2sequences* is always 3nil*,
3nil* otherwise.
.end_defun

.defun notevery predicate &rest sequences
...
.end_defun

.defun fill sequence element &key :start :end
Replaces the elements of 2sequence* with 2element*, from
2start* (default 0) up to 2end* (default length of the
sequence).
.lisp
(setq a '(0 1 2 3 4 5 6))
(fill a nil :start 2 :end 4)
  =>  (0 1 nil nil 4 5 6)
.end_lisp
And now,
.lisp
a  =>  (0 1 nil nil 4 5 6)
.end_lisp
.end_defun

.defun replace sequence1 sequence2 &key :start :end :start1 :end1 :start2 :end2
Replaces the elements of the specified subsequence of 2sequence1*
by the elements of the specified subsequence of 2sequence2*.
.lisp
(setq v (make-sequence 'vector 10))
  => #(nil nil nil nil nil nil nil nil nil nil)
(replace v '(1 2 3 4 5 6))
  => #(1 2 3 4 5 6 nil nil nil nil)
v => #(1 2 3 4 5 6 nil nil nil nil)
.end_lisp

2start* and 2end* are used as defaults for 2start1*,
2end1*, 2start2*, and 2end2*, which otherwise default to
0 and the lengths of the corresponding sequences.  The number of
elements transferred is the length of the shorter subsequence.
.end_defun


.section "Strings"

There is a large complement of string functions in lan{nil}, only a
few of which will be mentioned here.  Mostly they are like those used
in lan{zetalisp}.

.defun string-equal string1 string2 &optional start1 start2 end1 end2
This routine is the basic routine for doing case-independent string
equality tests.  That is,
.lisp
(string-equal "foo" "Foo")  =>  t
(equal "foo" "Foo")	    =>  nil
.end_lisp
As usual, the starts default to 0, and the ends to the lengths of the
strings.  If the lengths of the specified substrings differ, then the
strings are not string-equal.  Note that this function takes
positional rather than keyworded optional arguments, for historical
reasons.
.end_defun

.defun string-lessp string1 string2 &optional start1 start2 end1 end2
Returns 3t* if the specified substring of 2string1* is "less
than" that of 2string2*.  The comparison is case-independent;
effectively, lowercase characters are compared as if they were
uppercase.  If the first substring is a prefix of the second, then it
is "lessp".
.end_defun

.defun substring string start &optional end
Like 3subseq* ((subseq-fun)).  If the specified range is the
entire string, the string may not be copied.
.end_defun

.defun string-upcase string
Returns a copy of 2string*, with all lowercase characters
converted to uppercase.
.end_defun

.defun string-downcase string
Returns a copy of 2string*, with all uppercase characters
converted to lowercase.
.end_defun


.section "Arrays"

lan{nil} supports a large portion of the lan{common lisp} array
specification currently.  The lan{maclisp} compatible array routines
have been lost during the conversion, and have not been re-implemented
yet.  What is described here is a simple subset of what is offered.

In lan{nil}, a one-dimensional array is a vector.  Some types of
arrays have restrictions on the types of objects which can be stored
in them.  For example, arrays which can only hold string characters
are 3string-char* arrays, and if they are one-dimensional (and
hence vectors), they are strings.  An array which can hold any type of
object is termed a 3general* array.  At this time, that is the
most useful type of array (other than the very common special types
3string* and 3bit-vector*), so that is all that will be
discussed here.  Also, obscure, esoteric, and non-working features
have been omitted.

In lan{nil}, an array is an object all its own.  They do not need to
be associated with symbols or treated as functions in any strange way
(as had been the case in lan{maclisp} in the past).

.defun make-array dimensions
This creates an array with the specified dimensions.  2dimensions*
may be either a single non-negative fixnum, or a list of dimensions.
If it is a fixnum, then a one-dimensional array (vector) is created;
otherwise, the created array will have a rank of the number of
dimensions specified.  Thus, a 103x*10 array could be created with
.lisp
(make-array '(10 10))
.end_lisp
.end_defun

.defun aref array &rest indices
Returns the element of 2array* selected by the 2indices*.  The
number of indices must equal the rank of the array, and each index
must be a non-negative fixnum less than the size of the corresponding
dimension.

To update an element of an array, use 3setf* with 3aref*:
.lisp
(setf (aref a i j) new-value)
.end_lisp
.end_defun

.defun array-rank array
Returns the rank (number of dimensions) of 2array*.
.end_defun

.defun array-dimension array dimension-number
Returns the size of the 2dimension-number* dimension of
2array*.  The dimensions are numbered zero-origined;
dimension-number must be non-negative, and less than the rank of
2array*.  If an array had been created by 3(make-array '(2 3
4))*, then its 30* dimension is 32*, its 31* dimension
33*, etc.
.end_defun

.defun array-dimensions array
Returns a list of the dimensions of 2array*.  This could then be
given to 3make-array* to make another array with the same
dimensionality.
.end_defun


.chapter "Input and Output"

.section "Streams"

I/O in lan{nil} uses term_i{stream}s.  The operations performed
are implemented by sending messages to these streams;  there are
various levels of protocol involved, and it sometimes gets quite
complicated.  However, for most ordinary applications, there are
functions which may be used instead, providing a simpler interface,
and some argument defaulting.

There are several variables whose values are the streams used as the
defaults in various contexts.  If the name of the variable ends with
"3-input*", then it is only expected to be used for input;
"3-output*", then only for output;  and "3-io*", then both.

.defvar terminal-io
This is the stream which reads from and writes to the terminal.
.end_defvar

.defvar standard-input
This is the "default input stream", used as a default by functions
which can default a stream argument and expect to use it for input.
Normally, it is bound to a stream which indirects to the value of
3terminal-io*.  Some contexts may bind it, however;  when one is
compiling a file, or loading an interpreted lisp file, it will be
bound to a stream which reads from that file.
.end_defvar

.defvar standard-output
This is the "default output stream", used similarly to
3standard-input*, but for output.  Normally, it is bound to a
stream which indirects to the value of 3terminal-io*;  it may
sometimes be bound to something else, however, potentially even a
stream which "broadcasts" to multiple other streams.
.end_defvar

.defvar query-io
This is a stream used by functions which query the user, such as
fun_i{yes-or-no-p} ((yes-or-no-p-fun)).  Normally it indirects to
the value of 3terminal-io*, although it could conceivably by a
stream which logs the interaction.
.end_defvar

Most of the stream functions (with a couple exceptions) also allow the
stream to be one of the symbols 3t* or 3nil*.  3t* is
taken to mean the value of 3terminal-io*, and 3nil* the
default stream for the operation;  the value of either
3standard-input* or 3standard-output*, depending on whether an
input or output operation is implied.  The main exceptions are the
(lan{maclisp} compatible) fun_i{cursorpos} function (which is not
described here), which defaults to using 3terminal-io*, and the
3format* function ((format-fun)).  Also, some operations do not
inherently have any directionality, so cannot determine the meaning of
3nil* as a stream (none of them are described here anyway).

.section "Basic I/O"

.subsection "Input"

Most input functions take (possibly in addition to some other
arguments) optional 2stream* and 2eof-value* arguments.  If
the stream argument is null or not supplied, the value of
3standard-input* is used;  if it is 3t*, the value of
3terminal-io* is used.  The 2eof-value* argument determines
the behavior of the function if it is reading from a stream which can
run out of data, as a disk file might when the end of the file is
reached.  If no 2eof-value* argument is supplied, then the
function does not handle the end-of-file condition:  an error is
signalled.  Otherwise, that value is returned by the function, in
place of whatever object it would have read.  Note, however, that
end-of-file detected after the start of an object is always an error;
thus, 3read* will always error if there are (say) too few
close-parentheses in the expression, but will return its
2eof-value* if end-of-file is detected before the next lan{lisp}
expression starts.

.defun read-char &optional (stream standard-input) eof-value
Reads one character from 2stream*.
.end_defun

.defun tyi &optional (stream standard-input) eof-value
Reads one character from 2stream*, and returns its integer
representation.  This is provided only for lan{maclisp}
compatibility.
.end_defun

.defun peek-char &optional (stream standard-input) eof-value
Returns the next character to be read from 2stream*, but does not
"advance the pointer".  That is, repeated calls to 3peek-char*
with no intervening calls to 3read-char* will return the same
result, as will a single following call to 3read-char*.
.end_defun

.defun tyipeek etc etc etc
Tries hard to simulate lan{maclisp}-compatible 3tyipeek*.  May
not always succeed.
.end_defun

.defun read &optional stream eof-value
Reads one lan{lisp} expression from 2stream*.
.end_defun

.defun readline &optional stream eof-value
Reads one line of text from 2stream*, and returns it as a string.
The newline is passed over, but is not part of the returned string.
.end_defun

.subsection "Output"

For these functions, a 2stream* argument of 3nil* is the same
as specifying the value of 3standard-output*, and a 2stream*
argument of 3t* the same as specifying the value of
3terminal-io*.  This provides some semblance of lan{maclisp}
compatibility.  (Also a nice abbreviation over using
3terminal-io*.)

.defun write-char character &optional (stream standard-output)
Writes 2character* to 2stream*.  This 2must* be an object
of type 3character*;  a fixnum or a string are not acceptable.
.end_defun

.defun tyo integer-character &optional (stream standard-output)
This is provided for lan{maclisp} compatibility.
2integer-character* must be the integer representation of a
character (see 3int-char*, (int-char-fun));  it is converted to
a character and given to 3write-char*.
.end_defun

.defun princ object &optional (stream standard-output)
Prints 2object* to 2stream*.  If 2object* is a string,
then only the characters contained in the string are output;  if it is
a symbol, then only the characters of the print name are output.
.end_defun

.defun prin1 object &optional (stream standard-output)
This is the basic entry to print a lan{lisp} object in such a way
that it can be read back in again, hopefully.  For the most part, this
means that strings have doublequotes put around them, and maybe have
backslashes preceding contained doublequotes and backslashes, and
symbols have their package printed as a prefix and may have vertical
bars surrounding them if there are any characters in the print name
which would cause the symbol to not be read in as such.
.end_defun

.defun print object &optional stream
.lisp
(defun print (object &optional (stream standard-output))
  (prog2 (terpri stream)
	 (prin1 object stream)
	 (write-char #\space stream)))
.end_lisp
.end_defun

.defun terpri &optional stream
Does a newline on stream.
.end_defun

.defun fresh-line &optional stream
If the "cursor" of 2stream* is not at the beginning of a line,
this does a 3terpri*.  Thus, it can be used to guarantee that
subsequent output starts at the beginning of a line, while not
producing superfluous blank lines.
.end_defun

.defun pretty-prin1 object &optional stream
"Pretty-prints" the 2object*.  The object is assumed to be
lan{lisp} code;  i.e., lists which start with special function names
like 3defun*, 3let*, and 3cond* are treated specially, and
3quote* and 3function* forms are inverted to print out using
the 3'* and 3#'* prefixes.  Note that this does not
start the output on a new line;  this allows one to print a prefix
first.

This pretty-printer goes over the structure it is printing to detect
circularities, and displays them using lan{common lisp} labelling
syntax (which should be fairly obvious when seen).  This labelling is
not understood by the reader, but stops the printer from dying.
.end_defun

.defun pretty-print object &optional stream
3pretty-prin1*, with a 3terpri* first.
.end_defun

.defun format destination control-string &rest arguments
3format* provides ways to produce simple to fancy text output.
A simple call might look like
.lisp
(format t "~&The ~A count was ~D.~%" 'cat 10)
.end_lisp
The 3t* tells format its text to the default output stream (just
like giving 3print* no 2stream* argument).  Within the
2control-string*, a tilde introduces a 3format* directive.
The directives in the above string mean (respectively) go to a new
line if needed, 3princ* an argument (taken from the
2arguments*), print an argument as a decimal number, and output a
newline (3terpri*).  The output from that thus looks like
.lisp
The CAT count was 10.
.end_lisp
3format* differs from the other output functions in how it
interprets its 2destination* argument;  3t* means use the
value of 3standard-output*, and 3nil* means collect the output
and return it as a string.

3format* is almost entirely compatible with the 3format* used
in lan{maclisp} and lan{zetalisp}.  In fact, it uses the same
source as the one used in both lan{pdp-10} and lan{multics}
lan{maclisp} (and has some of the same bugs).  The only things
missing in the lan{nil} version are the operations which deal with
floating-point numbers.  More details on 3format* may be found in
either the Maclisp Extensions Manual ref{Maclisp-Extensions} or the
Lisp Machine Manual;  the former documents this version of
3format* more accurately.
.end_defun

.section "Interacting with the User"

Some functions of potential interest.

.defun y-or-n-p &optional message stream
Prints the string 2message* to the stream, which defaults to the
value of 3query-io*, and then reads a character.  3y-or-n-p*
requires that the character be either 3y* or 3n*, and returns
3t* if it is 3y* or 3nil* if it is 3n*.  It is unusual
to specify the stream argument to 3y-or-n-p*, as the default will
almost always suffice.
.end_defun

.defun yes-or-no-p &optional message stream
Somewhat like 3y-or-n-p*.  The input, however, is an entire line,
which must be either 3yes* or 3no*.  3yes-or-no-p* is
oriented towards unexpected questions which may have significant
consequences or require thought:  it flushes all typeahead, and beeps.
.end_defun

.defun format-y-or-n-p format-string &rest format-args
Like 3y-or-n-p*, but uses 3format* to display
2format-string* with arguments 2format-args*.
.end_defun

.defun format-yes-or-no-p format-string &rest format-args
Like 3yes-or-no-p*, but uses 3format* like
3format-y-or-n-p*.
.end_defun

.defun readline-with-prompt prompt-string &rest read-args
This is a convenient way to read a line of text from the terminal,
with a prompt string.  It is better than printing the prompt yourself
and calling 3readline*, because the input processor knows about
the prompt string and can reprint it as necessary.  2read-args*
are interpreted like 3read* does;  typically, none need to be
given.
.end_defun

.defun read-with-prompt prompt-string &rest read-args
Similar to 3readline-with-prompt*, but uses 3read*.
.end_defun


.chapter "Running and Debugging Programs"

.section "Loading Programs"

.defun load pathname &rest hairy-options
3load* is the general function for loading a file of either
lan{lisp} source or compiled lan{lisp} code into lan{nil}.  If
no file-type (extension) is specified in 2pathname*, then a file
type of 7vasl* (lan{vms} extension 7vas*) is looked for
first, and if that is not found, a file type of 7lisp* (lan{vms}
extension 7lsp*) is tried.  The manner of loading the file is
determined from the file itself, as are various attributes about the
file (such as its readtable and package).

3load* sets the default pathname it uses every time it is called.
Therefore, 3(load "")* effectively repeats the previous call to
3load*.
.end_defun

.section "The Interactive Debugger"
Generally when errors are detected, the error message is printed out,
and the term_i{interactive debugger} is entered.  This is a program
which takes (mostly) single-character commands, and can be used to
poke around the lan{lisp} stack and execution environment.  You can
reconize this, because it always prompts with 3>2n*>dbg>*,
where 2n* is the recursion-level of the debugger.  The 3?*
command prints what other commands are available, and a brief
description of what they do.  The debugger has a "current frame" which
it displays.  Many commands, such as those to display local variables
and arguments, operate with respect to that frame.  Commands may be
given arguments by typing the decimal digits before the command
character.  The most useful commands are
.table 3 250 250
.item D
Examine the next frame down (less recent invocation).
.item U
Examine the next frame up (more recent invocation).
.item A
Print an argument (these are zero-origined).  Because the arguments
are printed with the frame, this is only really useful if the argument
desired was not printed due to truncation of the printout.
.item E
Evaluate an expression (which is prompted for).  If the expression is
a symbol, then it is not actually evaluated;  rather, some information
about it is printed, which includes its current value.  The subtle
difference is to aid in debugging in a lexical environment.  If
3E* is given a numeric argument, then it will give a more detailed
analysis of the variable.
.item R
Prompts for and reads a form, evaluates that in the current lexical
environment, and returns that value as the value of the error function
call (that is, the call to 3error*, 3ferror*, or
3cerror*).
.end_table

.defun debug
The debugger may be entered directly from code by evaluating 3(debug)*.
.end_defun

It is worth noting that the debugger's idea of "down" and "up" is
different from the normal interpretations of stack direction.  This
will someday be fixed, and confuse everybody.

.section "Stepping"

The lan{nil} evaluator contains a hook with which every call into
the evaluator may be trapped.  term_i{Stepping} is when one gets to
interact with each such call, to follow what is happening during the
evaluation process.

.defmac step form
This evaluates 2form* with stepping turned on.  At each internal
3eval* call, control returns to the stepper;  typically, the
stepper then prompts for a command, and continues (or not) depending
on that command.  There are some heuristics for handling certain forms
which cause certain actions, including not waiting for a command.  The
most useful commands are
.table 3 250 250
.item C
Continue stepping (steps into the current form, if that is possible).
.item V
Don't step "into" this form, just evaluate it and show the resulting
value (and then continue as before).
.item N
Don't step "into" this form, don't even show its value;  just evaluate
it and continue.
.item B
Like 3V*, and then enters a break loop.  This is not so useful in
a lexical environment;  it is inherited from a lan{maclisp} stepper.
.c .item D
.c Like 3V*, and then enters the debugger.  This is mainly to give
.c you the ability to use the debugger's variable analyzer to poke at
.c lexical variable values.
.item ?
Lists all the defined stepper commands.
.end_table
.end_defun

.section "Tracing and Breaking"

.defmac break tag &optional (predicate-form t)
3break* evaluates 2predicate-form*, which defaults to 3t*.
If the result of this evaluation is not 3nil*, then it enters a
"break loop".  ";bkpt 2tag*" is printed out, and a recursive
read-eval-print loop is entered.  The prompt for reading says
32n*>break>*, where 2n* is the number of nested
3break* loops currently in force.  Note that 2tag* is not
evaluated.

3break* is one of the older debugging tools around.  It is not
nearly as useful as it had once been, because in a lan{lisp} with
lexically scoped variables, those values are not apparent from the
break loop.  In lan{nil} what is probably more useful would be to
insert explicit calls to 3(debug)* in ones code, rather than to
3break*.
.end_defmac

.defun *break value tag
This is the internal version of 3break* which evaluates both of
its arguments normally.  This is also how you can give a non-constant
2tag* argument to the break loop.
.end_defun

.defmac trace &rest trace-specs
With no arguments, 3trace* returns a list of all currently traced
functions.   Otherwise, it traces each of the functions in the manner
specified by 2trace-specs*.  In the simplest case, a
2trace-spec* is simply the name of a function.  Tracing then will
show the function and the arguments it receives when it is called, and
the value(s) it returns when it returns.

A 2trace-spec* may also be a list of a function name, and options.
For instance,
.lisp
(trace (fact :break))
.end_lisp
will trace the function 3fact*, and enter a break loop when
entering and exiting each call to 3fact*.  On entrance, in this
break loop, the variable 3*trace-break-args** is set to the list
of arguments given to the function;  on exit, to the list of returned
value(s).  Each option may also be a list of the option, and a
predicate;  the predicate receives arguments about the call, and
determines what happens with that option.  This is not developed here.
.end_defmac

.defmac untrace &rest fns
With no arguments, this undoes tracing on all traced functions.
Otherwise, it untraces only those functions specified.  The function
names are not evaluated.
.end_defmac

.defvar *trace-break-args*
When a 3break* loop is entered during function tracing due to the
3:break* option, this holds a
list of the arguments to the function being traced (if the break was
on entrance), or the list of value(s) returned (if the break was on
exit).  Changing this list will change the arguments given or values
returned.
.end_defvar

.section "Exhibiting"
.defun exhibit object
Runs an interactive structure editor on 2object*.  "?" gives a
list of single-character commands.
.end_defun

.section "Printing Definitions"

.defspec pp &optional name
If 2name* is defined as a function, then this pretty-prints the
form used to define it.  If it has a (dynamic) value, then a
3setq* form for that assignment is pretty-printed.  If 2name*
is not supplied, then it defaults to the name given to the previous
call to 3pp*.
.end_defspec

.defspec grindef &optional name
Same as 3pp*.
.end_defspec


.chapter "Steve, the Editor"

.defun ed &optional something
Enters the editor.  Currently, 2something* may only be a pathname;
that file will be read into a buffer (if that has not been done
already), and that buffer selected.  3(ed)* simply enters the
editor, with the same current buffer as the last time it was used.
.end_defun

The lan{nil} editor (which is named lan{steve} for a not
particularly convoluted reason that will not be explained here) is
mostly modeled after lan{its}/lan{tops-20} lan{emacs}
ref{Emacs}.  To the extent possible in the differing programming and
operating system environment, it attempts to be compatible with the
lan{emacs} provided on lan{tops-20}.  (For those familiar with the
lan{its} emacs, this is to allow control-C to be reserved for
interrupt usage under lan{vms};  control-Z is used as the
control-meta prefix.)  People familiar with this lan{emacs} should
be able to skip the remainder of this chapter except for section
(steve-lisp-interaction-css-number);  we are attempting to be
compatible, but it is still experimental.

When lan{steve} is entered, it turns on term_i{passall mode},
effectively disabling all special interpretations of input characters
by lan{vms} (see (vms-section-page), in particular
(passall-mode-page)).  This allows it to make as full use of the
limited characters available with an lan{ascii} keyboard as
possible.

lan{steve} is a term_i{realtime editor}.  That is, inserts text
into the buffer, and updates the display of the buffer contents, as
it is entered.  Most "normal" lan{ascii} characters are set to
simply insert themselves into the buffer;  most "control" characters
are set to do something other operation.

The commands to lan{steve} are based on an extended character set,
similar to the virtual extended character set in lan{emacs}.  That
is, in principal there may be different commands on each of the
characters 2control-A*, 2meta-A*, 2super-A*,
2hyper-A*, 2control-meta-A*, etc.  Because practically
none of these characters can be typed on a normal lan{ascii}
keyboard (the exceptions being only the 2subset* of the control
characters which get specially mapped into the extended character set
as it is), lan{steve} defines certain of the simple control
characters to be prefixes which add the extra bits to the following
character.  The character 3#\altmode* (3escape*), for example,
is 2prefix meta*;  typing the sequence 2altmode* 2a* is
the same as typing 2meta-a*.  Note that the case of the basic
character is irrelevant.

Here are the prefix and dispatch characters defined:
.table 2 250 250
.item Control-^
This is 2prefix control*.  It can be used to type in a control
character which is not part of the lan{ascii} character set, such as
2control-space*.
.item Altmode
2Prefix meta*.  The next character is interpreted with the
2meta* bit added.  Thus, 2altmode* 2altmode* is like
typing 2meta-altmode* (which is the command to enter the
minibuffer).
.item Control-Z
2Prefix control meta*.  The next character is interpreted with
2both* the control and meta bits added.
.item Control-X
This prompts for another character and dispatches off of it, as
opposed to being a bit-prefix.
.end_table
There are no prefix characters defined for the 2super* or
2hyper* bits yet, nor are there any commands defined on such
characters.

.section "Files and Buffers"

lan{steve} is capable of editing multiple files "at the same time";
that is, of maintaing the state of several editors at once.  Each file
being edited is in a buffer of its own, independent of all the others.
The most common commands needed to edit and save files are:
.table 2 250 250
.item C-X C-F -- Find File
This command prompts for a filename.  If lan{steve} already has a
buffer with a pathname which matches the pathname you specify, that is
selected (it becomes the "current buffer", the one you are editing).
If not, a buffer name is generated from the pathname, that buffer is
created (you are asked whether to reuse one if a buffer with that name
already exists), and the file is read into that buffer.
.item C-X C-S -- Save File
This writes the file to the 2buffer filename*, iff the buffer has
been modified.  There is a little "*" which appears as the rightmost
piece of information in the modeline, if the buffer has changed since
it was last read or written.
.item C-X B -- Select Buffer
Prompts for a buffer name (displaying the default, which is what a
null line will select), and selects that buffer, creating it if it
does not exist already.
.item C-X C-B -- List Buffers
Displays a list of all the buffers lan{steve} knows about, and some
information about them.
.end_table
The above are usually all that are needed as file commands for simple
editing uses.

.section "Arguments"

Many commands take signed numeric arguments.  Typically (but not
always) they are used as repeat counts for searches, kills, movement,
etc.  There are a few different ways in which in which arguments may
be accumlated for commands.

Standard argument commands accumulate when used consequetively, and
give the following command an argument of the "decimal" representation
of the accumlated characters.  Both 2control-* and
2control-meta-* digits and hyphen (minus sign) are assigned this
way.  Thus, the sequence 2C-M-2 C-M-3 C-N* runs the control-N
command with an argument of 323*;  presumably, this will move the
cursor down 23 lines.  2C-M-8 ** will insert "********" into the
buffer, and 2C-5 5* will insert "55555".

term_i{auto argument} commands are a slight extension.  They allow
multiple-digit arguments to be typed without having to use argument
commands for any digits but the first.  The 2meta* digits and
hyphen (minus sign) are all auto-arguments.  Thus, to give 2C-N*
an argument of 323*, only 2M-2 3 C-N* need be typed.  The
effect of this is that one only needs to type 2altmode* (i.e.,
2escape*), then the digits, then the command (or character to be
repeated).

The term_i{universal argument}, which is assigned to 2C-U*,
is like auto-argument, and then some.  A numeric argument 323*
could be typed as 2C-U 2 3*.  With no digits (or minus sign),
2C-U* is an argument of 24*;  with or without, subsequent
consequetive 2C-U*s multiply the argument by 34*.  Thus 2C-U
C-U C-N* gives 2C-N* an argument of 316*, 2C-U C-U C-U
C-N* gives it an argument of 364*, etc.

.section "Movement Commands"

.table 2 250 250
.item C-A -- Beginning of Line
Goes to the beginning of the line.
.item C-E -- End of Line
Goes to the end of the line.
.item C-F -- Forward Character
Moves forward one character (or 2argument* characters).
.item C-B -- Backup Character
.item1 Backspace -- Backup Character
Moves backwards one character (or 2argument* characters).
.item M-F -- Forward Word
Moves forward one "word" (or 2argument* words).
.item M-B -- Backward Word
Moves backward one "word" (or 2argument* words).
.item C-N -- Down Real Line
Moves down a line (or 2argument* lines).
.item C-P -- Up Real Line
Moves up a line (or 2argument* lines).
.item C-M-S -- Forward S-Expression
Moves forward one (or 2argument*) lan{lisp} expressions.
.item C-M-P -- Backward S-Expression
Moves backwards one (or 2argument*) lan{lisp} expressions.
.item C-M-A -- Beginning of Defun
Moves to the beginning of the current "defun" (toplevel s-expression).
.item C-M-E -- End of Defun
Moves to the end of the current "defun" (toplevel s-expression).
.item M-< -- Goto Beginning
Goes to the beginning of the buffer.
.item M-> -- Goto End
Goes to the end of the buffer.
.end_table

Movement by screen:
.table 2 250 250
.item C-V -- Next Screen
Goes forward one (visual) screenful.  A couple lines of context are
left.  Giving an argument to this command makes lan{steve} adjust
the displayed portion of the buffer forward that many lines.
.item M-V -- Previous Screen
Similar, only in the other direction.
.item C-L -- New Window
Clears and completely redisplays the screen.
.end_table

.section "Deleting Text"

.table 2 250 250
.item Rubout -- Backward Delete Hacking Tabs
Deletes one (or 2argument*) character backwards.  Tabs are treated
as if they were spaces, so you don't have to know which were in the
buffer.
.item C-Rubout -- Backward Delete Character
Deletes one (or 2argument*) character backwards.  Tabs are
2not* turned into spaces before being deleted.
.item C-D -- Delete Character
Deletes on (or 2argument*) character forwards.
.item M-Rubout -- Kill Word Backward
Deletes one (or 2argument*) word, backwards.
.item M-D -- Kill Word
Deletes on (or 2argument*) word, forwards.
.item C-M-Rubout -- Backward Kill S-expression
Deletes one (or 2argument*) lan{lisp} expressions, backwards.
.item C-M-K -- Kill S-expression
Deletes one (or 2argument*) lan{lisp} expressions, forwards.
.item C-K -- Kill Lines
Deletes lines.  With no argument, kills from the cursor to the end of
the line, unless the cursor is at the end of the line, in which case
the newline itself is killed.  With an argument, kills that many whole
lines.
.end_table

When text (other than single characters) is deleted, it is saved on a
2kill ring*.  Consequetive deletion commands (no other intervening
commands) are saved together, as if only one kill had been performed.
.table 2 250 250
.item C-Y -- Unkill
Restores the text most recently killed.
.item M-Y -- Un-Kill Pop
If what you restored with C-Y was not what you wanted, M-Y will
replace it with the previous block of text killed.  This may be
repeated some number of times.
.end_table

.section "Searching"

.table 2 250 250
.item C-S -- Incremental Search
Reads text from the terminal, and searches for it and updates the
display, as you type in the text.  The search may be repeated by
re-typing C-S, or reversed by typing C-R.  2Rubout* may be used to
delete characters being searched for;  the search then backtracks.
2Altmode* exits the search, leaving the cursor where it was last
shown.  Any "command" character also exits the search, then executes
that command.
.item C-R -- Reverse Incremental Search
Do the same, only backwards.
.end_table

.section "Other Stuff"

Regions, marking, transposition, appending kills, etc. etc. etc.  See
ref{Emacs}...

.section "Interacting with NIL"
.setq steve-lisp-interaction-css-number css-number

.table 2 250 250
.item C-M-Z -- Exit Editor
.item1 C-X C-Z -- Exit Editor
Return from the editor (to its caller).  This is currently always the
caller of 3ed*;  one of these commands, or some other, should
eventually be usurped to return directly to the lan{vms} lan{cli}.
.item M-Z -- Zap to Lisp
The current 3defun* (actually, toplevel s-expression the cursor is
contained within or immediately after) is evaluated.  This is
convenient to selectively evaluate a fixed-up form in a file which has
already been loaded.
.item M-X Compile-Sexp
Similar to M-Z, but 2compiles* the form instead.
.item M-X Compile-This-File
Compiles the file being edited (offering to save it first if
necessary).
.end_table


.page
.start_references

.defref CommonLisp
Steele, G. L., 2Common Lisp Reference Manual*, Carnegie-Mellon
University Department of Computer Science Spice Project,  (in
preparation).
.end_defref

.defref CommonLisp-Overview
Steele, G. L., 2et al.*, 2An Overview of Common LISP*,
paper presented at 1982 ACM symposium on LISP and Functional
Programming.  1982 ACM 0-89791-082-6/82/008/0098.  This can be copied
for the curious.
.end_defref

.defref LMMan
Weinreb, D., and Moon, D., 2Lisp Machine Manual*, (mitai),
(July 1981).  A newer edition of this is available from the AI
Publications Office.
.end_defref

.defref LOOP
Burke, G. S. ,and Moon, D., 2Loop Iteration Macro*, TM-169,
(mitlcs), (January 1981).  Available from the LCS Publications Office.
.end_defref

.defref Maclisp-Extensions
Bawden, A., Burke, G. S., and Hoffman, C. W., 2Maclisp
Extensions*, (mitlcs) TM-203, July 1981.  Available from the LCS
Publications Office.
.end_defref

.defref Moonual
Moon, D. A., 2MACLISP Reference Manual*, (mitlcs), (1974).
Reprints of portions of this are available from the LCS Publications
Office.
.end_defref

.defref NIL-0.5
Burke, G. S., Carrette, G. J., and Eliot, C. R., 2NIL
Notes for Release 0.5*, (mitai), Working Paper, in preparation.
.end_defref

.finish_references

