                                   CCHHAAPPTTEERR  55

                                  IInnppuutt//OOuuttppuutt

               The following functions are used to read from and write
          to external  devices  (e.g.  files)  and  programs  (through
          pipes).   All I/O goes through the lisp data type called the
          port.  A port may be open for either reading or writing, but
          usually  not both simultaneously (see _f_i_l_e_o_p_e_n ).  There are
          only a limited number of ports (20) and  they  will  not  be
          reclaimed  unless  they are _c_l_o_s_ed.  All ports are reclaimed
          by a _r_e_s_e_t_i_o call, but this drastic step won't be  necessary
          if the program closes what it uses.

               If  a port argument is not supplied to a function which
          requires one, or if a bad port argument  (such  as  nil)  is
          given,  then  FRANZ LISP will use the default port according
          to this scheme: If input is being done then the default port
          is  the  value  of  the symbol ppiippoorrtt and if output is being
          done then the default  port  is  the  value  of  the  symbol
          ppooppoorrtt.   Furthermore,  if  the value of piport or poport is
          not a valid port, then the standard input or standard output
          will be used, respectively.

               The  standard input and standard output are usually the
          keyboard and terminal display unless your job is running  in
          the  background  and  its  input or output is connected to a
          pipe.  All output which goes to  the  standard  output  will
          also  go  to  the port ppttppoorrtt if it is a valid port.  Output
          destined for the standard output will not reach the standard
          output  if  the symbol ^^ww is non nil (although it will still
          go to ppttppoorrtt if ppttppoorrtt is a valid port).

               Some of the  functions  listed  below  reference  files
          directly.   FRANZ  LISP  has borrowed a convenient shorthand
          notation from _/_b_i_n_/_c_s_h, concerning naming files.  If a  file
          name begins with ~ (tilde), and the symbol ttiillddee--eexxppaannssiioonn

          is  bound  to  something  other  than  nil,  then FRANZ LISP
          expands the file name.  It takes the  string  of  characters
          between  the  leading  tilde, and the first slash as a user-
          name.   Then,  that  initial  segment  of  the  filename  is
          replaced  by the home directory of the user.  The null user-
          name is taken to be the current user.

               FRANZ LISP keeps a cache of user home directory  infor-
          mation,  to  minimize  searching  the password file.  Tilde-
          expansion is performed in the  following  functions:  _c_f_a_s_l_,
          _c_h_d_i_r_, _f_a_s_l_, _f_f_a_s_l_, _f_i_l_e_o_p_e_n_, _i_n_f_i_l_e_, _l_o_a_d_, _o_u_t_f_i_l_e_, _p_r_o_b_e_f_,

          IInnppuutt//OOuuttppuutt                                             55--11

          IInnppuutt//OOuuttppuutt                                             55--22

          _s_y_s_:_a_c_c_e_s_s_, _s_y_s_:_u_n_l_i_n_k.

          ((ccffaassll    'st_file    'st_entry    'st_funcname    ['st_disc
          ['st_library]]))

               RETURNS: t

               SIDE EFFECT: This is used to load in a foreign function
                            (see S8.4).  The object  file  st_file  is
                            loaded  into  the  lisp  system.  St_entry
                            should be an entry point in the file  just
                            loaded.   The function binding of the sym-
                            bol s_funcname will be  set  to  point  to
                            st_entry,  so  that when the lisp function
                            s_funcname is  called,  st_entry  will  be
                            run.   st_disc  is  the  discipline  to be
                            given to s_funcname.  st_disc defaults  to
                            "subroutine"  if  it is not given or if it
                            is given as nil.  If  st_library  is  non-
                            null,  then  after  st_file is loaded, the
                            libraries  given  in  st_library  will  be
                            searched  to  resolve external references.
                            The form of st_library should be something
                            like  "-lm".  The C library  (" -lc " ) is
                            always searched so when  loading  in  a  C
                            file  you probably won't need to specify a
                            library.  For Fortran  files,  you  should
                            specify  "-lF77"  and if you are doing any
                            I/O, the library entry  should  be  "-lI77
                            -lF77".    For   Pascal  files  "-lpc"  is
                            required.

               NOTE: This function may be used to load the  output  of
                     the  assembler, C compiler, Fortran compiler, and
                     Pascal compiler  but NOT the lisp  compiler  (use
                     _f_a_s_l  for  that).   If  a  file has more than one
                     entry point, then use _g_e_t_a_d_d_r_e_s_s  to  locate  and
                     setup other foreign functions.
                     It  is  an  error  to  load in a file which has a
                     global entry point of the same name as  a  global
                     entry  point in the running lisp.  As soon as you
                     load in a  file  with  _c_f_a_s_l,  its  global  entry
                     points  become  part  of the lisp's entry points.
                     Thus you cannot _c_f_a_s_l  in  the  same  file  twice
                     unless  you  use  _r_e_m_o_v_e_a_d_d_r_e_s_s to change certain
                     global entry points to local entry points.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--33

          ((cclloossee 'p_port))

               RETURNS: t

               SIDE EFFECT: the specified port is drained and  closed,
                            releasing the port.

               NOTE: The  standard  defaults are not used in this case
                     since you probably never want to close the  stan-
                     dard output or standard input.

          ((ccpprriinnttff 'st_format 'xfst_val ['p_port]))

               RETURNS: xfst_val

               SIDE EFFECT: The  UNIX formatted output function printf
                            is called  with  arguments  st_format  and
                            xfst_val.   If  xfst_val  is a symbol then
                            its print name is passed to  printf.   The
                            format string may contain characters which
                            are just printed literally and it may con-
                            tain  special formatting commands preceded
                            by a percent sign.  The  complete  set  of
                            formatting  characters is described in the
                            UNIX manual.  Some useful ones are %d  for
                            printing a fixnum in decimal, %f or %e for
                            printing a flonum, and %s for  printing  a
                            character  string (or print name of a sym-
                            bol).

               EXAMPLE: _(_c_p_r_i_n_t_f _"_P_i _e_q_u_a_l_s _%_f_"  _3_._1_4_1_5_9_)  prints  `Pi
                        equals 3.14159'

          ((ddrraaiinn ['p_port]))

               RETURNS: nil

               SIDE EFFECT: If this is an output port then the charac-
                            ters in the output buffer are all sent  to
                            the device.  If this is an input port then
                            all pending characters are  flushed.   The
                            default  port  for  this  function  is the
                            default output port.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--44

          ((eexx [s_filename]))
          ((vvii [s_filename]))
          ((eexxll [s_filename]))
          ((vviill [s_filename]))

               RETURNS: nil

               SIDE EFFECT: The lisp system starts up an editor on the
                            file  named  as the argument.  It will try
                            appending .l to the file if it can't  find
                            it.   The  functions _e_x_l and _v_i_l will load
                            the file  after  you  finish  editing  it.
                            These  functions  will  also  remember the
                            name of the file  so  that  on  subsequent
                            invocations, you don't need to provide the
                            argument.

               NOTE: These functions do not evaluate their argument.

          ((ffaassll 'st_name ['st_mapf ['g_warn]]))

               WHERE:   st_mapf and g_warn default to nil.

               RETURNS: t if the function succeeded, nil otherwise.

               SIDE EFFECT: this function is designed to  load  in  an
                            object file generated by the lisp compiler
                            Liszt.  File names for object  files  usu-
                            ally end in `.o', so _f_a_s_l will append `.o'
                            to st_name (if it is not already present).
                            If st_mapf is non nil, then it is the name
                            of the map file to create.  _F_a_s_l writes in
                            the  map  file  the names and addresses of
                            the functions it loads and defines.   Nor-
                            mally  the map file is created (i.e. trun-
                            cated    if    it    exists),    but    if
                            _(_s_s_t_a_t_u_s _a_p_p_e_n_d_m_a_p _t_) is done then the map
                            file will be appended.  If g_warn  is  non
                            nil  and if a function is loaded from  the
                            file which  is  already  defined,  then  a
                            warning message will be printed.

               NOTE: _f_a_s_l  only looks in the current directory for the
                     file to load.  The function _l_o_a_d looks through  a
                     user-supplied  search  path and will call _f_a_s_l if
                     it finds a file with the same  root  name  and  a
                     `.o' extension.  In  most cases the user would be
                     better off using the function  _l_o_a_d  rather  than
                     calling _f_a_s_l directly.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--55

          ((ffffaassll   'st_file   'st_entry  'st_funcname  ['st_discipline
          ['st_library]]))

               RETURNS: the binary object created.

               SIDE EFFECT: the Fortran object file st_file is  loaded
                            into  the lisp system.  St_entry should be
                            an entry point in the file just loaded.  A
                            binary  object  will  be  created  and its
                            entry  field  will  be  set  to  point  to
                            st_entry.   The  discipline  field  of the
                            binary will be  set  to  st_discipline  or
                            "subroutine" by default.  If st_library is
                            present and non-null, then  after  st_file
                            is   loaded,   the   libraries   given  in
                            st_library will  be  searched  to  resolve
                            external    references.    The   form   of
                            st_library should be something  like  "-lS
                            -ltermcap".   In  any  case,  the standard
                            Fortran libraries will be searched also to
                            resolve external references.

               NOTE: in  F77  on Unix, the entry point for the fortran
                     function foo is named `_foo_'.

          ((ffiilleeppooss 'p_port ['x_pos]))

               RETURNS: the current position in the file if  x_pos  is
                        not given or else x_pos if x_pos is given.

               SIDE EFFECT: If  x_pos  is  given,  the next byte to be
                            read or written to the  port  will  be  at
                            position x_pos.

          ((ffiilleessttaatt 'st_filename))

               RETURNS: a  vector containing various numbers which the
                        UNIX operating system assigns  to  files.   if
                        the  file  doesn't exist, an error is invoked.
                        Use _p_r_o_b_e_f to determine if the file exists.

               NOTE: The individual entries can be accesed by mnemonic
                     functions of the form filestat:_f_i_e_l_d, where field
                     may be  any  of  atime,  ctime,  dev,  gid,  ino,
                     mode,mtime,  nlink,  rdev,  size, type, uid.  See
                     the UNIX programmers manual for a  more  detailed
                     description of these quantities.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--66

          ((ffllaattcc 'g_form ['x_max]))

               RETURNS: the  number  of  characters  required to print
                        g_form using _p_a_t_o_m.  If x_max is given and  if
                        _f_l_a_t_c  determines  that it will return a value
                        greater than  x_max,  then  it  gives  up  and
                        returns  the  current  value  it has computed.
                        This is useful if you just want to see  if  an
                        expression is larger than a certain size.

          ((ffllaattssiizzee 'g_form ['x_max]))

               RETURNS: the  number  of  characters  required to print
                        g_form using _p_r_i_n_t.  The meaning of  x_max  is
                        the same as for flatc.

               NOTE: Currently  this  just _e_x_p_l_o_d_e's g_form and checks
                     its length.

          ((ffiilleeooppeenn 'st_filename 'st_mode))

               RETURNS: a port for reading or  writing  (depending  on
                        st_mode) the file st_name.

               SIDE EFFECT: the  given  file  is opened (or created if
                            opened for  writing  and  it  doesn't  yet
                            exist).

               NOTE: this function call provides a direct interface to
                     the operating system's fopen function.  The  mode
                     may be more than just "r" for read, "w" for write
                     or "a" for append.  The modes "r+", "w+" and "a+"
                     permit  both  reading  and writing on a port pro-
                     vided that  _f_s_e_e_k  is  done  between  changes  in
                     direction.   See  the  UNIX manual description of
                     fopen for more details.  This  routine  does  not
                     look through a search path for a given file.

          ((ffsseeeekk 'p_port 'x_offset 'x_flag))

               RETURNS: the position in the file after the function is
                        performed.

               SIDE EFFECT: this  function  positions  the  read/write
                            pointer before a certain byte in the file.
                            If x_flag is 0 then the pointer is set  to
                            x_offset  bytes  from the beginning of the
                            file.  If x_flag is 1 then the pointer  is
                            set  to  x_offset  bytes  from the current
                            location in the file.  If x_flag is 2 then
                            the  pointer is set to x_offset bytes from
                            the end of the file.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--77

          ((iinnffiillee 's_filename))

               RETURNS: a port ready to read s_filename.

               SIDE EFFECT: this tries to open s_filename  and  if  it
                            cannot  or if there are no ports available
                            it gives an error message.

               NOTE: to allow your program to continue on a  file-not-
                     found error, you can use something like:
                     _(_c_o_n_d  _(_(_n_u_l_l  _(_s_e_t_q  _m_y_p_o_r_t _(_c_a_r _(_e_r_r_s_e_t _(_i_n_f_i_l_e
                     _n_a_m_e_) _n_i_l_)_)_)_)
                                 _(_p_a_t_o_m _'_"_c_o_u_l_d_n_'_t _o_p_e_n _t_h_e _f_i_l_e_"_)_)_)
                     which will set myport to the port to read from if
                     the  file  exists  or  will print a message if it
                     couldn't open it and also set myport to nil.   To
                     simply determine if a file exists, use _p_r_o_b_e_f.

          ((llooaadd 's_filename ['st_map ['g_warn]]))

               RETURNS: t

               NOTE: The  function  of _l_o_a_d has changed since previous
                     releases of FRANZ LISP and the following descrip-
                     tion should be read carefully.

               SIDE EFFECT: _l_o_a_d  now serves the function of both _f_a_s_l
                            and the old _l_o_a_d.  _L_o_a_d will search a user
                            defined  search  path for a lisp source or
                            object file with the  filename  s_filename
                            (with  the  extension  .l  or  .o added as
                            appropriate).  The search path which  _l_o_a_d
                            uses  is the value of _(_s_t_a_t_u_s _l_o_a_d_-_s_e_a_r_c_h_-
                            _p_a_t_h_).  The default is (|.| /usr/lib/lisp)
                            which  means look in the current directory
                            first and then  /usr/lib/lisp.   The  file
                            which  _l_o_a_d  looks for depends on the last
                            two   characters   of   s_filename.     If
                            s_filename  ends  with ".l" then _l_o_a_d will
                            only look for a file name  s_filename  and
                            will  assume  that  this  is  a FRANZ LISP
                            source file.  If s_filename ends with ".o"
                            then  _l_o_a_d will only look for a file named
                            s_filename and will assume that this is  a
                            FRANZ  LISP  object  file to be _f_a_s_led in.
                            Otherwise,  _l_o_a_d  will  first   look   for
                            s_filename.o,    then   s_filename.l   and
                            finally s_filename itself.   If  it  finds
                            s_filename.o  it  will assume that this is
                            an object file, otherwise it  will  assume
                            that  it is a source file.  An object file
                            is loaded using _f_a_s_l and a source file  is
                            loaded by reading and evaluating each form

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--88

                            in  the  file.   The  optional   arguments
                            st_map  and  g_warn  are  passed  to  _f_a_s_l
                            should _f_a_s_l be called.

               NOTE: _l_o_a_d requires a port to open the file s_filename.
                     It  then  lambda  binds the symbol piport to this
                     port and reads and evaluates the forms.

          ((mmaakkeerreeaaddttaabbllee ['s_flag]))

               WHERE:   if s_flag is not present it is assumed  to  be
                        nil.

               RETURNS: a readtable equal to the original readtable if
                        s_flag is non-null, or else equal to the  cur-
                        rent  readtable.  See chapter 7 for a descrip-
                        tion of readtables and their uses.

          ((mmssgg [l_option ...] ['g_msg ...]))

               NOTE: This function is intended for printing short mes-
                     sages.  Any of the arguments or options presented
                     can be used any number of times,  in  any  order.
                     The  messages  themselves  (g_msg) are evaluated,
                     and then they are transmitted  to  _p_a_t_o_m.   Typi-
                     cally,  they are strings, which evaluate to them-
                     selves.  The options are interpreted specially:

              ____________________________________________________

              _m_s_g _O_p_t_i_o_n _S_u_m_m_a_r_y

              _(_P _p___p_o_r_t_n_a_m_e_)           causes subsequent output to go to the port p_portname
                                  (port should be opened previously)

              _B              print a single blank.

              _(_B _'_n___b_)            evaluate n_b and print that many blanks.

              _N              print a single by calling _t_e_r_p_r.

              _(_N _'_n___n_)            evaluate n_n and transmit
                                  that many newlines to the stream.

              _D              _d_r_a_i_n the current port.
              ____________________________________________________

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                             55--99

          ((nnwwrriittnn ['p_port]))

               RETURNS: the number of characters in the buffer of  the
                        given port but not yet written out to the file
                        or device.  The buffer  is  flushed  automati-
                        cally when filled, or when _t_e_r_p_r is called.

          ((oouuttffiillee 's_filename ['st_type]))

               RETURNS: a port or nil

               SIDE EFFECT: this opens a port to write s_filename.  If
                            st_type is given and if it is  a symbol or
                            string  whose  name  begins with `a', then
                            the file will be opened  in  append  mode,
                            that  is  the current contents will not be
                            lost and the next data will be written  at
                            the  end of the file.  Otherwise, the file
                            opened  is  truncated  by  _o_u_t_f_i_l_e  if  it
                            existed  beforehand.  If there are no free
                            ports, outfile returns nil.  If one cannot
                            write  on  s_filename,  an  error  is sig-
                            nalled.

          ((ppaattoomm 'g_exp ['p_port]))

               RETURNS: g_exp

               SIDE EFFECT: g_exp is printed to the given port or  the
                            default  port.   If  g_exp  is a symbol or
                            string, the print name is printed  without
                            any escape characters around special char-
                            acters in the print name.  If g_exp  is  a
                            list  then  _p_a_t_o_m  has  the same effect as
                            _p_r_i_n_t.

          ((ppnnttlleenn 'xfs_arg))

               RETURNS: the  number  of  characters  needed  to  print
                        xfs_arg.

          ((ppoorrttpp 'g_arg))

               RETURNS: t iff g_arg is a port.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                            55--1100

          ((pppp [l_option] s_name1 ...))

               RETURNS: t

               SIDE EFFECT: If  s_name_i  has a function binding, it is
                            pretty-printed, otherwise if s_name_i has a
                            value  then  that is pretty-printed.  Nor-
                            mally the  output  of  the  pretty-printer
                            goes  to  the standard output port poport.
                            The options allow you to redirect it.

              ____________________________________________________

              _P_P _O_p_t_i_o_n _S_u_m_m_a_r_y

              _(_F _s___f_i_l_e_n_a_m_e_)           direct future printing to s_filename

              _(_P _p___p_o_r_t_n_a_m_e_)           causes output to go to the port p_portname
                                  (port should be opened previously)

              _(_E _g___e_x_p_r_e_s_s_i_o_n_)         evaluate g_expression and don't print
              ____________________________________________________

          ((pprriinncc 'g_arg ['p_port]))

               EQUIVALENT TO: patom.

          ((pprriinntt 'g_arg ['p_port]))

               RETURNS: nil

               SIDE EFFECT: prints g_arg on the  port  p_port  or  the
                            default port.

          ((pprroobbeeff 'st_file))

               RETURNS: t iff the file st_file exists.

               NOTE: Just  because it exists doesn't mean you can read
                     it.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                            55--1111

          ((pppp--ffoorrmm 'g_form ['p_port]))

               RETURNS: t

               SIDE EFFECT: g_form  is  pretty-printed  to  the   port
                            p_port (or poport if p_port is not given).
                            This is the  function which _p_p uses.   _p_p_-
                            _f_o_r_m  does  not  look for function defini-
                            tions or  values  of  variables,  it  just
                            prints out the form it is given.

               NOTE: This is useful as a top-level-printer, c.f.  _t_o_p_-
                     _l_e_v_e_l in Chapter 6.

          ((rraattoomm ['p_port ['g_eof]]))

               RETURNS: the next atom read from the given  or  default
                        port.   On end of file, g_eof (default nil) is
                        returned.

          ((rreeaadd ['p_port ['g_eof]]))

               RETURNS: the next lisp expression read from  the  given
                        or  default  port.   On  end  of  file,  g_eof
                        (default nil) is returned.

               NOTE: An error will occur if the reader is given an ill
                     formed  expression.  The most common error is too
                     many right parentheses (note  that  this  is  not
                     considered an error in Maclisp).

          ((rreeaaddcc ['p_port ['g_eof]]))

               RETURNS: the  next  character  read  from  the given or
                        default port.  On end of file, g_eof  (default
                        nil) is returned.

          ((rreeaaddlliisstt 'l_arg))

               RETURNS: the  lisp  expression  read  from  the list of
                        characters in l_arg.

          ((rreemmoovveeaaddddrreessss 's_name1 ['s_name2 ...]))

               RETURNS: nil

               SIDE EFFECT: the entries for the s_name_i  in  the  Lisp
                            symbol  table are removed.  This is useful
                            if you wish to _c_f_a_s_l or _f_f_a_s_l  in  a  file
                            twice, since it is illegal for a symbol in
                            the file you are loading to already  exist
                            in the lisp symbol table.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                            55--1122

          ((rreesseettiioo))

               RETURNS: nil

               SIDE EFFECT: all  ports except the standard input, out-
                            put and error are closed.

          ((sseettssyynnttaaxx 's_symbol 's_synclass ['ls_func]))

               RETURNS: t

               SIDE EFFECT: this sets the code for s_symbol to sx_code
                            in  the  current readtable.  If s_synclass
                            is _m_a_c_r_o or _s_p_l_i_c_i_n_g then ls_func  is  the
                            associated  function.   See  Chapter  7 on
                            the reader for more details.

          ((ssllooaadd 's_file))

               SIDE EFFECT: the file s_file (in the current directory)
                            is  opened  for  reading  and each form is
                            read, printed and evaluated.  If the  form
                            is  recognizable as a function definition,
                            only its name will be  printed,  otherwise
                            the whole form is printed.

               NOTE: This  function  is  useful when a file refuses to
                     load because of a syntax error and you would like
                     to narrow down where the error is.

          ((ttaabb 'x_col ['p_port]))

               SIDE EFFECT: enough  spaces are printed to put the cur-
                            sor on column x_col.   If  the  cursor  is
                            beyond  x_col  to  start  with, a _t_e_r_p_r is
                            done first.

          ((tteerrpprr ['p_port]))

               RETURNS: nil

               SIDE EFFECT: a terminate line   character  sequence  is
                            sent  to  the  given  port  or the default
                            port.  This will also drain the port.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                            55--1133

          ((tteerrpprrii ['p_port]))

               EQUIVALENT TO: terpr.

          ((ttiillddee--eexxppaanndd 'st_filename))

               RETURNS: a symbol whose pname is the tilde-expansion of
                        the  argument,  (as discussed at the beginning
                        of this chapter).  If the  argument  does  not
                        begin  with  a  tilde,  the argument itself is
                        returned.

          ((ttyyii ['p_port]))

               RETURNS: the fixnum representation of the next  charac-
                        ter read.  On end of file, -1 is returned.

          ((ttyyiippeeeekk ['p_port]))

               RETURNS: the  fixnum representation of the next charac-
                        ter to be read.

               NOTE: This does not actually  read  the  character,  it
                     just peeks at it.

          ((ttyyoo 'x_char ['p_port]))

               RETURNS: x_char.

               SIDE EFFECT: the  character whose fixnum representation
                            is x_code, is printed as a  on  the  given
                            output port or the default output port.

          ((uunnttyyii 'x_char ['p_port]))

               SIDE EFFECT: x_char  is put back in the input buffer so
                            a subsequent _t_y_i  or  _r_e_a_d  will  read  it
                            first.

               NOTE: a maximum of one character may be put back.

          ((uusseerrnnaammee--ttoo--ddiirr 'st_name))

               RETURNS: the  home  directory  of  the given user.  The
                        result  is  stored,  to  avoid   unnecessarily
                        searching the password file.

                                             Printed: October 16, 1993

          IInnppuutt//OOuuttppuutt                                            55--1144

          ((zzaapplliinnee))

               RETURNS: nil

               SIDE EFFECT: all  characters  up  to  and including the
                            line termination character  are  read  and
                            discarded  from  the  last  port  used for
                            input.

               NOTE: this is used as the macro function for the  semi-
                     colon character when it acts as a comment charac-
                     ter.

                                             Printed: October 16, 1993


                         CHAPTER  7

                      The Lisp Reader

   7.1.  Introduction

           The _r_e_a_d function is responsible for converting a
      stream  of characters into a Lisp expression.  _R_e_a_d is
      table driven and the table it uses is called a  _r_e_a_d_t_-
      _a_b_l_e.  The _p_r_i_n_t function does the inverse of _r_e_a_d; it
      converts a Lisp expression into a  stream  of  charac-
      ters.   Typically the conversion is done in such a way
      that if that stream of characters were read  by  _r_e_a_d,
      the  result  would  be  an expression equal to the one
      _p_r_i_n_t was given.  _P_r_i_n_t must also refer to the  readt-
      able  in  order to determine how to format its output.
      The _e_x_p_l_o_d_e function, which returns a list of  charac-
      ters  rather  than  printing them,  must also refer to
      the readtable.

           A readtable is  created  with  the  _m_a_k_e_r_e_a_d_t_a_b_l_e
      function,  modified  with  the  _s_e_t_s_y_n_t_a_x function and
      interrogated with the _g_e_t_s_y_n_t_a_x function.  The  struc-
      ture  of  a  readtable  is  hidden  from the user  - a
      readtable should only be manipulated  with  the  three
      functions mentioned above.

           There is one distinguished readtable  called  the
      _c_u_r_r_e_n_t  _r_e_a_d_t_a_b_l_e  whose  value determines what _r_e_a_d,
      _p_r_i_n_t and _e_x_p_l_o_d_e do.  The current  readtable  is  the
      value  of  the symbol _r_e_a_d_t_a_b_l_e.  Thus it is  possible
      to rapidly change the current syntax by lambda binding
      a  different  readtable to the symbol _r_e_a_d_t_a_b_l_e.  When
      the binding is undone, the syntax reverts to  its  old
      form.

   7.2.  Syntax Classes

           The readtable describes how each of the 128 ascii
      characters   should  be  treated  by  the  reader  and
      printer.  Each character belongs  to  a  _s_y_n_t_a_x  _c_l_a_s_s
      which has three properties:

      character class -
           Tells what the reader should do when it sees this

The Lisp Reader                                          7-1

The Lisp Reader                                          7-2

           character.  There are a large number of character
           classes. They are described below.

      separator -
           Most types of tokens the  reader  constructs  are
           one  character  long.   Four  token types have an
           arbitrary length:  number  (1234),  symbol  print
           name   (franz),   escaped   symbol   print   name
           (|franz|), and string ("franz").  The reader  can
           easily  determine  when it has come to the end of
           one of the last two types: it just looks for  the
           matching  delimiter (| or ").  When the reader is
           reading a number or symbol print name,  it  stops
           reading  when  it  comes  to a character with the
           _s_e_p_a_r_a_t_o_r property.  The separator  character  is
           pushed back into the input stream and will be the
           first character read when the  reader  is  called
           again.

      escape -
           Tells the printer when to put  escapes  in  front
           of, or around, a symbol whose print name contains
           this character.  There are  three  possibilities:
           always escape a symbol with this character in it,
           only escape a symbol if this is the only  charac-
           ter  in  the  symbol, and only escape a symbol if
           this  is  the  first  character  in  the  symbol.
           [note:  The  printer  will always escape a symbol
           which, if printed out, would look  like  a  valid
           number.]

           When the Lisp system is built, Lisp code is added
      to  a  C-coded kernel and the result becomes the stan-
      dard lisp system.  The readtable  present  in  the  C-
      coded  kernel,  called the _r_a_w _r_e_a_d_t_a_b_l_e, contains the
      bare necessities for reading in Lisp code.  During the
      construction  of  the  complete Lisp system, a copy is
      made of the raw readtable and then the copy  is  modi-
      fied  by  adding macro characters.  The result is what
      is called the _s_t_a_n_d_a_r_d _r_e_a_d_t_a_b_l_e.  When a  new  readt-
      able  is created with _m_a_k_e_r_e_a_d_t_a_b_l_e, a copy is made of
      either the raw  readtable  or  the  current  readtable
      (which is likely to be the standard readtable).

   7.3.  Reader Operations

           The reader has a very simple  algorithm.   It  is
      either  _s_c_a_n_n_i_n_g  for  a token, _c_o_l_l_e_c_t_i_n_g a token, or
      _p_r_o_c_e_s_s_i_n_g a token.  Scanning involves reading charac-
      ters  and throwing away those which don't start tokens
      (such as blanks and tabs).  Collecting means gathering

                                   Printed: January 31, 1984

The Lisp Reader                                          7-3

      the  characters  which  make up a token into a buffer.
      Processing  may  involve  creating  symbols,  strings,
      lists,  fixnums,  bignums or flonums or calling a user
      written function called a character macro.

           The components of the syntax class determine when
      the  reader  switches between the scanning, collecting
      and processing states.  The reader will continue scan-
      ning  as long as the character class of the characters
      it reads is _c_s_e_p_a_r_a_t_o_r.  When  it  reads  a  character
      whose character class is not _c_s_e_p_a_r_a_t_o_r it stores that
      character in its  buffer  and  begins  the  collecting
      phase.

           If the character class of that first character is
      _c_c_h_a_r_a_c_t_e_r,  _c_n_u_m_b_e_r, _c_p_e_r_i_o_d, or _c_s_i_g_n.  then it will
      continue collecting until it  runs  into  a  character
      whose  syntax class has the _s_e_p_a_r_a_t_o_r property.  (That
      last character will be  pushed  back  into  the  input
      buffer  and  will  be  the  first  character read next
      time.) Now the reader goes into the processing  phase,
      checking  to  see  if the token it read is a number or
      symbol.  It is important to note that  after the first
      character  is  collected  the  component of the syntax
      class which tells the reader to   stop  collecting  is
      the _s_e_p_a_r_a_t_o_r property, not the character class.

           If the character class  of  the  character  which
      stopped  the  scanning  is  not  _c_c_h_a_r_a_c_t_e_r,  _c_n_u_m_b_e_r,
      _c_p_e_r_i_o_d, or _c_s_i_g_n.  then  the  reader  processes  that
      character    immediately.    The   character   classes
      _c_s_i_n_g_l_e-_m_a_c_r_o,  _c_s_i_n_g_l_e-_s_p_l_i_c_i_n_g-_m_a_c_r_o,  and  _c_s_i_n_g_l_e-
      _i_n_f_i_x-_m_a_c_r_o  will act like _c_c_h_a_r_a_c_t_e_r if the following
      token is not a _s_e_p_a_r_a_t_o_r.   The  processing  which  is
      done  for  a  given  character  class  is described in
      detail in the next section.

   7.4.  Character Classes

_c_c_h_a_r_a_c_t_e_r    raw readtable:A-Z a-z ^H !#$%&*,/:;<=>?@^_`{}~
            standard readtable:A-Z a-z ^H !$%&*/:;<=>?@^_{}~
      A normal character.

_c_n_u_m_b_e_r                                    raw readtable:0-9
                                      standard readtable:0-9
      This type is a digit. The syntax for an integer  (fix-
      num  or  bignum)  is  a  string  of _c_n_u_m_b_e_r characters
      optionally followed by a _c_p_e_r_i_o_d.  If the  digits  are
      not  followed  by a _c_p_e_r_i_o_d, then they are interpreted

                                   Printed: January 31, 1984

The Lisp Reader                                          7-4

      in base _i_b_a_s_e which must be eight or ten.  The  syntax
      for  a  floating  point  number is either zero or more
      _c_n_u_m_b_e_r's followed by a _c_p_e_r_i_o_d and then  followed  by
      one  or  more  _c_n_u_m_b_e_r's.  A floating point number may
      also be  an integer or floating point number  followed
      by 'e' or 'd', an optional '+' or '-' and then zero or
      more _c_n_u_m_b_e_r's.

_c_s_i_g_n                                       raw readtable:+-
                                       standard readtable:+-
      A leading sign  for  a  number.  No  other  characters
      should be given this class.

_c_l_e_f_t_-_p_a_r_e_n                                  raw readtable:(
                                        standard readtable:(
      A left parenthesis.  Tells the reader to begin forming
      a list.

_c_r_i_g_h_t_-_p_a_r_e_n                                 raw readtable:)
                                        standard readtable:)
      A right parenthesis.  Tells the  reader  that  it  has
      reached the end of a list.

_c_l_e_f_t_-_b_r_a_c_k_e_t                                raw readtable:[
                                        standard readtable:[
      A left bracket.  Tells the reader that it should begin
      forming a list.  See the description of _c_r_i_g_h_t-_b_r_a_c_k_e_t
      for the difference between  cleft-bracket  and  cleft-
      paren.

_c_r_i_g_h_t_-_b_r_a_c_k_e_t                               raw readtable:]
                                        standard readtable:]
      A right bracket.  A _c_r_i_g_h_t-_b_r_a_c_k_e_t finishes the forma-
      tion of the current list and all enclosing lists until
      it finds one which  begins  with  a  _c_l_e_f_t-_b_r_a_c_k_e_t  or
      until it reaches the top level list.

_c_p_e_r_i_o_d                                      raw readtable:.
                                        standard readtable:.
      The period is used to separate element of a cons  cell
      [e.g.  (a . (b . nil)) is the same as (a b)].  _c_p_e_r_i_o_d
      is also used in numbers as described above.

_c_s_e_p_a_r_a_t_o_r                     raw readtable:^I-^M esc space
                          standard readtable:^I-^M esc space
      Separates tokens.  When the reader is scanning,  these

                                   Printed: January 31, 1984

The Lisp Reader                                          7-5

      character  are  passed over.  Note: there is a differ-
      ence between the _c_s_e_p_a_r_a_t_o_r character  class  and  the
      _s_e_p_a_r_a_t_o_r property of a syntax class.

_c_s_i_n_g_l_e_-_q_u_o_t_e                                raw readtable:'
                                        standard readtable:'
      This causes _r_e_a_d to be called recursively and the list
      (quote <value read>) to be returned.

_c_s_y_m_b_o_l_-_d_e_l_i_m_i_t_e_r                            raw readtable:|
                                        standard readtable:|
      This causes the reader to begin collecting  characters
      and  to  stop  only  when  another  identical _c_s_y_m_b_o_l-
      _d_e_l_i_m_i_t_e_r is seen. The only way to escape  a  _c_s_y_m_b_o_l-
      _d_e_l_i_m_i_t_e_r within a symbol name is with a _c_e_s_c_a_p_e char-
      acter.  The collected characters are converted into  a
      string which becomes the print name of a symbol.  If a
      symbol with an identical print  name  already  exists,
      then  the  allocation is not done, rather the existing
      symbol is used.

_c_e_s_c_a_p_e                                      raw readtable:\
                                        standard readtable:\
      This causes the  next  character  to  read  in  to  be
      treated  as  a  vcharacter.   A character whose syntax
      class is vcharacter has a character  class  _c_c_h_a_r_a_c_t_e_r
      and  does  not  have the _s_e_p_a_r_a_t_o_r property so it will
      not separate symbols.

_c_s_t_r_i_n_g_-_d_e_l_i_m_i_t_e_r                            raw readtable:"
                                        standard readtable:"
      This is  the  same  as  _c_s_y_m_b_o_l-_d_e_l_i_m_i_t_e_r  except  the
      result is returned as a string instead of a symbol.

_c_s_i_n_g_l_e_-_c_h_a_r_a_c_t_e_r_-_s_y_m_b_o_l                  raw readtable:none
                                     standard readtable:none
      This returns a symbol whose print name is the the sin-
      gle character which has been collected.

_c_m_a_c_r_o                                    raw readtable:none
                                       standard readtable:`,
      The reader calls the macro  function  associated  with
      this  character  and the current readtable, passing it
      no arguments.  The result of the macro is added to the
      structure the reader is building, just as if that form
      were directly read by the  reader.   More  details  on
      macros are provided below.

                                   Printed: January 31, 1984

The Lisp Reader                                          7-6

_c_s_p_l_i_c_i_n_g_-_m_a_c_r_o                           raw readtable:none
                                       standard readtable:#;
      A _c_s_p_l_i_c_i_n_g-_m_a_c_r_o differs from a _c_m_a_c_r_o in the way the
      result  is incorporated in the structure the reader is
      building.  A _c_s_p_l_i_c_i_n_g-_m_a_c_r_o must  return  a  list  of
      forms (possibly empty).  The reader acts as if it read
      each element of the list itself without the  surround-
      ing parenthesis.

_c_s_i_n_g_l_e_-_m_a_c_r_o                             raw readtable:none
                                     standard readtable:none
      This causes to reader to check the next character.  If
      it is a _c_s_e_p_a_r_a_t_o_r then this acts like a _c_m_a_c_r_o.  Oth-
      erwise, it acts like a _c_c_h_a_r_a_c_t_e_r.

_c_s_i_n_g_l_e_-_s_p_l_i_c_i_n_g_-_m_a_c_r_o                    raw readtable:none
                                     standard readtable:none
      This is triggered like  a  _c_s_i_n_g_l_e-_m_a_c_r_o  however  the
      result is spliced in like a _c_s_p_l_i_c_i_n_g-_m_a_c_r_o.

_c_i_n_f_i_x_-_m_a_c_r_o                              raw readtable:none
                                     standard readtable:none
      This is differs from a _c_m_a_c_r_o in that the macro  func-
      tion is passed a form representing what the reader has
      read so far. The result of the macro replaces what the
      reader had read so far.

_c_s_i_n_g_l_e_-_i_n_f_i_x_-_m_a_c_r_o                       raw readtable:none
                                     standard readtable:none
      This differs from the _c_i_n_f_i_x-_m_a_c_r_o in that  the  macro
      will  only be triggered if the character following the
      _c_s_i_n_g_l_e-_i_n_f_i_x-_m_a_c_r_o character is a _c_s_e_p_a_r_a_t_o_r.

_c_i_l_l_e_g_a_l                 raw readtable:^@-^G^N-^Z^\-^_rubout
                    standard readtable:^@-^G^N-^Z^\-^_rubout
      The characters cause the reader to signal an error  if
      read.

   7.5.  Syntax Classes

           The readtable maps each character into  a  syntax
      class.   The  syntax  class  contains  three pieces of
      information: the character class, whether  this  is  a
      separator,  and  the escape properties.  The first two
      properties are used by the reader,  the  last  by  the
      printer  (and  _e_x_p_l_o_d_e).   The initial lisp system has

                                   Printed: January 31, 1984

The Lisp Reader                                          7-7

      the following syntax classes defined.   The  user  may
      add  syntax  classes  with _a_d_d-_s_y_n_t_a_x-_c_l_a_s_s.  For each
      syntax class, we list the properties of the class  and
      which  characters  have  this syntax class by default.
      More information about each syntax class can be  found
      under  the description of the syntax class's character
      class.

vcharacter    raw readtable:A-Z a-z ^H !#$%&*,/:;<=>?@^_`{}~
_c_c_h_a_r_a_c_t_e_r  standard readtable:A-Z a-z ^H !$%&*/:;<=>?@^_{}~

vnumber                                    raw readtable:0-9
_c_n_u_m_b_e_r                               standard readtable:0-9

vsign                                       raw readtable:+-
_c_s_i_g_n                                  standard readtable:+-

vleft-paren                                  raw readtable:(
_c_l_e_f_t_-_p_a_r_e_n                             standard readtable:(
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vright-paren                                 raw readtable:)
_c_r_i_g_h_t_-_p_a_r_e_n                            standard readtable:)
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vleft-bracket                                raw readtable:[
_c_l_e_f_t_-_b_r_a_c_k_e_t                           standard readtable:[
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vright-bracket                               raw readtable:]
_c_r_i_g_h_t_-_b_r_a_c_k_e_t                          standard readtable:]
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vperiod                                      raw readtable:.
_c_p_e_r_i_o_d                                 standard readtable:.
_e_s_c_a_p_e_-_w_h_e_n_-_u_n_i_q_u_e

vseparator                     raw readtable:^I-^M esc space
_c_s_e_p_a_r_a_t_o_r                standard readtable:^I-^M esc space
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r
9

9                                   Printed: January 31, 1984

The Lisp Reader                                          7-8

vsingle-quote                                raw readtable:'
_c_s_i_n_g_l_e_-_q_u_o_t_e                           standard readtable:'
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vsymbol-delimiter                            raw readtable:|
_c_s_i_n_g_l_e_-_d_e_l_i_m_i_t_e_r                       standard readtable:|
_e_s_c_a_p_e_-_a_l_w_a_y_s

vescape                                      raw readtable:\
_c_e_s_c_a_p_e                                 standard readtable:\
_e_s_c_a_p_e_-_a_l_w_a_y_s

vstring-delimiter                            raw readtable:"
_c_s_t_r_i_n_g_-_d_e_l_i_m_i_t_e_r                       standard readtable:"
_e_s_c_a_p_e_-_a_l_w_a_y_s

vsingle-character-symbol                  raw readtable:none
_c_s_i_n_g_l_e_-_c_h_a_r_a_c_t_e_r_-_s_y_m_b_o_l             standard readtable:none
_s_e_p_a_r_a_t_o_r

vmacro                                    raw readtable:none
_c_m_a_c_r_o                                 standard readtable:`,
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vsplicing-macro                           raw readtable:none
_c_s_p_l_i_c_i_n_g_-_m_a_c_r_o                        standard readtable:#;
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vsingle-macro                             raw readtable:none
_c_s_i_n_g_l_e_-_m_a_c_r_o                        standard readtable:none
_e_s_c_a_p_e_-_w_h_e_n_-_u_n_i_q_u_e

vsingle-splicing-macro                    raw readtable:none
_c_s_i_n_g_l_e_-_s_p_l_i_c_i_n_g_-_m_a_c_r_o               standard readtable:none
_e_s_c_a_p_e_-_w_h_e_n_-_u_n_i_q_u_e

vinfix-macro                              raw readtable:none
_c_i_n_f_i_x_-_m_a_c_r_o                         standard readtable:none
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

vsingle-infix-macro                       raw readtable:none
_c_s_i_n_g_l_e_-_i_n_f_i_x_-_m_a_c_r_o                  standard readtable:none
_e_s_c_a_p_e_-_w_h_e_n_-_u_n_i_q_u_e

                                   Printed: January 31, 1984

The Lisp Reader                                          7-9

villegal                 raw readtable:^@-^G^N-^Z^\-^_rubout
_c_i_l_l_e_g_a_l            standard readtable:^@-^G^N-^Z^\-^_rubout
_e_s_c_a_p_e_-_a_l_w_a_y_s
_s_e_p_a_r_a_t_o_r

   7.6.  Character Macros

           Character macros are user written functions which
      are  executed  during  the reading process.  The value
      returned by a character macro may or may not  be  used
      by  the reader, depending on the type of macro and the
      value returned.  Character macros are always  attached
      to a single character with the _s_e_t_s_y_n_t_a_x function.

      7.6.1.  Types   There are  three  types  of  character
         macros:  normal,  splicing  and infix.  These types
         differ in the arguments they are given or  in  what
         is done with the result they return.

         7.6.1.1.  Normal

                 A normal macro is passed no arguments.  The
            value  returned by a normal macro is simply used
            by the reader  as  if  it  had  read  the  value
            itself.   Here  is  an  example of a macro which
            returns the abbreviation for a given state.

    ____________________________________________________

    ->(_d_e_f_u_n _s_t_a_t_e_a_b_b_r_e_v _n_i_l
         (_c_d_r (_a_s_s_q (_r_e_a_d) '((_c_a_l_i_f_o_r_n_i_a . _c_a) (_p_e_n_n_s_y_l_v_a_n_i_a . _p_a)))))
    stateabbrev
    -> (_s_e_t_s_y_n_t_a_x '_\! '_v_m_a_c_r_o '_s_t_a_t_e_a_b_b_r_e_v)
    t
    -> '( ! _c_a_l_i_f_o_r_n_i_a ! _w_y_o_m_i_n_g ! _p_e_n_n_s_y_l_v_a_n_i_a)
    (ca nil pa)
    ____________________________________________________

Notice what happened to
 ! _w_y_o_m_i_n_g.  Since it wasn't in the  table,  the  associated
function  returned  nil.   The creator of the macro may have
wanted to leave the list alone, in such a case, but couldn't

                                   Printed: January 31, 1984

The Lisp Reader                                         7-10

with  this  type  of  reader  macro.   The  splicing  macro,
described next, allows a character macro function to  return
a value that is ignored.

         7.6.1.2.  Splicing

                 The value returned from  a  splicing  macro
            must  be  a  list  or nil.  If the value is nil,
            then the value is ignored, otherwise the  reader
            acts  as  if  it  read  each object in the list.
            Usually the list only contains one  element.  If
            the reader is reading at the top level (i.e. not
            collecting elements of list), then it is illegal
            for  a  splicing  macro  to return more then one
            element in the list.  The major advantage  of  a
            splicing  macro over a normal macro is the abil-
            ity of the splicing macro to return nothing. The
            comment  character  (usually  ;)  is  a splicing
            macro bound to a function which reads to the end
            of the line and always returns nil.  Here is the
            previous example written as a splicing macro

    ____________________________________________________

    -> (_d_e_f_u_n _s_t_a_t_e_a_b_b_r_e_v _n_i_l
          ((_l_a_m_b_d_a (_v_a_l_u_e)
               (_c_o_n_d (_v_a_l_u_e (_l_i_s_t _v_a_l_u_e))
                     (_t _n_i_l)))
           (_c_d_r (_a_s_s_q (_r_e_a_d) '((_c_a_l_i_f_o_r_n_i_a . _c_a) (_p_e_n_n_s_y_l_v_a_n_i_a . _p_a))))))
    -> (_s_e_t_s_y_n_t_a_x '! '_v_s_p_l_i_c_i_n_g-_m_a_c_r_o '_s_t_a_t_e_a_b_b_r_e_v)
    -> '(!_p_e_n_n_s_y_l_v_a_n_i_a ! _f_o_o !_c_a_l_i_f_o_r_n_i_a)
    (pa ca)
    -> '!_f_o_o !_b_a_r !_p_e_n_n_s_y_l_v_a_n_i_a
    pa
    ->
    ____________________________________________________

         7.6.1.3.  Infix

                 Infix macros are passed  a  _c_o_n_c  structure
            representing   what   has   been  read  so  far.
            Briefly, a tconc structure is a single list cell
            whose  car points to a list and whose cdr points
            to  the  last  list  cell  in  that  list.   The
            interpretation   by  the  reader  of  the  value

                                   Printed: January 31, 1984

The Lisp Reader                                         7-11

            returned by  an infix macro depends  on  whether
            the  macro  is  called  while the reader is con-
            structing a list or whether it is called at  the
            top level of the reader.  If the macro is called
            while a list  is  being  constructed,  then  the
            value  returned  should  be   a tconc structure.
            The car of that structure replaces the  list  of
            elements  that  the  reader has been collecting.
            If the macro is called at  top  level,  then  it
            will  be  passed the value nil, and the value it
            returns should either be nil or a  tconc  struc-
            ture.   If the macro returns nil, then the value
            is ignored and the reader continues to read.  If
            the  macro returns a tconc structure of one ele-
            ment (i.e. whose car is a list of one  element),
            then  that  single  element  is  returned as the
            value of _r_e_a_d.  If the  macro  returns  a  tconc
            structure  of  more  than one element, then that
            list of elements is returned  as  the  value  of
            read.

    ____________________________________________________

    -> (_d_e_f_u_n _p_l_u_s_o_p (_x)
          (_c_o_n_d ((_n_u_l_l _x) (_t_c_o_n_c _n_i_l '_\+))
                (_t (_l_c_o_n_c _n_i_l (_l_i_s_t '_p_l_u_s (_c_a_a_r _x) (_r_e_a_d))))))

    plusop
    -> (_s_e_t_s_y_n_t_a_x '_\+ '_v_i_n_f_i_x-_m_a_c_r_o '_p_l_u_s_o_p)
    t
    -> '(_a + _b)
    (plus a b)
    -> '+
    |+|
    ->
    ____________________________________________________

      7.6.2.  Invocations

              There are  three  different  circumstances  in
         which  you  would like a macro function to be trig-
         gered.

         _A_l_w_a_y_s -
              Whenever the  macro  character  is  seen,  the
              macro should be invoked.  This is accomplished
              by  using  the   character   classes   _c_m_a_c_r_o,

                                   Printed: January 31, 1984

The Lisp Reader                                         7-12

              _c_s_p_l_i_c_i_n_g-_m_a_c_r_o, or _c_i_n_f_i_x-_m_a_c_r_o, and by using
              the _s_e_p_a_r_a_t_o_r property.   The  syntax  classes
              vmacro, vsplicing-macro, and vsingle-macro are
              defined this way.

         _W_h_e_n _f_i_r_s_t -
              The macro should only be  triggered  when  the
              macro  character  is the first character found
              after the scanning process.   A  syntax  class
              for  a _w_h_e_n _f_i_r_s_t macro would be defined using
              _c_m_a_c_r_o, _c_s_p_l_i_c_i_n_g-_m_a_c_r_o, or  _c_i_n_f_i_x-_m_a_c_r_o  and
              not including the _s_e_p_a_r_a_t_o_r property.

         _W_h_e_n _u_n_i_q_u_e -
              The macro should only be  triggered  when  the
              macro  character  is  the  only character col-
              lected in the token collection  phase  of  the
              reader,  i.e  the macro character is preceeded
              by zero or more _c_s_e_p_a_r_a_t_o_rs and followed by  a
              _s_e_p_a_r_a_t_o_r.   A  syntax class for a _w_h_e_n _u_n_i_q_u_e
              macro would be  defined  using  _c_s_i_n_g_l_e-_m_a_c_r_o,
              _c_s_i_n_g_l_e-_s_p_l_i_c_i_n_g-_m_a_c_r_o, or _c_s_i_n_g_l_e-_i_n_f_i_x-_m_a_c_r_o
              and not including the _s_e_p_a_r_a_t_o_r property.  The
              syntax  classes  so defined are vsingle-macro,
              vsingle-splicing-macro,   and   vsingle-infix-
              macro.

   7.7.  Functions

(setsyntax 's_symbol 's_synclass ['ls_func])

     WHERE:   ls_func is the name of a function or a  lambda
              body.

     RETURNS: t

     SIDE EFFECT: S_symbol should be a  symbol  whose  print
                  name  is  only  one character.  The syntax
                  class  for  that  character  is   set   to
                  s_synclass  in  the current readtable.  If
                  s_synclass is  a  class  that  requires  a
                  character macro, then ls_func must be sup-
                  plied.

     NOTE: The symbolic syntax codes are  new  to  Opus  38.
           For  compatibility,  s_synclass can be one of the
           fixnum syntax codes which appeared in older  ver-
           sions of the FRANZ LISP Manual.  This compatibil-
           ity is only temporary: existing code  which  uses
           the fixnum syntax codes should be converted.
9

9                                   Printed: January 31, 1984

The Lisp Reader                                         7-13

(getsyntax 's_symbol)

     RETURNS: the syntax class of  the  first  character  of
              s_symbol's  print name.  s_symbol's print name
              must be exactly one character long.

     NOTE: This function is new to Opus 38.   It  supercedes
           (_s_t_a_t_u_s _s_y_n_t_a_x) which no longer exists.

(add-syntax-class 's_synclass 'l_properties)

     RETURNS: s_synclass

     SIDE EFFECT: Defines the  syntax  class  s_synclass  to
                  have  properties  l_properties.   The list
                  l_properties should  contain  a  character
                  classes mentioned above.  l_properties may
                  contain  one  of  the  escape  properties:
                  _e_s_c_a_p_e-_a_l_w_a_y_s,    _e_s_c_a_p_e-_w_h_e_n-_u_n_i_q_u_e,   or
                  _e_s_c_a_p_e-_w_h_e_n-_f_i_r_s_t.  l_properties may  con-
                  tain the _s_e_p_a_r_a_t_o_r property.  After a syn-
                  tax  class  has  been  defined  with  _a_d_d-
                  _s_y_n_t_a_x-_c_l_a_s_s,  the  _s_e_t_s_y_n_t_a_x function can
                  be used to  give  characters  that  syntax
                  class.

    ____________________________________________________

    ; Define a non-separating macro character.
    ; This type of macro character is used in UCI-Lisp, and
    ; it corresponds to a  FIRST MACRO in Interlisp
    -> (_a_d_d-_s_y_n_t_a_x-_c_l_a_s_s '_v_u_c_i-_m_a_c_r_o '(_c_m_a_c_r_o _e_s_c_a_p_e-_w_h_e_n-_f_i_r_s_t))
    vuci-macro
    ->
    ____________________________________________________

9

9                                   Printed: January 31, 1984


                                   CCHHAAPPTTEERR  11

                                   FFRRAANNZZ LLIISSPP

             11..11..   FRANZ  LISPwas  algebraic manipulation, artificial
                intelligence, and programming languages at the Univer-
                sity of California at Berkeley.  Its roots  are  in  a
                PDP-11 Lisp system which originally came from Harvard.
                As it grew it adopted features  of  Maclisp  and  Lisp
                Machine  Lisp.   Substantial  compatibility with other
                Lisp  dialects  (Interlisp,   UCILisp,   CMULisp)   is
                achieved  by  means  of  support packages and compiler
                switches.  The heart of FRANZ LISP is  written  almost
                entirely in the programming language C.  Of course, it
                has been greatly  extended  by  additions  written  in
                Lisp.   A  small  part is written in the assembly lan-
                guage for the current host machines, VAXen and a  cou-
                ple  of flavors of 68000.  Because FRANZ LISP is writ-
                ten in C, it is relatively portable and easy  to  com-
                prehend.

                     FRANZ  LISP is capable of running large lisp pro-
                grams in a timesharing environment, has facilities for
                arrays  and  user  defined structures, has a user con-
                trolled reader with character and word macro  capabil-
                ities,  and  can interact directly with compiled Lisp,
                C, Fortran, and Pascal code.

                     This document is a reference manual for the FRANZ
                LISP  system.  It is not a Lisp primer or introduction
                to the language.  Some parts will be of interest  pri-
                marily  to  those maintaining FRANZ LISP at their com-
                puter site.  There is an additional document  entitled
                _T_h_e  _F_r_a_n_z  _L_i_s_p  _S_y_s_t_e_m_, _b_y _J_o_h_n _F_o_d_e_r_a_r_o_, _w_h_i_c_h _p_a_r_-
                _t_i_a_l_l_y _d_e_s_c_r_i_b_e_s  _t_h_e  _s_y_s_t_e_m  _i_m_p_l_e_m_e_n_t_a_t_i_o_n_.   _F_R_A_N_Z
                _L_I_S_P_,  _a_s  _d_e_l_i_v_e_r_e_d  _b_y _B_e_r_k_e_l_e_y_, _i_n_c_l_u_d_e_s _a_l_l _s_o_u_r_c_e
                _c_o_d_e _a_n_d _m_a_c_h_i_n_e _r_e_a_d_a_b_l_e _v_e_r_s_i_o_n _o_f _t_h_i_s  _m_a_n_u_a_l  _a_n_d
                _s_y_s_t_e_m  _d_o_c_u_m_e_n_t_.   _T_h_e _s_y_s_t_e_m _d_o_c_u_m_e_n_t _i_s _i_n _a _s_i_n_g_l_e
                _f_i_l_e _n_a_m_e_d _"_f_r_a_n_z_._n_" _i_n _t_h_e _"_d_o_c_" _s_u_b_d_i_r_e_c_t_o_r_y_.

          ____________________
             is  rumored that this name has something to do with Franz
          Liszt [F_rants List] (1811-1886)  a  Hungarian  composer  and
          keyboard   virtuoso.   These  allegations  have  never  been
          proven.

          FFRRAANNZZ LLIISSPP                                               11--11

          FFRRAANNZZ LLIISSPP                                               11--22

                     This document is divided into four Movements.  In
                the first one we will attempt to describe the language
                of FRANZ LISP  precisely  and  completely  as  it  now
                stands  (Opus  38.69, June 1983).  In the second Move-
                ment we will  look  at  the  reader,  function  types,
                arrays  and exception handling.  In the third Movement
                we will look at several large support packages written
                to help the FRANZ LISP user, namely the trace package,
                compiler, fixit and  stepping  package.   Finally  the
                fourth  movement  contains   an  index  into the other
                movements.  In the rest of this chapter we shall exam-
                ine  the  data  types  of FRANZ LISP.  The conventions
                used in the description of the  FRANZ  LISP  functions
                will  be  given  in  S1.3 -- it is very important that
                these conventions are  understood.

             11..22..  DDaattaa TTyyppeess   FRANZ LISP has  fourteen  data  types.
                In  this  section we shall look in detail at each type
                and if a type is divisible we shall  look  inside  it.
                There  is  a  Lisp function _t_y_p_e which will return the
                type name of a lisp  object.   This  is  the  official
                FRANZ  LISP  name  for  that type and we will use this
                name and this name only in the manual to avoid confus-
                ing  the  reader.   The  types  are listed in terms of
                importance rather than alphabetically.

                11..22..00..  lliissppvvaall   This is the name we use to  describe
                   any  Lisp  object.   The  function  _t_y_p_e will never
                   return `lispval'.

                11..22..11..  ssyymmbbooll   This object corresponds to a variable
                   in most other programming languages.  It may have a
                   value or may be `unbound'.  A symbol may be  _l_a_m_b_d_a
                   _b_o_u_n_d meaning that its current value is stored away
                   somewhere and the symbol  is given a new value  for
                   the  duration  of a certain context.  When the Lisp
                   processor  leaves that context, the  symbol's  cur-
                   rent  value  is  thrown  away  and its old value is
                   restored.
                   A symbol may also have a  _f_u_n_c_t_i_o_n  _b_i_n_d_i_n_g.   This
                   function  binding  is  static;  it cannot be lambda
                   bound.  Whenever the symbol is used  in  the  func-
                   tional  position  of a Lisp expression the function
                   binding of the symbol is examined  (see  Chapter  4
                   for more details on  evaluation).
                   A  symbol  may  also  have a _p_r_o_p_e_r_t_y _l_i_s_t, another
                   static data structure.  The property list  consists

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--33

                   of a list of an even number of elements, considered
                   to be grouped as pairs.  The first element  of  the
                   pair  is the _i_n_d_i_c_a_t_o_r the second the _v_a_l_u_e of that
                   indicator.
                   Each symbol has a print name _(_p_n_a_m_e_) which  is  how
                   this  symbol is accessed from input and referred to
                   on  (printed) output.
                   A symbol also has a hashlink used to  link  symbols
                   together  in the oblist -- this field is inaccessi-
                   ble to the lisp user.
                   Symbols are created by the reader and by the  func-
                   tions  _c_o_n_c_a_t,  _m_a_k_n_a_m and their derivatives.  Most
                   symbols live  on  FRANZ  LISP's  sole  _o_b_l_i_s_t,  and
                   therefore  two symbols with the same print name are
                   usually the  exact same object (they are _e_q).  Sym-
                   bols  which  are  not  on the oblist are said to be
                   _u_n_i_n_t_e_r_n_e_d_.  The function _m_a_k_n_a_m creates uninterned
                   symbols while _c_o_n_c_a_t creates _i_n_t_e_r_n_e_d ones.

               +-------------+-----------+-----------+---------------------+
               |Subpart name | Get value | Set value |        Type         |
               |             |           |           |                     |
               +-------------+-----------+-----------+---------------------+
               |   value     |   eval    |    set    |       lispval       |
               |             |           |   setq    |                     |
               +-------------+-----------+-----------+---------------------+
               |  property   |   plist   | setplist  |     list or nil     |
               |    list     |    get    |  putprop  |                     |
               |             |           |  defprop  |                     |
               +-------------+-----------+-----------+---------------------+
               |  function   |   getd    |   putd    | array, binary, list |
               |  binding    |           |    def    |       or nil        |
               +-------------+-----------+-----------+---------------------+
               | print name  | get_pname |           |       string        |
               +-------------+-----------+-----------+---------------------+
               | hash link   |           |           |                     |
               +-------------+-----------+-----------+---------------------+

                11..22..22..   lliisstt    A list cell has two parts, called the
                   car and cdr.  List cells are created by  the  func-
                   tion _c_o_n_s.

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--44

                    +-------------+-----------+-----------+---------+
                    |Subpart name | Get value | Set value |  Type   |
                    |             |           |           |         |
                    +-------------+-----------+-----------+---------+
                    |    car      |    car    |  rplaca   | lispval |
                    +-------------+-----------+-----------+---------+
                    |    cdr      |    cdr    |  rplacd   | lispval |
                    +-------------+-----------+-----------+---------+

                11..22..33..   bbiinnaarryy    This type acts as a function header
                   for machine coded functions.  It has two  parts,  a
                   pointer  to  the start of the function and a symbol
                   whose print name describes the argument _d_i_s_c_i_p_l_i_n_e.
                   The discipline (if _l_a_m_b_d_a, _m_a_c_r_o or _n_l_a_m_b_d_a) deter-
                   mines whether the arguments to this  function  will
                   be  evaluated by the caller before this function is
                   called.  If the discipline is  a  string  (specifi-
                   cally "_s_u_b_r_o_u_t_i_n_e", "_f_u_n_c_t_i_o_n", "_i_n_t_e_g_e_r_-_f_u_n_c_t_i_o_n",
                   "_r_e_a_l_-_f_u_n_c_t_i_o_n", "_c_-_f_u_n_c_t_i_o_n", "_d_o_u_b_l_e_-_c_-_f_u_n_c_t_i_o_n",
                   or  "_v_e_c_t_o_r_-_c_-_f_u_n_c_t_i_o_n"  )  then this function is a
                   foreign subroutine or function (see S8.5  for  more
                   details  on  this).  Although the type of the _e_n_t_r_y
                   field of a binary type object is usually ssttrriinngg  or
                   ootthheerr, the object pointed to is actually a sequence
                   of machine instructions.
                   Objects of type binary are  created  by  _m_f_u_n_c_t_i_o_n_,
                   _c_f_a_s_l_, and _g_e_t_a_d_d_r_e_s_s_.

                +-------------+-----------+-----------+------------------+
                |Subpart name | Get value | Set value |       Type       |
                |             |           |           |                  |
                +-------------+-----------+-----------+------------------+
                |   entry     | getentry  |           | string or fixnum |
                +-------------+-----------+-----------+------------------+
                | discipline  |  getdisc  |  putdisc  | symbol or fixnum |
                +-------------+-----------+-----------+------------------+

                11..22..44..   ffiixxnnuumm    A  fixnum is an integer constant in
                   the range -2to 2Small fixnums (-1024 to  1023)  are
                   stored  in a special table so they needn't be allo-
                   cated each time one is needed.  In  principle,  the
                   range  for  fixnums  is machine dependent, although
                   all current implementations  for  franz  have  this
                   range.

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--55

                11..22..55..   fflloonnuumm    A flonum is a double precision real
                   number.  On  the  VAX,  the  range  is   +-2.9x10to
                   +-1.7x10There  are  approximately  sixteen  decimal
                   digits of precision.  Other machines may have other
                   ranges.

                11..22..66..  bbiiggnnuumm   A bignum is an integer of potentially
                   unbounded size.  When  integer  arithmetic  exceeds
                   the limits of fixnums mentioned above, the calcula-
                   tion is automatically done  with  bignums.   Should
                   calculation with bignums give a result which can be
                   represented as a fixnum, then the fixnum  represen-
                   tation will be used.(f current algorithms for inte-
                   ger arithmetic operations will return  (in  certain
                   cases)   a  result  between  +-2and  2as  a  bignum
                   although this could be represented as a fixnum.
                   This contraction is known as _i_n_t_e_g_e_r _n_o_r_m_a_l_i_z_a_t_i_o_n.
                   Many  Lisp  functions assume that integers are nor-
                   malized.  Bignums are composed  of  a  sequence  of
                   lliisstt  cells  and a cell known as an ssddoott..  The user
                   should consider a bbiiggnnuumm structure indivisible  and
                   use functions such as _h_a_i_p_a_r_t, and _b_i_g_n_u_m_-_l_e_f_t_s_h_i_f_t
                   to extract parts of it.

                11..22..77..   ssttrriinngg    A  string  is  a  null   terminated
                   sequence  of characters.  Most functions of symbols
                   which operate on the symbol's print name will  also
                   work  on strings.  The default reader syntax is set
                   so that a sequence of characters surrounded by dou-
                   ble quotes is a string.

                11..22..88..   ppoorrtt   A port is a structure which the system
                   I/O routines can reference to transfer data between
                   the  Lisp  system and external media.  Unlike other
                   Lisp objects there are a  very  limited  number  of
                   ports (20).  Ports are allocated by _i_n_f_i_l_e and _o_u_t_-
                   _f_i_l_e and deallocated by  _c_l_o_s_e  and  _r_e_s_e_t_i_o.   The
                   _p_r_i_n_t function prints a port as a percent sign fol-
                   lowed by the name of the file it  is  connected  to
                   (if  the  port  was  opened by _f_i_l_e_o_p_e_n_, _i_n_f_i_l_e_, _o_r
                   _o_u_t_f_i_l_e).  During initialization, FRANZ LISP  binds
                   the  symbol  ppiippoorrtt to a port attached to the stan-
                   dard input stream.  This port  prints  as  %$stdin.
                   There  are  ports  connected to the standard output
                   and error streams,  which  print  as  %$stdout  and
                   %$stderr.   This is discussed in more detail at the
                   beginning of Chapter 5.

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--66

                11..22..99..  vveeccttoorr    Vectors  are  indexed  sequences  of
                   data.   They  can  be used to implement a notion of
                   user-defined types via  their  associated  property
                   list.  They make hhuunnkkss (see below) logically unnec-
                   essary, although hunks are very efficiently garbage
                   collected.   There  is  a  second  kind  of vector,
                   called an  immediate-vector,  which  stores  binary
                   data.   The name that the function _t_y_p_e returns for
                   immediate-vectors  is  vveeccttoorrii.   Immediate-vectors
                   could be used to implement strings and block-flonum
                   arrays, for  example.   Vectors  are  discussed  in
                   chapter  9.   The functions _n_e_w_-_v_e_c_t_o_r, and _v_e_c_t_o_r,
                   can be used to create vectors.

                    +-------------+-----------+-----------+---------+
                    |Subpart name | Get value | Set value |  Type   |
                    |             |           |           |         |
                    +-------------+-----------+-----------+---------+
                    |  datum[_i]   |   vref    |   vset    | lispval |
                    +-------------+-----------+-----------+---------+
                    |  property   |   vprop   | vsetprop  | lispval |
                    |             |           | vputprop  |         |
                    +-------------+-----------+-----------+---------+
                    |    size     |   vsize   |     -     | fixnum  |
                    +-------------+-----------+-----------+---------+

                11..22..1100..  aarrrraayy   Arrays are rather  complicated  types
                   and  are  fully  described  in Chapter 9.  An array
                   consists of a block of contiguous data, a  function
                   to  access  that data, and auxiliary fields for use
                   by  the  accessing  function.   Since  an   array's
                   accessing function is created by the user, an array
                   can  have  any  form  the  user  chooses  (e.g.  n-
                   dimensional, triangular, or hash table).
                   Arrays are created by the function _m_a_r_r_a_y.

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--77

             +----------------+-----------+-----------+---------------------+
             | Subpart name   | Get value | Set value |        Type         |
             |                |           |           |                     |
             +----------------+-----------+-----------+---------------------+
             |access function | getaccess | putaccess |    binary, list     |
             |                |           |           |      or symbol      |
             +----------------+-----------+-----------+---------------------+
             |   auxiliary    |  getaux   |  putaux   |       lispval       |
             +----------------+-----------+-----------+---------------------+
             |     data       | arrayref  |  replace  | block of contiguous |
             |                |           |    set    |       lispval       |
             +----------------+-----------+-----------+---------------------+
             |    length      | getlength | putlength |       fixnum        |
             +----------------+-----------+-----------+---------------------+
             |     delta      | getdelta  | putdelta  |       fixnum        |
             +----------------+-----------+-----------+---------------------+

                11..22..1111..   vvaalluuee   A value cell contains a pointer to a
                   lispval.  This type is used  mainly  by  arrays  of
                   general lisp objects.  Value cells are created with
                   the  _p_t_r  function.   A  value  cell  containing  a
                   pointer   to   the   symbol  `foo'  is  printed  as
                   `(ptr to)foo'

                11..22..1122..  hhuunnkk   A hunk is a vector of from  1  to  128
                   lispvals.   Once  a  hunk  is  created  (by _h_u_n_k or
                   _m_a_k_h_u_n_k) it cannot grow or shrink.  The access time
                   for an element of a hunk is slower than a list cell
                   element but faster than an array.  Hunks are really
                   only  allocated  in  sizes which are powers of two,
                   but can appear to the user to be any size in the  1
                   to  128  range.   Users  of hunks must realize that
                   _(_n_o_t _(_a_t_o_m _'_l_i_s_p_v_a_l_)_) will return true  if  _l_i_s_p_v_a_l
                   is  a hunk.  Most lisp systems do not have a direct
                   test for a list cell and instead use the above test
                   and  assume  that  a true result means _l_i_s_p_v_a_l is a
                   list cell.  In FRANZ LISP you can use _d_t_p_r to check
                   for  a  list  cell.   Although  hunks  are not list
                   cells, you can still access the first two hunk ele-
                   ments  with _c_d_r and _c_a_r and you can access any hunk
                   element with _c_x_r.(f a hunk, the function _c_d_r refer-
                   ences the first element and _c_a_r the second.
                   You  can set the value of the first two elements of
                   a hunk with _r_p_l_a_c_d and _r_p_l_a_c_a and you can  set  the
                   value  of  any  element of the hunk with _r_p_l_a_c_x.  A
                   hunk is printed by printing its contents surrounded
                   by  {  and  }.  However a hunk cannot be read in in
                   this way in the standard lisp system.  It  is  easy

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--88

                   to write a reader macro to do this if desired.

                11..22..1133..    ootthheerr    Occasionally,  you  can  obtain  a
                   pointer to storage not allocated by the  lisp  sys-
                   tem.   One  example  of  this is the entry field of
                   those FRANZ LISP  functions  written  in  C.   Such
                   objects  are  classified as of type ootthheerr.  Foreign
                   functions which call malloc to allocate  their  own
                   space,  may also inadvertantly create such objects.
                   The garbage collector is supposed  to  ignore  such
                   objects.

             11..33..  DDooccuummeennttaattiioonn   The conventions used in the follow-
                ing chapters were designed to give  a  great  deal  of
                information  in  a  brief  space.  The first line of a
                function description contains  the  function  name  in
                bboolldd ffaaccee  and  then lists the arguments, if any.  The
                arguments all have names which begin with a letter  or
                letters  and  an  underscore.  The letter(s) gives the
                allowable type(s) for that argument according to  this
                table.

                                             Printed: October 16, 1993

          FFRRAANNZZ LLIISSPP                                               11--99

                +-------+----------------------------------------------+
                |Letter |              Allowable type(s)               |
                |       |                                              |
                +-------+----------------------------------------------+
                |g      | any type                                     |
                +-------+----------------------------------------------+
                |s      | symbol (although nil may not be allowed)     |
                +-------+----------------------------------------------+
                |t      | string                                       |
                +-------+----------------------------------------------+
                |l      | list (although nil may be allowed)           |
                +-------+----------------------------------------------+
                |n      | number (fixnum, flonum, bignum)              |
                +-------+----------------------------------------------+
                |i      | integer (fixnum, bignum)                     |
                +-------+----------------------------------------------+
                |x      | fixnum                                       |
                +-------+----------------------------------------------+
                |b      | bignum                                       |
                +-------+----------------------------------------------+
                |f      | flonum                                       |
                +-------+----------------------------------------------+
                |u      | function type (either binary or lambda body) |
                +-------+----------------------------------------------+
                |y      | binary                                       |
                +-------+----------------------------------------------+
                |v      | vector                                       |
                +-------+----------------------------------------------+
                |V      | vectori                                      |
                +-------+----------------------------------------------+
                |a      | array                                        |
                +-------+----------------------------------------------+
                |e      | value                                        |
                +-------+----------------------------------------------+
                |p      | port (or nil)                                |
                +-------+----------------------------------------------+
                |h      | hunk                                         |
                +-------+----------------------------------------------+

                In  the  first  line  of a function description, those
                arguments preceded by a quote mark are evaluated (usu-
                ally before the function is called).  The quoting con-
                vention is used so that we can  give  a  name  to  the
                result  of evaluating the argument and we can describe
                the allowable types.  If an argument is not quoted  it
                does  not  mean  that that argument will not be evalu-
                ated, but rather that if it is evaluated, the time  at
                which  it  is evaluated will be specifically mentioned
                in the function description.  Optional  arguments  are
                surrounded  by  square  brackets.   An  ellipsis (...)
                means zero or more occurrences of an argument  of  the
                directly preceding type.

                                             Printed: October 16, 1993