+-----------------------------------+
             |                                   |
             |    U T I L I S P   M A N U A L    |
             |                                   |
             +-----------------------------------+
 
 
 
 
 
 
 
 
 
 
 
 
 
 
                      Takashi  Chikayama
 
 
                Information Engineering Course
 
                      University of Tokyo
 
 
 
                      Modified for MTS by
 
                       Michael Alexander
 
                  The University of Michigan 
 
 
 
 
 
 
 
 
 
 
 
 
Contents                                          Sep. 8, 1981
 
 
 
                      Table  of  Contents
 
 
 
 1.  Introduction   ...................................   1
 
   1.1 General Information   ..........................   1
   1.2 How to Run and Stop the System   ...............   1
   1.3 Notational Conventions and Notes on Syntax   ...   2
   1.4 Data Types   ...................................   4
   1.5 Lambda Lists   .................................   5
 
 2.  Predicates   .....................................   7
 
   2.1 Predicates on Data Types   .....................   7
   2.2 General Purpose Predicates   ...................   8
 
 3.  Evaluation   .....................................   9
 
   3.1 The Evaluator   ................................   9
   3.2 Various Functions Concerned with Evaluation   ..   9
 
 4.  Flow of Control   ................................  13
 
   4.1 Conditionals   .................................  13
   4.2 Iteration   ....................................  15
   4.3 Non-local Exits   ..............................  18
   4.4 Mapping   ......................................  19
 
 5.  Manipulating List Structure   ....................  22
 
   5.1 Cons manipulation   ............................  22
   5.2 List Manipulation   ............................  23
   5.3 Alteration of List Structure   .................  25
   5.4 Tables   .......................................  26
   5.5 Sorting   ......................................  29
   5.6 Hashing   ......................................  29
 
 6.  Symbols   ........................................  30
 
   6.1 The Value   ....................................  30
   6.2 The Definition   ...............................  31
   6.3 The Property List   ............................  32
   6.4 The Print Name   ...............................  33
   6.5 Creation of Symbols   ..........................  33
 
 7.  Numbers   ........................................  34
 
   7.1 Numeric Predicates   ...........................  34
   7.2 Conversion Functions   .........................  36
   7.3 Arithmetics   ..................................  36
   7.4 Logical Operations on Numbers   ................  38
 
 8.  Strings   ........................................  39
 
   8.1 Characters   ...................................  39
   8.2 String Manipulation   ..........................  40
   8.3 Manipulation of Characters in Strings   ........  42
 
                         Contents - 1
 
 
Sep. 8, 1981                                          Contents
 
 
 
   8.4 Converting Strings and Numbers   ...............  43
   8.5 Bit String Manipulation   ......................  43
 
 9.  Vectors   ........................................  44
 
   9.1 Vector Manipulation   ..........................  44
   9.2 References   ...................................  45
 
 10.  Macros   ........................................  47
 
   10.1 Evaluation of Macros   ........................  47
   10.2 DEFMACRO Facility   ...........................  48
   10.3 Backquote Facility   ..........................  49
 
 11.  Input and Output   ..............................  50
 
   11.1 Streams   .....................................  50
   11.2 Allocating Files   ............................  52
   11.3 Printed Representation   ......................  53
     11.3.1 The Printer   .............................  54
     11.3.2 The Reader   ..............................  56
     11.3.3 The Readtable   ...........................  58
     11.3.4 Setting Readtable   .......................  59
   11.4 Input Functions   .............................  60
   11.5 Output Functions   ............................  61
   11.6 Formatted Printing   ..........................  61
   11.7 Indented Printing   ...........................  62
 
 12.  Code Pieces   ...................................  64
 
 
 13.  Compilation   ...................................  65
 
   13.1 Compiling Functions   .........................  65
   13.2 Declaration   .................................  66
   13.3 Storing Compiled Objects   ....................  67
   13.4 Difference from the Interpreter   .............  67
   13.5 Providing Space for Compiled Codes   ..........  67
 
 14.  Errors and Debugging   ..........................  68
 
   14.1 The Error System   ............................  68
   14.2 Attention Handling   ..........................  71
   14.3 The Debugger   ................................  71
   14.4 The Low-Level Debugger   ......................  72
 
 15.  Memory Management System   ......................  73
 
 
 16.  Structure Editor - USE   ........................  75
 
   16.1 Invoking USE   ................................  75
   16.2 USE Session   .................................  76
   16.3 Scope and Position Numbers   ..................  77
   16.4 Pattern Matching Rules   ......................  77
   16.5 Printing Current Scope   ......................  78
   16.6 Changing the Scope   ..........................  78
   16.7 Searching   ...................................  79
 
                         Contents - 2
 
 
Contents                                          Sep. 8, 1981
 
 
 
   16.8 Inserting and Deleting Parentheses   ..........  79
   16.9 Inserting and Deleting S-expressions   ........  80
   16.10 Replacing S-expressions   ....................  81
 
 17.  Calling External Programs   .....................  82
 
   17.1 Calling TSS Commands   ........................  82
   17.2 Calling User-Defined Programs   ...............  82
   17.3 Manipulating Command Symbols   ................  83
 
 18.  Miscellaneous   .................................  84
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
                         Contents - 3
 
 
May 18, 1981                                   1. Introduction
 
 
 
 
 
1.  Introduction 
 
 
1.1 General Information 
 
The  UTILISP  (University of Tokyo Interactive LISt Processor)
system  is  designed  for  highly  interactive programming and
debugging of sophisticated programs. 
 
This  document is intended to serve both as a User's Guide and
as  a Reference Manual for the language and the system.  It is
hoped  that  those who are familiar with the Lisp language can
acquire a complete knowledge of the system from this manual. 
 
This  is  a preliminary version.  Several sections are missing
and these will be supplied in the near future.  Please consult
the author for information concerning these missing sections. 
 
The author's address is as follows: 
 
     Takashi Chikayama
 
     ICOT Institute for New Generation Computer Technology
     Mita Kokusai Bldg. 21F
     4-28 Mita 1-Chome
     Minato-ku, Tokyo 108, Japan
 
     Telephone: 03-456-3195
 
 
 
1.2 How to Run and Stop the System 
             (Note:  This section may be altered.)
 
At present, the system is in operation at the Computer Centre,
University of Michigan, and is organized as  a  MTS  program. 
The  standard  command  sequence  for  running  the  system is
currently as follows:
 
     #Run *UTILISP 
     > (Lisp input)
 
Several optional parameters exist for the command LISP, i.e.:
 
STACK: STACK=n specifies that the size of the stack area is to
     be n pages (1page = 4KB).  The default  value  for  n  is
     16. 
 
FIX: FIX=n  specifies  that  the size of the "fixed heap" area
     (for compiled codes) is to be n pages.  The default value
     for n is 8. 
 
SIZE: SIZE=n  specifies  that  n pages are to be allocated for
     use by UTILISP.  It will not get more space  if  this  is
     not enough.  The default value for n is 64. 
 
 
81-09-07                     - 1 -              Utilisp Manual
 
 
1. Introduction                                   May 18, 1981
 
 
 
If  the  logical  I/O  unit  0  has  been  assigned,  the file
associated with it  is  executed  first.   This  execution  is
identical  with  that  of  the  standard  top-level Lisp loop,
except that the results are not displayed. 
 
 
After  the  execution of the unit 0  file (if any), the system
enters  the  top-level  loop.   Each  S-expression  read in is
evaluated  and  the  result  is displayed.  Note that the top-
level evaluator is EVAL, not EVALQUOTE. 
 
The  session  can  be terminated by calling the function QUIT.
If  one  wishes  to  terminate  the  session  abnormally,  the
function ABEND can be used. 
 
There  are  cases  in  which  these  system  functions are not
recognized  by  the  Lisp  reader, e.g., when the READTABLE or
OBVECTOR  has  been  destroyed.   In  such  cases, the Utilisp
session can be terminated by ten consecutive exclamation marks
(!!!!!!!!!!)  at  the  beginning  of  an  input  line from the
terminal. 
 
In  case  an  endless  or unexpectedly long computation should
occur,  an  attention  interrupt from the terminal (usually by
means  of the break key) will stop the current computation and
the system enters the BREAK loop.  For details, see Chapter 14
(Errors and Debugging). 
 
 
1.3 Notational Conventions and Notes on Syntax 
 
There  are  several  conventions  concerning  notation,  which
should  be  understood  before  reading the manual in order to
avoid confusion. 
 
In  this  manual,  Lisp  symbols  are  printed  in  upper-case
characters.    Lower-case  words  appearing  in  S-expressions
represent  certain  Lisp  objects  the  details  of  which are
irrelevant  or  explained  elsewhere.  They appear between the
symbols "<" and ">", e.g., . 
 
In what follows, a Lisp object whose "car" is  and "cdr" is
  may  sometimes be written in the form (a .  b).  However,
note  that  and, especially,  are not necessarily atoms.
Thus, a list beginning with the symbol PROGN may be written in
the  form  (PROGN  .   body), where  is a list following
PROGN.   Similarly,  in  titles  of descriptions of functions,
"PLUS  .   args",  for  example,    indicates  a list of
arguments following the function PLUS. 
 
Lisp  symbols  appearing  as  titles  are  followed  by a term
indicating  its  category  within curly brackets, "»" and "º",
(if  it  is not an ordinary function) and a description of its
arguments  (if  it  is  not  a  variable).   Specifically, the
categories  are  "Special Form", "Macro", and "Variable".  The
following   examples   illustrate  the  manner  in  which  the
arguments are described: 
 
 
Utilisp Manual               - 2 -                    81-09-07
 
 
May 18, 1981                                   1. Introduction
 
 
 
QUOTE  »Special Formº arg
     QUOTE is a "special form" and takes one argument. 
 
CONS  x y
     CONS  is an ordinary function and requires two arguments,
      and , and their absence generates an error. 
 
GENSYM  (prefix) (begin)
     GENSYM  may  take  zero  to  two  arguments;  and
      are optional. 
 
PLUS  . args
     PLUS may take arbitrarily many (possibly zero) arguments.
 
-  arg . args
     - may take arbitrarily many (but at last one) arguments. 
 
As  in the examples, argument names appear between "<" and ">"
in the description of the function. 
 
The  symbol  "=>"  will  be  used  to  indicate  evaluation in
examples,  e.g.,  "FOO  =>  NIL"  means  that  "the  result of
evaluating FOO is NIL". 
 
There  are  several terms which are widely used in this manual
but   will   not   be  rigorously  defined.   They  are:   "S-
expression",  which  means  a  Lisp  object, especially in its
printed  representation;  "dotted pair", which means a "cons";
and  "atom",  which  means  a Lisp object other than a "cons".
Note  that  an atom does not necessarily mean a symbolic atom;
it may be a number, string, etc.  It is recommended that those
who  are  not familiar with these terms consult an appropriate
Lisp textbook. 
 
Several  characters  have  special  meanings in UTILISP, i.e.,
single  quote('),  double  quote("),  backquote(`),  comma(,),
semicolon(;), and slant(/). 
 
Semicolons  are  used  for  comments.   When  the  Lisp reader
encounters   a   semicolon,  it  ignores  all  the  characters
remaining  on  the  current  line and resumes reading from the
beginning  of the next line.  In such a case, a blank space is
automatically introduced between the last symbol preceding the
semicolon  and  the first symbol on the next line.  However, a
semicolon  can occur as an element of a string (see remarks on
double quotes below). 
 
A  single  quote  "'"  has the same effect as the special form
QUOTE  (see below).  For example, 'FOO is read as (QUOTE FOO),
and  '(CONS  'FOO  'BAR)  is  read as (QUOTE (CONS (QUOTE FOO)
(QUOTE BAR))), etc. 
 
Slants  are  used  for  quoting  characters possessing special
functions  so  that  they  are  merely  interpreted  as normal
alphabetic characters.  For example, /'FOO is read as a symbol
whose  print name is "'FOO" and not as (QUOTE FOO).  Thus, one
must type "//" to convey the symbol "/" to the Lisp reader. 
 
 
81-09-07                     - 3 -              Utilisp Manual
 
 
1. Introduction                                   May 18, 1981
 
 
 
Double quotes are used for indicating strings.  Any characters
occurring between a double quote and the next double quote are
read  as  a  string.   Double  quotes occurring inside strings
should  be typed twice.  For example, """" represents a string
consisting  of  one  double quote.  A string may extend beyond
the ends of a line. 
 
Concerning backquotes and commas, see Chapter 10 (Macros). 
 
 
1.4 Data Types 
 
There  are nine data types in this system, i.e., symbol, cons,
fixnum,  flonum,  string,  vector, reference, stream, and code
piece. 
 
A  symbol  has  a  "print name", a "value" (sometimes called a
"binding"),  a  definition,  and  a property list.  The "print
name"  is  a  string  which is the value of the function PNAME
when  applied to the symbol in question; this string serves as
the  printed representation of the symbol.  The "value" may be
any Lisp object, and is interpreted as the value of the symbol
when the latter is used as a variable.  The symbol may also be
in  "unbound"  state,  in  which case, it has no value at all.
Access  to the value of a symbol is effected by evaluating the
symbol,  and  the  value  may be updated by using the function
SET.   The  definition is functional attributes of the symbol;
access is effected by GETD and updating by PUTD.  The property
list  contains  an  even  number  of elements (possibly zero);
direct  access  and  updating  can  be  effected  by PLIST and
SETPLIST,  respectively,  but it is usually more convenient to
use  the  functions  GET (for access), PUTPROP (for adding and
updating  properties),  and REMPROP (for removing properties).
SYMBOL  is the basic function for creating a new symbol with a
certain  print  name.   All symbols which are normally read in
are  registered in a table called "obvector", and any of these
which  bear  the  same  name  are  identified  by means of the
function  INTERN  (for  details,  see  Chapter  11, "Input and
Output").   The  function GENSYM serves to generate a sequence
of distinct symbols. 
 
A "cons" is a Lisp object possessing two components, "car" and
"cdr",  which  can  be  any Lisp objects.  Access to these two
components   is   effected  by  the  functions  CAR  and  CDR,
respectively, and updating by RPLACA and RPLACD, respectively.
A "cons" may be constructed by means of the function CONS. 
 
There  are two kinds of numerical objects in this system, upon
which  arithmetical operations may be performed; one is called
"fixnum"  which  possesses  24-bit  signed  integer value; the
other is called "flonum" which possesses 64-bit floating point
value with the accuracy of about 15 decimal digits. 
 
A  string  is a finite sequence of characters.  Each character
has  an  8-bit code value which is usually interpreted interms
of  the  EBCDIK  code.   Independent access to and updating of
these  characters  can  be  effected by means of the functions
SREF  and  SSET,  respectively.  The length of a string can be
 
Utilisp Manual               - 4 -                    81-09-07
 
 
May 18, 1981                                   1. Introduction
 
 
 
obtained by applying the function STRING-LENGTH. 
 
A vector is a finite ordered set of Lisp objects.  Vectors can
be  created  by means of the function VECTOR.  The elements of
such  a  vector may be any Lisp objects; access is effected by
means  of the function VREF and updating by the function VSET.
The  length  of a vector can be obtained by using the function
VECTOR-LENGTH. 
 
A  reference  is  a pointer indicating an element of a vector.
It  is  often  useful to have access to and update elements of
vectors.    A   reference  can  be  created  by  the  function
REFERENCE; access to and updating of the corresponding element
can  be  effected  by means of the functions DEREF and SETREF,
respectively. 
 
A  stream is an object related to I/O.  All the I/O operations
in  this  system are carried out by means of such intermediary
streams, which are created by the function STREAM. 
 
A  code  piece  is a segment of machine code which constitutes
the  body of a predefined or a compiled function.  Code pieces
have names, normally a symbol, access to which can be effected
by means of the function FUNCNAME. 
 
 
1.5 Lambda Lists 
 
A  lambda-expression  is  the format specifying an interpreted
function in Lisp, and is of the form 
     (LAMBDA lambda-list . body)
where   is a list of forms.  Usually,  is a
list  of  symbols  which  corresponds  to the so-called formal
parameter list in certain other programming languages.  When a
lambda-expression  is applied to given values of the arguments
(actual  parameters),  the  symbols are bound to these values,
and  the  forms constituting  are evaluated sequentially
and the result of the last of these evaluations is returned as
the  final  result  of the application.  The formal parameters
are  then  unbound  and revert the state they were in prior to
the  application.   If  the  number of actual arguments is not
equal to the length of , an error is generated. 
 
In UTILISP, an element of  can be either a symbol
or a list of the form 
     (symbol . defaults)
When  the  number of actual arguments to which the function is
applied  is  less  than the length of , the given
actual arguments are first bound to the corresponding symbols.
The  remaining  elements  of   must have the form
(symbol  .   defaults).   Here,   is a list of forms
which  are  evaluated  sequentially and the result of the last
one  (or NIL in the case when  is empty) is bound to
.   If  an  actual  argument corresponding to a symbol
associated with a list  is supplied, then the symbol
is  bound  to  this  actual  argument  and the associated list
 is merely ignored. 
 
 
81-09-07                     - 5 -              Utilisp Manual
 
 
1. Introduction                                   May 18, 1981
 
 
 
Default   values  are  evaluated  after  the  binding  of  the
preceding  arguments,  hence, they may depend upon the results
of the preceding bindings. 
 
Some examples of lambda-lists are as follows: 
 
(A B C) : 
     A, B, and C are all required. 
 
(A B (C)) : 
     A and B are required but C is optional; the default value
     of C is NIL. 
 
(A B (C 0)) : 
     A and B are required but C is optional; the default value
     of C is 0. 
 
(A B (C (PRINT "Default value is used for C.") 0)) : 
     A  and B are required and C is optional; when the default
     value is used, the indicated message is printed. 
 
(A B (C (CONS A B))) : 
     A and B are required and C is optional; the default value
     of C depends upon A and B. 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Utilisp Manual               - 6 -                    81-09-07
 
 
May 17, 1981                                     2. Predicates
 
 
 
 
 
2.  Predicates 
 
 
A  predicate  is  a  function which tests the validity of some
condition  involving its arguments and returns the symbol T if
the condition holds, and the symbol NIL otherwise. 
 
When  a  Lisp  object  is  used  as  a  logical  value,  it is
interpreted  as  "false"  if  and  only if it is NIL; all Lisp
objects other than NIL are interpreted as "true". 
 
 
2.1 Predicates on Data Types 
 
The  following  predicates  are for testing data types.  These
predicates  return  T if the argument is of the type indicated
by the name of the function, NIL if it is of some other type. 
 
 SYMBOLP  arg
     Returns T if  is a symbol, otherwise NIL. 
 
 CONSP  arg
     Returns T if  is a "cons", otherwise NIL. 
 
 LISTP  arg
     LISTP  is an alias of CONSP.  This is incorporated mainly
     for compatibility with other Lisp systems. 
 
 ATOM  arg
     Returns T if  is not a "cons", otherwise NIL. 
 
 FIXP  arg
     Returns T if  is a "fixnum" object, i.e., an integer
     number, otherwise NIL. 
 
 FLOATP  arg
     Returns  T  if    is  a  "flonum"  object,  i.e.,  a
     floating-point number, otherwise NIL. 
 
 NUMBERP  arg
     Returns  T if  is a numerical object, i.e., either a
     "fixnum" or a "flonum", otherwise NIL. 
 
 STRINGP  arg
     Returns T if  is a string, otherwise NIL. 
 
 VECTORP  arg
     Returns T if  is a vector, otherwise NIL. 
 
 REFERENCEP  arg
     Returns T if  is a reference pointer, otherwise NIL.
 
 STREAMP arg
     Returns T if  is a stream, otherwise NIL. 
 
 
 
81-09-07                     - 7 -              Utilisp Manual
 
 
2. Predicates                                     May 17, 1981
 
 
 
 CODEP arg
     Returns T if  is a code piece, otherwise NIL. 
 
 
2.2 General Purpose Predicates 
 
The   following  functions  are  some  other  general  purpose
predicates. 
 
 EQ  x y
     Returns  T  if    and  denote the same Lisp object,
     otherwise  NIL.  Lisp objects which have the same printed
     representation  are  not necessarily identical.  However,
     the "interning" process ensures that two symbols with the
     same  print  name  are  identical  (see  Chapter  11, for
     details).   Unlike  some  other Lisp systems, equality of
     values   of  integer  numbers  ("fixnums")  can  also  be
     compared using EQ. 
 
     Note:   In  this manual, the expression "two Lisp objects
     are EQ" means that they are the same object. 
 
 NEQ  x y
     (NEQ   x   y)  =  (NOT  (EQ  x  y)).   This  function  is
     incorporated primarily for convenience in typing. 
 
 EQUAL  x y
     EQUAL  returns  T  if    and    are  "similar" Lisp
     objects,  otherwise  NIL.  That is, two strings are EQUAL
     if  they  have  the same length and all the characters in
     corresponding  positions  are the same, two "flonums" are
     EQUAL  if  they  have the same floating-point value, and,
     inductively,   two   "cons"  cells  are  EQUAL  if  their
     respective  "cars"  and  "cdrs"  are EQUAL.  In all other
     cases, two objects are EQUAL if and only if they are EQ. 
 
     If two Lisp objects are EQUAL, they have the same printed
     representation, however, the reverse does not necessarily
     hold (e.g., for symbols which have not been "interned"). 
 
 NOT  x
 NULL  x
     NOT  returns  the  symbol  T if  is EQ to NIL, and the
     symbol  NIL  otherwise.   NULL  is  the same as NOT; both
     functions  are  incorporated for the sake of readability.
     It  is recommended that NULL be used for checking whether
     a  given value is NIL, and that NOT be used for inverting
     a logical value. 
 
The  system  also  includes  various predicates in addition to
those  introduced in this chapter.  These will be described in
the  chapters  on  the  various  data  types accepted by these
predicates;  for  example, the predicate ZEROP is described in
Chapter 7, "Numbers". 
 
 
 
 
 
Utilisp Manual               - 8 -                    81-09-07
 
 
May 18, 1981                                     3. Evaluation
 
 
 
 
 
3.  Evaluation 
 
 
3.1 The Evaluator 
 
The process of evaluation of a Lisp form is as follows: 
 
If the form is neither a symbol nor a "cons", i.e., if it is a
"fixnum",  "flonum",  a  string,  a  code  piece,  a vector, a
reference  or  a  stream, then the result of its evaluation is
simply the form itself. 
 
If the form is a symbol, then the result is the value to which
that  symbol  is bound.  If the symbol is unbound, an error is
generated. 
 
A  so-called  "special  form"  (i.e., a "cons" identified by a
distinguished  symbol  in  its "car") is evaluated in a manner
which  depends  upon  the particular form in question.  All of
these  special  forms  will  be individually described in this
manual. 
 
If  the  form  in  question is not a so-called "special form",
then  it  requires the application of a function or a macro to
its  arguments.   The "car" of the form is a lambda-expression
or  the name of a function.  If the function is not a "macro",
the  "cdr"  of the form is a list of forms which are evaluated
sequentially,  from left to right, and the resulting arguments
are  then supplied to the function; the value finally returned
is the result of applying the function to these arguments. 
 
The evaluation process for macro forms is described in Chapter
10, "Macros". 
 
A more detailed and accurate description of the evaluator will
be    supplied   after   various   improvements   of   present
implementation have been carried out. 
 
 
3.2 Various Functions Concerned with Evaluation 
 
 EVAL  x
     Evaluates  , and returns the result.  Ordinarily, EVAL
     is not often used explicitly, since evaluation is usually
     carried  out  implicitly.   EVAL  is  primarily useful in
     programs  concerning  Lisp  itself,  rather  than  in its
     applications. 
 
 APPLY  fn arglist
     Applies  the  function  to the set of arguments given
     by , and returns the resulting value. 
 
 FUNCALL  fn . args
     Applies the function  to the set of arguments ,
     and   returns   the   resulting  value.   Note  that  the
     functional  argument   is evaluated in the usual way,
 
81-09-07                     - 9 -              Utilisp Manual
 
 
3. Evaluation                                     May 18, 1981
 
 
 
     while function which constitutes the "car" of an ordinary
     Lisp application is not. 
 
     Example: 
           (SETQ CONS 'PLUS) => PLUS
           (FUNCALL CONS 1 2) => 3
           (CONS 1 2) => (1 . 2)
 
     Thus,  explicit  application  using  FUNCALL,  instead of
     simple  implicit function application, should be used for
     functional  arguments, since, the binding of the function
     is  not  examined  by  the  evaluator  in simple implicit
     function  applications, whereas when FUNCALL is used, the
     functional argument symbol is evaluated first, yielding a
     function which is then applied in the ordinary manner. 
 
 QUOTE  »Special Formº arg
     Simply   returns  the  argument  .   Its  usefulness
     largely  consists  in  the  fact that its argument is not
     evaluated by the evaluator. 
 
     Examples: 
           (QUOTE X) => X
           (SETQ X (QUOTE (CONS 1 2))) X => (CONS 1 2)
 
     Since  QUOTE  is  very  frequently  used, the Lisp Reader
     allows  the  user  to  reduce the burden of keying in the
     program  by converting S-expressions preceded by a single
     quote character "'" into QUOTEd forms.  For example, 
          (SETQ X '(CONS 1 2))
     is converted into 
          (SETQ X (QUOTE (CONS 1 2)))
 
 FUNCTION  »Special Formº fn
     The  form  (FUNCTION  x) has precisely the same effect as
     (QUOTE  x); these alternative forms are available for the
     sake  of  clarity in reading and writing programs.  It is
     recommended  that  FUNCTION be used to quote a piece of a
     program,  and  that  QUOTE  be used for segments of data.
     The   compiler  utilizes  this  information  to  generate
     efficient object codes. 
 
     Note:  Function-valued arguments in Lisp functions should
     be  evoked using FUNCALL.  See the description of FUNCALL
     (above) for details. 
 
 COMMENT  »Special Formº . args
     COMMENT  ignores its arguments and always returns NIL; it
     is useful for inserting explanatory remarks. 
 
 PROGN  »Special Formº . args
     The  arguments    are  evaluated sequentially, from
     left  to  right,  and  the value of the final argument is
     returned.   This operation is useful in cases where it is
     necessary  to  evaluate a number of forms for the sake of
     the  concomitant  side  effects but only the value of the
     last  form  is  required.   Note that LAMBDA-expressions,
     COND  forms,  and  many  other  control  structure  forms
 
Utilisp Manual              - 10 -                    81-09-07
 
 
May 18, 1981                                     3. Evaluation
 
 
 
     incorporate  this  property  of  PROGN implicitly (in the
     sense  that  multiple  forms  are  handled  in  a similar
     manner). 
 
 PROG1  »Special Formº . args
     PROG1  functions in the same manner as PROGN, except that
     it  returns  the  value of the first argument rather than
     the  last.   PROG1  is  most  commonly used to evaluate a
     number  of  expressions,  with possible occurrence of the
     side  effects,  and return a value which must be computed
     before the side effects occur. 
 
     Example: 
           (SETQ X (PROG1 Y (SETQ Y X)))
 
     This  form interchanges the values of the variables X and
     Y. 
 
 PROG2  »Special Formº . args
     The  action  of  PROG2  is  the same as that of PROGN and
     PROG1,  except  that  it  returns the value of its second
     argument.   It  is  incorporated mainly for compatibility
     with other Lisp systems. 
 
     (PROG2  x  y  .   z) is equivalent to (PROGN x (PROG1 y .
     z)). 
 
 LET  »Macroº bindings . body
     A LET form has the syntax 
           (LET ((var1 vform1)
                 (var2 vform2)
                 ...)
               bform1
               bform2
               ...)
     which  is  automatically  converted  into and effectively
     equivalent to the following form: 
           ((LAMBDA (var1 var2 ...)
                bform1
                bform2
                ...)
            vform1
            vform2
            ...)
     It is often preferable to use LET rather than to directly
     use  LAMBDA,  since  the  variables and the corresponding
     forms  appear  textually  close  to  one  another,  which
     increases the readability of the program. 
 
     As LET forms are converted into LAMBDA application forms,
     all  the  values  of  the  's  are computed before
     binding  any  of  these  values  to  to the corresponding
     's.    For  example,    cannot  depend  upon
     ,  that  is,  if  appears in , then a
     variable  named    must  have  been bound somewhere
     outside this LET form. 
 
 
 
81-09-07                    - 11 -              Utilisp Manual
 
 
3. Evaluation                                     May 18, 1981
 
 
 
 LETS  »Macroº bindings . body
     LETS  is  similar  to  LET  except  that  LETS  binds its
     variables   sequentially,  one  by  one,  while  LET,  as
     mentioned   above,  binds  them  at  once.   (LETS  is  a
     contraction of "LET Sequentially"). 
 
     A LETS form has the syntax 
           (LETS ((var1 . vforms1)
                  (var2 . vforms2)
                  ...)
               bform1
               bform2
               ...)
     which is effectively equivalent to: 
           ((LAMBDA ((var1 . vforms1)
                     (var2 . vforms2)
                     ...)
                bform1
                bform2
                ...))
     each  list    constitutes the default value list
     for  the  corresponding , and therefore can depend
     upon  the  preceding  's  (see  Section 1.5, "Lambda
     Lists", for details). 
 
     Note:   The interpretation of LETS is faster than that of
     LET.    However,   once  compiled,  their  speeds  become
     identical. 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Utilisp Manual              - 12 -                    81-09-07
 
 
Jul. 3, 1981                                4. Flow of Control
 
 
 
 
 
4.  Flow of Control 
 
 
The  present  system  provides a variety of structures for the
flow of control. 
 
Function  application  is  the  basic  method for constructing
programs.   Moreover,  the definition of a function may always
call  the  function  being  defined.  This process is known as
"recursion". 
 
Both  explicit  and  implicit PROGN structures can be used for
sequential  execution  of  programs.   The  forms  in  a PROGN
structure are evaluated sequentially from left to right. 
 
In  this  chapter,  we  shall describe some even more flexible
control  structures.   Conditional  constructs  are useful for
making  decisions,  while iteration and mapping constructs may
be  convenient  for  repetition.  There are also more flexible
control structures known as non-local exits. 
 
 
4.1 Conditionals 
 
A  conditional construct incorporates a decision in a program,
resulting  in  the execution of one of several alternatives in
accordance with certain logical conditions. 
 
 AND  »Special Formº . args
     Evaluates the arguments sequentially, from left to right.
     If the value of any argument is NIL, then NIL is returned
     and  the  remaining  arguments are not evaluated.  If the
     value of all the arguments are non-NIL, then the value of
     the  last  argument  is returned.  AND can be interpreted
     for  logical  operation, where NIL stands for "false" and
     non-NIL for "true". 
 
     Examples: 
           (AND X Y)
           (AND (SETQ TEMP (ASSQ X Y))
                (RPLACD TEMP Z))
           (AND ERROR-EXISTS (PRINC "There is an error!"))
 
     Note:  (AND) => T 
 
 OR  »Special Formº . args
     Evaluates the arguments sequentially, from left to right.
     If the value of any argument is NIL, the next argument is
     evaluated.  If there are no remaining arguments, then NIL
     is  returned.   However,  if the value of any argument is
     non-NIL,  then that value is immediately returned and the
     remaining  arguments,  if any, are not evaluated.  OR can
     be  interpreted  as a logical operation, where NIL stands
     for "false" and non-NIL for "true". 
 
     Note:  (OR) => NIL 
 
81-09-07                    - 13 -              Utilisp Manual
 
 
4. Flow of Control                                Jul. 3, 1981
 
 
 
 
 COND  »Special Formº . clauses
     The   arguments  of  COND  are  usually  referred  to  as
     "clauses".   Each clause consists of a predicate followed
     by  a  number (possibly zero) of forms.  The predicate is
     called  the  "antecedent"  and  the  forms are called the
     "consequents". 
 
     Thus, a COND-form might have the following syntax: 
 
           (COND (antecedent consequent consequent ...)
                 (antecedent)
                 (antecedent consequent ...)
                 ...)
 
     Each  clause  represents an alternative which is selected
     if its antecedent is satisfied and the antecedents of all
     preceding clauses were not satisfied when evaluated. 
 
     The  clauses  are  processed  sequentially  from  left to
     right.   First,  the  antecedent of the current clause is
     evaluated.  If the result is NIL, the process advances to
     the   next   clause.    Otherwise,  the  consequents  are
     evaluated  sequentially  from  left  to right (in a PROGN
     manner),  the  value  of the last consequent is returned,
     and the remaining clauses (if any) are not processed.  If
     there  were  no  consequents in the selected clause, then
     the  value of the antecedent is returned.  If the clauses
     are  exhausted, that is, the value of every antecedent is
     NIL, then the value of the COND form is NIL. 
 
 SELECTQ  »Special Formº key-form . clauses
     Many  programs  require multiplex branchings which depend
     on  the  value  of  some  form.   A typical example is as
     follows: 
 
           (COND ((EQ X 'FOO) ...)
                 ((EQ X 'BAR) ...)
                 ((MEMQ X '(BAZ QUUX MUM)) ...)
                 (T ...))
 
     SELECTQ   is   incorporated   for   convenience  in  such
     situations.  A SELECTQ form has the following syntax: 
 
           (SELECTQ key-form
               (pattern consequent consequent ...)
               (pattern consequent consequent ...)
               (pattern consequent consequent ...)
               ...)
     The  first  argument   is evaluated first (just
     once).  The resulting value is called the "key".  The key
     form  is followed by a number of "clauses", each of which
     consists  of  a  "pattern" followed by a number (possibly
     zero)  of "consequent" forms.  The pattern of each clause
     is  compared  with  the  key,  and  if  it "matches", the
     consequents  of  this  clause  are evaluated, and SELECTQ
     returns  the  value of the last consequent.  If there are
     no  "matches",  or  if  there  is  no  consequent  in the
 
Utilisp Manual              - 14 -                    81-09-07
 
 
Jul. 3, 1981                                4. Flow of Control
 
 
 
     selected  clause,  then  NIL  is returned.  Note that the
     patterns are not evaluated. 
 
     The  objects  which may be used as the patterns and their
     "matching" conditions are as follows: 
 
     1) Any atom (symbol, number, etc.), except the symbol T 
          In  this  case,  the  key matches if it is EQ to the
          atom. 
     2) A list 
          In  this case, the key matches if it is EQ to one of
          the top-level elements of the list. 
     3) The symbol T 
          The  symbol  T  constitutes  a special pattern which
          matches anything. 
 
     Example:   The  preceding  example  can  be  expressed as
     follows: 
           (SELECTQ X
               (FOO ...)
               (BAR ...)
               ((BAZ QUUX MUM) ...)
               (T ...))
 
     Note:   The  symbol  T  itself  may  be used as the first
     component  of  a  clause,  in  a  non-trivial  manner, by
     selecting (T) as the pattern. 
 
 
4.2 Iteration 
 
 PROG  »Special Formº locals . body
     PROG   is   a   special  form  which  provides  temporary
     variables,  sequential  evaluation  of  forms, and "goto"
     operations.  A typical PROG form might have, for example,
     the following structure: 
 
           (PROG (var1 (var2 . inits2) var3 (var4 . inits4))
      tag1       statement1
                 statement2
      tag2       statement3
                 ...)
 
     ,  ,  ...   are  temporarily bound variables.
     The  binding of these variables prior to the execution of
     the PROG are recorded, and when the execution of the PROG
     has  been  completed, the original bindings are restored.
     If  a  variable  is associated with an initial value list
     ,  then  the  elements  of  the list are evaluated
     sequentially,  from  left  to right, and the value of the
     last  one  becomes the initial value of the variable.  If
     there  are  no  initial value forms, then the variable is
     initialized to NIL. 
 
     Example: 
           (PROG ((A T)
                  B
                  (C (PRINT "C is bound") (CAR '(FOO . BAR))))
 
81-09-07                    - 15 -              Utilisp Manual
 
 
4. Flow of Control                                Jul. 3, 1981
 
 
 
                 . body)
     Here,  the initial value of A is T, that of B is NIL, and
     that  of C is the symbol FOO.  Before the binding of C is
     executed, the indicated message is printed.  The bindings
     are  processed  sequentially,  and the value of each form
     may depend upon previous bindings. 
 
     The  portion of a PROG which follows the variable list is
     called  the "body".  The elements of  may be atoms,
     which  are  called  "tags",  or  "cons"  cells, which are
     called "statements." 
 
     After  the temporary variables have been bound, the forms
     in  the  body  are  processed sequentially.  Tags are not
     evaluated,  whereas  statements  are  evaluated and their
     values  discarded.   If  process  reaches  the end of the
     body, then NIL is returned.  However, two special devices
     (described  below)  may  be  used  to  alter  the flow of
     control in the body of a PROG. 
 
     If  (RETURN  x1 ...  xn) is evaluated, then processing of
     the body is terminated and the value of the last argument
      is returned as the value of the PROG.  If n=0, i.e.,
     if no arguments are present, then the value returned will
     be   NIL.    Only   those  RETURN  statements  which  are
     explicitly  included  in  the  body  of  a  PROG form can
     legitimately  used  in this manner (for example, a RETURN
     statement  occurring  within the definition of a function
     called  during  the  execution of a PROG will generate an
     error when the program is compiled.) 
 
     If  (GO tag) is evaluated, then the evaluation process is
     resumed  from  the statement labelled with  (in case
     there  is  no statement associated with , i.e., when
       is  at the end of a PROG body, the PROG routine is
     simply terminated);  is not evaluated.  If the label
       does  not  occur  in  the  body  of  the PROG form
     currently  being executed, the body of the innermost PROG
     form  properly including the current one is searched, and
     so  forth; if  is found, then the execution sequence
     leaves the current PROG form and the program execution is
     resumed from the point labelled with .  If the label
       does not occur in any PROG form which contains (GO
     tag),  then  an error is generated.  Any statement of the
     form  (GO  tag)  must  be explicitly included in the PROG
     form containing the destination indicated by . 
 
 GO  »Special Formº tag
     See the explanation under the entry for PROG above. 
 
     Note:     can  be  an  atom  of  any  type including
     symbolic  atoms  or  "fixnums".   Since  the  process  of
     searching  is  effected  using the equality criterion EQ,
     "flonums",  strings,  vectors,  etc.   are  generally not
     appropriate as labels. 
 
 
 
 
Utilisp Manual              - 16 -                    81-09-07
 
 
Jul. 3, 1981                                4. Flow of Control
 
 
 
 RETURN  . args
     See the explanation under the entry for "PROG" above. 
 
 LOOP  »Special Formº . body
     LOOP  is  a  special form used for simple iteration.  The
     arguments of LOOP are evaluated sequentially from left to
     right.   As  long  as  EXIT  is  not  evoked during these
     evaluations,   this  process  is  interminably  repeated.
     However,  if  an EXIT form is encountered, the inner-most
     LOOP  containing  it  is  terminated and the value of the
     last  argument  of  this EXIT is returned as the value of
     that LOOP form. 
 
     Example:   The  top-level  loop  of  the system, although
     actually defined in terms of machine language, could have
     been defined as follows: 
           (LOOP (PRINT (EVAL (READ))))
 
 EXIT  . args
     See the explanation under the entry for LOOP above.  EXIT
     being  an  ordinary function, its arguments are evaluated
     sequentially, from left to right, in the usual manner. 
 
     When  a  LOOP  form  is to be compiled, the corresponding
     EXIT forms must be explicitly contained in the LOOP. 
 
 DO  »Macroº index-part exit-part . body
     DO  is  a  control form which facilitates iteration using
     so-called  "index  variables." The first argument  is a list, the elements of which have the form 
 
          (var init next)
 
     where    is  a symbol employed as an index variable,
      is the initial value assigned to , and 
     is  a  form  which  is  computed  after  each  iteration,
     whereupon the resulting value is assigned to . 
 
     The  initial  values  are computed sequentially, and only
     after  this  process  is  completed are they bound to the
     corresponding  variables;  the same applies to subsequent
     assignments arising from the  forms. 
 
     The second argument  has the syntax as 
 
          (end-test . exit-forms)
 
     After  initially  binding  the index variables, and after
     each  round  of   value assignments, the form   is  evaluated.   If  the  result  is  non-NIL, the
     termination  process  begins;  the forms constituting the
     list    are evaluated sequentially, from left
     to  right,  and the value of the last one (or NIL, if the
     list  is empty) will be returned as the value
     of  the  DO  form.  The index variables are then unbound,
     their original values are restored, and the evaluation of
     the DO form terminates. 
 
 
81-09-07                    - 17 -              Utilisp Manual
 
 
4. Flow of Control                                Jul. 3, 1981
 
 
 
     Otherwise,  if  the  evaluation of  yields NIL,
     execution  of    begins;  is a list of forms,
     which are evaluated sequentially, from left to right, and
     the results are discarded.  When  is exhausted, the
     evaluation  process  proceeds  to  the  evaluation of the
      forms. 
 
     Any   form may be omitted from  when no
     assignment  of  the  corresponding  variable  is required
     after  iteration; in this case,  merely serves as an
     ordinary  local variable.  Any initiation form  may
     also  be  omitted;  in this case, NIL becomes the initial
     value of the corresponding . 
 
     A DO form, being a macro, is automatically converted into
     an  equivalent  combination  of  LET  and LOOP.  Thus, to
     depart  from  a DO form, the function EXIT can be used in
     its  ,  ,  or  the    forms of its
     .  It should be borne in mind that, since the
       forms  are evaluated outside the LOOP, the use of
     EXIT in an  form will terminate the evaluation of a
     still  "larger"  DO  or  LOOP  form  than  the  one under
     consideration. 
 
     Examples:    Printing  all  the  elements  of  a  list  X
     separated  by  a  space can be performed by the following
     program: 
          (DO ((L X (CDR L)))
             ((ATOM L))
             (PRIN1 (CAR L))
             (PRINC " "))
 
     When  each  element  of a vector V is a number, their sum
     can be computed by the following program: 
          (DO ((I 0 (1+ I))
               (L (VECTOR-LENGTH V))
               (SUM 0 (PLUS SUM (VREF V I))))
             ((= I L) SUM))
     Note  that,  in  this  example,  the body of DO is empty.
     This  is,  in  fact, the case in many applications, since
     the  index  and  exit  parts of a DO control form can, in
     themselves,  be  quite  powerful.   Also  note that, when
     (VREF  V I) is computed, the variable I still retains its
     previous  value, that is, the  value (1+ I) has not
     yet  been assigned to it.  L does not have a  part,
     and  is merely a temporary variable which facilitates the
     computation of . 
 
 
4.3 Non-local Exits 
 
 CATCH  tag . forms
     CATCH  is  a  function  primarily  utilized for non-local
     exits.   (CATCH  tag  .  forms) evaluates the elements of
     the  list  and returns the value of the last form,
     unless  an  expression  of the form (THROW tag .  values)
     with  the same  is encountered during the evaluation
     of  ,  in which case the arguments in  are
 
Utilisp Manual              - 18 -                    81-09-07
 
 
Jul. 3, 1981                                4. Flow of Control
 
 
 
     evaluated,  and CATCH immediately returns the last of the
       (or NIL when  is empty) and performs no
     further evaluation. 
 
     Note:   The argument  is evaluated, which is not the
     case  in  some  other Lisp systems.  However, no repeated
     evaluation  is  applied  to  the  elements  of  the  list
     ,  which  are  evaluated  just  once as the normal
     arguments  of  a  function.   The special action of CATCH
     occurs  during  the  evaluation  of its arguments, rather
     than  during  the execution of CATCH itself; the function
     CATCH,  in itself, only returns its last argument (or NIL
     when  there is only one argument ) if the evaluation
     of its arguments is completed without calling THROW. 
 
     Example: 
       (CATCH 'ATOMIC
          (MAPCAR L
             (FUNCTION (LAMBDA (X)
                          (COND ((ATOM X) (THROW 'ATOMIC X))
                                (T (CAR X)))))))
 
     This  program  returns  a  list  of  the  "car"'s  of the
     elements of the list L, if the latter are all non-atomic,
     otherwise, the first atomic element of L is returned. 
 
 THROW  tag . values
     As  described  above,  THROW  is used in conjunction with
     CATCH for (primarily non-local) exits.  THROW conveys the
     value  of  the  last  argument  in   (or NIL when
      is empty) back to the closest preceding CATCH in
     the execution sequence which possesses the same  and
     has  not  yet  been  evoked.   Any  CATCH forms (or other
     control  forms  or functions) which may be nested between
     the  THROW form under consideration and the corresponding
     CATCH are effectively ignored.  See the above description
     of CATCH for further details. 
 
     Note:   As  in the case of CATCH, both  and forms in
      are evaluated, unlike the corresponding function
     THROW in some other Lisp systems. 
 
     Example:  The following program returns A rather than B. 
           (CATCH 'A (CATCH 'B (THROW 'A 'A)) 'B)
 
 
4.4 Mapping 
 
Mapping  is a type of iteration in which a certain function is
successively  applied  to portions of a list or a vector given
as  an  argument.  There are several options for the manner in
which  the  portions  of the list or the vector are chosen and
the  results  returned  by the application of the function are
presented. 
 
 
 
 
 
81-09-07                    - 19 -              Utilisp Manual
 
 
4. Flow of Control                                Jul. 3, 1981
 
 
 
The table shows the relations between the six map functions on
list structures. 
 
                               applies function to
 
                         |  successive  |  successive  |
                         |   sublists   |   elements   |
          ---------------+--------------+--------------+
             its own     |              |              |
              first      |     MAP      |     MAPC     |
             argument    |              |              |
          ---------------+--------------+--------------+
             list of the |              |              |
  returns     function   |   MAPLIST    |    MAPCAR    |
              results    |              |              |
          ---------------+--------------+--------------+
            nconc of the |              |              |
              function   |    MAPCON    |    MAPCAN    |
              results    |              |              |
          ---------------+--------------+--------------+
 
 MAP  list fn
     The  function   is applied to the successive sublists
     of  ,  i.e.,  first   itself, then its "cdr",
     then  "cddr",  etc.   The  value returned is its original
     argument  (possibly modified by ).. 
 
     Example: 
           (MAP '(A B C) (FUNCTION PRIN1))
     This  program prints out "(A B C)(B C)(C)" and returns (A
     B C). 
 
 MAPC  list fn
     The  function   is applied to the successive elements
     of  ,  i.e.,  first  the  "car" of , then its
     "cadr",  then  "caddr",  etc.   The value returned is its
     original argument  (possibly modified by ).. 
 
     Example: 
           (MAPC '(A B C) (FUNCTION PRIN1))
     This program prints out "ABC" and returns (A B C). 
 
 MAPLIST  list fn
     The  function   is applied to the successive sublists
     of  ,  i.e.,  first   itself, then its "cdr",
     then  "cddr", etc.  The value returned is a newly created
     list of the results of these applications. 
 
     Example: 
           (MAPC '(A B C) (FUNCTION PRIN1))
     This program prints out "(A B C)(B C)(C)" and returns ((A
     B C) (B C) (C)). 
 
 MAPCAR  list fn
     The  function   is applied to the successive elements
     of  , i.e., first "car" of , then its "cadr",
     then "caddr", etc.  The value returned is a newly created
     list of the results of these applications. 
 
Utilisp Manual              - 20 -                    81-09-07
 
 
Jul. 3, 1981                                4. Flow of Control
 
 
 
 
     Example: 
           (MAPCAR '(A B C) (FUNCTION PRIN1))
     This  program prints out "ABC" and returns (A B C), which
     appears   the   same  as  the  original  arguments,  but,
     actually, has newly been created. 
 
 MAPCON  list fn
     The  function   is applied to the successive sublists
     of  ,  i.e.,  first   itself, then its "cdr",
     then  "cddr",  etc.  The value returned is the results of
     these applications concatenated together. 
 
     Example: 
           (MAPCON '(A B C) (FUNCTION NCONS))
     This program returns (A B C B C C). 
 
 MAPCAN  list fn
     The  function   is applied to the successive elements
     of  , i.e., first "car" of , then its "cadr",
     then  "caddr", etc.  The value returned is the results of
     these applications concatenated together. 
 
     Example: 
           (MAPCAN '(A B C) (FUNCTION NCONS))
     This  program  returns (A B C), which appears the same as
     the  original  argument,  but,  actually,  has newly been
     created. 
 
 MAPV  vector fn
     MAPV  successively  applies    to all the elements of
     ,  in increasing order of indices.  The arguments
     presented  to  the  function  are "reference" objects
     "pointing"  to  the elements of .  See chapter 9,
     "Vectors",  for  further  information  about "reference".
     The  value  returned  by  MAPV  is  simply  the  original
     argument   (possibly modified by the execution of
     the function ). 
 
     Example: 
           (MAPV (VECTOR 5)
              (FUNCTION (LAMBDA (R)
                           (SETREF R (READ)))))
     This   will   return   a  vector  of  five  Lisp  objects
     consecutively read in. 
 
 MAPVECTOR  vector fn
     MAPVECTOR  also  applies    to  all  the  elements of
     ,  in  increasing  order  of indices, however, in
     this  case,  the  arguments  presented  to    are the
     elements themselves, rather than references "pointing" to
     them  (see the description of MAPV).  MAPVECTOR returns a
     new  vector the components of which are the corresponding
     results of these applications. 
 
 
 
 
 
81-09-07                    - 21 -              Utilisp Manual
 
 
5. Manipulating List Structure                   Jul. 28, 1981
 
 
 
 
 
5.  Manipulating List Structure 
 
 
5.1 Cons manipulation 
 
 CAR  x
     CAR  returns  the  "car"  of  .  If  is an atom, an
     error is generated. 
 
 CDR x
     CDR  returns  the  "cdr"  of  .  If  is an atom, an
     error is generated. 
 
 C...R  x
     All  the  compositions  of  CAR  and CDR, upto a total of
     four,  are  defined  as, so-called, "built-in" functions.
     The  names of these functions begin with "C", followed by
     a  sequence  of  "A"'s  and  "D"'s  corresponding  to the
     indicated composition of functions, and end with "R". 
 
     Example:   (CDDAR x) is effectively the same as (CDR (CDR
     (CAR x))) 
 
 CR  x
     CR  returns   itself, and is the function in the C...R
     group  for  which  the total number of "A"'s and "D"'s is
     zero.   This  function  is  sometimes useful when dealing
     with   mapping  functions.   For  example,  (MAPCAR  list
     (FUNCTION  CR)) may be used to obtain a top-level copy of
     . 
 
 CONS  x y
     CONS  is  a primitive function which creates a new "cons"
     cell,  the  "car"  and  "cdr"  of  which are  and ,
     respectively. 
 
     Examples: 
           (CONS 'A 'B)  =>  (A . B)
           (CONS 'A '(B C D))  =>  (A B C D)
 
 NCONS  x
     (NCONS x) is effectively the same as (CONS x NIL). 
 
 XCONS  y x
     XCONS  (an  abbreviation of "eXchange CONS") differs from
     CONS only in that the order of the arguments is reversed.
     XCONS  is useful when the "cdr" part of the result should
     be evaluated before the "car" part. 
 
     Example: 
           (XCONS 'A 'B)  =>  (B .  A)
 
 COPY  x
     COPY  creates  and  returns  a  "copy" of .  The atoms
     constituting  the copy are the same as those constituting
     the  original  argument  , but all the "cons" cells of
 
Utilisp Manual              - 22 -                    81-09-07
 
 
Jul. 28, 1981                   5. Manipulating List Structure
 
 
 
     the copy are newly created. 
 
     Note:   List  structures  in  which  a non-atomic node is
     indicated  by  more  than  one  pointer  are  not  copied
     faithfully;  such nodes will be duplicated in the "copy".
     "Copying" a cyclic structure in this manner results in an
     endless computation. 
 
 
5.2 List Manipulation 
 
The  following  section  explains  some of the basic functions
provided   for   manipulating   lists.    A  list  is  defined
recursively  as  either  the  symbol  NIL, which represents an
empty  list,  or  a "cons" whose "cdr" is a list.  However, it
should  be noted that, although their arguments are denoted by
the  word "list", the functions described below are applicable
whether or not the final atom is NIL. 
 
 LAST  list
     LAST  returns  the  last  top-level "cons" of .  If
       is  an  atom,  an error is generated; if the top-
     level  structure  of    is  cyclic, then an endless
     computation occurs. 
 
     Example: 
           (LAST '(A (B C) D E))  =>  (E)
 
 LENGTH  list
     LENGTH  returns  the  length  of .  The length of a
     list is the number of its top-level elements. 
 
     As  in  the  case  of LAST, if the top-level structure of
      is cyclic, an endless computation occurs. 
 
     Example: 
           (LENGTH '(A (B C) D E))  =>  4
           (LENGTH NIL)  =>  0
 
 FIRST  x
     ==> (CAR x) 
 
 SECOND  x
     ==> (CADR x) 
 
 THIRD  x
     ==> (CADDR x) 
 
 FOURTH  x
     ==> (CADDDR x) 
 
 FIFTH  x
     ==> (CAR (CDDDDR x)) 
 
 SIXTH  x
     ==> (CADR (CDDDDR x)) 
 
 
 
81-09-07                    - 23 -              Utilisp Manual
 
 
5. Manipulating List Structure                   Jul. 28, 1981
 
 
 
 SEVENTH  x
     ==> (CADDR (CDDDDR x)) 
 
 NTH  n list
     NTH  returns the th top-level element of , where
     (CAR  list)  is counted as the zeroth element.  If  is
     negative  or not less than the length of , an error
     is  generated.  Note that (NTH 2 x) is actually (THIRD x)
     rather than (SECOND x). 
 
     Example: 
           (NTH 2 '(A B C D E))  =>  C
 
 NTHCDR  n list
     NTHCDR  applies CDR to the second argument for  times,
     and  returns  the result; for =0, the result is simply
       itself.   If  is negative or not less than the
     length of , an error is generated. 
 
     Example: 
           (NTHCDR 2 '(A B C D E))  =>  (C D E)
 
 LIST  . args
     LIST  constructs  and  returns  a  list of its arguments,
     ordered in the same manner as the arguments themselves. 
 
     Examples: 
           (LIST 1 2 (CAR '(3 5)) (+ 2 2))  =>  (1 2 3 4)
           (LIST)  =>  NIL
 
 APPEND  . lists
     The  result  of  APPEND is essentially a concatenation of
     its arguments, however, avoiding physical alteration, the
     arguments  are  copied (except for the last one; see also
     the  description  of  NCONC  below).   The  tail  of  the
     resulting  list  is physically identical with that of the
     last argument. 
 
     Examples: 
           (APPEND '(A B C) '(D E) NIL '(F G H))
                     =>  (A B C D E F G H)
           (APPEND)  =>  NIL
 
     Note:   When  several  lists  are to be APPENDed, and the
     order of the resulting list is not essential, the longest
     argument  should  be entered last since it is not copied;
     this  reduces  both  computing  time  and required memory
     space. 
 
 REVERSE  list
     REVERSE  creates  a  new  list, the top-level elements of
     which  are  the  same  as those of  but arranged in
     reverse  order.   REVERSE,  unlike  NREVERSE (see below),
     does not modify its argument. 
 
     Example: 
           (REVERSE '(A (B C) D))  =>  (D (B C) A)
 
 
Utilisp Manual              - 24 -                    81-09-07
 
 
Jul. 28, 1981                   5. Manipulating List Structure
 
 
 
 NCONC  . lists
     NCONC  returns  a  list which is the concatenation of the
     arguments.   The  arguments  (except  the  last  one) are
     physically  altered  in  the manner of RPLACD rather than
     copied (see also the description of APPEND above.) 
 
     Example: 
           (SETQ X '(A B C))
           (SETQ Y '(D E F))
           (NCONC X Y)  =>  (A B C D E F)
           X  =>  (A B C D E F)
     Note  that  the value of X itself has been altered, since
     the  "cdr"  of  its  last "cons" has been replaced by the
     value of Y. 
 
 NREVERSE  list
     NREVERSE  reverses  its argument , which is altered
     in  the  RPLACD  manner throughout the list (see also the
     description of REVERSE). 
 
     Example: 
           (SETQ X '(A B C))
           (NREVERSE X)  =>  (C B A)
           X  =>  (A)
     Note  that  the value of X itself has been altered, since
     the original list has been modified in RPLACD fashion. 
 
 PUSH  »Special Formº item var
     (PUSH item var) has the same effect and value as 
           (SETQ var (CONS item var))
     but  is  more  readable.   must be a bound variable.
     PUSH   is   useful,   along  with  POP  (see  below),  in
     maintaining a list in the manner of a push-down stack. 
 
 POP  »Special Formº var
     (POP var) has the same effect and value as 
           (PROG1 (CAR var) (SETQ var (CDR var)))
     but  is  more  readable.   must be a symbol which is
     bound  to  a  non-atomic  value prior to the execution of
     POP.   POP  is  useful,  along  with PUSH (see above), in
     maintaining a list in the manner of a push-down stack. 
 
 
5.3 Alteration of List Structure 
 
The  functions  RPLACA and RPLACD serve to alter existing list
structure;  that  is,  to  change  the  "cars"  and  "cdrs" of
existing "cons" cells. 
 
Since  structure  is  physically  altered  rather than copied,
caution  should  be  exercised  when using these functions, as
unexpected  side-effects may occur if portions of the affected
list  structures  are  common  to  several  Lisp objects.  The
functions  NCONC  and  NREVERSE  also  alter  list  structure,
however,  they  are  not  normally  used  to obtain such side-
effects,  rather,  the concomitant list-structure modification
is   effected   purely   for   the   sake  of  efficiency  and
corresponding non-destructive functions are also available. 
 
81-09-07                    - 25 -              Utilisp Manual
 
 
5. Manipulating List Structure                   Jul. 28, 1981
 
 
 
 
 RPLACA x y
     RPLACA  replaces  the  "car"  of    by  and returns
     (modified)  .    must be a "cons", while  may be
     any Lisp object. 
 
     Example: 
           (SETQ X '(A B C))
           (RPLACA X 'N)  =>  (N B C)
           X  =>  (N B C)
 
 RPLACD  x y
     RPLACD  replaces  the  "cdr"  of    by  and returns
     (modified)  .    must be a "cons", while  may be
     any Lisp object. 
 
     Example: 
           (SETQ X '(A B C))
           (RPLACD X 'C)  =>  (A . C)
           X  =>  (A . C)
 
 SUBST  x y z
     (SUBST  x y z) substitutes  for all occurrences of 
     in    (using  EQ for testing equality) and returns the
     modified  copy  of .  The original  is not altered,
     as  SUBST recursively copies all the "cons" cells of ,
     replacing by  all elements which are EQ to . 
 
     Example: 
           (SUBST 'A 'B '(A B (C B)))
             =>  (A A (C A))
 
     Note:   List  structures  in  which  a non-atomic node is
     designated  by  more  than  one  pointer  are  not copied
     faithfully;  such nodes will be duplicated in the "copy".
     Applying  SUBST  to  a  cyclic  structure  results  in an
     endless computation. 
 
 
5.4 Tables 
 
The  system  provides  several  functions  which  simplify the
maintenance  of  several  varieties of tabular data structures
assembled from "cons" cells. 
 
The  simplest  of these structures is just an ordinary list of
items, which represents an ordered set. 
 
An  association list is a list the element of which are "cons"
cells.   The  "car"  of each such "cons" is called a "key" and
the "cdr" represents an associated datum. 
 
Although these simple data structures are convenient for small
data  bases,  their  form  is  such that search time increases
linearly with the size of the data base, and consequently they
are  inefficient  when handling large amounts of data.  Large-
scale data bases are best maintained using vectors and hashing
functions (see the section 5.6 "Hashing" for details). 
 
Utilisp Manual              - 26 -                    81-09-07
 
 
Jul. 28, 1981                   5. Manipulating List Structure
 
 
 
 
 MEMQ  item list
     (MEMQ  item  list) returns NIL if  is not identical
     (with  respect  to  the  function  EQ)  with  one  of the
     elements  of , otherwise, it returns the portion of
       beginning  with  the  first occurrence of .
     The  procedure  searches    on  the top-level only.
     Since MEMQ returns NIL if  is not found, and a non-
     NIL  object  if  it  is  found,  MEMQ  can  be  used as a
     predicate. 
 
     Example: 
           (SETQ X '(A B C D E))
           (MEMQ 'C X)  =>  (C D E)
           (MEMQ 'FOO X)  =>  NIL
 
 MEMBER  item list
     MEMBER  functions in the same manner as MEMQ, except that
     EQUAL, rather than EQ, is used for comparison. 
 
 MEM  predicate item list
     MEM  functions in the same manner as MEMQ, except that it
     takes  an additional argument , the latter may
     be  any  predicate  taking two arguments.  (MEM (FUNCTION
     EQ)  a  b)  is  effectively identical with (MEMQ a b) and
     (MEM (FUNCTION EQUAL) a b) with (MEMBER a b). 
 
     Example: 
           (MEM (FUNCTION (LAMBDA (X Y) (0= (+ X Y))))
                13
                '(1 3 -4 -13 7 -6))
               =>  (-13 7 -6)
 
 DELQ  item list (n)
     When  the  optional  argument  is absent, DELQ returns
       with all top-level occurrences of  deleted;
     EQ  is  used  for  comparison.   The  argument   is
     actually altered in the RPLACD manner when occurrences of
       are  excised,  except that any initial segment of
       all the elements of which are EQ to  is not
     altered  in  this  manner (see Example below).  If  is
     present,  it  must  be  a "fixnum" and only the first 
     top-level  occurrences of  are deleted.   may be
     zero,  in  which  case,  itself is returned without
     any alteration. 
 
     Example: 
           (SETQ X '(A B A B))
           (DELQ X 'B)  =>  (A A)
           X  =>  (A A)
 
     Note:   DELQ  should  be  used for value, not for effect.
     Thus, the two pairs of operations 
           (SETQ Y '(A B A B))
           (SETQ Y (DELQ 'A Y))
     and 
           (SETQ Y '(A B A B))
           (DELQ 'A Y)
 
81-09-07                    - 27 -              Utilisp Manual
 
 
5. Manipulating List Structure                   Jul. 28, 1981
 
 
 
     result  in  different values of Y.  The value returned by
     DELQ  is  (B  B)  in both cases.  However, Y is given the
     value (B B) in the former case and (A B B) in the latter.
 
 REMQ  item list (n)
     REMQ  yields  the same result as DELQ, except that 
     itself  is not altered; what is returned is a copy of the
     original  argument    with  the first  top-level
     top-level occurrences of  removed, where  is the
     minimum of  and the number of top-level occurrences of
      in . 
 
 EVERY  list predicate
     EVERY  applies  ,  a predicate function of one
     argument,   to   the   top-level   elements   of   
     sequentially, from left to right.  If  returns
     non-NIL  for every element, then EVERY returns T.  If any
     of  these applications yields NIL, then EVERY returns NIL
     immediately, and no further applications are executed. 
 
 SOME  list predicate
     SOME  applies  ,  a  predicate function of one
     argument,   to   the   top-level   elements   of   
     sequentially, from left to right.  If  returns
     non-NIL  for  some element, then SOME immediately returns
     the  portion  of   beginning with the element which
     yielded   non-NIL,   and   no  further  applications  are
     executed.   If  all the applications yield NIL, then SOME
     returns NIL. 
 
 ASSQ  item alist
     ASSQ  searches  for  and returns the first element in the
     association  list    the  "car"  of which is EQ to
     ,  if  such an element exists, otherwise, the value
     NIL  is returned.  The association list may be updated by
     applying  RPLACD  to the result of ASSQ, if the latter is
     not NIL. 
 
     Example: 
           (ASSQ 'C '((A B) (C D) (E F)))
               =>  (C D)
 
 ASSOC  item alist
     ASSOC  functions  in the same manner as ASSQ, except that
     EQUAL instead of EQ is used for comparison. 
 
 ASS  predicate item alist
     ASS  functions in the same manner as ASSQ, except that it
     takes  an  additional  argument  , a predicate
     taking  two  arguments, which is used for comparison.  In
     the  special  case where  is EQ, this function
     effectively reduces to ASSQ. 
 
 
 
 
 
 
 
Utilisp Manual              - 28 -                    81-09-07
 
 
Jul. 28, 1981                   5. Manipulating List Structure
 
 
 
 
5.5 Sorting 
 
 SORT  table predicate
     The  list   is arranged in increasing order, using
     the  ordering  relation corresponding to , and
     the  resulting  ordered  list  is  returned.  
     should be a function of two arguments, which returns non-
     NIL  if  and  only if the first argument is strictly less
     than the second in the sense of total ordering relation. 
 
 
5.6 Hashing 
 
Some  hashing  scheme  is  desirable  in  order  to reduce the
computing time required for data retrieval in large-scale data
bases.   The search time required for an item remains constant
using  hashing,  as  long  as  the hash table is large enough,
compared with the number of its entries. 
 
The  present  system  provides a standard hashing function for
Lisp  objects  to  facilitate  the maintainance of hashed data
bases. 
 
 HASH  x
     HASH  computes  hash  value  for  and returns it as an
     integer  number  "fixnum".   The  result may be positive,
     negative, or zero.  Its properties guaranteed are: 
 
      1)  Objects  which  are  EQUAL  are  hashed to the equal
     value. 
      2) A "fixnum" is hashed to itself. 
      3) A string is hashed to non-negative value. 
      4)  A  symbol  is hashed to the same value as its print-
     name. 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
81-09-07                    - 29 -              Utilisp Manual
 
 
6. Symbols                                        Aug. 3, 1981
 
 
 
 
 
6.  Symbols 
 
Symbolic  atoms such as X or CONS are called "symbols" in this
system.   A  symbol  is associated with four Lisp objects; the
"binding"  is  the  value  of  the symbol when it is used as a
variable; the "definition" is the functional definition of the
symbol  when  it is used as the name of a function or a macro;
the  "property  list"  is  used to retain various Lisp objects
associated with the symbol; the "print name" is used for input
and output operations. 
 
 
6.1 The Value 
 
A  symbol  can  be associated with its "value", which may be a
Lisp  object  of  any  type,  and is returned as the result of
evaluating  the symbol.  The symbol may be in "unbound" state,
in  which  case  the  symbol  has  no  value  at  all; when an
"unbound"  symbol  is evaluated, an error is generated.  Newly
created symbols (by INTERN, GENSYM, etc.) are initially in the
"unbound"  state.   A  symbol  is called a "variable" when the
primary concern is its value. 
 
The  value  of  a  variable  can be changed either by "lambda-
binding"  or by "assignment"; when a symbol is "lambda-bound",
its  previous  value  is  saved  and  will  be restored later,
whereas  "assignment"  discards  the previous value.  "Lambda-
binding" is sometimes called simply "binding" in this manual. 
 
The symbols NIL and T are always bound to themselves; they may
not  be  assigned  nor lambda-bound (The error of changing the
value of T or NIL is not detected!) 
 
 SET  variable new-value
     "Assignment"   to    can  be  effected  by  the
     function  SET.   The  value  of   is changed to
       which  may be any Lisp object.  The previous
     value  of  , if any, is discarded.  SET returns
     the newly assigned value . 
 
 SETQ  »Special Formº . args
     (SETQ x y) is effectively the same as (SET 'x y). 
 
     Additional  feature  of  SETQ is concurrent assignment of
     variables  without  explicit temporary variables.  A SETQ
     form such as 
          (SETQ var1 form1 var2 form2 ...)
     is used for this purpose.  , , ...  are all
     evaluated first, sequentially, in this order.  Then their
     resulting values are assigned to , , .... 
 
     Example:   Values  of  two  variables  X  and  Y  can  be
     exchanged by 
          (SETQ X Y Y X)
 
 
 
Utilisp Manual              - 30 -                    81-09-07
 
 
Aug. 3, 1981                                        6. Symbols
 
 
 
 BOUNDP  variable
     BOUNDP  returns  T  if  is bound to some value;
     otherwise, i.e., if it is unbound, NIL is returned. 
 
 MAKE-UNBOUND  variable
     MAKE-UNBOUND makes  unbound.  The current value
     of   ,  if  any,  is  discarded.   MAKE-UNBOUND
     returns the symbol  as its value. 
 
 
6.2 The Definition 
 
A  symbol  can be associated with its "functional definition",
or "definition", for short.  When a function is called via its
name,  that is, when the first argument of FUNCALL or APPLY is
a  symbol,  or  a  symbol appears as the "car" of a form to be
evaluated,  the  "definition"  of  that  symbol is called as a
function.   When  a  symbol is not defined as a function nor a
macro,  the  symbol  is  said  to  be "undefined"; an error is
generated when an undefined symbol is used as a function. 
 
 DEFUN  »Macroº name lambda-list . body
     DEFUN  can be used for defining functions.   should
     be a symbol.  A list 
          (LAMBDA lambda-list . body)
     will  be  the  new  definition  of  .  The previous
     definition  of  ,  if  any,  is  discarded.   DEFUN
     returns  as its value. 
 
 MACRO  »Macroº name lambda-list . body
     MACRO  can be used for defining macros.   should be
     a symbol.  A list 
          (MACRO LAMBDA (arg) . body)
     will  be  the  new  definition  of  .  The previous
     definition  of  ,  if  any,  is  discarded.   MACRO
     returns  as its value. 
 
     Note:    Macros  can  more  elegantly  be  defined  using
     DEFMACRO.  See Chapter 10, Macros, for detail. 
 
 GETD  sym
     GETD  returns the definition of a symbol .  If 
     is undefined, an error is generated. 
 
 PUTD  sym def
     PUTD  makes the definition of  be .   must
     be  a  symbol  while    may  be any Lisp object.  It
     returns  as its value. 
 
 DEFINEDP  sym
     DEFINEDP returns T if  is defined as a function or a
     macro;  otherwise,  i.e.,  if  it  is  undefined,  NIL is
     returned. 
 
     Note:   DEFINEDP  returns NIL for special form indicators
     such  as  COND, since they are not defined as an ordinary
     function  nor  a  macro.   Use the function SPECIALP (see
     below) to discriminate special form indicators. 
 
81-09-07                    - 31 -              Utilisp Manual
 
 
6. Symbols                                        Aug. 3, 1981
 
 
 
 
 SPECIALP  sym
     SPECIALP  returns  T if  is a special form indicator
     (such as COND or PROG); otherwise, it returns NIL. 
 
 MAKE-UNDEFINED  sym
     MAKE-UNDEFINED makes the symbol  undefined.  Current
     definition  of  ,  if any, is discarded.  It returns
      as its value. 
 
 
6.3 The Property List 
 
Every  symbol is associated with its "property list", which is
a list used for associating certain Lisp objects with symbols.
A  property  list has an even number of elements; each pair of
elements  constitutes  a  property.   The first of the pair is
called  the "indicator" or the "name" of the property, and the
second is a Lisp object called the "value" of the property. 
 
Example: 
     A property list which have the form 
           (JAPAN TOKYO ENGLAND LONDON FRANCE PARIS)
     indicates  that  there  are three properties named JAPAN,
     ENGLAND  and  FRANCE,  and their values are TOKYO, LONDON
     and PARIS, respectively. 
 
When a symbol is created, its property list is initially NIL. 
 
Note:   Print-names,  bindings  and functional definitions are
often  implemented  as  properties  of symbols in various Lisp
systems,   however,   they   are   not  implemented  as  usual
"properties" in this system. 
 
 GET  sym name
     GET searches for a property of  named .  If it
     finds  such  a  property,  it  returns  the value of that
     property; otherwise, it returns NIL. 
 
     Note:   If  the  value  of  a  property  is  NIL,  it  is
     impossible  to distinguish whether the property exists or
     not, only from the result of GET. 
 
 PUTPROP  sym value name
     If  the  symbol  has no property with its name being
     ,  then  PUTPROP  adds  a new property named 
     with  the  value  ;  otherwise,  the  value of the
     existing property is updated to .  PUTPROP returns
      as its resulting value. 
 
 DEFPROP  »Macroº sym name value
     (DEFPROP x y z) ==> (PUTPROP 'x 'y 'z) 
 
 REMPROP  sym name
     REMPROP removes the property of  with its name being
     .   If    has no such property, it merely does
     nothing.  REMPROP returns NIL as its value. 
 
 
Utilisp Manual              - 32 -                    81-09-07
 
 
Aug. 3, 1981                                        6. Symbols
 
 
 
 PLIST  sym
     PLIST returns the property list of . 
 
 SETPLIST  sym property-list
     SETPLIST  sets  the  property list of  to .  It returns  as its value. 
 
 
6.4 The Print Name 
 
Every symbol has an associated string called the "print-name",
or  "pname"  for  short.   This  string is used as the printed
representation of the symbol in input and output operations. 
 
Though  print-names  are  normal character string objects (see
Chapter  8,  Strings,  for  more  information  about strings),
modifying  them  (by  SSET, etc.) requires certain care, since
they  are  used  to  "hash"  symbols into the Lisp name table,
"obvector" (see Chapter 11, Input and Output, for details). 
 
 PNAME  sym
     PNAME returns the print-name of the symbol . 
 
 
6.5 Creation of Symbols 
 
 SYMBOL  pname
     SYMBOL  creates  and returns a new symbol with its print-
     name being . 
 
 GENSYM  (prefix) (begin)
     GENSYM  generates  a  new  print-name,  and creates a new
     "uninterned" symbol with that print-name (see Chapter 11,
     Input and Output, for "interning"). 
 
     The  generated  print-name is prefixed by a string, which
     is initially "G" but can be changed by supplying GENSYM a
     string  argument .  The prefix string is followed
     by a 4-digit decimal representation of an integer number.
     This  number  is  incremented by one every time GENSYM is
     called  and only the least significant 4 digits are used.
     This number can also be initiated by giving a "fixnum" to
     GENSYM as its second argument . 
 
     Examples: 
           (GENSYM)  =>  G0034
           (GENSYM "GEN")  =>  GEN0035
           (GENSYM "ABC" 15)  =>  ABC0015
           (GENSYM)  =>  ABC0016
 
     Note:   Print-names  of  symbols  generated by GENSYM are
     primarily   for  ease  of  their  inspection  in  printed
     representations.   After  ten  thousand GENSYM calls, the
     print-name  of  the  generated symbol will be the same as
     the first one, but they are not the same symbol. 
 
See  also  Chapter  11, Input and Output, for INTERN which may
create a symbol with given print-name. 
 
81-09-07                    - 33 -              Utilisp Manual
 
 
7. Numbers                                        Aug. 3, 1981
 
 
 
 
 
7.  Numbers 
 
 
There  are  two  types  of  numbers  in  this  system,  namely
"fixnums" and "flonums". 
 
The  "fixnums"  have  a  signed  integer value of 24 bits.  No
overflow  checking  is  made  on  arithmetical  operations  on
"fixnums".  All the results are treated modulo 2 ** 24. 
 
The  "flonums"  have  a  64-bit  floating point value with the
accuracy of about 15 decimal digits.  Overflows are checked on
arithmetical operations on "flonums", but underflows are not. 
 
"Fixnums"  are  denoted  using  conventional  decimal notation
(e.g., 15) and "flonums" using decimal notation with a decimal
point  (e.g.,  15.0);  "flonums" can also have "exponentiating
part" indicated by the character "¡" (e.g., 1.5¡1). 
 
Functions   described   in  this  chapter  expect  numbers  of
appropriate  types  as  their  arguments; if an argument of an
illegal type is supplied, an error is generated. 
 
Functions  on  numbers can be grouped into three categories by
the  type  of  the numbers they accept:  Functions the name of
which  includes  alphabetic  characters  (e.g.,  PLUS)  can be
applied to both "fixnums" and "flonums".  If all the arguments
are  "fixnums",  the result will be a "fixnum"; otherwise, the
result  will be a "flonum".  Functions consisting only of non-
alphabetic characters are special purpose functions.  If their
names  end  with  the  character  "$" (e.g., +$), they are for
"flonums"  only;  otherwise  (e.g.,  +),  for  "fixnums" only.
These  rules  apply  to  all  the  functions described in this
chapter except explicitly stated otherwise. 
 
Special-purpose  arithmetic  functions  can  be  computed more
efficiently  than  general-purpose  ones,  especially when the
functions using them are compiled. 
 
 
7.1 Numeric Predicates 
 
 ZEROP  x
 0=  x
 0=$  x
     ZEROP,  0=  and  0=$  return  T if  is zero (of proper
     type); otherwise, they return NIL. 
 
 PLUSP  x
 0<  x
 0<$  x
     PLUSP,  0<  and  0<$ return T if  is a positive number
     (of proper type); otherwise, they return NIL. 
 
 
 
 
Utilisp Manual              - 34 -                    81-09-07
 
 
Aug. 3, 1981                                        7. Numbers
 
 
 
 MINUSP  x
 0>  x
 0>$  x
     MINUSP,  0>  and 0>$ return T if  is a negative number
     (of proper type); otherwise, they return NIL. 
 
 ODDP  x
     ODDP  returns T if  is odd; otherwise, it returns NIL.
      must be a "fixnum". 
 
 =  x y
 =$  x y
     =  and  =$  return T if  and  are equal numbers (of
     proper type); otherwise, they return NIL. 
 
     Note:   Equality  of numbers can also be tested using the
     function  EQUAL; equality of "fixnums" can also be tested
     using EQ. 
 
 #  x y
 <>  x y
 #$  x y
 <>$  x y
     #,  <>,  #$ and <>$ return T if  and  are not equal
     numbers; otherwise, they return NIL. 
 
 LESSP  arg . args
 <  arg . args
 <$  arg . args
     LESSP,  <  and <$ returns T if every argument (except the
     last  one)  is  strictly  less  than  the  next argument;
     otherwise, it returns NIL. 
 
 GREATERP  arg . args
 >  arg . args
 >$  arg . args
     GREATERP,  >  and  >$ returns T if every argument (except
     the last one) is strictly greater than the next argument;
     otherwise, it returns NIL. 
 
 <=  arg . args
 <=$  arg . args
     <=  and  <=$ returns T if every argument (except the last
     one)  is  less  than  or  equal  to  the  next  argument;
     otherwise, it returns NIL. 
 
 >=  arg . args
 >=$  arg . args
     >=  and  >=$ returns T if every argument (except the last
     one)  is  greater  than  or  equal  to the next argument;
     otherwise, it returns NIL. 
 
 
 
 
 
 
 
 
81-09-07                    - 35 -              Utilisp Manual
 
 
7. Numbers                                        Aug. 3, 1981
 
 
 
 
7.2 Conversion Functions 
 
 FIX  x
     FIX  converts  a "flonum"  into a "fixnum" and returns
     it; rounding is used for the conversion. 
 
 FLOAT  x
     FLOAT converts a "fixnum"  into a "flonum" and returns
     it. 
 
 
7.3 Arithmetics 
 
 PLUS  . args
 +  . args
 +$  . args
     PLUS,  + and +$ return the sum of its arguments.  With no
     argument, PLUS and + return 0, and +$ returns 0.0. 
 
 MINUS  x
     MINUS returns the negative of . 
 
 DIFFERENCE  arg . args
     DIFFERENCE  returns its first argument minus all the rest
     of its arguments. 
 
 -  arg . args
 -$  arg . args
     With  only  one  argument,  -  and -$ behaves the same as
     MINUS;  they  return  the negative of its argument.  With
     more than one argument, - and -$ are effectively the same
     as DIFFERENCE; they return their first argument minus all
     of the rest of the arguments. 
 
 TIMES  . args
 *  . args
 *$  . args
     TIMES,  *  and  *$  return  the product of its arguments.
     With  no  argument,  TIMES and * return 1, and *$ returns
     1.0. 
 
 QUOTIENT  arg . args
 //  arg . args
 //$  arg . args
     QUOTIENT, // and //$ return the first argument divided by
     all  of  the rest of its arguments.  For //, the division
     performed  is  integer division with truncation; for //$,
     floating-point  division;  for  QUOTIENT, the type of the
     division performed depends on the type of the arguments. 
 
     //  is  written here as "//" rather than "/" since "/" is
     the quoting character in Lisp syntax and must be doubled.
 
 ADD1  x
     (ADD1 x) ==> (PLUS x 1) 
 
 
 
Utilisp Manual              - 36 -                    81-09-07
 
 
Aug. 3, 1981                                        7. Numbers
 
 
 
 1+  x
     (1+ x) ==> (+ x 1) 
 
 1+$  x
     (1+$ x) ==> (+$ x 1.0) 
 
 SUB1  x
     (SUB1 x) ==> (DIFFERENCE x 1) 
 
 1-  x
     (1- x) ==> (- x 1) 
 
 1-$  x
     (1-$ x) ==> (-$ x 1.0) 
 
 INCR  »Macroº var amount
     (INCR var amount) ==> (SETQ var (+ var amount)) 
 
 DECR  »Macroº var amount
     (DECR var amount) ==> (SETQ var (- var amount)) 
 
 REMAINDER  x y
 [  x y
 [$  x y
     REMAINDER,  [  and [$ return the remainder of  divided
     by  .  The sign of the result is the same with  (if
     not zero). 
 
 MAX  arg . args
     MAX returns the largest of its arguments. 
 
 MIN  arg . args
     MIN returns the smallest of its arguments. 
 
 ABS  x
     ABS returns ||, the absolute value of the number . 
 
 EXPT  x y
 ¡  x y
 ¡$  x y
     EXPT,  ¡  and ¡$ return the th power of .   must
     be  a  "fixnum".   When  is a "fixnum" and  is non-
     negative,  then the result will be a "fixnum"; in all the
     other cases, the result will be a "flonum". 
 
 SIN  x
     SIN  computes  and  returns  sin(x).   can be either a
     "flonum" or a "fixnum", and the result is a "flonum". 
 
 COS  x
     COS  computes  and  returns  cos(x).   can be either a
     "flonum" or a "fixnum", and the result is a "flonum". 
 
 TAN  x
     TAN  computes  and  returns  tan(x).   can be either a
     "flonum" or a "fixnum", and the result is a "flonum". 
 
 
 
81-09-07                    - 37 -              Utilisp Manual
 
 
7. Numbers                                        Aug. 3, 1981
 
 
 
 ARCSIN  x
     ARCSIN  computes  and  returns  arc  sin(x).    can be
     either  a  "flonum"  or  a  "fixnum", and the result is a
     "flonum". 
 
 ARCCOS  x
     ARCCOS  computes  and  returns  arc  cos(x).    can be
     either  a  "flonum"  or  a  "fixnum", and the result is a
     "flonum". 
 
 ARCTAN  x
     ARCTAN  computes  and  returns  arc  tan(x).    can be
     either  a  "flonum"  or  a  "fixnum", and the result is a
     "flonum". 
 
 SQRT  x
     SQRT  computes  and  returns the square root of .  
     can be either a "flonum" or a "fixnum", and the result is
     a "flonum". 
 
 LOG  x
     LOG  computes  and  returns the natural logarithm of .
       can  be  either  a  "flonum"  or a "fixnum", and the
     result is a "flonum". 
 
 LOG10  x
     LOG10 computes and returns the ordinary logarithm of .
       can  be  either  a  "flonum"  or a "fixnum", and the
     result is a "flonum". 
 
 EXP  x
     EXP computes and returns a "flonum" the natural logarithm
     of which is . 
 
 
7.4 Logical Operations on Numbers 
 
Following functions treat "fixnums" as bit sequences of 24-bit
long.   If  a  non-fixnum  argument  is  supplied, an error is
generated. 
 
 LOGOR  . args
     LOGOR  returns  bitwise  logical  "or"  of the arguments.
     When no arguments are supplied, 0 is returned. 
 
 LOGAND  . args
     LOGAND  returns  bitwise  logical "and" of the arguments.
     When no arguments are supplied, -1 is returned. 
 
 LOGXOR  . args
     LOGXOR  returns  bitwise  logical "xor" of the arguments.
     When no arguments are supplied, 0 is returned. 
 
 LOGSHIFT  x y
     LOGSHIFT  returns  logically shifted  bits.  If 
     is positive,  is shifted left; if  is negative, 
     is  shifted  right.  Absolute value of  should be less
     than 24. 
 
Utilisp Manual              - 38 -                    81-09-07
 
 
Aug. 6, 1981                                        8. Strings
 
 
 
 
 
8.  Strings 
 
 
A  string is a Lisp object consisting of a sequence of zero or
more  characters.   They  are  primarily used for manipulating
texts.   Print-names  of  symbols  are  also represented using
strings. 
 
Characters  of  a  string  can be independently referenced and
updated  using  SREF  and  SSET,  respectively.  The subscript
origin  for  strings is zero.  If an subscript value specified
is not appropriate, i.e., if it is negative or greater than or
equal  to  the length of the corresponding string, an error is
signalled. 
 
Characters  are  a  "fixnum"  which resides between 0 and 255,
i.e.,  representable  in  one byte (8 bits).  They are usually
treated   as  EBCDIK  character  codes  in  input  and  output
operations. 
 
Strings  can  also  be  used  as vectors of small non negative
integer  "fixnums"  ranging 0 through 255.  This kind of usage
may save a considerable memory space, compared with the use of
normal vectors which requires 4 bytes for each component. 
 
 
8.1 Characters 
 
Characters  are  a  "fixnum"  which resides between 0 and 255.
They   are  treated  as  EBCDIK  codes  in  input  and  output
operations. 
 
 CHARACTER  x
     Some  of the functions manipulating strings require their
     arguments   to  be  a  character.   Though  most  of  the
     functions   introduced   in  this  chapter  automatically
     coerces  strings  or  symbols  to  characters,  there are
     certain cases in which explicit conversion is required. 
 
     CHARACTER  coerces  to a single character, represented
     as  a  "fixnum".  If  is a character, i.e.  a "fixnum"
     which  resides between 0 and 255,  itself is returned.
     If    is  a  non-null  string,  its first character is
     returned.  If  is a symbol, the first character of its
     print-name   is   returned.    Otherwise,   an  error  is
     generated. 
 
 
 
 
 
 
 
 
 
 
 
81-09-07                    - 39 -              Utilisp Manual
 
 
8. Strings                                        Aug. 6, 1981
 
 
 
 
8.2 String Manipulation 
 
Note that the subscript origin for strings is zero. 
 
 STRING  x
     Functions  manipulating strings require string arguments.
     Though  most  of the functions introduced in this chapter
     automatically  coerces  symbols  to  strings,  there  are
     certain cases in which explicit conversion is required. 
 
     STRING  coerces    into a string.  If  is a string,
      itself is returned.  If  is a symbol, its pname is
     returned.   If  is a character, a one-character string
     containing    is  returned.   Otherwise,  an  error is
     generated. 
 
 MAKE-STRING  length (char)
     MAKE-STRING  allocates  and  returns  a new string of the
     length  given  by  .   If  the  optional argument
     ,  which  must be a character, is supplied, all the
     characters  of  the allocated string will be initiated to
     ;  otherwise,  to the "fixnum" 0 (not the character
     code for "0"). 
 
 STRING-LENGTH  string
     STRING-LENGTH   returns   the  number  of  characters  in
     ,  which  is  one more than the largest subscript
     value for . 
 
 STRING-EQUAL  string1 string2
     STRING-EQUAL  compares  two  strings and returns T if two
     strings  have  the  same length and all the corresponding
     characters are the same; otherwise, it returns NIL. 
 
     Comparison  of  equality  of  two  strings  can  also  be
     effected  by  the  function EQUAL though, STRING-EQUAL is
     more specific and, therefore, more efficient. 
 
 STRING-LESSP  string1 string2
     STRING-LESSP compares two strings using dictionary order.
     The  result  is  T if  is the lesser, and NIL if
     they are equal or  is the lesser. 
 
     Examples: 
           (STRING-LESSP "ABC" "ABD")  =>  T
           (STRING-LESSP "ABC" "AB")  =>  NIL
 
 SUBSTRING  string (start) (end)
     SUBSTRING  extracts  a substring of , starting at
     the   character  specified  by    up  to  but  not
     including  the  character  specified by .  Thus, the
     length  of  the  string  returned  will  be    minus
     .   The  default  value for  is the length of
     , and that of  is zero. 
 
     Examples: 
           (SUBSTRING "ABCDE" 1 3)  =>  "BC"
 
Utilisp Manual              - 40 -                    81-09-07
 
 
Aug. 6, 1981                                        8. Strings
 
 
 
           (SUBSTRING "ABCDE" 1)  =>  "BCDE"
           (SUBSTRING "ABCDE")  =>  "ABCDE"
 
     Note:   Even  if  both    and    are omitted,
     SUBSTRING makes a new copy of  and returns it. 
 
 STRING-APPEND  . strings
     Any  number of strings are copied and concatenated into a
     single  string.   If  no  arguments are supplied, STRING-
     APPEND returns a null string "". 
 
 STRING-REVERSE  string
     Returns  a  copy of  with the order of characters
     reversed.   The original string is not physically altered
     (see also the description of STRING-NREVERSE below). 
 
 STRING-NREVERSE  string
     Returns    with the order of characters reversed.
     The  reversing is made on the argument  directly,
     physically  altering  the order of characters in 
     (see also the description of STRING-REVERSE above). 
 
 STRING-SEARCH-CHAR  char string (from)
     STRING-SEARCH-CHAR  searches  for  through 
     starting  at  the  index .  It returns the index of
     the  first appearance of , or NIL if none is found.
      may be a character or a list of characters, in the
     latter case, the subscript of the first occurrence of one
     of  the listed characters is returned.  The default value
     for  is zero. 
 
     Example: 
           (STRING-SEARCH-CHAR "B" "ABCDE")  =>  1
 
 STRING-SEARCH-NOT-CHAR  char string (from)
     STRING-SEARCH-NOT-CHAR  is the same as STRING-SEARCH-CHAR
     except  that  it searches for the occurrence of character
     which is "not" , or, when  is a list, "not" a
     member of . 
 
     Example: 
           (STRING-SEARCH-NOT-CHAR "0" "007")
             =>  2
 
 STRING-SEARCH  key string (from)
     STRING-SEARCH searches for the string  in the string
     .   The  search  begins  at subscript , the
     default  value  of  which is zero.  The value returned is
     the  subscript  of  the  first  character  of  the  first
     instance of , or NIL if none is found. 
 
 TRANSLATE  string table
     TRANSLATE  converts  characters in  using 
as the conversion table.
must be a string of 256 characters. Its subscript-n character substitutes the character whose code is n. The argument is physically altered. TRANSLATE returns the (modified) . 81-09-07 - 41 - Utilisp Manual 8. Strings Aug. 6, 1981 LOWER-CASE »Variableº UPPER-CASE »Variableº Values of LOWER-CASE and UPPER-CASE are standard conversion tables for converting upper-case characters to lower-case ones and the reverse, respectively. These tables are also used by the Lisp reader and the printer (see Chapter 11, Input and Output, for details). STRING-AMEND string1 string2 (from) STRING-AMEND moves characters in into physically altering characters in . All the characters in are moved to the portion of beginning with the specified subscript value . The default value of is zero. STRING-AMEND-AND string1 string2 (from) STRING-AMEND-OR string1 string2 (from) STRING-AMEND-XOR string1 string2 (from) STRING-AMEND-AND, -OR and -XOR are the same as STRING- AMEND except that characters in are not simply moved into , rather, logical "and", "or" or "xor" of characters in and corresponding characters in are moved to a portion of beginning with the specified subscript value . The default value of is zero. 8.3 Manipulation of Characters in Strings Characters of strings can be independently manipulated by following functions. Note that the subscript origin of strings is zero. GETCHAR string index GETCHAR returns the th character of as an interned one-character symbol. Example: (GETCH "ABC" 2) => C SREF string index SREF returns the th character of as a character, i.e., a "fixnum". SSET string index character SSET sets the th character of to , and returns . Utilisp Manual - 42 - 81-09-07 Aug. 6, 1981 8. Strings 8.4 Converting Strings and Numbers Consecutive characters of a string may be considered as a binary representation of an integer number. Following functions are for conversions between such character sequences and "fixnums". CUTOUT string pos length CUTOUT converts a character sequence beginning at the th character of with length into a "fixnum". should be positive and not greater than 3. If is 1 or 2, upper bytes of the result will be padded with zero. SPREAD value length SPREAD converts a "fixnum" into a string which contains the binary representation of . The resulting string has the length , which should be positive and not greater than 3. If cannot be represented in bytes, only lower bytes are converted and overflowed upper bytes are ignored. 8.5 Bit String Manipulation A string can also be regarded as a sequence of binary digits (bits). Thus, an array of logical values can be represented by a string, in which case, one character can hold eight distinct logical values. Using this representation, the memory space required for a large-scale bit table will be eight times smaller than when each character of a string is used to represent one logical value, or thirty-two times than when each vector element is used. To facilitate such a representation of bit tables, following functions are provided by the system. Compact representation of bit tables using following functions may save considerable memory space, however, computing speed will be somewhat slowed down. Note that functions such as STRING-AMEND-AND, -OR and -XOR may also be useful for logical operation on bit tables. BREF string index BREF returns T if th bit of is set; otherwise, it returns NIL. must be non-negative and smaller than eight times the length of . BSET string index value If is non-NIL, the th bit of is set; otherwise, it is reset. must be non- negative and smaller than eight times the length of . BSET returns as its value. 81-09-07 - 43 - Utilisp Manual 9. Vectors Aug. 6, 1981 9. Vectors Vectors are a Lisp object that consists of elements, each of which is a Lisp object again. The individual elements are selected by numerical subscripts origined zero. An error is generated if an subscript value specified is not appropriate, i.e., if it is negative or greater than or equal to the number of the elements. As elements of a vector can be accessed in constant time, it is advantageous compared with list structure consisting of binary "cons" cells when a large amount of data is to be manipulated. Disadvantage of using vectors, compared with lists, is that the size must be known before used. Vectors can be arbitrarily allocated and discarded like "cons" cells; they are independent objects on their own right, rather than being attributes of symbols as in some other Lisp systems. However, it is usually convenient to lambda-bind or assign a vector to a symbol, to use the symbol as its name, since vectors cannot be directly identified by the Lisp reader. Multi-dimensional arrays can be represented by vectors of vectors; vectors the elements of which are vectors again. 9.1 Vector Manipulation VECTOR size (filler) VECTOR allocates and returns a vector with its size being ; its subscript ranges from 0 to minus 1. If the optional argument is not supplied, all the elements of the allocated vector are initiated to NIL. Otherwise, if is supplied, the allocated vector will be initiated using in the same way as the function FILL-VECTOR (see the description of FILL- VECTOR below). VECTOR-LENGTH vector VECTOR-LENGTH returns the number of elements of . VREF vector subscript VREF returns the th element of . VSET vector subscript value VSET sets into the th element of . VSET returns as its value. FILL-VECTOR vector filler FILL-VECTOR fills with specified data and returns (modified) . When is an atom and not a vector, all the elements of become . Utilisp Manual - 44 - 81-09-07 Aug. 6, 1981 9. Vectors When is a list with one or more elements, is filled with the elements of that list. The subscript 0 element of is assigned the "car" of the list, subscript 1, the cadr, and so on. If the list is shorter than , remaining elements of are not affected. If the list is longer, remaining elements of the list are merely ignored. When is a vector, is filled with corresponding elements of the filler vector. If the filler vector is shorter, remaining elements of are not affected. If the filler vector is longer, remaining elements of the filler vector are merely ignored. Examples: When the value of V is a vector with, for example, 10 elements, (FILL-VECTOR V NIL) fills the vector with NIL's. (FILL-VECTOR V '(0 1 2 3 4)) sets first 5 elements of the vector with 0, 1, 2, 3, and 4, respectively. Remaining 5 elements are not affected. If the value of W is another vector with the same size, (FILL-VECTOR V W) copies the contents of W into V. 9.2 References It is often required to pass a vector and its subscript as a pair to functions. It would be more convenient if the pair could be treated just as a variable. UTILISP provides "reference" objects for this purpose. A "reference" is a pointer to an element of a vector. The pointed element can be accessed by DEREF and updated by SETREF. DEREF and SETREF can also be applied to variables, i.e., symbols. It is recommended that DEREF and SETREF should be used in functions which utilize "call-by-reference" parameter, instead of EVAL and SET. REFERENCE vector subscript REFERENCE makes and returns a "reference" pointing to the th element of . DEREF reference DEREF returns the value of ; if it is a symbol, the value of the symbol; if it is a "reference", the element of a vector it is pointing. SETREF reference value SETREF sets to ; if it is a symbol, its value is set; if it is a reference pointer, the pointed element of a vector is set. SETREF returns as its value. 81-09-07 - 45 - Utilisp Manual 9. Vectors Aug. 6, 1981 REFERRED-VECTOR reference REFERRED-VECTOR returns the vector an element of which is pointed by . Note: Computation of this function requires time proportional to the subscript of the element pointed by . REFERRED-INDEX reference REFERRED-INDEX returns the subscript of the vector element pointed by . Note: Computation of this function requires time proportional to the subscript of the element pointed by . See also MAPVECTOR and MAPV (Chapter 4, Mapping) to perform certain computation on all the elements of a vector. Utilisp Manual - 46 - 81-09-07 Aug. 6, 1981 10. Macros 10. Macros 10.1 Evaluation of Macros When a "cons" cell with its "car" being a symbol is evaluated, the evaluator inspects the definition of that symbol. If the definition is a "cons" cell, and its "car" is the symbol MACRO, then that definition is called a "macro". The "cdr" of the definition is treated as a function of one argument. The evaluator applies that function to the "cdr" of the original form. The result of this application is evaluated again by the evaluator, and the value returned by this re-evaluation is finally returned as the result of the evaluation of the original form. Example: Suppose the definition of NCONS is (MACRO LAMBDA (X) (LIST 'CONS (CAR X) NIL)) This is a macro; it is a "cons" the "car" of which is the symbol MACRO. The evaluation process of a form (NCONS 'FOO) is as follows: The evaluator recognizes that the form to be evaluated is a "cons" cell the "car" of which is a symbol, i.e., NCONS; the definition of the symbol NCONS is examined and the "car" of the definition is found to be the symbol MACRO. Then the evaluator takes the "cdr" of the definition, which is a LAMBDA-expression, and applies it to the "cdr" of the original form, i.e., the list ('FOO). X is bound to ('FOO) and the result of the application will be (CONS 'FOO NIL). The evaluator then evaluates this new form in place of the original one. (CONS 'FOO NIL) is evaluated to (FOO) and so the result of (NCONS 'FOO) is, finally, (FOO). Macros can be expanded recursively; expanded form of a macro form can be another macro form, in which case, the expanded form is expanded again, until it becomes a non-macro form. Macros can be used for a variety of purposes. For example, "custom-made" control structures can be easily implemented as macros. Example: WHILE-DO construct such as (WHILE-DO condition . body) can be defined as a macro using MACRO special form as (MACRO WHILE-DO (X) (NCONC (LIST 'LOOP (LIST 'AND (CAR X) '(EXIT))) (CDR X))) which expands the original form into (LOOP (AND condition (EXIT)) . body) 81-09-07 - 47 - Utilisp Manual 10. Macros Aug. 6, 1981 Using macros may result in a considerable time and space overhead while the program is executed interpretively. However, once compiled, programs using macros can be executed as efficiently as those without macros, since the compiler expands macro calls prior to the compilation. Thus, using macros is considered to pay no penalty on run-time performance. Efficient execution can only be realized through compilation anyway. As macros are expanded in compilation time, macros should not refer to global variables. The expansion should be the same in any context (on the assumption that, of course, CAR still means CAR, CDR means CDR, etc). Macros cannot be applied to arguments in the same way as usual functions. Macros takes arguments which are not evaluated yet, while application is calling a function with already evaluated arguments. Thus, calling FUNCALL or APPLY with macros as the first argument will generate an error. 10.2 DEFMACRO Facility Complicated macros must have access to structural details of their argument lists. Such an access requires densely nested CAR and CDR functions, which may not only increase the difficulty of programming but also damages the readability of the resulting program. DEFMACRO facility is provided to facilitate access to portions of the argument list by giving names to portions of the argument list. DEFMACRO »Macroº name arg-pattern . body A DEFMACRO form of the syntax (DEFMACRO name arg-pattern . body) is expanded into (MACRO name (@) . expanded-body) where may be an arbitrarily complicated tree structure of symbols, which serves as a template of the argument list. Its "car" represents the "car" of the argument list, its "cdr", the "cdr" of the list. is almost the same as except that all the accesses to the symbols in are converted to accesses to corresponding portions of the argument list. Example: The WHILE-DO in the former example can be more elegantly defined using DEFMACRO as follows: (DEFMACRO WHILE-DO (CONDITION . BODY) (NCONC (LIST 'LOOP (LIST 'AND CONDITION '(EXIT))) BODY)) Utilisp Manual - 48 - 81-09-07 Aug. 6, 1981 10. Macros 10.3 Backquote Facility It is still not easy to define a macro even with DEFMACRO. The difficulty lies in the fact that two different forms must be considered at a time: The expanded form which will be finally evaluated is one; the form which produces that form is the other, and this form is what the programmer have to write down. The backquote facility is provided to facilitate the construction of the latter. The backquote character (`) is defined as a read macro (see Chapter 11 for detail), which acts similarly to normal single quote (') that makes a QUOTEd form of the S-expression following it. However, when a form included in the following S-expression is preceded by a comma (,), that form is not QUOTEd while all the other portions are effectively QUOTEd. Examples: `X is read in as (QUOTE X) which is the same as 'X. `(A ,B C) is read in as (LIST 'A B 'C). As B is not quoted, it is evaluated when the whole form is evaluated. WHILE-DO macro can be still more elegantly defined as (DEFMACRO WHILE-DO (CONDITION . BODY) `(LOOP (AND ,CONDITION (EXIT)) . ,BODY)) Backquotes can be nested. When backquotes are nested twice, double comma will make a form to be evaluated in the first evaluation of the whole form; a form preceded by a single comma will be evaluated in its second evaluation. 81-09-07 - 49 - Utilisp Manual 11. Input and Output Aug. 7, 1981 11. Input and Output 11.1 Streams Streams are Lisp objects through which I/O operations are performed. Streams may be connected to an external file or to the user terminal. File streams are created by the function STREAM. They should be opened by the functions INOPEN or OUTOPEN before being used. Any number of streams can be connected to a single external file. It is also possible to open two or more streams connected to one file in output mode. However, it is difficult to predict the result of output operations in such cases, since the files are modified through file buffers. STREAM ddname STREAM makes a stream which is connected to the external file defined by (data definition name), which must be a string of one to eight characters. Data definition names can be defined using Lisp functions ALLOC or CALLTSS; they can also be defined using the commands of the operating system. See the next section for details. INOPEN stream INOPEN opens as an input stream. When opening is unsuccessful, an error is generated; otherwise, it returns . Record formats which the current system can deal with as input files are F (Fixed length), FB (Fixed length, Blocked), V (Variable length), and VB (Variable length, Blocked). OUTOPEN stream (lrecl) (blksize) OUTOPEN opens as an output file. If is given, the file will have the logical record length of . If is given, the file will have the block size of . If either of these is not given, these informations are extracted in some other way (from the file label, for example). If no such information is available, the default values for and are used, which are 255 and 2560, respectively. When opening is unsuccessful, an error is generated; otherwise, OUTOPEN returns . The system opens the file as a VB (Variable length, Blocked) format file. CLOSE stream CLOSE closes the file associated with . When closing is unsuccessful, an error is generated; otherwise, it returns . Utilisp Manual - 50 - 81-09-07 Aug. 7, 1981 11. Input and Output OPENFILES »Variableº The value of OPENFILES is a list of streams which are currently open. The most recently opened stream comes first in the list. The list is automatically maintained by INOPEN, OUTOPEN, and CLOSE; the user may not update the value of OPENFILES explicitly. Example: All the files currently open can be closed by: (MAPC OPENFILES (FUNCTION CLOSE)) STREAM-MODE stream STREAM-MODE returns the current state of ; if it is open as an input file, it returns the symbol INOPEN; if it is open as an output file, it returns the symbol OUTOPEN; if it is not open, it returns NIL. LINELENGTH (stream) LINELENGTH returns the length of the current line, for input streams; it returns the maximum line length allowed, for output streams. The default value for is the value of STANDARD-OUTPUT. Note: When has the VB format, its LINELENGTH is 4 less than its logical record length, since LINELENGTH does not include the size of the record descriptor field. LINESIZE (size) With no argument, LINESIZE returns the line length of the terminal as a "fixnum". If the optional argument is supplied, the line length of the terminal stream is set to ; must be positive and less than 256. In the latter case, LINESIZE returns this new line length as its value. CURSOR (stream) CURSOR returns current column position of , where column zero being the first column. The default value of is the value of STANDARD-OUTPUT. COLLEFT (stream) When is an input streams, COLLEFT returns how many more characters exist in the current line; if it is an output streams, it returns how many more characters can be printed on the current line. The default value of is the value of STANDARD-OUTPUT. Note: CURSOR + COLLEFT is always equal to LINELENGTH. STANDARD-INPUT »Variableº STANDARD-OUTPUT »Variableº Values of these variables are streams for which I/O operations are normally performed; values of these variables are used as the default values of stream arguments in various I/O functions. Reading and printing can be elegantly directed to a desired stream by lambda- binding these variables to the stream. Using this style, these variables will recover their old values when they are unbound. 81-09-07 - 51 - Utilisp Manual 11. Input and Output Aug. 7, 1981 The initial values of STANDARD-INPUT and -OUTPUT are the same as those of TERMINAL-INPUT and -OUTPUT, respectively, which are the streams connected with the user terminal (see below). Example: (LET ((STANDARD-INPUT some-stream)) (READ)) is effectively the same as: (READ some-stream) TERMINAL-INPUT »Variableº TERMINAL-OUTPUT »Variableº Values of these variables are the streams which are connected to the user terminal. Example: While the standard output stream is directed to some file stream, messages to the terminal can be explicitly directed to the terminal as in the following example: (LET ((STANDARD-OUTPUT some-stream)) (COND ((NULL L) (PRINT "L is null" TERMINAL-OUTPUT)) (T (MAPC L 'PRINT)))) PROMPT »Variableº Value of PROMPT is a string which is used for prompting input from the terminal. Initial value of PROMPT is ">". It is recommended that subsystems of the Lisp system should bind PROMPT to certain string which identifies the subsystem to notify the terminal user what the prompting system is, or, what kind of input is expected Example: (SETQ NAME (LET ((PROMPT "Who are you? ")) (READ))) 11.2 Allocating Files ALLOC filename ALLOC allocates a file designated by a string . (ALLOC "filename") is the same as (CALLTSS "ALLOC DS(filename) SHR"), or giving a command such as "ALLOC DS(filename) SHR" to the TSS command interpreter. The case of characters in the string is ignored. It returns the data definition name for the file, which is a string of 8 characters, if the allocation is successful; otherwise, if unsuccessful, it returns the return code as a "fixnum". CALLTSS tss-command CALLTSS executes tss commands given by a string . Commands which are executable are ALLOCATE, FREE, ATTRIBUTE, and command procedures including only these; other TSS commands can be executed using the Utilisp Manual - 52 - 81-09-07 Aug. 7, 1981 11. Input and Output function CALL (see the description of CALL in Chapter 18, "Miscellaneous"). The case of characters in the string is ignored. If the command is executed successfully, and certain data definition name (ddname) is available, that ddname, a string of 8 characters, is returned; otherwise, if successful and a ddname is not available but certain data set name (dsname) is available, then that dsname, a string of 44 characters, is returned; otherwise, the return code of the command is returned, which is zero when the command is terminated successfully. Example: (CALLTSS "ALLOC DS(FOOFILE)") => "SYS00013" (CALLTSS "ALLOC DD(SYS00013)") => "A0000.FOOFILE " Note: The dsname always has 44 characters regardless of its real length. Blanks are padded if the file name is shorter than 44 characters. FILE-STREAM filename (member) FILE-STREAM returns a stream object connected to the file specified by , which is a string containing the full name of the file in upper-case letters; the user identifier (such as A3840) cannot be omitted. When the optional argument is supplied, the file specified by must be a PO (Partition Organized) file, and the member of the PO file indicated by will be the file specified; otherwise, the file is regarded to be a simple sequential file. Example: (FILE-STREAM "A3840.LISPLIB.VDATA" "PRIND") 11.3 Printed Representation Lisp objects cannot be directly handled since they are stored inside the machine memory. In order to examine these Lisp objects, the system provides a representation of its objects in the form of printed text; this is called the printed representation. Functions such as PRINT, PRIN1, and PRINC take a Lisp object as their argument, and send the characters of its printed representation to a stream; these functions are known as the printer. The function READ takes characters from a stream, interprets them as a printed representation of a Lisp object, constructs a corresponding object, and returns it; this function is known as the reader. This section describes printed representation of various Lisp objects. 81-09-07 - 53 - Utilisp Manual 11. Input and Output Aug. 7, 1981 11.3.1 The Printer Printing is done either with or without "slashification". The "non-slashified" representation looks simple and readable to human eyes, but they may not be properly read in again by the machine. The "slashified" version can be faithfully converted back into Lisp objects by READ, except for some peculiar objects, namely, streams, vectors, references, and code pieces. The printed representation of an object depends on its type. For a "fixnum": If the "fixnum" is negative, the printed representation is preceded by a minus sign ("-"); if non- negative, no sign is printed. Then comes the decimal representation of the absolute value of the "fixnum". Slashification does not affect the printing of "fixnums". For a "flonum": The printed representation is preceded by a sign ("+" or "-"), then a digit zero ("0"), a decimal point ("."), and the fraction part which is a sequence of decimal digits. Number of digits in the fraction part is specified by the value of the symbol DIGITS. Then comes the exponentiation part indicator ("¡"), sign of the exponentiation part ("+" or "-"), and the value of the exponentiation part in two decimal digits. Thus, the number of characters of the printed representation of a "flonum" is, in total, DIGITS + 7. Slashification does not affect the printing of "flonums". For a symbol: If "slashification" is off, the printed representation is simply the successive characters of the print-name string of the symbol, except that, when the value of USE-LOWER is non-NIL, upper-case characters are converted into corresponding lower-case characters using the value of the symbol LOWER-CASE as the conversion table. If "slashification" is on, some special characters are preceded by the escape character "/". The decision whether escape is required is made using the current readtable, i.e., the current value of the symbol READTABLE. Objects printed with "slashification" are always read back faithfully, provided that the same readtable is used as when it is printed out. For a string: If "slashification" is off, the printed representation is simply the successive characters of the string. If "slashification" is on, the string is printed between double quotes ("), and double quotes inside the string are duplicated. For "cons" cells: The printed representation for "cons" cells tends to favor to lists, rather than dotted pairs. It starts with an open parenthesis. Then, the "car" of the "cons" is printed, and the "cdr" of the "cons" is examined. If it is NIL, a close parenthesis is printed. If it is anything but a "cons", then a space, a dot, a space, and that object is printed followed by a close parenthesis. If it is a "cons", a space is printed and the printing starts again all over from the point after the open parenthesis is printed, using this Utilisp Manual - 54 - 81-09-07 Aug. 7, 1981 11. Input and Output new "cons". This procedure produces the usual printed representation such as those seen in this manual. For a code piece: The printed representation has the syntax C#, where is the name of the code piece, normally the name of the function to which the code piece is associated. Code pieces cannot be read back in properly. For other objects: The printed representation has the syntax #
, where is a character indicating the type of the object ("V" for vectors, "R" for references, "S" for streams), and
is the decimal representation of the current address of the object. The address is merely for convenience in discriminating two objects; the objects may be relocated by the garbage collector. Vectors, references, and streams cannot be read back in properly. DIGITS »Variableº The value of DIGITS, which must be a positive "fixnum", specifies how many digits are to be printed in the fraction part of the printed representation of "flonums". The initial value of DIGITS is 7, and, thus, the length of the printed representation of a "flonum" is, initially, 14. USE-LOWER »Variableº When the value of USE-LOWER is non-NIL, lower-case characters are used in the printed representation of symbols. It does not affect the printed representation of strings. Its initial value is NIL. ATOMLENGTH x ATOMLENGTH returns the length of the printed representation of an atom . The printing is assumed to be "slashified". If is not an atom, an error is generated. The following additional feature is provided for the printed representation of "cons" cells; as a list is printed, PRINT maintains the length of the list so far, and the depth of recursion of printing lists. If the length exceeds the value of the variable PRINTLENGTH, PRINT will terminate the printed representation of the list with "???" and a close parenthesis. If the depth of recursion exceeds the value of the variable PRINTLEVEL, the list will be printed as "?". These features allow abbreviated printing which is concise and suppresses detail. PRINTLEVEL »Variableº PRINTLENGTH »Variableº Values of these variables are used as described above. Their initial values are 4 and 10 respectively. Infinitely deep or long printed representation may be obtained by setting zero to these variables. The special characters used in the printed representations can be changed to any character by setting characters in the string which is the initial value of the symbol SPECIAL- 81-09-07 - 55 - Utilisp Manual 11. Input and Output Aug. 7, 1981 CHARACTERS. SPECIAL-CHARACTERS »Variableº The value of SPECIAL-CHARACTERS is a string the elements of which are characters used for special purpose in printed representations. The index values, the usage of the corresponding characters, and their initial values are as follows: 0 : " " blank space 1 : "(" open parenthesis 2 : ")" close parenthesis 3 : "." dot for dotted notation 4 : "/" escape character 5 : """" string quote 6 : "+" plus sign 7 : "-" minus sign 8 : "." decimal point 9 : "¡" exponentiation part indicator 10 : "#" separator used for codes, streams, etc. 11 : "C" code piece indicator 12 : "S" stream indicator 13 : "V" vector indicator 14 : "R" reference indicator 11.3.2 The Reader The purpose of the reader is to accept characters, interpret them as the printed representation of a Lisp object, and return a corresponding Lisp object. The reader cannot accept all the printed representations; the printed representations of vectors, references, streams, and code pieces cannot be read in again. However, the reader has many features which are not seen in the printer. The reader accepts slashified printed representation of numbers, symbols, strings, and conses. Some special characters can be defined as single character objects, which are read in as a one character symbol of that character. Macro characters can be defined, reading which will cause a call to a function associated with that character. See following sections about the "readtable" and read macros. Symbols with the same print-name are read as the same object. This is realized by keeping all the useful symbols in a table called the "obvector". This table is organized as a hash table the key used is print-names of symbols. The registration process to the "obvector" is called "interning". OBVECTOR »Variableº The value of OBVECTOR is the current obvector. An "interned" symbol is a top-level element of the element of the obvector, the index of which is given by: ([ (HASH (PNAME sy)) (VECTOR-LENGTH OBVECTOR)) Utilisp Manual - 56 - 81-09-07 Aug. 7, 1981 11. Input and Output DEFAULT-OBVECTOR »Variableº Value of DEFAULT-OBVECTOR is the initial value of OBVECTOR. All the predefined symbols are initially registered in this table. OBLIST (obvector) OBLIST returns a list of symbols registered in . The default value of is the current value of the symbol OBVECTOR. The list is newly created each time when this function is called. INTERN »Variableº The value of INTERN is the "interning" function used by the reader, which must be a function of one argument. When a character sequence which is to be interpreted as a symbol is encountered, the Lisp reader calls this function with one argument, the string consisting of the characters of that sequence. The result of reading the symbol will be the result of this function. The initial value of INTERN is the function INTERN (see below). Any user-defined name table management principle can be established by binding INTERN to a user-defined "interning" function. INTERN string (obvector) INTERN first converts all the lower-case characters in to the corresponding upper-case characters ( is physically altered.) The value of the symbol UPPER-CASE is used for this conversion. Then is searched for a symbol which has the print-name STRING- EQUAL to . If it is found, INTERN returns that symbol; if not, a new symbol with its print-name being is created, registered in , and returned as the value of INTERN. The default value for is the current value of the symbol OBVECTOR. INTERN-SOFT string (obvector) INTERN-SOFT works almost the same as INTERN except that it does not create a new symbol. is searched for a symbol with the print-name STRING-EQUAL to . If it is found, a list beginning with that symbol is returned; otherwise, if not found, NIL is returned. REMOB symbol (obvector) REMOB searches for a symbol which is EQ to . If found, it is removed from the table making it hidden from the Lisp reader; if not, nothing is done. It returns NIL as its value. The default value of is the current value of the symbol OBVECTOR. 81-09-07 - 57 - Utilisp Manual 11. Input and Output Aug. 7, 1981 11.3.3 The Readtable The reader is controlled by a vector called the "readtable". A "readtable" is a vector consisting of 256 "fixnum" elements, the index n element of which corresponds to the character of EBCDIK code n, and indicates the nature of the character. Currently, only lower 16 bits of each element are used. Their meanings and the initial values in the default readtable are as follows: X'000001' (LSB) means that this character is an ordinary alphabetic character. All the usual characters have this bit on and others off. X'000002' means that this character is an extended alphabetic character. This bit is currently not used. X'000004' means that this character is a digit. Characters "0" through "9" has this bit on. X'000008' means that this character is a sign. "+" and "-" has this bit on. X'000010' is "alternate meaning" bit. This bit is used in several ways. For example, "-" has this bit on, while it is off for "+". X'000020' means the escape character. "/" has this bit on. X'000040' means that this character should be slashified in a symbol. Characters with special meaning have this bit on. X'000080' means that this character should be slashified when appeared at the top of a symbol. Special characters, signs, and digits have this bit on. X'000100' means string quote character. Double quote has this bit on. X'000200' means macro character. The macro definition (a function with no argument) is in the corresponding position of the macrotable. X'000400' means right parenthesis, ")". X'000800' means dotted pair dot, ".". X'001000' means left parenthesis, "(". X'002000' means blank and alike, which is normally skipped between lexical elements. X'004000' means a single character object. Utilisp Manual - 58 - 81-09-07 Aug. 7, 1981 11. Input and Output X'008000' means that this character terminates a symbol or a number. All the special characters have this bit on. The "macrotable" is used to hold the definition of macro characters. The definition should be a function of no argument, the result of which is returned as the object read in. READTABLE »Variableº MACROTABLE »Variableº Values of READTABLE and MACROTABLE are the current readtable and the macrotable, respectively. The initial value of these variables are the same as those of DEFAULT-READTABLE and -MACROTABLE, respectively (see below). User-defined readtable or macrotable can be used by binding these variable to certain values. DEFAULT-READTABLE »Variableº DEFAULT-MACROTABLE »Variableº Value of these variables are the standard readtable and the macro table of the system. 11.3.4 Setting Readtable Characters can be defined as a macro character by the function READMACRO. When the reader encounters a macro character in the input text, a function associated with that character is called. The result of the function is returned as the return value of READ. READMACRO char fn (readtable) (macrotable) is defined as a macro character associated with . This definition is done in and given as arguments. If they are absent, current values of READTABLE and MACROTABLE are assumed. Examples: The macro character "'" could have been defined by: (READMACRO (CHARACTER "'") (FUNCTION (LAMBDA NIL (LIST 'QUOTE (READ))))) Note that this works not only for (READ) but also for (READ some-stream); the latter binds the variable STANDARD-INPUT to , making (READ) in the definition of the read macro input from that stream. If the backquote character "`" cannot be typed in from certain terminal, an alternative character, say, "%", can be settled for backquote macro by: (READMACRO "%" (VREF MACROTABLE 121)) 121 is the EBCDIC code for "`". Predefined read macros are quote "'", backquote "`", and comma ",". See Chapter 10, Macros, for backquote and comma. Characters may be defined as single character objects. When the reader encounters one of them (except when reading 81-09-07 - 59 - Utilisp Manual 11. Input and Output Aug. 7, 1981 characters in a string), then it is read as an "interned" single character symbol, regardless of preceding or following characters. Single character objects can be defined by the function SINGLE-CHARACTER. SINGLE-CHARACTER char (readtable) is defined as a single character object in . If is not supplied, current value of READTABLE is assumed. Example: (SINGLE-CHARACTER "&") From then on, A&NIL&B will be read as 5 symbols, A, &, NIL, &, and B. 11.4 Input Functions Functions described in this section bind the variable STANDARD-INPUT to the argument , before reading any character in. Thus, input is always performed on STANDARD- INPUT stream. The default value of is the current value of STANDARD-INPUT. READ (stream) READ reads in one printed representation of a Lisp object from , and returns it as its value. READLINE (stream) READLINE reads the current line, from current position to the line end, and return a string consisting of the characters read in. The next character input from the stream will be the first character on the next line. SKIPLINE (stream) SKIPLINE works the same as READLINE except that it returns NIL, instead of a string. CURRENT-LINE (stream) CURRENT-LINE returns the current line of as a string object. Returned string includes all the characters in the current input line, regardless of the current character position. The character position is not affected. TYI (stream) TYI inputs one character from and returns its code as a "fixnum". TYIPEEK (stream) TYIPEEK returns the next character of . The difference with TYI is that TYIPEEK does not advance the current character position of . Thus, consecutive calls of TYIPEEK will result the same. Utilisp Manual - 60 - 81-09-07 Aug. 7, 1981 11. Input and Output READCH (stream) READCH is the same as TYI, except that, instead of returning a character as a "fixnum", it returns an "interned" symbol the print-name of which is a one- character string of the character read in. 11.5 Output Functions The functions in this section first binds the variable STANDARD-OUTPUT to the argument , before any actual output. Thus, output operations are always performed on the STANDARD-OUTPUT stream. The default value for is the current value of the symbol STANDARD-OUTPUT. PRIN1 x (stream) PRIN1 outputs the printed representation of to , with "slashification". The value of PRIN1 is . PRINT x (stream) PRINT works the same as PRIN1, except that PRINT terminates the current line after printing out. PRINC x (stream) PRINC is the same as PRIN1 except that the printing is done without "slashification". TYO char (stream) TYO outputs the character whose EBCDIK code is specified by to . TYO returns as its value. TERPRI (stream) TERPRI terminates the current line of . TERPRI returns NIL as its value. TAB n (stream) TAB will set the character position of at the column . If the current character position is less than , spaces are printed out until the column is reached; if the current position exceeds the column , the line is terminated and spaces are put out on the next line. TAB returns NIL as its value. 11.6 Formatted Printing It is often required to print an S-expression in the midst of a certain message. For example, given a symbol and a number , one might require such an output as "The symbol appeared times." with and varying time to time. Of course, this can be achieved by (PROGN (PRINC "The symbol ") (PRIN1 sy) (PRINC " appeared ") (PRIN1 num) (PRINC " times.") 81-09-07 - 61 - Utilisp Manual 11. Input and Output Aug. 7, 1981 (TERPRI)) but this looks ugly and not readable. This kind of output is required so often that the system provides formatted printing facility. FORMAT »Macroº pattern . args FORMAT is a macro for formatted printing. The first argument is a string specifying the output format and the rest of the arguments is a list of forms which are evaluated and used according to . The string is normally printed out as it is. However, when a slant character (/) is encountered, printing is controlled by the directive character immediately following it. If the directive character requires arguments, values of are used sequentially from left to right. Control directive characters currently available and their meanings are as follows: S: prints one S-expression with "slashification". C: prints one S-expression without "slashification". B: prints one character the code of which is supplied as an argument. G: pretty-prints one S-expression. T: tabulates to the column specified by the argument. N: terminates the current line. /: prints "/", i.e., a slant should be doubled. Case of directive characters is ignored. Example: The former example can be printed by (FORMAT "The symbol /S appeared /S times./N" sy num) 11.7 Indented Printing Printed representations of S-expressions are not easily examined by human eyes, especially when parentheses are densely nested. The indented printer PRIND will help you producing more readable outputs by giving appropriate indention. PRIND x (width) (asblock) (level) (length) is printed with certain indention. is the maximum width for printing, the default value of which is the line length of the current output stream. When is non-NIL, then the print out will be more compact than when it is NIL (the readability may be somewhat damaged). The default value of is NIL. When and arguments are supplied, they must be non-negative "fixnums", and when they are non- zero, the maximum level and length of printing lists will Utilisp Manual - 62 - 81-09-07 Aug. 7, 1981 11. Input and Output be and , respectively. QUOTE forms such as (QUOTE A) are printed as 'A. Moreover, when the value of the variable USEBQ is non- NIL, backquotes and commas are used for printing CONS and LIST forms; (LIST A 'B C) is printed as `(,A B ,C), (CONS 'A B) as `(A . ,B). PRIND returns NIL as its value, unlike PRINT which returns its first argument. USEBQ »Variableº When the value of USEBQ is non-NIL, backquotes and commas are used in the print-out of PRIND. The initial value of USEBQ is NIL. PP »Macroº funcname The definition of the symbol is printed so that the definition will be recovered when the print-out is read in and evaluated. Usual functions are printed as (DEFUN funcname argument-list . body) Macros defined using DEFMACRO are printed as (DEFMACRO funcname argument-pattern . body) Other macros are printed as (MACRO funcname argument-list . body) 81-09-07 - 63 - Utilisp Manual 12. Code Pieces Aug. 13, 1981 12. Code Pieces Code pieces are a Lisp object which contains machine language instructions and some Lisp objects which are accessed from the code. Though code pieces may itself be used as functions, it is usually more convenient to use their names, i.e., symbols, as functions. Code pieces are either predefined by the system or obtained by compiling lambda forms. A code piece has its name, which is normally a function symbol associated with that code piece. FUNCNAME code FUNCNAME returns the name of . Number of arguments for a code piece may be restricted to reside in some range. The minimum and the maximum numbers of arguments are stored somehow in the code pieces for run-time checking, and can be examined by the following functions. MINARG code MAXARG code MINARG and MAXARG return the minimum and the maximum number of arguments for , respectively. The values returned by these functions may not always be precise. However, it is guaranteed that an error is generated when is applied to less arguments than the result of MINARG or more than the result of MAXARG. If allows arbitrarily many arguments, MAXARG returns -1. A code piece can be constructed by the following function. LOAD-CODE x LOAD-CODE constructs and returns a codepiece specified by the argument , which has the syntax (name maxarg machine-code quoted) where is the name of the function, is the maximum number of arguments of the function, is a list of "fixnums" each of which represents one half-word (16 bits) of the machine code, and, finally, is a list of Lisp objects accessed from the machine code. Utilisp Manual - 64 - 81-09-07 Aug. 13, 1981 13. Compilation 13. Compilation The Lisp compiler is a program which translates interpretive functions, which have the form of lists, into machine codes which are directly executed by the hardware. The merit of compilation is that the execution speed will be considerably improved. 13.1 Compiling Functions COMPILE »Macroº . function-names The compiler can be evoked by simply applying the macro COMPILE as (COMPILE . function-names) where is a list of symbolic atoms the definitions of which are lambda forms. The definition of these symbols will be replaced by the compiled code. COMPILE returns the list as its value. Example: Interpretive functions F and G can be compiled by: (COMPILE F G) REVERT »Macroº . function-names The interpretive definition of a function which is compiled using COMPILE is saved in the property list of the function symbol as its PREVIOUS-DEFINITION property. REVERT sets the definition of the symbols in to their PREVIOUS-DEFINITION properties. REVERT returns as its value. The calling interface of compiled and interpretive functions are totally compatible. Thus, a compiled function may call interpretive functions and vice versa. Macro calls in the definition of the function being compiled are expanded before the compilation. Thus, such macros must be defined before the compilation. Usually, the compiler generates various run-time check codes. When the program has been completed and there is no possibility of errors, these check codes may be superfluous. The following variables are used to give direction to the compiler whether such check codes are required or not. TYPECHECK »Variableº When the value of TYPECHECK is non-NIL, the compiler generates type check codes; otherwise, no run-time type check code is generated. The initial value of TYPECHECK is T. 81-09-07 - 65 - Utilisp Manual 13. Compilation Aug. 13, 1981 UBVCHECK »Variableº When the value of UBVCHECK is non-NIL, the compiler generates check codes for unbound variables; otherwise, unbound variables are not checked in the object code. The initial value of UBVCHECK is T. INDEXCHECK »Variableº When the value of INDEXCHECK is non-NIL, the compiler generates check codes for array or string index range; otherwise, no run-time check code for index range is generated. The initial value of INDEXCHECK is T. 13.2 Declaration Various declarations may be required for exact compilation. The macro DECLARE and the function RESET-COMPILATION-FLAGS are provided for such declarations. DECLARE »Macroº item-list indicator DECLARE is used to declare that the elements of have the attribute indicated by . Currently, the indicators used are SPECIAL and REDEFINE. RESET-COMPILATION-FLAGS RESET-COMPILATION-FLAGS revokes all the declarations effected via the macro DECLARE so far. The compiled object is designed so as to use "static" scope rule for local variables (usual Lisp scope rule is so-called "dynamic" scope rule). For exact compilation of functions which utilize global variables, all the non-locally referred variables (i.e., variables referred from functions other than that which binds the variable) should be declared to be SPECIAL. The declaration of SPECIAL variables can be effected by (DECLARE var-list SPECIAL) where is a list of non-locally referred variables. Example: When variables X and Y are used non-locally, they should be declared SPECIAL before compiling functions which binds them by: (DECLARE (X Y) SPECIAL) If a non-local variable is not properly declared, the compiler treats the variable as a local variable; the value of a local variable is stored somewhere on the system stack access to which can only be possible from the function which binds the variable. For calls to some of the predefined functions (such as ATOM, CAR, CDR, etc.), the compiler generates certain machine-code sequences which work effectively the same as these functions. Thus, if some of the predefined standard functions are to be redefined by the user program, they should be declared by (DECLARE fn-list REDEFINE) where is a list of the names of predefined functions Utilisp Manual - 66 - 81-09-07 Aug. 13, 1981 13. Compilation which are to be redefined. 13.3 Storing Compiled Objects The compiler puts the compiled code in a relocatable form (in a form of list of numbers and some Lisp objects) in the property list of the name of the compiled function as its COMPILED-CODE property. This can be printed to a file as a normal lisp object and can later be read back in. This relocatable form can be converted into machine code object (code piece) by the function LOAD-CODE. The result of LOAD- CODE may be put into the definition cell of the function name by the function PUTD (see Chapter 12, Code Pieces, for details). Example: If the relocatable compiled code for the function F is stored in the file connected to an input stream which is the value of the variable OBJ, the definition of F can be loaded by: (PUTD 'F (LOAD-CODE (READ OBJ))) 13.4 Difference from the Interpreter As the compiled object is designed so as to attain efficient execution, some differences exist between the run-time behaviour of compiled codes and interpretive codes. Non-local GO and RETURN in PROG forms as well as non-local EXIT in LOOP forms are not allowed in compiled functions. Only available non-local exit structure is that provided by CATCH and THROW. Because of certain difficulty of implementation, the arguments of CATCH are evaluated interpretively. Thus, variables which are referred to in the arguments of CATCH should be declared to be SPECIAL. 13.5 Providing Space for Compiled Codes Compiled codes are stored in an area called FIXED-HEAP which is different from usual HEAP for ordinary Lisp objects. When a large amount of code should be compiled, the size of the FIXED-HEAP must be specified to be large enough. This can be achieved by supplying an optional parameter "FIX" to the TSS command "LISP" as >>LISP FIX(n) where is a number indicating how many pages (1024 words/page) should be provided for compiled objects. The default value of is 8. As the garbage collector does not collect garbages in the FIXED-HEAP area, re-compilation of functions leaves uncollectable garbages. See Chapter 15, Memory Management System, for details. 81-09-07 - 67 - Utilisp Manual 14. Errors and Debugging Aug. 18, 1981 14. Errors and Debugging 14.1 The Error System The system generates an error when some invalid operation is tried by the program; for example, when the "car" of an atom has been taken. When an error is generated, the value of the symbol corresponding to the kind of the error is examined. The value is interpreted as a function, which is called by the system with one argument; it depends upon the kind of the error what this argument is. The initial value for these symbols are the symbols themselves. These symbols themselves are defined as standard error handlers, which print an appropriate error diagnostic message, the information passed as the argument, and the function in which, or while evaluating arguments of which, the error took place. Then the value of the symbol BREAK is examined, which must be a function of no argument, and this function is then called in the environment where the error has occurred (the variables have the same values as when the error took place). The result of this function call will be the result of the function during the evaluation of which the error occurred. BREAK »Variableº The value of BREAK is a function which is called by the standard error handlers after printing error diagnostics. The initial value of BREAK is BREAK itself. BREAK BREAK first binds STANDARD-INPUT and -OUTPUT to the streams connected to the terminal, READTABLE and MACROTABLE to the standard ones, PROMPT to the string "@", and then enters a READ-EVAL-PRINT loop similar to the top-level loop. This loop can be terminated by the function UNBREAK (see below). UNBREAK . args UNBREAK can be used to terminate a BREAK loop. The inner-most BREAK loop is terminated and the value returned by that BREAK will be the last argument of UNBREAK. If no BREAK encloses an UNBREAK call, an error is generated. Following are the variables the values of which are used as the error handlers, and, at the same time, function names of the standard error handlers. The initial values of these variables are themselves. The optional argument is interpreted as the function name where the error has occurred. The default value of is the function from which the error handler is called. When an error handler is to be called explicitly (usually by FUNCALL), an appropriate function name should be given for this optional argument. Utilisp Manual - 68 - 81-09-07 Aug. 18, 1981 14. Errors and Debugging Example: The function CADR could have been defined as: (DEFUN CADR (X) (COND ((OR (ATOM X) (ATOM (CDR X))) (FUNCALL ERR:ARGUMENT-TYPE X 'CADR)) (T (CAR (CDR X))))) ERR:ARGUMENT-TYPE »Variableº ERR:ARGUMENT-TYPE x (where) The type of was not valid for the function applied to it. ERR:BUFFER-OVERFLOW »Variableº ERR:BUFFER-OVERFLOW dc (where) A string or a symbol is read in which is longer than the string buffer. The size of the string buffer is, currently, 1000 characters. is always NIL. ERR:CATCH »Variableº ERR:CATCH tag (where) THROW was called with its first argument being , but the corresponding CATCH with its first argument EQ to was no found. ERR:END-OF-FILE »Variableº ERR:END-OF-FILE stream (where) The end of the file was reached while reading the file associated with . is automatically closed. ERR:FLOATING-OVERFLOW »Variableº ERR:FLOATING-OVERFLOW dc (where) An arithmetical overflow occurred during a floating-point arithmetic operation. is always NIL. ERR:FUNCTION »Variableº ERR:FUNCTION x (where) was used as a function but is illegal as a function, i.e., a non-symbolic atom or a "cons" cell which is not a LAMBDA form. ERR:GO »Variableº ERR:GO tag (where) A GO form was evaluated with but the corresponding PROG that has the label in its body was not found. ERR:INDEX »Variableº ERR:INDEX index (where) was used as an index for a vector or a string, but is out of index range or not even a "fixnum". ERR:IO »Variableº ERR:IO stream (where) was used for some I/O operation but has not been opened properly; an input stream was used for output, the reverse case, or was not open at all. 81-09-07 - 69 - Utilisp Manual 14. Errors and Debugging Aug. 18, 1981 ERR:NUMBER-OF-ARGUMENTS »Variableº ERR:NUMBER-OF-ARGUMENTS dc (where) The number of arguments for a function was too many or too few. is always NIL. ERR:OPEN-CLOSE »Variableº ERR:OPEN-CLOSE stream (where) Opening or closing of failed. Usually, some diagnostic message, besides that of the Lisp system, is printed out by the operating system. ERR:READ »Variableº ERR:READ dc (where) The character sequence read in cannot be interpreted as an S-expression. This error is often caused by an improper usage of dots ("."). ERR:RETURN »Variableº ERR:RETURN dc (where) RETURN, EXIT, or UNBREAK was called but the corresponding PROG, LOOP, or BREAK was not found. is always NIL. ERR:UNBOUND-VARIABLE »Variableº ERR:UNBOUND-VARIABLE var (where) was evaluated but is unbound. ERR:UNDEFINED-FUNCTION »Variableº ERR:UNDEFINED-FUNCTION fn (where) The symbol was used as a function but is undefined. ERR:VARIABLE »Variableº ERR:VARIABLE x (where) was used as a variable but is not a symbol. ERR:ZERO-DIVISION »Variableº ERR:ZERO-DIVISION dc (where) Division by zero was attempted. This error may occur in both integer and floating arithmetics. is always NIL. Two special errors are handled quite differently. They are the overflow of the system stack and the shortage of the available memory. When a stack overflow occurs, or when the garbage collector failed to collect enough memory for computation, a diagnostic message indicating the kind of the error is printed, all the variables recover their top-level values, and the system resumes the top-level loop. When a stack overflow occurs during a garbage collection, the system prints out a message and the Lisp session is terminated abnormally, since such a situation is fatal and recovery is impossible. Utilisp Manual - 70 - 81-09-07 Aug. 18, 1981 14. Errors and Debugging 14.2 Attention Handling When the execution of a Lisp program is interrupted from the terminal (usually by the break key), the attention interrupt handler is called. If the system is during a certain I/O operation, this call will be postponed until the termination of that I/O. ATTENTION-HANDLER »Variableº The value of ATTENTION-HANDLER is the attention interrupt handler, which must be a function of no argument. The initial value of ATTENTION-HANDLER is BREAK. 14.3 The Debugger The debugger is a collection of functions which are useful in debugging Lisp programs. As debugger is designed for interpretive functions, it is recommended to debug programs in interpretive form and then compile them into machine codes (see Section 12, Compilation, for details). TRACE »Macroº . funcnames TRACE takes arbitrarily many arguments which are names of interpretive functions. The functions listed in become "traced"; the function name and arguments are printed on entry to these functions, the name and the result of the function are printed on exit, with the nesting level, in appropriate indention. "Tracing" is effected by automatically rewriting the definition of the "traced" functions. This alteration can be restored by the function UNTRACE. TRACE-WHEN »Macroº pred . funcnames TRACE-WHEN is the same as TRACE except that tracing is conditional. The form is evaluated each time a function listed in is called, and that function call will be "traced" if and only if the value of evaluating is non-NIL. As arguments to the function are already bound when is evaluated, may depend upon the arguments. UNTRACE »Macroº . funcnames UNTRACE stops "tracing" of the functions listed in . BACKTRACE (n) With no argument, BACKTRACE returns a list of the names of all the functions which are nesting around the current environment. When is supplied, a list of the names of only innerly nested functions is returned. Inside the BREAK loop of the standard error handler, this function can be used to examine the calling sequence upto where the error has occurred. 81-09-07 - 71 - Utilisp Manual 14. Errors and Debugging Aug. 18, 1981 OLDVALUE (n) With no argument, OLDVALUE returns a list of dotted pairs. The "car" of each pair is a variable which is bound by lambda-binding and the "cdr" is its previous value before the binding. If the variable had been in unbound state before the binding, its previous value is indicated by the symbol *UBV*. The order in the list is such that recently bound variables come earlier. When is supplied, only pairs concerning recent bindings are included. This function can be used to get information on the binding history. TOPLEVEL TOPLEVEL first undoes all the variable bindings except top-level ones. Then the value of the variable TOPLEVEL is examined. The value must be a function of no argument, and this function is then called. As the initial value of the TOPLEVEL is the symbol UTILISP, TOPLEVEL can be used to resume the top-level loop. TOPLEVEL »Variableº The value of TOPLEVEL is a function of no argument which is used as the Lisp top-level. The initial value of TOPLEVEL is UTILISP. 14.4 The Low-Level Debugger The low-level debugger is a collections of function for debugging the UTILISP system itself. As they are primarily prepared for maintainance of the system, some of them are not safe; misuse of them may cause a fatal error. They should be used with proper knowledge of the physical represenation of various Lisp objects. ADDRESS x ADDRESS returns the current memory address of as a "fixnum". If is a "reference", the address of the vector element pointed by is returned. If is a "fixnum", itself is returned. Note: The Lisp objects may be relocated by the garbage collector, except for those which are allocated in the FIXED-HEAP area. PEEK addr length PEEK returns a string which contains a copy of the machine memory beginning at (ADDRESS addr) and long. Utilisp Manual - 72 - 81-09-07 Aug. 18, 1981 15. Memory Management System 15. Memory Management System The memory space used by the UTILISP system is divided into six areas. They are, HEAP for usual Lisp objects FIXED-HEAP for predefined objects and compiled codes STREAM-HEAP for streams STACK for control information and temporary storage KERNEL for the system kernel SAVED for I/O buffer and external programs The size of the FIXED-HEAP, STACK and SAVED areas can be specified by the parameters at the initiation of the Lisp system (see Chapter 1, Introduction, for details). The sizes of the STREAM-HEAP and KERNEL areas are system-defined constants. The size of the HEAP area can be set by the function HEAP-SIZE. As the system uses the "copying garbage collection" scheme, the maximum size allowed for the HEAP area is half the memory size available. The size of the area available for the HEAP area is the maximum memory size allowed for a user job by the operating system minus the total size of all the other areas. When an object is to be allocated, by CONS for example, and not enough space is left in the HEAP area (or STREAM-HEAP for streams), then the garbage collector is called. The garbage collector gathers all the Lisp objects which can never be accessed; the memory space occupied by them becomes reusable. Then, the execution of the original program is resumed. The garbage collector of the UTILISP system is not only for collecting garbages but also for compactifying and linearizing Lisp objects to keep the "working set" small. For this purpose, the garbage collector can be called before the available space has been completely exhausted; it is automatically called when the size of the HEAP area reached the size set by the system. This size is twice as large as the area occupied by accessible Lisp objects after the previous collection, as long as it is between the minimum specified and the maximum allowed. Initially, this minimum size is set equal to the maximum. Thus, the garbage collector is evoked only when the available space has been completely exhausted. The garbage collector can also be called explicitly by the function GC. GC GC evokes the garbage collector. It returns NIL as its value. Following functions are for asking states and setting 81-09-07 - 73 - Utilisp Manual 15. Memory Management System Aug. 18, 1981 parameters of the memory management system. The unit of memory space used in these functions is "word" (four bytes). GCCOUNT GCCOUNT returns a "fixnum" which indicates how many times the garbage collector has been called since the system initiation. GCTIME GCTIME returns a "fixnum" indicating CPU time required for GC so far. The unit used is mili-second. HEAP-SIZE (size) With no argument, HEAP-SIZE returns a list of the form (heap fixed) where is the current size of the HEAP area and is the size of the FIXED-HEAP area. When is supplied, the size of the HEAP area is set to . must be a "fixnum" greater than the size of the HEAP area already in use, and less than the allowed maximum. MINIMUM-HEAP-SIZE (size) With no argument, MINIMUM-HEAP-SIZE returns the minimum heap size used to decide the size of the HEAP area after garbage collections. When is supplied, the minimum heap size is set to . MAXIMUM-HEAP-SIZE MAXIMUM-HEAP-SIZE returns the maximum size allowed for the HEAP area. HEAP-USED HEAP-USED returns a list of the form (current cumulative fixed) is the size of the HEAP area currently in use. As this includes garbages, it is precise only immediately after garbage collections. is the size of the HEAP area currently in use plus total size of the HEAP area collected by the garbage collector since the system initiation. This size is, of course, equal to the total size of the Lisp objects allocated in the HEAP area so far. is the size of the FIXED-HEAP area currently in use. STACK-SIZE STACK-SIZE returns the size of the STACK area. STACK-USED STACK-USED returns the size of the STACK area currently in use. Utilisp Manual - 74 - 81-09-07 Sep. 1, 1981 16. Structure Editor - USE 16. Structure Editor - USE USE (Utilisp Structure Editor) is a structure-oriented editor for inspecting and changing list structures, which may be Lisp programs or data. One merit of using USE, compared with text-oriented editors such as TECO or QED, is that editing is done on Lisp data structures themselves, rather than on their printed representations; USE has the knowledge of the hierarchical structure of the edited data, and the editing commands of USE reflect this hierarchy. Another merit is that the editing is done in the Lisp environment; arbitrary Lisp form can be evaluated during editing and currently edited structures can also be manipulated by Lisp functions. USE always manipulates a copy of the original list structure; all the atoms in the copy are the same with the original ones, but all the "cons" cells are newly created for the copy. Thus, when a USE session is aborted by a K (Kill) command, the original program or data is not affected at all. 16.1 Invoking USE Following macros are used to invoke USE and, on their normal termination, restore the edited result. ED »Macroº fn ED invokes USE for editing interpretive functions. The definition of will be edited. ED puts edited result in the definition cell of on normal termination. EDV »Macroº var EDV invokes USE for editing values of variables. The value of is edited. EDV sets edited result in the definition cell of , on normal termination. EDP »Macroº sym EDP invokes USE for editing properties of symbols. The property list of is edited, and the result will become the property list of , on normal termination. EDF »Macroº file-name EDF invokes USE for editing text files containing printed representations of Lisp objects. is evaluated first. Its result must be a string representing the name of the file to be edited. It is often convenient to set a file name to a variable and use that variable as the argument of EDF, since a file name may be quite complicated. A a string indicating the file name may also be used directly as an argument of EDF, since a string is evaluated to itself. What is edited is a list of all all the objects the printed representations of which are stored in the file. 81-09-07 - 75 - Utilisp Manual 16. Structure Editor - USE Sep. 1, 1981 The order of the elements in the list is the same as in the file. In other words, an extra left and a right parentheses are assumed at the beginning and at the end of the file. The top-level elements of the result of editing will be printed back to the file on normal termination. Note: Rewriting an external file does not affect the state of the Lisp objects, even if the file contains function definitions such as DEFUN or MACRO forms. The content of the file must be evaluated to effect redefinition. EDL »Macroº loc EDL invokes USE for editing some data which cannot be edited through ED, EDV nor EDP. should be a form to access a component of certain structure, for example, (CAR cons) to access the "car" of a "cons" cell , (VREF vec n) to access th element of a vector . is evaluated first, and its value will be edited by USE. The result will be put back to where it was derived from, on normal termination. USE x USE is the USE system itself. It is normally called using above macros, but users may also call USE directly. USE returns one component list of the edited result, when the USE session is normally terminated; it returns NIL when it is terminated abnormally (by K command). 16.2 USE Session USE prompts terminal input by "?" when it is expecting a command. If a symbol or a number is is typed in, it is interpreted as a command; otherwise, especially when you type in a list, the list is interpreted as a form which is evaluated and the result is printed. When the form is evaluated, the symbol ? is bound to the current "scope" (see the next section for details). The E command can be used to evaluate an atom. E form The form
is evaluated and the result is printed. Arbitrarily many commands and their operands may be typed on a single line. They are executed sequentially, as long as no error is found. When an error is found, the rest of the current input line will be ignored. Following commands are for terminating a USE session. Q Q (Quit) terminates the current session normally. If USE is called from one of the macros described in the previous section, edited result is restored accordingly. Utilisp Manual - 76 - 81-09-07 Sep. 1, 1981 16. Structure Editor - USE K K (Kill) terminates the current session abnormally. If USE is called by one of the macros described in the previous section, edited result is merely discarded, and the original definition, value, property list, etc. are not affected. 16.3 Scope and Position Numbers The editor always have current "scope", which is a portion of the whole S-expression being edited. This "scope" can be nested; the current scope can be an element of its parent scope, and this parent scope can have its parent, and so on. All insertion, deletion, and replacement are effected only inside the current scope. When the current scope is a list, elements in the list can be specified by their positions. A positive "fixnum" n represents the n'th element. A negative number -n represents the n'th element counted from the last. 1 the first element and -1 means the last. Examples: If the current scope is (A B C D E F G), 1 means A. 3 means C. -1 means G. -3 means E. 10 is invalid. -10 is invalid. 16.4 Pattern Matching Rules It is sometimes desired to search a certain pattern of S- expressions, without specifying its detail. For example, a form SETQing to a symbol X may be of programmer's concern irrespective of the value assigned. This example can be expressed as (SETQ X ?). The rules of pattern matching are quite simple: 1) A pattern matches an S-expression EQUAL to it. 2) ? matches any S-expression. 3) ??? matches any portion of a list. Examples: (CAR X) matches (CAR X) but not (CAR '(A B)). (CAR ?) matches both (CAR X) and (CAR '(A B)). (CONS ? ?) matches both (CONS X X) and (CONS X Y). (LIST ???) matches both (LIST) and (LIST X Y Z). (A ??? Z) matches any of (A Z), (A B Z), or (A B C D E Z). 81-09-07 - 77 - Utilisp Manual 16. Structure Editor - USE Sep. 1, 1981 16.5 Printing Current Scope P P (Print) command prints the current scope in usual abbreviated way. See Chapter 10, Input and Output, for abbreviated printing. PP PP (Pretty Print) command prints the current scope with appropriate indention. See Chapter 10, Input and Output, for pretty-printing. LEVEL n LENGTH n LEVEL and LENGTH commands are used to set the maximum printing level and length in abbreviated printing to . should be a "fixnum". Note: The level and the length specified by these commands are only effective in one USE session. The values of PRINTLEVEL and PRINTLENGTH are not affected. 16.6 Changing the Scope n -n 0 Position numbers themselves are commands to change the scope to the position specified. The command 0 changes the scope to the parent of the current scope, i.e. a list which contains the current scope as its element. TOP TOP command changes the scope to the whole S-expression being edited. N N (Next) command moves the scope to the element next to the current scope in the parent scope. When there is no parent scope or the current scope is the last element of the parent scope, it is an error. B L (Last) command moves the scope to the element one before the current scope in the parent scope. When there is no parent scope or the current scope is the first element of the parent scope, it is an error. W W (Where) command prints where the current scope is beginning from the top level. Utilisp Manual - 78 - 81-09-07 Sep. 1, 1981 16. Structure Editor - USE 16.7 Searching F pattern F (Find) command searches an S-expression which "matches" in textual order (searches "car" before "cdr"). Searching is done in the current scope only. If one is found, the scope is changed to the S-expression found. The intermediate scopes are saved and can be accessed using the command "0". If is not found, a message is generated and the scope remains unchanged. FF pattern FF (Find Forward) command is the same as F command except that the search begins from after the current scope. FB pattern FB (Find Backward) command is the same as F command except that the search is performed in reverse direction ("cdr" before "car") and the search begin from before the current scope. FN FN (Find Next) command is the same as FF command except that the same is used as previous F, FF or FB command. 16.8 Inserting and Deleting Parentheses BI m n BI (Both In) command inserts an open parenthesis at the left of and a close parenthesis at the right of . and are position numbers. Example: BI 2 4 (A B C D E) ==> (A (B C D) E) BO n BO (Both Out) command deletes the parentheses enclosing which should be a list. is a position number. It is the inverse operation of BI. Example: BO 2 (A (B C D) E) ==> (A B C D E) LI n LI (Left In) command inserts an open parenthesis at the left of . is a position number. Example: LI 2 (A B C D E) ==> (A (B C D E)) RI n RI (Right In) command inserts a close parenthesis at the right of . is a position number. Example: RI 2 81-09-07 - 79 - Utilisp Manual 16. Structure Editor - USE Sep. 1, 1981 (A B C D E) ==> ((A B) C D E) LO n LO (Left Out) command moves the open parenthesis of to the beginning of the current scope. must a position number which specifies a list. Example: LO 2 (A (B C D) E) ==> ((A B C D) E) RO n RO (Right Out) command moves the close parenthesis of to the end of the current scope. should be a position number specifying a list. Example: RO 2 (A (B C D) E) ==> (A (B C D E)) 16.9 Inserting and Deleting S-expressions I pos sexpr I (Insert) command inserts at the right of . If is a number, it is interpreted as a position number. Otherwise, it is interpreted as a pattern and the first S-expression found to match is assumed. To use a number as a pattern, quote the number like '3. In this case, the quote is not included in the pattern used for matching. Examples: (A B C D E) I 3 X ==> (A B C X D E) I B (FOO BAR) ==> (A B (FOO BAR) C X D E) Note: Insertion to the top of a list can be achieved by specifying 0 for . A sexpr A (Append) command replaces the tail of the current scope by . If the current scope is atomic, the whole scope is replaced by . Examples: NIL A (A B C) ==> (A B C) A D ==> (A B C . D) IN sexpr IN (Insert Next) commands inserts at the right of the current scope in the parent scope. Utilisp Manual - 80 - 81-09-07 Sep. 1, 1981 16. Structure Editor - USE D pos D (Delete) command deletes from current scope. The meaning of is the same as in I command. Examples: (A B C D E) D 3 ==> (A B D E) D B ==> (A D E) Y pos Y (Yank) command inserts an S-expression most recently saved by USE at the right of . What is saved is either the S-expression deleted using D command, S- expression replaced using R command, or the result of evaluating a form which is typed in instead of a command. The meaning of is the same as in I command. This command can be used, with D command, to move a portion of S-expression inside the edited structure. Examples: (A B C D E) D 3 ==> (A B D E) Y A ==> (A C B D E) (CONS 'A 'B) => (A . B) Y 3 ==> (A C B (A . B) E) 16.10 Replacing S-expressions R pos expr R (Replace) command replaces with . has the same meaning as in I command. Example: R 3 (FOO BAR) (A B C D E) ==> (A B (FOO BAR) D E) RA pattern expr RA (Replace All) command replaces all S-expressions in the current scope which matches with . Number of actual replacements is reported. Example: RA X Y (A X B X C) ==> (A Y B Y C) 2 OCCURRENCES ARE REPLACED 81-09-07 - 81 - Utilisp Manual 17. Calling External Programs Aug. 26, 1981 17. Calling External Programs External programs, such as TSS command processors or assembly language routines, can be envoked from the Lisp system using the functions introduced in this chapter. Data can be passed as the parameters to external programs or as the values of "command symbols" (see the manuals of VOS3 for details of "command symbols"). 17.1 Calling TSS Commands CALL command (param) The TSS command indicated by is called. A string , if present, is passed to the command processor as its parameter string. It returns NIL if the execution of is terminated normally; otherwise, it returns the return code of the as a "fixnum". Note: Command procedures and previledged commands (including commands concerning file protection) cannot be executed using CALL. 17.2 Calling User-Defined Programs User defined programs (which may be coded in the assembly language) can be loaded to the memory using the function PROGRAM-LOAD. Such a program can be evoked using PROGRAM-CALL and it can be removed from the memory space by PROGRAM-DELETE when it is no longer necessary. The calling interface to the program is as follows: Register 1: the address of the parameter list which consists of four words. The first word contains an address of a word which contains a pointer to a Lisp object specified as the parameter. The second word contains the address of the UPT, the third word, the address of the PSCB, and the fourth word, the address of the ECT. See the VOS3 manual no. 8090-3-007 about UPT, PSCB and ECT. Register 13: the address of the register save area. Register 14: the return address. Register 15: the entry address of the called program. When a program called by the function PROGRAM-CALL is terminated abnormally, the Lisp system itself also terminates abnormally. Thus, such a program must be coded with certain care. If the program is to be called more than once, the REUS attribute must be specified when the program is linked (see the VOS3 manual no. 8080-3-301 about REUS attribute). Utilisp Manual - 82 - 81-09-07 Aug. 26, 1981 17. Calling External Programs PROGRAM-LOAD name ddname The program specified by is loaded from the file which is assigned the data definition name . When the loading is successible, the symbol T is returned; otherwise, the returned code of the LOAD macro is returned. PROGRAM-CALL entry (param) The program specified by is called with the interface described above. PROGRAM-CALL returns the return code of the called program. PROGRAM-DELETE The program which has the entry name is deleted. PROGRAM-DELETE returns NIL as its value. 17.3 Manipulating Command Symbols Command symbols can hold either an integer value or a character string value. The values of the command symbols can be defined and detected using following functions. The name of a command symbol must begin with an upper-case letter followed by an arbitrary sequence of upper-case letters and digits, and must not be longer than 32 characters. DEFCS name value If the command symbol specified by has not been defined, a new command symbol whose name being is defined and given the value specified by the argument . If it is already defined, then is set as the new value of the command symbol. must be a "fixnum" or a string containing upto 256 characters. DEFCS returns as its value. DETCS name If the command symbol specified by is defined, DETCS returns its value, which is a "fixnum" or a string. If it is not defined, NIL is returned. DELCS name If the command symbol specified by is defined, it is deleted. If it is not defined, DELCS merely does nothing. DELCS returns NIL. 81-09-07 - 83 - Utilisp Manual 18. Miscellaneous Sep. 2, 1981 18. Miscellaneous This chapter describes functions that do not seem to fit anywhere else. TIME (form) With no argument, TIME returns the CPU time elapsed by the Lisp system since its initiation. This includes the time required for garbage collection and for external programs which are called using PROGRAM-CALL, but excludes the time consumed by external programs called using CALL. If the optional argument is supplied, is evaluated again, and CPU time required for this re-evaluation is returned. The time is returned as a "fixnum" object in mili-seconds. QUIT (retcode) QUIT will return control to the caller of the Lisp system, usually to tss command level, with return code . The default value of is 0. All the files opened by in the Lisp system will be automatically closed. ABEND (retcode) ABEND abnormally terminates the Lisp system with return code . The default value of is 4095. VERSION »Variableº The value of VERSION is a string which indicates version of the system. NEWS NEWS will print out news from the implementer. HELP »Macroº sym HELP can be used to get information of the symbol from this manual. The portion of the manual beginning with the title is printed. This printing can be stopped by an attention interrupt (usually by the break key). HELP returns NIL as its value. DATE-TIME DATE-TIME returns a string containing the date and time. The string has the format "YYMMDDHHMMSSCC" where YY are two least significant digits of the year, MM, month, DD, day, HH, hour in 24-hour system, MM, minute, SS, second, CC, centi-second. Example: At 5:30 in the evening of January the 20th, 1981, (DATE-TIME) => "81012017300000" Utilisp Manual - 84 - 81-09-07 Sep. 2, 1981 18. Miscellaneous USERID USERID returns user-id of the current TSS session as a string. UTILISP UTILISP is the top-level loop of the UTILISP system. An S-expression is read in, evaluated and printed. This is repeated again and again. The prompting character of the top-level loop is ">". This symbol UTILISP is the initial value of the symbol TOPLEVEL (see Chapter 14, Errors and Debugging, for details). ? »Variableº Each time the a form read in is evaluated in a UTILISP loop or in a BREAK loop, the result is set to the variable ?. Example: In the top-level UTILISP loop, (CONS 'FOO 'BAR) => (FOO . BAR) ? => (FOO . BAR) 81-09-07 - 85 - Utilisp Manual Appendix - Differences in MTS Appendix: Differences in MTS The description preceeding describes UTILISP as it exists in the Hitachi system it was written for originally, except that sections 1.1 and 1.2 have been updated to reflect the way it is run in MTS. Most of the other differences between the Hitachi and MTS versions are minor and should cause no problems for someone familiar with MTS. This appendix will attempt to list them. Page 50: The parameter to OUTOPEN is irrelevant in MTS and is ignored. Page 51: The comment about format VB records in the description of LINELENGTH is irrelevant and should be ignored. Page 50ff: All references to "ddname" should be changed to refer to a FDUB pointer or Logical I/O Unit name. ALLOC returns a FDUB pointer, for example Page 51: The initial assignment of the various standard I/O streams is as follows: STANDARD-INPUT = SCARDS STANDARD-OUTPUT = SPRINT TERMINAL-INPUT = GUSER TERMINAL-OUTPUT = SERCOM Page 52: The CALLTSS function is not implemented in MTS. Page 53: The FILE-STREAM function takes a full MTS FDName as a parameter. It will not accept a library member name and all discussion of PO files should be ignored. Page 66: There is an additional compiler control variable. If UDFCHECK is non-NIL the compiler will check for undefined functions when making calls from compiled code. Page 73: The description of SAVED in the discussion of memory management should be ignored. It is irrelevant in MTS. Page 82: The CALL function can be used to execute any MTS command, except that if the command is RUN, LOAD, DEBUG, or RERUN, UTILISP will be unloaded and CALL will never return. Page 83: PROGRAM-CALL and PROGRAM-LOAD have been changed significantly (even in the Hitachi version) and the description here is not correct. Page 84: Section 17.3 about command symbols is not relevant to MTS and should be ignored. Appendix Index Sep. 8, 1981 Symbol Index < arg . args .................................... 35 <$ arg . args ................................... 35 <> x y .......................................... 35 <>$ x y ......................................... 35 <= arg . args ................................... 35 <=$ arg . args .................................. 35 + . args ........................................ 36 +$ . args ....................................... 36 * . args ........................................ 36 *$ . args ....................................... 36 ¡ x y ........................................... 37 ¡$ x y .......................................... 37 - arg . args .................................... 36 -$ arg . args ................................... 36 // arg . args ................................... 36 //$ arg . args .................................. 36 > arg . args .................................... 35 >$ arg . args ................................... 35 >= arg . args ................................... 35 >=$ arg . args .................................. 35 ? »Variableº .................................... 85 # x y ........................................... 35 #$ x y .......................................... 35 = x y ........................................... 35 =$ x y .......................................... 35 ABEND (retcode) ................................. 84 ABS x ........................................... 37 ADDRESS x ....................................... 72 ADD1 x .......................................... 36 ALLOC filename .................................. 52 AND »Special Formº . args ....................... 13 APPEND . lists .................................. 24 APPLY fn arglist ................................ 9 ARCCOS x ........................................ 38 ARCSIN x ........................................ 38 ARCTAN x ........................................ 38 ASS predicate item alist ........................ 28 ASSOC item alist ................................ 28 ASSQ item alist ................................. 28 ATOM arg ........................................ 7 ATOMLENGTH x .................................... 55 ATTENTION-HANDLER »Variableº .................... 71 Index - 1 Sep. 8, 1981 Index BACKTRACE (n) ................................... 71 BOUNDP variable ................................. 31 BREAK ............................................ 68 BREAK »Variableº ................................ 68 BREF string index ............................... 43 BSET string index value ......................... 43 C...R x ......................................... 22 CALL command (param) ............................ 82 CALLTSS tss-command ............................. 52 CAR x ........................................... 22 CATCH tag . forms ............................... 18 CDR x ............................................ 22 CHARACTER x ..................................... 39 CLOSE stream .................................... 50 CODEP arg ........................................ 8 COLLEFT (stream) ................................ 51 COMMENT »Special Formº . args ................... 10 COMPILE »Macroº . function-names ................ 65 COND »Special Formº . clauses ................... 14 CONS x y ........................................ 22 CONSP arg ....................................... 7 COPY x .......................................... 22 COS x ........................................... 37 CR x ............................................ 22 CURRENT-LINE (stream) ........................... 60 CURSOR (stream) ................................. 51 CUTOUT string pos length ........................ 43 DATE-TIME ........................................ 84 DECLARE »Macroº item-list indicator ............. 66 DECR »Macroº var amount ......................... 37 DEFAULT-MACROTABLE »Variableº ................... 59 DEFAULT-OBVECTOR »Variableº ..................... 57 DEFAULT-READTABLE »Variableº .................... 59 DEFCS name value ................................ 83 DEFINEDP sym .................................... 31 DEFMACRO »Macroº name arg-pattern . body ........ 48 DEFPROP »Macroº sym name value .................. 32 DEFUN »Macroº name lambda-list . body ........... 31 DELCS name ...................................... 83 DELQ item list (n) .............................. 27 DEREF reference ................................. 45 DETCS name ...................................... 83 DIFFERENCE arg . args ........................... 36 DIGITS »Variableº ............................... 55 DO »Macroº index-part exit-part . body .......... 17 ED »Macroº fn ................................... 75 EDF »Macroº file-name ........................... 75 EDL »Macroº loc ................................. 76 EDP »Macroº sym ................................. 75 EDV »Macroº var ................................. 75 EQ x y .......................................... 8 EQUAL x y ....................................... 8 ERR:ARGUMENT-TYPE x (where) ..................... 69 ERR:ARGUMENT-TYPE »Variableº .................... 69 ERR:BUFFER-OVERFLOW dc (where) .................. 69 Index - 2 Index Sep. 8, 1981 ERR:BUFFER-OVERFLOW »Variableº .................. 69 ERR:CATCH tag (where) ........................... 69 ERR:CATCH »Variableº ............................ 69 ERR:END-OF-FILE stream (where) .................. 69 ERR:END-OF-FILE »Variableº ...................... 69 ERR:FLOATING-OVERFLOW dc (where) ................ 69 ERR:FLOATING-OVERFLOW »Variableº ................ 69 ERR:FUNCTION x (where) .......................... 69 ERR:FUNCTION »Variableº ......................... 69 ERR:GO tag (where) .............................. 69 ERR:GO »Variableº ............................... 69 ERR:INDEX index (where) ......................... 69 ERR:INDEX »Variableº ............................ 69 ERR:IO stream (where) ........................... 69 ERR:IO »Variableº ............................... 69 ERR:NUMBER-OF-ARGUMENTS dc (where) .............. 70 ERR:NUMBER-OF-ARGUMENTS »Variableº .............. 70 ERR:OPEN-CLOSE stream (where) ................... 70 ERR:OPEN-CLOSE »Variableº ....................... 70 ERR:READ dc (where) ............................. 70 ERR:READ »Variableº ............................. 70 ERR:RETURN dc (where) ........................... 70 ERR:RETURN »Variableº ........................... 70 ERR:UNBOUND-VARIABLE var (where) ................ 70 ERR:UNBOUND-VARIABLE »Variableº ................. 70 ERR:UNDEFINED-FUNCTION fn (where) ............... 70 ERR:UNDEFINED-FUNCTION »Variableº ............... 70 ERR:VARIABLE x (where) .......................... 70 ERR:VARIABLE »Variableº ......................... 70 ERR:ZERO-DIVISION dc (where) .................... 70 ERR:ZERO-DIVISION »Variableº .................... 70 EVAL x .......................................... 9 EVERY list predicate ............................ 28 EXIT . args ..................................... 17 EXP x ........................................... 38 EXPT x y ........................................ 37 FIFTH x ......................................... 23 FILE-STREAM filename (member) ................... 53 FILL-VECTOR vector filler ....................... 44 FIRST x ......................................... 23 FIX x ........................................... 36 FIXP arg ........................................ 7 FLOAT x ......................................... 36 FLOATP arg ...................................... 7 FORMAT »Macroº pattern . args ................... 62 FOURTH x ........................................ 23 FUNCALL fn . args ............................... 9 FUNCNAME code ................................... 64 FUNCTION »Special Formº fn ...................... 10 GC ............................................... 73 GCCOUNT .......................................... 74 GCTIME ........................................... 74 GENSYM (prefix) (begin) ......................... 33 GET sym name .................................... 32 GETCHAR string index ............................ 42 GETD sym ........................................ 31 Index - 3 Sep. 8, 1981 Index GO »Special Formº tag ........................... 16 GREATERP arg . args ............................. 35 HASH x .......................................... 29 HEAP-SIZE (size) ................................ 74 HEAP-USED ........................................ 74 HELP »Macroº sym ................................ 84 INCR »Macroº var amount ......................... 37 INDEXCHECK »Variableº ........................... 66 INOPEN stream ................................... 50 INTERN string (obvector) ........................ 57 INTERN »Variableº ............................... 57 INTERN-SOFT string (obvector) ................... 57 LAST list ....................................... 23 LENGTH list ..................................... 23 LESSP arg . args ................................ 35 LET »Macroº bindings . body ..................... 11 LETS »Macroº bindings . body .................... 12 LINELENGTH (stream) ............................. 51 LINESIZE (size) ................................. 51 LIST . args ..................................... 24 LISTP arg ....................................... 7 LOAD-CODE x ..................................... 64 LOG x ........................................... 38 LOGAND . args ................................... 38 LOGOR . args .................................... 38 LOGSHIFT x y .................................... 38 LOGXOR . args ................................... 38 LOG10 x ......................................... 38 LOOP »Special Formº . body ...................... 17 LOWER-CASE »Variableº ........................... 42 MACRO »Macroº name lambda-list . body ........... 31 MACROTABLE »Variableº ........................... 59 MAKE-STRING length (char) ....................... 40 MAKE-UNBOUND variable ........................... 31 MAKE-UNDEFINED sym .............................. 32 MAP list fn ..................................... 20 MAPC list fn .................................... 20 MAPCAN list fn .................................. 21 MAPCAR list fn .................................. 20 MAPCON list fn .................................. 21 MAPLIST list fn ................................. 20 MAPV vector fn .................................. 21 MAPVECTOR vector fn ............................. 21 MAX arg . args .................................. 37 MAXARG code ..................................... 64 MAXIMUM-HEAP-SIZE ................................ 74 MEM predicate item list ......................... 27 MEMBER item list ................................ 27 MEMQ item list .................................. 27 MIN arg . args .................................. 37 MINARG code ..................................... 64 MINIMUM-HEAP-SIZE (size) ........................ 74 MINUS x ......................................... 36 MINUSP x ........................................ 35 Index - 4 Index Sep. 8, 1981 NCONC . lists ................................... 25 NCONS x ......................................... 22 NEQ x y ......................................... 8 NEWS ............................................. 84 NOT x ........................................... 8 NREVERSE list ................................... 25 NTH n list ...................................... 24 NTHCDR n list ................................... 24 NULL x .......................................... 8 NUMBERP arg ..................................... 7 OBLIST (obvector) ............................... 57 OBVECTOR »Variableº ............................. 56 ODDP x .......................................... 35 OLDVALUE (n) .................................... 72 OPENFILES »Variableº ............................ 51 OR »Special Formº . args ........................ 13 OUTOPEN stream (lrecl) (blksize) ................ 50 PEEK addr length ................................ 72 PLIST sym ....................................... 33 PLUS . args ..................................... 36 PLUSP x ......................................... 34 PNAME sym ....................................... 33 POP »Special Formº var .......................... 25 PP »Macroº funcname ............................. 63 PRINC x (stream) ................................ 61 PRIND x (width) (asblock) (level) (length) ...... 62 PRINT x (stream) ................................ 61 PRINTLENGTH »Variableº .......................... 55 PRINTLEVEL »Variableº ........................... 55 PRIN1 x (stream) ................................ 61 PROG »Special Formº locals . body ............... 15 PROGN »Special Formº . args ..................... 10 PROGRAM-CALL entry (param) ...................... 83 PROGRAM-DELETE .......................... 83 PROGRAM-LOAD name ddname ........................ 83 PROG1 »Special Formº . args ..................... 11 PROG2 »Special Formº . args ..................... 11 PROMPT »Variableº ............................... 52 PUSH »Special Formº item var .................... 25 PUTD sym def .................................... 31 PUTPROP sym value name .......................... 32 QUIT (retcode) .................................. 84 QUOTE »Special Formº arg ........................ 10 QUOTIENT arg . args ............................. 36 READ (stream) ................................... 60 READCH (stream) ................................. 61 READLINE (stream) ............................... 60 READMACRO char fn (readtable) (macrotable) ...... 59 READTABLE »Variableº ............................ 59 REFERENCE vector subscript ...................... 45 REFERENCEP arg .................................. 7 REFERRED-INDEX reference ........................ 46 REFERRED-VECTOR reference ....................... 46 Index - 5 Sep. 8, 1981 Index REMAINDER x y ................................... 37 REMOB symbol (obvector) ......................... 57 REMPROP sym name ................................ 32 REMQ item list (n) .............................. 28 RESET-COMPILATION-FLAGS .......................... 66 RETURN . args ................................... 17 REVERSE list .................................... 24 REVERT »Macroº . function-names ................. 65 RPLACA x y ....................................... 26 RPLACD x y ...................................... 26 [ x y ........................................... 37 [$ x y .......................................... 37 SECOND x ........................................ 23 SELECTQ »Special Formº key-form . clauses ....... 14 SET variable new-value .......................... 30 SETPLIST sym property-list ...................... 33 SETQ »Special Formº . args ...................... 30 SETREF reference value .......................... 45 SEVENTH x ....................................... 24 SIN x ........................................... 37 SINGLE-CHARACTER char (readtable) ............... 60 SIXTH x ......................................... 23 SKIPLINE (stream) ............................... 60 SOME list predicate ............................. 28 SORT table predicate ............................ 29 SPECIAL-CHARACTERS »Variableº ................... 56 SPECIALP sym .................................... 32 SPREAD value length ............................. 43 SQRT x .......................................... 38 SREF string index ............................... 42 SSET string index character ..................... 42 STACK-SIZE ....................................... 74 STACK-USED ....................................... 74 STANDARD-INPUT »Variableº ....................... 51 STANDARD-OUTPUT »Variableº ...................... 51 STREAM ddname ................................... 50 STREAM-MODE stream .............................. 51 STREAMP arg ...................................... 7 STRING x ........................................ 40 STRING-AMEND string1 string2 (from) ............. 42 STRING-AMEND-AND string1 string2 (from) ......... 42 STRING-AMEND-OR string1 string2 (from) .......... 42 STRING-AMEND-XOR string1 string2 (from) ......... 42 STRING-APPEND . strings ......................... 41 STRING-EQUAL string1 string2 .................... 40 STRING-LENGTH string ............................ 40 STRING-LESSP string1 string2 .................... 40 STRING-NREVERSE string .......................... 41 STRING-REVERSE string ........................... 41 STRING-SEARCH key string (from) ................. 41 STRING-SEARCH-CHAR char string (from) ........... 41 STRING-SEARCH-NOT-CHAR char string (from) ....... 41 STRINGP arg ..................................... 7 SUBST x y z ..................................... 26 SUBSTRING string (start) (end) .................. 40 SUB1 x .......................................... 37 Index - 6 Index Sep. 8, 1981 SYMBOL pname .................................... 33 SYMBOLP arg ..................................... 7 TAB n (stream) .................................. 61 TAN x ........................................... 37 TERMINAL-INPUT »Variableº ....................... 52 TERMINAL-OUTPUT »Variableº ...................... 52 TERPRI (stream) ................................. 61 THIRD x ......................................... 23 THROW tag . values .............................. 19 TIME (form) ..................................... 84 TIMES . args .................................... 36 TOPLEVEL ......................................... 72 TOPLEVEL »Variableº ............................. 72 TRACE »Macroº . funcnames ....................... 71 TRACE-WHEN »Macroº pred . funcnames ............. 71 TRANSLATE string table .......................... 41 TYI (stream) .................................... 60 TYIPEEK (stream) ................................ 60 TYO char (stream) ............................... 61 TYPECHECK »Variableº ............................ 65 UBVCHECK »Variableº ............................. 66 UNBREAK . args .................................. 68 UNTRACE »Macroº . funcnames ..................... 71 UPPER-CASE »Variableº ........................... 42 USE x ........................................... 76 USE-LOWER »Variableº ............................ 55 USEBQ »Variableº ................................ 63 USERID ........................................... 85 UTILISP .......................................... 85 VECTOR size (filler) ............................ 44 VECTOR-LENGTH vector ............................ 44 VECTORP arg ..................................... 7 VERSION »Variableº .............................. 84 VREF vector subscript ........................... 44 VSET vector subscript value ..................... 44 XCONS y x ....................................... 22 ZEROP x ......................................... 34 0< x ............................................ 34 0<$ x ........................................... 34 0> x ............................................ 35 0>$ x ........................................... 35 0= x ............................................ 34 0=$ x ........................................... 34 1+ x ............................................ 37 1+$ x ........................................... 37 1- x ............................................ 37 1-$ x ........................................... 37 Index - 7