













                         XLISP: An Object-oriented Lisp

                                  Version 2.1c

                                February 6, 1988


                                       by
                               David Michael Betz
                                  P.O. Box 144
                             Peterborough, NH 03458

                              (603) 924-4145 (home)

                    Copyright (c) 1988, by David Michael Betz
                               All Rights Reserved
            Permission is granted for unrestricted non-commercial use




           Additional features u_n_d_e_r_l_i_n_e_d_, by Tom Almy August 5, 1991.

     This distributed version has enhancements  which can be eliminated via
     compilation options. Portions from  XLISP-STAT are Copyright (c) 1988,
     Luke  Tierney. UNIXSTUF.C  is  from from  Winterp 1.0,  Copyright 1989
     Hewlett-Packard Company  (by Niels Mayer). Other  enhancements and bug
     fixes are provided without restriction by Tom Almy, Mikael Pettersson,
     Neal  Holtz, Johnny Greenblatt, and  Ken Whedbee. See  source code for
     details.









                                Table of Contents

     INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . . . . . .    1

     A NOTE FROM THE AUTHOR  . . . . . . . . . . . . . . . . . . . . .    2

     XLISP COMMAND LOOP  . . . . . . . . . . . . . . . . . . . . . . .    3

     BREAK COMMAND LOOP  . . . . . . . . . . . . . . . . . . . . . . .    5

     DATA TYPES  . . . . . . . . . . . . . . . . . . . . . . . . . . .    6

     THE EVALUATOR . . . . . . . . . . . . . . . . . . . . . . . . . .    9

     HOOK FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . . .   10

     LEXICAL CONVENTIONS . . . . . . . . . . . . . . . . . . . . . . .   11

     READTABLES  . . . . . . . . . . . . . . . . . . . . . . . . . . .   13

     LAMBDA LISTS  . . . . . . . . . . . . . . . . . . . . . . . . . .   15

     OBJECTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17

     SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21

     EVALUATION FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . .   23

     SYMBOL FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . .   25

     PROPERTY LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . .   29

     HASH TABLE FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . .   30

     ARRAY FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . .   31

     SEQUENCE FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . .   32

     LIST FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . . .   37

     DESTRUCTIVE LIST FUNCTIONS  . . . . . . . . . . . . . . . . . . .   41

     ARITHMETIC FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . .   42

     BITWISE LOGICAL FUNCTIONS . . . . . . . . . . . . . . . . . . . .   47

     STRING FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . .   48

     CHARACTER FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . .   50

     STRUCTURE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . .   52

     OBJECT FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . .   54







     XLISP 2.1c                 Table of Contents


     PREDICATE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . .   56

     CONTROL CONSTRUCTS  . . . . . . . . . . . . . . . . . . . . . . .   60

     LOOPING CONSTRUCTS  . . . . . . . . . . . . . . . . . . . . . . .   63

     THE PROGRAM FEATURE . . . . . . . . . . . . . . . . . . . . . . .   64

     INPUT/OUTPUT FUNCTIONS  . . . . . . . . . . . . . . . . . . . . .   66

     THE FORMAT FUNCTION . . . . . . . . . . . . . . . . . . . . . . .   68

     FILE I/O FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . .   71

     STRING STREAM FUNCTIONS . . . . . . . . . . . . . . . . . . . . .   74

     DEBUGGING AND ERROR HANDLING FUNCTIONS  . . . . . . . . . . . . .   76

     SYSTEM FUNCTIONS  . . . . . . . . . . . . . . . . . . . . . . . .   78

     ADDITIONAL FUNCTIONS AND UTILITIES  . . . . . . . . . . . . . . .   83

     BUG FIXES AND EXTENSIONS  . . . . . . . . . . . . . . . . . . . .   87

     EXAMPLES: FILE I/O FUNCTIONS  . . . . . . . . . . . . . . . . . .   94

     INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   96







     XLISP 2.1c                   INTRODUCTION                       Page 1




     INTRODUCTION

     XLISP is  an experimental programming  language combining some  of the
     features of Common Lisp  with an object-oriented extension capability.
     It  was  implemented  to allow  experimentation  with  object-oriented
     programming on small computers.

     There are currently implementations of XLISP running on the IBM-PC and
     clones under MS-DOS, on  the Macintosh, the Atari-ST and the Amiga. It
     is  completely written in the  programming language 'C'  and is easily
     extended  with  user written  built-in  functions and  classes.  It is
     available in source form to non-commercial users.

     Many  Common Lisp functions are  built into XLISP.  In addition, XLISP
     defines the  objects 'Object' and  'Class' as primitives.  'Object' is
     the only  class that has  no superclass and  hence is the  root of the
     class heirarchy  tree. 'Class' is  the class of which  all classes are
     instances (it is the only object that is an instance of itself).

     This  document  is  a brief  description  of  XLISP.  It assumes  some
     knowledge  of LISP and some  understanding of the  concepts of object-
     oriented programming.

     I recommend  the book  "LISP" by  Winston  and Horn  and published  by
     Addison Wesley for  learning Lisp. The first  edition of this  book is
     based on MacLisp and the second edition is based on Common Lisp. XLISP
     will continue to migrate towards compatibility with Common Lisp.

     You  will probably also need a copy  of "Common Lisp: The Language" by
     Guy L. Steele,  Jr., published by Digital Press to  use as a reference
     for some of the  Common Lisp functions that are described only briefly
     in this document.







     XLISP 2.1c              A NOTE FROM THE AUTHOR                  Page 2



     A NOTE FROM THE AUTHOR

     If you have any problems with XLISP, feel  free to contact me for help
     or advice. Please  remember that  since XLISP is  available in  source
     form in  a high level language,  many users have been  making versions
     available on  a variety of machines.  If you call to  report a problem
     with a specific version, I may not be able to help you if that version
     runs  on  a machine  to which  I don't  have  access. Please  have the
     version  number of the version that you are running readily accessible
     before calling me.

     If you find  a bug in XLISP, first  try to fix the bug  yourself using
     the source code  provided. If you  are successful in  fixing the  bug,
     send the bug report along with the fix to me. If you don't have access
     to a C compiler or are unable to fix a bug, please send the bug report
     to me and I'll try to fix it.

     Any suggestions for improvements will be welcomed. Feel free to extend
     the language in whatever way suits your needs. However, PLEASE DO  NOT
     RELEASE  ENHANCED VERSIONS WITHOUT CHECKING  WITH ME FIRST!!   I would
     like to be the clearing house for  new features added to XLISP. If you
     want to add features for your own personal use, go ahead. But,  if you
     want  to distribute your  enhanced version,  contact me  first. Please
     remember that the goal of XLISP is to provide  a language to learn and
     experiment  with   LISP  and  object-oriented  programming   on  small
     computers. I don't want it to get so big that it requires megabytes of
     memory to run.

     T_h_e_ v_e_r_s_i_o_n_  o_f_ t_h_e_ c_o_d_e_ m_o_d_i_f_i_e_d_ a_n_d_ s_u_p_p_l_i_e_d_ v_i_a_ T_o_m_ A_l_m_y_ a_n_d_ o_t_h_e_r_s_
     h_a_s_  c_o_m_p_i_l_a_t_i_o_n_ o_p_t_i_o_n_s_  t_o_ d_i_s_a_b_l_e_  a_l_l_ e_x_t_e_n_s_i_o_n_s_  t_o_  D_a_v_i_d_ B_e_t_z_'_s_
     o_r_i_g_i_n_a_l_._ O_n_l_y_ b_u_g_f_i_x_e_s_ a_r_e_  u_n_c_o_n_d_i_t_i_o_n_a_l_l_y_ i_n_c_l_u_d_e_d_._ S_e_e_ t_h_e_ s_e_c_t_i_o_n_
     b_e_g_i_n_n_i_n_g_ o_n_  p_a_g_e_ 8_7_ f_o_r_  a_ l_i_s_t_i_n_g_  o_f_ b_u_g_ f_i_x_e_s_  a_n_d_ t_h_e_  e_x_t_e_n_s_i_o_n_
     e_n_a_b_l_e_d_  w_i_t_h_  t_h_e_ v_a_r_i_o_u_s_  c_o_m_p_i_l_a_t_i_o_n_  o_p_t_i_o_n_s_._  A_s_s_i_s_t_a_n_c_e_ o_n_  t_h_i_s_
     v_e_r_s_i_o_n_  (_o_r_ t_h_e_  o_r_i_g_i_n_a_l_)_ c_a_n_  b_e_ o_b_t_a_i_n_e_d_  o_n_ t_h_e_  U_S_E_N_E_T_ n_e_w_s_g_r_o_u_p_
     c_o_m_p_._l_a_n_g_._l_i_s_p_._x_,_  o_r_ b_y_ w_r_i_t_i_n_g_ t_o_  T_o_m_ A_l_m_y_ a_t_  t_h_e_ i_n_t_e_r_n_e_t_ a_d_d_r_e_s_s_
     t_o_m_a_@_s_a_i_l_._l_a_b_s_._t_e_k_._c_o_m_._ B_e_c_a_u_s_e_ o_f_  t_h_e_s_e_ m_o_d_i_f_i_c_a_t_i_o_n_s_,_ t_h_i_s_  v_e_r_s_i_o_n_
     i_s_ c_a_l_l_e_d_ X_L_I_S_P_ 2_._1_b_ t_o_ d_i_s_t_i_n_g_u_s_h_ i_t_ f_r_o_m_ t_h_e_ o_r_i_g_i_n_a_l_._







     XLISP 2.1c                XLISP COMMAND LOOP                    Page 3



     XLISP COMMAND LOOP

     When   XLISP  is  started,  it  first  tries  to  load  the  workspace
     "xlisp.wks", o_r_  a_n_ a_l_t_e_r_n_a_t_i_v_e_  f_i_l_e_ s_p_e_c_i_f_i_e_d_ w_i_t_h_  t_h_e_ "_-_w_f_i_l_e_n_a_m_e_"_
     o_p_t_i_o_n_,_ from the current directory. If that file doesn't exist, o_r_ t_h_e_
     "_-_w_"_ f_l_a_g_ i_s_ i_n_  t_h_e_ c_o_m_m_a_n_d_ l_i_n_e_,_ XLISP builds an  initial workspace,
     empty except for the built-in functions and symbols.

     Then,_  p_r_o_v_i_d_i_n_g_  p_r_o_v_i_d_i_n_g_  n_o_  w_o_r_k_s_p_a_c_e_  f_i_l_e_ w_a_s_  l_o_a_d_e_d_,_    XLISP
     attempts  to load "init.lsp" from the current directory. It then loads
     any files named  as parameters  on the command  line (after  appending
     ".lsp"  to their names). If the "-v" flag is in the command line, then
     the  files are loaded verbosely.  The option "-tfilename"  will open a
     transcript file of the name "filename".

     XLISP then issues the following prompt (_u_n_l_e_s_s_ s_t_a_n_d_a_r_d_ i_n_p_u_t_ h_a_s_ b_e_e_n_
     r_e_d_i_r_e_c_t_e_d_)_:

     >

     This indicates that XLISP is waiting for an expression to be typed.

     When  a  complete  expression  has  been  entered, XLISP  attempts  to
     evaluate  that expression. If  the expression  evaluates successfully,
     XLISP prints the result and then returns for another expression.

     The  following control characters can  be used while  XLISP is waiting
     for input:

          Backspace delete last character
          Del       delete last character
          tab       tabs over (treated as space by XLISP reader)
          ctrl-C    goto top level
          ctrl-G    cleanup and return one level
          ctrl-Z    end of file (returns one level or exits program)
          ctrl-P    proceed (continue)
          ctrl-T    print information (added function by TAA)

     Under MS-DOS the following control characters can be typed while XLISP
     is executing  (providing standard input  has not been  redirected away
     from the console):

          ctrl-B    BREAK -- enter break loop
          ctrl-S    Pause until another key is struck
          ctrl-C    go to top level (if lucky: ctrl-B,ctrl-C is safer)
          ctrl-T    print information

     U_n_d_e_r_ M_S_-_D_O_S_ i_f_ t_h_e_ g_l_o_b_a_l_ v_a_r_i_a_b_l_e_ *_d_o_s_-_i_n_p_u_t_*_ i_s_ s_e_t_ n_o_n_-_N_I_L_,_ D_O_S_ i_s_
     u_s_e_d_ t_o_ r_e_a_d_  e_n_t_i_r_e_ i_n_p_u_t_ l_i_n_e_s_._ O_p_e_r_a_t_i_o_n_ t_h_i_s_ w_a_y_  i_s_ c_o_n_v_e_n_i_e_n_t_ i_f_
     c_e_r_t_a_i_n_ D_O_S_ u_t_i_l_i_t_i_e_s_,_ s_u_c_h_ a_s_ C_E_D_,_ a_r_e_ u_s_e_d_,_ o_r_ i_f_ X_L_I_S_P_ i_s_ r_u_n_ u_n_d_e_r_







     XLISP 2.1c                XLISP COMMAND LOOP                    Page 4


     a_n_ e_d_i_t_o_r_ l_i_k_e_  E_P_S_I_L_O_N_._ I_n_ t_h_i_s_ c_a_s_e_,_ n_o_r_m_a_l_ c_o_m_m_a_n_d_  l_i_n_e_ e_d_i_t_i_n_g_ i_s_
     a_v_a_i_l_a_b_l_e_,_ b_u_t_ t_h_e_ c_o_n_t_r_o_l_  k_e_y_s_ w_i_l_l_ n_o_t_ w_o_r_k_ (_i_n_  p_a_r_t_i_c_u_l_a_r_,_ c_t_r_l_-_C_
     w_i_l_l_ c_a_u_s_e_ t_h_e_ p_r_o_g_r_a_m_  t_o_ e_x_i_t_!_)_._ U_s_e_ t_h_e_ X_L_I_S_P_  f_u_n_c_t_i_o_n_s_ t_o_p_-_l_e_v_e_l_,_
     c_l_e_a_n_-_u_p_,_ a_n_d_ c_o_n_t_i_n_u_e_ i_n_s_t_e_a_d_ o_f_ c_t_r_l_-_C_,_ c_t_r_l_-_G_,_ a_n_d_ c_t_r_l_-_P_._







     XLISP 2.1c                BREAK COMMAND LOOP                    Page 5



     BREAK COMMAND LOOP

     When  XLISP encounters  an error  while evaluating  an  expression, it
     attempts to handle the error in the following way:

     If the symbol  '*breakenable*' is true,  the message corresponding  to
     the  error is  printed. If  the error  is correctable,  the correction
     message is printed.

     If the symbol  '*tracenable*' is  true, a trace  back is printed.  The
     number  of  entries  printed  depends  on  the  value  of  the  symbol
     '*tracelimit*'.  If this  symbol  is set  to  something other  than  a
     number, the entire trace back stack is printed.

     XLISP then enters  a read/eval/print loop to allow the user to examine
     the state  of the interpreter in  the context of the  error. This loop
     differs  from the normal top-level read/eval/print loop in that if the
     user  invokes  the function  'continue',  XLISP will  continue  from a
     correctable error. If the user invokes the function  'clean-up', XLISP
     will abort  the break loop  and return  to the top  level or  the next
     lower numbered break loop.  When in a break  loop, XLISP prefixes  the
     break level to the normal prompt.

     If  the symbol '*breakenable*' is  NIL, XLISP looks  for a surrounding
     errset  function. If  one is  found, XLISP examines  the value  of the
     print flag. If this flag is true, the error message is printed. In any
     case, XLISP causes the errset function call to return NIL.

     If there is  no surrounding  errset function, XLISP  prints the  error
     message and returns to the top level.







     XLISP 2.1c                    DATA TYPES                        Page 6



     DATA TYPES

     There are several different data types available to XLISP programmers.
     Typical  implementation limits  are  shown for  32  bit word  systems.
     Values in square brackets apply to 16 bit MS-DOS implementations.

     All data nodes are  effectively cons cells consisting of  two pointers
     and and one  or two bytes of  identification flags (9 or  10 bytes per
     cell). Node space is managed and garbage collected by XLISP. Array and
     string storage is  either allocated  by the C  runtime or managed  and
     garbaged  collected  by XLISP  (compilation  option).  If  C does  the
     allocation,  memory  fragmentation  can  occur.  Fragmentation  can be
     eliminated by saving the image and restarting XLISP.


         NIL
          I_n_ t_h_e_ o_r_i_g_i_n_a_l_ d_i_s_t_r_i_b_u_t_i_o_n_,_ N_I_L_ w_a_s_ a_ s_p_e_c_i_a_l_ c_a_s_e_ s_y_m_b_o_l_ w_h_i_c_h_
          h_a_d_ n_o_  p_r_o_p_e_r_t_i_e_s_._ A_ c_o_m_p_i_l_a_t_i_o_n_  o_p_t_i_o_n_ w_i_l_l_ c_a_u_s_e_ N_I_L_  t_o_ b_e_ a_
          s_y_m_b_o_l_  (_a_l_t_h_o_u_g_h_ n_o_t_  i_n_  t_h_e_ *_o_b_a_r_r_a_y_*_)_,_  a_l_l_o_w_i_n_g_ s_e_t_t_i_n_g_  i_t_s_
          p_r_o_p_e_r_t_i_e_s_._
         lists
          Either NIL  or a CDR-linked list  of cons cells, terminated  by a
          symbol  (typically NIL).  Circular lists  are allowable,  but can
          cause  problems with  some functions  so they  must be  used with
          care.
         arrays
          The CDR field  of an  array points to  the dynamically  allocated
          data  array, while  the CAR  contains the  integer length  of the
          array. Elements in  the data  array are pointers  to other  cells
          [Size limited to about 16360].
         character strings
          Implemented like arrays, except string array is  byte indexed and
          contains the  actual characters. Note that  unlike the underlying
          C, the null character (value 0) is valid.  [Size limited to about
          65500]
         symbols
          Implemented  as a 4 element  array. The elements  are value cell,
          function  cell, property list, and print name (a character string
          node).  Print names are limited to 100 characters. T_h_e_r_e_ a_r_e_ a_l_s_o_
          f_l_a_g_s_ f_o_r_ c_o_n_s_t_a_n_t_  a_n_d_ s_p_e_c_i_a_l_._ V_a_l_u_e_s_ b_o_u_n_d_  t_o_ s_p_e_c_i_a_l_ s_y_m_b_o_l_s_
          (_d_e_c_l_a_r_e_d_  w_i_t_h_ D_E_F_V_A_R_  o_r_ D_E_F_P_A_R_A_M_E_T_E_R_)_  a_r_e_ a_l_w_a_y_s_  d_y_n_a_m_i_c_a_l_l_y_
          b_o_u_n_d_,_ r_a_t_h_e_r_ t_h_a_n_ b_e_i_n_g_ l_e_x_i_c_a_l_l_y_ b_o_u_n_d_._
         integers
          Small integers (> -129 and <256) are statically allocated and are
          thus always EQ integers of the same value. The CAR  field is used
          to hold the value, which is a 32 bit signed integer.







     XLISP 2.1c                    DATA TYPES                        Page 7


         characters
          All  characters   are  statically  allocated  and   are  thus  EQ
          characters of the same value.  The CAR field is used to  hold the
          value. In XLISP characters are "unsigned" and thus range in value
          from 0 to 255.
         floats
          The CAR  and CDR fields hold  the value, which is  typically a 64
          bit IEEE floating point number.
     _    c_o_m_p_l_e_x_ n_u_m_b_e_r_s_
          P_a_r_t_  o_f_   t_h_e_  m_a_t_h_  e_x_t_e_n_s_i_o_n_  c_o_m_p_i_l_a_t_i_o_n_  o_p_t_i_o_n_._  I_n_t_e_r_n_a_l_l_y_
          i_m_p_l_e_m_e_n_t_e_d_ a_s_ a_n_ a_r_r_a_y_ o_f_ t_h_e_ r_e_a_l_ a_n_d_ i_m_a_g_i_n_a_r_y_ p_a_r_t_._ T_h_e_ p_a_r_t_s_
          c_a_n_ b_e_ e_i_t_h_e_r_  b_o_t_h_ i_n_t_e_g_e_r_s_  o_r_ b_o_t_h_ r_e_a_l_s_._  A_n_y_ f_u_n_c_t_i_o_n_  w_h_i_c_h_
          w_o_u_l_d_ r_e_t_u_r_n_ a_n_ i_n_t_e_g_e_r_ c_o_m_p_l_e_x_ n_u_m_b_e_r_ w_i_t_h_ a_ z_e_r_o_ i_m_a_g_i_n_a_r_y_ p_a_r_t_
          r_e_t_u_r_n_s_ j_u_s_t_ t_h_e_ i_n_t_e_g_e_r_._
         objects
          Implemented  as  an array  of  instance variable  count  plus one
          elements. The  first element  is the  object's  class, while  the
          remaining arguments are the instance variables.
         streams (file)
          The  CAR and CDR fields are  used in a system  dependent way as a
          file  pointer. Files are not always kept open across image saves,
          but the  standard file  streams are rebound  automatically during
          image restores.
         streams (unnamed -- string)
          Implemented as a tconc-style list of characters.
         subrs (built-in functions)
          The CAR field points to the actual code to execute, while the CDR
          field is an internal pointer to the name of the function.
         fsubrs (special forms)
          Same implementation as subrs.
         closures (user defined functions)
          Implemented as an array of 11 elements:
          1.   name symbol or NIL
          2.   'lambda or 'macro
          3.   list of required arguments
          4.   optional arguments as  list of (<arg>  <init> <specified-p>)
               triples.
          5.   &rest argument
          6.   &key arguments as list of (<key> <arg> <init> <specified-p>)
               quadruples.
          7.   &aux arguments as list of (<arg> <init>) pairs.
          8.   function body
          9.   value environment (see page 77 for format)
          10.  function environment
          11.  argument list (unprocessed)
         structures
          Implemented as an array with first element being a pointer to the
          structure  name  string, and  the  remaining  elements being  the
          structure elements.







     XLISP 2.1c                    DATA TYPES                        Page 8


     _    h_a_s_h_-_t_a_b_l_e_s_
          I_m_p_l_e_m_e_n_t_e_d_ a_s_ a_ s_t_r_u_c_t_u_r_e_ o_f_ v_a_r_y_i_n_g_ l_e_n_g_t_h_ w_i_t_h_  n_o_ g_e_n_e_r_a_l_i_z_e_d_
          a_c_c_e_s_s_i_n_g_  f_u_n_c_t_i_o_n_s_,_ b_u_t_  w_i_t_h_ a_  s_p_e_c_i_a_l_ p_r_i_n_t_  f_u_n_c_t_i_o_n_ (_p_r_i_n_t_
          f_u_n_c_t_i_o_n_s_ n_o_t_ a_v_a_i_l_a_b_l_e_ f_o_r_ s_t_a_n_d_a_r_d_ s_t_r_u_c_t_u_r_e_s_)_._
     _    r_a_n_d_o_m_-_s_t_a_t_e_s_
          I_m_p_l_e_m_e_n_t_e_d_ a_s_ a_  s_t_r_u_c_t_u_r_e_ w_i_t_h_  a_ s_i_n_g_l_e_ e_l_e_m_e_n_t_  w_h_i_c_h_ i_s_  t_h_e_
          r_a_n_d_o_m_ s_t_a_t_e_  (_h_e_r_e_ a_ f_i_x_n_u_m_,_ b_u_t_ c_o_u_l_d_  c_h_a_n_g_e_ w_i_t_h_o_u_t_ i_m_p_a_c_t_i_n_g_
          x_l_i_s_p_ p_r_o_g_r_a_m_s_)_._







     XLISP 2.1c                   THE EVALUATOR                      Page 9



     THE EVALUATOR

     The process of evaluation in XLISP:

     Strings, characters, numbers of any type, objects, arrays, structures,
     streams, subrs, fsubrs and closures evaluate to themselves.

     Symbols act as  variables and  are evaluated by  retrieving the  value
     associated with their current binding.

     Lists are  evaluated by examining  the first  element of the  list and
     then taking one of the following actions:

          If  it is  a  symbol, the  functional  binding of  the  symbol is
          retrieved.

          If it is  a lambda expression, a  closure is constructed for  the
          function described by the lambda expression.

          If it is a subr, fsubr or closure, it stands for itself.

          Any other value is an error.

     Then, the value produced by the previous step is examined:

          If it  is a  subr or  closure, the  remaining  list elements  are
          evaluated and the subr  or closure is applied to  these evaluated
          expressions.

          If it  is an fsubr, the  fsubr is called with  the remaining list
          elements as arguments (unevaluated).

          If  it is a macro, the macro  is expanded with the remaining list
          elements as arguments (unevaluated).  The macro expansion is then
          evaluated  in place  of the  original macro  call. I_f_  t_h_e_ s_y_m_b_o_l_
          *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_  i_s_  n_o_t_  N_I_L_,_  t_h_e_n_ t_h_e_  e_x_p_a_n_d_e_d_  m_a_c_r_o_  w_i_l_l_
          (_d_e_s_t_r_u_c_t_i_v_e_l_y_)_ r_e_p_l_a_c_e_ t_h_e_ o_r_i_g_i_n_a_l_ m_a_c_r_o_ e_x_p_r_e_s_s_i_o_n_._ T_h_i_s_ m_e_a_n_s_
          t_h_a_t_ t_h_e_ m_a_c_r_o_ w_i_l_l_ o_n_l_y_ b_e_  e_x_p_a_n_d_e_d_ o_n_c_e_,_ b_u_t_ t_h_e_ o_r_i_g_i_n_a_l_ c_o_d_e_
          w_i_l_l_ b_e_ l_o_s_t_._  T_h_e_ d_i_s_p_l_a_c_e_m_e_n_t_  w_i_l_l_ n_o_t_ t_a_k_e_  p_l_a_c_e_ u_n_l_e_s_s_  t_h_e_
          m_a_c_r_o_ e_x_p_a_n_d_s_ i_n_t_o_  a_ l_i_s_t_._  T_h_e_ s_t_a_n_d_a_r_d_ X_L_I_S_P_  p_r_a_c_t_i_c_e_ i_s_  t_h_e_
          m_a_c_r_o_  w_i_l_l_ b_e_ e_x_p_a_n_d_e_d_  e_a_c_h_ t_i_m_e_  t_h_e_ e_x_p_r_e_s_s_i_o_n_  i_s_ e_v_a_l_u_a_t_e_d_,_
          w_h_i_c_h_ n_e_g_a_t_e_s_ s_o_m_e_ o_f_ t_h_e_ a_d_v_a_n_t_a_g_e_s_ o_f_ u_s_i_n_g_ m_a_c_r_o_s_._







     XLISP 2.1c                  HOOK FUNCTIONS                     Page 10



     HOOK FUNCTIONS

     (_A_P_P_L_Y_H_O_O_K_ i_s_ a_ c_o_m_p_i_l_a_t_i_o_n_ o_p_t_i_o_n_)_

     The  evalhook  and  applyhook  facility are  useful  for  implementing
     debugging programs or  just observing  the operation of  XLISP. It  is
     possible to control evaluation of forms in any context.

     If the  symbol '*evalhook*' is bound to a function closure, then every
     call  of  eval  will  call  this  function.  The  function  takes  two
     arguements, the form to be evaluated and execution environment. During
     the  execution  of this  function,  *evalhook*  (and *applyhook*)  are
     dynamically bound to NIL to prevent undesirable recursion. This "hook"
     function returns the result of the evaluation.

     If  the  symbol  '*applyhook*' is  bound  to  a  function, then  every
     function application within an eval will call this function (note that
     the function apply, and others which do not use eval,  will not invoke
     the apply  hook  function).  The  function takes  two  arguments,  the
     function closure and  the argument list (which is  already evaluated).
     During execution  of this hook function,  *applyhook* (and *evalhook*)
     are  dynamically bound  to NIL  to prevent  undesired recursion.  This
     function is to return the result of the function application.

     Note that the hook functions cannot reset *evalhook* or *applyhook* to
     NIL, because upon exit these values will be reset. An excape mechanism
     is  provided --  execution of  'top-level', or  any error  that causes
     return  to the  top  level, will  unhook  the functions.  Applications
     should  bind   these  values   either  via  'progv',   'evalhook',  or
     'applyhook'.

     The  functions  'evalhook'  and  'applyhook'  allowed  for  controlled
     application of the hook functions. The form supplied as an argument to
     'evalhook', or  the function application given to 'applyhook', are not
     hooked themselves, but  any subsidiary forms and  applications are. In
     addition, by supplying NIL  values for the hook  functions, 'evalhook'
     can be used to execute a  form within a specific environment passed as
     an argument.

     An additional hook function  exists for the garbage collector.  If the
     symbol  '*gc-hook*'  is bound  to a  function,  then this  function is
     called after every garbage collection. The function has two arguments.
     The first is  the total number of nodes, and the  second is the number
     of nodes  free. The return value  is ignored. During the  execution of
     the  function,  *gc-hook*  is  dynamically  bound to  NIL  to  prevent
     undesirable recursion.







     XLISP 2.1c                LEXICAL CONVENTIONS                  Page 11



     LEXICAL CONVENTIONS

     The  following  conventions  must  be  followed  when  entering  XLISP
     programs:

     Comments  in XLISP code begin with a semi-colon character and continue
     to the end of the line.

     Except  when  escape sequences  are used,  symbol  names in  XLISP can
     consist  of any sequence of non-blank  printable characters except the
     terminating macro characters:

          ( ) ' ` , " ;

     and the escape characters:

          \ |

     In addition, the first character may not be '#' (non-terminating macro
     character), nor may the  symbol have identical syntax with  an integer
     or floating point  literal. Uppercase and lowercase characters are not
     distinguished within symbol names. All lowercase characters are mapped
     to uppercase on input.

     Any  printing character, including whitespace, may be part of a symbol
     name  when  escape characters  are  used.  The backslash  escapes  the
     following  character,  while multiple  characters  can  be escaped  by
     placing them between vertical bars. At all times the backslash must be
     used to escape either escape characters.

     For  semantic reasons, certain  chararacter sequences should/can never
     be used as symbols in XLISP. A single period is  used to denote dotted
     lists.  The symbol NIL represents an empty list. Symbols starting with
     a  colon are keywords,   and will always  evaluate to themselves. Thus
     they  should not  be used  as regular  symbols. The  symbol T  is also
     reserved for use as the truth value.

     Integer  literals consist of a sequence of digits optionally beginning
     with a sign ('+' or '-'). The range of values an integer can represent
     is limited by the size of a C 'long' on the machine on which  XLISP is
     running.

     Floating  point literals  consist of  a sequence of  digits optionally
     beginning with a  sign ('+' or '-')  and including one  or both of  an
     embedded decimal point or  a trailing exponent. The  optional exponent
     is denoted  by an 'E'  followed by  an optional sign  and one  or more
     digits. The range of  values a floating point number  can represent is
     limited by the size of a C 'double' on most machines on which XLISP is
     running.







     XLISP 2.1c                LEXICAL CONVENTIONS                  Page 12


     Integer  and  floating  point  literals cannot  have  embedded  escape
     characters. If they do, they are  treated as symbols. Thus '12\3' is a
     symbol even though it would appear to be identical to '123'.

     C_o_m_p_l_e_x_ l_i_t_e_r_a_l_s_ a_r_e_  o_f_ t_h_e_ f_o_r_m_a_t_ #_C_(_r_ i_)_,_ w_h_e_r_e_ r_  i_s_ t_h_e_ r_e_a_l_ p_a_r_t_
     a_n_d_ i_  i_s_ t_h_e_ i_m_a_g_i_n_a_r_y_  p_a_r_t_._ A_  r_e_a_d_-_m_a_c_r_o_ i_s_ u_s_e_d_  t_o_ r_e_a_d_  c_o_m_p_l_e_x_
     l_i_t_e_r_a_l_s_._ T_h_e_s_e_ c_a_n_ b_e_ a_n_y_ v_a_l_i_d_ i_n_t_e_g_e_r_ o_r_ f_l_o_a_t_i_n_g_ p_o_i_n_t_ l_i_t_e_r_a_l_._

     Character literals are handled via the #\ read-macro construct:

          #\<char>       == the ASCII code of the printing character
          #\newline      == ASCII linefeed character
          #\space        == ASCII space character
          #\rubout       == ASCII rubout (DEL)
          #\C-<char>     == ASCII control character
          #\M-<char>     == ASCII character with msb set (Meta character)
          #\M-C-<char>   == ASCII control character with msb set


     Literal  strings  are sequences  of  characters  surrounded by  double
     quotes  (the " read-macro). Within quoted strings the '\' character is
     used to allow non-printable characters to be included. The codes
     recognized are:

          \\        means the character '\'
          \n        means newline
          \t        means tab
          \r        means return
          \f        means form feed
          \nnn      means the character whose octal code is nnn







     XLISP 2.1c                    READTABLES                       Page 13



     READTABLES

     The behaviour of the reader is controlled by a data structure called a
     "readtable".  The reader  uses the  symbol *readtable*  to locate  the
     current  readtable. This  table controls  the interpretation  of input
     characters  -- if it is  changed then the  section LEXICAL CONVENTIONS
     may not  apply. The readtable  is an array  with 256 entries,  one for
     each of the extended ASCII character codes. Each entry contains one of
     the  following values, with the initial entries assigned to the values
     indicated:

          :white-space        A  whitespace character  -  tab, cr,  lf, ff,
                              space
          (:tmacro . fun)     terminating readmacro - ( ) " , ; ' `
          (:nmacro . fun)     non-terminating readmacro - #
          :sescape            Single escape character - \
          :mescape            Multiple escape character - |
          :constituent        Indicating a symbol constituent (all printing
                              characters not listed above)
          NIL                 Indicating  an invalid  character (everything
                              else)

     In the case of :TMACRO and :NMACRO, the "fun" component is a function.
     This  can  either  be  a  built-in  readmacro  function  or  a  lambda
     expression.  The function takes two parameters. The first is the input
     stream and the second is the  character that caused the invocation  of
     the readmacro. The  readmacro function should  return NIL to  indicate
     that the character should be treated  as white space or a value consed
     with  NIL to  indicate  that the  readmacro  should be  treated as  an
     occurance of the  specified value.  Of course, the  readmacro code  is
     free to read additional characters from the input stream. A :nmacro is
     a symbol constituent except as the first character of a symbol.

     As an example, the following read macro allows  the square brackets to
     be used as a more visibly appealing alternative to the SEND function:







     XLISP 2.1c                    READTABLES                       Page 14


     (setf (aref *readtable* (char-int #\[)) ; #\[ table entry
           (cons :tmacro
                 (lambda (f c &aux ex) ; second arg is not used
                         (do ()
                             ((eq (peek-char t f) #\]))
                             (setf ex (append ex (list (read f)))))
                         (read-char f) ; toss the trailing #\]
                         (cons (cons 'send ex) NIL))))

     (setf (aref *readtable* (char-int #\]))
           (cons :tmacro
                 (lambda (f c)
                         (error "misplaced right bracket"))))


     XLISP defines several useful read macros:

          '<expr>             == (quote <expr>)
          `<expr>             == (backquote <expr>)
          ,<expr>             == (comma <expr>)
          ,@<expr>            == (comma-at <expr>)
          #'<expr>            == (function <expr>)
          #(<expr>...)        == an array of the specified expressions
          #S(<structtype> [<slotname> <value>]...)
                              ==  structure of  specified type  and initial
                              values
          #_._<_e_x_p_r_>_            =_=_ r_e_s_u_l_t_ o_f_ e_v_a_l_u_a_t_i_n_g_ <_e_x_p_r_>_
          #x<hdigits>         == a hexadecimal number (0-9,A-F)
          #o<odigits>         == an octal number (0-7)
          #b<bdigits>         == a binary number (0-1)
          #|  |#              == a comment
          #:<symbol>          == an uninterned symbol
          #_C_(_r_ i_)_             =_=_ a_ c_o_m_p_l_e_x_ n_u_m_b_e_r_







     XLISP 2.1c                   LAMBDA LISTS                      Page 15



     LAMBDA LISTS

     There are several forms in XLISP that require that a  "lambda list" be
     specified. A lambda  list is a definition of the arguments accepted by
     a function. There are four different types of arguments.

     The  lambda list  starts with  required arguments.  Required arguments
     must be specified in every call to the function.

     The  required  arguments  are  followed by  the  &optional  arguments.
     Optional   arguments  may  be  provided  or  omitted  in  a  call.  An
     initialization expression may  be specified to provide a default value
     for  an  &optional argument  if  it  is omitted  from  a  call. If  no
     initialization   expression  is  specified,  an  omitted  argument  is
     initialized  to NIL.  It is  also possible  to provide  the name  of a
     'supplied-p' variable that can be used to determine if a call provided
     a value for the argument or if the initialization expression was used.
     If specified,  the supplied-p variable will  be bound to T  if a value
     was specified in the call and NIL if the default value was used.

     The  &optional arguments are followed by the &rest argument. The &rest
     argument gets  bound to the remainder  of the argument list  after the
     required and &optional arguments have been removed.

     The &rest argument is  followed by the &key arguments.  When a keyword
     argument is  passed to a  function, a  pair of values  appears in  the
     argument list. The  first expression in the pair should  evaluate to a
     keyword symbol  (a symbol that  begins with a  ':'). The value  of the
     second expression is the value of the keyword argument. Like &optional
     arguments,  &key  arguments  can have  initialization  expressions and
     supplied-p  variables. In  addition,  it is  possible  to specify  the
     keyword to be used in a function call. If no keyword is specified, the
     keyword  obtained by  adding a  ':' to  the beginning  of the  keyword
     argument  symbol  is used.  In other  words,  if the  keyword argument
     symbol is  'foo', the  keyword will  be ':foo'.  T_h_e_ &_a_l_l_o_w_-_o_t_h_e_r_-_k_e_y_s_
     m_a_r_k_e_r_  i_s_ i_g_n_o_r_e_d_ i_n_ t_h_e_ o_r_i_g_i_n_a_l_ d_i_s_t_r_i_b_u_t_i_o_n_ (_o_t_h_e_r_ k_e_y_s_ a_r_e_ a_l_w_a_y_s_
     a_l_l_o_w_e_d_)_ b_u_t_  e_n_a_b_l_e_d_ v_i_a_ a_  c_o_m_p_i_l_a_t_i_o_n_ o_p_t_i_o_n_._  W_h_e_n_ e_n_a_b_l_e_d_,_  e_x_t_r_a_
     k_e_y_w_o_r_d_s_ w_i_l_l_ s_i_g_n_a_l_ a_n_ e_r_r_o_r_ u_n_l_e_s_s_ &_a_l_l_o_w_-_o_t_h_e_r_-_k_e_y_s_ i_s_ p_r_e_s_e_n_t_._

     The &key arguments are followed by the &aux variables. These are local
     variables that are bound  during the evaluation of the  function body.
     It  is  possible  to  have  initialization  expressions  for  the &aux
     variables.







     XLISP 2.1c                   LAMBDA LISTS                      Page 16


     Here is the complete syntax for lambda lists:

          (<rarg>...
           [&optional [<oarg> | (<oarg> [<init> [<svar>]])]...]
           [&rest <rarg>]
           [&key
            [<karg> |  ([<karg> |  (<key> <karg>)] [<init>  [<svar>]])] ...
          [&allow-other-keys]]
           [&aux [<aux> | (<aux> [<init>])]...])

         where:

          <rarg>    is a required argument symbol
          <oarg>    is an &optional argument symbol
          <rarg>    is the &rest argument symbol
          <karg>    is a &key argument symbol
          <key>     is a keyword symbol (starts with ':')
          <aux>     is an auxiliary variable symbol
          <init>    is an initialization expression
          <svar>    is a supplied-p variable symbol







     XLISP 2.1c                      OBJECTS                        Page 17



     OBJECTS

     Definitions:

         selector - a symbol used to select an appropriate method
         message - a selector and a list of actual arguments
         method - the code that implements a message

     Since  XLISP was created to  provide a simple  basis for experimenting
     with  object-oriented programming,  one  of the  primitive data  types
     included is 'object'. In XLISP, an object consists of a data structure
     containing a  pointer  to the  object's  class  as well  as  an  array
     containing the values of the object's instance variables.

     Officially,  there is  no way  to see  inside an  object (look  at the
     values of its instance variables). The only way to communicate with an
     object is by sending it a message.

     You can  send a message to  an object using the  'send' function. This
     function  takes the object as its first argument, the message selector
     as  its  second argument  (which must  be  a symbol)  and  the message
     arguments as its remaining arguments.

     The 'send' function determines  the class of the receiving  object and
     attempts to find a method corresponding to the message selector in the
     set of messages defined for that class. If the message is not found in
     the  object's  class  and the  class  has  a  super-class, the  search
     continues by looking at the messages defined for the super-class. This
     process continues from one super-class to the next until  a method for
     the message is found. If no method is found, an error occurs.

     To perform  a  method lookup  starting  with the  method's  superclass
     rather than the  object's class, use  the function 'send-super'.  This
     allows a subclass to invoke a standard method in its parent class even
     though it overrides that method with its own specialized version.

     When a method  is found, the evaluator  binds the receiving  object to
     the symbol  'self'  and  evaluates  the  method  using  the  remaining
     elements  of the  original  list as  arguments  to the  method.  These
     arguments  are  always  evaluated  prior   to  being  bound  to  their
     corresponding formal  arguments. The  result of evaluating  the method
     becomes the result of the expression.

     Two  objects, both  classes, are  predefined: Object  and Class.  Both
     Object and  Class  are of  class  Class. The  superclass of  Class  is
     Object, while  Object has no superclass. Typical  use is to create new
     classes (by sending  :new to Class) to represent  application objects.
     Objects of these classes,  created by sending :new to  the appropriate
     new class,  are subclasses of Object.  The Object method :show  can be
     used to view the contents of any object.







     XLISP 2.1c                      OBJECTS                        Page 18



     THE 'Object' CLASS

     Object  THE TOP OF THE CLASS HEIRARCHY

     Messages:

          :show                         SHOW AN OBJECT'S INSTANCE VARIABLES
                    returns   the object

          :class                              RETURN THE CLASS OF AN OBJECT
                    returns   the class of the object

          :_p_r_i_n_1_ [_<_s_t_r_e_a_m_>_]_                                P_R_I_N_T_ T_H_E_ O_B_J_E_C_T_
                    <_s_t_r_e_a_m_>_  d_e_f_a_u_l_t_,_  o_r_ N_I_L_,_ i_s_  *_s_t_a_n_d_a_r_d_-_o_u_t_p_u_t_*_,_ T_ i_s_
                              *_t_e_r_m_i_n_a_l_-_i_o_*_
                    r_e_t_u_r_n_s_   t_h_e_ o_b_j_e_c_t_

          :isnew                  THE DEFAULT OBJECT INITIALIZATION ROUTINE
                    returns   the object

          :_s_u_p_e_r_c_l_a_s_s_                      G_E_T_ T_H_E_ S_U_P_E_R_C_L_A_S_S_ O_F_ T_H_E_ O_B_J_E_C_T_
                    r_e_t_u_r_n_s_   N_I_L_
                    (_D_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_,_ s_e_e_ :_s_u_p_e_r_c_l_a_s_s_ b_e_l_o_w_)_

          :_i_s_m_e_m_b_e_r_o_f_ <_c_l_a_s_s_>_                              C_L_A_S_S_ M_E_M_B_E_R_S_H_I_P_
                    <_c_l_a_s_s_>_   c_l_a_s_s_ n_a_m_e_
                    r_e_t_u_r_n_s_   T_ i_f_ o_b_j_e_c_t_ m_e_m_b_e_r_ o_f_ c_l_a_s_s_,_ e_l_s_e_ N_I_L_
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

          :_i_s_k_i_n_d_o_f_ <_c_l_a_s_s_>_                                C_L_A_S_S_ M_E_M_B_E_R_S_H_I_P_
                    <_c_l_a_s_s_>_   c_l_a_s_s_ n_a_m_e_
                    r_e_t_u_r_n_s_   T_ i_f_  o_b_j_e_c_t_ m_e_m_b_e_r_  o_f_ c_l_a_s_s_ o_r_  s_u_b_c_l_a_s_s_ o_f_
                              c_l_a_s_s_,_ e_l_s_e_ N_I_L_
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

          :_r_e_s_p_o_n_d_s_t_o_ <_s_e_l_>_                              S_E_L_E_C_T_O_R_ K_N_O_W_L_E_D_G_E_
                    <_s_e_l_>_     m_e_s_s_a_g_e_ s_e_l_e_c_t_o_r_
                    r_e_t_u_r_n_s_   T_ i_f_  o_b_j_e_c_t_  r_e_s_p_o_n_d_s_ t_o_  m_e_s_s_a_g_e_  s_e_l_e_c_t_o_r_,_
                              e_l_s_e_ N_I_L_._
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

          :_s_t_o_r_e_o_n_                                      R_E_A_D_ R_E_P_R_E_S_E_N_T_A_T_I_O_N_
                    r_e_t_u_r_n_s_   a_ l_i_s_t_,_ t_h_a_t_ w_h_e_n_ e_x_e_c_u_t_e_d_ w_i_l_l_ c_r_e_a_t_e_ a_ c_o_p_y_
                              o_f_  t_h_e_  o_b_j_e_c_t_._  O_n_l_y_ w_o_r_k_s_  f_o_r_  m_e_m_b_e_r_s_ o_f_
                              c_l_a_s_s_e_s_ c_r_e_a_t_e_d_ w_i_t_h_ d_e_f_c_l_a_s_s_._
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_







     XLISP 2.1c                      OBJECTS                        Page 19



     THE 'Class' CLASS

     Class   THE CLASS OF ALL OBJECT CLASSES (including itself)

     Messages:

          :new                             CREATE A NEW INSTANCE OF A CLASS
                    returns   the new class object

          :isnew <ivars> [<cvars> [<super>]]         INITIALIZE A NEW CLASS
                    <ivars>   the list of instance variable symbol
                    <cvars>   the list of class variable symbols
                    <super>   the superclass (default is Object)
                    returns   the new class object

          :answer <msg> <fargs> <code>             ADD A MESSAGE TO A CLASS
                    <msg>     the message symbol
                    <fargs>   the formal argument list (lambda list)
                    <code>    a list of executable expressions
                    returns   the object

          :_s_u_p_e_r_c_l_a_s_s_                      G_E_T_ T_H_E_ S_U_P_E_R_C_L_A_S_S_ O_F_ T_H_E_ O_B_J_E_C_T_
                    r_e_t_u_r_n_s_   t_h_e_ s_u_p_e_r_c_l_a_s_s_ (_o_f_ t_h_e_ c_l_a_s_s_)_
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

          :_m_e_s_s_a_g_e_s_                   G_E_T_ T_H_E_ L_I_S_T_ O_F_ M_E_S_S_A_G_E_S_ O_F_ T_H_E_ C_L_A_S_S_
                    r_e_t_u_r_n_s_   a_s_s_o_c_i_a_t_i_o_n_  l_i_s_t_  o_f_  m_e_s_s_a_g_e_ s_e_l_e_c_t_o_r_s_  a_n_d_
                              c_l_o_s_u_r_e_s_ f_o_r_ m_e_s_s_a_g_e_s_._
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

          :_s_t_o_r_e_o_n_                                      R_E_A_D_ R_E_P_R_E_S_E_N_T_A_T_I_O_N_
                    r_e_t_u_r_n_s_   a_ l_i_s_t_,_ t_h_a_t_ w_h_e_n_ e_x_e_c_u_t_e_d_ w_i_l_l_ r_e_-_c_r_e_a_t_e_ t_h_e_
                              c_l_a_s_s_ a_n_d_ i_t_s_ m_e_t_h_o_d_s_._
                    (_d_e_f_i_n_e_d_ i_n_ c_l_a_s_s_e_s_._l_s_p_)_

     When  a new  instance of  a class  is created  by sending  the message
     ':new' to an existing class, the message ':isnew' followed by whatever
     parameters were  passed to  the ':new'  message is  sent to  the newly
     created  object. Therefore,  when a  new class  is created  by sending
     ':new'  to class  'Class'  the  message  ':isnew'  is  sent  to  Class
     automatically.  To create  a new  class, a  function of  the following
     format is used:
       (setq <newclassname> (send Class :new <ivars> [<cvars> [<super>]]))

     When  a new class  is created, an optional  parameter may be specified
     indicating  the  superclass of  the new  class.  If this  parameter is
     omitted, the  new  class  will be  a  subclass of  'Object'.  A  class
     inherits all instance variables, class variables, and methods from its
     super-class.







     XLISP 2.1c                      OBJECTS                        Page 20


     INSTANCE VARIABLES OF CLASS 'CLASS':

          MESSAGES  - An  association list  of  message names  and closures
                    implementing the messages.

          IVARS - List of names of instance variables.

          CVARS - List of names of class variables.

          CVAL - Array of class variable values.

          SUPERCLASS - The superclass of this class or NIL if no superclass
                    (only for class OBJECT).

          IVARCNT - instance variables in this class (length of IVARS)

          IVARTOTAL  - total  instance  variables for  this  class and  all
                    superclasses of this class.

          P_N_A_M_E_ -_ p_r_i_n_t_n_a_m_e_ s_t_r_i_n_g_ f_o_r_ t_h_i_s_ c_l_a_s_s_._







     XLISP 2.1c                      SYMBOLS                        Page 21



     SYMBOLS

     All  values  are initially  NIL  unless otherwise  specified.  A_l_l_ a_r_e_
     s_p_e_c_i_a_l_ v_a_r_i_a_b_l_e_s_ u_n_l_e_s_s_ i_n_d_i_c_a_t_e_d_ t_o_ b_e_ c_o_n_s_t_a_n_t_s_._

         NIL - the empty list and the boolean value for  "false" The value
          of NIL  is NIL, and  cannot be changed  (it is a  constant). (car
          NIL) and (cdr NIL) are also NIL.
         t - boolean value "true" is constant with value t.
         self - within a method context, the current object (see page 17),
          otherwise initially unbound.
         object - constant, value is the class 'Object.'
         class - constant, value is the class 'Class'.
     _    i_n_t_e_r_n_a_l_-_t_i_m_e_-_u_n_i_t_s_-_p_e_r_-_s_e_c_o_n_d_  -_  i_n_t_e_g_e_r_  c_o_n_s_t_a_n_t_   t_o_  d_i_v_i_d_e_
          r_e_t_u_r_n_e_d_ t_i_m_e_s_ b_y_ t_o_ g_e_t_ t_i_m_e_ i_n_ s_e_c_o_n_d_s_._
     _    p_i_  -_ f_l_o_a_t_i_n_g_  p_o_i_n_t_ a_p_r_o_x_i_m_a_t_i_o_n_  o_f_ p_i_ (_c_o_n_s_t_a_n_t_  d_e_f_i_n_e_d_ w_h_e_n_
          m_a_t_h_ e_x_t_e_n_s_i_o_n_ i_s_ c_o_m_p_i_l_e_d_)_._
         *obarray*  -  the  object  hash  table.  Length  of  array  is  a
          compilation option.  Objects are  hashed using the  hash function
          and are placed on a list in the appropriate array slot.
     _    *_t_e_r_m_i_n_a_l_-_i_o_*_  -_ s_t_r_e_a_m_  b_o_u_n_d_ t_o_  k_e_y_b_o_a_r_d_ a_n_d_  d_i_s_p_l_a_y_._  D_o_ n_o_t_
          a_l_t_e_r_._
         *standard-input* - the standard input stream, initially stdin. I_f_
          s_t_d_i_n_ i_s_  n_o_t_ r_e_d_i_r_e_c_t_e_d_ o_n_ t_h_e_ c_o_m_m_a_n_d_  l_i_n_e_,_ t_h_e_n_ *_t_e_r_m_i_n_a_l_-_i_o_*_
          i_s_ u_s_e_d_ s_o_ t_h_a_t_ a_l_l_ i_n_t_e_r_a_c_t_i_v_e_ i_/_o_ u_s_e_s_ t_h_e_ s_a_m_e_ s_t_r_e_a_m_._
         *standard-output* - the standard output stream, initially stdout.
          I_f_  s_t_d_o_u_t_  i_s_   n_o_t_  r_e_d_i_r_e_c_t_e_d_   o_n_  t_h_e_   c_o_m_m_a_n_d_  l_i_n_e_   t_h_e_n_
          *_t_e_r_m_i_n_a_l_-_i_o_*_ i_s_ u_s_e_d_ s_o_  t_h_a_t_ a_l_l_ i_n_t_e_r_a_c_t_i_v_e_ i_/_o_ u_s_e_s_  t_h_e_ s_a_m_e_
          s_t_r_e_a_m_._
         *error-output*  -  the error  output  stream (used  by  all error
          messages), i_n_i_t_i_a_l_l_y_ s_a_m_e_ a_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_._
         *trace-output* -  the  trace output  stream  (used by  the  trace
          function), i_n_i_t_i_a_l_l_y_ s_a_m_e_ a_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_.
         *debug-io*  - the  break  loop  i/o  stream,  i_n_i_t_i_a_l_l_y_  s_a_m_e_  a_s_
          *_t_e_r_m_i_n_a_l_-_i_o_*_._ S_y_s_t_e_m_ m_e_s_s_a_g_e_s_   (_o_t_h_e_r_ t_h_a_n_ e_r_r_o_r_ m_e_s_s_a_g_e_s_)_ a_l_s_o_
          p_r_i_n_t_ o_u_t_ o_n_ t_h_i_s_ s_t_r_e_a_m_.
         *breakenable* -  flag controlling  entering break loop  on errors
          (see page 5)
         *tracelist* - list  of names  of functions  to trace,  as set  by
          trace function.
         *tracenable* - enable trace back printout on errors (see page 5).
         *tracelimit* - number  of levels of  trace back information  (see
          page 5).
         *evalhook* - user substitute for the evaluator function (see page
          10, and evalhook and applyhook functions).
         *applyhook* - user substitute  for function application (see page
          10, and evalhook and applyhook functions).
         *readtable* - the current readtable (see page 13).







     XLISP 2.1c                      SYMBOLS                        Page 22


         *unbound* - indicator for unbound symbols. A constant. Do not use
          this symbol since accessing  any variable to which this  has been
          bound will cause an unbound symbol error message.
         *gc-flag* - controls the printing of gc messages. When non-NIL, a
          message is printed after each garbage collection giving the total
          number of nodes and the number of nodes free.
         *gc-hook* -  function to call after garbage  collection (see page
          10).
         *integer-format* - format  for printing integers (initially  "%d"
          or "%ld" depending on implementation)
         *float-format* - format for printing floats (default is typically
          "%g")
         *print-case*  - symbol  output  case when  printing using  prin1.
          Unless excaped, all characters in symbol names are upcased by the
          reader. Default value :upcase prints symbols as  they are stored,
          while the  value :downcase will cause uppercase  characters to be
          printed in  lowercase. Lowercase characters in  symbol names will
          always be escaped  when printed  with prin1. Note  that in  XLISP
          symbols printed with  princ do not  honor *print-case* but  print
          exactly as they are stored (equivalent to :upcase).
     _    *_p_r_i_n_t_-_l_e_v_e_l_*_ -_ W_h_e_n_ b_o_u_n_d_  t_o_ a_ n_u_m_b_e_r_,_ l_i_s_t_ l_e_v_e_l_s_  b_e_y_o_n_d_ t_h_i_s_
          v_a_l_u_e_  a_r_e_ p_r_i_n_t_e_d_ a_s_ '_#_'_._  U_s_e_d_ b_y_ a_l_l_  p_r_i_n_t_i_n_g_ f_u_n_c_t_i_o_n_s_._ G_o_o_d_
          p_r_e_c_a_u_t_i_o_n_ t_o_ a_v_o_i_d_ g_e_t_t_i_n_g_ c_a_u_g_h_t_ i_n_ c_i_r_c_u_l_a_r_ l_i_s_t_s_._
     _    *_p_r_i_n_t_-_l_e_n_g_t_h_*_ -_ W_h_e_n_ b_o_u_n_d_  t_o_ a_ n_u_m_b_e_r_,_ l_i_s_t_s_ l_o_n_g_e_r_  t_h_a_n_ t_h_i_s_
          v_a_l_u_e_  a_r_e_ p_r_i_n_t_e_d_ a_s_ '_._._._'_._ U_s_e_d_ b_y_ a_l_l_ p_r_i_n_t_i_n_g_ f_u_n_c_t_i_o_n_s_._ G_o_o_d_
          p_r_e_c_a_u_t_i_o_n_ t_o_ a_v_o_i_d_ g_e_t_t_i_n_g_ c_a_u_g_h_t_ i_n_ c_i_r_c_u_l_a_r_ l_i_s_t_s_._
     _    *_d_o_s_-_i_n_p_u_t_*_ -_ W_h_e_n_ n_o_t_ N_I_L_,_ u_s_e_s_ d_o_s_ l_i_n_e_ i_n_p_u_t_ f_u_n_c_t_i_o_n_ f_o_r_ r_e_a_d_
          (_s_e_e_ p_a_g_e_ 3_)_._
     _    *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_ -_  W_h_e_n_ n_o_t_ N_I_L_,_  m_a_c_r_o_s_ a_r_e_ r_e_p_l_a_c_e_d_  b_y_ t_h_e_i_r_
          e_x_p_a_n_s_i_o_n_s_ w_h_e_n_ e_x_e_c_t_u_t_e_d_ (_s_e_e_ p_a_g_e_ 9_)_._
     _    *_r_a_n_d_o_m_-_s_t_a_t_e_*_  -_ t_h_e_  d_e_f_a_u_l_t_  r_a_n_d_o_m_-_s_t_a_t_e_ u_s_e_d_  b_y_ t_h_e_  r_a_n_d_o_m_
          f_u_n_c_t_i_o_n_._

     There are several symbols maintained by the read/eval/print loop.  The
     symbols '+', '++', and '+++' are  bound to the most recent three input
     expressions. The symbols  '*', '**' and  '***' are bound  to the  most
     recent  three results.  The  symbol '-'  is  bound to  the  expression
     currently being evaluated.  It becomes the value of '+'  at the end of
     the evaluation.

     Since the original XLISP  does not have "special variables"  the progv
     function must  be used  to bind global  symbols to  new values  within
     applications  (this  is the  only  application-accessible  way to  get
     dynamic binding). T_h_e_ m_o_d_i_f_i_e_d_ X_L_I_S_P_ h_a_s_ s_p_e_c_i_a_l_ v_a_r_i_a_b_l_e_s_._







     XLISP 2.1c               EVALUATION FUNCTIONS                  Page 23



     EVALUATION FUNCTIONS

     (eval <expr>)                             EVALUATE AN XLISP EXPRESSION
          <expr>    the expression to be evaluated
          returns   the result of evaluating the expression

     (apply <fun> <arg>...<args>)   APPLY A FUNCTION TO A LIST OF ARGUMENTS
          <fun>     the function to apply (or  function symbol). May not be
                    macro or fsubr.
          <_a_r_g_>_     i_n_i_t_i_a_l_ a_r_g_u_m_e_n_t_s_,_ w_h_i_c_h_ a_r_e_ C_O_N_S_e_d_ t_o_._._._
          <args>    the argument list
          returns   the result of applying the function to the arguments

     (funcall <fun> <arg>...)                CALL A FUNCTION WITH ARGUMENTS
          <fun>     the function  to call (or function symbol).  May not be
                    macro or fsubr.
          <arg>     arguments to pass to the function
          returns   the result of calling the function with the arguments

     (quote <expr>)                        RETURN AN EXPRESSION UNEVALUATED
          fsubr
          <expr>    the expression to be quoted (quoted)
          returns   <expr> unevaluated

     (function <expr>)                    GET THE FUNCTIONAL INTERPRETATION
          fsubr
          <expr>    the symbol or lambda expression (quoted)
          returns   the functional interpretation

     (_i_d_e_n_t_i_t_y_ <_e_x_p_r_>_)_                                R_E_T_U_R_N_ T_H_E_ E_X_P_R_E_S_S_I_O_N_
          N_e_w_ f_u_n_c_t_i_o_n_._ I_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_
          r_e_t_u_r_n_s_   t_h_e_ e_x_p_r_e_s_s_i_o_n_

     (backquote <expr>)                                  FILL IN A TEMPLATE
          fsubr
          <expr>    the template (quoted)
          returns   a  copy  of  the   template  with  comma  and  comma-at
                    expressions expanded.

     (comma <expr>)                                        COMMA EXPRESSION
          (Never executed)  As the  object  of a  backquote expansion,  the
          expression is  evaluated and becomes  an object in  the enclosing
          list.

     (comma-at <expr>)                                  COMMA-AT EXPRESSION
          (Never  executed) As  the object  of  a backquote  expansion, the
          expression is evaluated (and must evaluate to a list) and is then
          spliced into the enclosing list.







     XLISP 2.1c               EVALUATION FUNCTIONS                  Page 24


     (lambda <args> <expr>...)                      MAKE A FUNCTION CLOSURE
          fsubr
          <args>    formal argument list (lambda list) (quoted)
          <expr>    expressions of the function body (quoted)
          returns   the function closure

     (get-lambda-expression <closure>)            GET THE LAMBDA EXPRESSION
          <closure> the closure
          returns   the original lambda expression

     (macroexpand <form>)                    RECURSIVELY EXPAND MACRO CALLS
          <form>    the form to expand
          returns   the macro expansion

     (macroexpand-1 <form>)                             EXPAND A MACRO CALL
          <form>    the macro call form
          returns   the macro expansion







     XLISP 2.1c                 SYMBOL FUNCTIONS                    Page 25



     SYMBOL FUNCTIONS

     (set <sym> <expr>)                    SET THE GLOBAL VALUE OF A SYMBOL
          <sym>     the symbol being set
          <expr>    the new value
          returns   the new value

     (setq [<sym> <expr>]...)                     SET THE VALUE OF A SYMBOL
          fsubr
          <sym>     the symbol being set (quoted)
          <expr>    the new value
          returns   the new value

     (psetq [<sym> <expr>]...)                     PARALLEL VERSION OF SETQ
          fsubr. All expressions are evaluated  before any assignments
          are made.
          <sym>     the symbol being set (quoted)
          <expr>    the new value
          returns   the new value

     (setf [<place> <expr>]...)                    SET THE VALUE OF A FIELD
          fsubr
          <place> the field  specifier (if a macro it is expanded, then the
                  form arguments are evaluated):
                  <sym>                 set value of a symbol
                  (car <expr>)          set car of a cons node
                  (cdr <expr>)          set cdr of a cons node
                  (nth <n> <expr>)      set nth car of a list
                  (aref <expr> <n>)     set  nth  element  of  an  array o_r_
                                        s_t_r_i_n_g_
                  (_e_l_t_ <_e_x_p_r_>_ <_n_>_)_      s_e_t_ n_t_h_ e_l_e_m_e_n_t_ o_f_ a_ s_e_q_u_e_n_c_e_
                  (get <sym> <prop>)    set value of a property
                  (symbol-value <sym>)  set global value of a symbol
                  (symbol-function <sym>)         set functional value of a
                                                  symbol
                  (symbol-plist <sym>)  set property list of a symbol
                  (_g_e_t_h_a_s_h_ <_k_e_y_>_ <_t_b_l_>_ <_d_e_f_>_)_     a_d_d_ o_r_ r_e_p_l_a_c_e_ h_a_s_h_ t_a_b_l_e_
                  e_n_t_r_y_._ <_d_e_f_>_ i_s_ i_g_n_o_r_e_d_
                  (_s_e_n_d_ <_o_b_j_>_ :_<_i_v_a_r_>_)_  (_W_h_e_n_   c_l_a_s_s_e_s_._l_s_p_   u_s_e_d_)_,_    s_e_t_
                                        i_n_s_t_a_n_c_e_ v_a_r_i_a_b_l_e_ o_f_ o_b_j_e_c_t_._
                  (<sym>-<element> <struct>)      set   the    element   of
                                                  structure   struct,  type
                                                  sym.
                  (<fieldsym> <args>)   the  function  stored  in  property
                                        *setf*  in   symbol  <fieldsym>  is
                                        applied to (<args> <expr>)
          <value> the new value
          returns the new value







     XLISP 2.1c                 SYMBOL FUNCTIONS                    Page 26


     (_d_e_f_s_e_t_f_ <_s_y_m_>_ <_f_c_n_>_)_                    D_E_F_I_N_E_ A_ S_E_T_F_ F_I_E_L_D_ S_P_E_C_I_F_I_E_R_
     (_d_e_f_s_e_t_f_ <_s_y_m_>_ <_f_a_r_g_s_>_ (_<_v_a_l_u_e_>_)_ <_e_x_p_r_>_._._._)_
          D_e_f_i_n_e_d_  a_s_   m_a_c_r_o_  i_n_   c_o_m_m_o_n_._l_s_p_._  C_o_n_v_e_n_i_e_n_t_,_  C_o_m_m_o_n_   L_i_s_p_
          c_o_m_p_a_t_i_b_l_e_  a_l_t_e_r_n_a_t_i_v_e_  t_o_  s_e_t_t_i_n_g_  *_s_e_t_f_*_  p_r_o_p_e_r_t_y_  d_i_r_e_c_t_l_y_,_
          a_l_t_h_o_u_g_h_ s_e_c_o_n_d_ f_o_r_m_a_t_ i_s_ n_o_t_ a_s_ e_f_f_i_c_i_e_n_t_._
          <_s_y_m_>_     f_i_e_l_d_ s_p_e_c_i_f_i_e_r_ s_y_m_b_o_l_ (_q_u_o_t_e_d_)_
          <_f_c_n_>_     f_u_n_c_t_i_o_n_ t_o_  u_s_e_ (_q_u_o_t_e_d_  s_y_m_b_o_l_)_ w_h_i_c_h_ t_a_k_e_s_  t_h_e_ s_a_m_e_
                    a_r_g_u_m_e_n_t_s_ a_s_  t_h_e_ f_i_e_l_d_  s_p_e_c_i_f_i_e_r_  p_l_u_s_ a_n_  a_d_d_i_t_i_o_n_a_l_
                    a_r_g_u_m_e_n_t_ f_o_r_ t_h_e_ v_a_l_u_e_._ T_h_e_ v_a_l_u_e_ m_u_s_t_ b_e_ r_e_t_u_r_n_e_d_._
          <_f_a_r_g_s_>_   f_o_r_m_a_l_ a_r_g_u_m_e_n_t_ l_i_s_t_ (_l_a_m_b_d_a_ l_i_s_t_)_ (_q_u_o_t_e_d_)_
          <_v_a_l_u_e_>_   s_y_m_b_o_l_ b_o_u_n_d_ t_o_ v_a_l_u_e_ t_o_ s_t_o_r_e_ (_q_u_o_t_e_d_)_._
          <_e_x_p_r_>_    e_x_p_r_e_s_s_i_o_n_s_  t_o_ e_v_a_l_u_a_t_e_ (_q_u_o_t_e_d_)_._  T_h_e_ l_a_s_t_ e_x_p_r_e_s_s_i_o_n_
                    m_u_s_t_ r_e_t_u_r_n_ <_v_a_l_u_e_>_._
          r_e_t_u_r_n_s_   t_h_e_ f_i_e_l_d_ s_p_e_c_i_f_i_e_r_ s_y_m_b_o_l_

     (_p_u_s_h_  <_e_x_p_r_>_ <_p_l_a_c_e_>_)_                                 C_O_N_S_ T_O_ A_ F_I_E_L_D_
          D_e_f_i_n_e_d_  a_s_  m_a_c_r_o_  i_n_  c_o_m_m_o_n_._l_s_p_._  O_n_l_y_  e_v_a_l_u_a_t_e_s_  p_l_a_c_e_  f_o_r_m_
          a_r_g_u_m_e_n_t_s_ o_n_e_  t_i_m_e_._ I_t_ i_s_ r_e_c_o_m_m_e_n_d_e_d_  t_h_a_t_ *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_ b_e_
          n_o_n_-_N_I_L_ f_o_r_ b_e_s_t_ p_e_r_f_o_r_m_a_n_c_e_._
          <_p_l_a_c_e_>_   f_i_e_l_d_ s_p_e_c_i_f_i_e_r_ b_e_i_n_g_ m_o_d_i_f_i_e_d_ (_s_e_e_ s_e_t_f_)_
          <_e_x_p_r_>_    v_a_l_u_e_ t_o_ c_o_n_s_ t_o_ f_i_e_l_d_
          r_e_t_u_r_n_s_   t_h_e_ n_e_w_ v_a_l_u_e_ w_h_i_c_h_ i_s_ (_C_O_N_S_ <_e_x_p_r_>_ <_p_l_a_c_e_>_)_

     (_p_u_s_h_n_e_w_ <_e_x_p_r_>_ <_p_l_a_c_e_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_ C_O_N_S_ N_E_W_ T_O_ A_ F_I_E_L_D_
          D_e_f_i_n_e_d_  a_s_  m_a_c_r_o_  i_n_  c_o_m_m_o_n_._l_s_p_._  O_n_l_y_  e_v_a_l_u_a_t_e_s_  p_l_a_c_e_  f_o_r_m_
          a_r_g_u_m_e_n_t_s_ o_n_e_  t_i_m_e_._ I_t_ i_s_ r_e_c_o_m_m_e_n_d_e_d_  t_h_a_t_ *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_ b_e_
          n_o_n_-_N_I_L_ f_o_r_ b_e_s_t_ p_e_r_f_o_r_m_a_n_c_e_._
          <_p_l_a_c_e_>_   f_i_e_l_d_ s_p_e_c_i_f_i_e_r_ b_e_i_n_g_ m_o_d_i_f_i_e_d_ (_s_e_e_ s_e_t_f_)_
          <_e_x_p_r_>_    v_a_l_u_e_ t_o_ c_o_n_s_ t_o_ f_i_e_l_d_,_ i_f_ n_o_t_ a_l_r_e_a_d_y_ M_E_M_B_E_R_ o_f_ f_i_e_l_d_
          :_t_e_s_t_     t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_d_e_f_a_u_l_t_s_ t_o_ e_q_l_)_
          :_t_e_s_t_-_n_o_t_ t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_s_e_n_s_e_ i_n_v_e_r_t_e_d_)_
          :_k_e_y_      f_u_n_c_t_i_o_n_  t_o_  a_p_p_l_y_  t_o_  t_e_s_t_  f_u_n_c_t_i_o_n_  l_i_s_t_  a_r_g_u_m_e_n_t_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          r_e_t_u_r_n_s_   t_h_e_ n_e_w_ v_a_l_u_e_ w_h_i_c_h_ i_s_ (_C_O_N_S_ <_e_x_p_r_>_ <_p_l_a_c_e_>_)_ o_r_ <_p_l_a_c_e_>_

     (_p_o_p_ <_p_l_a_c_e_>_)_                          R_E_M_O_V_E_ F_I_R_S_T_ E_L_E_M_E_N_T_ O_F_ A_ F_I_E_L_D_
          D_e_f_i_n_e_d_  a_s_  m_a_c_r_o_  i_n_  c_o_m_m_o_n_._l_s_p_._  O_n_l_y_  e_v_a_l_u_a_t_e_s_  p_l_a_c_e_  f_o_r_m_
          a_r_g_u_m_e_n_t_s_ o_n_e_  t_i_m_e_._ I_t_ i_s_ r_e_c_o_m_m_e_n_d_e_d_  t_h_a_t_ *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_ b_e_
          n_o_n_-_N_I_L_ f_o_r_ b_e_s_t_ p_e_r_f_o_r_m_a_n_c_e_._
          <_p_l_a_c_e_>_   t_h_e_ f_i_e_l_d_ b_e_i_n_g_ m_o_d_i_f_i_e_d_ (_s_e_e_ s_e_t_f_)_
          r_e_t_u_r_n_s_   (_C_A_R_ <_p_l_a_c_e_>_)_,_ f_i_e_l_d_ c_h_a_n_g_e_d_ t_o_ (_C_D_R_ <_p_l_a_c_e_>_)_

     (_i_n_c_f_ <_p_l_a_c_e_>_ [_<_v_a_l_u_e_>_]_)_                             I_N_C_R_E_M_E_N_T_ A_ F_I_E_L_D_
     (_d_e_c_f_ <_p_l_a_c_e_>_ [_<_v_a_l_u_e_>_]_)_                             D_E_C_R_E_M_E_N_T_ A_ F_I_E_L_D_
          D_e_f_i_n_e_d_  a_s_  m_a_c_r_o_  i_n_  c_o_m_m_o_n_._l_s_p_._  O_n_l_y_  e_v_a_l_u_a_t_e_s_  p_l_a_c_e_  f_o_r_m_
          a_r_g_u_m_e_n_t_s_ o_n_e_  t_i_m_e_._ I_t_ i_s_ r_e_c_o_m_m_e_n_d_e_d_  t_h_a_t_ *_d_i_s_p_l_a_c_e_-_m_a_c_r_o_s_*_ b_e_
          n_o_n_-_N_I_L_ f_o_r_ b_e_s_t_ p_e_r_f_o_r_m_a_n_c_e_._
          <_p_l_a_c_e_>_   f_i_e_l_d_ s_p_e_c_i_f_i_e_r_ b_e_i_n_g_ m_o_d_i_f_i_e_d_ (_s_e_e_ s_e_t_f_)_
          <_v_a_l_u_e_>_   N_u_m_e_r_i_c_ v_a_l_u_e_ (_d_e_f_a_u_l_t_ 1_)_
          r_e_t_u_r_n_s_   t_h_e_  n_e_w_  v_a_l_u_e_ w_h_i_c_h_  i_s_  (_+_  <_p_l_a_c_e_>_ <_v_a_l_u_e_>_)_  o_r_  (_-_
                    <_p_l_a_c_e_>_ <_v_a_l_u_e_>_)_







     XLISP 2.1c                 SYMBOL FUNCTIONS                    Page 27


     (defun <sym> <fargs> <expr>...)                      DEFINE A FUNCTION
     (defmacro <sym> <fargs> <expr>...)                      DEFINE A MACRO
          fsubr
          <sym>     symbol being defined (quoted)
          <fargs>   formal argument list (lambda list) (quoted)
          <expr>    expressions  constituting  the  body  of  the  function
                    (quoted)
          returns   the function symbol

     (gensym [<tag>])                                     GENERATE A SYMBOL
          <tag>     string or number
          returns   the new symbol, uninterned

     (intern <pname>)                               MAKE AN INTERNED SYMBOL
          <pname>   the symbol's print name string
          returns   the new symbol

     (make-symbol <pname>)                        MAKE AN UNINTERNED SYMBOL
          <pname>   the symbol's print name string
          returns   the new symbol

     (symbol-name <sym>)                     GET THE PRINT NAME OF A SYMBOL
          <sym>     the symbol
          returns   the symbol's print name

     (symbol-value <sym>)                         GET THE VALUE OF A SYMBOL
          <sym>     the symbol
          returns   the symbol's value

     (symbol-function <sym>)           GET THE FUNCTIONAL VALUE OF A SYMBOL
          <sym>     the symbol
          returns   the symbol's functional value

     (symbol-plist <sym>)                 GET THE PROPERTY LIST OF A SYMBOL
          <sym>     the symbol
          returns   the symbol's property list

     (hash <expr> <n>)                               COMPUTE THE HASH INDEX
          <expr>    t_h_e_ o_b_j_e_c_t_ t_o_ h_a_s_h_ (_w_a_s_ o_n_l_y_ s_y_m_b_o_l_s_ o_r_ s_t_r_i_n_g_s_)_
          <n>       the table size (positive integer)
          returns   the hash index (integer 0 to n-1)

     (makunbound <sym>)                      MAKE A SYMBOL VALUE BE UNBOUND
          W_a_s_ d_e_f_i_n_e_d_ i_n_ i_n_i_t_._l_s_p_._ Y_o_u_ c_a_n_n_o_t_ u_n_b_i_n_d_ c_o_n_s_t_a_n_t_s_._
          <sym>     the symbol
          returns   the symbol

     (fmakunbound <sym>)                  MAKE A SYMBOL FUNCTION BE UNBOUND
          Defined in init.lsp
          <sym>     the symbol
          returns   the symbol







     XLISP 2.1c                 SYMBOL FUNCTIONS                    Page 28


     (_u_n_i_n_t_e_r_n_ <_s_y_m_>_)_                                     U_N_I_N_T_E_R_N_ A_ S_Y_M_B_O_L_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_s_y_m_>_     t_h_e_ s_y_m_b_o_l_
          r_e_t_u_r_n_s_   t_ i_f_ s_u_c_c_e_s_s_f_u_l_,_ N_I_L_ i_f_ s_y_m_b_o_l_ n_o_t_ i_n_t_e_r_n_e_d_

     (defconstant <sym> <val>)                            DEFINE A CONSTANT
          W_a_s_ d_e_f_i_n_e_d_ i_n_ i_n_i_t_._l_s_p_ a_n_d_ c_o_n_s_t_a_n_t_s_ w_e_r_e_n_'_t_ r_e_a_l_l_y_._
          fsubr or macro
          <sym>     the symbol
          <val>     the value
          returns   the value

     (defparameter <sym> <val>)                          DEFINE A PARAMETER
          fsubr.  W_a_s_ m_a_c_r_o_ d_e_f_i_n_e_d_ i_n_ i_n_i_t_._l_s_p_ a_n_d_ d_i_d_n_'_t_ c_r_e_a_t_e_ a_ s_p_e_c_i_a_l_
          v_a_r_i_a_b_l_e_._
          <sym>     the symbol
          <val>     the value
          returns   the value

     (defvar <sym> [<val>])                               DEFINE A VARIABLE
          fsubr. W_a_s_ m_a_c_r_o_ d_e_f_i_n_e_d_  i_n_ i_n_i_t_._l_s_p_ a_n_d_ d_i_d_n_t_ d_e_f_i_n_e_  a_ s_p_e_c_i_a_l_
          v_a_r_i_a_b_l_e_._ Variable only initialized if not previously defined.
          <sym>     the symbol
          <val>     the initial value, or NIL if absent.
          returns   the current value







     XLISP 2.1c              PROPERTY LIST FUNCTIONS                Page 29



     PROPERTY LIST FUNCTIONS

     A_s_ a_n_ a_d_d_e_d_ f_e_a_t_u_r_e_,_ p_r_o_p_e_r_t_y_ n_a_m_e_s_ a_r_e_ n_o_t_ l_i_m_i_t_e_d_ t_o_ s_y_m_b_o_l_s_._

     (get <sym> <prop>)                         GET THE VALUE OF A PROPERTY
          <sym>     the symbol
          <prop>    the property symbol
          returns   the property value or NIL

     (putprop <sym> <val> <prop>)       PUT A PROPERTY ONTO A PROPERTY LIST
          <sym>     the symbol
          <val>     the property value
          <prop>    the property symbol
          returns   the property value

     (remprop <sym> <prop>)                               DELETE A PROPERTY
          <sym>     the symbol
          <prop>    the property symbol
          returns   NIL







     XLISP 2.1c               HASH TABLE FUNCTIONS                  Page 30



     HASH TABLE FUNCTIONS

     N_e_w_ s_e_c_t_i_o_n_._ N_e_w_ f_u_n_c_t_i_o_n_s_._

     A hash  table is implemented  as an  structure of type  hash-table. No
     general accessing functions  are provided, and  hash tables print  out
     using the angle bracket  convention (not readable by READ).  The first
     element  is the  comparison function.  The remaining  elements contain
     association lists  of keys  (that hash  to the same  value) and  their
     data.

     (make-hash-table &key :size :test)                   MAKE A HASH TABLE
          :size     size of hash table -- should be a prime number. Default
                    is 31.
          :test     comparison function. Defaults to eql.
          returns   the hash table

     (gethash <key> <table> [<def>])                EXTRACT FROM HASH TABLE
          See also gethash in SETF.
          <key>     hash key
          <table>   hash table
          <def>     value to return on no match (default is NIL)
          returns   associated data, if found, or <def> if not found.

     (remhash <key> <table>)                         DELETE FROM HASH TABLE
          <key>     hash key
          <table>   hash table
          returns   T if deleted, NIL if not in table

     (clrhash <table>)                                 CLEAR THE HASH TABLE
          <table>   hash table
          returns   NIL, all entries cleared from table

     (hash-table-count <table>)             NUMBER OF ENTRIES IN HASH TABLE
          <table>   hash table
          returns   integer number of entries in table

     (maphash <fcn> <table>)                MAP FUNCTION OVER TABLE ENTRIES
          <fcn>     the  function  or  function  name, a  function  of  two
                    arguments,  the first  is  bound to  the  key, and  the
                    second the value of each table entry in turn.
          <table>   hash table
          returns   NIL







     XLISP 2.1c                  ARRAY FUNCTIONS                    Page 31



     ARRAY FUNCTIONS

     S_e_q_u_e_n_c_e_ f_u_n_c_t_i_o_n_s_ w_o_r_k_ o_n_ a_r_r_a_y_s_._

     (aref <array> <n>)                     GET THE NTH ELEMENT OF AN ARRAY
          T_h_i_s_ f_u_n_c_t_i_o_n_ n_o_w_  a_l_s_o_ w_o_r_k_s_  o_n_ s_t_r_i_n_g_s_._ S_e_e_  s_e_t_f_ f_o_r_  s_e_t_t_i_n_g_
          e_l_e_m_e_n_t_s_ o_f_ a_r_r_a_y_s_
          <array>   the array
          <n>       the array index (integer, zero based)
          returns   the value of the array element

     (make-array <size>)                                   MAKE A NEW ARRAY
          <size>    the size of the new array (integer)
          returns   the new array

     (vector <expr>...)                          MAKE AN INITIALIZED VECTOR
          <expr>    the vector elements
          returns   the new vector







     XLISP 2.1c                SEQUENCE FUNCTIONS                   Page 32



     SEQUENCE FUNCTIONS

     T_h_e_s_e_  f_u_n_c_t_i_o_n_s_ w_o_r_k_ o_n_ s_e_q_u_e_n_c_e_s_  -_-_ l_i_s_t_s_,_ a_r_r_a_y_s_,_  o_r_ s_t_r_i_n_g_s_,_ a_n_d_
     e_x_c_e_p_t_ a_s_  n_o_t_e_d_ r_e_p_r_e_s_e_n_t_ a_n_  e_x_t_e_n_s_i_o_n_ o_f_ t_h_e_  o_r_i_g_i_n_a_l_ d_i_s_t_r_i_b_u_t_i_o_n_
     X_L_I_S_P_ 2_._0_._

     (concatenate <type> <expr> ...)                  CONCATENATE SEQUENCES
          If result type is string, sequences must contain only characters.
          <type>    result type, one of CONS, LIST, ARRAY, or STRING
          <expr>    zero or more sequences to concatenate
          returns   a sequence which is  the concatenation of the arguement
                    sequences

     (elt <expr> <n>)                     GET THE NTH ELEMENT OF A SEQUENCE
          <expr>    the sequence
          <n>       the index of element to return
          returns   the element if the index is in bounds, otherwise error

     (map <type> <fcn> <expr> ...)    APPLY FUNCTION TO SUCCESSIVE ELEMENTS
          <type>    result type, one of CONS, LIST, ARRAY, STRING, or NIL
          <fcn>     the function or function name
          <expr>    a sequence for each argument of the function
          returns   a new sequence of type <type>.

     (every <fcn> <expr> ...)        APPLY FUNCTION TO ELEMENTS UNTIL FALSE
     (notevery <fcn> <expr> ...)
          <fcn>     the function or function name
          <expr>    a sequence for each argument of the function
          returns   every returns last evaluated function result
                    notevery  returns T if there  is a NIL function result,
                    else NIL

     (some <fcn> <expr> ...)          APPLY FUNCTION TO ELEMENTS UNTIL TRUE
     (notany <fcn> <expr> ...)
          <fcn>     the function or function name
          <expr>    a sequence for each argument of the function
          returns   some returns first non-NIL function result, or NIL
                    notany  returns  NIL if  there  is  a non-NIL  function
                    result, else T

     (length <expr>)                          FIND THE LENGTH OF A SEQUENCE
          U_n_c_h_a_n_g_e_d_ f_r_o_m_ t_h_e_ d_i_s_t_r_i_b_u_t_i_o_n_
          <expr>    the list, vector or string
          returns   the length of the list, vector or string

     (reverse <expr>)                                    REVERSE A SEQUENCE
     (nreverse <expr>)                     DESTRUCTIVELY REVERSE A SEQUENCE
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_ w_o_r_k_e_d_ o_n_ l_i_s_t_s_._ n_r_e_v_e_r_s_e_ i_s_ n_e_w_._
          <expr>    the sequence to reverse
          returns   a new sequence in the reverse order







     XLISP 2.1c                SEQUENCE FUNCTIONS                   Page 33


     (subseq <seq> <start> [<end>])                   EXTRACT A SUBSEQUENCE
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_ w_o_r_k_e_d_ o_n_ s_t_r_i_n_g_s_._
          <seq>     the sequence
          <start>   the starting position (zero origin)
          <end>     the  ending position + 1  (defaults to end)  o_r_ N_I_L_ f_o_r_
                    e_n_d_ o_f_ s_e_q_u_e_n_c_e_
          returns   the sequence between <start> and <end>

     (search <seq1> <seq2> &key :test  :test-not :key :start1 :end1 :start2
     :end2)
                                                        SEARCH FOR SEQUENCE
          <seq1>    the sequence to search for
          <seq2>    the sequence to search in
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :key      function to apply to test  function arguments (defaults
                    to identity)
          :start1   starting index in <seq1>
          :end1     index of end+1 in <seq1> or NIL for end of sequence
          :start2   starting index in <seq2>
          :end2     index of end+1 in <seq2> or NIL for end of sequence
          returns   position of first match

     (remove <expr> <seq> &key :test :test-not :key :start :end)
                                            REMOVE ELEMENTS FROM A SEQUENCE
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_  w_o_r_k_e_d_ o_n_ l_i_s_t_s_._ K_e_y_w_o_r_d_s_ :_k_e_y_ :_s_t_a_r_t_ :_e_n_d_ a_r_e_
          n_e_w_._
          <expr>    the element to remove
          <seq>     the sequence
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :key      function  to apply to  test function  sequence argument
                    (defaults to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   copy of sequence with matching expressions removed

     (remove-if <test> <seq> &key :key :start :end)
                                             REMOVE ELEMENTS THAT PASS TEST
     (remove-if-not <test> <seq> &key :key :start :end)
                                             REMOVE ELEMENTS THAT FAIL TEST
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_ w_o_r_k_e_d_ o_n_ l_i_s_t_s_._ K_e_y_w_o_r_d_s_ :_k_e_y_  :_s_t_a_r_t_ :_e_n_d_ a_r_e_
          n_e_w_._
          <test>    the test predicate
          <seq>     the sequence
          :key      function  to apply to  test function argument (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   copy of sequence with matching or non-matching elements
                    removed







     XLISP 2.1c                SEQUENCE FUNCTIONS                   Page 34


     (count-if <test> <seq> &key :key :start :end)
                                              COUNT ELEMENTS THAT PASS TEST
          <test>    the test predicate
          <seq>     the sequence
          :key      function to  apply to test function  argument (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   count of matching elements

     (find-if <test> <seq> &key :key :start :end)
                                        FIND FIRST ELEMENT THAT PASSES TEST
          <test>    the test predicate
          <seq>     the list
          :key      function to apply  to test function  argument (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   first element of sequence that passes test

     (position-if <test> <seq> &key :key :start :end)
                            FIND POSITION OF FIRST ELEMENT THAT PASSES TEST
          <test>    the test predicate
          <seq>     the list
          :key      function  to apply to  test function argument (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   position of first element of sequence that passes test,
                    or NIL.

     (delete <expr> <seq> &key :key :test :test-not :start :end)
                                            DELETE ELEMENTS FROM A SEQUENCE
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_ w_o_r_k_e_d_ o_n_ l_i_s_t_s_._ K_e_y_w_o_r_d_s_ :_k_e_y_ :_s_t_a_r_t_ :_e_n_d_  a_r_e_
          n_e_w_._
          <expr>    the element to delete
          <seq>     the sequence
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :key      function to  apply to  test function  sequence argument
                    (defaults to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   the sequence with the matching expressions deleted







     XLISP 2.1c                SEQUENCE FUNCTIONS                   Page 35


     (delete-if <test> <seq> &key :key :start :end)
                                             DELETE ELEMENTS THAT PASS TEST
     (delete-if-not <test> <seq> &key :key :start :end)
                                             DELETE ELEMENTS THAT FAIL TEST
          D_i_s_t_r_i_b_u_t_i_o_n_ o_n_l_y_ w_o_r_k_e_d_ o_n_ l_i_s_t_s_._  K_e_y_w_o_r_d_s_ :_k_e_y_ :_s_t_a_r_t_ :_e_n_d_ a_r_e_
          n_e_w_._
          <test>    the test predicate
          <seq>     the sequence
          :key      function to apply  to test function argument  (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   the  sequence  with matching  or  non-matching elements
                    deleted

     (reduce <fcn> <seq> &key :initial-value :start :end)
                                            REDUCE SEQUENCE TO SINGLE VALUE
          <fcn>     function  (of  two arguments)  to  apply  to result  of
                    previous  function application  (or first  element) and
                    each member of sequence.
          <seq>     the sequence
          :initial-value      value to  use  as  first  argument  in  first
                              function  application  rather than  using the
                              first element of the sequence.
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   if sequence  is empty  and there  is no  initial value,
                    returns result of applying function to zero arguements.
                    If  there is  a  single element,  returns the  element.
                    Otherwise  returns  the  result  of the  last  function
                    application.

     (remove-duplicates <seq> &key :test :test-not :key :start :end)
                                            REMOVE DUPLICATES FROM SEQUENCE
          <seq>     the sequence
          :test     comparison function (default eql)
          :test-not comparison function (sense inverted)
          :key      function to  apply to test function arguments (defaults
                    to identity)
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   copy of sequence with duplicates removed.

     (fill <seq> <expr> &key :start :end)         REPLACE ITEMS IN SEQUENCE
          Defined in common.lsp
          <seq>     the sequence
          <expr>    new value to place in sequence
          :start    starting index
          :end      index of end+1, or NIL for (length <seq>)
          returns   sequence with items replaced with new item







     XLISP 2.1c                SEQUENCE FUNCTIONS                   Page 36


     (replace <seq1> <seq2> &key :start1 :end1 :start2 :end2)
                                    REPLACE ITEMS IN SEQUENCE FROM SEQUENCE
          Defined in common.lsp
          <seq1>    the sequence to modify
          <seq2>    sequence with new items
          :start1   starting index in <seq1>
          :end1     index of end+1 in <seq1> or NIL for end of sequence
          :start2   starting index in <seq2>
          :end2     index of end+1 in <seq2> or NIL for end of sequence
          returns   first sequence with items replaced







     XLISP 2.1c                  LIST FUNCTIONS                     Page 37



     LIST FUNCTIONS 

     (car <expr>)                             RETURN THE CAR OF A LIST NODE
          <expr>    the list node
          returns   the car of the list node

     (cdr <expr>)                             RETURN THE CDR OF A LIST NODE
          <expr>    the list node
          returns   the cdr of the list node

     (cxxr <expr>)                                    ALL CxxR COMBINATIONS
     (cxxxr <expr>)                                  ALL CxxxR COMBINATIONS
     (cxxxxr <expr>)                                ALL CxxxxR COMBINATIONS

     (first <expr>)                                       A SYNONYM FOR CAR
     (second <expr>)                                     A SYNONYM FOR CADR
     (third <expr>)                                     A SYNONYM FOR CADDR
     (fourth <expr>)                                   A SYNONYM FOR CADDDR
     (rest <expr>)                                        A SYNONYM FOR CDR

     (cons <expr1> <expr2>)                       CONSTRUCT A NEW LIST NODE
          <expr1>   the car of the new list node
          <expr2>   the cdr of the new list node
          returns   the new list node

     (_a_c_o_n_s_ <_e_x_p_r_1_>_ <_e_x_p_r_2_>_ <_a_l_i_s_t_>_)_             A_D_D_ T_O_ F_R_O_N_T_ O_F_ A_S_S_O_C_ L_I_S_T_
          d_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_1_>_   k_e_y_ o_f_ n_e_w_ a_s_s_o_c_i_a_t_i_o_n_
          <_e_x_p_r_2_>_   v_a_l_u_e_ o_f_ n_e_w_ a_s_s_o_c_i_a_t_i_o_n_
          <_a_l_i_s_t_>_   a_s_s_o_c_i_a_t_i_o_n_ l_i_s_t_
          r_e_t_u_r_n_s_   n_e_w_ a_s_s_o_c_i_a_t_i_o_n_  l_i_s_t_,_  w_h_i_c_h_ i_s_  (_c_o_n_s_  (_c_o_n_s_  <_e_x_p_r_1_>_
                    <_e_x_p_r_2_>_)_ <_e_x_p_r_3_>_)_)_

     (list <expr>...)                               CREATE A LIST OF VALUES
     (_l_i_s_t_*_ <_e_x_p_r_>_ ._._._ <_l_i_s_t_>_)_
          l_i_s_t_*_ m_a_y_ b_e_ d_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <expr>    expressions to be combined into a list
          returns   the new list

     (append <expr>...)                                        APPEND LISTS
          <expr>    lists whose elements are to be appended
          returns   the new list

     (last <list>)                      RETURN THE LAST LIST NODE OF A LIST
          <list>    the list
          returns   the last list node in the list







     XLISP 2.1c                  LIST FUNCTIONS                     Page 38


     (_b_u_t_l_a_s_t_ <_l_i_s_t_>_ [_<_n_>_]_)_             R_E_T_U_R_N_ C_O_P_Y_ O_F_ A_L_L_ B_U_T_ L_A_S_T_ O_F_ L_I_S_T_
          A_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_l_i_s_t_>_    t_h_e_ l_i_s_t_
          <_n_>_       c_o_u_n_t_ o_f_ e_l_e_m_e_n_t_s_ t_o_ o_m_i_t_ (_d_e_f_a_u_l_t_ 1_)_
          r_e_t_u_r_n_s_   c_o_p_y_ o_f_ l_i_s_t_ w_i_t_h_ l_a_s_t_ e_l_e_m_e_n_t_(_s_)_ a_b_s_e_n_t_._

     (nth <n> <list>)                      RETURN THE NTH ELEMENT OF A LIST
          <n>       the number of the element to return (zero origin)
          <list>    the list
          returns   the nth element or NIL if the list isn't that long

     (nthcdr <n> <list>)                       RETURN THE NTH CDR OF A LIST
          <n>       the number of the element to return (zero origin)
          <list>    the list
          returns   the nth cdr or NIL if the list isn't that long

     (member <expr> <list> &key :test :test-not :key)
                                               FIND AN EXPRESSION IN A LIST
          <expr>    the expression to find
          <list>    the list to search
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :_k_e_y_      f_u_n_c_t_i_o_n_  t_o_  a_p_p_l_y_  t_o_  t_e_s_t_  f_u_n_c_t_i_o_n_  l_i_s_t_  a_r_g_u_m_e_n_t_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          returns   the remainder of the list starting with the expression

     (assoc <expr> <alist> &key :test :test-not :key)
                                            FIND AN EXPRESSION IN AN A-LIST
          <expr>    the expression to find
          <alist>   the association list
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :_k_e_y_      f_u_n_c_t_i_o_n_  t_o_  a_p_p_l_y_  t_o_  t_e_s_t_  f_u_n_c_t_i_o_n_  l_i_s_t_  a_r_g_u_m_e_n_t_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          returns   the alist entry or NIL

     (mapc <fcn> <list1> <list>...)       APPLY FUNCTION TO SUCCESSIVE CARS
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   the first list of arguments

     (mapcar <fcn> <list1> <list>...)     APPLY FUNCTION TO SUCCESSIVE CARS
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   a list of the values returned

     (mapl <fcn> <list1> <list>...)       APPLY FUNCTION TO SUCCESSIVE CDRS
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   the first list of arguments







     XLISP 2.1c                  LIST FUNCTIONS                     Page 39


     (maplist <fcn> <list1> <list>...)    APPLY FUNCTION TO SUCCESSIVE CDRS
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   a list of the values returned

     (mapcan <fcn> <list1> <list>...)      APPL FUNCTION TO SUCCESSIVE CARS
          This function is in init.lsp
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   list of return values nconc'd together

     (mapcon <fcn> <list1> <list>...)      APPL FUNCTION TO SUCCESSIVE CDRS
          This function is in init.lsp
          <fcn>     the function or function name
          <listn>   a list for each argument of the function
          returns   list of return values nconc'd together

     (subst <to> <from> <expr> &key :test :test-not :key)
                                                     SUBSTITUTE EXPRESSIONS
          M_o_d_i_f_i_e_d_ t_o_ d_o_ m_i_n_i_m_u_m_ c_o_p_y_i_n_g_ a_s_ i_n_ C_o_m_m_o_n_ L_i_s_p_
          <to>      the new expression
          <from>    the old expression
          <expr>    the expression in which to do the substitutions
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :_k_e_y_      f_u_n_c_t_i_o_n_ t_o_ a_p_p_l_y_ t_o_  t_e_s_t_ f_u_n_c_t_i_o_n_ e_x_p_r_e_s_s_i_o_n_ a_r_g_u_m_e_n_t_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          returns   the expression with substitutions

     (sublis <alist> <expr> &key :test :test-not :key)
                                                  SUBSTITUTE WITH AN A-LIST
          M_o_d_i_f_i_e_d_ t_o_ d_o_ m_i_n_i_m_u_m_ c_o_p_y_i_n_g_ a_s_ i_n_ C_o_m_m_o_n_ L_i_s_p_
          <alist>   the association list
          <expr>    the expression in which to do the substitutions
          :test     the test function (defaults to eql)
          :test-not the test function (sense inverted)
          :_k_e_y_      f_u_n_c_t_i_o_n_ t_o_ a_p_p_l_y_ t_o_ t_e_s_t_  f_u_n_c_t_i_o_n_ e_x_p_r_e_s_s_i_o_n_ a_r_g_u_m_e_n_t_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          returns   the expression with substitutions

     (_p_a_i_r_l_i_s_ <_k_e_y_s_>_ <_v_a_l_u_e_s_>_ [_<_a_l_i_s_t_>_]_)_     B_U_I_L_D_ A_N_ A_-_L_I_S_T_ F_R_O_M_ T_W_O_ L_I_S_T_S_
          I_n_ f_i_l_e_ c_o_m_m_o_n_._l_s_p_
          <_k_e_y_s_>_    l_i_s_t_ o_f_ a_s_s_o_c_i_a_t_i_o_n_ k_e_y_s_
          <_v_a_l_u_e_s_>_  l_i_s_t_ o_f_ a_s_s_o_c_i_a_t_i_o_n_ v_a_l_u_e_s_,_ s_a_m_e_ l_e_n_g_t_h_ a_s_ k_e_y_s_
          <_a_l_i_s_t_>_   e_x_i_s_t_i_n_g_ a_s_s_o_c_i_a_t_i_o_n_ l_i_s_t_,_ d_e_f_a_u_l_t_ N_I_L_
          r_e_t_u_r_n_s_   n_e_w_ a_s_s_o_c_i_a_t_i_o_n_ l_i_s_t_

     (_c_o_p_y_-_l_i_s_t_ <_l_i_s_t_>_)_                        C_O_P_Y_ T_H_E_ T_O_P_ L_E_V_E_L_ O_F_ A_ L_I_S_T_
          I_n_ f_i_l_e_ c_o_m_m_o_n_._l_s_p_
          <_l_i_s_t_>_    t_h_e_ l_i_s_t_
          r_e_t_u_r_n_s_   a_ c_o_p_y_ o_f_ t_h_e_ l_i_s_t_ (_n_e_w_ c_o_n_s_ c_e_l_l_s_ i_n_ t_o_p_ l_e_v_e_l_)_







     XLISP 2.1c                  LIST FUNCTIONS                     Page 40


     (_c_o_p_y_-_a_l_i_s_t_ <_a_l_i_s_t_>_)_                          C_O_P_Y_ A_N_ A_S_S_O_C_I_A_T_I_O_N_ L_I_S_T_
          I_n_ f_i_l_e_ c_o_m_m_o_n_._l_s_p_
          <_a_l_i_s_t_>_   t_h_e_ a_s_s_o_c_i_a_t_i_o_n_ l_i_s_t_
          r_e_t_u_r_n_s_   a_ c_o_p_y_  o_f_ t_h_e_  a_s_s_o_c_i_a_t_i_o_n_ l_i_s_t_  (_k_e_y_s_ a_n_d_ v_a_l_u_e_s_  n_o_t_
          c_o_p_i_e_s_)_

     (_c_o_p_y_-_t_r_e_e_ <_t_r_e_e_>_)_                                         C_O_P_Y_ A_ T_R_E_E_
          I_n_ f_i_l_e_ c_o_m_m_o_n_._l_s_p_
          <_t_r_e_e_>_    a_ t_r_e_e_ s_t_r_u_c_t_u_r_e_ o_f_ c_o_n_s_ c_e_l_l_s_
          r_e_t_u_r_n_s_   a_ c_o_p_y_ o_f_ t_h_e_ t_r_e_e_ s_t_r_u_c_t_u_r_e_

     (_i_n_t_e_r_s_e_c_t_i_o_n_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_ S_E_T_ F_U_N_C_T_I_O_N_S_
     (_u_n_i_o_n_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_s_e_t_-_d_i_f_f_e_r_e_n_c_e_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_n_i_n_t_e_r_s_e_c_t_i_o_n_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_n_u_n_i_o_n_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_n_s_e_t_-_d_i_f_f_e_r_e_n_c_e_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
     (_n_s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_
          N_e_w_ f_u_n_c_t_i_o_n_s_._ s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_  a_n_d_ n_s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_ d_e_f_i_n_e_d_ i_n_
          c_o_m_m_o_n_._l_s_p_._  n_u_n_i_o_n_,_  n_i_n_t_e_r_s_e_c_t_i_o_n_,_   a_n_d_  n_s_e_t_-_d_i_f_f_e_r_e_n_c_e_   a_r_e_
          a_l_i_a_s_e_d_ t_o_ t_h_e_i_r_ n_o_n_-_d_e_s_t_r_u_c_t_i_v_e_ c_o_u_n_t_e_r_p_a_r_t_s_ i_n_ c_o_m_m_o_n_._l_s_p_._
          <_l_i_s_t_1_>_   f_i_r_s_t_ l_i_s_t_
          <_l_i_s_t_2_>_   s_e_c_o_n_d_ l_i_s_t_
          :_t_e_s_t_     t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_d_e_f_a_u_l_t_s_ t_o_ e_q_l_)_
          :_t_e_s_t_-_n_o_t_ t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_s_e_n_s_e_ i_n_v_e_r_t_e_d_)_
          :_k_e_y_      f_u_n_c_t_i_o_n_ t_o_ a_p_p_l_y_ t_o_ t_e_s_t_ f_u_n_c_t_i_o_n_ a_r_g_u_m_e_n_t_s_  (_d_e_f_a_u_l_t_s_
                    t_o_ i_d_e_n_t_i_t_y_)_
          r_e_t_u_r_n_s_   i_n_t_e_r_s_e_c_t_i_o_n_:_ l_i_s_t_ o_f_ a_l_l_ e_l_e_m_e_n_t_s_ i_n_ b_o_t_h_ l_i_s_t_s_
                    u_n_i_o_n_:_ l_i_s_t_ o_f_ a_l_l_ e_l_e_m_e_n_t_s_ i_n_ e_i_t_h_e_r_ l_i_s_t_
                    s_e_t_-_d_i_f_e_r_e_n_c_e_:_ l_i_s_t_  o_f_ a_l_l_ e_l_e_m_e_n_t_s_ i_n_  f_i_r_s_t_ l_i_s_t_ b_u_t_
                    n_o_t_ i_n_ s_e_c_o_n_d_ l_i_s_t_
                    s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_:_ l_i_s_t_ o_f_ a_l_l_ e_l_e_m_e_n_t_s_ i_n_ o_n_l_y_ o_n_e_ l_i_s_t_
                    "_n_"_ v_e_r_s_i_o_n_s_ a_r_e_ p_o_t_e_n_t_i_a_l_l_y_ d_e_s_t_r_u_c_t_i_v_e_._

     (_a_d_j_o_i_n_ <_e_x_p_r_>_ <_l_i_s_t_>_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_         A_D_D_ U_N_I_Q_U_E_ T_O_ L_I_S_T_
          N_e_w_ f_u_n_c_t_i_o_n_._
          <_e_x_p_r_>_    n_e_w_ e_l_e_m_e_n_t_ t_o_ a_d_d_
          <_l_i_s_t_>_    t_h_e_ l_i_s_t_
          :_t_e_s_t_     t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_d_e_f_a_u_l_t_s_ t_o_ e_q_l_)_
          :_t_e_s_t_-_n_o_t_ t_h_e_ t_e_s_t_ f_u_n_c_t_i_o_n_ <_s_e_n_s_e_ i_n_v_e_r_t_e_d_)_
          :_k_e_y_      f_u_n_c_t_i_o_n_ t_o_ a_p_p_l_y_ t_o_  t_e_s_t_ f_u_n_c_t_i_o_n_ a_r_g_u_m_e_n_t_s_ (_d_e_f_a_u_l_t_s_
                    t_o_ i_d_e_n_t_i_t_y_)_
          r_e_t_u_r_n_s_   i_f_ e_l_e_m_e_n_t_  n_o_t_ i_n_ l_i_s_t_ t_h_e_n_ (_c_o_n_s_ <_e_x_p_r_>_ <_l_i_s_t_>_)_,_ e_l_s_e_
                    <_l_i_s_t_>_._







     XLISP 2.1c            DESTRUCTIVE LIST FUNCTIONS               Page 41



     DESTRUCTIVE LIST FUNCTIONS

     S_e_e_ a_l_s_o_ n_r_e_v_e_r_s_e_,_ d_e_l_e_t_e_,_ d_e_l_e_t_e_-_i_f_,_ d_e_l_e_t_e_-_i_f_-_n_o_t_,_ f_i_l_l_,_ a_n_d_ r_e_p_l_a_c_e_
     u_n_d_e_r_   S_E_Q_U_E_N_C_E_  F_U_N_C_T_I_O_N_S_,_   s_e_t_f_   u_n_d_e_r_   s_y_m_b_o_l_  f_u_n_c_t_i_o_n_s_,_   a_n_d_
     n_i_n_t_e_r_s_e_c_t_i_o_n_,_  n_u_n_i_o_n_,_  n_s_e_t_-_d_i_f_f_e_r_e_n_c_e_,_ a_n_d_  n_s_e_t_-_e_x_c_l_u_s_i_v_e_-_o_r_ u_n_d_e_r_
     L_I_S_T_ F_U_N_C_T_I_O_N_S_._

     (rplaca <list> <expr>)                  REPLACE THE CAR OF A LIST NODE
          <list>    the list node
          <expr>    the new value for the car of the list node
          returns   the list node after updating the car

     (rplacd <list> <expr>)                  REPLACE THE CDR OF A LIST NODE
          <list>    the list node
          <expr>    the new value for the cdr of the list node
          returns   the list node after updating the cdr

     (nconc <list>...)                      DESTRUCTIVELY CONCATENATE LISTS
          <list>    lists to concatenate
          returns   the result of concatenating the lists

     (sort <list> <test> &key :key)                             SORT A LIST
          <list>    the list to sort
          <test>    the comparison function
          :_k_e_y_      f_u_n_c_t_i_o_n_  t_o_  a_p_p_l_y_  t_o_ c_o_m_p_a_r_i_s_o_n_  f_u_n_c_t_i_o_n_  a_r_g_u_m_e_n_t_s_
                    (_d_e_f_a_u_l_t_s_ t_o_ i_d_e_n_t_i_t_y_)_
          returns   the sorted list







     XLISP 2.1c               ARITHMETIC FUNCTIONS                  Page 42



     ARITHMETIC FUNCTIONS

     W_a_r_n_i_n_g_:_ i_n_t_e_g_e_r_ c_a_l_c_u_l_a_t_i_o_n_s_ t_h_a_t_ o_v_e_r_f_l_o_w_ g_i_v_e_ e_r_r_o_n_e_o_u_s_ r_e_s_u_l_t_s_._ O_n_
     s_y_s_t_e_m_s_ w_i_t_h_ I_E_E_E_ f_l_o_a_t_i_n_g_ p_o_i_n_t_,_ t_h_e_ v_a_l_u_e_s_ +_I_N_F_ a_n_d_ -_I_N_F_ r_e_s_u_l_t_ f_r_o_m_
     o_v_e_r_f_l_o_w_i_n_g_ f_l_o_a_t_i_n_g_ p_o_i_n_t_ c_a_l_c_u_l_a_t_i_o_n_s_._

     T_h_e_  m_a_t_h_ e_x_t_e_n_s_i_o_n_  a_d_d_s_ a_d_d_i_t_i_o_n_a_l_  f_u_n_c_t_i_o_n_a_l_i_t_y_ t_o_  f_u_n_c_t_i_o_n_s_ t_h_a_t_
     t_o_o_k_ o_n_l_y_ f_l_o_a_t_i_n_g_ p_o_i_n_t_  a_r_g_u_m_e_n_t_s_ (_S_I_N_ C_O_S_  T_A_N_ A_S_I_N_ A_C_O_S_ A_T_A_N_  E_X_P_T_
     E_X_P_  S_Q_R_T_)_:_  T_h_e_y_  w_i_l_l_  n_o_w_  t_a_k_e_  a_r_g_u_m_e_n_t_s_  o_f_  a_n_y_  t_y_p_e_._  I_n_  t_h_e_
     d_e_s_c_r_i_p_t_i_o_n_s_,_  "_r_e_a_l_ n_u_m_b_e_r_"_  m_e_a_n_s_ f_l_o_a_t_i_n_g_  p_o_i_n_t_ n_u_m_b_e_r_  o_r_ i_n_t_e_g_e_r_
     o_n_l_y_._


     (truncate <expr> <_d_e_n_o_m_>_)                        TRUNCATES TOWARD ZERO
     (_r_o_u_n_d_ <_e_x_p_r_>_ <_d_e_n_o_m_>_)_                   R_O_U_N_D_S_ T_O_W_A_R_D_ N_E_A_R_E_S_T_ I_N_T_E_G_E_R_
     (_f_l_o_o_r_ <_e_x_p_r_>_ <_d_e_n_o_m_>_)_              T_R_U_N_C_A_T_E_S_ T_O_W_A_R_D_ N_E_G_A_T_I_V_E_ I_N_F_I_N_I_T_Y_
     (_c_e_i_l_i_n_g_ <_e_x_p_r_>_ <_d_e_n_o_m_>_)_                     T_R_U_N_C_A_T_E_S_ T_O_W_A_R_D_ I_N_F_I_N_I_T_Y_
          R_o_u_n_d_,_ f_l_o_o_r_,_ a_n_d_ c_e_i_l_i_n_g_,_  a_n_d_ t_h_e_ s_e_c_o_n_d_ a_r_g_u_m_e_n_t_  o_f_ t_r_u_n_c_a_t_e_,_
          a_r_e_ p_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_._ R_e_s_u_l_t_s_ t_o_o_ b_i_g_ t_o_ b_e_ r_e_p_r_e_s_e_n_t_e_d_
          a_s_ i_n_t_e_g_e_r_s_ a_r_e_ r_e_t_u_r_n_e_d_ a_s_ f_l_o_a_t_i_n_g_ p_o_i_n_t_ n_u_m_b_e_r_s_ a_s_ p_a_r_t_ o_f_ t_h_e_
          m_a_t_h_ e_x_t_e_n_s_i_o_n_._ I_n_t_e_g_e_r_s_ a_r_e_ r_e_t_u_r_n_e_d_ a_s_ i_s_._
          <expr>    the real number
          <_d_e_n_o_m_>_   r_e_a_l_ n_u_m_b_e_r_ t_o_ d_i_v_i_d_e_ <_e_x_p_r_>_ b_y_ b_e_f_o_r_e_ c_o_n_v_e_r_t_i_n_g_
          returns   the integer result of converting the number

     (float <expr>)          CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
          <expr>    the real number
          returns   the number as a floating point number

     (+ [<expr>...])                                  ADD A LIST OF NUMBERS
          W_i_t_h_ n_o_ a_r_g_u_m_e_n_t_s_ r_e_t_u_r_n_s_ a_d_d_i_t_i_o_n_ i_d_e_n_t_i_t_y_,_ 0_ (_i_n_t_e_g_e_r_)_
          <expr>    the numbers
          returns   the result of the addition

     (- <expr>...)     SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
          <expr>    the numbers
          returns   the result of the subtraction

     (* [<expr>...])                             MULTIPLY A LIST OF NUMBERS
          W_i_t_h_ n_o_ a_r_g_u_m_e_n_t_s_ r_e_t_u_r_n_s_ m_u_l_t_i_p_l_i_c_a_t_i_o_n_ i_d_e_n_t_i_t_y_,_ 1_
          <expr>    the numbers
          returns   the result of the multiplication

     (/ <expr>...)       DIVIDE A LIST OF NUMBERS OR INVERT A SINGLE NUMBER
          W_h_e_n_ m_a_t_h_ e_x_t_e_n_s_i_o_n_ i_s_ c_o_m_p_i_l_e_d_,_ d_i_v_i_s_i_o_n_  o_f_ i_n_t_e_g_e_r_s_ r_e_s_u_l_t_s_ i_n_
          a_  f_l_o_a_t_i_n_g_ p_o_i_n_t_  q_u_o_t_i_e_n_t_  i_f_ t_h_e_  q_u_o_t_i_e_n_t_  c_a_n_n_o_t_ b_e_  e_x_a_c_t_l_y_
          r_e_p_r_e_s_e_n_t_e_d_  a_s_ a_n_ i_n_t_e_g_e_r_._  T_o_ p_e_r_f_o_r_m_ a_n_  i_n_t_e_g_e_r_ d_i_v_i_s_i_o_n_,_ u_s_e_
          T_R_U_N_C_A_T_E_._
          <expr>    the numbers
          returns   the result of the division







     XLISP 2.1c               ARITHMETIC FUNCTIONS                  Page 43


     (1+ <expr>)                                        ADD ONE TO A NUMBER
          <expr>    the number
          returns   the number plus one

     (1- <expr>)                                 SUBTRACT ONE FROM A NUMBER
          <expr>    the number
          returns   the number minus one

     (rem <expr>...)                         REMAINDER OF A LIST OF NUMBERS
          W_h_e_n_ m_a_t_h_  e_x_t_e_n_s_i_o_n_ c_o_m_p_i_l_e_d_,_ o_n_l_y_ t_w_o_  a_r_g_u_m_e_n_t_s_ a_l_l_o_w_e_d_,_ w_h_i_c_h_
          m_a_y_ b_e_ r_e_a_l_ n_u_m_b_e_r_s_._
          <expr>    the numbers (must be integers)
          returns   the result of the remainder operation

     (min <expr>...)                      THE SMALLEST OF A LIST OF NUMBERS
          <expr>    the real numbers
          returns   the smallest number in the list

     (max <expr>...)                       THE LARGEST OF A LIST OF NUMBERS
          <expr>    the real numbers
          returns   the largest number in the list

     (abs <expr>)                            THE ABSOLUTE VALUE OF A NUMBER
          <expr>    the number
          returns   the absolute value of the number,_ w_h_i_c_h_ i_s_ t_h_e_ f_l_o_a_t_i_n_g_
                    p_o_i_n_t_ m_a_g_n_i_t_u_d_e_ f_o_r_ c_o_m_p_l_e_x_ n_u_m_b_e_r_s_._

     (_s_i_g_n_u_m_ <_e_x_p_r_>_)_                               G_E_T_ T_H_E_ S_I_G_N_ O_F_ A_ N_U_M_B_E_R_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   z_e_r_o_ i_f_ n_u_m_b_e_r_  i_s_ z_e_r_o_,_ o_n_e_  i_f_ p_o_s_i_t_i_v_e_,_ o_r_  n_e_g_a_t_i_v_e_
                    o_n_e_  i_f_ n_e_g_a_t_i_v_e_._ N_u_m_e_r_i_c_ t_y_p_e_ i_s_ s_a_m_e_ a_s_ n_u_m_b_e_r_._ F_o_r_ a_
                    c_o_m_p_l_e_x_ n_u_m_b_e_r_,_  r_e_t_u_r_n_s_ u_n_i_t_ m_a_g_n_i_t_u_d_e_ b_u_t_  s_a_m_e_ p_h_a_s_e_
                    a_s_ n_u_m_b_e_r_._

     (gcd [<n>...])                     COMPUTE THE GREATEST COMMON DIVISOR
          With  no  arguments  returns 0,  with  one  argument returns  the
          argument.
          <n>       The number(s) (integer)
          returns   the greatest common divisor

     (_l_c_m_ <_n_>_._._._)_                         C_O_M_P_U_T_E_ T_H_E_ L_E_A_S_T_ C_O_M_M_O_N_ M_U_L_T_I_P_L_E_
          P_a_r_t_ o_f_ m_a_t_h_ e_x_t_e_n_s_i_o_n_._
          <_n_>_       T_h_e_ n_u_m_b_e_r_(_s_)_ (_i_n_t_e_g_e_r_)_
          r_e_t_u_r_n_s_   t_h_e_ l_e_a_s_t_ c_o_m_m_o_n_ m_u_l_t_i_p_l_e_







     XLISP 2.1c               ARITHMETIC FUNCTIONS                  Page 44


     (random <n> [_<_s_t_a_t_e_>_]_)                  COMPUTE A PSEUDO-RANDOM NUMBER
          O_r_i_g_i_n_a_l_l_y_ w_o_r_k_e_d_  o_n_l_y_ w_i_t_h_ i_n_t_e_g_e_r_s_  a_n_d_ d_i_d_ n_o_t_  t_a_k_e_ o_p_t_i_o_n_a_l_
          a_r_g_u_m_e_n_t_._
          <n>       the real number upper bound
          <_s_t_a_t_e_>_   a_ r_a_n_d_o_m_-_s_t_a_t_e_ (_d_e_f_a_u_l_t_ i_s_ *_r_a_n_d_o_m_-_s_t_a_t_e_*_)_
          returns   a random number in range [0,n)

     (_m_a_k_e_-_r_a_n_d_o_m_-_s_t_a_t_e_ [_<_s_t_a_t_e_>_]_)_                    C_R_E_A_T_E_ A_ R_A_N_D_O_M_-_S_T_A_T_E_
          N_e_w_ f_u_n_c_t_i_o_n_._
          <_s_t_a_t_e_>_   a_  r_a_n_d_o_m_-_s_t_a_t_e_,_ t_,_  o_r_  N_I_L_ (_d_e_f_a_u_l_t_  N_I_L_)_._ N_I_L_  m_e_a_n_s_
                    *_r_a_n_d_o_m_-_s_t_a_t_e_*_
          r_e_t_u_r_n_s_   I_f_  <_s_t_a_t_e_>_ i_s_  t_,_ a_  r_a_n_d_o_m_ r_a_n_d_o_m_-_s_t_a_t_e_,_  o_t_h_e_r_w_i_s_e_ a_
                    c_o_p_y_ o_f_ <_s_t_a_t_e_>_

     (sin <expr>)                              COMPUTE THE SINE OF A NUMBER
     (cos <expr>)                            COMPUTE THE COSINE OF A NUMBER
     (tan <expr>)                           COMPUTE THE TANGENT OF A NUMBER
     (asin <expr>)                         COMPUTE THE ARC SINE OF A NUMBER
     (acos <expr>)                       COMPUTE THE ARC COSINE OF A NUMBER
          <expr>    the floating point number
          returns   the sine, cosine,  tangent, arc sine, or arc  cosine of
                    the number

     (atan <expr> [_<_e_x_p_r_2_>_]_)            COMPUTE THE ARC TANGENT OF A NUMBER
          <_e_x_p_r_2_>_ c_a_n_ o_n_l_y_ b_e_ s_p_e_c_i_f_i_e_d_ w_h_e_n_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_ i_s_ c_o_m_p_i_l_e_d_
          <expr>    the floating point number (_n_u_m_e_r_a_t_o_r_>_
          <_e_x_p_r_2_>_   t_h_e_ d_e_n_o_m_i_n_a_t_o_r_,_ d_e_f_a_u_l_t_ 1_
          returns   the arc tangent of <_e_x_p_r_>_/_<_e_x_p_r_2_>_

     (_s_i_n_h_ <_e_x_p_r_>_)_                  C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ S_I_N_E_ O_F_ A_ N_U_M_B_E_R_
     (_c_o_s_h_ <_e_x_p_r_>_)_                C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ C_O_S_I_N_E_ O_F_ A_ N_U_M_B_E_R_
     (_t_a_n_h_ <_e_x_p_r_>_)_               C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ T_A_N_G_E_N_T_ O_F_ A_ N_U_M_B_E_R_
     (_a_s_i_n_h_ <_e_x_p_r_>_)_             C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ A_R_C_ S_I_N_E_ O_F_ A_ N_U_M_B_E_R_
     (_a_c_o_s_h_ <_e_x_p_r_>_)_           C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ A_R_C_ C_O_S_I_N_E_ O_F_ A_ N_U_M_B_E_R_
     (_a_t_a_n_h_ <_e_x_p_r_>_)_          C_O_M_P_U_T_E_ T_H_E_ H_Y_P_E_R_B_O_L_I_C_ A_R_C_ T_A_N_G_E_N_T_ O_F_ A_ N_U_M_B_E_R_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   t_h_e_  h_y_p_e_r_b_o_l_i_c_ s_i_n_e_,_  c_o_s_i_n_e_,_ t_a_n_g_e_n_t_,_  a_r_c_  s_i_n_e_,_ a_r_c_
                    c_o_s_i_n_e_,_ o_r_ a_r_c_ t_a_n_g_e_n_t_ o_f_ t_h_e_ n_u_m_b_e_r_._

     (expt <x-expr> <y-expr>)                      COMPUTE X TO THE Y POWER
          <x-expr>  the floating point number 
          <y-expr>  the floating point exponent 
          returns   x to the y power

     (exp <x-expr>)                                COMPUTE E TO THE X POWER
          <x-expr>  the floating point number 
          returns   e to the x power







     XLISP 2.1c               ARITHMETIC FUNCTIONS                  Page 45


     (_c_i_s_ <_x_-_e_x_p_r_>_)_                                 C_O_M_P_U_T_E_ C_O_S_I_N_E_ +_ I_ S_I_N_E_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_x_-_e_x_p_r_>_  t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   e_ t_o_ t_h_e_ i_x_ p_o_w_e_r_

     (_l_o_g_ <_e_x_p_r_>_ [_<_b_a_s_e_>_]_)_                             C_O_M_P_U_T_E_ T_H_E_ L_O_G_R_I_T_H_M_
          P_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          <_b_a_s_e_>_    t_h_e_ b_a_s_e_,_ d_e_f_a_u_l_t_ i_s_ e_
          r_e_t_u_r_n_s_   l_o_g_ b_a_s_e_ <_b_a_s_e_>_ o_f_ <_e_x_p_r_>_

     (sqrt <expr>)                      COMPUTE THE SQUARE ROOT OF A NUMBER
          <expr>    the floating point number 
          returns   the square root of the number

     (_c_o_m_p_l_e_x_ <_r_e_a_l_>_ [_<_i_m_a_g_>_]_)_                    C_O_N_V_E_R_T_ T_O_ C_O_M_P_L_E_X_ N_U_M_B_E_R_
          P_a_r_t_ o_f_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_r_e_a_l_>_    r_e_a_l_ n_u_m_b_e_r_ r_e_a_l_ p_a_r_t_
          <_i_m_a_g_>_    r_e_a_l_ n_u_m_b_e_r_ i_m_a_g_i_n_a_r_y_ p_a_r_t_ (_d_e_f_a_u_l_t_ 0_)_
          r_e_t_u_r_n_s_   t_h_e_ c_o_m_p_l_e_x_ n_u_m_b_e_r_

     (_r_e_a_l_p_a_r_t_ <_e_x_p_r_>_)_                        G_E_T_ T_H_E_ R_E_A_L_ P_A_R_T_ O_F_ A_ N_U_M_B_E_R_
          P_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   t_h_e_ r_e_a_l_ p_a_r_t_ o_f_ a_ c_o_m_p_l_e_x_ n_u_m_b_e_r_,_ o_r_ t_h_e_ n_u_m_b_e_r_ i_t_s_e_l_f_
          i_f_ a_ r_e_a_l_ n_u_m_b_e_r_

     (_i_m_a_g_p_a_r_t_ <_e_x_p_r_>_)_                   G_E_T_ T_H_E_ I_M_A_G_I_N_A_R_Y_ P_A_R_T_ O_F_ A_ N_U_M_B_E_R_
          P_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   t_h_e_  i_m_a_g_i_n_a_r_y_ p_a_r_t_ o_f_ a_ c_o_m_p_l_e_x_ n_u_m_b_e_r_,_ o_r_ z_e_r_o_ o_f_ t_h_e_
                    t_y_p_e_ o_f_ t_h_e_ n_u_m_b_e_r_ i_f_ a_ r_e_a_l_ n_u_m_b_e_r_._

     (_c_o_n_j_u_g_a_t_e_ <_e_x_p_r_>_)_                       G_E_T_ T_H_E_ C_O_N_J_U_G_A_T_E_ O_F_ A_ N_U_M_B_E_R_
          P_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   t_h_e_ c_o_n_j_u_g_a_t_e_ o_f_ a_ c_o_m_p_l_e_x_ n_u_m_b_e_r_,_ o_r_ t_h_e_ n_u_m_b_e_r_ i_t_s_e_l_f_
          i_f_ a_ r_e_a_l_ n_u_m_b_e_r_._

     (_p_h_a_s_e_ <_e_x_p_r_>_)_                               G_E_T_ T_H_E_ P_H_A_S_E_ O_F_ A_ N_U_M_B_E_R_
          P_a_r_t_ o_f_ t_h_e_ m_a_t_h_ e_x_t_e_n_s_i_o_n_
          <_e_x_p_r_>_    t_h_e_ n_u_m_b_e_r_
          r_e_t_u_r_n_s_   t_h_e_  p_h_a_s_e_ a_n_g_l_e_,_ e_q_u_i_v_a_l_e_n_t_ t_o_ (_a_t_a_n_ (_i_m_a_g_p_a_r_t_ <_e_x_p_r_>_)_
                    (_r_e_a_l_p_a_r_t_ <_e_x_p_r_>_)_)_







     XLISP 2.1c               ARITHMETIC FUNCTIONS                  Page 46


     (< <n1> <n2>...)                                    TEST FOR LESS THAN
     (<= <n1> <n2>...)                       TEST FOR LESS THAN OR EQUAL TO
     (= <n1> <n2>...)                                     TEST FOR EQUAL TO
     (/= <n1> <n2>...)                                TEST FOR NOT EQUAL TO
     (>= <n1> <n2>...)                    TEST FOR GREATER THAN OR EQUAL TO
     (> <n1> <n2>...)                                 TEST FOR GREATER THAN
          <n1>      the first real number to compare
          <n2>      the second real number to compare
          returns   the result of comparing <n1> with <n2>...







     XLISP 2.1c             BITWISE LOGICAL FUNCTIONS               Page 47



     BITWISE LOGICAL FUNCTIONS

     (logand [<expr>...])             THE BITWISE AND OF A LIST OF INTEGERS
          W_i_t_h_ n_o_ a_r_g_u_m_e_n_t_s_ r_e_t_u_r_n_s_ i_d_e_n_t_i_t_y_ -_1_
          <expr>    the integers
          returns   the result of the and operation

     (logior [<expr>...])    THE BITWISE INCLUSIVE OR OF A LIST OF INTEGERS
          W_i_t_h_ n_o_ a_r_g_u_m_e_n_t_s_ r_e_t_u_r_n_s_ i_d_e_n_t_i_t_y_ 0_
          <expr>    the integers
          returns   the result of the inclusive or operation

     (logxor [<expr>...])    THE BITWISE EXCLUSIVE OR OF A LIST OF INTEGERS
          W_i_t_h_ n_o_ a_r_g_u_m_e_n_t_s_ r_e_t_u_r_n_s_ i_d_e_n_t_i_t_y_ 0_
          <expr>    the integers
          returns   the result of the exclusive or operation

     (lognot <expr>)                           THE BITWISE NOT OF A INTEGER
          <expr>    the integer
          returns   the bitwise inversion of integer

     (_l_o_g_t_e_s_t_ <_e_x_p_r_1_>_ <_e_x_p_r_2_>_)_             T_E_S_T_ B_I_T_W_I_S_E_ A_N_D_ O_F_ T_W_O_ I_N_T_E_G_E_R_S_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_1_>_   t_h_e_ f_i_r_s_t_ i_n_t_e_g_e_r_
          <_e_x_p_r_2_>_   t_h_e_ s_e_c_o_n_d_ i_n_t_e_g_e_r_
          r_e_t_u_r_n_s_   T_  i_f_ t_h_e_ r_e_s_u_l_t_ o_f_ t_h_e_ a_n_d_ o_p_e_r_a_t_i_o_n_ i_s_ n_o_n_-_z_e_r_o_,_ e_l_s_e_
                    N_I_L_







     XLISP 2.1c                 STRING FUNCTIONS                    Page 48



     STRING FUNCTIONS

     E_x_t_e_n_s_i_o_n_ b_e_y_o_n_d_ d_i_s_t_r_i_b_u_t_i_o_n_:_ f_u_n_c_t_i_o_n_s_ w_i_t_h_ n_a_m_e_s_  s_t_a_r_t_i_n_g_ "_s_t_r_i_n_g_"_
     w_i_l_l_ a_l_s_o_  a_c_c_e_p_t_ a_ s_y_m_b_o_l_,_ i_n_  w_h_i_c_h_ c_a_s_e_ t_h_e_ s_y_m_b_o_l_'_s_  p_r_i_n_t_ n_a_m_e_ i_s_
     u_s_e_d_._

     (string <expr>)              MAKE A STRING FROM AN INTEGER ASCII VALUE
          <expr>    an  integer (which  is first  converted into  its ASCII
                    character value), string, character, or symbol
          returns   the string representation of the argument

     (string-trim <bag> <str>)                   TRIM BOTH ENDS OF A STRING
          <bag>     a string containing characters to trim
          <str>     the string to trim
          returns   a trimed copy of the string

     (string-left-trim <bag> <str>)           TRIM THE LEFT END OF A STRING
          <bag>     a string containing characters to trim
          <str>     the string to trim
          returns   a trimed copy of the string

     (string-right-trim <bag> <str>)         TRIM THE RIGHT END OF A STRING
          <bag>     a string containing characters to trim
          <str>     the string to trim
          returns   a trimed copy of the string

     (string-upcase <str> &key :start :end)            CONVERT TO UPPERCASE
          <str>     the string
          :start    the starting offset
          :end      the ending offset + 1 o_r_ N_I_L_ f_o_r_ e_n_d_ o_f_ s_t_r_i_n_g_
          returns   a converted copy of the string

     (string-downcase <str> &key :start :end)          CONVERT TO LOWERCASE
          <str>     the string
          :start    the starting offset
          :end      the ending offset + 1 o_r_ N_I_L_ f_o_r_ e_n_d_ o_f_ s_t_r_i_n_g_
          returns   a converted copy of the string

     (nstring-upcase <str> &key :start :end)           CONVERT TO UPPERCASE
          <str>     the string
          :start    the starting offset
          :end      the ending offset + 1 o_r_ N_I_L_ f_o_r_ e_n_d_ o_f_ s_t_r_i_n_g_
          returns   the converted string (not a copy)

     (nstring-downcase <str> &key :start :end)         CONVERT TO LOWERCASE
          <str>     the string
          :start    the starting offset
          :end      the ending offset + 1 o_r_ N_I_L_ f_o_r_ e_n_d_ o_f_ s_t_r_i_n_g_
          returns   the converted string (not a copy)







     XLISP 2.1c                 STRING FUNCTIONS                    Page 49


     (strcat <expr>...)                                 CONCATENATE STRINGS
          M_a_c_r_o_ i_n_ i_n_i_t_._l_s_p_,_ t_o_ m_a_i_n_t_a_i_n_ c_o_m_p_a_t_i_b_i_l_i_t_y_ w_i_t_h_ d_i_s_t_r_i_b_u_t_i_o_n_._
          S_e_e_ "_c_o_n_c_a_t_e_n_a_t_e_"_._
          <expr>    the strings to concatenate
          returns   the result of concatenating the strings

     (string< <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string<= <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string= <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string/= <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string>= <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string> <str1> <str2> &key :start1 :end1 :start2 :end2)
          <str1>    the first string to compare
          <str2>    the second string to compare
          :start1   first substring starting offset
          :end1     first substring ending  offset +  1 o_r_ N_I_L_  f_o_r_ e_n_d_  o_f_
                    s_t_r_i_n_g_
          :start2   second substring starting offset
          :end2     second  substring ending offset +  1 o_r_ N_I_L_  f_o_r_ e_n_d_ o_f_
                    s_t_r_i_n_g_
          returns   string=: t if predicate is true, NIL otherwise
                    others:  If predicate  is true  then number  of initial
                    matching characters, else NIL
          Note: case is significant with these comparison functions.

     (string-lessp <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string-not-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string-equal <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string-not-equal <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string-not-lessp <str1> <str2> &key :start1 :end1 :start2 :end2)
     (string-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2)
          <str1>    the first string to compare
          <str2>    the second string to compare
          :start1   first substring starting offset
          :end1     first substring ending  offset +  1 o_r_ N_I_L_  f_o_r_ e_n_d_  o_f_
                    s_t_r_i_n_g_
          :start2   second substring starting offset
          :end2     second  substring ending offset +  1 o_r_ N_I_L_  f_o_r_ e_n_d_ o_f_
                    s_t_r_i_n_g_
          returns   string-equal: t if predicate is true, NIL otherwise
                    others:  If predicate  is true  then number  of initial
                    matching characters, else NIL
          Note: case is not significant with these comparison functions.







     XLISP 2.1c                CHARACTER FUNCTIONS                  Page 50



     CHARACTER FUNCTIONS

     (char <string> <index>)              EXTRACT A CHARACTER FROM A STRING
          <string>  the string
          <index>   the string index (zero relative)
          returns   the ascii code of the character

     (upper-case-p <chr>)                  IS THIS AN UPPER CASE CHARACTER?
          <chr>     the character
          returns   true if the character is upper case, NIL otherwise

     (lower-case-p <chr>)                   IS THIS A LOWER CASE CHARACTER?
          <chr>     the character
          returns   true if the character is lower case, NIL otherwise

     (both-case-p <chr>)     IS THIS AN ALPHABETIC (EITHER CASE) CHARACTER?
          <chr>     the character
          returns   true if the character is alphabetic, NIL otherwise

     (digit-char-p <chr>)                        IS THIS A DIGIT CHARACTER?
          <chr>     the character
          returns   the digit weight if character is a digit, NIL otherwise

     (char-code <chr>)                    GET THE ASCII CODE OF A CHARACTER
          <chr>     the character
          returns   the ASCII character code (integer,_ p_a_r_i_t_y_ b_i_t_ s_t_r_i_p_p_e_d_)

     (code-char <code>)        GET THE CHARACTER WITH A SPECFIED ASCII CODE
          <code>    the ASCII code (integer,_ r_a_n_g_e_ 0_-_1_2_7_)
          returns   the character with that code or NIL

     (char-upcase <chr>)                  CONVERT A CHARACTER TO UPPER CASE
          <chr>     the character
          returns   the upper case character

     (char-downcase <chr>)                CONVERT A CHARACTER TO LOWER CASE
          <chr>     the character
          returns   the lower case character

     (digit-char <n>)                     CONVERT A DIGIT WEIGHT TO A DIGIT
          <n>       the digit weight (integer)
          returns   the digit character or NIL

     (char-int <chr>)                     CONVERT A CHARACTER TO AN INTEGER
          <chr>     the character
          returns   the ASCII character code (_r_a_n_g_e_ 0_-_2_5_5_)_

     (int-char <int>)                     CONVERT AN INTEGER TO A CHARACTER
          <int>     the ASCII character code (_t_r_e_a_t_e_d_ m_o_d_u_l_o_ 2_5_6_)_
          returns   the character with that code







     XLISP 2.1c                CHARACTER FUNCTIONS                  Page 51


     (char< <chr1> <chr2>...)
     (char<= <chr1> <chr2>...)
     (char= <chr1> <chr2>...)
     (char/= <chr1> <chr2>...)
     (char>= <chr1> <chr2>...)
     (char> <chr1> <chr2>...)
          <chr1>    the first character to compare
          <chr2>    the second character(s) to compare
          returns   t if predicate is true, NIL otherwise
          Note: case is significant with these comparison functions.

     (char-lessp <chr1> <chr2>...)
     (char-not-greaterp <chr1> <chr2>...)
     (char-equal <chr1> <chr2>...)
     (char-not-equal <chr1> <chr2>...)
     (char-not-lessp <chr1> <chr2>...)
     (char-greaterp <chr1> <chr2>...)
          <chr1>    the first string to compare
          <chr2>    the second string(s) to compare
          returns   t if predicate is true, NIL otherwise
          Note: case is not significant with these comparison functions.







     XLISP 2.1c                STRUCTURE FUNCTIONS                  Page 52



     STRUCTURE FUNCTIONS

     XLISP provides  a  subset  of the  Common  Lisp  structure  definition
     facility.  No slot  options are  allowed, but  slots can  have default
     initialization expressions.

          (defstruct name <slot-desc>...)
     or
          (defstruct (name <option>...) <slot-desc>...)
                    fsubr
                    <name>              the structure name symbol (quoted)
                    <option>            option description (quoted)
                    <slot-desc>         slot descriptions (quoted)
                    returns             the structure name

     The recognized options are:

          (:conc-name name)
          (:include name [<slot-desc>...])

     Note that if :CONC-NAME appears, it should be before :INCLUDE.

     Each slot description takes the form:

          <name>
     or
          (<name> <defexpr>)

     If  the default initialization  expression is not  specified, the slot
     will be initialized  to NIL if  no keyword argument  is passed to  the
     creation function.

     DEFSTRUCT causes access functions to be  created for each of the slots
     and also arranges that SETF will work with those access functions. The
     access function  names are constructed  by taking the  structure name,
     appending  a  '-'  and then  appending  the  slot  name. This  can  be
     overridden by using the :CONC-NAME option.

     DEFSTRUCT also  makes a creation function  called MAKE-<structname>, a
     copy function called COPY-<structname> and a predicate function called
     <structname>-P. The creation function takes keyword arguments for each
     of  the slots. Structures can be created  using the #S( read macro, as
     well.

     The  property *struct-slots*  is added  to the  symbol that  names the
     structure. This property consists of an association list of slot names
     and  closures that evaluate to  the initial values  (NIL if no initial
     value expression).







     XLISP 2.1c                STRUCTURE FUNCTIONS                  Page 53


     For instance:

          (defstruct foo bar (gag 2))

     creates the following functions:

          (foo-bar <expr>)
          (setf (foo-bar <expr>) <value>)
          (foo-gag <expr>)
          (setf (foo-gag <expr>) <value>)
          (make-foo &key :bar :gag)
          (copy-foo <expr>)
          (foo-p <expr>)







     XLISP 2.1c                 OBJECT FUNCTIONS                    Page 54



     OBJECT FUNCTIONS

     T_h_i_s_  s_e_c_t_i_o_n_ i_s_ c_o_m_p_l_e_t_e_l_y_ n_e_w_._  N_o_t_e_ t_h_a_t_ t_h_e_  f_u_n_c_t_i_o_n_s_ p_r_o_v_i_d_e_d_ i_n_
     c_l_a_s_s_e_s_._l_s_p_ a_r_e_ u_s_e_f_u_l_ b_u_t_ n_o_t_ n_e_c_e_s_s_a_r_y_._

     Messages defined for Object and Class are listed starting on page 18.

     (send <object> <message> [<args>...])                   SEND A MESSAGE
          <object>  the object to receive the message
          <message> message sent to object
          <args>    arguments to method (if any)
          returns   the result of the method

     (send-super <message> [<args>])           SEND A MESSAGE TO SUPERCLASS
          valid only in method context
          <message> message sent to method's superclass
          <args>    arguments to method (if any)
          returns   the result of the method

     (defclass <sym> <ivars> [<cvars> [<super>]])        DEFINE A NEW CLASS
          defined in class.lsp as a macro
          <sym>     symbol whose value is  to be bound to the  class object
                    (quoted)
          <ivars>   list of instance variables (quoted). Instance variables
                    specified  either  as  <ivar>  or  (<ivar>  <init>)  to
                    specify non-NIL default initial value.
          <cvars>   list of class variables (quoted)
          <super>   superclass, or Object if absent.
          This function  sends :SET-PNAME  (defined in classes.lsp)  to the
          new class to set the class' print name instance variable.
          Methods defined for classes defined with defclass:
          (send <object> :<ivar>)
                    Returns the specified instance variable
          (send <object> :SET-IVAR <ivar> <value>)
                    Used to set an instance variable, typically with setf.
          (send <sym> :NEW {:<ivar> <init>})
                    Actually  definition  for  :ISNEW. Creates  new  object
                    initializing instance variables as specified in keyword
                    arguments, or  to their default if  keyword argument is
                    missing. Returns the object.

     (defmethod <class> <sym> <fargs> <expr> ...)       DEFINE A NEW METHOD
          defined in class.lsp as a macro
          <class>   Class which will respond to message
          <sym>     Message name (quoted)
          <fargs>   Formal  argument   list.  Leading  "self"   is  implied
                    (quoted)
          <expr>    Expressions constituting body of method (quoted)
          returns   the class object.







     XLISP 2.1c                 OBJECT FUNCTIONS                    Page 55


     (definst <class> <sym> [<args>...])       DEFINE A NEW GLOBAL INSTANCE
          defined in class.lsp as a macro
          <class>   Class of new object
          <sym>     Symbol whose value will be set to new object
          <args>    Arguments passed to :NEW  (typically initial values for
                    instance variables)







     XLISP 2.1c                PREDICATE FUNCTIONS                  Page 56



     PREDICATE FUNCTIONS

     (atom <expr>)                                         IS THIS AN ATOM?
          <expr>    the expression to check
          returns   t if the value is an atom, NIL otherwise

     (symbolp <expr>)                                     IS THIS A SYMBOL?
          <expr>    the expression to check
          returns   t if the expression is a symbol, NIL otherwise

     (numberp <expr>)                                     IS THIS A NUMBER?
          <expr>    the expression to check
          returns   t if the expression is a number, NIL otherwise

     (null <expr>)                                   IS THIS AN EMPTY LIST?
          <expr>    the list to check
          returns   t if the list is empty, NIL otherwise

     (not <expr>)                                            IS THIS FALSE?
          <expr>    the expression to check
          return    t if the value is NIL, NIL otherwise

     (listp <expr>)                                         IS THIS A LIST?
          <expr>    the expression to check
          returns   t if the value is a cons or NIL, NIL otherwise

     (endp <list>)                               IS THIS THE END OF A LIST?
          <list>    the list
          returns   t if the value is NIL, NIL otherwise

     (consp <expr>)                               IS THIS A NON-EMPTY LIST?
          <expr>    the expression to check
          returns   t if the value is a cons, NIL otherwise

     (_c_o_n_s_t_a_n_t_p_ <_e_x_p_r_>_)_                                 I_S_ T_H_I_S_ A_ C_O_N_S_T_A_N_T_?_
          N_e_w_ f_u_n_c_t_i_o_n_ d_e_f_i_n_e_d_ a_s_ S_U_B_R_ o_r_ i_n_ i_n_i_t_._l_s_p_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ c_h_e_c_k_
          r_e_t_u_r_n_s_   t_ i_f_  t_h_e_ v_a_l_u_e_  i_s_ a_ c_o_n_s_t_a_n_t_  (_b_a_s_i_c_a_l_l_y_,_ w_o_u_l_d_  E_V_A_L_
                    <_e_x_p_r_>_   r_e_p_e_a_t_e_d_l_y_  r_e_t_u_r_n_   t_h_e_  s_a_m_e_   t_h_i_n_g_?_)_,_  N_I_L_
                    o_t_h_e_r_w_i_s_e_._

     (integerp <expr>)                                  IS THIS AN INTEGER?
          <expr>    the expression to check
          returns   t if the value is an integer, NIL otherwise

     (floatp <expr>)                                       IS THIS A FLOAT?
          <expr>    the expression to check
          returns   t if the value is a float, NIL otherwise







     XLISP 2.1c                PREDICATE FUNCTIONS                  Page 57


     (_c_o_m_p_l_e_x_p_ <_e_x_p_r_>_)_                            I_S_ T_H_I_S_ A_ C_O_M_P_L_E_X_ N_U_M_B_E_R_?_
          P_a_r_t_ o_f_ m_a_t_h_ e_x_t_e_n_s_i_o_n_._
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ c_h_e_c_k_
          r_e_t_u_r_n_s_   t_ i_f_ t_h_e_ v_a_l_u_e_ i_s_ a_ c_o_m_p_l_e_x_ n_u_m_b_e_r_,_ N_I_L_ o_t_h_e_r_w_i_s_e_

     (stringp <expr>)                                     IS THIS A STRING?
          <expr>    the expression to check
          returns   t if the value is a string, NIL otherwise

     (characterp <expr>)                               IS THIS A CHARACTER?
          <expr>    the expression to check
          returns   t if the value is a character, NIL otherwise

     (arrayp <expr>)                                      IS THIS AN ARRAY?
          <expr>    the expression to check
          returns   t if the value is an array, NIL otherwise

     (streamp <expr>)                                     IS THIS A STREAM?
          <expr>    the expression to check
          returns   t if the value is a stream, NIL otherwise

     (_o_p_e_n_-_s_t_r_e_a_m_-_p_ <_s_t_r_e_a_m_>_)_                               I_S_ S_T_R_E_A_M_ O_P_E_N_?_
          N_e_w_ f_u_n_c_t_i_o_n_
          <_s_t_r_e_a_m_>_  t_h_e_ s_t_r_e_a_m_
          r_e_t_u_r_n_s_   t_ i_f_ t_h_e_ s_t_r_e_a_m_ i_s_ o_p_e_n_,_ N_I_L_ o_t_h_e_r_w_i_s_e_

     (_i_n_p_u_t_-_s_t_r_e_a_m_-_p_ <_s_t_r_e_a_m_>_)_                          I_S_ S_T_R_E_A_M_ R_E_A_D_A_B_L_E_?_
          N_e_w_ f_u_n_c_t_i_o_n_
          <_s_t_r_e_a_m_>_  t_h_e_ s_t_r_e_a_m_
          r_e_t_u_r_n_s_   t_ i_f_ s_t_r_e_a_m_ i_s_ r_e_a_d_a_b_l_e_,_ N_I_L_ o_t_h_e_r_w_i_s_e_

     (_o_u_t_p_u_t_-_s_t_r_e_a_m_-_p_ <_s_t_r_e_a_m_>_)_                         I_S_ S_T_R_E_A_M_ W_R_I_T_A_B_L_E_?_
          N_e_w_ F_u_n_c_t_i_o_n_
          <_s_t_r_e_a_m_>_  t_h_e_ s_t_r_e_a_m_
          r_e_t_u_r_n_s_   t_ i_f_ s_t_r_e_a_m_ i_s_ w_r_i_t_a_b_l_e_,_ N_I_L_ o_t_h_e_r_w_i_s_e_

     (objectp <expr>)                                    IS THIS AN OBJECT?
          <expr>    the expression to check
          returns   t if the value is an object, NIL otherwise

     (classp <expr>)                                IS THIS A CLASS OBJECT?
          <expr>    the expression to check
          returns   t if the value is a class object, NIL otherwise

     (boundp <sym>)                        IS A VALUE BOUND TO THIS SYMBOL?
          <sym>     the symbol
          returns   t if a value is bound to the symbol, NIL otherwise







     XLISP 2.1c                PREDICATE FUNCTIONS                  Page 58


     (fboundp <sym>)            IS A FUNCTIONAL VALUE BOUND TO THIS SYMBOL?
          <sym>     the symbol
          returns   t if a  functional value  is bound to  the symbol,  NIL
                    otherwise

     (_f_u_n_c_t_i_o_n_p_ <_s_y_m_>_)_                                  I_S_ T_H_I_S_ A_ F_U_N_C_T_I_O_N_?_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ c_h_e_c_k_
          r_e_t_u_r_n_s_   t_ i_f_  t_h_e_ v_a_l_u_e_ i_s_  a_ f_u_n_c_t_i_o_n_  -_-_ t_h_a_t_ i_s_,_  c_a_n_ i_t_  b_e_
                    a_p_p_l_i_e_d_ t_o_ a_r_g_u_m_e_n_t_s_._ T_h_i_s_ i_s_ t_r_u_e_ f_o_r_ a_n_y_ s_y_m_b_o_l_ (_e_v_e_n_
                    t_h_o_s_e_ w_i_t_h_  n_o_ f_u_n_c_t_i_o_n_  b_i_n_d_i_n_g_)_,_ l_i_s_t_ w_i_t_h_  c_a_r_ b_e_i_n_g_
                    l_a_m_b_d_a_,_ a_ c_l_o_s_u_r_e_,_ o_r_ s_u_b_r_._ O_t_h_e_r_w_i_s_e_ r_e_t_u_r_n_s_ N_I_L_._

     (minusp <expr>)                               IS THIS NUMBER NEGATIVE?
          <expr>    the number to test
          returns   t if the number is negative, NIL otherwise

     (zerop <expr>)                                    IS THIS NUMBER ZERO?
          <expr>    the number to test
          returns   t if the number is zero, NIL otherwise

     (plusp <expr>)                                IS THIS NUMBER POSITIVE?
          <expr>    the number to test
          returns   t if the number is positive, NIL otherwise

     (evenp <expr>)                                   IS THIS INTEGER EVEN?
          <expr>    the integer to test
          returns   t if the integer is even, NIL otherwise

     (oddp <expr>)                                     IS THIS INTEGER ODD?
          <expr>    the integer to test
          returns   t if the integer is odd, NIL otherwise

     (_s_u_b_s_e_t_p_ <_l_i_s_t_1_>_ <_l_i_s_t_2_>_ &_k_e_y_ :_t_e_s_t_ :_t_e_s_t_-_n_o_t_ :_k_e_y_)_   I_S_ S_E_T_ A_ S_U_B_S_E_T_?_
          A_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_l_i_s_t_1_>_   t_h_e_ f_i_r_s_t_ l_i_s_t_
          <_l_i_s_t_2_>_   t_h_e_ s_e_c_o_n_d_ l_i_s_t_
          :_t_e_s_t_     t_e_s_t_ f_u_n_c_t_i_o_n_ (_d_e_f_a_u_l_t_s_ t_o_ e_q_l_)_
          :_t_e_s_t_-_n_o_t_ t_e_s_t_ f_u_n_c_t_i_o_n_ (_s_e_n_s_e_ i_n_v_e_r_t_e_d_)_
          :_k_e_y_      f_u_n_c_t_i_o_n_ t_o_ a_p_p_l_y_ t_o_  t_e_s_t_ f_u_n_c_t_i_o_n_ a_r_g_u_m_e_n_t_s_ (_d_e_f_a_u_l_t_s_
                    t_o_ i_d_e_n_t_i_t_y_)_
          r_e_t_u_r_n_s_   t_ i_f_ e_v_e_r_y_  e_l_e_m_e_n_t_ o_f_ t_h_e_ f_i_r_s_t_ l_i_s_t_  i_s_ i_n_ t_h_e_ s_e_c_o_n_d_
                    l_i_s_t_,_ N_I_L_ o_t_h_e_r_w_i_s_e_







     XLISP 2.1c                PREDICATE FUNCTIONS                  Page 59


     (eq <expr1> <expr2>)                        ARE THE EXPRESSIONS EQUAL?
     (eql <expr1> <expr2>)
     (equal <expr1> <expr2>)
     (_e_q_u_a_l_p_ <_e_x_p_r_1_>_ <_e_x_p_r_2_>_)_
          e_q_u_a_l_p_ d_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_
          <expr1>   the first expression
          <expr2>   the second expression
          returns   t if  equal, NIL otherwise. Each  is progressively more
                    liberal in what is "equal":
                    eq:   identical  pointers  --  works  with  characters,
                              symbols, and arbitrarily small integers
                    eql: works with all  numbers, if same type (see  also =
                    on page 46)
                    equal: lists and strings
                    equalp:  case  insensitive  characters  (and  strings),
                              numbers of differing types, arrays (which can
                              be equalp to string containing same elements)

     (_t_y_p_e_p_ <_e_x_p_r_>_ <_t_y_p_e_>_)_                        I_S_ T_H_I_S_ A_ S_P_E_C_I_F_I_E_D_ T_Y_P_E_?_
          A_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ t_e_s_t_
          <_t_y_p_e_>_    t_h_e_ t_y_p_e_ s_p_e_c_i_f_i_e_r_._  S_y_m_b_o_l_s_ c_a_n_ e_i_t_h_e_r_ b_e_ o_n_e_ o_f_ t_h_o_s_e_
                    l_i_s_t_e_d_ u_n_d_e_r_ t_y_p_e_-_o_f_ (_o_n_ p_a_g_e_ 8_0_)_ o_r_ o_n_e_ o_f_:_
                    A_T_O_M_      a_n_y_ a_t_o_m_
                    N_U_L_L_      n_i_l_
                    S_T_R_E_A_M_    a_n_y_ s_t_r_e_a_m_
                    N_U_M_B_E_R_    a_n_y_ n_u_m_b_e_r_ t_y_p_e_
                    S_T_R_U_C_T_    a_n_y_ s_t_r_u_c_t_u_r_e_ (_e_x_c_e_p_t_ h_a_s_h_-_t_a_b_l_e_)_
                    F_U_N_C_T_I_O_N_  a_n_y_ f_u_n_c_t_i_o_n_,_  a_s_ d_e_f_i_n_e_d_ b_y_  f_u_n_c_t_i_o_n_p_ (_p_a_g_e_
                              5_8_)_
                    T_h_e_  s_p_e_c_i_f_e_r_ c_a_n_ a_l_s_o_ b_e_ a_ f_o_r_m_ (_w_h_i_c_h_ c_a_n_ b_e_ n_e_s_t_e_d_)_._
                    A_l_l_ f_o_r_m_ e_l_e_m_e_n_t_s_ a_r_e_ q_u_o_t_e_d_._ V_a_l_i_d_ f_o_r_m_ c_a_r_s_:_
                    O_R_        a_n_y_ o_f_ t_h_e_ c_d_r_ t_y_p_e_ s_p_e_c_i_f_i_e_r_s_ m_u_s_t_ b_e_ t_r_u_e_
                    A_N_D_       a_l_l_ o_f_ t_h_e_ c_d_r_ t_y_p_e_ s_p_e_c_i_f_i_e_r_s_ m_u_s_t_ b_e_ t_r_u_e_
                    N_O_T_       t_h_e_ s_i_n_g_l_e_ c_d_r_ t_y_p_e_ s_p_e_c_i_f_i_e_r_ m_u_s_t_ b_e_ f_a_l_s_e_
                    S_A_T_I_S_F_I_E_S_ t_h_e_  r_e_s_u_l_t_  o_f_  a_p_p_l_y_i_n_g_  t_h_e_  c_d_r_ p_r_e_d_i_c_a_t_e_
                              f_u_n_c_t_i_o_n_ t_o_ <_e_x_p_r_>_
                    M_E_M_B_E_R_    <_e_x_p_r_>_ m_u_s_t_ b_e_ e_q_l_ t_o_ o_n_e_ o_f_ t_h_e_ c_d_r_ v_a_l_u_e_s_
                    O_B_J_E_C_T_    <_e_x_p_r_>_ m_u_s_t_ b_e_ a_n_ o_b_j_e_c_t_,_ o_f_  c_l_a_s_s_ s_p_e_c_i_f_i_e_d_
                              b_y_ t_h_e_ s_i_n_g_l_e_ c_d_r_ v_a_l_u_e_._ T_h_e_ c_d_r_ v_a_l_u_e_ c_a_n_ b_e_
                              a_ s_y_m_b_o_l_ w_h_i_c_h_ m_u_s_t_ e_v_a_l_u_a_t_e_ t_o_ a_ c_l_a_s_s_._
                    N_o_t_e_  t_h_a_t_ N_I_L_  i_s_ c_o_n_s_i_d_e_r_e_d_  t_o_ b_e_  o_f_ t_y_p_e_  L_I_S_T_ a_n_d_
                    S_Y_M_B_O_L_  (_b_u_t_ n_o_t_ C_O_N_S_)_,_ a_l_l_ C_O_N_S_ c_e_l_l_s_ a_r_e_ a_l_s_o_ o_f_ t_y_p_e_
                    L_I_S_T_,_ e_v_e_r_y_t_h_i_n_g_ i_s_ o_f_  t_y_p_e_ T_,_ a_n_d_ n_o_t_h_i_n_g_ i_s_  o_f_ t_y_p_e_
                    N_I_L_._
          r_e_t_u_r_n_s_   t_ i_f_ <_e_x_p_r_>_ i_s_ o_f_ t_y_p_e_ <_t_y_p_e_>_,_ N_I_L_ o_t_h_e_r_w_i_s_e_._







     XLISP 2.1c                CONTROL CONSTRUCTS                   Page 60



     CONTROL CONSTRUCTS

     (cond <pair>...)                                EVALUATE CONDITIONALLY
          fsubr
          <pair>    pair consisting of:
                    (<pred> <expr>...)
                    where
                    <pred>    is a predicate expression
                    <expr>    evaluated if the predicate is not NIL
          returns   the value  of the  first expression whose  predicate is
                    not NIL

     (and <expr>...)               THE LOGICAL AND OF A LIST OF EXPRESSIONS
          fsubr
          <expr>    the expressions to be ANDed
          returns   NIL if  any expression evaluates to  NIL, otherwise the
                    value of the last expression (evaluation of expressions
                    stops after the first expression that evaluates to NIL)

     (or <expr>...)                 THE LOGICAL OR OF A LIST OF EXPRESSIONS
          fsubr
          <expr>    the expressions to be ORed
          returns   NIL if  all expressions evaluate to  NIL, otherwise the
                    value  of the first  non-NIL expression  (evaluation of
                    expressions stops after the  first expression that does
                    not evaluate to NIL)

     (if <texpr> <expr1> [<expr2>])      EVALUATE EXPRESSIONS CONDITIONALLY
          fsubr
          <texpr>   the test expression
          <expr1>   the expression to be evaluated if texpr is non-NIL
          <expr2>   the expression to be evaluated if texpr is NIL
          returns   the value of the selected expression

     (when <texpr> <expr>...)        EVALUATE ONLY WHEN A CONDITION IS TRUE
          fsubr
          <texpr>   the test expression
          <expr>    the expression(s) to be evaluted if texpr is non-NIL
          returns   the value of the last expression or NIL

     (unless <texpr> <expr>...)     EVALUATE ONLY WHEN A CONDITION IS FALSE
          fsubr
          <texpr>   the test expression
          <expr>    the expression(s) to be evaluated if texpr is NIL
          returns   the value of the last expression or NIL







     XLISP 2.1c                CONTROL CONSTRUCTS                   Page 61


     (case <expr> <case>...[(t <expr>)])                     SELECT BY CASE
          fsubr
          <expr>    the selection expression
          <case>    pair consisting of:
                    (<value> <expr>...)
                    where:
                    <value>   is  a   single  expression   or  a   list  of
                              expressions (unevaluated)
                    <expr>    are  expressions  to  execute  if   the  case
                              matches
          (t <expr>)          default case (no previous matching)
          returns   the value of the last expression of the matching case

     (let (<binding>...) <expr>...)                   CREATE LOCAL BINDINGS
     (let* (<binding>...) <expr>...)            LET WITH SEQUENTIAL BINDING
          fsubr
          <binding> the variable bindings each of which is either:
                    1)        a symbol (which is initialized to NIL)
                    2)        a list whose car  is a symbol and  whose cadr
                              is an initialization expression
          <expr>    the expressions to be evaluated
          returns   the value of the last expression

     (flet (<binding>...) <expr>...)                 CREATE LOCAL FUNCTIONS
     (labels (<binding>...) <expr>...)        FLET WITH RECURSIVE FUNCTIONS
     (macrolet (<binding>...) <expr>...)                CREATE LOCAL MACROS
          fsubr
          <binding> the function bindings each of which is:
                    (<sym> <fargs> <expr>...)
                    where:
                    <sym>     the function/macro name
                    <fargs>   formal argument list (lambda list)
                    <expr>    expressions  constituting  the  body  of  the
                              function/macro
          <expr>    the expressions to be evaluated
          returns   the value of the last expression

     (catch <sym> <expr>...)          EVALUATE EXPRESSIONS AND CATCH THROWS
          fsubr
          <sym>     the catch tag
          <expr>    expressions to evaluate
          returns   the value of the last expression the throw expression

     (throw <sym> [<expr>])                                THROW TO A CATCH
          fsubr
          <sym>     the catch tag
          <expr>    the value for the catch to return (defaults to NIL)
          returns   never returns







     XLISP 2.1c                CONTROL CONSTRUCTS                   Page 62


     (unwind-protect <expr> <cexpr>...)  PROTECT EVALUATION OF AN EXPRESSION
          fsubr
          <expr>    the expression to protect
          <cexpr>   the cleanup expressions
          returns   the value of the expression
          Note:     unwind-protect  guarantees  to   execute  the   cleanup
          expressions even if a non-local exit terminates the evaluation of
          the protected expression







     XLISP 2.1c                LOOPING CONSTRUCTS                   Page 63



     LOOPING CONSTRUCTS

     (loop <expr>...)                                    BASIC LOOPING FORM
          fsubr
          <expr>    the body of the loop
          returns   never returns (must use non-local exit, such as RETURN)

     (do (<binding>...) (<texpr> <rexpr>...) <expr>...)GENERAL LOOPING FORM
     (do* (<binding>...) (<texpr> <rexpr>...) <expr>...)
          fsubr. do binds simultaneously, do* binds sequentially
          <binding> the variable bindings each of which is either:
                    1)        a symbol (which is initialized to NIL)
                    2)        a list of the form: (<sym> <init> [<step>])
                    where:
                              <sym>     is the symbol to bind
                              <init>    the initial value of the symbol
                              <step>    a step expression
          <texpr>   the termination test expression
          <rexpr>   result expressions (the default is NIL)
          <expr>    the body of the loop (treated like an implicit prog)
          returns   the value of the last result expression

     (dolist (<sym> <expr> [<rexpr>]) <expr>...)        LOOP THROUGH A LIST
          fsubr
          <sym>     the symbol to bind to each list element
          <expr>    the list expression
          <rexpr>   the result expression (the default is NIL)
          <expr>    the body of the loop (treated like an implicit prog)
          returns   the result expression

     (dotimes (<sym> <expr> [<rexpr>]) <expr>...)     LOOP FROM ZERO TO N-1
          fsubr
          <sym>     the symbol to bind to each value from 0 to n-1
          <expr>    the number of times to loop
          <rexpr>   the result expression (the default is NIL)
          <expr>    the body of the loop (treated like an implicit prog)
          returns   the result expression







     XLISP 2.1c                THE PROGRAM FEATURE                  Page 64



     THE PROGRAM FEATURE

     (prog (<binding>...) <expr>...)                    THE PROGRAM FEATURE
     (prog* (<binding>...) <expr>...)          PROG WITH SEQUENTIAL BINDING
          fsubr -- equivalent to (let () (block NIL (tagbody ...)))
          <binding> the variable bindings each of which is either:
                    1)        a symbol (which is initialized to NIL)
                    2)        a list whose  car is a symbol  and whose cadr
                              is an initialization expression
          <expr>    expressions to evaluate or tags (symbols)
          returns   NIL or the argument passed to the return function

     (block <name> <expr>...)                                   NAMED BLOCK
          fsubr
          <name>    the block name (quoted symbol)
          <expr>    the block body
          returns   the value of the last expression

     (return [<expr>])             CAUSE A PROG CONSTRUCT TO RETURN A VALUE
          fsubr
          <expr>    the value (defaults to NIL)
          returns   never returns

     (return-from <name> [<value>])   RETURN FROM A NAMED BLOCK OR FUNCTION
          fsubr. In xlisp, the names are dynamically scoped.
          <name>    the block or function name  (quoted symbol). If name is
                    NIL, use function RETURN.
          <value>   the value to return (defaults to NIL)
          returns   never returns

     (tagbody <expr>...)                                  BLOCK WITH LABELS
          fsubr
          <expr>    expression(s) to evaluate or tags (symbols)
          returns   NIL

     (go <sym>)                                GO TO A TAG WITHIN A TAGBODY
          fsubr. In xlisp, tags are dynamically scoped.
          <sym>     the tag (quoted)
          returns   never returns

     (progv <slist> <vlist> <expr>...)             DYNAMICALLY BIND SYMBOLS
          fsubr
          <slist>   list of symbols (evaluated)
          <vlist>   list of values to bind to the symbols (evaluated)
          <expr>    expression(s) to evaluate
          returns   the value of the last expression







     XLISP 2.1c                THE PROGRAM FEATURE                  Page 65


     (prog1 <expr1> <expr>...)             EXECUTE EXPRESSIONS SEQUENTIALLY
          fsubr
          <expr1>   the first expression to evaluate
          <expr>    the remaining expressions to evaluate
          returns   the value of the first expression

     (prog2 <expr1> <expr2> <expr>...)     EXECUTE EXPRESSIONS SEQUENTIALLY
          fsubr
          <expr1>   the first expression to evaluate
          <expr2>   the second expression to evaluate
          <expr>    the remaining expressions to evaluate
          returns   the value of the second expression

     (progn <expr>...)                     EXECUTE EXPRESSIONS SEQUENTIALLY
          fsubr
          <expr>    the expressions to evaluate
          returns   the value of the last expression (or NIL)







     XLISP 2.1c              INPUT/OUTPUT FUNCTIONS                 Page 66



     INPUT/OUTPUT FUNCTIONS

     N_o_t_e_  t_h_a_t_ w_h_e_n_ p_r_i_n_t_i_n_g_ o_b_j_e_c_t_s_,_  p_r_i_n_t_i_n_g_ i_s_ a_c_c_o_m_p_l_i_s_h_e_d_ b_y_ s_e_n_d_i_n_g_
     t_h_e_  m_e_s_s_a_g_e_ :_p_r_i_n_1_  t_o_ t_h_e_  o_b_j_e_c_t_  (_t_h_i_s_ i_s_  a_  m_o_d_i_f_i_c_a_t_i_o_n_ o_f_  t_h_e_
     d_i_s_t_r_i_b_u_t_i_o_n_)_._

     (read [<stream> [<eof> [<rflag>]]])                 READ AN EXPRESSION
          <stream>  the input stream (default, o_r_ N_I_L_,_ is *standard-input*,_
                    T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          <eof>     the value to return on end of file (default is NIL)
          <rflag>   recursive read flag. The value is ignored
          returns   the expression read

     (set-macro-character <ch> <fcn> [ T ])               MODIFY READ TABLE
          defined in init.lsp
          <ch>      character to define
          <fcn>     function to bind to character (see page 13)
          T         if TMACRO rather than NMACRO

     (get-macro-character <ch>)                          EXAMINE READ TABLE
          defined in init.lsp
          <ch>      character
          returns   function bound to character

     (print <expr> [<stream>])            PRINT AN EXPRESSION ON A NEW LINE
          The  expression is  printed  using prin1,  then  current line  is
          terminated (Note: this is backwards from Common Lisp).
          <expr>    the expression to be printed
          <stream>  the    output    stream    (default,_    o_r_    N_I_L_,_   is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the expression

     (prin1 <expr> [<stream>])                          PRINT AN EXPRESSION
          symbols,  cons cells  (without  circularities), arrays,  strings,
          numbers,  and  characters  are  printed  in  a  format  generally
          acceptable to the read  function. Readability can be  affected by
          the global formatting variables. *print-level* and *print-length*
          affect the printing of lists and arrays, *integer-format* affects
          the printing of integers,  *float-format* affects the printing of
          floats, and *print-case* affects the printing of symbols.
          <expr>    the expression to be printed
          <stream>  the    output   stream    (default,_    o_r_    N_I_L_,_    is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the expression







     XLISP 2.1c              INPUT/OUTPUT FUNCTIONS                 Page 67


     (princ <expr> [<stream>])          PRINT AN EXPRESSION WITHOUT QUOTING
          Like PRIN1 except  symbols (including  uninterned), strings,  and
          characters  are  printed exactly  as  stored,  without using  any
          quoting mechanisms. *print-case* is ignored.
          <expr>    the expressions to be printed
          <stream>  the    output    stream    (default,_    o_r_    N_I_L_,_   is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the expression

     (pprint <expr> [<stream>])                  PRETTY PRINT AN EXPRESSION
          Uses prin1 for printing.
          <expr>    the expressions to be printed
          <stream>  the    output   stream    (default,_    o_r_    N_I_L_,_    is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the expression

     (terpri [<stream>])                   TERMINATE THE CURRENT PRINT LINE
          <stream>  the    output    stream    (default,_    o_r_    N_I_L_,_   is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   NIL

     (_f_r_e_s_h_-_l_i_n_e_ [_<_s_t_r_e_a_m_>_]_)_                               S_T_A_R_T_ A_ N_E_W_ L_I_N_E_
          N_o_t_e_:_ a_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_s_t_r_e_a_m_>_  t_h_e_    o_u_t_p_u_t_    s_t_r_e_a_m_    (_d_e_f_a_u_l_t_,_    o_r_    N_I_L_,_   i_s_
                    *_s_t_a_n_d_a_r_d_-_o_u_t_p_u_t_*_,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)_
          r_e_t_u_r_n_s_   t_  i_f_ a_  n_e_w_ l_i_s_t_  w_a_s_ s_t_a_r_t_e_d_,_ N_I_L_  i_f_ a_l_r_e_a_d_y_  a_t_ t_h_e_
                    s_t_a_r_t_ o_f_ a_ l_i_n_e_._

     (flatsize <expr>)         LENGTH OF PRINTED REPRESENTATION USING PRIN1
          <expr>    the expression
          returns   the length

     (flatc <expr>)            LENGTH OF PRINTED REPRESENTATION USING PRINC
          <expr>    the expression
          returns   the length

     (_y_-_o_r_-_n_-_p_ [_<_f_m_t_>_ [_<_a_r_g_>_._._._]_]_)_                 A_S_K_ A_ Y_E_S_ O_R_ N_O_ Q_U_E_S_T_I_O_N_
          d_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_._ U_s_e_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_ s_t_r_e_a_m_ f_o_r_ i_n_t_e_r_a_c_t_i_o_n_._
          <_f_m_t_>_     o_p_t_i_o_n_a_l_ f_o_r_m_a_t_ s_t_r_i_n_g_ f_o_r_ q_u_e_s_t_i_o_n_ (_s_e_e_ p_a_g_e_ 6_8_)_
          <_a_r_g_>_     a_r_g_u_m_e_n_t_s_,_ i_f_ a_n_y_,_ f_o_r_ f_o_r_m_a_t_ s_t_r_i_n_g_
          r_e_t_u_r_n_s_   T_ f_o_r_ y_e_s_,_ N_I_L_ f_o_r_ n_o_._







     XLISP 2.1c                THE FORMAT FUNCTION                  Page 68



     THE FORMAT FUNCTION

     (format <stream> <fmt> [<arg>...])                 DO FORMATTED OUTPUT
          <stream>  the output stream (T is *standard-output*)
          <fmt>     the format string
          <arg>     the format arguments
          returns   output string if <stream> is NIL, NIL otherwise

     The  format  string  can  contain  characters that  should  be  copied
     directly  to  the output  and  formatting  directives. The  formatting
     directives are:

          ~A o_r_ ~_a_  print next argument using princ
          ~S o_r_ ~_s_  print next argument using prin1
          ~_D_ o_r_ ~_d_  p_r_i_n_t_ n_e_x_t_ a_r_g_u_m_e_n_t_ i_n_t_e_g_e_r_
          ~_E_ o_r_ ~_e_  p_r_i_n_t_ n_e_x_t_ a_r_g_u_m_e_n_t_ i_n_ e_x_p_o_n_e_n_t_i_a_l_ f_o_r_m_
          ~_F_ o_r_ ~_f_  p_r_i_n_t_ n_e_x_t_ a_r_g_u_m_e_n_t_ i_n_ f_i_x_e_d_ p_o_i_n_t_ f_o_r_m_
          ~_G_ o_r_ ~_g_  p_r_i_n_t_ n_e_x_t_ a_r_g_u_m_e_n_t_ u_s_i_n_g_ e_i_t_h_e_r_ ~_E_  o_r_ ~_F_ d_e_p_e_n_d_i_n_g_ o_n_
          m_a_g_n_i_t_u_d_e_
          ~%        start a new line
          ~_&_        s_t_a_r_t_ a_ n_e_w_ l_i_n_e_ i_f_ n_o_t_ o_n_ a_ n_e_w_ l_i_n_e_
          ~_t_ o_r_ ~_T_  g_o_ t_o_ a_ s_p_e_c_i_f_i_e_d_ c_o_l_u_m_n_
          ~~        print a tilde character
          ~_\_n_       i_g_n_o_r_e_ r_e_t_u_r_n_ a_n_d_ f_o_l_l_o_w_i_n_g_ w_h_i_t_e_s_p_a_c_e_

     I_f_ X_L_I_S_P_ i_s_ c_o_m_p_i_l_e_d_  w_i_t_h_ E_N_H_F_O_R_M_A_T_ d_e_f_i_n_e_d_,_ t_h_e_n_ ~_\_n_ ~_D_  ~_E_ ~_F_ ~_G_ ~_T_
     a_n_d_  ~_&_ a_r_e_  d_e_f_i_n_e_d_ a_n_d_  t_h_e_ f_o_r_m_a_t_  d_i_r_e_c_t_i_v_e_s_ c_a_n_  c_o_n_t_a_i_n_ o_p_t_i_o_n_a_l_
     p_r_e_f_i_x_ a_n_d_ o_p_t_i_o_n_a_l_  c_o_l_o_n_ (_:_)_  o_r_ a_t_-_s_i_g_n_ (_@_)_  m_o_d_i_f_i_e_r_s_ b_e_t_w_e_e_n_  t_h_e_
     t_i_l_d_e_  a_n_d_  d_i_r_e_c_t_i_v_e_   c_h_a_r_a_c_t_e_r_._  P_r_e_f_i_x_  c_h_a_r_a_c_t_e_r_s_  a_r_e_   u_n_s_i_g_n_e_d_
     i_n_t_e_g_e_r_s_,_ o_r_ t_h_e_ c_h_a_r_a_c_t_e_r_  '_v_'_ t_o_ i_n_d_i_c_a_t_e_  t_h_e_ n_u_m_b_e_r_ i_s_ t_a_k_e_n_  f_r_o_m_
     t_h_e_  n_e_x_t_  a_r_g_u_m_e_n_t_,_  o_r_  a_ s_i_n_g_l_e_  q_u_o_t_e_  (_'_)_  f_o_l_l_o_w_e_d_  b_y_ a_  s_i_n_g_l_e_
     c_h_a_r_a_c_t_e_r_ f_o_r_ t_h_o_s_e_ p_a_r_a_m_e_t_e_r_s_ t_h_a_t_ s_h_o_u_l_d_ b_e_ a_ s_i_n_g_l_e_ c_h_a_r_a_c_t_e_r_._

     F_o_r_ ~_A_ a_n_d_ ~_S_ t_h_e_ f_u_l_l_ f_o_r_m_ i_s_:_

          ~_m_i_n_c_o_l_,_c_o_l_i_n_c_,_m_i_n_p_a_d_,_p_a_d_c_h_a_r_:_@_A_        (_o_r_ S_)_

     I_f_ :_ i_s_ g_i_v_e_n_,_ N_I_L_ w_i_l_l_ p_r_i_n_t_ a_s_ "_(_)_"_ r_a_t_h_e_r_ t_h_a_n_ "_N_I_L_"_._ T_h_e_ s_t_r_i_n_g_ i_s_
     p_a_d_d_e_d_ o_n_ t_h_e_  r_i_g_h_t_ (_o_r_ l_e_f_t_,_ i_f_  @_ i_s_ g_i_v_e_n_)_ w_i_t_h_  a_t_ l_e_a_s_t_ "_m_i_n_p_a_d_"_
     c_o_p_i_e_s_ o_f_ t_h_e_ "_p_a_d_c_h_a_r_"_._ P_a_d_d_i_n_g_ c_h_a_r_a_c_t_e_r_s_ a_r_e_ t_h_e_n_ i_n_s_e_r_t_e_d_ "_c_o_l_i_n_c_"_
     c_h_a_r_a_c_t_e_r_s_ a_t_ a_ t_i_m_e_ u_n_t_i_l_  t_h_e_ t_o_t_a_l_ w_i_d_t_h_ i_s_ a_t_ l_e_a_s_t_  "_m_i_n_c_o_l_"_._ T_h_e_
     d_e_f_a_u_l_t_s_ a_r_e_  0_ f_o_r_ m_i_n_c_o_l_ a_n_d_  m_i_n_p_a_d_,_ 1_ f_o_r_ c_o_l_i_n_c_,_  a_n_d_ #_\_s_p_a_c_e_ f_o_r_
     p_a_d_c_h_a_r_._ F_o_r_ e_x_a_m_p_l_e_:_

          ~_1_5_,_,_2_,_'_._@_A_

     T_h_e_ o_u_t_p_u_t_  i_s_ p_a_d_d_e_d_ o_n_  t_h_e_ l_e_f_t_ w_i_t_h_ a_t_  l_e_a_s_t_ 2_ p_e_r_i_o_d_s_  u_n_t_i_l_ t_h_e_
     o_u_t_p_u_t_ i_s_ a_t_ l_e_a_s_t_ 1_5_ c_h_a_r_a_c_t_e_r_s_ w_i_d_e_._







     XLISP 2.1c                THE FORMAT FUNCTION                  Page 69


     F_o_r_ ~_D_ t_h_e_ f_u_l_l_ f_o_r_m_ i_s_:_

          ~_m_i_n_c_o_l_,_p_a_d_c_h_a_r_@_D_

     I_f_ t_h_e_ a_r_g_u_m_e_n_t_  i_s_ n_o_t_ a_ F_I_X_N_U_M_,_ t_h_e_n_ t_h_e_  f_o_r_m_a_t_ "_~_m_i_n_c_o_l_A_"_ i_s_ u_s_e_d_._
     I_f_ "_m_i_n_c_o_l_"_  i_s_ s_p_e_c_i_f_i_e_d_ t_h_e_n_ t_h_e_ n_u_m_b_e_r_ i_s_  p_a_d_d_e_d_ o_n_ t_h_e_ l_e_f_t_ t_o_ b_e_
     a_t_ l_e_a_s_t_ t_h_a_t_ m_a_n_y_ c_h_a_r_a_c_t_e_r_s_ l_o_n_g_ u_s_i_n_g_ "_p_a_d_c_h_a_r_"_._ "_p_a_d_c_h_a_r_"_ d_e_f_a_u_l_t_s_
     t_o_ #_\_s_p_a_c_e_._ I_f_ @_  i_s_ u_s_e_d_ a_n_d_  t_h_e_ v_a_l_u_e_ i_s_  p_o_s_i_t_i_v_e_,_ t_h_e_n_ a_  l_e_a_d_i_n_g_
     p_l_u_s_ s_i_g_n_ i_s_ p_r_i_n_t_e_d_ b_e_f_o_r_e_ t_h_e_ f_i_r_s_t_ d_i_g_i_t_._

     F_o_r_ ~_E_ ~_F_ a_n_d_ ~_G_ t_h_e_ f_u_l_l_ f_o_r_m_ i_s_:_

          ~_m_i_n_c_o_l_,_r_o_u_n_d_,_p_a_d_c_h_a_r_@_E_                 (_o_r_ F_ o_r_ G_)_

     (_T_h_i_s_ i_m_p_l_e_m_e_n_t_a_t_i_o_n_ i_s_ n_o_t_ C_o_m_m_o_n_  L_i_s_p_ c_o_m_p_a_t_i_b_l_e_._)_ I_f_ t_h_e_  a_r_g_u_m_e_n_t_
     i_s_  n_o_t_  a_   r_e_a_l_  n_u_m_b_e_r_   (_F_I_X_N_U_M_  o_r_  F_L_O_N_U_M_)_,_   t_h_e_n_  t_h_e_   f_o_r_m_a_t_
     "_~_m_i_n_c_o_l_,_p_a_d_c_h_a_r_D_"_ i_s_ u_s_e_d_._ T_h_e_ n_u_m_b_e_r_ i_s_ p_r_i_n_t_e_d_ u_s_i_n_g_ t_h_e_ C_ l_a_n_g_u_a_g_e_
     e_,_ f_,_ o_r_ g_ f_o_r_m_a_t_s_._ I_f_ t_h_e_ n_u_m_b_e_r_ c_o_u_l_d_ p_o_t_e_n_t_i_a_l_l_y_ t_a_k_e_ m_o_r_e_ t_h_a_n_ 1_0_0_
     d_i_g_i_t_s_ t_o_ p_r_i_n_t_,_ t_h_e_n_ F_  f_o_r_m_a_t_ i_s_ f_o_r_c_e_d_ t_o_ E_ f_o_r_m_a_t_,_ a_l_t_h_o_u_g_h_ s_o_m_e_ C_
     l_i_b_r_a_r_i_e_s_ w_i_l_l_  d_o_ t_h_i_s_  a_t_ a_  l_o_w_e_r_ n_u_m_b_e_r_ o_f_  d_i_g_i_t_s_._ I_f_  "_r_o_u_n_d_"_ i_s_
     s_p_e_c_i_f_i_e_d_,_  t_h_a_n_ t_h_a_t_  i_s_ t_h_e_  n_u_m_b_e_r_ o_f_  d_i_g_i_t_s_ t_o_  t_h_e_ r_i_g_h_t_  o_f_ t_h_e_
     d_e_c_i_m_a_l_  p_o_i_n_t_ t_h_a_t_ w_i_l_l_ b_e_ p_r_i_n_t_e_d_,_ o_t_h_e_r_w_i_s_e_ s_i_x_ d_i_g_i_t_s_ (_o_r_ w_h_a_t_e_v_e_r_
     i_s_ n_e_c_e_s_s_a_r_y_  i_n_ G_ f_o_r_m_a_t_)_ a_r_e_  p_r_i_n_t_e_d_._ I_n_ G_ f_o_r_m_a_t_,_  t_r_a_i_l_i_n_g_ z_e_r_o_e_s_
     a_r_e_  d_e_l_e_t_e_d_ a_n_d_ e_x_p_o_n_e_n_t_i_a_l_  n_o_t_a_t_i_o_n_ i_s_ u_s_e_d_ i_f_  t_h_e_ e_x_p_o_n_e_n_t_ o_f_ t_h_e_
     n_u_m_b_e_r_  i_s_  g_r_e_a_t_e_r_ t_h_a_n_  t_h_e_  p_r_e_c_i_s_i_o_n_ o_r_  l_e_s_s_  t_h_a_n_ -_4_._  I_f_  t_h_e_ @_
     m_o_d_i_f_i_e_r_  i_s_  u_s_e_d_,_ a_  l_e_a_d_i_n_g_ p_l_u_s_  s_i_g_n_  i_s_ p_r_i_n_t_e_d_  b_e_f_o_r_e_ p_o_s_i_t_i_v_e_
     v_a_l_u_e_s_._ I_f_  "_m_i_n_c_o_l_"_ i_s_ s_p_e_c_i_f_i_e_d_,_ t_h_e_ n_u_m_b_e_r_ i_s_ p_a_d_d_e_d_ o_n_ t_h_e_ l_e_f_t_ t_o_
     b_e_  a_t_  l_e_a_s_t_  "_m_i_n_c_o_l_"_  c_h_a_r_a_c_t_e_r_s_ l_o_n_g_  u_s_i_n_g_  "_p_a_d_c_h_a_r_"_._  "_p_a_d_c_h_a_r_"_
     d_e_f_a_u_l_t_s_ t_o_ #_\_s_p_a_c_e_._

     F_o_r_ ~_%_ a_n_d_ ~_~_,_ t_h_e_  f_u_l_l_ f_o_r_m_ i_s_ ~_n_%_ o_r_ ~_n_~_._ "_n_"_ c_o_p_i_e_s_ (_d_e_f_a_u_l_t_=_1_)_ o_f_
     t_h_e_ c_h_a_r_a_c_t_e_r_ a_r_e_ o_u_t_p_u_t_._

     F_o_r_  ~_&_,_ t_h_e_ f_u_l_l_ f_o_r_m_ i_s_ ~_n_&_._  ~_0_&_ d_o_e_s_ n_o_t_h_i_n_g_._ O_t_h_e_r_w_i_s_e_ e_n_o_u_g_h_ n_e_w_
     l_i_n_e_  c_h_a_r_a_c_t_e_r_s_  a_r_e_  e_m_i_t_e_d_  t_o_ m_o_v_e_  d_o_w_n_  t_o_  t_h_e_  "_n_"_t_h_  n_e_w_ l_i_n_e_
     (_d_e_f_a_u_l_t_=_1_)_._

     F_o_r_ ~_T_,_ t_h_e_ f_u_l_l_ f_o_r_m_ i_s_:_

          ~_c_o_u_n_t_,_t_a_b_w_i_d_t_h_@_T_

     T_h_e_ c_u_r_s_o_r_  i_s_ m_o_v_e_d_ t_o_ c_o_l_u_m_n_  "_c_o_u_n_t_"_ (_d_e_f_a_u_l_t_ 1_)_._ I_f_  t_h_e_ c_u_r_s_o_r_ i_s_
     i_n_i_t_i_a_l_l_y_ a_t_ c_o_u_n_t_ o_r_ b_e_y_o_n_d_,_ t_h_e_n_ t_h_e_ c_u_r_s_o_r_ i_s_ m_o_v_e_d_  f_o_r_w_a_r_d_ t_o_ t_h_e_
     n_e_x_t_ p_o_s_i_t_i_o_n_ t_h_a_t_  i_s_ a_  m_u_l_t_i_p_l_e_ o_f_ "_t_a_b_w_i_d_t_h_"_  (_d_e_f_a_u_l_t_ 1_)_  c_o_l_u_m_n_s_
     b_e_y_o_n_d_  c_o_u_n_t_._  W_h_e_n_  t_h_e_ @_  m_o_d_i_f_i_e_r_  i_s_  u_s_e_d_,_  t_h_e_n_ p_o_s_i_t_i_o_n_i_n_g_  i_s_
     r_e_l_a_t_i_v_e_._  "_c_o_u_n_t_"_  s_p_a_c_e_s_ a_r_e_  p_r_i_n_t_e_d_,_  t_h_e_n_  a_d_d_i_t_i_o_n_a_l_ s_p_a_c_e_s_  a_r_e_
     p_r_i_n_t_e_d_ t_o_ m_a_k_e_  t_h_e_ c_o_l_u_m_n_ n_u_m_b_e_r_  b_e_ a_ m_u_l_t_i_p_l_e_ o_f_  "_t_a_b_w_i_d_t_h_"_._ N_o_t_e_
     t_h_a_t_ c_o_l_u_m_n_ c_a_l_c_u_a_t_i_o_n_s_ w_i_l_l_  b_e_ i_n_c_o_r_r_e_c_t_ i_f_ A_S_C_I_I_ t_a_b_  c_h_a_r_a_c_t_e_r_s_ o_r_
     A_N_S_I_ c_u_r_s_o_r_ p_o_s_i_t_i_o_n_i_n_g_ s_e_q_u_e_n_c_e_s_ a_r_e_ u_s_e_d_._







     XLISP 2.1c                THE FORMAT FUNCTION                  Page 70


     F_o_r_  ~_\_n_,_ i_f_ t_h_e_ c_o_l_o_n_ m_o_d_i_f_i_e_r_ i_s_  u_s_e_d_,_ t_h_e_n_ t_h_e_ f_o_r_m_a_t_ d_i_r_e_c_t_i_v_e_ i_s_
     i_g_n_o_r_e_d_  (_a_l_l_o_w_i_n_g_  e_m_b_e_d_d_e_d_  r_e_t_u_r_n_s_   i_n_  t_h_e_  s_o_u_r_c_e_  f_o_r_  e_n_h_a_n_c_e_d_
     r_e_a_d_a_b_i_l_i_t_y_)_._  I_f_ t_h_e_ a_t_-_s_i_g_n_ m_o_d_i_f_i_e_r_ i_s_ u_s_e_d_,_ t_h_e_n_ a_ c_a_r_r_i_a_g_e_ r_e_t_u_r_n_
     i_s_ e_m_i_t_t_e_d_,_ a_n_d_ f_o_l_l_o_w_i_n_g_ w_h_i_t_e_s_p_a_c_e_ i_s_ i_g_n_o_r_e_d_._ 







     XLISP 2.1c                FILE I/O FUNCTIONS                   Page 71



     FILE I/O FUNCTIONS

     Note  that initially, when starting xlisp, there are six system stream
     symbols which  are associated with  three streams. *_T_E_R_M_I_N_A_L_-_I_O_*_  i_s_ a_
     s_p_e_c_i_a_l_ s_t_r_e_a_m_ t_h_a_t_  i_s_ b_o_u_n_d_ t_o_ t_h_e_ k_e_y_b_o_a_r_d_ a_n_d_  d_i_s_p_l_a_y_,_ a_n_d_ a_l_l_o_w_s_
     f_o_r_ i_n_t_e_r_a_c_t_i_v_e_  e_d_i_t_i_n_g_._ *STANDARD-INPUT* is bound  to standard input
     o_r_ t_o_ *_T_E_R_M_I_N_A_L_-_I_O_*_ i_f_  n_o_t_ r_e_d_i_r_e_c_t_e_d_. *STANDARD-OUTPUT* is bound  to
     standard output o_r_ t_o_  *_T_E_R_M_I_N_A_L_-_I_O_*_ i_f_ n_o_t_ r_e_d_i_r_e_c_t_e_d_. *ERROR-OUTPUT*
     (error message output), *TRACE-OUTPUT* (for TRACE and TIME functions),
     and  *DEBUG-IO*  (break  loop i/o,_  a_n_d_  m_e_s_s_a_g_e_s_)  are  all bound  to
     *_T_E_R_M_I_N_A_L_-_I_O_*_  (was   stderr).  Standard  input  and   output  can  be
     redirected on most systems.

     When the  transcript is active (either  -t on the command  line or the
     DRIBBLE  function), all characters that  would be sent  to the display
     via  *_T_E_R_M_I_N_A_L_-_I_O_*_ (_w_a_s_  s_t_d_e_r_r_  o_r_ s_t_d_o_u_t_)_  are  also placed  in  the
     transcript file.

     *_T_E_R_M_I_N_A_L_-_I_O_*_ s_h_o_u_l_d_ n_o_t_ b_e_ c_h_a_n_g_e_d_._ A_n_y_ o_t_h_e_r_ s_y_s_t_e_m_ s_t_r_e_a_m_s_ t_h_a_t_ a_r_e_
     c_h_a_n_g_e_d_ b_y_ a_n_ a_p_p_l_i_c_a_t_i_o_n_ s_h_o_u_l_d_ b_e_ r_e_s_t_o_r_e_d_ t_o_ t_h_e_i_r_ o_r_i_g_i_n_a_l_ v_a_l_u_e_s_._

     (read-char [<stream>])                  READ A CHARACTER FROM A STREAM
          <stream>  the input stream (default,_ o_r_ N_I_L_,_ is *standard-input*,_
                    T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the character or NIL at end of file

     (peek-char [<flag> [<stream>]])             PEEK AT THE NEXT CHARACTER
          <flag>    flag for skipping white space (default is NIL)
          <stream>  the input stream (default,_ o_r_ N_I_L_,_ is *standard-input*,_
                    T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the character or NIL at end of file

     (write-char <ch> [<stream>])             WRITE A CHARACTER TO A STREAM
          <ch>      the character to write
          <stream>  the    output    stream    (default,_    o_r_    N_I_L_,_   is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the character

     (read-line [<stream>])                       READ A LINE FROM A STREAM
          <stream>  the input stream (default,_ o_r_ N_I_L_,_ is *standard-input*,_
                    T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the string excluding  the #\newline, or  NIL at end  of
                    file







     XLISP 2.1c                FILE I/O FUNCTIONS                   Page 72


     (open    <fname>    &key    :direction     :element-type    :if-exists
     :if-does-not-exist)
                                                         OPEN A FILE STREAM
          T_h_e_  f_u_n_c_t_i_o_n_ O_P_E_N_ h_a_s_ b_e_e_n_  s_i_g_n_i_f_i_c_a_n_t_l_y_ e_n_h_a_n_c_e_d_ t_o_ m_a_t_c_h_ m_o_r_e_
          c_l_o_s_e_l_y_  C_o_m_m_o_n_   L_i_s_p_._  T_h_e_  o_r_i_g_i_n_a_l_  f_u_n_c_t_i_o_n_   o_n_l_y_  h_a_d_  t_h_e_
          :_d_i_r_e_c_t_i_o_n_  k_e_y_w_o_r_d_ a_r_g_u_m_e_n_t_,_  w_h_i_c_h_ c_o_u_l_d_  o_n_l_y_ h_a_v_e_  t_h_e_ v_a_l_u_e_s_
          :_i_n_p_u_t_ o_r_ :_o_u_t_p_u_t_._  W_h_e_n_ u_s_e_d_  w_i_t_h_ t_h_e_ :_o_u_t_p_u_t_  k_e_y_w_o_r_d_,_ i_t_  w_a_s_
          e_q_u_i_v_a_l_e_n_t_  t_o_   (_o_p_e_n_  <_f_n_a_m_e_>_  :_d_i_r_e_c_t_i_o_n_   :_o_u_t_p_u_t_  :_i_f_-_e_x_i_s_t_s_
          :_s_u_p_e_r_s_e_d_e_)_._

          <fname>        the file name string or symbol
          :direction     Read and  write permission for stream  (default is
                         :input).
            :input       Open file for read operations only.
            :probe       Open file for reading, then close it  (use to test
                         for file existance)
            :output      Open file for write operations only.
            :io          Like :output, but reading also allowed.
          :element-type  FIXNUM  or  CHARACTER (default  is  CHARACTER), as
                         returned by  type-of function (on  page 80). Files
                         opened with  type FIXNUM are binary  files instead
                         of   ascii,  which   means  no  crlf   to/from  lf
                         conversion  takes place,  and  control-Z will  not
                         terminate  an  input file.  It  is  the intent  of
                         Common Lisp  that  binary files  only be  accessed
                         with read-byte and write-byte while ascii files be
                         accessed  with  any  function  but  read-byte  and
                         write-byte.   XLISP   does   not    enforce   that
                         distinction.
          :if-exists     action to take  if file  exists. Argument  ignored
                         for :input (file is positioned at start) or :probe
                         (file is closed)
            :error       give error message
            :rename      rename file to generated  backup name, then open a
                         new file of the original name. This is the default
                         action
            :new-version same as :rename
            :overwrite   file is positioned to start, original data intact
            :append      file is positioned to end
            :supersede   delete original file and open new file of the same
                         name
            :rename-and-delete  same as :supersede
            NIL          close file and return NIL
          :if-does-not-exist    action to take if file does not exist.
            :error       give   error  message  (default   for  :input,  or
                         :overwrite or :append)
            :create      create a new file (default for :output or :io when
                         not :overwrite or :append)
            NIL          return NIL (default for :probe)
          returns        a file stream, or sometimes NIL







     XLISP 2.1c                FILE I/O FUNCTIONS                   Page 73


     (close <stream>)                                   CLOSE A FILE STREAM
          O_r_i_g_i_n_a_l_ v_e_r_s_i_o_n_ d_i_d_ n_o_t_ "_c_l_o_s_e_"_ u_n_n_a_m_e_d_ (_s_t_r_i_n_g_)_ s_t_r_e_a_m_s_._
          <stream>  the stream
          returns   t if stream  closed, NIL if terminal (cannot be closed)
                    or already closed.

     (_w_i_t_h_-_o_p_e_n_-_f_i_l_e_ (_<_v_a_r_>_ <_f_n_a_m_e_>_ [_<_k_a_r_g_>_._._._]_)_ [_<_e_x_p_r_>_._._._]_)_
                                                      E_V_A_L_U_A_T_E_ U_S_I_N_G_ A_ F_I_L_E_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_ a_s_ a_ m_a_c_r_o_._ F_i_l_e_ w_i_l_l_ a_l_w_a_y_s_ b_e_ c_l_o_s_e_d_ u_p_o_n_
          c_o_m_p_l_e_t_i_o_n_
          <_v_a_r_>_     s_y_m_b_o_l_   n_a_m_e_  t_o_  b_i_n_d_   s_t_r_e_a_m_  t_o_  w_h_i_l_e_  e_v_a_l_u_a_t_i_n_g_
                    e_x_p_r_e_s_s_s_i_o_n_s_ (_q_u_o_t_e_d_)_
          <_f_n_a_m_e_>_   f_i_l_e_ n_a_m_e_ s_t_r_i_n_g_ o_r_ s_y_m_b_o_l_
          <_k_a_r_g_>_    k_e_y_w_o_r_d_ a_r_g_u_m_e_n_t_s_ f_o_r_ t_h_e_ i_m_p_l_i_c_i_t_ o_p_e_n_ c_o_m_m_a_n_d_
          <_e_x_p_r_>_    e_x_p_r_e_s_s_i_o_n_s_  t_o_ e_v_a_l_u_a_t_e_  w_h_i_l_e_ f_i_l_e_ i_s_  o_p_e_n_ (_i_m_p_l_i_c_i_t_
                    p_r_o_g_n_)_
          r_e_t_u_r_n_s_   v_a_l_u_e_ o_f_ l_a_s_t_ <_e_x_p_r_>_._

     (read-byte [<stream>])                       READ A BYTE FROM A STREAM
          <stream>  the input stream (default,_ o_r_ N_I_L_,_ is *standard-input*,_
                    T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the byte (integer) or NIL at end of file

     (write-byte <byte> [<stream>])                WRITE A BYTE TO A STREAM
          <byte>    the byte to write (integer)
          <stream>  the    output    stream    (default,_   o_r_    N_I_L_,_    is
                    *standard-output*,_ T_ i_s_ *_t_e_r_m_i_n_a_l_-_i_o_*_)
          returns   the byte (integer)

     (_f_i_l_e_-_l_e_n_g_t_h_ <_s_t_r_e_a_m_>_)_                              G_E_T_ L_E_N_G_T_H_ O_F_ F_I_L_E_
          N_o_t_e_:_ n_e_w_ f_u_n_c_t_i_o_n_
          F_o_r_  a_n_ a_s_c_i_i_  f_i_l_e_,_ t_h_e_ l_e_n_g_t_h_  r_e_p_o_r_t_e_d_ m_a_y_ b_e_  l_a_r_g_e_r_ t_h_a_n_ t_h_e_
          n_u_m_b_e_r_ o_f_ c_h_a_r_a_c_t_e_r_s_ r_e_a_d_ o_r_ w_r_i_t_t_e_n_ b_e_c_a_u_s_e_ o_f_ C_R_ c_o_n_v_e_r_s_i_o_n_._
          <_s_t_r_e_a_m_>_  t_h_e_ f_i_l_e_ s_t_r_e_a_m_ (_s_h_o_u_l_d_ b_e_ d_i_s_k_ f_i_l_e_)_
          r_e_t_u_r_n_s_   l_e_n_g_t_h_ o_f_ f_i_l_e_,_ o_r_ N_I_L_ i_f_ c_a_n_n_o_t_ b_e_ d_e_t_e_r_m_i_n_e_d_._

     (_f_i_l_e_-_p_o_s_i_t_i_o_n_ <_s_t_r_e_a_m_>_ [_<_e_x_p_r_>_]_)_             G_E_T_ O_R_ S_E_T_ F_I_L_E_ P_O_S_I_T_I_O_N_
          N_o_t_e_:_ n_e_w_ f_u_n_c_t_i_o_n_
          F_o_r_ a_n_ a_s_c_i_i_ f_i_l_e_,_  t_h_e_ f_i_l_e_ p_o_s_i_t_i_o_n_ m_a_y_ n_o_t_ b_e_ t_h_e_  s_a_m_e_ a_s_ t_h_e_
          n_u_m_b_e_r_ o_f_ c_h_a_r_a_c_t_e_r_s_ r_e_a_d_ o_r_ w_r_i_t_t_e_n_ b_e_c_a_u_s_e_ o_f_ C_R_ c_o_n_v_e_r_s_i_o_n_._ I_t_
          w_i_l_l_ b_e_ c_o_r_r_e_c_t_ w_h_e_n_ u_s_i_n_g_ f_i_l_e_-_p_o_s_i_t_i_o_n_ t_o_ p_o_s_i_t_i_o_n_ a_  f_i_l_e_ a_t_ a_
          l_o_c_a_t_i_o_n_ e_a_r_l_i_e_r_ r_e_p_o_r_t_e_d_ b_y_ f_i_l_e_-_p_o_s_i_t_i_o_n_._
          <_s_t_r_e_a_m_>_  t_h_e_ f_i_l_e_ s_t_r_e_a_m_ (_s_h_o_u_l_d_ b_e_ a_ d_i_s_k_ f_i_l_e_)_
          <_e_x_p_r_>_    d_e_s_i_r_e_d_ f_i_l_e_ p_o_s_i_t_i_o_n_,_ i_f_ s_e_t_t_i_n_g_ p_o_s_i_t_i_o_n_._ C_a_n_ a_l_s_o_ b_e_
                    :_s_t_a_r_t_ f_o_r_ s_t_a_r_t_ o_f_ f_i_l_e_ o_r_ :_e_n_d_ f_o_r_ e_n_d_ o_f_ f_i_l_e_._
          r_e_t_u_r_n_s_   i_f_ s_e_t_t_i_n_g_ p_o_s_i_t_i_o_n_,_ a_n_d_ s_u_c_c_e_s_s_f_u_l_,_ t_h_e_n_ T_;_ i_f_ g_e_t_t_i_n_g_
                    p_o_s_i_t_i_o_n_  a_n_d_ s_u_c_c_e_s_s_f_u_l_  t_h_e_n_ t_h_e_  p_o_s_i_t_i_o_n_;_ o_t_h_e_r_w_i_s_e_
                    N_I_L_







     XLISP 2.1c              STRING STREAM FUNCTIONS                Page 74



     STRING STREAM FUNCTIONS

     These  functions operate on unnamed  streams. An unnamed output stream
     collects characters sent  to it when it is used  as the destination of
     any output function. The functions 'get-output-stream' string and list
     return a sting or list of the characters.

     An unnamed  input stream is setup  with the 'make-string-input-stream'
     function  and returns each character of the  string when it is used as
     the source of any input function.

     Note  that there  is no  difference between  unnamed input  and output
     streams.  Unnamed input streams may be written to by output functions,
     in  which case  the characters  are appended  to the  tail end  of the
     stream. Unnamed output streams may also be (destructively) read by any
     input function as well as the get-output-stream functions.

     (make-string-input-stream <str> [<start> [<end>]])
          <str>     the string
          <start>   the starting offset
          <end>     the ending offset + 1 o_r_ N_I_L_ f_o_r_ e_n_d_ o_f_ s_t_r_i_n_g_
          returns   an unnamed stream that reads from the string

     (make-string-output-stream)
          returns   an unnamed output stream

     (get-output-stream-string <stream>)
          The output stream is emptied by this function
          <stream>  the output stream
          returns   the output so far as a string

     (get-output-stream-list <stream>)
          The output stream is emptied by this function
          <stream>  the output stream
          returns   the output so far as a list

     (_w_i_t_h_-_i_n_p_u_t_-_f_r_o_m_-_s_t_r_i_n_g_   (_<_v_a_r_>_  <_s_t_r_>_   &_k_e_y_  :_s_t_a_r_t_   :_e_n_d_  :_i_n_d_e_x_)_
     [_<_e_x_p_r_>_._._._]_)_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_ a_s_ a_ m_a_c_r_o_
          <_v_a_r_>_     s_y_m_b_o_l_  t_h_a_t_ s_t_r_e_a_m_  i_s_  b_o_u_n_d_ t_o_  d_u_r_i_n_g_ e_x_e_c_u_t_i_o_n_  o_f_
                    e_x_p_r_e_s_s_i_o_n_s_ (_q_u_o_t_e_d_)_
          <_s_t_r_>_     t_h_e_ s_t_r_i_n_g_
          :_s_t_a_r_t_    s_t_a_r_t_i_n_g_ o_f_f_s_e_t_ i_n_t_o_ s_t_r_i_n_g_ (_d_e_f_a_u_l_t_ 0_)_
          :_e_n_d_      e_n_d_i_n_g_ o_f_f_s_e_t_ +_ 1_  (_d_e_f_a_u_l_t_,_ o_r_ N_I_L_,_ i_s_ e_n_d_ o_f_ s_t_r_i_n_g_)_
          :_i_n_d_e_x_    s_e_t_f_  p_l_a_c_e_ f_o_r_m_  w_h_i_c_h_  g_e_t_s_ f_i_n_a_l_  i_n_d_e_x_ i_n_t_o_  s_t_r_i_n_g_
                    a_f_t_e_r_ l_a_s_t_ e_x_p_r_e_s_s_i_o_n_ i_s_ e_x_e_c_u_t_e_d_ (_q_u_o_t_e_d_)_
          <_e_x_p_r_>_    e_x_p_r_e_s_s_i_o_n_s_ t_o_ e_v_a_l_u_a_t_e_ (_i_m_p_l_i_c_i_t_ p_r_o_g_n_)_
          r_e_t_u_r_n_s_   t_h_e_ v_a_l_u_e_ o_f_ t_h_e_ l_a_s_t_ <_e_x_p_r_>_







     XLISP 2.1c              STRING STREAM FUNCTIONS                Page 75


     (_w_i_t_h_-_o_u_t_p_u_t_-_t_o_-_s_t_r_i_n_g_ (_<_v_a_r_>_)_ [_<_e_x_p_r_>_._._._]_)_
          D_e_f_i_n_e_d_ i_n_ c_o_m_m_o_n_._l_s_p_ a_s_ a_ m_a_c_r_o_
          <_v_a_r_>_     s_y_m_b_o_l_  t_h_a_t_ s_t_r_e_a_m_  i_s_  b_o_u_n_d_ t_o_  d_u_r_i_n_g_ e_x_e_c_u_t_i_o_n_  o_f_
                    e_x_p_r_e_s_s_i_o_n_s_ (_q_u_o_t_e_d_)_
          <_e_x_p_r_>_    e_x_p_r_e_s_s_i_o_n_s_ t_o_ e_v_a_l_u_a_t_e_ (_i_m_p_l_i_c_i_t_ p_r_o_g_n_)_
          r_e_t_u_r_n_s_   c_o_n_t_e_n_t_s_ o_f_ s_t_r_e_a_m_,_ a_s_ a_ s_t_r_i_n_g_







     XLISP 2.1c           DEBUGGING AND ERROR HANDLING              Page 76



     DEBUGGING AND ERROR HANDLING FUNCTIONS

     (trace [<sym>...])                    ADD A FUNCTION TO THE TRACE LIST
          fsubr
          <sym>     the function(s) to add (quoted)
          returns   the trace list

     (untrace [<sym>...])             REMOVE A FUNCTION FROM THE TRACE LIST
          fsubr.  I_f_ n_o_ f_u_n_c_t_i_o_n_s_ g_i_v_e_n_,_ a_l_l_ f_u_n_c_t_i_o_n_s_ a_r_e_ r_e_m_o_v_e_d_ f_r_o_m_ t_h_e_
          t_r_a_c_e_ l_i_s_t_._
          <sym>     the function(s) to remove (quoted)
          returns   the trace list

     (error <emsg> [<arg>])                  SIGNAL A NON-CORRECTABLE ERROR
          <emsg>    the error message string
          <arg>     the argument expression (printed after the message)
          returns   never returns

     (cerror <cmsg> <emsg> [<arg>])              SIGNAL A CORRECTABLE ERROR
          <cmsg>    the continue message string
          <emsg>    the error message string
          <arg>     the argument expression (printed after the message)
          returns   NIL when continued from the break loop

     (break [<bmsg> [<arg>]])                            ENTER A BREAK LOOP
          <bmsg>    the break message string (defaults to "**BREAK**")
          <arg>     the argument expression (printed after the message)
          returns   NIL when continued from the break loop

     (clean-up)                                     CLEAN-UP AFTER AN ERROR
          returns   never returns

     (top-level)        CLEAN-UP AFTER AN ERROR AND RETURN TO THE TOP LEVEL
          returns   never returns

     (continue)                           CONTINUE FROM A CORRECTABLE ERROR
          returns   never returns

     (errset <expr> [<pflag>])                                  TRAP ERRORS
          fsubr
          <expr>    the expression to execute
          <pflag>   flag to control printing  of the error message (default
                    t)
          returns   the value of the last expression consed with NIL or NIL
                    on error

     (baktrace [<n>])              PRINT N LEVELS OF TRACE BACK INFORMATION
          <n>       the number of levels (defaults to all levels)
          returns   NIL







     XLISP 2.1c           DEBUGGING AND ERROR HANDLING              Page 77


     (evalhook <expr> <ehook> <ahook> [<env>])          EVALUATE WITH HOOKS
          <expr>    the expression to evaluate. <ehook> is not used  at the
                    top level.
          <ehook>   the value for *evalhook*
          <ahook>   the value for *applyhook*
          <env>     the  environment  (default is  NIL).  The  format is  a
                    dotted pair  of value (car) and  function (cdr) binding
                    lists.  Each binding  list is  a list of  level binding
                    a-lists,  with  the innermost  a-list first.  The level
                    binding  a-list associates  the bound  symbol  with its
                    value.
          returns   the result of evaluating the expression

     (_a_p_p_l_y_h_o_o_k_ <_f_u_n_>_ <_a_r_g_l_i_s_t_>_ <_e_h_o_o_k_>_ <_a_h_o_o_k_>_)_           A_P_P_L_Y_ W_I_T_H_ H_O_O_K_S_
          N_o_t_e_:_ A_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_f_u_n_>_     T_h_e_  f_u_n_c_t_i_o_n_ c_l_o_s_u_r_e_._  <_a_h_o_o_k_>_  i_s_ n_o_t_  u_s_e_d_ f_o_r_  t_h_i_s_
                    f_u_n_c_t_i_o_n_ a_p_p_l_i_c_a_t_i_o_n_._
          <_a_r_g_l_i_s_t_>_ T_h_e_ l_i_s_t_ o_f_ a_r_g_u_m_e_n_t_s_._
          <_e_h_o_o_k_>_   t_h_e_ v_a_l_u_e_ f_o_r_ *_e_v_a_l_h_o_o_k_*_
          <_a_h_o_o_k_>_   t_h_e_ v_a_l_u_e_ f_o_r_ *_a_p_p_l_y_h_o_o_k_*_
          r_e_t_u_r_n_s_   t_h_e_ r_e_s_u_l_t_ o_f_ a_p_p_l_y_i_n_g_ <_f_u_n_>_ t_o_ <_a_r_g_l_i_s_t_>_

     (debug)                                            ENABLE DEBUG BREAKS
     (nodebug)                                         DISABLE DEBUG BREAKS
          Defined in init.lsp







     XLISP 2.1c                 SYSTEM FUNCTIONS                    Page 78



     SYSTEM FUNCTIONS

     (load <fname> &key :verbose :print)                 LOAD A SOURCE FILE
          An  implicit  ERRSET exists  in this  function  so that  if error
          occurs during loading, and *breakenable*  is NIL, then the  error
          message will be printed  and NIL will be returned.  A_ c_o_m_p_i_l_a_t_i_o_n_
          o_p_t_i_o_n_  a_l_l_o_w_s_ t_h_e_ u_s_e_ o_f_ t_h_e_ O_S_ e_n_v_i_r_o_n_m_e_n_t_a_l_ v_a_r_i_a_b_l_e_ X_L_P_A_T_H_ a_s_
          a_ s_e_a_r_c_h_ p_a_t_h_ f_o_r_  f_i_l_e_s_ i_n_ t_h_i_s_  f_u_n_c_t_i_o_n_._ I_f_ t_h_e_ f_i_l_e_n_a_m_e_  d_o_e_s_
          n_o_t_ c_o_n_t_a_i_n_  p_a_t_h_ s_e_p_a_r_a_t_o_r_s_ (_'_/_'_ f_o_r_ U_N_I_X_,_ a_n_d_ e_i_t_h_e_r_ '_/_'_ o_r_ '_\_'_
          f_o_r_ M_S_-_D_O_S_)_ a_n_d_ X_L_P_A_T_H_  i_s_ d_e_f_i_n_e_d_,_ t_h_e_n_ e_a_c_h_ p_a_t_h_n_a_m_e_  i_n_ X_L_P_A_T_H_
          i_s_ t_r_i_e_d_ i_n_ t_u_r_n_ u_n_t_i_l_  a_ m_a_t_c_h_i_n_g_ f_i_l_e_ i_s_  f_o_u_n_d_._ I_f_ n_o_ f_i_l_e_  i_s_
          f_o_u_n_d_,_  t_h_e_n_ o_n_e_ l_a_s_t_ a_t_t_e_m_p_t_  i_s_ m_a_d_e_ i_n_  t_h_e_ c_u_r_r_e_n_t_ d_i_r_e_c_t_o_r_y_._
          T_h_e_ p_a_t_h_n_a_m_e_s_ a_r_e_ s_e_p_a_r_a_t_e_d_ b_y_ e_i_t_h_e_r_ a_ s_p_a_c_e_ o_r_ s_e_m_i_c_o_l_o_n_,_ a_n_d_ a_
          t_r_a_i_l_i_n_g_ p_a_t_h_ s_e_p_a_r_a_t_o_r_ c_h_a_r_a_c_t_e_r_ i_s_ o_p_t_i_o_n_a_l_._
          <fname>   the filename  string or symbol. The  extension "lsp" is
                    assumed.
          :verbose  the verbose flag (default is t)
          :print    the print flag (default is NIL)
          returns   t if successful, else NIL

     (restore <fname>)                        RESTORE WORKSPACE FROM A FILE
          A_  c_o_m_p_i_l_a_t_i_o_n_ o_p_t_i_o_n_  a_l_l_o_w_s_  t_h_e_ u_s_e_  o_f_  t_h_e_ O_S_  e_n_v_i_r_o_n_m_e_n_t_a_l_
          v_a_r_i_a_b_l_e_ X_L_P_A_T_H_ a_s_ a_ s_e_a_r_c_h_ p_a_t_h_ f_o_r_ f_i_l_e_s_  i_n_ t_h_i_s_ f_u_n_c_t_i_o_n_._ S_e_e_
          t_h_e_  n_o_t_e_ u_n_d_e_r_  f_u_n_c_t_i_o_n_ "_l_o_a_d_"_,_ a_b_o_v_e_._  Note that  file streams
          other than the standard  system streams are "restored" as  closed
          files,  and  the standard  system  streams  are restored  to  the
          defaults  as  of  when  xlisp was  started.  C_e_r_t_a_i_n_  c_o_m_p_i_l_a_t_i_o_n_
          o_p_t_i_o_n_s_ w_i_l_l_ s_a_v_e_ s_t_r_e_a_m_s_  a_c_r_o_s_s_ s_a_v_e_s_;_ i_n_ t_h_i_s_ c_a_s_e_,_  t_h_e_ f_i_l_e_s_
          a_r_e_ r_e_s_t_o_r_e_d_ i_n_ t_h_e_ s_a_m_e_ m_o_d_e_ t_h_e_y_ w_e_r_e_ c_r_e_a_t_e_d_,_ i_f_ p_o_s_s_i_b_l_e_,_ a_n_d_
          a_r_e_ p_o_s_i_t_i_o_n_e_d_ w_h_e_r_e_ t_h_e_y_ w_e_r_e_ a_t_ t_h_e_ t_i_m_e_ o_f_ t_h_e_  s_a_v_e_._ I_f_ x_l_i_s_p_
          i_s_ r_u_n_  f_r_o_m_ a_  d_i_f_f_e_r_e_n_t_ d_i_r_e_c_t_o_r_y_,_  o_r_ i_f_ t_h_e_  f_i_l_e_s_ h_a_v_e_  b_e_e_n_
          a_l_t_e_r_e_d_,_  s_i_n_c_e_ t_h_e_  t_i_m_e_ o_f_  t_h_e_ s_a_v_e_,_  t_h_e_ r_e_s_t_o_r_e_  m_a_y_  n_o_t_ b_e_
          s_u_c_c_e_s_s_f_u_l_._ Memory allocation will not be the same as the current
          settings of ALLOC are  used. Execution proceeds at the  top-level
          read-eval-print loop. The state of  the transcript logging is not
          affected by this function.
          <fname>   the filename  string or symbol. The  extension "wks" is
                    assumed.
          returns   NIL on failure, otherwise never returns

     (save <fname>)                                SAVE WORKSPACE TO A FILE
          You cannot save from within a load. Not all of the state is saved
          --  see "restore",  above. By  saving a  workspace with  the name
          "xlisp",  that workspace  will be  loaded automatically  when you
          invoke xlisp.
          <fname>   the filename  string or symbol. The  extension "wks" is
                    assumed.
          returns   t if workspace was written, NIL otherwise







     XLISP 2.1c                 SYSTEM FUNCTIONS                    Page 79


     (savefun <fcn>)                                SAVE FUNCTION TO A FILE
          defined in init.lsp
          <fcn>     function  name (saves  it to  file  of same  name, with
                    extension ".lsp")
          returns   t if successful

     (dribble [<fname>])       CREATE A FILE WITH A TRANSCRIPT OF A SESSION
          <fname>   file name string or symbol
                    (if missing, close current transcript)
          returns   t if the transcript is opened, NIL if it is closed

     (gc)                                          FORCE GARBAGE COLLECTION
          returns   NIL

     (expand [<num>])                      EXPAND MEMORY BY ADDING SEGMENTS
          <num>     the number of segments to add, default 1
          returns   the number of segments added

     (alloc <num> [_<_n_u_m_2_>_]_)  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
          <num>     the number of nodes to allocate
          <_n_u_m_2_>_    t_h_e_  n_u_m_b_e_r_ o_f_ p_o_i_n_t_e_r_ e_l_e_m_e_n_t_s_ t_o_ a_l_l_o_c_a_t_e_ i_n_ a_n_ a_r_r_a_y_
                    s_e_g_m_e_n_t_  (_w_h_e_n_  d_y_n_a_m_i_c_  a_r_r_a_y_   a_l_l_o_c_a_t_i_o_n_  c_o_m_p_i_l_e_d_)_._
                    D_e_f_a_u_l_t_ i_s_ n_o_ c_h_a_n_g_e_._
          returns   the old number of nodes to allocate

     (room)                               SHOW MEMORY ALLOCATION STATISTICS
          Statistics (which are sent to *STANDARD-OUTPUT*) include:
           Nodes - number of nodes, free and used
           Free nodes - number of free nodes
           Segments - number of node segments, including those reserved for
                    characters and small integers.
           Allocate - number of nodes to allocate in any new node segments
           Total - total memory bytes allocated for  node segments, arrays,
                    and strings
           Collections - number of garbage collections
          W_h_e_n_  d_y_n_a_m_i_c_  a_r_r_a_y_   a_l_l_o_c_a_t_i_o_n_  i_s_  c_o_m_p_i_l_e_d_,_   t_h_e_  f_o_l_l_o_w_i_n_g_
          a_d_d_i_t_i_o_n_a_l_ s_t_a_t_i_s_t_i_c_s_ a_r_e_ p_r_i_n_t_e_d_:_
           V_e_c_t_o_r_   n_o_d_e_s_  -_  n_u_m_b_e_r_  o_f_  p_o_i_n_t_e_r_s_   i_n_  a_r_r_a_y_s_  a_n_d_  (_s_i_z_e_
          e_q_u_i_v_a_l_e_n_t_)_ s_t_r_i_n_g_s_
           V_e_c_t_o_r_ s_e_g_s_ -_ n_u_m_b_e_r_ o_f_ v_e_c_t_o_r_ s_e_g_m_e_n_t_s_._ I_n_c_r_e_a_s_e_s_ a_n_d_ d_e_c_r_e_a_s_e_s_
          a_s_ n_e_e_d_e_d_._
           V_e_c_ a_l_l_o_c_a_t_e_ -_ n_u_m_b_e_r_ o_f_ p_o_i_n_t_e_r_ e_l_e_m_e_n_t_s_ t_o_ a_l_l_o_c_a_t_e_ i_n_ a_n_y_ n_e_w_
                    v_e_c_t_o_r_ s_e_g_m_e_n_t_
          returns   NIL

     (_t_i_m_e_ <_e_x_p_r_>_)_                                   M_E_A_S_U_R_E_ E_X_E_C_U_T_I_O_N_ T_I_M_E_
          f_s_u_b_r_._ N_o_t_e_:_ a_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ e_v_a_l_u_a_t_e_
          r_e_t_u_r_n_s_   t_h_e_  r_e_s_u_l_t_ o_f_  t_h_e_ e_x_p_r_e_s_s_i_o_n_._  T_h_e_ e_x_e_c_u_t_i_o_n_  t_i_m_e_ i_s_
                    p_r_i_n_t_e_d_ t_o_ *_T_R_A_C_E_-_O_U_T_P_U_T_*_







     XLISP 2.1c                 SYSTEM FUNCTIONS                    Page 80


     (_g_e_t_-_i_n_t_e_r_n_a_l_-_r_e_a_l_-_t_i_m_e_)_                        G_E_T_ E_L_A_P_S_E_D_ C_L_O_C_K_ T_I_M_E_
     (_g_e_t_-_i_n_t_e_r_n_a_l_-_r_u_n_-_t_i_m_e_)_                     G_E_T_ E_L_A_P_S_E_D_ E_X_E_C_U_T_I_O_N_ T_I_M_E_
          N_o_t_e_:_ a_d_d_e_d_ f_u_n_c_t_i_o_n_s_
          r_e_t_u_r_n_s_   i_n_t_e_g_e_r_     t_i_m_e_     i_n_      s_y_s_t_e_m_     u_n_i_t_s_      (_s_e_e_
                    i_n_t_e_r_n_a_l_-_t_i_m_e_-_u_n_i_t_s_-_p_e_r_-_s_e_c_o_n_d_ o_n_ p_a_g_e_ 2_1_)_._  m_e_a_n_i_n_g_ o_f_
                    a_b_s_o_l_u_t_e_ v_a_l_u_e_s_ i_s_ s_y_s_t_e_m_ d_e_p_e_n_d_e_n_t_._

     (_c_o_e_r_c_e_ <_e_x_p_r_>_ <_t_y_p_e_>_)_             F_O_R_C_E_ E_X_P_R_E_S_S_I_O_N_ T_O_ D_E_S_I_G_N_A_T_E_D_ T_Y_P_E_
          N_o_t_e_:_ a_d_d_e_d_ f_u_n_c_t_i_o_n_
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ c_o_e_r_c_e_
          <_t_y_p_e_>_    d_e_s_i_r_e_d_ t_y_p_e_,_ a_s_ r_e_t_u_r_n_e_d_ b_y_ t_y_p_e_-_o_f_ (_s_e_e_ p_a_g_e_ 8_0_)_
          r_e_t_u_r_n_s_   <_e_x_p_r_>_ i_f_ t_y_p_e_ i_s_ c_o_r_r_e_c_t_,_ o_r_ c_o_n_v_e_r_t_e_d_ o_b_j_e_c_t_._
          S_e_q_u_e_n_c_e_s_ c_a_n_  b_e_ c_o_e_r_c_e_d_ i_n_t_o_ o_t_h_e_r_  s_e_q_u_e_n_c_e_s_,_ s_i_n_g_l_e_ c_h_a_r_a_c_t_e_r_
          s_t_r_i_n_g_s_  o_r_  s_y_m_b_o_l_s_  w_i_t_h_  s_i_n_g_l_e_ c_h_a_r_a_c_t_e_r_  p_r_i_n_t_n_a_m_e_s_  c_a_n_  b_e_
          c_o_e_r_c_e_d_ i_n_t_o_ c_h_a_r_a_c_t_e_r_s_,_ i_n_t_e_g_e_r_s_  c_a_n_ b_e_ c_o_e_r_c_e_d_ i_n_t_o_ c_h_a_r_a_c_t_e_r_s_
          o_r_ f_l_o_n_u_m_s_._ F_l_o_n_u_m_s_ c_a_n_ b_e_ c_o_e_r_c_e_d_ i_n_t_o_ c_o_m_p_l_e_x_ (_s_o_ c_a_n_ i_n_t_e_g_e_r_s_,_
          b_u_t_ t_h_e_y_ t_u_r_n_ b_a_c_k_ i_n_t_o_ i_n_t_e_g_e_r_s_)_._

     (type-of <expr>)                    RETURNS THE TYPE OF THE EXPRESSION
          I_t_  i_s_ r_e_c_o_m_m_e_n_d_e_d_  t_h_a_t_ t_y_p_e_p_  b_e_  u_s_e_d_ i_n_s_t_e_a_d_,_  a_s_ i_t_  i_s_ m_o_r_e_
          g_e_n_e_r_a_l_._
          <expr>    the expression to return the type of
          returns   o_r_i_g_i_n_a_l_l_y_ i_f_ t_h_e_ e_x_p_r_e_s_s_i_o_n_ w_a_s_ N_I_L_,_ N_I_L_ w_a_s_ r_e_t_u_r_n_e_d_._
                    One of the symbols:
                    L_I_S_T_                f_o_r_ N_I_L_
                    SYMBOL              for symbols
                    OBJECT              for objects
                    CONS                for conses
                    SUBR                for built-in functions
                    FSUBR               for special forms
                    CLOSURE             for defined functions
                    STRING              for strings
                    FIXNUM              for integers
                    FLONUM              for floating point numbers
                    C_O_M_P_L_E_X_             f_o_r_ c_o_m_p_l_e_x_ n_u_m_b_e_r_s_
                    CHARACTER           for characters
                    FILE-STREAM         for file pointers
                    UNNAMED-STREAM      for unnamed streams
                    ARRAY               for arrays
                    H_A_S_H_-_T_A_B_L_E_          f_o_r_ h_a_s_h_ t_a_b_l_e_s_
                    sym                 for structures of type "sym"

     (peek <addrs>)                            PEEK AT A LOCATION IN MEMORY
          <addrs>   the address to peek at (integer)
          returns   the value at the specified address (integer)

     (poke <addrs> <value>)                        POKE A VALUE INTO MEMORY
          <addrs>   the address to poke (integer)
          <value>   the value to poke into the address (integer)
          returns   the value







     XLISP 2.1c                 SYSTEM FUNCTIONS                    Page 81


     (address-of <expr>)                   GET THE ADDRESS OF AN XLISP NODE
          <expr>    the node
          returns   the address of the node (integer)

     (get-key)                                READ A KEYSTROKE FROM CONSOLE
          OS dependent.
          returns   integer value of key (no echo)

     (system <command>)                            EXECUTE A SYSTEM COMMAND
          OS dependent.
          <command> Command string, if 0 length then spawn OS shell
          returns   T if  successful (note  that MS/DOS  command.com always
                    returns success)

     (exit)                                                      EXIT XLISP
          returns   never returns

     (_g_e_n_e_r_i_c_ <_e_x_p_r_>_)_         C_R_E_A_T_E_ A_ G_E_N_E_R_I_C_ T_Y_P_E_D_ C_O_P_Y_ O_F_ T_H_E_ E_X_P_R_E_S_S_I_O_N_
          N_o_t_e_:_ a_d_d_e_d_ f_u_n_c_t_i_o_n_,_ T_o_m_ A_l_m_y_'_s_ c_r_e_a_t_i_o_n_ f_o_r_ d_e_b_u_g_g_i_n_g_ x_l_i_s_p_._
          <_e_x_p_r_>_    t_h_e_ e_x_p_r_e_s_s_i_o_n_ t_o_ c_o_p_y_
          r_e_t_u_r_n_s_   N_I_L_ i_f_  v_a_l_u_e_ i_s_  N_I_L_ a_n_d_ N_I_L_S_Y_M_B_O_L_  c_o_m_p_i_l_a_t_i_o_n_ o_p_t_i_o_n_
                    n_o_t_ d_e_c_l_a_r_e_d_,_ o_t_h_e_r_w_i_s_e_ i_f_ t_y_p_e_ i_s_:_
                    S_Y_M_B_O_L_              c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_
                    O_B_J_E_C_T_              c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_
                    C_O_N_S_                (_C_O_N_S_ (_C_A_R_ <_e_x_p_r_>_)_(_C_D_R_ <_e_x_p_r_>_)_)_
                    C_L_O_S_U_R_E_             c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_
                    S_T_R_I_N_G_              c_o_p_y_ o_f_ t_h_e_ s_t_r_i_n_g_
                    F_I_X_N_U_M_              v_a_l_u_e_
                    F_L_O_N_U_M_              v_a_l_u_e_
                    C_H_A_R_A_C_T_E_R_           v_a_l_u_e_
                    U_N_N_A_M_E_D_-_S_T_R_E_A_M_      c_o_p_y_ a_s_ a_ C_O_N_S_
                    A_R_R_A_Y_               c_o_p_y_ o_f_ t_h_e_ a_r_r_a_y_
                    C_O_M_P_L_E_X_             c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_
                    H_A_S_H_-_T_A_B_L_E_          c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_
                    s_t_r_u_c_t_u_r_e_           c_o_p_y_ a_s_ a_n_ A_R_R_A_Y_


     The following graphic and display functions represent an  extension by
     Tom Almy:

     (cls)                                                    CLEAR DISPLAY
          Clear the display and position cursor at upper left corner.
          returns   nil

     (cleol)                                           CLEAR TO END OF LINE
          Clears current line to end.
          returns   nil







     XLISP 2.1c                 SYSTEM FUNCTIONS                    Page 82


     (goto-xy [<column> <row>])                  GET OR SET CURSOR POSITION
          Cursor  is  repositioned  if  optional arguments  are  specified.
          Coordinates are clipped to actual size of display.
          <column>  0-based column (x coordinate)
          <row>     0-based row (y coordinate)
          returns   list of original column and row positions

     (color <value>)                                      SET DRAWING COLOR
          <value>   Drawing color (not checked for validity)
          returns   <value>

     (move <x1> <y1> [<x2> <y2> ...])                         ABSOLUTE MOVE
     (moverel <x1> <y2> [<x2> <y2> ...])                      RELATIVE MOVE
          For  moverel,  all coordinates  are  relative  to the  preceeding
          point.
          <x1> <y1> Moves to point x1,y1 in anticipation of draw.
          <x2> <y2> Draws to points specified in additional arguments.
          returns   T if succeeds, else NIL

     (draw [<x1> <y1> ...])                                   ABSOLUTE DRAW
     (drawrel [<x1> <y1> ...])                                RELATIVE DRAW
          For  drawrel,  all coordinates  are  relative  to the  preceeding
          point.
          <x1> <y1> Point(s) drawn to, in order.
          returns   T if succeeds, else NIL

     (mode <ax> [<bx> <width> <height>)                    SET DISPLAY MODE
          Standard  modes require  only <ax>  argument. Extended  modes are
          "Super-VGA" or "Super-EGA" and are display card specific. Not all
          XLISP versions support all modes.
          <ax>      Graphic mode (value passed in register AX)
                    Common standard Modes:
                    0,1 - 40x25 text
                    2,3 - 80x25 text
                    4,5 - 320x200 4 color graphics (CGA)
                    6 - 640x200 monchrome graphics (CGA)
                    13 - 320x200 16 color graphics (EGA)
                    14 - 640x200 16 color graphics (EGA)
                    16 - 640x350 16 color graphics (EGA)
                    18 - 640x480 16 color graphics (VGA)
                    19 - 320x200 256 color graphics (VGA)
          <bx>      BX value for some extended graphic modes
          <width>   width for extended graphic modes
          <height>  height for extended graphic modes
          returns   T, or NIL if fails







     XLISP 2.1c               ADDITIONAL FUNCTIONS                  Page 83



     ADDITIONAL FUNCTIONS AND UTILITIES

     STEP.LSP

     This file contains a simple Lisp  single-step debugger. It  started as
     an  implementation of  the "hook"  example in  chapter 20  of Steele's
     "Common Lisp". This version was brought up on Xlisp 1.7 for the Amiga,
     and then on VAXLISP.

     To invoke: (step (whatever-form with args))

     For  each list  (interpreted function  call), the  stepper  prints the
     environment  and the list, then enters a read-eval-print loop. At this
     point the available commands are:

     (a list)<CR>   evaluate the list in the current environment, print the
                    result, and repeat.
     <CR>           step into the called function
     anything_else<CR>        step over the called function.

     If the stepper comes to  a form that is not a list it  prints the form
     and the value, and continues on without stopping.

     Note that stepper  commands are executed  in the current  environment.
     Since  this is the case,  the stepper commands  can change the current
     environment. For example,  a SETF will change  an environment variable
     and thus can alter the course of execution.

     Global variables - newline, *hooklevel*

     Functions/macros   -   while   step   eval-hool-function   step-spaces
     step-flush

     Note     an  even more  powerful  stepper  package  is in  stepper.lsp
     (documented in stepper.doc).







     XLISP 2.1c               ADDITIONAL FUNCTIONS                  Page 84


     PP.LSP

     In addition to  the pretty-printer  itself, this file  contains a  few
     functions that illustrate some simple but useful applications.

     (pp <object> [<stream>])                       PRETTY PRINT EXPRESSION
     (pp-def <funct> [<stream>])                PRETTY PRINT FUNCTION/MACRO
     (pp-file <file> [<stream>])                          PRETTY PRINT FILE
          <object>  The expression to print
          <funct>   Function to print (as DEFUN or DEFMACRO)
          <file>    File  to  print (specify  either  as  string or  quoted
                    symbol)
          <stream>  Output stream (default is *standard-output*)
          returns   T

     Global   variables:   tabsize    maxsize   miser-size    min-miser-car
     max-normal-car

     Functions/Macros: sym-function  pp-file pp-def make-def pp  pp1 moveto
     spaces pp-rest-across pp-rest  printmacrop pp-binding-form  pp-do-form
     pp-defining-form pp-pair-form

     See the source file for more information.







     XLISP 2.1c               ADDITIONAL FUNCTIONS                  Page 85


     REPAIR.LSP

     This file contains a structure editor.
     Execute
          (repair 'symbol) to edit a symbol.
          (repairf symbol) to edit the function binding of a symbol (allows
                    changing the argument list  or function type, lambda or
                    macro).

     The  editor alters the current  selection by copying  so that aborting
     all  changes is  generally posible;  the exception  is when  editing a
     closure, if the closure is BACKed out of, the change is permanent.

     For all  commands taking a numeric argument,  the first element of the
     selection is the 0th (as in NTH function).

     Any array elements become lists when  they are selected, and return to
     arrays upon RETURN or BACK commands.

     Do not create new closures, because the environment will be incorrect.
     Closures become LAMBDA or MACRO expressions as the selection. Only the
     closure  body may be changed; the argument list cannot be successfully
     modified, nor can the environment.

     For class objects, only the methods and message names can be modified.
     For  instance objects,  instance  variables can  be  examined (if  the
     object under-stands the message :<ivar>  for the particular ivar), and
     changed  (if  :SET-IVAR  is  defined  for that  class,  as  it  is  if
     CLASSES.LSP is used).

     (command list on next page)







     XLISP 2.1c               ADDITIONAL FUNCTIONS                  Page 86


     COMMANDS (general):
          ?         list available commands for the selection.
          RETURN    exit, saving all changes.
          ABORT     exit, without changes.
          BACK      go back one level (as before CAR CDR or N commands).
          B n       go back n levels.
          L         display selection using pprint; if selection is symbol,
                    give short description.
          MAP       pprints each  element of selection, or  if selection is
                    symbol then gives complete description of properties.
          PLEV x    set   *print-level*   to   x.   (Initial   default   is
                    *rep-print-level*)
          PLEN x    set   *print-length   to   x.   (Initial   default   is
                    *rep-print-length*)
          EVAL x    evaluates x and prints result. The symbol @ is bound to
                    the selection.
          REPLACE x replaces the  current selection  with evaluated x.  The
                    symbol @ is bound to the selection.
     COMMANDS (if selection is symbol):
          VALUE     edit the value binding.
          FUNCTION  edit the function binding (must be a closure).
          PROP x    edit property x.
     COMMANDS (if selection is list):
          CAR       select the CAR of the current selection.
          CDR       select the CDR of the current selection.
          n         where n is small  non-negative integer, changes current
                    selection to (NTH n list).
          SUBST x y all occurances of (quoted) y are replaced with (quoted)
                    x. EQUAL is used for the comparison.
          RAISE n   removes   parenthesis   surrounding   nth  element   of
                    selection.
          LOWER n m inserts parenthesis starting with the nth  element, for
                    m elements.
          ARRAY n m as in LOWER, but makes elements into an array.
          I n x     inserts (quoted) x before nth element in selection.
          R n x     replaces nth element in selection with (quoted) x.
          D n       deletes nth element in selection.

     All function names and  global variables start with the  string "rep-"
     or "*rep-*".







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 87



     BUG FIXES AND EXTENSIONS


     The  following bugs  and minor  nits have  been fixed in  the standard
     (Betz) distribution  of XLISP  2.1cand  2.1. Bugs  fixed by  Tom Almy,
     except as noted:

         STRCAT where aggregate  size of argument strings  is greater than
          32k causes crash (16 bit integer systems).

         MAKE-ARRAY creates bogus array  for sizes 32768-65535, and arrays
          of size (mod size  65536) for larger sizes.   MAKE-ARRAY attempts
          to make negative sized arrays (16 bit integer systems).

         The following functions treat their numeric count argument modulo
          65536: DOTIMES, AREF, and the AREF and NTH place forms of SETF.

         "restore" corrupts  system (argument  stack not being  reset, and
          modification to CVPTR is needed for 8086 systems)

         Any  attempt to do more than one  RESTORE in a session causes the
          error "insufficient memory - segment".

         Strings containing nulls cannot be read, printed, or checked  for
          EQUAL. (Note,  strcat has  the same  problem,  but I  have a  new
          version, the Common Lisp concatenate function, which will replace
          it.

         NTH and NTHCDR fail for zero length (i.e. NIL) lists.

         :DOWNCASE  does  not work  with  all  compilers because  of  side
          effects in tolower() in some C libraries.

         Unnamed streams never survive a garbage collection (Paul A.W. van
          Niekerk).

         (format  NIL ...) does not protect the unnamed stream it creates,
          it will vanish during a GC. (Paul A. W. van Niekerk)

         In XLISP 2.0,  there seems to be a  bug in (sort ... ...)  due to
          some unprotected  pointers in sortlist() and  splitlist() in file
          xllist.c. (Neal Holtz)

         The  functions  SYMBOL-NAME, SYMBOL-VALUE,  SYMBOL-PLIST, BOUNDP,
          and FBOUNDP fail with  the symbol NIL as the  argument. Corrected
          to return "NIL", NIL, NIL, t, and NIL, respectively.

         A fix  was made  to prevent global  assignment of T  or keywords.
          (When SPECIALS is defined, then constants can never be bound).







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 88


         The  function LAST returned the wrong value when its argment list
          ended with a dotted pair.

         EVAL and LOAD  did not use global environment, EVALHOOK's default
          was not global environment.

         *gc-hook*  was  not rebound  to  NIL during  execution  of gchook
          function.

         A  bug that  caused the environment  to be wrong  when RETURN was
          executed within a DOTIMES or DOLIST has been corrected.

         Errors during execution of LOAD would often leave the file open.

         Closed  files would sometimes  respond to  reads, and  would give
          misleading error messages.

         MAKE-STRING-INPUT-STREAM  allowed start>end,  and would  not work
          for string lengths >32767 on 16 bit integer systems.


     The  following  represent minor  functional  improvements incorporated
     into the source without conditionals:


         Control  and  meta  characters  printed  "raw"  with  prin1,  now
          generate appropriate escape sequences.

         Can  now   declare  character  literals  for   control  and  meta
          characters, using new  escape sequences.( #\C-<char> for  control
          characters,   #\M-<char>   for   meta   characters   (msb   set),
          #\M-C-<char> for meta-control characters, #\rubout for 0x7f).

         Double quotes are  now escaped when  printed (i.e., (print  "\"")
          would print as """).

         Invalid  symbols  can  no  longer  be  created  with  intern  and
          make-symbol (such as symbol names containing control characters).
          Also, you can no longer make NIL, which was highly irregular! You
          can't change  the  value  of a  constant  (with  set  functions).
          Constants are T and keywords which always evaluate to themselves.

         (UNTRACE) now untraces all functions.

         The key "T", meaning "otherwise" in the CASE function, used to be
          allowed  at  any position,  when Common  Lisp (and  common sense)
          dictates it should only be at the end.

         (string <expr>) now makes a string from an integer as version 1.6
          did, and the manual suggests.







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 89


         SUBST and  SUBLIS perform minimum structure  copying, as required
          by Common Lisp.

         Added command line option -w.

         Added command line option -? to give usage message.

         For some  *stuff.c files, changed  so that standard  input and/or
          output can be redirected.

         For MS/DOS use, code in *stuf.c changed so that xlisp runs with a
          "raw" terminal mode, break off, and buffering for faster display.
          If *DOS-INPUT* is non-NIL, DOS is used to read input lines, which
          allows programs like CED  to work, and better operation  of xlisp
          in a Epsilon process window.

         Lexical and functional environment of a call to DEFMETHOD is used
          during the methods evaluation (Niels Mayer).

         CHAR-CODE  changed to mask off "parity"  bit, thus returning only
          code  values 0-127.  This  means that  (code-char (char-code  x))
          succeeds for all characters x.

         APPEND  and NCONC modified  to give  error messages  for improper
          arguments, rather than just ignoring them.

         A  check is  now made  for  extra arguments  in  subrs that  take
          keyword arguments.

         Identity values are now returned for certain functions when given
          no arguments: (+) => 0, (*) => 1, (LOGAND) => -1,  (LOGIOR) => 0,
          (LOGXOR) => 0

         Documentation corrected indicating all arguments are optional for
          GCD, and (GCD) => 0.

         Function  HASH  works  with all  objects,  not  just symbols  and
          strings.

         PEEK and POKE changed to access data the size of  a pointer. This
          will  allow consistant  operation  across systems.  Now the  only
          problem is that programs  don't know sizeof(OFFTYPE) to calculate
          the addresses of adjacient locations...

         Closed  streams can  be  closed without  error. Unnamed  (string)
          streams  can now be closed (they become closed file streams). The
          console cannot be closed. CLOSE returns true if close succeeds.

         Checks are made for attempting to make symbols or file names that
          are too long.







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 90


     Internal (non-visible) changes:

         Definitions  of  strings  internally   changed  to  "char"   from
          "unsigned char", thus making C code look much cleaner. New macros
          getstringch and  setstringch added to fetch  and store (unsigned)
          characters  into  a string.  This also  made  the code  much more
          readable.

         I'm trying to ANSI the definitions by adding function prototypes.
          It's not perfect yet!

         evfun()  modified to reduce C stack usage in recursive functions.
          The  local variable  "name"  replaced with  "getname(fun)"  where
          used;  The call  to  xleval was  replaced  with the  contents  of
          xleval. The local variable "type" in evform()  was deleted since,
          although set, its value was never used.

         The  values for  ADEPTH  and EDEPTH  changed  to more  reasonable
          values  1000 and 650 respectively with a 16k stack. EDEPTH should
          be roughly  2/3 ADEPTH. Before  the change,  the processor  stack
          would overflow first, causing a crash.  These values are compiler
          dependent, unfortunately.

         The recursion flag (rflag) argument for xlread  was deleted since
          it is no  longer used.   In xlread.c, the macro  functions obtain
          but  never use the macro character "mch".  This local variable is
          now deleted.

         All  refereces to osbgetc and osbputc changed to fgetc and fputc.
          osagetc and osaputc defined as macros in most systems to be fgetc
          and  fputc, but can be  defined as functions  for those compilers
          that  cannot  properly  handle  fseek   of  ascii  files.    When
          appropriate, fread  or fwrite have been  substituted for improved
          performance.

         A  number  of  functions  have been  rewritten  or  modified  for
          improved performance,  the most notable being  all functions that
          have the :test keyword when using  the default are over twice  as
          fast. EQUAL was changed to iterate down the cdr chain rather than
          recursing, reducing the chance of processor overflow. LIST builds
          from tail for much greater efficiency.

         No  documentation for function 'send-super', which exists instead
          of the two conflicting techniques in the documentation "A message
          can  also  be  sent... but  the  method  lookup  starts with  the
          object's superclass"  and the  message :SENDSUPER.   The instance
          variables for objects of class CLASS are not described.

         Documentation revised  to match  changes, and expanded  where not
          clear.







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 91


         Some  extern  declarations  added to  get  past  linting of  ANSI
          compilers. Added  makefiles for Zortech  C, Metaware High  C 386,
          Gnu   C,  BSD  UNIX,  and  Microway  NDP  C-386  compilers.  Some
          additional asm source files exist for the three 386 compilers.

     Functions of various compilation function options (see xlisp.h):

         NILSYMBOL -- NIL is a symbol. Should use only with SPECIALS.

         BETTERIO   --   adds    FILE-POSITION   FILE-LENGTH    FRESH-LINE
          OPEN-STREAM-P  INPUT-STREAM-P OUTPUT-STREAM-P,  and  lots of  new
          OPEN   functions  including   :io   and   binary  streams.   Adds
          *terminal-io* and  ability to correctly  redirect standard  input
          and standard  output. All  read and  write functions  can specify
          stream    NIL    (which    is    default    *standard-input*   or
          *standard-output*)  or  T (which  is *terminal-io*).  Printing of
          stream objects gives a better idea of what they are.

         FILETABLE  -- a  table  is maintained  of  all open  file  names,
          enhancing  PRINTing of  stream  objects. This  also allows  files
          streams to be saved in workspace files.

         PRINDEPTH -- adds *PRINT-LEVEL* and *PRINT-LENGTH*.

         OBJPRNT -- adds :prin1 Object class method, PNAME class  instance
          variable,  and  humanly  decipherable printing  of  objects  with
          PRIN1. (Mikael Pettersson)

         ENHFORMAT --  FORMAT function  modifiers and ~\n  directive (Neal
          Holtz)  and  ~d  ~e ~f  and  ~g  directives.  When BETTERIO  also
          defined, ~t and ~& directives added.

         JMAC  -- enhances  performance on  32 bit  processors, especially
          with virtual memory. (Johnny Greenblatt)

         JGC -- improved garbage collection. (Johnny Greenblatt)

         DISPMACRO -- adds *displace-macros* feature.

         ALLOWOTHER  -- makes  &allow-other-keys to  actually work  rather
          than being default.

         SPECIALS   --  allows   special  variables  (which   always  bind
          dynamically  rather  than  lexically)  and  constants.  Prohibits
          rebinding of  constants in  all cases. New  functions DEFCONSTANT
          DEFPARAMETER DEFVAR MAKUNBOUND CONSTANTP.







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 92


         COMMONLISP  -- NIL  means end  of string  for ending  indexes and
          string  functions. String  functions take  symbols or  strings as
          arguments.  Symbol  properties can  be  other  than symbols  (Ken
          Whedbee).  APPLY takes multiple  arguments. AREF indexes strings.
          Uninterned symbols print with leading #:. #. read macro added.

         COMMONLISPF --  defines common code which is  used for additional
          options  SRCHFCNS  MAPFCNS POSFCNS  REMDUPS  KEYARG and  TIERNEY.
          Defines new versions of REVERSE  REMOVE* DELETE* which handle all
          sequence  types and  have keyword  arguments. Adds  functions ELT
          COERCE NREVERSE TYPEP LIST*  and BUTLAST. Deletes function STRCAT
          (now a macro).

         SRCHFCNS -- Adds SEARCH.

         MAPFCNS -- Adds SOME EVERY NOTANY NOTEVERY and MAP.

         POSFCNS -- Adds POSITION-IF COUNT-IF FIND-IF.

         REMDUPS -- Adds REMOVE-DUPLICATES.

         TIERNEY -- Adds REDUCE. (Luke Tierney)

         KEYARG -- Adds :KEY arguments where appropriate.

         ADDEDTAA -- Adds GENERIC.

         TIMES -- Adds  TIME GET-INTERNAL-RUN-TIME  GET-INTERNAL-REAL-TIME
          INTERNAL-TIME-UNITS-PER-SECOND (Luke Tierney?)

         SETS --  Adds ADJOIN  UNION INTERSECTION SET-DIFFERENCE  SUBSETP.
          (Luke Tierney)

         HASHFCNS --  Adds GETHASH MAKE-HASH-TABLE  (Ken Whedbee)  REMHASH
          CLRHASH HASH-TABLE-COUNT, and MAPHASH

         RANDOM  -- Adds *RANDOM-STATE*, MAKE-RANDOM-STATE, floating point
          random numbers, and the optional random state argument to RANDOM.

         STRUCTS  --  Adds DEFSTRUCT  ASIN  ACOS  ATAN,  and  makes  XLISP
          identify itself as  version 2.1 (David Michael  Betz). There were
          several  modifications  to  this  code  to  make it  Common  Lisp
          compatible.

         APPLYHOOK -- Adds APPLYHOOK.

         COMPLX  --  Adds complex  numbers  and  functional support  where
          appropriate.  Also  adds  functions  COMPLEX   COMPLEXP  IMAGPART
          REALPART  PHASE LOG.  Constant PI.  (Luke Tierney)  Function LCM.
          (Ken Whedbee)   Two argument  ATAN, REM of  floats, two  argument
          TRUNCATE FLOOR CEILING and ROUND.







     XLISP 2.1c             BUG FIXES AND EXTENSIONS                Page 93


         GRAPHICS -- Adds MODE  MOVE MOVEREL DRAW DRAWREL COLOR  CLS CLEOL
          GOTO-XY.

         PATHNAMES -- Adds search paths for LOAD and RESTORE.



     DYNAMIC  ARRAY ALLOCATION -- XLISP normally uses the C malloc function
     to allocate regions of memory which XLISP uses for LVALS (cons nodes),
     and uses  the C malloc and  free functions to  allocate and deallocate
     each array  or array-like node.  This can  cause memory  fragmentation
     problems since the  C heap cannot be compressed. If  XLISP is compiled
     using  the dldmem.c and dlimage.c files rather than xldmem and xlimage
     files then  XLISP handles the  array structures by  allocating regions
     which  are used to hold multiple arrays and are garbage collected (and
     compressed and  eliminated if empty) as needed.  This change seemingly
     never is  more efficient (because of the garbage collection overhead),
     but does allow heavily array and string intensive programs to run that
     otherwise might not  because of  memory fragmentation.  It also  saves
     memory because  of less space  overhead (in  some environments).  Note
     that dynamic  array  allocation method  is  forced for  MS-DOS  Medium
     Memory model.







     XLISP 2.1c                     EXAMPLES                        Page 94



     EXAMPLES: FILE I/O FUNCTIONS


     Input from a File

     To  open a  file for  input, use  the OPEN  function with  the keyword
     argument :DIRECTION set to :INPUT. To  open a file for output, use the
     OPEN function with the keyword argument :DIRECTION set to :OUTPUT. The
     OPEN function  takes a single required  argument which is  the name of
     the file to be  opened. This name can be in the form  of a string or a
     symbol. The OPEN function returns an  object of type FILE-STREAM if it
     succeeds in opening the specified file. It returns the value NIL if it
     fails. In  order to manipulate the  file, it is necessary  to save the
     value returned by the OPEN function. This is usually done by assigning
     it to a variable with the SETQ special form or by binding it using LET
     or LET*. Here is an example:

         (setq fp (open "init.lsp" :direction :input))

     Evaluating  this expression will  result in the  file "init.lsp" being
     opened. The file  object that  will be returned  by the OPEN  function
     will be assigned to the variable "fp".

     It is now possible to  use the file for  input. To read an  expression
     from  the file,  just supply  the value  of the  "fp" variable  as the
     optional "stream" argument to READ.

         (read fp)

     Evaluating this expression will result in reading the first expression
     from  the  file "init.lsp".  The expression  will  be returned  as the
     result of the  READ function.  More expressions can  be read from  the
     file using further calls to the READ function. When there  are no more
     expressions  to read, the READ  function will return  NIL (or whatever
     value was supplied as the second argument to READ).

     Once you are done reading from the file, you should close it. To close
     the file, use the following expression:

         (close fp)

     Evaluating this expression will cause the file to be closed.







     XLISP 2.1c                     EXAMPLES                        Page 95



     Output to a File

     Writing to a  file is pretty  much the same as  reading from one.  You
     need  to open  the  file first.  This  time you  should  use the  OPEN
     function to indicate that you will do output to the file. For example:

         (setq fp (open "test.dat" :direction :output))

     Evaluating this expression will  open the file "test.dat"  for output.
     If the file already exists, its current contents will be discarded. If
     it  doesn't  already  exist,  it  will be  created.  In  any  case,  a
     FILE-STREAM  object will be returned  by the OPEN  function. This file
     object will be assigned to the "fp" variable.

     It is now possible to write to this file by supplying the value of the
     "fp"  variable  as  the  optional  "stream"  parameter  in  the  PRINT
     function.

         (print "Hello there" fp)

     Evaluating this  expression will  result in  the string "Hello  there"
     being written to the file "test.dat".  More data can be written to the
     file using the same technique.

     Once you are done writing to the file, you should close it. Closing an
     output file is just like closing an input file.

         (close fp)

     Evaluating  this expression  will close  the output  file and  make it
     permanent.



     A Slightly More Complicated File Example

     This example shows how to open  a file, read each Lisp expression from
     the file and print it. It demonstrates the use of files and the use of
     the optional "stream" argument to the READ
     function.

         (do* ((fp (open "test.dat" :direction :input))
               (ex (read fp) (read fp)))
              ((null ex) nil)
           (print ex))







     XLISP 2.1c                       INDEX                         Page 96


     INDEX


     :answer  19                           :test     26,   30,   33-35,
     :append  72                                     38-40, 58
     :class  18                            :test-not   26,  33-35,  38,
     :conc-name  52                                  39, 40, 58
     :constituent  13                      :tmacro  13
     :create  72                           :upcase  22
     :direction  72                        :verbose  78
     :downcase  22                         :white-space  13
     :element-type  72                     +  22, 42
     :end  33-35, 48, 73                   ++  22
     :end1  33, 36, 49                     +++  22
     :end2  33, 36, 49                     -  22, 42
     :error  72                            *  22, 42
     :if-does-not-exist  72                **  22
     :if-exists  72                        ***  22
     :include  52                          *applyhook*  10, 21
     :initial-value  35                    *breakenable*  5, 21
     :input  72                            *debug-io*  21
     :io  72                               *displace-macros*  9, 22
     :iskindof  18                         *dos-input*  3, 22
     :ismemberof  18                       *error-output*  21
     :isnew  18, 19                        *evalhook*  10, 21
     :key  26, 33-35, 38-41, 58            *float-format*  22
     :mescape  13                          *gc-flag*  22
     :messages  19                         *gc-hook*  10, 22
     :new  19                              *integer-format*  22
     :new-version  72                      *obarray*  21
     :nmacro  13                           *print-case*  22
     :output  72                           *print-length*  22
     :overwrite  72                        *print-level*  22
     :prin1  18                            *random-state*  22
     :print  78                            *readtable*  13, 21
     :probe  72                            *standard-input*  21
     :rename  72                           *standard-output*  21
     :rename-and-delete  72                *struct-slots*  52
     :respondsto  18                       *terminal-io*  21
     :sescape  13                          *trace-output*  21
     :set-ivar  54                         *tracelimit*  5, 21
     :set-pname  54                        *tracelist*  21
     :show  18                             *tracenable*  5, 21
     :size  30                             *unbound*  22
     :start  33-35, 48, 73                 /  42
     :start1  33, 36, 49                   /=  46
     :start2  33, 36, 49                   <  46
     :storeon  18, 19                      <=  46
     :superclass  18, 19                   =  46
     :supersede  72                        >  46
                                           >=  46







     XLISP 2.1c                       INDEX                         Page 97


     &allow-other-keys  15                 char/=  51
     &aux  15                              char<  51
     &key  15                              char<=  51
     &optional  15                         char=  51
     &rest  15                             char>  51
     1+  43                                char>=  51
     1-  43                                CHARACTER  80
     abs  43                               characterp  57
     acons  37                             cis  45
     acos  44                              class  21
     acosh  44                             classp  57
     address-of  81                        clean-up  4, 76
     adjoin  40                            clean-up,  5
     alloc  79                             close  73
     AND  59, 60                           CLOSURE  80
     append  37                            clrhash  30
     apply  23                             cls  81
     applyhook  10, 77                     code-char  50
     aref  25, 31                          coerce  80
     ARRAY  80                             color  82
     arrayp  57                            comma  23
     asin  44                              comma-at  23
     asinh  44                             complex  45, 80
     assoc  38                             complexp  57
     atan  44                              concatenate  32
     atanh  44                             cond  60
     atom  56, 59                          conjugate  45
     backquote  23                         cons  37, 80
     baktrace  76                          consp  56
     block  64                             constantp  56
     both-case-p  50                       continue  4, 5, 76
     boundp  57                            copy-alist  40
     break  76                             copy-list  39
     butlast  38                           copy-tree  40
     car  25, 37                           cos  44
     case  61                              cosh  44
     catch  61                             count-if  34
     cdr  25, 37                           cxxr  37
     ceiling  42                           cxxxr  37
     cerror  76                            cxxxxr  37
     char  50                              debug  77
     char-code  50                         decf  26
     char-downcase  50                     defclass  54
     char-equal  51                        defconstant  28
     char-greaterp  51                     definst  55
     char-int  50                          defmacro  27
     char-lessp  51                        defmethod  54
     char-not-equal  51                    defparameter  28
     char-not-greaterp  51                 defsetf  26
     char-not-lessp  51                    defstruct  52
     char-upcase  50                       defun  27







     XLISP 2.1c                       INDEX                         Page 98


     defvar  28                            functionp  58
     delete  34                            gc  79
     delete-if  35                         gcd  43
     delete-if-not  35                     generic  81
     digit-char  50                        gensym  27
     digit-char-p  50                      get  25, 29
     do  63                                get-internal-real-time  80
     do*  63                               get-internal-run-time  80
     dolist  63                            get-key  81
     dotimes  63                           get-lambda-expression  24
     draw  82                              get-macro-character  66
     drawrel  82                           get-output-stream-list  74
     dribble  79                           get-output-stream-string
     elt  25, 32                                     74
     endp  56                              gethash  25, 30
     eq  59                                go  64
     eql  59                               goto-xy  82
     equal  59                             hash  27
     equalp  59                            HASH-TABLE  80
     error  76                             hash-table-count  30
     errset  5, 76                         identity  23
     eval  23                              if  60
     evalhook  10, 77                      imagpart  45
     evenp  58                             incf  26
     every  32                             input-stream-p  57
     exit  81                              int-char  50
     exp  44                               integerp  56
     expand  79                            intern  27
     expt  44                              internal-time-units-per-sec
     fboundp  58                                     ond  21
     file-length  73                       intersection  40
     file-position  73                     labels  61
     FILE-STREAM  80                       lambda  24
     fill  35                              last  37
     find-if  34                           lcm  43
     first  37                             length  32
     FIXNUM  80                            let  61
     flatc  67                             let*  61
     flatsize  67                          list  37, 80
     flet  61                              list*  37
     float  42                             listp  56
     floatp  56                            load  78
     FLONUM  80                            log  45
     floor  42                             logand  47
     fmakunbound  27                       logior  47
     format  68                            lognot  47
     fourth  37                            logtest  47
     fresh-line  67                        logxor  47
     FSUBR  80                             loop  63
     funcall  23                           lower-case-p  50
     function  23, 59                      macroexpand  24







     XLISP 2.1c                       INDEX                         Page 99


     macroexpand-1  24                     pairlis  39
     macrolet  61                          peek  80
     make-array  31                        peek-char  71
     make-hash-table  30                   phase  45
     make-random-state  44                 pi  21
     make-string-input-stream              plusp  58
               74                          poke  80
     make-string-output-stream             pop  26
               74                          position-if  34
     make-symbol  27                       pp  84
     makunbound  27                        pprint  67
     map  32                               prin1  66
     mapc  38                              princ  67
     mapcan  39                            print  66
     mapcar  38                            prog  64
     mapcon  39                            prog*  64
     maphash  30                           prog1  65
     mapl  38                              prog2  65
     maplist  39                           progn  65
     max  43                               progv  64
     member  38, 59                        psetq  25
     min  43                               push  26
     minusp  58                            pushnew  26
     mode  82                              putprop  29
     move  82                              quote  23
     moverel  82                           random  44
     nconc  41                             read  66
     NIL  21                               read-byte  73
     nintersection  40                     read-char  71
     nodebug  77                           read-line  71
     not  56, 59                           realpart  45
     notany  32                            reduce  35
     notevery  32                          rem  43
     nreverse  32                          remhash  30
     nset-difference  40                   remove  33
     nset-exclusive-or  40                 remove-duplicates  35
     nstring-downcase  48                  remove-if  33
     nstring-upcase  48                    remove-if-not  33
     nth  25, 38                           remprop  29
     nthcdr  38                            repair  85
     null  56, 59                          repairf  85
     NUMBER  59                            replace  36
     numberp  56                           rest  37
     nunion  40                            restore  78, 79
     object  21, 59, 80                    return  64
     objectp  57                           return-from  64
     oddp  58                              reverse  32
     open  72                              room  79
     open-stream-p  57                     round  42
     OR  59, 60                            rplaca  41
     output-stream-p  57                   rplacd  41







     XLISP 2.1c                       INDEX                        Page 100


     SATISFIES  59                         symbol-plist  25, 27
     save  78                              symbol-value  25, 27
     search  33                            symbolp  56
     second  37                            system  81
     self  17, 21                          t  21
     send  17, 25, 54                      tagbody  64
     send-super  17, 54                    tan  44
     set  25                               tanh  44
     set-difference  40                    terpri  67
     set-exclusive-or  40                  third  37
     set-macro-character  66               throw  61
     setf  25                              time  79
     setq  25                              top-level  4, 76
     signum  43                            trace  76
     sin  44                               truncate  42
     sinh  44                              type-of  80
     some  32                              typep  59
     sort  41                              union  40
     sqrt  45                              unless  60
     step  83                              UNNAMED-STREAM  80
     strcat  49                            untrace  76
     STREAM  59                            unwind-protect  62
     streamp  57                           upper-case-p  50
     string  48, 80                        vector  31
     string-downcase  48                   when  60
     string-equal  49                      with-input-from-string  74
     string-greaterp  49                   with-open-file  73
     string-left-trim  48                  with-output-to-string  75
     string-lessp  49                      write-byte  73
     string-not-equal  49                  write-char  71
     string-not-greaterp  49               y-or-n-p  67
     string-not-lessp  49                  zerop  58
     string-right-trim  48
     string-trim  48
     string-upcase  48
     string/=  49
     string<  49
     string<=  49
     string=  49
     string>  49
     string>=  49
     stringp  57
     STRUCT  59
     sublis  39
     SUBR  80
     subseq  33
     subsetp  58
     subst  39
     SYMBOL  80
     symbol-function  25, 27
     symbol-name  27

