

                   The FRANZ LISP Manual

                             by


                      _J_o_h_n _K_. _F_o_d_e_r_a_r_o


                      _K_e_i_t_h _L_. _S_k_l_o_w_e_r


                        _K_e_v_i_n _L_a_y_e_r


                         June 1983


                                               A document in
                                              four movements
9

9


PS2:9-2                                The Franz Lisp Manual


                       _O_v_e_r_t_u_r_e


     _A  _c_h_o_r_u_s  _o_f  _s_t_u_d_e_n_t_s  _u_n_d_e_r  _t_h_e  _d_i_r_e_c_t_i_o_n  _o_f
     _R_i_c_h_a_r_d _F_a_t_e_m_a_n _h_a_v_e _c_o_n_t_r_i_b_u_t_e_d _t_o _b_u_i_l_d_i_n_g _F_R_A_N_Z
     _L_I_S_P _f_r_o_m _a _m_e_r_e _m_e_l_o_d_y _i_n_t_o  _a  _f_u_l_l  _s_y_m_p_h_o_n_y  .
     _T_h_e  _m_a_j_o_r _c_o_n_t_r_i_b_u_t_o_r_s _t_o _t_h_e _i_n_i_t_i_a_l _s_y_s_t_e_m _w_e_r_e
     _M_i_k_e _C_u_r_r_y,  _J_o_h_n  _B_r_e_e_d_l_o_v_e  _a_n_d  _J_e_f_f  _L_e_v_i_n_s_k_y.
     _B_i_l_l  _R_o_w_a_n  _a_d_d_e_d _t_h_e _g_a_r_b_a_g_e _c_o_l_l_e_c_t_o_r _a_n_d _a_r_r_a_y
     _p_a_c_k_a_g_e.  _T_o_m _L_o_n_d_o_n _w_o_r_k_e_d _o_n _a_n  _e_a_r_l_y  _c_o_m_p_i_l_e_r
     _a_n_d   _h_e_l_p_e_d  _i_n  _o_v_e_r_a_l_l  _s_y_s_t_e_m  _d_e_s_i_g_n.   _K_e_i_t_h
     _S_k_l_o_w_e_r _h_a_s _c_o_n_t_r_i_b_u_t_e_d _m_u_c_h _t_o _F_R_A_N_Z _L_I_S_P, _a_d_d_i_n_g
     _t_h_e  _b_i_g_n_u_m _p_a_c_k_a_g_e _a_n_d _r_e_w_r_i_t_i_n_g _m_o_s_t _o_f _t_h_e _c_o_d_e
     _t_o _i_n_c_r_e_a_s_e  _i_t_s  _e_f_f_i_c_i_e_n_c_y  _a_n_d  _c_l_a_r_i_t_y.   _K_i_p_p
     _H_i_c_k_m_a_n  _a_n_d  _C_h_a_r_l_e_s  _K_o_e_s_t_e_r _a_d_d_e_d _h_u_n_k_s.  _M_i_t_c_h
     _M_a_r_c_u_s _a_d_d_e_d *_r_s_e_t, _e_v_a_l_h_o_o_k _a_n_d  _e_v_a_l_f_r_a_m_e.   _D_o_n
     _C_o_h_e_n  _a_n_d  _o_t_h_e_r_s  _a_t  _C_a_r_n_e_g_i_e-_M_e_l_l_o_n  _m_a_d_e _s_o_m_e
     _i_m_p_r_o_v_e_m_e_n_t_s _t_o  _e_v_a_l_f_r_a_m_e  _a_n_d  _p_r_o_v_i_d_e_d  _v_a_r_i_o_u_s
     _f_e_a_t_u_r_e_s  _m_o_d_e_l_l_e_d  _a_f_t_e_r  _U_C_I/_C_M_U _P_D_P-_1_0 _L_i_s_p _a_n_d
     _I_n_t_e_r_l_i_s_p  _e_n_v_i_r_o_n_m_e_n_t_s  (_e_d_i_t_o_r,  _d_e_b_u_g_g_e_r,  _t_o_p-
     _l_e_v_e_l).  _J_o_h_n _F_o_d_e_r_a_r_o _w_r_o_t_e _t_h_e _c_o_m_p_i_l_e_r, _a_d_d_e_d _a
     _f_e_w _f_u_n_c_t_i_o_n_s, _a_n_d _w_r_o_t_e _m_u_c_h _o_f _t_h_i_s  _m_a_n_u_a_l.  _O_f
     _c_o_u_r_s_e,  _o_t_h_e_r  _a_u_t_h_o_r_s  _h_a_v_e _c_o_n_t_r_i_b_u_t_e_d _s_p_e_c_i_f_i_c
     _c_h_a_p_t_e_r_s _a_s _i_n_d_i_c_a_t_e_d.  _K_e_v_i_n _L_a_y_e_r  _m_o_d_i_f_i_e_d  _t_h_e
     _c_o_m_p_i_l_e_r  _t_o  _p_r_o_d_u_c_e _c_o_d_e _f_o_r _t_h_e _M_o_t_o_r_o_l_a _6_8_0_0_0,
     _a_n_d _h_e_l_p_e_d _m_a_k_e _F_R_A_N_Z _L_I_S_P _p_a_s_s ``_L_i_n_t''.
     _T_h_i_s _m_a_n_u_a_l _m_a_y _b_e _s_u_p_p_l_e_m_e_n_t_e_d _o_r  _s_u_p_p_l_a_n_t_e_d  _b_y
     _l_o_c_a_l _c_h_a_p_t_e_r_s _r_e_p_r_e_s_e_n_t_i_n_g _a_l_t_e_r_a_t_i_o_n_s, _a_d_d_i_t_i_o_n_s
     _a_n_d _d_e_l_e_t_i_o_n_s.  _W_e _a_t _U._C. _B_e_r_k_e_l_e_y _a_r_e _p_l_e_a_s_e_d _t_o
     _l_e_a_r_n  _o_f  _g_e_n_e_r_a_l_l_y  _u_s_e_f_u_l  _s_y_s_t_e_m _f_e_a_t_u_r_e_s, _b_u_g
     _f_i_x_e_s, _o_r _u_s_e_f_u_l _p_r_o_g_r_a_m  _p_a_c_k_a_g_e_s,  _a_n_d  _w_e  _w_i_l_l
     _a_t_t_e_m_p_t _t_o _r_e_d_i_s_t_r_i_b_u_t_e _s_u_c_h _c_o_n_t_r_i_b_u_t_i_o_n_s.


98c9 1980, 1981, 1983 by the Regents of the University of Cali-
fornia.   (exceptions:  Chapters 13, 14 (first half), 15 and
16 have separate copyrights, as indicated. These are  repro-
duced by permission of the copyright holders.)
Permission to copy without fee all or part of this  material
is  granted provided that the copies are not made or distri-
buted for direct commercial  advantage,  and  the  copyright
notice  of  the Regents, University of California, is given.
All rights reserved.


9


The Franz Lisp Manual                                PS2:9-3


Work reported herein was supported in  part  by  the  U.  S.
Department  of  Energy,  Contract DE-AT03-76SF00034, Project
Agreement DE-AS03-79ER10358, and the National Science  Foun-
dation under Grant No.  MCS 7807291


UNIX is a trademark of Bell Laboratories.  VAX and  PDP  are
trademarks  of  Digital Equiptment Coporation.  MC68000 is a
trademark of Motorola Semiconductor Products, Inc.


9

9


PS2:9-4                                The Franz Lisp Manual


                           Score


                    First Movement (_a_l_l_e_g_r_o _n_o_n _t_r_o_p_p_o)

     1. FRANZ LISP
          _I_n_t_r_o_d_u_c_t_i_o_n _t_o _F_R_A_N_Z _L_I_S_P, _d_e_t_a_i_l_s _o_f _d_a_t_a _t_y_p_e_s,
          _a_n_d _d_e_s_c_r_i_p_t_i_o_n _o_f _n_o_t_a_t_i_o_n
     2. Data Structure Access
          _F_u_n_c_t_i_o_n_s _f_o_r _t_h_e _c_r_e_a_t_i_o_n, _d_e_s_t_r_u_c_t_i_o_n _a_n_d  _m_a_n_i_-
          _p_u_l_a_t_i_o_n _o_f _l_i_s_p _d_a_t_a _o_b_j_e_c_t_s.
     3. Arithmetic Functions
          _F_u_n_c_t_i_o_n_s _t_o _p_e_r_f_o_r_m _a_r_i_t_h_m_e_t_i_c _o_p_e_r_a_t_i_o_n_s.
     4. Special Functions
          _F_u_n_c_t_i_o_n_s _f_o_r _a_l_t_e_r_i_n_g _f_l_o_w _o_f _c_o_n_t_r_o_l.  _F_u_n_c_t_i_o_n_s
          _f_o_r _m_a_p_p_i_n_g _o_t_h_e_r _f_u_n_c_t_i_o_n_s _o_v_e_r _l_i_s_t_s.
     5. I/O Functions
          _F_u_n_c_t_i_o_n_s _f_o_r  _r_e_a_d_i_n_g  _a_n_d  _w_r_i_t_i_n_g  _f_r_o_m  _p_o_r_t_s.
          _F_u_n_c_t_i_o_n_s  _f_o_r  _t_h_e  _m_o_d_i_f_i_c_a_t_i_o_n  _o_f _t_h_e _r_e_a_d_e_r'_s
          _s_y_n_t_a_x.
     6. System Functions
          _F_u_n_c_t_i_o_n_s _f_o_r _s_t_o_r_a_g_e _m_a_n_a_g_e_m_e_n_t,  _d_e_b_u_g_g_i_n_g,  _a_n_d
          _f_o_r  _t_h_e _r_e_a_d_i_n_g _a_n_d _s_e_t_t_i_n_g _o_f _g_l_o_b_a_l _L_i_s_p _s_t_a_t_u_s
          _v_a_r_i_a_b_l_e_s.   _F_u_n_c_t_i_o_n_s  _f_o_r  _d_o_i_n_g   _U_N_I_X-_s_p_e_c_i_f_i_c
          _t_a_s_k_s _s_u_c_h _a_s _p_r_o_c_e_s_s _c_o_n_t_r_o_l.


                    Second Movement (_L_a_r_g_o)

     7. The Reader
          _A _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e  _s_y_n_t_a_x  _c_o_d_e_s  _u_s_e_d  _b_y  _t_h_e
          _r_e_a_d_e_r.  _A_n _e_x_p_l_a_n_a_t_i_o_n _o_f _c_h_a_r_a_c_t_e_r _m_a_c_r_o_s.
     8. Functions, Fclosures, and Macros
          _A  _d_e_s_c_r_i_p_t_i_o_n  _o_f  _v_a_r_i_o_u_s  _t_y_p_e_s  _o_f  _f_u_n_c_t_i_o_n_a_l
          _o_b_j_e_c_t_s.   _A_n  _e_x_a_m_p_l_e _o_f _t_h_e _u_s_e _o_f _f_o_r_e_i_g_n _f_u_n_c_-
          _t_i_o_n_s.
     9. Arrays and Vectors
          _A _d_e_t_a_i_l_e_d _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e _p_a_r_t_s  _o_f  _a_n  _a_r_r_a_y
          _a_n_d _o_f _M_a_c_l_i_s_p _c_o_m_p_a_t_i_b_l_e _a_r_r_a_y_s.
     10. Exception Handling
          _A _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e _e_r_r_o_r _h_a_n_d_l_i_n_g  _s_e_q_u_e_n_c_e  _a_n_d
          _o_f _a_u_t_o_l_o_a_d_i_n_g.


9

9


The Franz Lisp Manual                                PS2:9-5


                    Third Movement (_S_c_h_e_r_z_o)

     11. The Joseph Lister Trace Package
          _A _d_e_s_c_r_i_p_t_i_o_n _o_f _a _v_e_r_y _u_s_e_f_u_l _d_e_b_u_g_g_i_n_g _a_i_d.
     12. Liszt, the lisp compiler
          _A _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e _o_p_e_r_a_t_i_o_n _o_f _t_h_e _c_o_m_p_i_l_e_r _a_n_d
          _h_i_n_t_s _f_o_r _m_a_k_i_n_g _f_u_n_c_t_i_o_n_s _c_o_m_p_i_l_a_b_l_e.
     13. CMU Top Level and File Package
          _A _d_e_s_c_r_i_p_t_i_o_n  _o_f  _a  _t_o_p  _l_e_v_e_l  _w_i_t_h  _a  _h_i_s_t_o_r_y
          _m_e_c_h_a_n_i_s_m _a_n_d _a _p_a_c_k_a_g_e _w_h_i_c_h _h_e_l_p_s _y_o_u _k_e_e_p _t_r_a_c_k
          _o_f _f_i_l_e_s _o_f _l_i_s_p _f_u_n_c_t_i_o_n_s.
     14 Stepper
          _A _d_e_s_c_r_i_p_t_i_o_n _o_f _a _p_r_o_g_r_a_m _w_h_i_c_h  _p_e_r_m_i_t_s  _y_o_u  _t_o
          _p_u_t  _b_r_e_a_k_p_o_i_n_t_s  _i_n  _l_i_s_p _c_o_d_e _a_n_d _t_o _s_i_n_g_l_e _s_t_e_p
          _i_t.  _A _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e _e_v_a_l_h_o_o_k _a_n_d _f_u_n_c_a_l_l_h_o_o_k
          _m_e_c_h_a_n_i_s_m.
     15 Fixit
          _A _p_r_o_g_r_a_m _w_h_i_c_h _p_e_r_m_i_t_s _y_o_u _t_o _e_x_a_m_i_n_e _a_n_d  _m_o_d_i_f_y
          _e_v_a_l_u_a_t_i_o_n _s_t_a_c_k _i_n _o_r_d_e_r _t_o _f_i_x _b_u_g_s _o_n _t_h_e _f_l_y.
     16 Lisp Editor
          _A _s_t_r_u_c_t_u_r_e _e_d_i_t_o_r _f_o_r _i_n_t_e_r_a_c_t_i_v_e _m_o_d_i_f_i_c_a_t_i_o_n _o_f
          _l_i_s_p _c_o_d_e.


                    Final Movement (_a_l_l_e_g_r_o)

     Appendix A - Function Index
     Appendix B - List of Special Symbols
     Appendix C - Short Subjects
          _G_a_r_b_a_g_e _c_o_l_l_e_c_t_o_r, _D_e_b_u_g_g_i_n_g, _D_e_f_a_u_l_t _T_o_p _L_e_v_e_l


9

9


                         CHAPTER  1


                         FRANZ LISP


   _1._1.  FRANZ LISP[|-] was created  as  a  tool  to  further
      research   in  symbolic  and  algebraic  manipulation,
      artificial intelligence, and programming languages  at
      the University 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
      language for the current host machines,  VAXen  and  a
      couple  of  flavors  of  68000.  Because FRANZ LISP is
      written in C, it is relatively portable  and  easy  to
      comprehend.

           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, by John Foderaro, which par-
      tially describes  the  system  implementation.   FRANZ
      LISP,  as  delivered  by Berkeley, includes all source
      code and machine readable version of this  manual  and
      system  document.   The system document is in a single
____________________
9   [|-]It 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.


9PS2:9-6                                The Franz Lisp Manual


The Franz Lisp Manual                                PS2:9-7


      file named "franz.n" in the "doc" subdirectory.

           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  1.3  -- it is very important that
      these conventions are  understood.


   _1._2.  _D_a_t_a _T_y_p_e_s   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.


      _1._2._0.  _l_i_s_p_v_a_l   This is the name we use to  describe
         any  Lisp  object.   The  function  _t_y_p_e will never
         return `lispval'.


      _1._2._1.  _s_y_m_b_o_l   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
         current  value  is thrown away and its old value is
         restored.
9         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


9


PS2:9-8                                The Franz Lisp Manual


         for more details on  evaluation).
9         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
         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.
9         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.
9         A symbol also has a hashlink used to  link  symbols
         together  in the oblist -- this field is inaccessi-
         ble to the lisp user.
9         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.


8      ____________________________________________________________
       Subpart name   Get value   Set value          Type

8      ________________________________________________________________________________________________________________________
          value         eval         set            lispval
                                    setq
8      ____________________________________________________________
         property       plist     setplist        list or nil
           list          get       putprop
                                   defprop
8      ____________________________________________________________
         function       getd        putd      array, binary, list
         binding                     def            or nil
8      ____________________________________________________________
        print name    get_pname                     string
8      ____________________________________________________________
        hash link
8      ____________________________________________________________
7      |7|7|7|7|7|7|7|7|7|7|7|7|7|


                    |7|7|7|7|7|7|7|7|7|7|7|7|7|


                                |7|7|7|7|7|7|7|7|7|7|7|7|7|


                                            |7|7|7|7|7|7|7|7|7|7|7|7|7|


                                                                  |7|7|7|7|7|7|7|7|7|7|7|7|7|


      _1._2._2.  _l_i_s_t   A list cell has two parts,  called  the
         car  and  cdr.  List cells are created by the func-
         tion _c_o_n_s.


9


The Franz Lisp Manual                                PS2:9-9


8            ________________________________________________
             Subpart name   Get value   Set value    Type

8            ________________________________________________________________________________________________
                 car           car       rplaca     lispval
8            ________________________________________________
                 cdr           cdr       rplacd     lispval
8            ________________________________________________
7            |8|7|7|7|7|


9                          |8|7|7|7|7|


9                                      |8|7|7|7|7|


9                                                  |8|7|7|7|7|


9                                                            |8|7|7|7|7|


9


      _1._2._3.  _b_i_n_a_r_y   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 8.5 for more
         details on this).  Although the type of  the  _e_n_t_r_y
         field  of a binary type object is usually string or
         other, 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.


8        _________________________________________________________
         Subpart name   Get value   Set value         Type

8        __________________________________________________________________________________________________________________
            entry       getentry                string or fixnum
8        _________________________________________________________
          discipline     getdisc     putdisc    symbol or fixnum
8        _________________________________________________________
7        |8|7|7|7|7|


9                      |8|7|7|7|7|


9                                  |8|7|7|7|7|


9                                              |8|7|7|7|7|


9                                                                 |8|7|7|7|7|


9


      _1._2._4.  _f_i_x_n_u_m   A fixnum is an  integer  constant  in
         the  range -2[31] to 2[31]-1.  Small fixnums (-1024
         to 1023) are stored in  a  special  table  so  they
         needn't  be  allocated each time one is needed.  In
         principle, the range for fixnums is machine  depen-
         dent,  although  all  current  implementations  for
         franz have this range.

9


9


PS2:9-10                               The Franz Lisp Manual


      _1._2._5.  _f_l_o_n_u_m   A flonum is a double  precision  real
         number.  On  the  VAX, the range is +_2.9x10[-37] to
         +_1.7x10[38].   There  are   approximately   sixteen
         decimal  digits  of  precision.  Other machines may
         have other ranges.


      _1._2._6.  _b_i_g_n_u_m   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[|-].  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 normalized.   Bignums  are
         composed  of  a  sequence  of _l_i_s_t cells and a cell
         known as an _s_d_o_t.  The user should consider a  _b_i_g_-
         _n_u_m 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.


      _1._2._7.   _s_t_r_i_n_g    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.


      _1._2._8.  _p_o_r_t   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  piport  to  a  port  attached  to  the
____________________
9   [|-]The current algorithms for integer  arithmetic  opera-
tions will return (in certain cases) a result between +_2[30]
and 2[31] as a bignum although this could be represented  as
a fixnum.


9


The Franz Lisp Manual                               PS2:9-11


         standard  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.


      _1._2._9.  _v_e_c_t_o_r    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  hunks  (see  below)  logically
         unnecessary, although hunks  are  very  efficiently
         garbage  collected.  There is a second kind of vec-
         tor,  called  an  immediate-vector,  which   stores
         binary  data.   The  name  that  the  function _t_y_p_e
         returns   for   immediate-vectors    is    vectori.
         Immediate-vectors   could   be  used  to  implement
         strings and block-flonum arrays, for example.  Vec-
         tors  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  vec-
         tors.


8            ________________________________________________
             Subpart name   Get value   Set value    Type

8            ________________________________________________________________________________________________
               datum[_i]       vref        vset      lispval
8            ________________________________________________
               property       vprop     vsetprop    lispval
                                        vputprop
8            ________________________________________________
                 size         vsize         -       fixnum
8            ________________________________________________
7            |7|7|7|7|7|7|7|


                          |7|7|7|7|7|7|7|


                                      |7|7|7|7|7|7|7|


                                                  |7|7|7|7|7|7|7|


                                                            |7|7|7|7|7|7|7|


      _1._2._1_0.  _a_r_r_a_y   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.


9


PS2:9-12                               The Franz Lisp Manual


8     _______________________________________________________________
       Subpart name     Get value   Set value          Type

8     ______________________________________________________________________________________________________________________________
      access function   getaccess   putaccess      binary, list
                                                     or symbol
8     _______________________________________________________________
         auxiliary       getaux      putaux           lispval
8     _______________________________________________________________
           data         arrayref     replace    block of contiguous
                                       set            lispval
8     _______________________________________________________________
          length        getlength   putlength         fixnum
8     _______________________________________________________________
           delta        getdelta    putdelta          fixnum
8     _______________________________________________________________
7     |7|7|7|7|7|7|7|7|7|7|7|


                      |7|7|7|7|7|7|7|7|7|7|7|


                                  |7|7|7|7|7|7|7|7|7|7|7|


                                              |7|7|7|7|7|7|7|7|7|7|7|


                                                                    |7|7|7|7|7|7|7|7|7|7|7|


      _1._2._1_1.  _v_a_l_u_e   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'


      _1._2._1_2.  _h_u_n_k   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[|-].  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
____________________
9   [|-]In a hunk, the function _c_d_r references the first  ele-
ment and _c_a_r the second.


The Franz Lisp Manual                               PS2:9-13


         its contents surrounded by { and }.  However a hunk
         cannot  be read in in this way in the standard lisp
         system.  It is easy to write a reader macro  to  do
         this if desired.


      _1._2._1_3.   _o_t_h_e_r    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  other.   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.


   _1._3.  _D_o_c_u_m_e_n_t_a_t_i_o_n   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
      bold face 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.


9


9


PS2:9-14                               The Franz Lisp Manual


8       _______________________________________________________
        Letter                Allowable type(s)

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


               |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


                                                              |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


      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
      evaluated,  but  rather  that  if it is evaluated, the
      time at which it is  evaluated  will  be  specifically
      mentioned in the function description.  Optional argu-
      ments are surrounded by square brackets.  An  ellipsis
      (...) means zero or more occurrences of an argument of
      the directly preceding type.


9


                            CHAPTER  2


                      Data Structure Access


           The following functions allow one to  create  and
      manipulate  the various types of lisp data structures.
      Refer to 1.2 for details of the data structures  known
      to FRANZ LISP.


   _2._1.  _L_i_s_t_s

           The following functions exist  for  the  creation
      and  manipulating  of  lists.  Lists are composed of a
      linked list of objects  called  either  'list  cells',
      'cons cells' or 'dtpr cells'.  Lists are normally ter-
      minated with the special symbol _n_i_l.  _n_i_l  is  both  a
      symbol and a representation for the empty list ().


      _2._1._1.  _l_i_s_t _c_r_e_a_t_i_o_n

(cons 'g_arg1 'g_arg2)

     RETURNS: a new list cell whose car is g_arg1 and  whose
              cdr is g_arg2.

(xcons 'g_arg1 'g_arg2)

     EQUIVALENT TO: (_c_o_n_s '_g__a_r_g_2 '_g__a_r_g_1)

(ncons 'g_arg)

     EQUIVALENT TO: (_c_o_n_s '_g__a_r_g _n_i_l)

(list ['g_arg1 ... ])

     RETURNS: a list whose elements are the g_arg_i.


9

9The Franz Lisp Manual                               PS2:9-15


PS2:9-16                               The Franz Lisp Manual


(append 'l_arg1 'l_arg2)

     RETURNS: a list containing the elements of l_arg1  fol-
              lowed by l_arg2.

     NOTE: To generate the result, the top level list  cells
           of  l_arg1 are duplicated and the cdr of the last
           list cell is set to point to l_arg2.   Thus  this
           is  an  expensive  operation  if l_arg1 is large.
           See the  descriptions  of  _n_c_o_n_c  and  _t_c_o_n_c  for
           cheaper  ways  of  doing  the  _a_p_p_e_n_d if the list
           l_arg1 can be altered.

(append1 'l_arg1 'g_arg2)

     RETURNS: a list like l_arg1 with  g_arg2  as  the  last
              element.

     NOTE: this  is  equivalent  to  (append  'l_arg1  (list
           'g_arg2)).


    ____________________________________________________

    ; A common mistake is using append to add one element to the end of a list
    -> (_a_p_p_e_n_d '(_a _b _c _d) '_e)
    (a b c d . e)
    ; The user intended to say:
    -> (_a_p_p_e_n_d '(_a _b _c _d) '(_e))
    (_a _b _c _d _e)
    ; _b_e_t_t_e_r _i_s _a_p_p_e_n_d_1
    -> (_a_p_p_e_n_d_1 '(_a _b _c _d) '_e)
    (_a _b _c _d _e)
    ____________________________________________________


(quote! [g_qform_i] ...[! 'g_eform_i] ...  [!! 'l_form_i] ...)

     RETURNS: The list  resulting  from  the   splicing  and
              insertion process described below.

     NOTE: _q_u_o_t_e!  is the complement of the  _l_i_s_t  function.
           _l_i_s_t  forms  a list by evaluating each for in the
           argument list; evaluation is  suppressed  if  the
           form  is _q_u_o_t_eed.  In _q_u_o_t_e!, each form is impli-
           citly _q_u_o_t_eed.  To be evaluated, a form  must  be
           preceded  by one of the evaluate operations ! and
           !!. ! g_eform evaluates g_form and the  value  is
           inserted  in  the  place  of  the call; !! l_form
           evaluates l_form and the value  is  spliced  into
           the place of the call.


The Franz Lisp Manual                               PS2:9-17


           `Splicing in' means  that  the  parentheses  sur-
           rounding  the  list  are  removed  as the example
           below shows.  Use of the evaluate  operators  can
           occur at any level in a form argument.

           Another way to get the effect of the _q_u_o_t_e! func-
           tion is to use the backquote character macro (see
            8.3.3).


    ____________________________________________________

    (_q_u_o_t_e! _c_o_n_s ! (_c_o_n_s _1 _2) _3) = (_c_o_n_s (_1 . _2) _3)
    (_q_u_o_t_e! _1 !! (_l_i_s_t _2 _3 _4) _5) = (_1 _2 _3 _4 _5)
    (_s_e_t_q _q_u_o_t_e_d '_e_v_a_l_e_d)(_q_u_o_t_e! ! ((_I _a_m  ! _q_u_o_t_e_d))) = ((_I _a_m _e_v_a_l_e_d))
    (_q_u_o_t_e! _t_r_y ! '(_t_h_i_s ! _o_n_e)) = (_t_r_y (_t_h_i_s ! _o_n_e))
    ____________________________________________________


(bignum-to-list 'b_arg)

     RETURNS: A list  of  the  fixnums  which  are  used  to
              represent the bignum.

     NOTE: the inverse of this function is _l_i_s_t-_t_o-_b_i_g_n_u_m.

(list-to-bignum 'l_ints)

     WHERE:   l_ints is a list of fixnums.

     RETURNS: a bignum constructed of the given fixnums.

     NOTE: the inverse of this function is _b_i_g_n_u_m-_t_o-_l_i_s_t.


      _2._1._2.  _l_i_s_t _p_r_e_d_i_c_a_t_e_s


9

9


PS2:9-18                               The Franz Lisp Manual


(dtpr 'g_arg)

     RETURNS: t iff g_arg is a list cell.

     NOTE: that (dtpr '()) is nil.  The name dtpr is a  con-
           traction for ``dotted pair''.

(listp 'g_arg)

     RETURNS: t iff g_arg is a list object or nil.

(tailp 'l_x 'l_y)

     RETURNS: l_x, if a list cell _e_q  to  l_x  is  found  by
              _c_d_ring down l_y zero or more times, nil other-
              wise.


    ____________________________________________________

    -> (_s_e_t_q _x '(_a _b _c _d) _y (_c_d_d_r _x))
    (c d)
    -> (_a_n_d (_d_t_p_r _x) (_l_i_s_t_p _x))     ; x and y are dtprs and lists
    t
    -> (_d_t_p_r '())           ; () is the same as nil and is not a dtpr
    nil
    -> (_l_i_s_t_p '())          ; however it is a list
    t
    -> (_t_a_i_l_p _y _x)
    (c d)
    ____________________________________________________


(length 'l_arg)

     RETURNS: the number of elements in  the  top  level  of
              list l_arg.


      _2._1._3.  _l_i_s_t _a_c_c_e_s_s_i_n_g


9

9


The Franz Lisp Manual                               PS2:9-19


(car 'l_arg)
(cdr 'l_arg)

     RETURNS: _c_o_n_s cell.  (_c_a_r (_c_o_n_s x y)) is always x, (_c_d_r
              (_c_o_n_s  x  y)) is always y.  In FRANZ LISP, the
              cdr portion is located first in memory.   This
              is  hardly  noticeable, and we mention it pri-
              marily as a curiosity.

(c..r 'lh_arg)

     WHERE:   the .. represents any positive number  of  a's
              and d's.

     RETURNS: the result of accessing the list structure  in
              the  way determined by the function name.  The
              a's and d's are read from right to left,  a  _d
              directing  the access down the cdr part of the
              list cell and an _a down the car part.

     NOTE: lh_arg may also be nil, and it is guaranteed that
           the  car  and  cdr of nil is nil.  If lh_arg is a
           hunk,  then  (_c_a_r '_l_h__a_r_g)   is   the   same   as
           (_c_x_r _1 '_l_h__a_r_g) and  (_c_d_r '_l_h__a_r_g) is the same as
           (_c_x_r _0 '_l_h__a_r_g).
           It is generally hard to read and  understand  the
           context  of  functions  with large strings of _a's
           and _d's, but these  functions  are  supported  by
           rapid  accessing  and open-compiling (see Chapter
           12).

(nth 'x_index 'l_list)

     RETURNS: the nth element of l_list, assuming zero-based
              index.   Thus  (nth  0  l_list) is the same as
              (car l_list).  _n_t_h is both a function,  and  a
              compiler  macro,  so  that more efficient code
              might be generated than for _n_t_h_e_l_e_m (described
              below).

     NOTE: If x_arg1 is non-positive  or  greater  than  the
           length of the list, nil is returned.


9

9


PS2:9-20                               The Franz Lisp Manual


(nthcdr 'x_index 'l_list)

     RETURNS: the result of  _c_d_ring  down  the  list  l_list
              x_index times.

     NOTE: If    x_index    is    less    than    0,    then
           (_c_o_n_s _n_i_l '_l__l_i_s_t) is returned.

(nthelem 'x_arg1 'l_arg2)

     RETURNS: The x_arg1'_s_t element of the list l_arg2.

     NOTE: This function comes from the PDP-11 Lisp system.

(last 'l_arg)

     RETURNS: the last list cell in the list l_arg.

     EXAMPLE: _l_a_s_t does NOT return the  last  element  of  a
              list!
              (_l_a_s_t '(_a _b)) = (b)

(ldiff 'l_x 'l_y)

     RETURNS: a  list  of all elements in l_x but not in l_y
              , i.e., the list difference of l_x and l_y.

     NOTE: l_y must be a tail of l_x, i.e., _e_q to the result
           of  applying  some  number  of _c_d_r's to l_x. Note
           that  the  value   of   _l_d_i_f_f   is   always   new
           list  structure  unless l_y is nil, in which case
           (_l_d_i_f_f _l__x _n_i_l) is l_x itself.  If l_y   is   not
           a  tail  of  l_x, _l_d_i_f_f generates an error.

     EXAMPLE: (_l_d_i_f_f '_l__x (_m_e_m_b_e_r '_g__f_o_o  '_l__x))  gives  all
              elements in l_x up to the first g_foo.


      _2._1._4.  _l_i_s_t _m_a_n_i_p_u_l_a_t_i_o_n

(rplaca 'lh_arg1 'g_arg2)

     RETURNS: the modified lh_arg1.

     SIDE EFFECT: the car of lh_arg1 is set to  g_arg2.   If
                  lh_arg1  is a hunk then the second element
                  of the hunk is set to g_arg2.


9

9


The Franz Lisp Manual                               PS2:9-21


(rplacd 'lh_arg1 'g_arg2)

     RETURNS: the modified lh_arg1.

     SIDE EFFECT: the cdr of lh_arg2 is set to  g_arg2.   If
                  lh_arg1  is  a hunk then the first element
                  of the hunk is set to g_arg2.


(attach 'g_x 'l_l)

     RETURNS: l_l whose _c_a_r is now g_x, whose  _c_a_d_r  is  the
              original (_c_a_r _l__l), and whose _c_d_d_r is the ori-
              ginal (_c_d_r _l__l).

     NOTE: what happens is that g_x is added to  the  begin-
           ning  of  list l_l  yet maintaining the same list
           cell  at the beginning of the list.

(delete 'g_val 'l_list ['x_count])

     RETURNS: the result of  splicing  g_val  from  the  top
              level of l_list no more than x_count times.

     NOTE: x_count defaults to a very large number, thus  if
           x_count  is  not  given, all occurrences of g_val
           are removed from the top level of l_list.   g_val
           is compared with successive _c_a_r's of l_list using
           the function _e_q_u_a_l.

     SIDE EFFECT: l_list is modified using  rplacd,  no  new
                  list cells are used.

(delq 'g_val 'l_list ['x_count])
(dremove 'g_val 'l_list ['x_count])

     RETURNS: the result of  splicing  g_val  from  the  top
              level of l_list no more than x_count times.

     NOTE: _d_e_l_q (and _d_r_e_m_o_v_e) are the same as _d_e_l_e_t_e  except
           that _e_q is used for comparison instead of _e_q_u_a_l.


9

9


PS2:9-22                               The Franz Lisp Manual


    ____________________________________________________

    ; note that you should use the value returned by _d_e_l_e_t_e or _d_e_l_q
    ; and not assume that g_val will always show the deletions.
    ; For example

    -> (_s_e_t_q _t_e_s_t '(_a _b _c _a _d _e))
    (a b c a d e)
    -> (_d_e_l_e_t_e '_a _t_e_s_t)
    (b c d e)         ; the value returned is what we would expect
    -> _t_e_s_t
    (a b c d e)       ; but test still has the first a in the list!
    ____________________________________________________


(remq 'g_x 'l_l ['x_count])
(remove 'g_x 'l_l)

     RETURNS: a _c_o_p_y of l_l  with  all  top  level  elements
              _e_q_u_a_l to g_x removed.  _r_e_m_q uses _e_q instead of
              _e_q_u_a_l for comparisons.

     NOTE: remove does not modify its arguments like _d_e_l_e_t_e,
           and _d_e_l_q do.

(insert 'g_object 'l_list 'u_comparefn 'g_nodups)

     RETURNS: a list consisting of l_list with g_object des-
              tructively  inserted  in a place determined by
              the ordering function u_comparefn.

     NOTE: (_c_o_m_p_a_r_e_f_n '_g__x  '_g__y)  should  return  something
           non-nil  if  g_x can precede g_y in sorted order,
           nil if g_y must precede g_x.  If  u_comparefn  is
           nil, alphabetical order will be used. If g_nodups
           is non-nil, an element will not be inserted if an
           equal  element  is  already  in the list.  _i_n_s_e_r_t
           does binary search to determine where  to  insert
           the new element.


9

9


The Franz Lisp Manual                               PS2:9-23


(merge 'l_data1 'l_data2 'u_comparefn)

     RETURNS: the merged list of the two input sorted  lists
              l_data1  and  l_data1  using binary comparison
              function u_comparefn.

     NOTE: (_c_o_m_p_a_r_e_f_n '_g__x  '_g__y)  should  return  something
           non-nil  if  g_x can precede g_y in sorted order,
           nil if g_y must precede g_x.  If  u_comparefn  is
           nil,    alphabetical    order   will   be   used.
           u_comparefn should be thought of as "less than or
           equal".   _m_e_r_g_e  changes  both  of its data argu-
           ments.

(subst 'g_x 'g_y 'l_s)
(dsubst 'g_x 'g_y 'l_s)

     RETURNS: the result of substituting g_x for  all  _e_q_u_a_l
              occurrences of g_y  at all levels in l_s.

     NOTE: If g_y is a symbol, _e_q will be used for comparis-
           ons.   The function _s_u_b_s_t does not modify l_s but
           the function  _d_s_u_b_s_t  (destructive  substitution)
           does.

(lsubst 'l_x 'g_y 'l_s)

     RETURNS: a copy of l_s  with l_x spliced in  for  every
              occurrence  of  of g_y at all levels. Splicing
              in means that the parentheses surrounding  the
              list  l_x  are  removed  as  the example below
              shows.


    ____________________________________________________

    -> (_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
    ((a b c) y z ((a b c) y z) ((a b c) y z))
    -> (_l_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
    (a b c y z (a b c y z) (a b c y z))
    ____________________________________________________


9

9


PS2:9-24                               The Franz Lisp Manual


(subpair 'l_old 'l_new 'l_expr)

     WHERE:   there are  the  same  number  of  elements  in
              l_old as l_new.

     RETURNS: the list l_expr  with  all  occurrences  of  a
              object  in l_old replaced by the corresponding
              one in l_new.  When a substitution is made,  a
              copy  of  the  value  to  substitute in is not
              made.

     EXAMPLE: (_s_u_b_p_a_i_r '(_a _c)' (_x _y) '(_a _b _c _d)) = (_x _b _y _d)


(nconc 'l_arg1 'l_arg2 ['l_arg3 ...])

     RETURNS: A list consisting of the  elements  of  l_arg1
              followed by the elements of l_arg2 followed by
              l_arg3 and so on.

     NOTE: The _c_d_r of  the  last  list  cell  of  l_arg_i  is
           changed to point to l_arg_i+_1.


    ____________________________________________________

    ; _n_c_o_n_c is faster than _a_p_p_e_n_d because it doesn't allocate new list cells.
    -> (_s_e_t_q _l_i_s_1 '(_a _b _c))
    (a b c)
    -> (_s_e_t_q _l_i_s_2 '(_d _e _f))
    (d e f)
    -> (_a_p_p_e_n_d _l_i_s_1 _l_i_s_2)
    (a b c d e f)
    -> _l_i_s_1
    (a b c)       ; note that lis1 has not been changed by _a_p_p_e_n_d
    -> (_n_c_o_n_c _l_i_s_1 _l_i_s_2)
    (a b c d e f) ; _n_c_o_n_c returns the same value as _a_p_p_e_n_d
    -> _l_i_s_1
    (a b c d e f) ; but in doing so alters lis1
    ____________________________________________________


9

9


The Franz Lisp Manual                               PS2:9-25


(reverse 'l_arg)
(nreverse 'l_arg)

     RETURNS: the list l_arg with the elements  at  the  top
              level in reverse  order.

     NOTE: The function _n_r_e_v_e_r_s_e does the reversal in place,
           that is the list structure is modified.

(nreconc 'l_arg 'g_arg)

     EQUIVALENT TO: (_n_c_o_n_c (_n_r_e_v_e_r_s_e '_l__a_r_g) '_g__a_r_g)


   _2._2.  _P_r_e_d_i_c_a_t_e_s

           The following functions test  for  properties  of
      data  objects.  When  the result of the test is either
      'false' or 'true',  then  nil  will  be  returned  for
      'false' and something other than nil (often t) will be
      returned for 'true'.

(arrayp 'g_arg)

     RETURNS: t iff g_arg is of type array.

(atom 'g_arg)

     RETURNS: t iff g_arg is not a list or hunk object.

     NOTE: (_a_t_o_m '()) returns t.

(bcdp 'g_arg)

     RETURNS: t iff g_arg is a data object of type binary.

     NOTE: This function is a throwback to the  PDP-11  Lisp
           system.   The  name stands for binary code predi-
           cate.


9

9


PS2:9-26                               The Franz Lisp Manual


(bigp 'g_arg)

     RETURNS: t iff g_arg is a bignum.

(dtpr 'g_arg)

     RETURNS: t iff g_arg is a list cell.

     NOTE: that (dtpr '()) is nil.

(hunkp 'g_arg)

     RETURNS: t iff g_arg is a hunk.

(listp 'g_arg)

     RETURNS: t iff g_arg is a list object or nil.

(stringp 'g_arg)

     RETURNS: t iff g_arg is a string.

(symbolp 'g_arg)

     RETURNS: t iff g_arg is a symbol.

(valuep 'g_arg)

     RETURNS: t iff g_arg is a value cell

(vectorp 'v_vector)

     RETURNS: t iff the argument is a vector.

(vectorip 'v_vector)

     RETURNS: t iff the argument is an immediate-vector.

(type 'g_arg)
(typep 'g_arg)

     RETURNS: a symbol whose pname  describes  the  type  of
              g_arg.


9

9


The Franz Lisp Manual                               PS2:9-27


(signp s_test 'g_val)

     RETURNS: t iff g_val is a number  and  the  given  test
              s_test on g_val returns true.

     NOTE: The fact that _s_i_g_n_p simply returns nil  if  g_val
           is  not  a  number is probably the most important
           reason that _s_i_g_n_p is used.  The permitted  values
           for  s_test  and what they mean are given in this
           table.


8                           ____________________
                            s_test   tested

8                           ________________________________________
                            l        g_val < 0
                            le       g_val <_ 0
                            e        g_val = 0
                            n        g_val =/ 0
                            ge       g_val >_ 0
                            g        g_val > 0
8                           ____________________
7                           |7|7|7|7|7|7|7|7|


                                               |7|7|7|7|7|7|7|7|


(eq 'g_arg1 'g_arg2)

     RETURNS: t if g_arg1 and g_arg2 are the exact same lisp
              object.

     NOTE: _E_q simply tests if g_arg1 and g_arg2 are  located
           in  the exact same place in memory.  Lisp objects
           which print the same are not necessarily _e_q.  The
           only  objects  guaranteed  to  be _e_q are interned
           symbols with the same print name.  [Unless a sym-
           bol  is  created  in  a special way (such as with
           _u_c_o_n_c_a_t or _m_a_k_n_a_m) it will be interned.]

(neq 'g_x 'g_y)

     RETURNS: t if g_x is not _e_q to g_y, otherwise nil.


9


PS2:9-28                               The Franz Lisp Manual


(equal 'g_arg1 'g_arg2)
(eqstr 'g_arg1 'g_arg2)

     RETURNS: t iff g_arg1 and g_arg2 have the  same  struc-
              ture as described below.

     NOTE: g_arg and g_arg2 are _e_q_u_a_l if

      (1)   they are _e_q.

      (2)   they are both fixnums with the same value

      (3)   they are both flonums with the same value

      (4)   they are both bignums with the same value

      (5)   they are both strings and are identical.

      (6)   they are both lists and their cars and cdrs  are
            _e_q_u_a_l.


    ____________________________________________________

    ; _e_q is much faster than _e_q_u_a_l, especially in compiled code,
    ; however you cannot use _e_q to test for equality of numbers outside
    ; of the range -1024 to 1023.  _e_q_u_a_l will always work.
    -> (_e_q _1_0_2_3 _1_0_2_3)
    t
    -> (_e_q _1_0_2_4 _1_0_2_4)
    nil
    -> (_e_q_u_a_l _1_0_2_4 _1_0_2_4)
    t
    ____________________________________________________


(not 'g_arg)
(null 'g_arg)

     RETURNS: t iff g_arg is nil.


9

9


The Franz Lisp Manual                               PS2:9-29


(member 'g_arg1 'l_arg2)
(memq 'g_arg1 'l_arg2)

     RETURNS: that part of the  l_arg2  beginning  with  the
              first  occurrence of g_arg1.  If g_arg1 is not
              in the top level of l_arg2, nil is returned.

     NOTE: _m_e_m_b_e_r tests for equality with _e_q_u_a_l, _m_e_m_q  tests
           for equality with _e_q.


   _2._3.  _S_y_m_b_o_l_s _a_n_d _S_t_r_i_n_g_s

           In many of the following functions  the  distinc-
      tion  between symbols and strings is somewhat blurred.
      To remind ourselves of the difference, a string  is  a
      null terminated sequence of characters, stored as com-
      pactly as possible.  Strings are used as constants  in
      FRANZ  LISP.   They  _e_v_a_l to themselves.  A symbol has
      additional structure: a value, property list, function
      binding,  as  well  as its external representation (or
      print-name).  If a symbol  is  given  to  one  of  the
      string  manipulation  functions  below, its print name
      will be used as the string.

           Another popular way to represent strings in  Lisp
      is  as  a  list of fixnums which represent characters.
      The suffix 'n' to a string manipulation function indi-
      cates that it returns a string in this form.


      _2._3._1.  _s_y_m_b_o_l _a_n_d _s_t_r_i_n_g _c_r_e_a_t_i_o_n

(concat ['stn_arg1 ... ])
(uconcat ['stn_arg1 ... ])

     RETURNS: a symbol whose print name  is  the  result  of
              concatenating  the print names, string charac-
              ters  or  numerical  representations  of   the
              sn_arg_i.

     NOTE: If no arguments are given, a symbol with  a  null
           pname  is  returned.   _c_o_n_c_a_t  places  the symbol
           created on the oblist, the function _u_c_o_n_c_a_t  does
           the  same thing but does not place the new symbol
           on the oblist.

     EXAMPLE: (_c_o_n_c_a_t '_a_b_c (_a_d_d _3 _4) "_d_e_f") = abc7def

9

9


PS2:9-30                               The Franz Lisp Manual


(concatl 'l_arg)

     EQUIVALENT TO: (_a_p_p_l_y '_c_o_n_c_a_t '_l__a_r_g)


(implode 'l_arg)
(maknam 'l_arg)

     WHERE:   l_arg is a list of symbols, strings and  small
              fixnums.

     RETURNS: The symbol whose print name is the  result  of
              concatenating  the  first  characters  of  the
              print names of the symbols and strings in  the
              list.    Any  fixnums  are  converted  to  the
              equivalent ascii character.  In order to  con-
              catenate  entire  strings  or print names, use
              the function _c_o_n_c_a_t.

     NOTE: _i_m_p_l_o_d_e interns the  symbol  it  creates,  _m_a_k_n_a_m
           does not.

(gensym ['s_leader])

     RETURNS: a new uninterned atom beginning with the first
              character  of  s_leader's  pname, or beginning
              with g if s_leader is not given.

     NOTE: The  symbol  looks  like  x0nnnnn  where   x   is
           s_leader's  first  character  and  nnnnn  is  the
           number of times you have called gensym.

(copysymbol 's_arg 'g_pred)

     RETURNS: an uninterned symbol with the same print  name
              as  s_arg.   If  g_pred  is  non nil, then the
              value, function binding and property  list  of
              the new symbol are made _e_q to those of s_arg.


(ascii 'x_charnum)

     WHERE:   x_charnum is between 0 and 255.

     RETURNS: a symbol whose print name is the single  char-
              acter    whose    fixnum   representation   is
              x_charnum.


9

9


The Franz Lisp Manual                               PS2:9-31


(intern 's_arg)

     RETURNS: s_arg

     SIDE EFFECT: s_arg is put on the oblist if  it  is  not
                  already there.

(remob 's_symbol)

     RETURNS: s_symbol

     SIDE EFFECT: s_symbol is removed from the oblist.

(rematom 's_arg)

     RETURNS: t if s_arg is indeed an atom.

     SIDE EFFECT: s_arg is  put  on  the  free  atoms  list,
                  effectively reclaiming an atom cell.

     NOTE: This function does _n_o_t check to see if  s_arg  is
           on  the  oblist  or is referenced anywhere.  Thus
           calling _r_e_m_a_t_o_m on an  atom  in  the  oblist  may
           result in disaster when that atom cell is reused!


      _2._3._2.  _s_t_r_i_n_g _a_n_d _s_y_m_b_o_l _p_r_e_d_i_c_a_t_e_s

(boundp 's_name)

     RETURNS: nil  if s_name is unbound:  that  is,  it  has
              never  been  given a value.  If x_name has the
              value g_val, then (nil . g_val)  is  returned.
              See also _m_a_k_u_n_b_o_u_n_d.

(alphalessp 'st_arg1 'st_arg2)

     RETURNS: t iff the `name' of st_arg1 is  alphabetically
              less  than the name of st_arg2. If st_arg is a
              symbol then its `name' is its print name.   If
              st_arg  is  a  string,  then its `name' is the
              string itself.


      _2._3._3.  _s_y_m_b_o_l _a_n_d _s_t_r_i_n_g _a_c_c_e_s_s_i_n_g


9

9


PS2:9-32                               The Franz Lisp Manual


(symeval 's_arg)

     RETURNS: the value of symbol s_arg.

     NOTE: It is illegal to ask for the value of an  unbound
           symbol.   This  function  has  the same effect as
           _e_v_a_l, but compiles into much more efficient code.

(get_pname 's_arg)

     RETURNS: the string which is the print name of s_arg.

(plist 's_arg)

     RETURNS: the property list of s_arg.

(getd 's_arg)

     RETURNS: the function definition of  s_arg  or  nil  if
              there is no function definition.

     NOTE: the function definition may turn  out  to  be  an
           array header.

(getchar 's_arg 'x_index)
(nthchar 's_arg 'x_index)
(getcharn 's_arg 'x_index)

     RETURNS: the x_index_t_h character of the print  name  of
              s_arg  or  nil  if  x_index  is less than 1 or
              greater than the length of s_arg's print name.

     NOTE: _g_e_t_c_h_a_r and _n_t_h_c_h_a_r return a symbol with a single
           character print name, _g_e_t_c_h_a_r_n returns the fixnum
           representation of the character.

(substring 'st_string 'x_index ['x_length])
(substringn 'st_string 'x_index ['x_length])

     RETURNS: a string of length at most  x_length  starting
              at x_index_t_h character in the string.

     NOTE: If x_length is not given, all of  the  characters
           for   x_index  to  the  end  of  the  string  are
           returned.  If  x_index  is  negative  the  string
           begins  at  the x_index_t_h character from the end.
           If x_index is out of bounds, nil is returned.

     NOTE: _s_u_b_s_t_r_i_n_g returns a list of  symbols,  _s_u_b_s_t_r_i_n_g_n
           returns  a  list  of  fixnums.   If _s_u_b_s_t_r_i_n_g_n is
           given a 0 x_length argument then a single  fixnum
           which is the x_index_t_h character is returned.
9

9


The Franz Lisp Manual                               PS2:9-33


      _2._3._4.  _s_y_m_b_o_l _a_n_d _s_t_r_i_n_g _m_a_n_i_p_u_l_a_t_i_o_n

(set 's_arg1 'g_arg2)

     RETURNS: g_arg2.

     SIDE EFFECT: the value of s_arg1 is set to g_arg2.

(setq s_atm1 'g_val1 [ s_atm2 'g_val2 ... ... ])

     WHERE:   the arguments are  pairs  of  atom  names  and
              expressions.

     RETURNS: the last g_val_i.

     SIDE EFFECT: each s_atm_i  is  set  to  have  the  value
                  g_val_i.

     NOTE: _s_e_t evaluates all of its arguments, _s_e_t_q does not
           evaluate the s_atm_i.

(desetq sl_pattern1 'g_exp1 [... ...])

     RETURNS: g_expn

     SIDE EFFECT: This  acts  just  like  _s_e_t_q  if  all  the
                  sl_pattern_i  are  symbols.  If sl_pattern_i
                  is a list then it   is  a  template  which
                  should  have  the same structure as g_exp_i
                  The symbols in sl_pattern are assigned  to
                  the  corresponding  parts  of g_exp.  (See
                  also _s_e_t_f )

     EXAMPLE: (_d_e_s_e_t_q (_a _b (_c . _d)) '(_1 _2 (_3 _4 _5)))
              sets a to 1, b to 2, c to 3, and d to (4 5).


(setplist 's_atm 'l_plist)

     RETURNS: l_plist.

     SIDE EFFECT: the property  list  of  s_atm  is  set  to
                  l_plist.


9

9


PS2:9-34                               The Franz Lisp Manual


(makunbound 's_arg)

     RETURNS: s_arg

     SIDE EFFECT: the value of s_arg is made `unbound'.   If
                  the interpreter attempts to evaluate s_arg
                  before it  is  again  given  a  value,  an
                  unbound variable error will occur.

(aexplode 's_arg)
(explode 'g_arg)
(aexplodec 's_arg)
(explodec 'g_arg)
(aexploden 's_arg)
(exploden 'g_arg)

     RETURNS: a list of the characters  used  to  print  out
              s_arg or g_arg.

     NOTE: The functions beginning  with  'a'  are  internal
           functions  which are limited to symbol arguments.
           The functions _a_e_x_p_l_o_d_e and _e_x_p_l_o_d_e return a  list
           of  characters which _p_r_i_n_t would use to print the
           argument. These characters include all  necessary
           escape   characters.    Functions  _a_e_x_p_l_o_d_e_c  and
           _e_x_p_l_o_d_e_c return a list of characters which  _p_a_t_o_m
           would  use  to print the argument (i.e. no escape
           characters).  Functions  _a_e_x_p_l_o_d_e_n  and  _e_x_p_l_o_d_e_n
           are similar to _a_e_x_p_l_o_d_e_c and _e_x_p_l_o_d_e_c except that
           a list of fixnum equivalents  of  characters  are
           returned.


    ____________________________________________________

    -> (_s_e_t_q _x '|_q_u_o_t_e _t_h_i_s _\| _o_k?|)
    |quote this \| ok?|
    -> (_e_x_p_l_o_d_e _x)
    (q u o t e |\\| | | t h i s |\\| | | |\\| |\|| |\\| | | o k ?)
    ; note that |\\| just means the single character: backslash.
    ; and |\|| just means the single character: vertical bar
    ; and | | means the single character: space

    -> (_e_x_p_l_o_d_e_c _x)
    (q u o t e | | t h i s | | |\|| | | o k ?)
    -> (_e_x_p_l_o_d_e_n _x)
    (113 117 111 116 101 32 116 104 105 115 32 124 32 111 107 63)
    ____________________________________________________


9

9


The Franz Lisp Manual                               PS2:9-35


   _2._4.  _V_e_c_t_o_r_s

           See Chapter 9 for a discussion of vectors.   They
      are  less efficient that hunks but more efficient than
      arrays.


      _2._4._1.  _v_e_c_t_o_r _c_r_e_a_t_i_o_n

(new-vector 'x_size ['g_fill ['g_prop]])

     RETURNS: A vector of length x_size.  Each data entry is
              initialized to g_fill, or to nil, if the argu-
              ment g_fill is not present.  The vector's pro-
              perty is set to g_prop, or to nil, by default.

(new-vectori-byte 'x_size ['g_fill ['g_prop]])
(new-vectori-word 'x_size ['g_fill ['g_prop]])
(new-vectori-long 'x_size ['g_fill ['g_prop]])

     RETURNS: A vectori with x_size  elements  in  it.   The
              actual  memory requirement is two long words +
              x_size*(n  bytes),  where  n  is  1  for  new-
              vector-byte,  2  for new-vector-word, or 4 for
              new-vectori-long.  Each data entry is initial-
              ized  to  g_fill,  or to zero, if the argument
              g_fill is not present.  The vector's  property
              is set to g_prop, or nil, by default.


     Vectors may be created by specifying  multiple  initial
     values:

(vector ['g_val0 'g_val1 ...])

     RETURNS: a vector, with as many data elements as  there
              are arguments.  It is quite possible to have a
              vector with no data  elements.   The  vector's
              property will be a null list.


9

9


PS2:9-36                               The Franz Lisp Manual


(vectori-byte ['x_val0 'x_val2 ...])
(vectori-word ['x_val0 'x_val2 ...])
(vectori-long ['x_val0 'x_val2 ...])

     RETURNS: a vectori, with as many data elements as there
              are  arguments.  The arguments are required to
              be fixnums.  Only the low order byte  or  word
              is  used  in  the  case  of  vectori-byte  and
              vectori-word.  The vector's property  will  be
              null.


      _2._4._2.  _v_e_c_t_o_r _r_e_f_e_r_e_n_c_e

(vref 'v_vect 'x_index)
(vrefi-byte 'V_vect 'x_bindex)
(vrefi-word 'V_vect 'x_windex)
(vrefi-long 'V_vect 'x_lindex)

     RETURNS: the desired data element from a  vector.   The
              indices  must  be  fixnums.  Indexing is zero-
              based.  The vrefi functions  sign  extend  the
              data.

(vprop 'Vv_vect)

     RETURNS: The Lisp property associated with a vector.

(vget 'Vv_vect 'g_ind)

     RETURNS: The value stored under g_ind if the Lisp  pro-
              perty  associated  with 'Vv_vect is a disembo-
              died property list.

(vsize 'Vv_vect)
(vsize-byte 'V_vect)
(vsize-word 'V_vect)

     RETURNS: the number of data  elements  in  the  vector.
              For  immediate-vectors,  the  functions vsize-
              byte and vsize-word return the number of  data
              elements,  if one thinks of the binary data as
              being comprised of bytes or words.


      _2._4._3.  _v_e_c_t_o_r _m_o_d_f_i_c_a_t_i_o_n


9

9


The Franz Lisp Manual                               PS2:9-37


(vset 'v_vect 'x_index 'g_val)
(vseti-byte 'V_vect 'x_bindex 'x_val)
(vseti-word 'V_vect 'x_windex 'x_val)
(vseti-long 'V_vect 'x_lindex 'x_val)

     RETURNS: the datum.

     SIDE EFFECT: The indexed element of the vector  is  set
                  to  the value.  As noted above, for vseti-
                  word and vseti-byte,  the  index  is  con-
                  strued  as  the number of the data element
                  within the  vector.   It  is  not  a  byte
                  address.   Also,  for those two functions,
                  the low order byte or  word  of  x_val  is
                  what is stored.

(vsetprop 'Vv_vect 'g_value)

     RETURNS: g_value.  This should be either a symbol or  a
              disembodied  property list whose _c_a_r is a sym-
              bol identifying the type of the vector.

     SIDE EFFECT: the property list of  Vv_vect  is  set  to
                  g_value.

(vputprop 'Vv_vect 'g_value 'g_ind)

     RETURNS: g_value.

     SIDE EFFECT: If the vector property  of  Vv_vect  is  a
                  disembodied  property  list, then vputprop
                  adds the value g_value under the indicator
                  g_ind.  Otherwise, the old vector property
                  is made the first element of the list.


   _2._5.  _A_r_r_a_y_s

           See Chapter  9  for  a  complete  description  of
      arrays.  Some of these functions are part of a Maclisp
      array compatibility package representing only one sim-
      ple way of using the array structure of FRANZ LISP.


      _2._5._1.  _a_r_r_a_y _c_r_e_a_t_i_o_n


9

9


PS2:9-38                               The Franz Lisp Manual


(marray 'g_data 's_access 'g_aux 'x_length 'x_delta)

     RETURNS: an array type with the fields set up from  the
              above  arguments  in  the  obvious  way  (see
              1.2.10).

(*array 's_name 's_type 'x_dim1 ... 'x_dim_n)
(array s_name s_type x_dim1 ... x_dim_n)

     WHERE:   s_type may be one of t, nil,  fixnum,  flonum,
              fixnum-block and flonum-block.

     RETURNS: an array of type s_type with n  dimensions  of
              extents given by the x_dim_i.

     SIDE EFFECT: If s_name is non nil, the function defini-
                  tion  of s_name is set to the array struc-
                  ture returned.

     NOTE: These  functions  create  a  Maclisp   compatible
           array.  In FRANZ LISP arrays of type t, nil, fix-
           num and flonum are equivalent and the elements of
           these  arrays  can  be  any  type of lisp object.
           Fixnum-block and  flonum-block  arrays  are  res-
           tricted  to  fixnums and flonums respectively and
           are used mainly to communicate with foreign func-
           tions (see 8.5).

     NOTE: *_a_r_r_a_y evaluates its arguments, _a_r_r_a_y does not.


      _2._5._2.  _a_r_r_a_y _p_r_e_d_i_c_a_t_e

(arrayp 'g_arg)

     RETURNS: t iff g_arg is of type array.


      _2._5._3.  _a_r_r_a_y _a_c_c_e_s_s_o_r_s


9

9


The Franz Lisp Manual                               PS2:9-39


(getaccess 'a_array)
(getaux 'a_array)
(getdelta 'a_array)
(getdata 'a_array)
(getlength 'a_array)

     RETURNS: the field of the array object a_array given by
              the function name.

(arrayref 'a_name 'x_ind)

     RETURNS: the  x_ind_t_h  element  of  the  array   object
              a_name.  x_ind of zero accesses the first ele-
              ment.

     NOTE: _a_r_r_a_y_r_e_f uses the data, length and  delta  fields
           of a_name to determine which object to return.

(arraycall s_type 'as_array 'x_ind1 ... )

     RETURNS: the element selected by  the indices from  the
              array a_array of type s_type.

     NOTE: If as_array is a symbol then the function binding
           of this symbol should contain an array object.
           s_type is ignored by _a_r_r_a_y_c_a_l_l  but  is  included
           for compatibility with Maclisp.

(arraydims 's_name)

     RETURNS: a list of the type and  bounds  of  the  array
              s_name.

(listarray 'sa_array ['x_elements])

     RETURNS: a  list  of  all  of  the  elements  in  array
              sa_array.   If  x_elements is given, then only
              the first x_elements are returned.


9

9


PS2:9-40                               The Franz Lisp Manual


    ____________________________________________________

    ; We will create a 3 by 4 array of general lisp objects
    -> (_a_r_r_a_y _e_r_n_i_e _t _3 _4)
    array[12]

    ; the array header is stored in the function definition slot of the
    ; symbol ernie
    -> (_a_r_r_a_y_p (_g_e_t_d '_e_r_n_i_e))
    t
    -> (_a_r_r_a_y_d_i_m_s (_g_e_t_d '_e_r_n_i_e))
    (t 3 4)

    ; store in ernie[2][2] the list (test list)
    -> (_s_t_o_r_e (_e_r_n_i_e _2 _2) '(_t_e_s_t _l_i_s_t))
    (test list)

    ; check to see if it is there
    -> (_e_r_n_i_e _2 _2)
    (test list)

    ; now use the low level function _a_r_r_a_y_r_e_f to find the same element
    ; arrays are 0 based and row-major (the last subscript varies the fastest)
    ; thus element [2][2] is the 10th element , (starting at 0).
    -> (_a_r_r_a_y_r_e_f (_g_e_t_d '_e_r_n_i_e) _1_0)
    (ptr to)(test list)    ; the result is a value cell (thus the (ptr to))
    ____________________________________________________


      _2._5._4.  _a_r_r_a_y _m_a_n_i_p_u_l_a_t_i_o_n

(putaccess 'a_array 'su_func)
(putaux 'a_array 'g_aux)
(putdata 'a_array 'g_arg)
(putdelta 'a_array 'x_delta)
(putlength 'a_array 'x_length)

     RETURNS: the second argument to the function.

     SIDE EFFECT: The field of the array object given by the
                  function  name  is  replaced by the second
                  argument to the function.


9

9


The Franz Lisp Manual                               PS2:9-41


(store 'l_arexp 'g_val)

     WHERE:   l_arexp is an expression which  references  an
              array element.

     RETURNS: g_val

     SIDE EFFECT: the array location which contains the ele-
                  ment  which  l_arexp references is changed
                  to contain g_val.

(fillarray 's_array 'l_itms)

     RETURNS: s_array

     SIDE EFFECT: the array s_array is filled with  elements
                  from l_itms.  If there are not enough ele-
                  ments in l_itms to fill the entire  array,
                  then the last element of l_itms is used to
                  fill the remaining parts of the array.


   _2._6.  _H_u_n_k_s

           Hunks are  vector-like  objects  whose  size  can
      range  from  1 to 128 elements.  Internally, hunks are
      allocated in sizes which are powers of 2.  In order to
      create  hunks  of  a  given size, a hunk with at least
      that many elements is allocated  and  a  distinguished
      symbol   EMPTY   is   placed  in  those  elements  not
      requested.  Most hunk  functions  respect  those  dis-
      tinguished  symbols,  but  there are two (*_m_a_k_h_u_n_k and
      *_r_p_l_a_c_x) which will overwrite the  distinguished  sym-
      bol.


      _2._6._1.  _h_u_n_k _c_r_e_a_t_i_o_n

(hunk 'g_val1 ['g_val2 ... 'g_val_n])

     RETURNS: a hunk of length n whose elements are initial-
              ized to the g_val_i.

     NOTE: the maximum size of a hunk is 128.

     EXAMPLE: (_h_u_n_k _4 '_s_h_a_r_p '_k_e_y_s) = {4 sharp keys}


9

9


PS2:9-42                               The Franz Lisp Manual


(makhunk 'xl_arg)

     RETURNS: a hunk of length  xl_arg  initialized  to  all
              nils  if  xl_arg  is a fixnum.  If xl_arg is a
              list,  then  we  return   a   hunk   of   size
              (_l_e_n_g_t_h '_x_l__a_r_g)  initialized  to the elements
              in xl_arg.

     NOTE: (_m_a_k_h_u_n_k '(_a _b _c))     is      equivalent      to
           (_h_u_n_k '_a '_b '_c).

     EXAMPLE: (_m_a_k_h_u_n_k _4) = {_n_i_l _n_i_l _n_i_l _n_i_l}

(*makhunk 'x_arg)

     RETURNS: a hunk of size 2[x_arg] initialized to EMPTY.

     NOTE: This is only to be used by such functions as _h_u_n_k
           and _m_a_k_h_u_n_k which create and initialize hunks for
           users.


      _2._6._2.  _h_u_n_k _a_c_c_e_s_s_o_r

(cxr 'x_ind 'h_hunk)

     RETURNS: element x_ind (starting at 0) of hunk h_hunk.

(hunk-to-list 'h_hunk)

     RETURNS: a list consisting of the elements of h_hunk.


      _2._6._3.  _h_u_n_k _m_a_n_i_p_u_l_a_t_o_r_s

(rplacx 'x_ind 'h_hunk 'g_val)
(*rplacx 'x_ind 'h_hunk 'g_val)

     RETURNS: h_hunk

     SIDE EFFECT: Element x_ind (starting at 0) of h_hunk is
                  set to g_val.

     NOTE: _r_p_l_a_c_x will not modify one of  the  distinguished
           (EMPTY) elements whereas *_r_p_l_a_c_x will.


9

9


The Franz Lisp Manual                               PS2:9-43


(hunksize 'h_arg)

     RETURNS: the size of the hunk h_arg.

     EXAMPLE: (_h_u_n_k_s_i_z_e (_h_u_n_k _1 _2 _3)) = 3


   _2._7.  _B_c_d_s

           A bcd object contains a pointer to compiled  code
      and  to  the type of function object the compiled code
      represents.

(getdisc 'y_bcd)
(getentry 'y_bcd)

     RETURNS: the field of the bcd object given by the func-
              tion name.

(putdisc 'y_func 's_discipline)

     RETURNS: s_discipline

     SIDE EFFECT: Sets the discipline  field  of  y_func  to
                  s_discipline.


   _2._8.  _S_t_r_u_c_t_u_r_e_s

           There are three common structures constructed out
      of  list  cells: the assoc list, the property list and
      the tconc list.  The functions below manipulate  these
      structures.


      _2._8._1.  _a_s_s_o_c _l_i_s_t

              An `assoc list' (or alist) is  a  common  lisp
         data structure.  It has the form
         ((key1 . value1) (key2 . value2) (key3 . value3) ... (keyn . valuen))


9

9


PS2:9-44                               The Franz Lisp Manual


(assoc 'g_arg1 'l_arg2)
(assq 'g_arg1 'l_arg2)

     RETURNS: the first top level element  of  l_arg2  whose
              _c_a_r is _e_q_u_a_l (with _a_s_s_o_c) or _e_q (with _a_s_s_q) to
              g_arg1.

     NOTE: Usually l_arg2 has an _a-_l_i_s_t structure and g_arg1
           acts as key.

(sassoc 'g_arg1 'l_arg2 'sl_func)

     RETURNS: the                 result                  of
              (_c_o_n_d ((_a_s_s_o_c '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))

     NOTE: sassoc is written as a macro.

(sassq 'g_arg1 'l_arg2 'sl_func)

     RETURNS: the                 result                  of
              (_c_o_n_d ((_a_s_s_q '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))

     NOTE: sassq is written as a macro.


    ____________________________________________________

    ; _a_s_s_o_c or _a_s_s_q is given a key and an assoc list and returns
    ; the key and value item if it exists, they differ only in how they test
    ; for equality of the keys.

    -> (_s_e_t_q _a_l_i_s_t '((_a_l_p_h_a . _a) ( (_c_o_m_p_l_e_x _k_e_y) . _b) (_j_u_n_k . _x)))
    ((alpha . a) ((complex key) . b) (junk . x))

    ; we should use _a_s_s_q when the key is an atom
    -> (_a_s_s_q '_a_l_p_h_a _a_l_i_s_t)
    (alpha . a)

    ; but it may not work when the key is a list
    -> (_a_s_s_q '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
    nil

    ; however _a_s_s_o_c will always work
    -> (_a_s_s_o_c '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
    ((complex key) . b)
    ____________________________________________________


9

9


The Franz Lisp Manual                               PS2:9-45


(sublis 'l_alst 'l_exp)

     WHERE:   l_alst is an _a-_l_i_s_t.

     RETURNS: the list l_exp with every occurrence  of  key_i
              replaced by val_i.

     NOTE: new list structure is returned to prevent modifi-
           cation  of l_exp.  When a substitution is made, a
           copy of the value to substitute in is not made.


      _2._8._2.  _p_r_o_p_e_r_t_y _l_i_s_t

              A property list  consists  of  an  alternating
         sequence  of  keys and values.  Normally a property
         list is stored on a symbol. A list is  a  'disembo-
         died' property list if it contains an odd number of
         elements, the first of which is ignored.

(plist 's_name)

     RETURNS: the property list of s_name.

(setplist 's_atm 'l_plist)

     RETURNS: l_plist.

     SIDE EFFECT: the property  list  of  s_atm  is  set  to
                  l_plist.


(get 'ls_name 'g_ind)

     RETURNS: the value under indicator g_ind  in  ls_name's
              property list if ls_name is a symbol.

     NOTE: If there is no indicator g_ind in ls_name's  pro-
           perty list nil is returned.  If ls_name is a list
           of an odd number of elements then it is a  disem-
           bodied  property list. _g_e_t searches a disembodied
           property list by starting at its _c_d_r, and compar-
           ing every other element with g_ind, using _e_q.


9

9


PS2:9-46                               The Franz Lisp Manual


(getl 'ls_name 'l_indicators)

     RETURNS: the property list  ls_name  beginning  at  the
              first  indicator which is a member of the list
              l_indicators, or nil if none of the indicators
              in  l_indicators  are  on  ls_name's  property
              list.

     NOTE: If ls_name is a list, then it is assumed to be  a
           disembodied property list.


(putprop 'ls_name 'g_val 'g_ind)
(defprop ls_name g_val g_ind)

     RETURNS: g_val.

     SIDE EFFECT: Adds to the property list of  ls_name  the
                  value g_val under the indicator g_ind.

     NOTE: _p_u_t_p_r_o_p evaluates it arguments, _d_e_f_p_r_o_p does not.
           ls_name  may  be a disembodied property list, see
           _g_e_t.

(remprop 'ls_name 'g_ind)

     RETURNS: the portion of  ls_name's property list begin-
              ning  with  the  property  under the indicator
              g_ind.  If there  is  no  g_ind  indicator  in
              ls_name's plist, nil is returned.

     SIDE EFFECT: the value under indicator g_ind and  g_ind
                  itself  is  removed from the property list
                  of ls_name.

     NOTE: ls_name may be a disembodied property  list,  see
           _g_e_t.


9

9


The Franz Lisp Manual                               PS2:9-47


    ____________________________________________________

    -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_a '_a_l_p_h_a)
    a
    -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_b '_b_e_t_a)
    b
    -> (_p_l_i_s_t '_x_l_a_t_e)
    (alpha a beta b)
    -> (_g_e_t '_x_l_a_t_e '_a_l_p_h_a)
    a
    ; use of a disembodied property list:
    -> (_g_e_t '(_n_i_l _f_a_t_e_m_a_n _r_j_f _s_k_l_o_w_e_r _k_l_s _f_o_d_e_r_a_r_o _j_k_f) '_s_k_l_o_w_e_r)
    kls
    ____________________________________________________


      _2._8._3.  _t_c_o_n_c _s_t_r_u_c_t_u_r_e

              A tconc structure is a special  type  of  list
         designed to make it easy to add objects to the end.
         It consists of a list cell whose _c_a_r  points  to  a
         list  of the elements added with _t_c_o_n_c or _l_c_o_n_c and
         whose _c_d_r points to the last list cell of the  list
         pointed to by the _c_a_r.

(tconc 'l_ptr 'g_x)

     WHERE:   l_ptr is a tconc structure.

     RETURNS: l_ptr with g_x added to the end.

(lconc 'l_ptr 'l_x)

     WHERE:   l_ptr is a tconc structure.

     RETURNS: l_ptr with the list l_x spliced in at the end.


9

9


PS2:9-48                               The Franz Lisp Manual


    ____________________________________________________

    ; A _t_c_o_n_c structure can be initialized in two  ways.
    ; nil can be given to _t_c_o_n_c in which case _t_c_o_n_c will generate
    ; a _t_c_o_n_c structure.

    ->(_s_e_t_q _f_o_o (_t_c_o_n_c _n_i_l _1))
    ((1) 1)

    ; Since _t_c_o_n_c destructively adds to
    ; the list, you can now add to foo without using _s_e_t_q again.

    ->(_t_c_o_n_c _f_o_o _2)
    ((1 2) 2)
    ->_f_o_o
    ((1 2) 2)

    ; Another way to create a null  _t_c_o_n_c structure
    ; is to use (_n_c_o_n_s _n_i_l).

    ->(_s_e_t_q _f_o_o (_n_c_o_n_s _n_i_l))
    (nil)
    ->(_t_c_o_n_c _f_o_o _1)
    ((1) 1)

    ; now see what _l_c_o_n_c can do
    -> (_l_c_o_n_c _f_o_o _n_i_l)
    ((1) 1)                 ; no change
    -> (_l_c_o_n_c _f_o_o '(_2 _3 _4))
    ((1 2 3 4) 4)
    ____________________________________________________


      _2._8._4.  _f_c_l_o_s_u_r_e_s

              An  fclosure  is  a  functional  object  which
         admits some data manipulations.  They are discussed
         in 8.4.  Internally, they are constructed from vec-
         tors.


9

9


The Franz Lisp Manual                               PS2:9-49


(fclosure 'l_vars 'g_funobj)

     WHERE:   l_vars is a list of variables, g_funobj is any
              object that can be funcalled (including, fclo-
              sures).

     RETURNS: A vector which is the fclosure.

(fclosure-alist 'v_fclosure)

     RETURNS: An association list representing the variables
              in  the  fclosure.   This is a snapshot of the
              current state of the fclosure.  If  the  bind-
              ings  in  the fclosure are changed, any previ-
              ously  calculated  results  of  _f_c_l_o_s_u_r_e-_a_l_i_s_t
              will not change.

(fclosure-function 'v_fclosure)

     RETURNS: the functional object part of the fclosure.

(fclosurep 'v_fclosure)

     RETURNS: t iff the argument is an fclosure.

(symeval-in-fclosure 'v_fclosure 's_symbol)

     RETURNS: the current binding of a particular symbol  in
              an fclosure.

(set-in-fclosure 'v_fclosure 's_symbol 'g_newvalue)

     RETURNS: g_newvalue.

     SIDE EFFECT: The variable  s_symbol  is  bound  in  the
                  fclosure to g_newvalue.


   _2._9.  _R_a_n_d_o_m _f_u_n_c_t_i_o_n_s

           The following functions don't fall  into  any  of
      the classifications above.


9

9


PS2:9-50                               The Franz Lisp Manual


(bcdad 's_funcname)

     RETURNS: a fixnum which is the address in memory  where
              the function s_funcname begins.  If s_funcname
              is not a machine coded function (binary)  then
              _b_c_d_a_d returns nil.

(copy 'g_arg)

     RETURNS: A structure _e_q_u_a_l to g_arg but with  new  list
              cells.

(copyint* 'x_arg)

     RETURNS: a fixnum with the same value as x_arg but in a
              freshly allocated cell.

(cpy1 'xvt_arg)

     RETURNS: a new cell of the same type  as  xvt_arg  with
              the same value as xvt_arg.

(getaddress 's_entry1 's_binder1  'st_discipline1  [...  ...
...])

     RETURNS: the binary object which s_binder1's   function
              field is set to.

     NOTE: This looks in the running lisp's symbol table for
           a symbol with the same name as s_entry_i.  It then
           creates a binary object whose entry field  points
           to    s_entry_i    and    whose    discipline   is
           st_discipline_i.  This binary object is stored  in
           the    function    field    of   s_binder_i.    If
           st_discipline_i is nil, then "subroutine" is  used
           by  default.  This is especially useful for _c_f_a_s_l
           users.

(macroexpand 'g_form)

     RETURNS: g_form after all macros in it are expanded.

     NOTE: This function will only  macroexpand  expressions
           which  could  be  evaluated  and it does not know
           about the special nlambdas such as _c_o_n_d  and  _d_o,
           thus it misses many macro expansions.


9

9


The Franz Lisp Manual                               PS2:9-51


(ptr 'g_arg)

     RETURNS: a value cell initialized to point to g_arg.

(quote g_arg)

     RETURNS: g_arg.

     NOTE: the reader allows you to abbreviate  (quote  foo)
           as 'foo.

(kwote 'g_arg)

     RETURNS:  (_l_i_s_t (_q_u_o_t_e _q_u_o_t_e) _g__a_r_g).

(replace 'g_arg1 'g_arg2)

     WHERE:   g_arg1 and g_arg2 must be  the  same  type  of
              lispval and not symbols or hunks.

     RETURNS: g_arg2.

     SIDE EFFECT: The effect of _r_e_p_l_a_c_e is dependent on  the
                  type  of  the  g_arg_i  although  one  will
                  notice a similarity in  the  effects.   To
                  understand what _r_e_p_l_a_c_e does to fixnum and
                  flonum arguments, you  must  first  under-
                  stand  that  such  numbers  are `boxed' in
                  FRANZ LISP.  What this means  is  that  if
                  the  symbol  x  has a value 32412, then in
                  memory the value  element  of  x's  symbol
                  structure  contains the address of another
                  word of memory (called a box)  with  32412
                  in it.

                  Thus, there are two ways of  changing  the
                  value  of  x:  the  first is to change the
                  value element of x's symbol  structure  to
                  point to a word of memory with a different
                  value.  The second way is  to  change  the
                  value  in  the box which x points to.  The
                  former method is used almost  all  of  the
                  time,  the  latter is used very rarely and
                  has the potential to  cause  great  confu-
                  sion.   The function _r_e_p_l_a_c_e allows you to
                  do the latter, i.e.,  to  actually  change
                  the value in the box.

                  You should watch out for these situations.
                  If  you  do  (_s_e_t_q _y _x), then both x and y
                  will point to the same box.   If  you  now
                  (_r_e_p_l_a_c_e _x _1_2_3_4_5),  then  y will also have
                  the value 12345.  And, in fact, there  may


PS2:9-52                               The Franz Lisp Manual


                  be many other pointers to that box.

                  Another problem with replacing fixnums  is
                  that  some  boxes are read-only.  The fix-
                  nums between -1024 and 1023 are stored  in
                  a  read-only  area and attempts to replace
                  them will result  in  an  "Illegal  memory
                  reference"  error  (see the description of
                  _c_o_p_y_i_n_t* for a way around this problem).

                  For the other valid types, the  effect  of
                  _r_e_p_l_a_c_e is easy to understand.  The fields
                  of g_val1's structure are made eq  to  the
                  corresponding  fields  of  g_val2's struc-
                  ture.  For example,  if  x   and   y  have
                  lists   as   values  then  the  effect  of
                  (_r_e_p_l_a_c_e _x _y)    is    the     same     as
                  (_r_p_l_a_c_a _x (_c_a_r _y)) and (_r_p_l_a_c_d _x (_c_d_r _y)).

(scons 'x_arg 'bs_rest)

     WHERE:   bs_rest is a bignum or nil.

     RETURNS: a bignum whose first bigit is x_arg and  whose
              higher order bigits are bs_rest.

(setf g_refexpr 'g_value)

     NOTE: _s_e_t_f is a generalization  of  setq.   Information
           may  be  stored  by  binding variables, replacing
           entries of arrays, and vectors, or being  put  on
           property  lists,  among  others.  Setf will allow
           the user to store data  into  some  location,  by
           mentioning  the  operation  used  to refer to the
           location.  Thus, the first argument may  be  par-
           tially  evaluated,  but only to the extent needed
           to calculate a reference.  _s_e_t_f returns  g_value.
           (Compare to _d_e_s_e_t_q )


    ____________________________________________________

      (setf x 3)        =  (setq x 3)
      (setf (car x) 3)  = (rplaca x 3)
      (setf (get foo 'bar) 3) = (putprop foo 3 'bar)
      (setf (vref vector index) value) = (vset vector index value)
    ____________________________________________________


9

9


The Franz Lisp Manual                               PS2:9-53


(sort 'l_data 'u_comparefn)

     RETURNS: a list of the elements of  l_data  ordered  by
              the comparison function u_comparefn.

     SIDE EFFECT: the list l_data is  modified  rather  than
                  allocated in new storage.

     NOTE: (_c_o_m_p_a_r_e_f_n '_g__x  '_g__y)  should  return  something
           non-nil  if  g_x can precede g_y in sorted order;
           nil if g_y must precede g_x.  If  u_comparefn  is
           nil, alphabetical order will be used.

(sortcar 'l_list 'u_comparefn)

     RETURNS: a list of the  elements  of  l_list  with  the
              _c_a_r's    ordered    by   the   sort   function
              u_comparefn.

     SIDE EFFECT: the list l_list is  modified  rather  than
                  copied.

     NOTE: Like _s_o_r_t, if u_comparefn  is  nil,  alphabetical
           order will be used.


9

9


                           CHAPTER  3


                      Arithmetic Functions


          This chapter describes FRANZ LISP's functions  for
     doing  arithmetic.  Often the same function is known by
     many names.  For example, _a_d_d is also  _p_l_u_s,  and  _s_u_m.
     This  is  caused  by  our  desire to be compatible with
     other Lisps.  The FRANZ LISP user  should  avoid  using
     functions with names such as + and * unless their argu-
     ments are fixnums.  The Lisp compiler  takes  advantage
     of these implicit declarations.

          An attempt to divide or  to  generate  a  floating
     point  result  outside  of  the range of floating point
     numbers will cause a floating exception signal from the
     UNIX  operating system.  The user can catch and process
     this interrupt if desired (see the description  of  the
     _s_i_g_n_a_l function).


   _3._1.  _S_i_m_p_l_e _A_r_i_t_h_m_e_t_i_c _F_u_n_c_t_i_o_n_s

(add ['n_arg1 ...])
(plus ['n_arg1 ...])
(sum ['n_arg1 ...])
(+ ['x_arg1 ...])

     RETURNS: the sum of the arguments. If no arguments  are
              given, 0 is returned.

     NOTE: if the size of the partial sum exceeds the  limit
           of a fixnum, the partial sum will be converted to
           a bignum.  If any of the arguments  are  flonums,
           the  partial  sum  will  be converted to a flonum
           when that argument is processed  and  the  result
           will thus be a flonum.  Currently, if in the pro-
           cess of doing the addition a bignum must be  con-
           verted  into  a  flonum  an  error  message  will
           result.


9

9PS2:9-54                               The Franz Lisp Manual


The Franz Lisp Manual                               PS2:9-55


(add1 'n_arg)
(1+ 'x_arg)

     RETURNS: its argument plus 1.

(diff ['n_arg1 ... ])
(difference ['n_arg1 ... ])
(- ['x_arg1 ... ])

     RETURNS: the result of subtracting from n_arg1 all sub-
              sequent  arguments. If no arguments are given,
              0 is returned.

     NOTE: See the description of add for  details  on  data
           type conversions and restrictions.

(sub1 'n_arg)
(1- 'x_arg)

     RETURNS: its argument minus 1.

(minus 'n_arg)

     RETURNS: zero minus n_arg.

(product ['n_arg1 ... ])
(times ['n_arg1 ... ])
(* ['x_arg1 ... ])

     RETURNS: the product  of  all  of  its  arguments.   It
              returns 1 if there are no arguments.

     NOTE: See the  description  of  the  function  _a_d_d  for
           details  and  restrictions  to the automatic data
           type coercion.

(quotient ['n_arg1 ...])
(/ ['x_arg1 ...])

     RETURNS: the result of dividing the first  argument  by
              succeeding ones.

     NOTE: If there are no arguments, 1  is  returned.   See
           the  description  of the function _a_d_d for details
           and restrictions of data type coercion.  A divide
           by zero will cause a floating exception interrupt
           -- see the description of the _s_i_g_n_a_l function.


9

9


PS2:9-56                               The Franz Lisp Manual


(*quo 'i_x 'i_y)

     RETURNS: the integer part of i_x / i_y.

(Divide 'i_dividend 'i_divisor)

     RETURNS: a list whose car is  the  quotient  and  whose
              cadr  is  the  remainder  of  the  division of
              i_dividend by i_divisor.

     NOTE: this is restricted to integer division.

(Emuldiv 'x_fact1 'x_fact2 'x_addn 'x_divisor)

     RETURNS: a list of the quotient and remainder  of  this
              operation:
              ((x_fact1 * x_fact2) + (sign extended) x_addn) / x_divisor.

     NOTE: this  is  useful for creating a bignum arithmetic
           package in Lisp.


   _3._2.  _p_r_e_d_i_c_a_t_e_s

(numberp 'g_arg)

(numbp 'g_arg)

     RETURNS: t iff g_arg is a  number  (fixnum,  flonum  or
              bignum).

(fixp 'g_arg)

     RETURNS: t iff g_arg is a fixnum or bignum.

(floatp 'g_arg)

     RETURNS: t iff g_arg is a flonum.

(evenp 'x_arg)

     RETURNS: t iff x_arg is even.


9

9


The Franz Lisp Manual                               PS2:9-57


(oddp 'x_arg)

     RETURNS: t iff x_arg is odd.

(zerop 'g_arg)

     RETURNS: t iff g_arg is a number equal to 0.

(onep 'g_arg)

     RETURNS: t iff g_arg is a number equal to 1.

(plusp 'n_arg)

     RETURNS: t iff n_arg is greater than zero.

(minusp 'g_arg)

     RETURNS: t iff g_arg is a negative number.

(greaterp ['n_arg1 ...])
(> 'fx_arg1 'fx_arg2)
(>& 'x_arg1 'x_arg2)

     RETURNS: t iff the arguments are in a strictly decreas-
              ing order.

     NOTE: In functions _g_r_e_a_t_e_r_p and > the function  _d_i_f_f_e_r_-
           _e_n_c_e  is  used to compare adjacent values. If any
           of the arguments are non-numbers, the error  mes-
           sage will come from the _d_i_f_f_e_r_e_n_c_e function.  The
           arguments to > must  be fixnums or both  flonums.
           The arguments to >& must both be fixnums.

(lessp ['n_arg1 ...])
(< 'fx_arg1 'fx_arg2)
(<& 'x_arg1 'x_arg2)

     RETURNS: t iff the arguments are in a strictly increas-
              ing order.

     NOTE: In functions _l_e_s_s_p and < the function  _d_i_f_f_e_r_e_n_c_e
           is used to compare adjacent values. If any of the
           arguments are non numbers, the error message will
           come from the _d_i_f_f_e_r_e_n_c_e function.  The arguments
           to < may be either fixnums or flonums but must be
           the  same type.  The arguments to <& must be fix-
           nums.


9

9


PS2:9-58                               The Franz Lisp Manual


(= 'fx_arg1 'fx_arg2)

(=& 'x_arg1 'x_arg2)

     RETURNS: t iff the arguments have the same value.   The
              arguments to = must be the either both fixnums
              or both flonums.  The arguments to =& must  be
              fixnums.


   _3._3.  _T_r_i_g_n_o_m_e_t_r_i_c _F_u_n_c_t_i_o_n_s

           Some of these funtcions are taken from  the  host
      math  library,  and  we take no further responsibility
      for their accuracy.

(cos 'fx_angle)

     RETURNS: the (flonum)  cosine  of  fx_angle  (which  is
              assumed to be in radians).

(sin 'fx_angle)

     RETURNS: the sine of fx_angle (which is assumed  to  be
              in radians).

(acos 'fx_arg)

     RETURNS: the (flonum) arc cosine of fx_arg in the range
              0 to J.

(asin 'fx_arg)

     RETURNS: the (flonum) arc sine of fx_arg in  the  range
              -J/2 to J/2.

(atan 'fx_arg1 'fx_arg2)

     RETURNS: the (flonum) arc tangent of fx_arg1/fx_arg2 in
              the range -J to J.


   _3._4.  _B_i_g_n_u_m/_F_i_x_n_u_m _M_a_n_i_p_u_l_a_t_i_o_n


9

9


The Franz Lisp Manual                               PS2:9-59


(haipart bx_number x_bits)

     RETURNS: a fixnum (or bignum) which contains the x_bits
              high  bits  of  (_a_b_s _b_x__n_u_m_b_e_r)  if  x_bits is
              positive,    otherwise    it    returns    the
              (_a_b_s _x__b_i_t_s) low bits of (_a_b_s _b_x__n_u_m_b_e_r).

(haulong bx_number)

     RETURNS: the number of significant bits in bx_number.

     NOTE: the result is equal to the least integer  greater
           to or equal to the base two logarithm of one plus
           the absolute value of bx_number.

(bignum-leftshift bx_arg x_amount)

     RETURNS: bx_arg shifted left by x_amount.  If  x_amount
              is  negative,  bx_arg will be shifted right by
              the magnitude of x_amount.

     NOTE: If bx_arg is shifted right, it will be rounded to
           the nearest even number.

(sticky-bignum-leftshift 'bx_arg 'x_amount)

     RETURNS: bx_arg shifted left by x_amount.  If  x_amount
              is  negative,  bx_arg will be shifted right by
              the magnitude of x_amount and rounded.

     NOTE: sticky rounding is done this way: after shifting,
           the low order bit is changed to 1 if any 1's were
           shifted off to the right.


   _3._5.  _B_i_t _M_a_n_i_p_u_l_a_t_i_o_n

(boole 'x_key 'x_v1 'x_v2 ...)

     RETURNS: the result of the bitwise boolean operation as
              described in the following table.

     NOTE: If there are more than 3 arguments, then  evalua-
           tion  proceeds  left  to  right with each partial
           result becoming the new value of x_v1.  That is,
                (_b_o_o_l_e '_k_e_y '_v_1 '_v_2 '_v_3) =_ (_b_o_o_l_e '_k_e_y (_b_o_o_l_e '_k_e_y '_v_1 '_v_2) '_v_3).
           In the following table, * represents bitwise and,
           + represents bitwise or, O+ represents bitwise xor
           and  _  represents  bitwise  negation  and is the
           highest precedence operator.


PS2:9-60                               The Franz Lisp Manual


8____________________________________________________________________________________________
                                     (boole 'key 'x 'y)

8________________________________________________________________________________________________________________________________________________________________________________________
  key         0          1          2         3         4          5          6         7
 result       0        x * y     _ x * y      y      x * _ y       x        x O+ y     x + y

 common
 names                  and                          bitclear                xor       or

8____________________________________________________________________________________________

  key         8          9         10        11         12        13         14        15
 result   _ (x + y)   _(x O+ y)     _ x     _ x + y     _ y      x + _ y   _ x + _ y    -1
 common
 names       nor       equiv               implies                          nand
8____________________________________________________________________________________________
7|8|7|7|7|7|7|7|7|7|7|7|7|7|7|


9                                                                                            |8|7|7|7|7|7|7|7|7|7|7|7|7|7|


9

(lsh 'x_val 'x_amt)

     RETURNS: x_val shifted left by x_amt if x_amt is  posi-
              tive.   If x_amt is negative, then _l_s_h returns
              x_val shifted right by the magnitude if x_amt.

     NOTE: This always  returns  a  fixnum  even  for  those
           numbers  whose  magnitude  is  so large that they
           would normally be represented as a  bignum,  i.e.
           shifter  bits  are  lost.   For  more general bit
           shifters,  see   _b_i_g_n_u_m-_l_e_f_t_s_h_i_f_t   and   _s_t_i_c_k_y-
           _b_i_g_n_u_m-_l_e_f_t_s_h_i_f_t.

(rot 'x_val 'x_amt)

     RETURNS: x_val rotated left by x_amt if x_amt is  posi-
              tive.  If  x_amt  is  negative,  then x_val is
              rotated right by the magnitude of x_amt.


   _3._6.  _O_t_h_e_r _F_u_n_c_t_i_o_n_s

           As noted above, some of the  following  functions
      are  inherited  from  the  host math library, with all
      their virtues and vices.


9

9


The Franz Lisp Manual                               PS2:9-61


(abs 'n_arg)
(absval 'n_arg)

     RETURNS: the absolute value of n_arg.

(exp 'fx_arg)

     RETURNS: _e raised to the fx_arg power (flonum) .

(expt 'n_base 'n_power)

     RETURNS: n_base raised to the n_power power.

     NOTE: if either of the arguments are flonums, the  cal-
           culation will be done using _l_o_g and _e_x_p.

(fact 'x_arg)

     RETURNS: x_arg factorial. (fixnum or bignum)

(fix 'n_arg)

     RETURNS: a fixnum as close as we can get to n_arg.

     NOTE: _f_i_x will round down.  Currently, if  n_arg  is  a
           flonum  larger  than  the  size of a fixnum, this
           will fail.

(float 'n_arg)

     RETURNS: a flonum as close as we can get to n_arg.

     NOTE: if n_arg is a bignum larger than the maximum size
           of  a  flonum,  then  a  floating  exception will
           occur.

(log 'fx_arg)

     RETURNS: the natural logarithm of fx_arg.

(max 'n_arg1 ... )

     RETURNS: the maximum value in the list of arguments.


9

9


PS2:9-62                               The Franz Lisp Manual


(min 'n_arg1 ... )

     RETURNS: the minimum value in the list of arguments.

(mod 'i_dividend 'i_divisor)
(remainder 'i_dividend 'i_divisor)

     RETURNS: the remainder when i_dividend  is  divided  by
              i_divisor.

     NOTE: The sign of the result will have the same sign as
           i_dividend.

(*mod 'x_dividend 'x_divisor)

     RETURNS: the  balanced  representation  of   x_dividend
              modulo x_divisor.

     NOTE: the  range  of  the  balanced  representation  is
           abs(x_divisor)/2    to    (abs(x_divisor)/2)    -
           x_divisor + 1.

(random ['x_limit])

     RETURNS: a fixnum between 0 and x_limit - 1 if  x_limit
              is  given.   If x_limit is not given, any fix-
              num, positive or negative, might be returned.

(sqrt 'fx_arg)

     RETURNS: the square root of fx_arg.


9

9


                           CHAPTER  4


                        Special Functions


(and [g_arg1 ...])

     RETURNS: the value of the last argument  if  all  argu-
              ments  evaluate  to a non-nil value, otherwise
              _a_n_d returns nil.  It returns t if there are no
              arguments.

     NOTE: the arguments are evaluated  left  to  right  and
           evaluation  will cease with the first nil encoun-
           tered.

(apply 'u_func 'l_args)

     RETURNS: the result of applying function u_func to  the
              arguments in the list l_args.

     NOTE: If u_func is a lambda, then  the  (_l_e_n_g_t_h _l__a_r_g_s)
           should  equal the number of formal parameters for
           the u_func.  If u_func is  a  nlambda  or  macro,
           then l_args is bound to the single formal parame-
           ter.


9

9The Franz Lisp Manual                               PS2:9-63


PS2:9-64                               The Franz Lisp Manual


    ____________________________________________________

    ; _a_d_d_1 is a lambda of 1 argument
    -> (_a_p_p_l_y '_a_d_d_1 '(_3))
    4

    ; we will define _p_l_u_s_1 as a macro which will be equivalent to _a_d_d_1
    -> (_d_e_f _p_l_u_s_1 (_m_a_c_r_o (_a_r_g) (_l_i_s_t '_a_d_d_1 (_c_a_d_r _a_r_g))))
    plus1
    -> (_p_l_u_s_1 _3)
    4

    ; now if we _a_p_p_l_y a macro we obtain the form it changes to.
    -> (_a_p_p_l_y '_p_l_u_s_1 '(_p_l_u_s_1 _3))
    (add1 3)

    ; if we _f_u_n_c_a_l_l a macro however, the result of the macro is _e_v_a_led
    ; before it is returned.
    -> (_f_u_n_c_a_l_l '_p_l_u_s_1 '(_p_l_u_s_1 _3))
    4

    ; for this particular macro, the _c_a_r of the _a_r_g is not checked
    ; so that this too will work
    -> (_a_p_p_l_y '_p_l_u_s_1 '(_f_o_o _3))
    (add1 3)

    ____________________________________________________


(arg ['x_numb])

     RETURNS: if x_numb  is  specified  then  the  x_numb'_t_h
              argument  to  the enclosing lexpr If x_numb is
              not specified then this returns the number  of
              arguments to the enclosing lexpr.

     NOTE: it is an error to the interpreter  if  x_numb  is
           given and out of range.


9

9


The Franz Lisp Manual                               PS2:9-65


(break [g_message ['g_pred]])

     WHERE:   if g_message is not given it is assumed to  be
              the null string, and if g_pred is not given it
              is assumed to be t.

     RETURNS: the value of (*_b_r_e_a_k '_g__p_r_e_d '_g__m_e_s_s_a_g_e)

(*break 'g_pred 'g_message)

     RETURNS: nil immediately if g_pred  is  nil,  else  the
              value  of  the next (return 'value) expression
              typed in at top level.

     SIDE EFFECT: If the  predicate,  g_pred,  evaluates  to
                  non-null, the lisp system stops and prints
                  out `Break '  followed  by  g_message.  It
                  then  enters a break loop which allows one
                  to interactively debug a program.  To con-
                  tinue  execution  from a break you can use
                  the _r_e_t_u_r_n  function.  to  return  to  top
                  level  or another break level, you can use
                  _r_e_t_b_r_k or _r_e_s_e_t.

(caseq 'g_key-form l_clause1 ...)

     WHERE:   l_clause_i is a list of the form  (g_comparator
              ['g_form_i  ...]).  The comparators may be sym-
              bols, small fixnums, a list of  small  fixnums
              or symbols.

     NOTE: The way caseq works is that it  evaluates  g_key-
           form, yielding a value we will call the selector.
           Each clause is examined  until  the  selector  is
           found consistent with the comparator.  For a sym-
           bol, or a fixnum, this means the two must be  _e_q.
           For  a list, this means that the selector must be
           _e_q to some element of the list.

           The comparator consisting of  the  symbol  t  has
           special  semantics: it matches anything, and con-
           sequently, should be the last comparator.

           In any case, having chosen a clause, _c_a_s_e_q evalu-
           ates each form within that clause and

     RETURNS: the value of the last form.  If no comparators
              are matched, _c_a_s_e_q returns nil.


9

9


PS2:9-66                               The Franz Lisp Manual


    ____________________________________________________

    Here are two ways of defining the same function:
    ->(_d_e_f_u_n _f_a_t_e (_p_e_r_s_o_n_n_a)
            (_c_a_s_e_q _p_e_r_s_o_n_n_a
              (_c_o_w '(_j_u_m_p_e_d _o_v_e_r _t_h_e _m_o_o_n))
              (_c_a_t '(_p_l_a_y_e_d _n_e_r_o))
              ((_d_i_s_h _s_p_o_o_n) '(_r_a_n _a_w_a_y _w_i_t_h _e_a_c_h _o_t_h_e_r))
              (_t '(_l_i_v_e_d _h_a_p_p_i_l_y _e_v_e_r _a_f_t_e_r))))
    fate
    ->(_d_e_f_u_n _f_a_t_e (_p_e_r_s_o_n_n_a)
            (_c_o_n_d
                    ((_e_q _p_e_r_s_o_n_n_a '_c_o_w) '(_j_u_m_p_e_d _o_v_e_r _t_h_e _m_o_o_n))
                    ((_e_q _p_e_r_s_o_n_n_a '_c_a_t) '(_p_l_a_y_e_d _n_e_r_o))
                    ((_m_e_m_q _p_e_r_s_o_n_n_a '(_d_i_s_h _s_p_o_o_n)) '(_r_a_n _a_w_a_y _w_i_t_h _e_a_c_h _o_t_h_e_r))
                    (_t '(_l_i_v_e_d _h_a_p_p_i_l_y _e_v_e_r _a_f_t_e_r))))
    fate
    ____________________________________________________


(catch g_exp [ls_tag])

     WHERE:   if ls_tag is not given, it is  assumed  to  be
              nil.

     RETURNS: the result of (*_c_a_t_c_h '_l_s__t_a_g _g__e_x_p)

     NOTE: catch is defined as a macro.

(*catch 'ls_tag g_exp)

     WHERE:   ls_tag is either a symbol or a  list  of  sym-
              bols.

     RETURNS: the result of evaluating g_exp  or  the  value
              thrown during the evaluation of g_exp.

     SIDE EFFECT: this first sets up a `catch frame' on  the
                  lisp  runtime  stack.   Then  it begins to
                  evaluate g_exp.  If g_exp  evaluates  nor-
                  mally,  its  value  is returned.  If, how-
                  ever, a value is thrown during the evalua-
                  tion of g_exp then this *catch will return
                  with that value if one of these  cases  is
                  true:

      (1)   the tag thrown to is ls_tag

      (2)   ls_tag is a list and the  tag  thrown  to  is  a
            member of this list


The Franz Lisp Manual                               PS2:9-67


      (3)   ls_tag is nil.

     NOTE: Errors are  implemented  as  a  special  kind  of
           throw.   A  catch  with  no tag will not catch an
           error but a catch whose tag  is  the  error  type
           will  catch  that  type of error.  See Chapter 10
           for more information.

(comment [g_arg ...])

     RETURNS: the symbol comment.

     NOTE: This does absolutely nothing.

(cond [l_clause1 ...])

     RETURNS: the last value evaluated in the  first  clause
              satisfied.   If  no clauses are satisfied then
              nil is returned.

     NOTE: This is  the  basic  conditional  `statement'  in
           lisp.   The  clauses  are  processed from left to
           right.   The  first  element  of  a   clause   is
           evaluated.   If  it evaluated to a non-null value
           then that clause is satisfied and  all  following
           elements  of that clause are evaluated.  The last
           value computed is returned as the  value  of  the
           cond.  If there is just one element in the clause
           then its value is returned.  If the first element
           of a clause evaluates to nil, then the other ele-
           ments of that clause are not  evaluated  and  the
           system moves to the next clause.

(cvttointlisp)

     SIDE EFFECT: The reader is modified to conform with the
                  Interlisp syntax.  The character % is made
                  the escape character and special  meanings
                  for  comma,  backquote  and  backslash are
                  removed. Also the reader is told  to  con-
                  vert upper case to lower case.


9

9


PS2:9-68                               The Franz Lisp Manual


(cvttofranzlisp)

     SIDE EFFECT: FRANZ LISP's default syntax is reinstated.
                  One  would  run this function after having
                  run any of  the  other  _c_v_t_t_o-  functions.
                  Backslash  is  made  the escape character,
                  super-brackets work again, and the  reader
                  distinguishes   between  upper  and  lower
                  case.

(cvttomaclisp)

     SIDE EFFECT: The reader is  modified  to  conform  with
                  Maclisp  syntax.   The character / is made
                  the escape character and the special mean-
                  ings for backslash, left and right bracket
                  are removed.  The  reader  is  made  case-
                  insensitive.

(cvttoucilisp)

     SIDE EFFECT: The reader is modified to conform with UCI
                  Lisp  syntax.  The character / is made the
                  escape character, tilde is made  the  com-
                  ment character, exclamation point takes on
                  the  unquote  function  normally  held  by
                  comma,  and  backslash,  comma,  semicolon
                  become normal characters.  Here  too,  the
                  reader is made case-insensitive.

(debug s_msg)

     SIDE EFFECT: Enter  the  Fixit  package  described   in
                  Chapter  15.   This  package allows you to
                  examine the evaluation  stack  in  detail.
                  To  leave the Fixit package type 'ok'.

(debugging 'g_arg)

     SIDE EFFECT: If g_arg is non-null,  Franz  unlinks  the
                  transfer  tables, does a (*_r_s_e_t _t) to turn
                  on  evaluation  monitoring  and  sets  the
                  all-error  catcher  (ER%all)  to be _d_e_b_u_g-
                  _e_r_r-_h_a_n_d_l_e_r.  If g_arg is nil, all of  the
                  above changes are undone.


9

9


The Franz Lisp Manual                               PS2:9-69


(declare [g_arg ...])

     RETURNS: nil

     NOTE: this is a no-op to the evaluator.  It has special
           meaning to the compiler (see Chapter 12).

(def s_name (s_type l_argl g_exp1 ...))

     WHERE:   s_type is one of  lambda,  nlambda,  macro  or
              lexpr.

     RETURNS: s_name

     SIDE EFFECT: This defines the function  s_name  to  the
                  lisp  system.   If  s_type  is  nlambda or
                  macro then the argument list  l_argl  must
                  contain exactly one non-nil symbol.

(defmacro s_name l_arg g_exp1 ...)
(defcmacro s_name l_arg g_exp1 ...)

     RETURNS: s_name

     SIDE EFFECT: This defines the  macro  s_name.  _d_e_f_m_a_c_r_o
                  makes  it  easy  to  write macros since it
                  makes the syntax just like _d_e_f_u_n.  Further
                  information   on  _d_e_f_m_a_c_r_o  is  in  8.3.2.
                  _d_e_f_c_m_a_c_r_o defines compiler-only macros, or
                  cmacros.  A  cmacro  is stored on the pro-
                  perty list of a symbol under the indicator
                  cmacro.  Thus a function can have a normal
                  definition and a cmacro  definition.   For
                  an  example of the use of cmacros, see the
                  definitions   of   nthcdr   and   nth   in
                  /usr/lib/lisp/common2.l

(defun s_name [s_mtype] ls_argl g_exp1 ... )

     WHERE:   s_mtype is one of fexpr, expr, args or macro.

     RETURNS: s_name

     SIDE EFFECT: This defines the function s_name.

     NOTE: this exists for Maclisp compatibility, it is just
           a  macro  which changes the defun form to the def
           form.   An  s_mtype  of  fexpr  is  converted  to
           nlambda  and of expr to lambda. Macro remains the
           same.  If ls_arg1 is a non-nil symbol,  then  the
           type  is  assumed  to be lexpr and ls_arg1 is the
           symbol which is bound to the number of args  when
           the function is entered.


PS2:9-70                               The Franz Lisp Manual


           For compatibility with  the  Lisp  Machine  Lisp,
           there are three types of optional parameters that
           can occur in ls_argl:   &_o_p_t_i_o_n_a_l  declares  that
           the  following  symbols  are optional, and may or
           may not appear in the argument list to the  func-
           tion, &_r_e_s_t _s_y_m_b_o_l declares that all forms in the
           function call that are not accounted for by  pre-
           vious  lambda bindings are to be assigned to _s_y_m_-
           _b_o_l, and &_a_u_x _f_o_r_m_1 ... _f_o_r_m_n declares  that  the
           _f_o_r_m_i  are either symbols, in which case they are
           lambda bound to nil, or lists, in which case  the
           first  element of the list is lambda bound to the
           second, evaluated element.


    ____________________________________________________

    ; _d_e_f and _d_e_f_u_n here are used to define identical functions
    ; you can decide for yourself which is easier to use.
    -> (_d_e_f _a_p_p_e_n_d_1 (_l_a_m_b_d_a (_l_i_s _e_x_t_r_a) (_a_p_p_e_n_d _l_i_s (_l_i_s_t _e_x_t_r_a))))
    append1

    -> (_d_e_f_u_n _a_p_p_e_n_d_1 (_l_i_s _e_x_t_r_a) (_a_p_p_e_n_d _l_i_s (_l_i_s_t _e_x_t_r_a)))
    append1

    ; Using the & forms...
    -> (_d_e_f_u_n _t_e_s_t (_a _b &_o_p_t_i_o_n_a_l _c &_a_u_x (_r_e_t_v_a_l _0) &_r_e_s_t _z)
            (_i_f _c _t_h_e_m (_m_s_g "_O_p_t_i_o_n_a_l _a_r_g _p_r_e_s_e_n_t" _N
                            "_c _i_s " _c _N))
            (_m_s_g "_r_e_s_t _i_s " _z _N
                 "_r_e_t_v_a_l _i_s " _r_e_t_v_a_l _N))
    test
    -> (_t_e_s_t _1 _2 _3 _4)
    Optional arg present
    c is 3
    rest is (4)
    retval is 0
    ____________________________________________________


9

9


The Franz Lisp Manual                               PS2:9-71


(defvar s_variable ['g_init])

     RETURNS: s_variable.

     NOTE: This form is put at the top level in files,  like
           _d_e_f_u_n.

     SIDE EFFECT: This declares s_variable to be special. If
                  g_init   is   present  and  s_variable  is
                  unbound  when  the  file   is   read   in,
                  s_variable  will  be  set  to the value of
                  g_init.  An advantage  of  `(defvar  foo)'
                  over  `(declare (special foo))' is that if
                  a file containing defvars  is  loaded  (or
                  fasl'ed)  in during compilation, the vari-
                  ables mentioned in the  defvar's  will  be
                  declared  special.   The  only way to have
                  that effect with `(declare (special foo))'
                  is to _i_n_c_l_u_d_e the file.

(do l_vrbs l_test g_exp1 ...)

     RETURNS: the last form in the cdr of l_test  evaluated,
              or  a  value  explicitly  given  by  a  return
              evaluated within the do body.

     NOTE: This is the basic iteration form for FRANZ  LISP.
           l_vrbs  is a list of zero or more var-init-repeat
           forms.  A var-init-repeat form looks like:
                (s_name [g_init [g_repeat]])
           There  are  three  cases  depending  on  what  is
           present  in the form.  If just s_name is present,
           this means that when the do is entered, s_name is
           lambda-bound  to nil and is never modified by the
           system (though the program is certainly  free  to
           modify    its    value).     If   the   form   is
           (s_name 'g_init) then the only difference is that
           s_name  is  lambda-bound  to  the value of g_init
           instead of nil.  If g_repeat is also present then
           s_name is lambda-bound to g_init when the loop is
           entered and after each pass through the  do  body
           s_name is  bound to the value of g_repeat.
           l_test is either nil or has the form  of  a  cond
           clause.   If  it  is nil then the do body will be
           evaluated only once and the do will  return  nil.
           Otherwise,  before  the  do body is evaluated the
           car of l_test is evaluated and if the  result  is
           non-null,  this  signals  an  end to the looping.
           Then  the  rest  of  the  forms  in  l_test   are
           evaluated  and  the  value  of  the  last  one is
           returned as the value of the do.  If the  cdr  of
           l_test  is nil, then nil is returned -- thus this
           is not exactly like a cond clause.


PS2:9-72                               The Franz Lisp Manual


           g_exp1 and those forms  which  follow  constitute
           the  do  body.  A do body is like a prog body and
           thus may have labels and one may  use  the  func-
           tions go and return.
           The sequence of evaluations is this:

      (1)   the init forms are evaluated left to  right  and
            stored in temporary locations.

      (2)   Simultaneously all do variables are lambda bound
            to the value of their init forms or nil.

      (3)   If l_test is non-null, then the car is evaluated
            and  if it is non-null, the rest of the forms in
            l_test are  evaluated  and  the  last  value  is
            returned as the value of the do.

      (4)   The forms in the do body are evaluated  left  to
            right.

      (5)   If l_test is nil the do  function  returns  with
            the value nil.

      (6)   The repeat forms are evaluated and saved in tem-
            porary locations.

      (7)   The variables with repeat forms  are  simultane-
            ously bound to the values of those forms.

      (8)   Go to step 3.

     NOTE: there is an alternate form of  do  which  can  be
           used  when  there is only one do variable.  It is
           described next.


9

9


The Franz Lisp Manual                               PS2:9-73


    ____________________________________________________

    ; this is  a simple function which numbers the elements of a list.
    ; It uses a _d_o function with two local variables.
    -> (_d_e_f_u_n _p_r_i_n_t_e_m (_l_i_s)
                 (_d_o ((_x_x _l_i_s (_c_d_r _x_x))
                      (_i _1 (_1+ _i)))
                     ((_n_u_l_l _x_x) (_p_a_t_o_m "_a_l_l _d_o_n_e") (_t_e_r_p_r))
                     (_p_r_i_n_t _i)
                     (_p_a_t_o_m ": ")
                     (_p_r_i_n_t (_c_a_r _x_x))
                     (_t_e_r_p_r)))
    printem
    -> (_p_r_i_n_t_e_m '(_a _b _c _d))
    1: a
    2: b
    3: c
    4: d
    all done
    nil
    ->
    ____________________________________________________


(do s_name g_init g_repeat g_test g_exp1 ...)

     NOTE: this is another, less general,  form of  do.   It
           is evaluated by:

      (1)   evaluating g_init

      (2)   lambda binding s_name to value of g_init

      (3)   g_test is evaluated and if it is not nil the  do
            function returns with nil.

      (4)   the do body is evaluated beginning at g_exp1.

      (5)   the repeat  form  is  evaluated  and  stored  in
            s_name.

      (6)   go to step 3.

     RETURNS: nil


9

9


PS2:9-74                               The Franz Lisp Manual


(environment [l_when1 l_what1 l_when2 l_what2 ...])
(environment-maclisp [l_when1 l_what1 l_when2 l_what2 ...])
(environment-lmlisp [l_when1 l_what1 l_when2 l_what2 ...])

     WHERE:   the when's  are  a  subset  of  (eval  compile
              load),  and  the symbols have the same meaning
              as they do in 'eval-when'.

              The what's may be
                      (files file1 file2 ... fileN),
              which insure that the named files are  loaded.
              To  see  if  file_i  is  loaded, it looks for a
              'version'  property  under  file_i's   property
              list.   Thus  to prevent multiple loading, you
              should put
                      (putprop 'myfile t 'version),
              at the end of myfile.l.

              Another acceptable form for a what is
              (syntax type)
              Where type is either maclisp,  intlisp,  ucil-
              isp, franzlisp.

     SIDE EFFECT: _e_n_v_i_r_o_n_m_e_n_t-_m_a_c_l_i_s_p sets  the  environment
                  to that which `liszt -m' would generate.

                  _e_n_v_i_r_o_n_m_e_n_t-_l_m_l_i_s_p   sets  up   the   lisp
                  machine  environment. This is like maclisp
                  but it has additional macros.

                  For these specialized  environments,  only
                  the     files    clauses    are    useful.
                          (environment-maclisp      (compile
                  eval) (files foo bar))

     RETURNS: the last list of files requested.

(err ['s_value [nil]])

     RETURNS: nothing (it never returns).

     SIDE EFFECT: This causes an error and if this error  is
                  caught  by an _e_r_r_s_e_t then that _e_r_r_s_e_t will
                  return s_value instead  of  nil.   If  the
                  second  arg  is given, then it must be nil
                  (MAClisp compatibility).


9

9


The Franz Lisp Manual                               PS2:9-75


(error ['s_message1 ['s_message2]])

     RETURNS: nothing (it never returns).

     SIDE EFFECT: s_message1 and s_message2 are  _p_a_t_o_med  if
                  they  are  given  and  then  _e_r_r is called
                  (with  no  arguments),  which  causes   an
                  error.

(errset g_expr [s_flag])

     RETURNS: a list of one  element,  which  is  the  value
              resulting from evaluating g_expr.  If an error
              occurs during the evaluation of  g_expr,  then
              the locus of control will return to the _e_r_r_s_e_t
              which will then return nil (unless  the  error
              was  caused  by a call to _e_r_r, with a non-null
              argument).

     SIDE EFFECT: S_flag  is  evaluated  before  g_expr   is
                  evaluated. If s_flag is not given, then it
                  is assumed to be t.  If  an  error  occurs
                  during   the  evaluation  of  g_expr,  and
                  s_flag evaluated to a non-null value, then
                  the  error  message  associated  with  the
                  error is printed before control returns to
                  the errset.

(eval 'g_val ['x_bind-pointer])

     RETURNS: the result of evaluating g_val.

     NOTE: The evaluator evaluates g_val in this way:
           If g_val is a symbol, then the evaluator  returns
           its  value.   If  g_val had never been assigned a
           value, then this  causes  an  `Unbound  Variable'
           error.   If  x_bind-pointer  is  given,  then the
           variable  is  evaluated  with  respect  to   that
           pointer  (see  _e_v_a_l_f_r_a_m_e  for  details  on  bind-
           pointers).

           If g_val is of type  value,  then  its  value  is
           returned.   If  g_val  is  of any other type than
           list, g_val is returned.

           If g_val is a list object then g_val is either  a
           function  call  or array reference.  Let g_car be
           the  first  element  of  g_val.   We  continually
           evaluate g_car until we end up with a symbol with
           a non-null  function  binding  or  a  non-symbol.
           Call what we end up with: g_func.

           G_func must be one of three types:  list,  binary


PS2:9-76                               The Franz Lisp Manual


           or array.  If it is a list then the first element
           of the list, which we shall call g_functype, must
           be  either  lambda,  nlambda, macro or lexpr.  If
           g_func is a binary, then its discipline, which we
           shall call g_functype, is either lambda, nlambda,
           macro or a string.  If g_func is  an  array  then
           this  form  is evaluated specially, see Chapter 9
           on arrays.  If g_func is a list or  binary,  then
           g_functype  will  determine  how the arguments to
           this function, the cdr of g_val,  are  processed.
           If g_functype is a string, then this is a foreign
           function call (see 8.5 for more details).

           If g_functype is lambda or lexpr,  the  arguments
           are  evaluated  (by calling _e_v_a_l recursively) and
           stacked.  If g_functype is nlambda then the argu-
           ment  list  is  stacked.   If g_functype is macro
           then the entire form, g_val is stacked.

           Next, the formal variables are lambda bound.  The
           formal  variables  are  the  cadr  of g_func.  If
           g_functype is  nlambda,  lexpr  or  macro,  there
           should  only  be one formal variable.  The values
           on the stack are lambda bound to the formal vari-
           ables  except  in  the case of a lexpr, where the
           number of actual arguments is bound to the formal
           variable.

           After  the  binding  is  done,  the  function  is
           invoked,  either by jumping to the entry point in
           the case of a binary or by evaluating the list of
           forms  beginning  at  cddr g_func.  The result of
           this function invocation is returned as the value
           of the call to eval.

(evalframe 'x_pdlpointer)

     RETURNS: an evalframe  descriptor  for  the  evaluation
              frame    just    before    x_pdlpointer.    If
              x_pdlpointer is nil, it returns the evaluation
              frame  of  the  frame  just before the current
              call to _e_v_a_l_f_r_a_m_e.

     NOTE: An evalframe descriptor describes a call to _e_v_a_l,
           _a_p_p_l_y or _f_u_n_c_a_l_l.  The form of the descriptor is
           (_t_y_p_e  _p_d_l-_p_o_i_n_t_e_r  _e_x_p_r_e_s_s_i_o_n  _b_i_n_d-_p_o_i_n_t_e_r  _n_p-
           _i_n_d_e_x _l_b_o_t-_i_n_d_e_x)
           where type is `eval' if this describes a call  to
           _e_v_a_l  or  `apply'  if  this is a call to _a_p_p_l_y or
           _f_u_n_c_a_l_l.    pdl-pointer   is   a   number   which
           describes this context. It can be passed to _e_v_a_l_-
           _f_r_a_m_e to obtain the next descriptor  and  can  be
           passed  to  _f_r_e_t_u_r_n  to  cause a return from this


The Franz Lisp Manual                               PS2:9-77


           context.  bind-pointer is the  size  of  variable
           binding  stack  when  this  evaluation began. The
           bind-pointer can be given as a second argument to
           _e_v_a_l  to  order to evaluate variables in the same
           context as this  evaluation. If  type  is  `eval'
           then  expression  will  have  the form (_f_u_n_c_t_i_o_n-
           _n_a_m_e _a_r_g_1 ...).  If type is `apply' then  expres-
           sion    will    have    the    form    (_f_u_n_c_t_i_o_n-
           _n_a_m_e (_a_r_g_1 ...)).  np-index  and  lbot-index  are
           pointers  into  the argument stack (also known as
           the _n_a_m_e_s_t_a_c_k array) at the time of call.   lbot-
           index  points  to  the  first  argument, np-index
           points one beyond the last argument.
           In order for there to be enough  information  for
           _e_v_a_l_f_r_a_m_e to return, you must call (*_r_s_e_t _t).

     EXAMPLE: (_p_r_o_g_n (_e_v_a_l_f_r_a_m_e _n_i_l))
              returns  (_e_v_a_l  _2_1_4_7_4_7_8_6_0_0  (_p_r_o_g_n  (_e_v_a_l_f_r_a_m_e
              _n_i_l)) _1 _8 _7)

(evalhook 'g_form 'su_evalfunc ['su_funcallfunc])

     RETURNS: the result of evaluating g_form  after  lambda
              binding  `evalhook'  to su_evalfunc and, if it
              is  given,  lambda  binding  `funcallhook'  to
              su_funcallhook.

     NOTE: As explained in 14.4, the function _e_v_a_l may  pass
           the  job  of  evaluating  a form to a user `hook'
           function when  various  switches  are  set.   The
           hook  function  normally  prints  the  form to be
           evaluated on the terminal and then  evaluates  it
           by  calling  _e_v_a_l_h_o_o_k.   _E_v_a_l_h_o_o_k does the lambda
           binding mentioned above and then  calls  _e_v_a_l  to
           evaluate  the  form  after  setting  an  internal
           switch to tell _e_v_a_l not to call the  user's  hook
           function  just  this  one  time.  This allows the
           evaluation process to advance one  step  and  yet
           insure  that  further  calls  to  _e_v_a_l will cause
           traps to the hook  function  (if  su_evalfunc  is
           non-null).
           In order for  _e_v_a_l_h_o_o_k  to  work,  (*_r_s_e_t _t)  and
           (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t)  must  have been done previ-
           ously.


9

9


PS2:9-78                               The Franz Lisp Manual


(exec s_arg1 ...)

     RETURNS: the result of forking and executing  the  com-
              mand   named   by   concatenating  the  s_arg_i
              together with spaces in between.

(exece 's_fname ['l_args ['l_envir]])

     RETURNS: the error code  from  the  system  if  it  was
              unable  to  execute  the  command s_fname with
              arguments l_args and with the environment  set
              up  as specified in l_envir.  If this function
              is successful, it will not return, instead the
              lisp  system  will be overlaid by the new com-
              mand.

(freturn 'x_pdl-pointer 'g_retval)

     RETURNS: g_retval from  the  context  given  by  x_pdl-
              pointer.

     NOTE: A  pdl-pointer  denotes  a   certain   expression
           currently  being evaluated. The pdl-pointer for a
           given expression can be obtained from _e_v_a_l_f_r_a_m_e.

(frexp 'f_arg)

     RETURNS: a  list  cell  (_e_x_p_o_n_e_n_t  .  _m_a_n_t_i_s_s_a)   which
              represents the given flonum

     NOTE: The exponent will be a fixnum, the mantissa a  56
           bit bignum.  If you think of the the binary point
           occurring right  after  the  high  order  bit  of
           mantissa, then f_arg = 2[exponent] * mantissa.

(funcall 'u_func ['g_arg1 ...])

     RETURNS: the value of applying function u_func  to  the
              arguments  g_arg_i  and  then  evaluating  that
              result if u_func is a macro.

     NOTE: If u_func is a macro or nlambda then there should
           be only one g_arg.  _f_u_n_c_a_l_l is the function which
           the evaluator uses to evaluate lists.  If _f_o_o  is
           a    lambda    or    lexpr    or    array,   then
           (_f_u_n_c_a_l_l '_f_o_o '_a '_b '_c)    is    equivalent    to
           (_f_o_o '_a '_b '_c).    If   _f_o_o  is  a  nlambda  then
           (_f_u_n_c_a_l_l '_f_o_o '(_a _b _c)) is equivalent to (_f_o_o _a _b
           _c).    Finally,   if   _f_o_o   is   a   macro  then
           (_f_u_n_c_a_l_l '_f_o_o '(_f_o_o _a _b _c))  is   equivalent   to
           (_f_o_o _a _b _c).

9

9


The Franz Lisp Manual                               PS2:9-79


(funcallhook 'l_form 'su_funcallfunc ['su_evalfunc])

     RETURNS: the result of _f_u_n_c_a_l_ling the  (_c_a_r _l__f_o_r_m)  on
              the   already   evaluated   arguments  in  the
              (_c_d_r _l__f_o_r_m)  after   lambda   binding   `fun-
              callhook'  to  su_funcallfunc  and,  if  it is
              given,   lambda    binding    `evalhook'    to
              su_evalhook.

     NOTE: This function is designed to continue the evalua-
           tion  process  with  as  little  work as possible
           after a funcallhook trap has occurred. It is  for
           this  reason  that the form of l_form is unortho-
           dox: its _c_a_r is the name of the function to  call
           and  its  _c_d_r  are  a  list of arguments to stack
           (without evaluating  again)  before  calling  the
           given function.  After stacking the arguments but
           before calling _f_u_n_c_a_l_l an internal switch is  set
           to  prevent  _f_u_n_c_a_l_l from passing the job of fun-
           calling to su_funcallfunc.  If _f_u_n_c_a_l_l is  called
           recursively   in   funcalling   l_form   and   if
           su_funcallfunc is non-null, then the arguments to
           _f_u_n_c_a_l_l  will actually be given to su_funcallfunc
           (a lexpr) to be funcalled.
           In order for  _e_v_a_l_h_o_o_k  to  work,  (*_r_s_e_t _t)  and
           (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t)  must  have been done previ-
           ously.  A more detailed description  of  _e_v_a_l_h_o_o_k
           and _f_u_n_c_a_l_l_h_o_o_k is given in Chapter 14.

(function u_func)

     RETURNS: the function binding of u_func  if  it  is  an
              symbol   with  a  function  binding  otherwise
              u_func is returned.

(getdisc 'y_func)

     RETURNS: the discipline of the machine  coded  function
              (either lambda, nlambda or macro).

(go g_labexp)

     WHERE:   g_labexp is either a symbol or an expression.

     SIDE EFFECT: If g_labexp is an expression, that expres-
                  sion  is  evaluated and should result in a
                  symbol.  The locus  of  control  moves  to
                  just  following the symbol g_labexp in the
                  current prog or do body.

     NOTE: this is only valid in the context of a prog or do
           body.   The  interpreter  and compiler will allow
           non-local _g_o's although the compiler won't  allow


PS2:9-80                               The Franz Lisp Manual


           a _g_o to leave a function body.  The compiler will
           not allow g_labexp to be an expression.

(if 'g_a 'g_b)
(if 'g_a 'g_b 'g_c ...)
(if 'g_a then  'g_b [...] [elseif 'g_c then 'g_d ...]  [else
'g_e [...])
(if 'g_a then  'g_b [...] [elseif 'g_c thenret]  [else  'g_d
[...])

     NOTE: The various forms of _i_f are intended to be a more
           readable  conditional  statement,  to  be used in
           place of _c_o_n_d.  There are two  varieties  of  _i_f,
           with  keywords,  and  without.   The keyword-less
           variety is inherited from common  Maclisp  usage.
           A  keyword-less, two argument _i_f is equivalent to
           a one-clause _c_o_n_d, i.e. (_c_o_n_d (a b)).   Any other
           keyword-less  _i_f  must  have at least three argu-
           ments.  The first two  arguments  are  the  first
           clause  of the equivalent _c_o_n_d, and all remaining
           arguments are shoved into a second clause  begin-
           ning  with  t.   Thus,  the  second form of _i_f is
           equivalent to
                   (_c_o_n_d (a b) (t c ...)).

           The keyword variety has the following grouping of
           arguments:   a   predicate,  a  then-clause,  and
           optional   else-clause.    The    predicate    is
           evaluated,  and  if  the  result  is non-nil, the
           then-clause  will  be  performed,  in  the  sense
           described  below.  Otherwise, (i.e. the result of
           the predicate evaluation was precisely nil),  the
           else-clause will be performed.

           Then-clauses will either consist entirely of  the
           single  keyword  thenret,  or will start with the
           keyword then, and be followed  by  at  least  one
           general  expression.   (These general expressions
           must not be one of the keywords.)  To  actuate  a
           thenret  means to cease further evaluation of the
           _i_f, and to return the value of the predicate just
           calculated.  The performance of the longer clause
           means to  evaluate  each  general  expression  in
           turn, and then return the last value calculated.

           The else-clause may begin with the  keyword  else
           and  be  followed by at least one general expres-
           sion.  The rendition of this clause is just  like
           that  of a then-clause.  An else-clause may begin
           alternatively with the  keyword  elseif,  and  be
           followed  (recursively)  by  a  predicate,  then-
           clause, and optional else-clause.  Evaluation  of
           this  clause,  is  just evaluation of an _i_f-form,


The Franz Lisp Manual                               PS2:9-81


           with the same predicate, then- and else-clauses.

(I-throw-err 'l_token)

     WHERE:   l_token is the _c_d_r of the value returned  from
              a *_c_a_t_c_h with the tag ER%unwind-protect.

     RETURNS: nothing (never returns in the current context)

     SIDE EFFECT: The error or throw denoted by  l_token  is
                  continued.

     NOTE: This function is used to implement _u_n_w_i_n_d-_p_r_o_t_e_c_t
           which allows the processing of a transfer of con-
           trol though a certain context to be  interrupted,
           a  user  function  to  be  executed  and than the
           transfer of control to  continue.   The  form  of
           l_token is either
           (_t _t_a_g _v_a_l_u_e) for a throw or
           (_n_i_l _t_y_p_e _m_e_s_s_a_g_e _v_a_l_r_e_t  _c_o_n_t_u_a_b  _u_n_i_q_u_e_i_d  [_a_r_g
           ...]) for an error.
           This function is not to be used for  implementing
           throws  or errors and is only documented here for
           completeness.

(let l_args g_exp1 ... g_exprn)

     RETURNS: the result of evaluating  g_exprn  within  the
              bindings given by l_args.

     NOTE: l_args is either nil (in which case _l_e_t  is  just
           like  _p_r_o_g_n)  or it is a list of binding objects.
           A binding object is a  list  (_s_y_m_b_o_l _e_x_p_r_e_s_s_i_o_n).
           When a _l_e_t is entered, all of the expressions are
           evaluated and then simultaneously lambda-bound to
           the  corresponding  symbols.   In  effect,  a _l_e_t
           expression  is  just  like  a  lambda  expression
           except  the  symbols and their initial values are
           next to each other, making the expression  easier
           to  understand.  There are some added features to
           the _l_e_t expression: A binding object can just  be
           a   symbol,   in   which   case   the  expression
           corresponding to that  symbol  is  `nil'.   If  a
           binding object is a list and the first element of
           that list is another  list,  then  that  list  is
           assumed  to be a binding template and _l_e_t will do
           a _d_e_s_e_t_q on it.


9

9


PS2:9-82                               The Franz Lisp Manual


(let* l_args g_exp1 ... g_expn)

     RETURNS: the result of evaluating  g_exprn  within  the
              bindings given by l_args.

     NOTE: This is identical to _l_e_t except  the  expressions
           in  the  binding  list  l_args  are evaluated and
           bound sequentially instead of in parallel.

(lexpr-funcall 'g_function ['g_arg1 ...] 'l_argn)

     NOTE: This is a cross between funcall and  apply.   The
           last  argument,  must be a list (possibly empty).
           The element of list arg are stack  and  then  the
           function is funcalled.

     EXAMPLE: (lexpr-funcall 'list 'a '(b c d)) is the  same
              as
               (funcall 'list 'a 'b 'c 'd)

(listify 'x_count)

     RETURNS: a list of x_count  of  the  arguments  to  the
              current function (which must be a lexpr).

     NOTE: normally  arguments   1   through   x_count   are
           returned.  If x_count is negative then  a list of
           last abs(x_count) arguments are returned.

(map 'u_func 'l_arg1 ...)

     RETURNS: l_arg1

     NOTE: The function u_func is applied to successive sub-
           lists  of  the  l_arg_i.  All sublists should have
           the same length.

(mapc 'u_func 'l_arg1 ...)

     RETURNS: l_arg1.

     NOTE: The function u_func is applied to successive ele-
           ments  of  the  argument lists.  All of the lists
           should have the same length.


9

9


The Franz Lisp Manual                               PS2:9-83


(mapcan 'u_func 'l_arg1 ...)

     RETURNS: nconc applied to the results of the functional
              evaluations.

     NOTE: The function u_func is applied to successive ele-
           ments of the argument lists.  All sublists should
           have the same length.

(mapcar 'u_func 'l_arg1 ...)

     RETURNS: a list of the values returned from  the  func-
              tional application.

     NOTE: the function u_func is applied to successive ele-
           ments of the argument lists.  All sublists should
           have the same length.

(mapcon 'u_func 'l_arg1 ...)

     RETURNS: nconc applied to the results of the functional
              evaluation.

     NOTE: the function u_func is applied to successive sub-
           lists of the argument lists.  All sublists should
           have the same length.

(maplist 'u_func 'l_arg1 ...)

     RETURNS: a  list  of  the  results  of  the  functional
              evaluations.

     NOTE: the function u_func is applied to successive sub-
           lists  of  the  arguments  lists.   All  sublists
           should have the same length.

     Readers may find the following summary table useful  in
     remembering  the  differences  between  the six mapping
     functions:


8         ________________________________________________________________
                                          Value returned is

                             l_arg1   list of results   _n_c_o_n_c of results
7           Argument to
           functional is
8        ________________________________________________________________

         elements of list    mapc        mapcar             mapcan

             sublists        map         maplist            mapcon
8        ________________________________________________________________
7        |7|7|7|7|7|7|7|7|


                          |7|7|7|7|7|7|7|7|


                                                                        |7|7|7|7|7|7|7|7|


9


PS2:9-84                               The Franz Lisp Manual


(mfunction t_entry 's_disc)

     RETURNS: a lisp  object  of  type  binary  composed  of
              t_entry and s_disc.

     NOTE: t_entry is a pointer to the machine  code  for  a
           function,  and  s_disc  is  the  discipline (e.g.
           lambda).

(oblist)

     RETURNS: a list of all symbols on the oblist.

(or [g_arg1 ... ])

     RETURNS: the value of the first non-null  argument   or
              nil if all arguments evaluate to nil.

     NOTE: Evaluation proceeds left to right  and  stops  as
           soon  as one of the arguments evaluates to a non-
           null value.

(prog l_vrbls g_exp1 ...)

     RETURNS: the value explicitly given in a return form or
              else  nil if no return is done by the time the
              last g_exp_i is evaluated.

     NOTE: the local variables are lambda-bound to nil, then
           the  g_exp_i  are  evaluated  from  left to right.
           This is a prog body (obviously)  and  this  means
           than  any symbols seen are not evaluated, but are
           treated as labels.  This also means that return's
           and go's are allowed.

(prog1 'g_exp1 ['g_exp2 ...])

     RETURNS: g_exp1

(prog2 'g_exp1 'g_exp2 ['g_exp3 ...])

     RETURNS: g_exp2

     NOTE: the forms are evaluated from left  to  right  and
           the value of g_exp2 is returned.


9

9


The Franz Lisp Manual                               PS2:9-85


(progn 'g_exp1 ['g_exp2 ...])

     RETURNS: the last g_exp_i.

(progv 'l_locv 'l_initv g_exp1 ...)

     WHERE:   l_locv is a list of symbols and l_initv  is  a
              list of expressions.

     RETURNS: the value of the last g_exp_i evaluated.

     NOTE: The expressions in  l_initv  are  evaluated  from
           left  to  right and then lambda-bound to the sym-
           bols in l_locv.  If there are too few expressions
           in l_initv then the missing values are assumed to
           be nil.  If there are  too  many  expressions  in
           l_initv then the extra ones are ignored (although
           they  are  evaluated).   Then  the   g_exp_i   are
           evaluated  left to right.  The body of a progv is
           like the body of a progn, it is _n_o_t a prog  body.
           (C.f. _l_e_t)

(purcopy 'g_exp)

     RETURNS: a copy of g_exp with new pure cells  allocated
              wherever possible.

     NOTE: pure space is never swept up by the garbage  col-
           lector,  so  this  should only be done on expres-
           sions which are not likely to become  garbage  in
           the  future.   In  certain cases, data objects in
           pure space become read-only after a _d_u_m_p_l_i_s_p  and
           then  an attempt to modify the object will result
           in an illegal memory reference.

(purep 'g_exp)

     RETURNS: t iff the object g_exp is in pure space.

(putd 's_name 'u_func)

     RETURNS: u_func

     SIDE EFFECT: this sets the function binding  of  symbol
                  s_name to u_func.


9

9


PS2:9-86                               The Franz Lisp Manual


(return ['g_val])

     RETURNS: g_val (or nil if g_val is  not  present)  from
              the enclosing prog or do body.

     NOTE: this form is only valid in the context of a  prog
           or do body.

(selectq 'g_key-form [l_clause1 ...])

     NOTE: This function is just  like  _c_a_s_e_q  (see  above),
           except  that  the  symbol  otherwise has the same
           semantics as the symbol t, when used  as  a  com-
           parator.

(setarg 'x_argnum 'g_val)

     WHERE:   x_argnum is greater than zero and less than or
              equal to the number of arguments to the lexpr.

     RETURNS: g_val

     SIDE EFFECT: the lexpr's x_argnum'th argument is set to
                  g-val.

     NOTE: this can only be used within the body of a lexpr.

(throw 'g_val [s_tag])

     WHERE:   if s_tag is not given, it  is  assumed  to  be
              nil.

     RETURNS: the value of (*_t_h_r_o_w '_s__t_a_g '_g__v_a_l).

(*throw 's_tag 'g_val)

     RETURNS: g_val from the first enclosing catch with  the
              tag s_tag or with no tag at all.

     NOTE: this is used in conjunction with *_c_a_t_c_h to  cause
           a clean jump to an enclosing context.


9

9


The Franz Lisp Manual                               PS2:9-87


(unwind-protect g_protected [g_cleanup1 ...])

     RETURNS: the result of evaluating g_protected.

     NOTE: Normally g_protected is evaluated and  its  value
           remembered, then the g_cleanup_i are evaluated and
           finally  the  saved  value  of   g_protected   is
           returned.    If   something  should  happen  when
           evaluating g_protected which  causes  control  to
           pass  through  g_protected   and thus through the
           call to the unwind-protect, then  the  g_cleanup_i
           will  still  be  evaluated.   This  is  useful if
           g_protected does  something sensitive which  must
           be  cleaned  up  whether  or not g_protected com-
           pletes.


9

9


                           CHAPTER  5


                          Input/Output


          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 _p_i_p_o_r_t
     and  if  output  is being done then the default port is
     the value of the symbol _p_o_p_o_r_t.   Furthermore,  if  the
     value of piport or poport is not a valid port, then the
     standard input or standard output will be used, respec-
     tively.

          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 _p_t_p_o_r_t  if  it
     is a valid port.  Output destined for the standard out-
     put will not reach the standard output if the symbol ^_w
     is  non  nil  (although  it  will still go to _p_t_p_o_r_t if
     _p_t_p_o_r_t is a valid port).

          Some of the functions listed below reference files
     directly.   FRANZ LISP has borrowed a convenient short-
     hand notation from /_b_i_n/_c_s_h, concerning  naming  files.
     If  a  file  name begins with ~ (tilde), and the symbol
     _t_i_l_d_e-_e_x_p_a_n_s_i_o_n

     is bound to something other than nil, then  FRANZ  LISP
     expands  the file name.  It takes the string of charac-
     ters 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 username is taken to be the current user.
9

9PS2:9-88                               The Franz Lisp Manual


The Franz Lisp Manual                               PS2:9-89


          FRANZ LISP keeps a cache of  user  home  directory
     information,  to  minimize searching the password file.
     Tilde-expansion is performed  in  the  following  func-
     tions:  _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, _s_y_s:_a_c_c_e_s_s, _s_y_s:_u_n_l_i_n_k.

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

     RETURNS: t

     SIDE EFFECT: This is used to load in a foreign function
                  (see  8.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 glo-
           bal  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.


9

9


PS2:9-90                               The Franz Lisp Manual


(close '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.

(cprintf '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'

(drain ['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.


9

9


The Franz Lisp Manual                               PS2:9-91


(ex [s_filename])
(vi [s_filename])
(exl [s_filename])
(vil [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.

(fasl '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.


9

9


PS2:9-92                               The Franz Lisp Manual


(ffasl  '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_'.

(filepos '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.

(filestat '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.


9

9


The Franz Lisp Manual                               PS2:9-93


(flatc '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.

(flatsize '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.

(fileopen '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.

(fseek '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.
9

9


PS2:9-94                               The Franz Lisp Manual


(infile '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.

(load '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


The Franz Lisp Manual                               PS2:9-95


                  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.

(makereadtable ['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
              current  readtable.   See  chapter  7  for   a
              description of readtables and their uses.

(msg [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.
    ____________________________________________________


9

9


PS2:9-96                               The Franz Lisp Manual


(nwritn ['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.

(outfile '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.

(patom '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.

(pntlen 'xfs_arg)

     RETURNS: the  number  of  characters  needed  to  print
              xfs_arg.

(portp 'g_arg)

     RETURNS: t iff g_arg is a port.


9

9


The Franz Lisp Manual                               PS2:9-97


(pp [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
    ____________________________________________________


(princ 'g_arg ['p_port])

     EQUIVALENT TO: patom.

(print 'g_arg ['p_port])

     RETURNS: nil

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

(probef 'st_file)

     RETURNS: t iff the file st_file exists.

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


9

9


PS2:9-98                               The Franz Lisp Manual


(pp-form '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.

(ratom ['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.

(read ['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).

(readc ['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.

(readlist 'l_arg)

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


9

9


The Franz Lisp Manual                               PS2:9-99


(removeaddress '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.

(resetio)

     RETURNS: nil

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

(setsyntax '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.

(sload '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.

(tab '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.


9

9


PS2:9-100                              The Franz Lisp Manual


(terpr ['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.

(terpri ['p_port])

     EQUIVALENT TO: terpr.

(tilde-expand '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.

(tyi ['p_port])

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

(tyipeek ['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.

(tyo '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.

(untyi '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.


9

9


The Franz Lisp Manual                              PS2:9-101


(username-to-dir 'st_name)

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

(zapline)

     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.


9

9


                           CHAPTER  6


                        System Functions


          This  chapter  describes  the  functions  used  to
     interact  with  internal  components of the Lisp system
     and operating system.

(allocate 's_type 'x_pages)

     WHERE:   s_type is one of the  FRANZ  LISP  data  types
              described in 1.3.

     RETURNS: x_pages.

     SIDE EFFECT: FRANZ LISP attempts to allocate x_pages of
                  type  s_type.   If there aren't x_pages of
                  memory left, no space  will  be  allocated
                  and an error will occur.  The storage that
                  is allocated is not given to  the  caller,
                  instead  it  is  added to the free storage
                  list of s_type.  The functions _s_e_g_m_e_n_t and
                  _s_m_a_l_l-_s_e_g_m_e_n_t  allocate blocks  of storage
                  and return it to the caller.

(argv 'x_argnumb)

     RETURNS: a symbol whose pname is the x_argnumb_t_h  argu-
              ment (starting at 0) on the command line which
              invoked the current lisp.

     NOTE: if x_argnumb is less than zero,  a  fixnum  whose
           value  is  the number of arguments on the command
           line is returned.  (_a_r_g_v _0) returns the  name  of
           the lisp you are running.

(baktrace)

     RETURNS: nil

     SIDE EFFECT: the lisp runtime stack is examined and the
                  name  of (most) of the functions currently
                  in  execution  are  printed,  most  active
                  first.

     NOTE: this will occasionally miss the names of compiled
           lisp  functions  due to incomplete information on
           the stack.  If you  are  tracing  compiled  code,
           then  _b_a_k_t_r_a_c_e  won't  be  able  to interpret the


PS2:9-102                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-103


           stack unless  (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l)  was  done.
           See  the  function  _s_h_o_w_s_t_a_c_k  for another way of
           printing the lisp runtime stack.   This  misspel-
           ling is from Maclisp.

(chdir 's_path)

     RETURNS: t iff the system call succeeds.

     SIDE EFFECT: the current directory set to s_path. Among
                  other things, this will affect the default
                  location where the input/output  functions
                  look for and create files.

     NOTE: _c_h_d_i_r follows the standard UNIX  conventions,  if
           s_path  does  not begin with a slash, the default
           path is changed to the current path  with  s_path
           appended.   _C_h_d_i_r  employs  tilde-expansion (dis-
           cussed in Chapter 5).

(command-line-args)

     RETURNS: a list of the arguments typed on  the  command
              line, either to the lisp interpreter, or saved
              lisp dump, or application  compiled  with  the
              autorun option (liszt -r).

(deref 'x_addr)

     RETURNS: The contents of x_addr, when thought of  as  a
              longword memory location.

     NOTE: This may be useful in constructing arguments to C
           functions out of `dangerous' areas of memory.

(dumplisp s_name)

     RETURNS: nil

     SIDE EFFECT: the current lisp is dumped  to  the  named
                  file.   When  s_name is executed, you will
                  be in a lisp in the same state as when the
                  dumplisp was done.

     NOTE: dumplisp will fail if one tries to write over the
           current  running file. UNIX does not allow you to
           modify the file you are running.


9

9


PS2:9-104                              The Franz Lisp Manual


(eval-when l_time g_exp1 ...)

     SIDE EFFECT: l_time may contain any combination of  the
                  symbols  _l_o_a_d,  _e_v_a_l,  and  _c_o_m_p_i_l_e.   The
                  effects of load and compile  is  discussed
                  in  12.3.2.1 compiler.  If eval is present
                  however,  this  simply  means   that   the
                  expressions g_exp1 and so on are evaluated
                  from  left  to  right.   If  eval  is  not
                  present, the forms are not evaluated.

(exit ['x_code])

     RETURNS: nothing (it never returns).

     SIDE EFFECT: the lisp system dies with exit code x_code
                  or 0 if x_code is not specified.

(fake 'x_addr)

     RETURNS: the lisp object at address x_addr.

     NOTE: This is intended to be used by  people  debugging
           the lisp system.

(fork)

     RETURNS: nil to  the  child  process  and  the  process
              number of the child to the parent.

     SIDE EFFECT: A copy of the current lisp system is  made
                  in  memory and both lisp systems now begin
                  to  run.   This  function  can   be   used
                  interactively   to  temporarily  save  the
                  state of Lisp (as shown  below),  but  you
                  must  be  careful  that  only  one  of the
                  lisp's interacts with the  terminal  after
                  the fork.  The _w_a_i_t function is useful for
                  this.


9

9


The Franz Lisp Manual                              PS2:9-105


    ____________________________________________________

    -> (_s_e_t_q _f_o_o '_b_a_r)              ;; set a variable
    bar
    -> (_c_o_n_d ((_f_o_r_k)(_w_a_i_t)))        ;; duplicate the lisp system and
    nil                             ;; make the parent wait
    -> _f_o_o                          ;; check the value of the variable
    bar
    -> (_s_e_t_q _f_o_o '_b_a_z)              ;; give it a new value
    baz
    -> _f_o_o                          ;; make sure it worked
    baz
    -> (_e_x_i_t)                       ;; exit the child
    (5274 . 0)                      ;; the _w_a_i_t function returns this
    -> _f_o_o                          ;; we check to make sure parent was
    bar                             ;; not modified.
    ____________________________________________________


(gc)

     RETURNS: nil

     SIDE EFFECT: this causes a garbage collection.

     NOTE: The function _g_c_a_f_t_e_r is not called  automatically
           after  this function finishes.  Normally the user
           doesn't have to call _g_c since garbage  collection
           occurs automatically whenever internal free lists
           are exhausted.

(gcafter s_type)

     WHERE:   s_type is one of the  FRANZ  LISP  data  types
              listed in 1.3.

     NOTE: this function is called by the garbage  collector
           after  a  garbage  collection which was caused by
           running out of data type s_type.   This  function
           should  determine if more space need be allocated
           and if so should allocate it.  There is a default
           gcafter  function but users who want control over
           space allocation can define their own -- but note
           that it must be an nlambda.


9

9


PS2:9-106                              The Franz Lisp Manual


(getenv 's_name)

     RETURNS: a symbol whose pname is the value of s_name in
              the   current  UNIX  environment.   If  s_name
              doesn't exist in the  current  environment,  a
              symbol with a null pname is returned.

(hashtabstat)

     RETURNS: a list of fixnums representing the  number  of
              symbols in each bucket of the oblist.

     NOTE: the oblist is stored a  hash  table  of  buckets.
           Ideally there would be the same number of symbols
           in each bucket.

(help [sx_arg])

     SIDE EFFECT: If sx_arg is a symbol then the portion  of
                  this manual beginning with the description
                  of sx_arg is printed on the terminal.   If
                  sx_arg  is  a fixnum or the name of one of
                  the appendicies, that chapter or  appendix
                  is  printed  on the terminal.  If no argu-
                  ment is provided, _h_e_l_p prints the  options
                  that it recognizes.  The program `more' is
                  used to print the manual on the  terminal;
                  it will stop after each page and will con-
                  tinue after the space key is pressed.

(include s_filename)

     RETURNS: nil

     SIDE EFFECT: The given  filename  is  _l_o_a_ded  into  the
                  lisp.

     NOTE: this is similar to load except  the  argument  is
           not  evaluated.   Include means something special
           to the compiler.

(include-if 'g_predicate s_filename)

     RETURNS: nil

     SIDE EFFECT: This has the same effect as  include,  but
                  is  only actuated if the predicate is non-
                  nil.


9

9


The Franz Lisp Manual                              PS2:9-107


(includef 's_filename)

     RETURNS: nil

     SIDE EFFECT: this is the same  as  _i_n_c_l_u_d_e  except  the
                  argument is evaluated.

(includef-if 'g_predicate s_filename)

     RETURNS: nil

     SIDE EFFECT: This has the same effect as includef,  but
                  is  only actuated if the predicate is non-
                  nil.

(maknum 'g_arg)

     RETURNS: the address of its argument converted  into  a
              fixnum.

(monitor ['xs_maxaddr])

     RETURNS: t

     SIDE EFFECT: If xs_maxaddr is t then profiling  of  the
                  entire   lisp   system   is   begun.    If
                  xs_maxaddr is a fixnum then  profiling  is
                  done  only  up  to address xs_maxaddr.  If
                  xs_maxaddr is not given, then profiling is
                  stopped  and  the data obtained is written
                  to the file  'mon.out'  where  it  can  be
                  analyzed with the UNIX 'prof' program.

     NOTE: this function only works if the lisp  system  has
           been  compiled  in  a  special way, otherwise, an
           error is invoked.

(opval 's_arg ['g_newval])

     RETURNS: the value associated  with  s_arg  before  the
              call.

     SIDE EFFECT: If g_newval is specified, the value  asso-
                  ciated with s_arg is changed to g_newval.

     NOTE: _o_p_v_a_l keeps track of storage allocation. If s_arg
           is one of the data types then _o_p_v_a_l will return a
           list of three fixnums representing the number  of
           items  of  that  type in use, the number of pages
           allocated and the number of items  of  that  type
           per  page.  You  should  never  try to change the
           value _o_p_v_a_l associates with  a  data  type  using
           _o_p_v_a_l.


PS2:9-108                              The Franz Lisp Manual


           If s_arg is _p_a_g_e_l_i_m_i_t then _o_p_v_a_l will return (and
           set  if  g_newval is given) the maximum amount of
           lisp data pages it  will  allocate.   This  limit
           should  remain small unless you know your program
           requires lots of space as this limit  will  catch
           programs   in  infinite  loops  which  gobble  up
           memory.

(*process 'st_command ['g_readp ['g_writep]])

     RETURNS: either a fixnum if one argument is given, or a
              list of two ports and a fixnum if two or three
              arguments are given.

     NOTE: *_p_r_o_c_e_s_s  starts  another  process   by   passing
           st_command to the shell (it first tries /bin/csh,
           then it tries /bin/sh if /bin/csh doesn't exist).
           If  only one argument is given to *_p_r_o_c_e_s_s, *_p_r_o_-
           _c_e_s_s waits for the new process to  die  and  then
           returns  the  exit  code  of the new process.  If
           more two or three arguments are  given,  *_p_r_o_c_e_s_s
           starts the process and then returns a list which,
           depending on the value of g_readp  and  g_writep,
           may  contain  i/o ports for communcating with the
           new process.  If g_writep  is  non-null,  then  a
           port  will  be created which the lisp program can
           use to send characters to the  new  process.   If
           g_readp  is non-null, then a port will be created
           which the lisp program can use to read characters
           from  the  new  process.   The  value returned by
           *_p_r_o_c_e_s_s is (readport writeport pid) where  read-
           port and writeport are either nil or a port based
           on the value of g_readp and g_writep.  Pid is the
           process  id of the new process.  Since it is hard
           to remember the order of  g_readp  and  g_writep,
           the  functions *_p_r_o_c_e_s_s-_s_e_n_d and *_p_r_o_c_e_s_s-_r_e_c_e_i_v_e
           were written to perform the common functions.

(*process-receive 'st_command)

     RETURNS: a port which can be read.

     SIDE EFFECT: The command st_command  is  given  to  the
                  shell  and  it  is  started running in the
                  background.  The output of that command is
                  available   for   reading   via  the  port
                  returned.  The input of the  command  pro-
                  cess is set to /dev/null.


9

9


The Franz Lisp Manual                              PS2:9-109


(*process-send 'st_command)

     RETURNS: a port which can be written to.

     SIDE EFFECT: The command st_command  is  given  to  the
                  shell  and  it  is  started  runing in the
                  background.  The lisp program can  provide
                  input  for that command by sending charac-
                  ters to the port returned  by  this  func-
                  tion.   The  output of the command process
                  is set to /dev/null.

(process s_pgrm [s_frompipe s_topipe])

     RETURNS: if the optional arguments are  not  present  a
              fixnum  which  is  the  exit  code when s_prgm
              dies.  If the optional arguments are  present,
              it returns a fixnum which is the process id of
              the child.

     NOTE: This command is obsolete.   New  programs  should
           use one of the *_p_r_o_c_e_s_s commands given above.

     SIDE EFFECT: If s_frompipe and s_topipe are given, they
                  are  bound  to ports which are pipes which
                  direct characters from FRANZ LISP  to  the
                  new process and to FRANZ LISP from the new
                  process  respectively.   _P_r_o_c_e_s_s  forks  a
                  process  named  s_prgm and waits for it to
                  die iff there are no pipe arguments given.

(ptime)

     RETURNS: a list of two  elements.   The  first  is  the
              amount of processor time used by the lisp sys-
              tem so far, and the second is  the  amount  of
              time used by the garbage collector so far.

     NOTE: the time is measured in those units used  by  the
           _t_i_m_e_s(2)  system call, usually 60_t_hs of a second.
           The first number includes the second number.  The
           amount  of time used by garbage collection is not
           recorded until the first call to ptime.  This  is
           done  to  prevent  overhead  when the user is not
           interested in garbage collection times.


9

9


PS2:9-110                              The Franz Lisp Manual


(reset)

     SIDE EFFECT: the lisp runtime stack is cleared and  the
                  system  restarts  at the top level by exe-
                  cuting a (_f_u_n_c_a_l_l _t_o_p-_l_e_v_e_l _n_i_l).

(restorelisp 's_name)

     SIDE EFFECT: this  reads  in  file  s_name  (which  was
                  created  by  _s_a_v_e_l_i_s_p)  and  then  does  a
                  (_r_e_s_e_t).

     NOTE: This is only used on VMS systems  where  _d_u_m_p_l_i_s_p
           cannot be used.

(retbrk ['x_level])

     WHERE:   x_level is a small integer of either sign.

     SIDE EFFECT: The default error handler keeps  a  notion
                  of  the current level of the error caught.
                  If x_level is negative, control is  thrown
                  to  this default error handler whose level
                  is that many less than the present, or  to
                  _t_o_p-_l_e_v_e_l  if  there  aren't  enough.   If
                  x_level is non-negative, control is passed
                  to  the handler at that level.  If x_level
                  is not present, the value -1 is  taken  by
                  default.

(*rset 'g_flag)

     RETURNS: g_flag

     SIDE EFFECT: If g_flag is non nil then the lisp  system
                  will   maintain  extra  information  about
                  calls to _e_v_a_l and  _f_u_n_c_a_l_l.   This  record
                  keeping slows down the evaluation but this
                  is required  for the  functions  _e_v_a_l_h_o_o_k,
                  _f_u_n_c_a_l_l_h_o_o_k,  and  _e_v_a_l_f_r_a_m_e  to  work. To
                  debug  compiled  lisp  code  the  transfer
                  tables       should      be      unlinked:
                  (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l)


9

9


The Franz Lisp Manual                              PS2:9-111


(savelisp 's_name)

     RETURNS: t

     SIDE EFFECT: the state of the Lisp system is  saved  in
                  the  file  s_name.   It  can be read in by
                  _r_e_s_t_o_r_e_l_i_s_p.

     NOTE: This is only used on VMS systems  where  _d_u_m_p_l_i_s_p
           cannot be used.

(segment 's_type 'x_size)

     WHERE:   s_type is one of the data types given in 1.3

     RETURNS: a  segment  of  contiguous  lispvals  of  type
              s_type.

     NOTE: In reality, _s_e_g_m_e_n_t returns a new  data  cell  of
           type  s_type  and  allocates space for x_size - 1
           more s_type's beyond the one  returned.   _S_e_g_m_e_n_t
           always  allocates  new  space  and does so in 512
           byte chunks.  If you ask for 2  fixnums,  segment
           will  actually  allocate 128 of them thus wasting
           126 fixnums.  The  function  _s_m_a_l_l-_s_e_g_m_e_n_t  is  a
           smarter  space allocator and should be used when-
           ever possible.

(shell)

     RETURNS: the exit code of the shell when it dies.

     SIDE EFFECT: this forks a new shell  and  returns  when
                  the shell dies.

(showstack)

     RETURNS: nil

     SIDE EFFECT: all  forms  currently  in  evaluation  are
                  printed,  beginning  with the most recent.
                  For compiled code the most that  showstack
                  will  show is the function name and it may
                  miss some functions.


9

9


PS2:9-112                              The Franz Lisp Manual


(signal 'x_signum 's_name)

     RETURNS: nil if no previous call  to  signal  has  been
              made, or the previously installed s_name.

     SIDE EFFECT: this  declares  that  the  function  named
                  s_name   will  handle  the  signal  number
                  x_signum.  If s_name is nil, the signal is
                  ignored.  Presently only four UNIX signals
                  are caught.  They and their  numbers  are:
                  Interrupt(2),    Floating    exception(8),
                  Alarm(14), and Hang-up(1).

(sizeof 'g_arg)

     RETURNS: the number of  bytes  required  to  store  one
              object of type g_arg, encoded as a fixnum.

(small-segment 's_type 'x_cells)

     WHERE:   s_type is one of fixnum, flonum and value.

     RETURNS: a segment of  x_cells  data  objects  of  type
              s_type.

     SIDE EFFECT: This may  call  _s_e_g_m_e_n_t  to  allocate  new
                  space  or  it  may  be  able  to  fill the
                  request on a page already allocated.   The
                  value returned by _s_m_a_l_l-_s_e_g_m_e_n_t is usually
                  stored in the data  subpart  of  an  array
                  object.

(sstatus g_type g_val)

     RETURNS: g_val

     SIDE EFFECT: If  g_type  is  not  one  of  the  special
                  sstatus  codes  described  in the next few
                  pages this simply sets g_val as the  value
                  of status type g_type in the system status
                  property list.


9

9


The Franz Lisp Manual                              PS2:9-113


(sstatus appendmap g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is non-null when _f_a_s_l is told  to
                  create  a  load map, it will append to the
                  file  name  given  in  the  _f_a_s_l  command,
                  rather  than creating a new map file.  The
                  initial value is nil.

(sstatus automatic-reset g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is non-null when an error  occurs
                  which no one wants to handle, a _r_e_s_e_t will
                  be done instead of  entering  a  primitive
                  internal break loop.  The initial value is
                  t.

(sstatus chainatom g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is non nil and a _c_a_r or _c_d_r of  a
                  symbol  is done, then nil will be returned
                  instead of an error being signaled.   This
                  only affects the interpreter, not the com-
                  piler.  The initial value is nil.

(sstatus dumpcore g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is nil,  FRANZ  LISP  tells  UNIX
                  that a segmentation violation or bus error
                  should cause a core dump.  If g_val is non
                  nil  then  FRANZ  LISP  will  catch  those
                  errors and print a  message  advising  the
                  user to reset.

     NOTE: The initial value for this flag is nil, and  only
           those  knowledgeable  of  the innards of the lisp
           system should ever set this flag non nil.


9

9


PS2:9-114                              The Franz Lisp Manual


(sstatus dumpmode x_val)

     RETURNS: x_val

     SIDE EFFECT: All subsequent _d_u_m_p_l_i_s_p's will be done  in
                  mode  x_val.   x_val  may be either 413 or
                  410 (decimal).

     NOTE: the advantage of mode 413 is that the dumped Lisp
           can  be demand paged in when first started, which
           will make it start faster and disrupt other users
           less.  The initial value is 413.

(sstatus evalhook g_val)

     RETURNS: g_val

     SIDE EFFECT: When g_val is non nil,  this  enables  the
                  evalhook  and  funcallhook  traps  in  the
                  evaluator.  See 14.4 for more details.

(sstatus feature g_val)

     RETURNS: g_val

     SIDE EFFECT: g_val is added  to  the  (_s_t_a_t_u_s _f_e_a_t_u_r_e_s)
                  list,

(sstatus gcstrings g_val)

     RETURNS: g_val

     SIDE EFFECT: if g_val is non-null, and if  string  gar-
                  bage  collection was enabled when the lisp
                  system was compiled, string space will  be
                  garbage collected.

     NOTE: the default value for this is nil since  in  most
           applications  garbage  collecting  strings  is  a
           waste of time.

(sstatus ignoreeof g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is non-null when an end  of  file
                  (CNTL-D  on UNIX) is typed to the standard
                  top-level interpreter, it will be  ignored
                  rather then cause the lisp system to exit.
                  If the the standard input  is  a  file  or
                  pipe  then this has no effect, an EOF will
                  always cause lisp to  exit.   The  initial
                  value is nil.


The Franz Lisp Manual                              PS2:9-115


(sstatus nofeature g_val)

     RETURNS: g_val

     SIDE EFFECT: g_val is removed from the status  features
                  list if it was present.

(sstatus translink g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is nil then all  transfer  tables
                  are  cleared and further calls through the
                  transfer table will  not  cause  the  fast
                  links  to be set up.  If g_val is the sym-
                  bol _o_n then all  possible  transfer  table
                  entries  will  be linked and the flag will
                  be set to cause fast links to  be  set  up
                  dynamically.   Otherwise  all that is done
                  is to set the flag to cause fast links  to
                  be  set up dynamically.  The initial value
                  is nil.

     NOTE: For a discussion of transfer tables, see 12.8.

(sstatus uctolc g_val)

     RETURNS: g_val

     SIDE EFFECT: If g_val is not  nil  then  all  unescaped
                  capital  letters  in  symbols  read by the
                  reader will be converted to lower case.

     NOTE: This allows FRANZ LISP to be compatible with sin-
           gle  case  lisp  systems (e.g. Maclisp, Interlisp
           and UCILisp).

(status g_code)

     RETURNS: the value  associated  with  the  status  code
              g_code  if  g_code  is  not one of the special
              cases given below


9

9


PS2:9-116                              The Franz Lisp Manual


(status ctime)

     RETURNS: a symbol whose print name is the current  time
              and date.

     EXAMPLE: (_s_t_a_t_u_s _c_t_i_m_e) = |Sun Jun 29 16:51:26 1980|

     NOTE: This  has  been  made  obsolete  by  _t_i_m_e-_s_t_r_i_n_g,
           described below.

(status feature g_val)

     RETURNS: t iff g_val is in the status features list.

(status features)

     RETURNS: the value of the features  code,  which  is  a
              list  of  features  which  are present in this
              system.    You   add   to   this   list   with
              (_s_s_t_a_t_u_s _f_e_a_t_u_r_e '_g__v_a_l)  and  test if feature
              g_feat         is         present         with
              (_s_t_a_t_u_s _f_e_a_t_u_r_e '_g__f_e_a_t).

(status isatty)

     RETURNS: t iff the standard input is a terminal.

(status localtime)

     RETURNS: a list of  fixnums  representing  the  current
              time.

     EXAMPLE: (_s_t_a_t_u_s _l_o_c_a_l_t_i_m_e) =  (3 51 13 31 6 81  5  211
              1)
              means 3_r_d second, 51_s_t minute,  13_t_h  hour  (1
              p.m), 31_s_t day, month 6 (0 = January), year 81
              (0 = 1900), day of the  week  5  (0 = Sunday),
              211_t_h  day  of  the  year and daylight savings
              time is in effect.

(status syntax s_char)

     NOTE: This  function  should  not  be  used.   See  the
           description  of  _g_e_t_s_y_n_t_a_x  (in  Chapter 7) for a
           replacement.


9

9


The Franz Lisp Manual                              PS2:9-117


(status undeffunc)

     RETURNS: a list of all functions which  transfer  table
              entries  point to but which are not defined at
              this point.

     NOTE: Some of the undefined functions listed  could  be
           arrays which have yet to be created.

(status version)

     RETURNS: a string which is  the  current  lisp  version
              name.

     EXAMPLE: (_s_t_a_t_u_s _v_e_r_s_i_o_n) = "Franz Lisp, Opus 38.61"

(syscall 'x_index ['xst_arg1 ...])

     RETURNS: the result of issuing  the  UNIX  system  call
              number x_index with arguments xst_arg_i.

     NOTE: The UNIX system calls are described in section  2
           of the UNIX Programmer's manual. If xst_arg_i is a
           fixnum, then its value is passed as an  argument,
           if  it  is  a symbol then its pname is passed and
           finally if it is a string then the string  itself
           is  passed  as an argument.  Some useful syscalls
           are:
           (_s_y_s_c_a_l_l _2_0) returns process id.
           (_s_y_s_c_a_l_l _1_3) returns the number of seconds  since
           Jan 1, 1970.
           (_s_y_s_c_a_l_l _1_0 '_f_o_o) will unlink (delete)  the  file
           foo.

(sys:access 'st_filename 'x_mode)
(sys:chmod 'st_filename 'x_mode)
(sys:gethostname)
(sys:getpid)
(sys:getpwnam 'st_username)
(sys:link 'st_oldfilename 'st_newfilename)
(sys:time)
(sys:unlink 'st_filename)

     NOTE: We have been warned that the actual  system  call
           numbers  may  vary  among different UNIX systems.
           Users concerned about portability may wish to use
           this  group  of  functions.  Another advantage is
           that tilde-expansion is performed on all filename
           arguments.   These functions do what is described
           in the system call section of your UNIX manual.

           _s_y_s:_g_e_t_p_w_n_a_m returns a  vector  of  four  entries
           from the password file, being the user name, user


PS2:9-118                              The Franz Lisp Manual


           id, group id, and home directory.

(time-string ['x_seconds])

     RETURNS: an ascii string giving the time and date which
              was  x_seconds  after  UNIX's idea of creation
              (Midnight, Jan 1, 1970 GMT).  If  no  argument
              is  given,  time-string  returns  the  current
              date.  This supplants (_s_t_a_t_u_s _c_t_i_m_e), and  may
              be  used  to make the results of _f_i_l_e_s_t_a_t more
              intelligible.

(top-level)

     RETURNS: nothing (it never returns)

     NOTE: This function is  the  top-level  read-eval-print
           loop.   It  never  returns  any  value.  Its main
           utility is that if you  redefine  it,  and  do  a
           (reset)  then  the  redefined (top-level) is then
           invoked.  The default top-level for Franz,  allow
           one  to  specify  his  own  printer or reader, by
           binding the symbols  top-level-printer  and  top-
           level-reader.   One can let the default top-level
           do most of the drudgery in catching _r_e_s_e_t's,  and
           reading  in  .lisprc files, by binding the symbol
           user-top-level, to a routine that concerns itself
           only with the read-eval-print loop.

(wait)

     RETURNS: a dotted pair (_p_r_o_c_e_s_s_i_d .  _s_t_a_t_u_s)  when  the
              next child process dies.


9

9


                           CHAPTER  7


                         The Lisp Reader


   _7._1.  _I_n_t_r_o_d_u_c_t_i_o_n

           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.  _S_y_n_t_a_x _C_l_a_s_s_e_s

           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 Franz Lisp Manual                              PS2:9-119


PS2:9-120                              The Franz Lisp Manual


           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.  _R_e_a_d_e_r _O_p_e_r_a_t_i_o_n_s

           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


The Franz Lisp Manual                              PS2:9-121


      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.  _C_h_a_r_a_c_t_e_r _C_l_a_s_s_e_s


_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


PS2:9-122                              The Franz Lisp Manual


      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


The Franz Lisp Manual                              PS2:9-123


      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  _v_c_h_a_r_a_c_t_e_r.   A character whose syntax
      class is _v_c_h_a_r_a_c_t_e_r 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.


PS2:9-124                              The Franz Lisp Manual


_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.  _S_y_n_t_a_x _C_l_a_s_s_e_s

           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


The Franz Lisp Manual                              PS2:9-125


      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


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


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


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


9

9


PS2:9-126                              The Franz Lisp Manual


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


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


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


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

9

9


The Franz Lisp Manual                              PS2:9-127


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


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


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


   _7._6.  _C_h_a_r_a_c_t_e_r _M_a_c_r_o_s

           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.  _T_y_p_e_s   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.  _N_o_r_m_a_l

                 A normal macro is passed no arguments.  The
            value  returned by a normal macro is simply used


PS2:9-128                              The Franz Lisp Manual


            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
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.  _S_p_l_i_c_i_n_g

                 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


9

9


The Franz Lisp Manual                              PS2:9-129


    ____________________________________________________

    -> (_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.  _I_n_f_i_x

                 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
            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.


9

9


PS2:9-130                              The Franz Lisp Manual


    ____________________________________________________

    -> (_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.  _I_n_v_o_c_a_t_i_o_n_s

              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,
              _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
              _v_m_a_c_r_o, _v_s_p_l_i_c_i_n_g-_m_a_c_r_o, and _v_s_i_n_g_l_e-_m_a_c_r_o 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,


The Franz Lisp Manual                              PS2:9-131


              _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 _v_s_i_n_g_l_e-_m_a_c_r_o,
              _v_s_i_n_g_l_e-_s_p_l_i_c_i_n_g-_m_a_c_r_o,   and   _v_s_i_n_g_l_e-_i_n_f_i_x-
              _m_a_c_r_o.


   _7._7.  _F_u_n_c_t_i_o_n_s

(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.

(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


PS2:9-132                              The Franz Lisp Manual


                  syntax 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


                           CHAPTER  8


                Functions, Fclosures, and Macros


   _8._1.  _v_a_l_i_d _f_u_n_c_t_i_o_n _o_b_j_e_c_t_s

           There are many different objects which can occupy
      the  function field of a symbol object.  Table 8.1, on
      the following page, shows all  of  the  possibilities,
      how  to recognize them, and where to look for documen-
      tation.


   _8._2.  _f_u_n_c_t_i_o_n_s

           The basic Lisp function is the  lambda  function.
      When a lambda function is called, the actual arguments
      are evaluated from left to right and are  lambda-bound
      to the formal parameters of the lambda function.

           An nlambda function is usually used for functions
      which  are  invoked  by  the  user at top level.  Some
      built-in functions which evaluate their  arguments  in
      special  ways  are  also  nlambdas (e.g _c_o_n_d, _d_o, _o_r).
      When an  nlambda  function  is  called,  the  list  of
      unevaluated  arguments  is  lambda bound to the single
      formal parameter of the nlambda function.

           Some programmers will  use  an  nlambda  function
      when  they  are  not  sure  how many arguments will be
      passed.  Then, the first thing  the  nlambda  function
      does  is  map  _e_v_a_l over the list of unevaluated argu-
      ments it has been passed.  This is usually  the  wrong
      thing  to  do,  as it will not work compiled if any of
      the arguments are local variables. The solution is  to
      use  a  lexpr.   When  a lexpr function is called, the
      arguments are evaluated and a fixnum  whose  value  is
      the  number of arguments is lambda-bound to the single
      formal parameter of the lexpr function.  The lexpr can
      then access the arguments using the _a_r_g function.

           When a function is compiled, _s_p_e_c_i_a_l declarations
      may  be  needed to preserve its behavior.  An argument
      is not lambda-bound to the name of  the  corresponding
      formal parameter unless that formal parameter has been


The Franz Lisp Manual                              PS2:9-133


PS2:9-134                              The Franz Lisp Manual


8_________________________________________________________________
   informal name             object type          documentation
8__________________________________________________________________________________________________________________________________
    interpreted             list with _c_a_r              8.2
  lambda function           _e_q to lambda
8_________________________________________________________________
    interpreted             list with _c_a_r              8.2
  nlambda function          _e_q to nlambda
8_________________________________________________________________
    interpreted             list with _c_a_r              8.2
   lexpr function            _e_q to lexpr
8_________________________________________________________________
    interpreted             list with _c_a_r              8.3
       macro                 _e_q to macro
8_________________________________________________________________
      fclosure            vector with _v_p_r_o_p            8.4
                           _e_q to fclosure
8_________________________________________________________________
      compiled         binary with discipline          8.2
  lambda or lexpr           _e_q to lambda
      function
8_________________________________________________________________
      compiled         binary with discipline          8.2
  nlambda function          _e_q to nlambda
8_________________________________________________________________
      compiled         binary with discipline          8.3
       macro                 _e_q to macro
8_________________________________________________________________
      foreign          binary with discipline          8.5
     subroutine          of "subroutine"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
      function            of "function"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
  integer function    of "integer-function"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
   real function        of "real-function"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
     C function          of "c-function"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
  double function     of "double-c-function"[|-]
8_________________________________________________________________
      foreign          binary with discipline          8.5
 structure function   of "vector-c-function"[|-]
8_________________________________________________________________
       array                array object                9
8_________________________________________________________________
7|8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


9                    |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


9                                                |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


9                                                                 |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|


9                         Table 8.1
9____________________
9   [|-]Only the first character of the string is significant (i.e "s"
is ok for "subroutine")


The Franz Lisp Manual                              PS2:9-135


      declared _s_p_e_c_i_a_l (see 12.3.2.2).

           Lambda and lexpr functions both  compile  into  a
      binary object with a discipline of lambda.  However, a
      compiled lexpr still acts like an interpreted lexpr.


   _8._3.  _m_a_c_r_o_s

           An important feature of Lisp is  its  ability  to
      manipulate  programs  as  data.   As a result of this,
      most Lisp implementations  have  very  powerful  macro
      facilities.  The Lisp language's macro facility can be
      used to incorporate  popular  features  of  the  other
      languages  into  Lisp.   For  example, there are macro
      packages which allow one to create records  (ala  Pas-
      cal)  and  refer  to  elements of those records by the
      field names.  The _s_t_r_u_c_t package imported from Maclisp
      does  this.   Another  popular  use  for  macros is to
      create more readable control structures  which  expand
      into  _c_o_n_d,  _o_r  and  _a_n_d.  One such example is the If
      macro.  It allows you to write

      (_I_f (_e_q_u_a_l _n_u_m_b _0) _t_h_e_n (_p_r_i_n_t '_z_e_r_o) (_t_e_r_p_r)
       _e_l_s_e_i_f (_e_q_u_a_l _n_u_m_b _1) _t_h_e_n (_p_r_i_n_t '_o_n_e) (_t_e_r_p_r)
       _e_l_s_e (_p_r_i_n_t '|_I _g_i_v_e _u_p|))

      which expands to

      (_c_o_n_d
          ((_e_q_u_a_l _n_u_m_b _0) (_p_r_i_n_t '_z_e_r_o) (_t_e_r_p_r))
          ((_e_q_u_a_l _n_u_m_b _1) (_p_r_i_n_t '_o_n_e) (_t_e_r_p_r))
          (_t (_p_r_i_n_t '|_I _g_i_v_e _u_p|)))


      _8._3._1.  _m_a_c_r_o _f_o_r_m_s

              A macro is a function  which  accepts  a  Lisp
         expression   as  input  and  returns  another  Lisp
         expression.  The action the macro takes  is  called
         macro expansion.  Here is a simple example:

         -> (_d_e_f _f_i_r_s_t (_m_a_c_r_o (_x) (_c_o_n_s '_c_a_r (_c_d_r _x))))
         first
         -> (_f_i_r_s_t '(_a _b _c))
         a
         -> (_a_p_p_l_y '_f_i_r_s_t '(_f_i_r_s_t '(_a _b _c)))
         (car '(a b c))

         The first input line defines a macro called  _f_i_r_s_t.


PS2:9-136                              The Franz Lisp Manual


         Notice  that the macro has one formal parameter, _x.
         On the second input line, we ask the interpreter to
         evaluate  (_f_i_r_s_t '(_a _b _c)).   _E_v_a_l  sees that _f_i_r_s_t
         has a function definition  of  type  macro,  so  it
         evaluates  _f_i_r_s_t's definition, passing to _f_i_r_s_t, as
         an argument, the form _e_v_a_l  itself  was  trying  to
         evaluate:  (_f_i_r_s_t '(_a _b _c)).  The _f_i_r_s_t macro chops
         off the car of the argument with _c_d_r, cons'  a  _c_a_r
         at   the   beginning   of   the  list  and  returns
         (_c_a_r '(_a _b _c)), which _e_v_a_l evaluates.  The value  _a
         is returned as the value of (_f_i_r_s_t '(_a _b _c)).  Thus
         whenever _e_v_a_l tries to evaluate a  list  whose  car
         has  a macro definition it ends up doing (at least)
         two operations, the first of which is a call to the
         macro  to  let  it  macro  expand the form, and the
         other is the evaluation of the result of the macro.
         The  result of the macro may be yet another call to
         a macro, so _e_v_a_l may have to do even  more  evalua-
         tions  until it can finally determine the  value of
         an expression.  One way to see  how  a  macro  will
         expand  is to use _a_p_p_l_y as shown on the third input
         line above.


      _8._3._2.  _d_e_f_m_a_c_r_o

              The macro _d_e_f_m_a_c_r_o makes it easier  to  define
         macros  because it allows you to name the arguments
         to the macro call.  For example,  suppose  we  find
         ourselves      often      writing     code     like
         (_s_e_t_q _s_t_a_c_k (_c_o_n_s _n_e_w_e_l_t _s_t_a_c_k).  We could define a
         macro  named  _p_u_s_h  to  do this for us.  One way to
         define it is:

         -> (_d_e_f _p_u_s_h
               (_m_a_c_r_o (_x) (_l_i_s_t '_s_e_t_q (_c_a_d_d_r _x) (_l_i_s_t '_c_o_n_s (_c_a_d_r _x) (_c_a_d_d_r _x)))))
         push

         then (_p_u_s_h _n_e_w_e_l_t _s_t_a_c_k) will expand  to  the  form
         mentioned above.  The same macro written using def-
         macro would be:

         -> (_d_e_f_m_a_c_r_o _p_u_s_h (_v_a_l_u_e _s_t_a_c_k)
           (_l_i_s_t '_s_e_t_q ,_s_t_a_c_k (_l_i_s_t '_c_o_n_s ,_v_a_l_u_e ,_s_t_a_c_k)))
         push

         Defmacro allows you to name the  arguments  of  the
         macro  call,  and  makes  the macro definition look
         more like a function definition.


9

9


The Franz Lisp Manual                              PS2:9-137


      _8._3._3.  _t_h_e _b_a_c_k_q_u_o_t_e _c_h_a_r_a_c_t_e_r _m_a_c_r_o

              The default syntax for  FRANZ  LISP  has  four
         characters  with  associated character macros.  One
         is semicolon for  comments.   Two  others  are  the
         backquote and comma which are used by the backquote
         character macro.  The  fourth  is  the  sharp  sign
         macro described in the next section.

              The backquote macro is used  to  create  lists
         where many of the elements are fixed (quoted). This
         makes it very useful  for  creating  macro  defini-
         tions.  In the simplest case, a backquote acts just
         like a single quote:

         ->`(_a _b _c _d _e)
         (a b c d e)

         If a comma precedes an element of a backquoted list
         then that element is evaluated and its value is put
         in the list.

         ->(_s_e_t_q _d '(_x _y _z))
         (x y z)
         ->`(_a _b _c ,_d _e)
         (a b c (x y z) e)

         If a comma followed by an at sign precedes an  ele-
         ment  in  a  backquoted  list, then that element is
         evaluated and spliced into the list with _a_p_p_e_n_d.

         ->`(_a _b _c ,@_d _e)
         (a b c x y z e)

         Once a list begins with a backquote, the commas may
         appear anywhere in the list as this example shows:

         ->`(_a _b (_c _d ,(_c_d_r _d)) (_e _f (_g _h ,@(_c_d_d_r _d) ,@_d)))
         (a b (c d (y z)) (e f (g h z x y z)))

         It is also possible and sometimes  even  useful  to
         use  the backquote macro within itself.  As a final
         demonstration of  the  backquote  macro,  we  shall
         define  the  first  and  push  macros using all the
         power at our disposal: defmacro and  the  backquote
         macro.

         ->(_d_e_f_m_a_c_r_o _f_i_r_s_t (_l_i_s_t) `(_c_a_r ,_l_i_s_t))
         first
         ->(_d_e_f_m_a_c_r_o _p_u_s_h (_v_a_l_u_e _s_t_a_c_k) `(_s_e_t_q ,_s_t_a_c_k (_c_o_n_s ,_v_a_l_u_e ,_s_t_a_c_k)))
         stack

9

9


PS2:9-138                              The Franz Lisp Manual


      _8._3._4.  _s_h_a_r_p _s_i_g_n _c_h_a_r_a_c_t_e_r _m_a_c_r_o

              The sharp sign macro can perform a  number  of
         different  functions   at read time.  The character
         directly following the sharp sign determines  which
         function  will  be  done,  and  following  Lisp  s-
         expressions may serve as arguments.


         _8._3._4._1.  _c_o_n_d_i_t_i_o_n_a_l _i_n_c_l_u_s_i_o_n

            If you plan to run one source file in more  than
            one environment then you may want to some pieces
            of code to be included  or not included  depend-
            ing  on  the  environment.  The  C language uses
            "#ifdef" and "#ifndef"  for  this  purpose,  and
            Lisp  uses  "#+" and "#-".  The environment that
            the   sharp   sign   macro   checks    is    the
            (_s_t_a_t_u_s _f_e_a_t_u_r_e_s) list which is initialized when
            the Lisp system  is  built   and  which  may  be
            altered     by     (_s_s_t_a_t_u_s _f_e_a_t_u_r_e _f_o_o)     and
            (_s_s_t_a_t_u_s _n_o_f_e_a_t_u_r_e _b_a_r) The form  of conditional
            inclusion is
                        _#_+_w_h_e_n _w_h_a_t
            where _w_h_e_n is either a symbol or  an  expression
            involving symbols and the functions _a_n_d, _o_r, and
            _n_o_t.  The meaning is that _w_h_a_t will only be read
            in  if  _w_h_e_n  is true.  A symbol in _w_h_e_n is true
            only if  it  appears  in  the  (_s_t_a_t_u_s _f_e_a_t_u_r_e_s)
            list.


    ____________________________________________________

    ; suppose we want to write a program which references a file
    ; and which can run at ucb, ucsd and cmu where the file naming conventions
    ; are different.
    ;
    -> (_d_e_f_u_n _h_o_w_o_l_d (_n_a_m_e)
          (_t_e_r_p_r)
          (_l_o_a_d #+(_o_r _u_c_b _u_c_s_d) "/_u_s_r/_l_i_b/_l_i_s_p/_a_g_e_s._l"
                 #+_c_m_u "/_u_s_r/_l_i_s_p/_d_o_c/_a_g_e_s._l")
          (_p_a_t_o_m _n_a_m_e)
          (_p_a_t_o_m " _i_s ")
          (_p_r_i_n_t (_c_d_r (_a_s_s_o_c _n_a_m_e _a_g_e_f_i_l_e)))
          (_p_a_t_o_m "_y_e_a_r_s _o_l_d")
          (_t_e_r_p_r))
    ____________________________________________________


The form


The Franz Lisp Manual                              PS2:9-139


                        _#_-_w_h_e_n _w_h_a_t
is equivalent to
                     _#_+_(_n_o_t _w_h_e_n_) _w_h_a_t


         _8._3._4._2.  _f_i_x_n_u_m _c_h_a_r_a_c_t_e_r _e_q_u_i_v_a_l_e_n_t_s

            When working with fixnum equivalents of  charac-
            ters,  it  is  often hard to remember the number
            corresponding to a character.  The form
                            _#_/_c
            is equivalent to the  fixnum  representation  of
            character c.


    ____________________________________________________

    ; a function which returns t if the user types y else it returns nil.
    ;
    -> (_d_e_f_u_n _y_e_s_o_r_n_o _n_i_l
          (_p_r_o_g_n (_a_n_s)
                 (_s_e_t_q _a_n_s (_t_y_i))
                 (_c_o_n_d ((_e_q_u_a_l _a_n_s #/_y) _t)
                       (_t _n_i_l))))
    ____________________________________________________


         _8._3._4._3.  _r_e_a_d _t_i_m_e _e_v_a_l_u_a_t_i_o_n

            Occasionally you want to express a constant as a
            Lisp  expression,  yet you don't want to pay the
            penalty of evaluating this expression each  time
            it is referenced.  The form
                        _#_._e_x_p_r_e_s_s_i_o_n
            evaluates  the  expression  at  read  time   and
            returns its value.


9

9


PS2:9-140                              The Franz Lisp Manual


    ____________________________________________________

    ; a function to test if any of bits 1 3 or 12 are set in a fixnum.
    ;
    -> (_d_e_f_u_n _t_e_s_t_i_t (_n_u_m)
          (_c_o_n_d ((_z_e_r_o_p (_b_o_o_l_e _1 _n_u_m #.(+ (_l_s_h _1 _1) (_l_s_h _1 _3) (_l_s_h _1 _1_2))))
                 _n_i_l)
                (_t _t)))
    ____________________________________________________


   _8._4.  _f_c_l_o_s_u_r_e_s

           Fclosures are a type of functional  object.   The
      purpose  is  to  remember the values of some variables
      between invocations of the functional  object  and  to
      protect this data from being inadvertently overwritten
      by other Lisp  functions.   Fortran  programs  usually
      exhibit  this behavior for their variables.  (In fact,
      some versions of Fortran would require  the  variables
      to  be  in COMMON).  Thus it is easy to write a linear
      congruent random number generator in  Fortran,  merely
      by keeping the seed as a variable in the function.  It
      is much more risky to do so in Lisp, since any special
      variable you picked, might be used by some other func-
      tion.  Fclosures are an attempt to provide most of the
      same  functionality  as closures in Lisp Machine Lisp,
      to users of FRANZ LISP.  Fclosures are related to clo-
      sures in this way:
      (fclosure '(a b) 'foo) <==>
              (let ((a a) (b b)) (closure '(a b) 'foo))


      _8._4._1.  _a_n _e_x_a_m_p_l_e

____________________________________________________________

% lisp
Franz Lisp, Opus 38.60
->(defun code (me count)
  (print (list 'in x))
  (setq x (+ 1 x))
  (cond ((greaterp count 1) (funcall me me (sub1 count))))
  (print (list 'out x)))
code
->(defun tester (object count)
  (funcall object object count) (terpri))


The Franz Lisp Manual                              PS2:9-141


tester
->(setq x 0)
0
->(setq z (fclosure '(x) 'code))
fclosure[8]
-> (tester z 3)
(in 0)(in 1)(in 2)(out 3)(out 3)(out 3)
nil
->x
0
____________________________________________________________


              The function _f_c_l_o_s_u_r_e  creates  a  new  object
         that  we  will  call  an  fclosure, (although it is
         actually a vector).  The fclosure contains a  func-
         tional  object, and a set of symbols and values for
         the symbols.  In the above  example,  the  fclosure
         functional object is the function code.  The set of
         symbols and values just contains the symbol `x' and
         zero,  the  value  of  `x'  when  the  fclosure was
         created.

         When an fclosure is funcall'ed:

         1)   The Lisp system lambda binds  the  symbols  in
              the fclosure to their values in the fclosure.

         2)   It continues the  funcall  on  the  functional
              object of the fclosure.

         3)   Finally, it un-lambda binds the symbols in the
              fclosure  and  at  the  same  time  stores the
              current values of the symbols in the fclosure.


              Notice that the fclosure is saving  the  value
         of  the  symbol  `x'.   Each  time  a  fclosure  is
         created, new space  is  allocated  for  saving  the
         values  of the symbols. Thus if we execute fclosure
         again, over the same  function,  we  can  have  two
         independent counters:

____________________________________________________________

-> (setq zz (fclosure '(x) 'code))
fclosure[1]
-> (tester zz 2)
(in 0)(in 1)(out 2)(out 2)
-> (tester zz 2)


PS2:9-142                              The Franz Lisp Manual


(in 2)(in 3)(out 4)(out 4)
-> (tester z 3)
(in 3)(in 4)(in 5)(out 6)(out 6)(out 6)
____________________________________________________________


      _8._4._2.  _u_s_e_f_u_l _f_u_n_c_t_i_o_n_s

              Here are some quick some  summaries  of  func-
         tions  dealing  with  closures.  They are more for-
         mally defined in 2.8.4.  To  recap,  fclosures  are
         made by (_f_c_l_o_s_u_r_e '_l__v_a_r_s '_g__f_u_n_c_o_b_j).  l_vars is a
         list of symbols (not containing nil), g_funcobj  is
         any  object  that can be funcalled.  (Objects which
         can be funcalled, include compiled Lisp  functions,
         lambda  expressions,  symbols,  foreign  functions,
         etc.) In general, if you want a  compiled  function
         to  be closed over a variable, you must declare the
         variable  to  be  special  within   the   function.
         Another example would be:

                     (fclosure '(a b) #'(lambda (x) (plus x a)))

         Here, the #' construction will  make  the  compiler
         compile the lambda expression.

              There are times when you want to  share  vari-
         ables  between  fclosures.  This can be done if the
         fclosures  are  created  at  the  same  time  using
         _f_c_l_o_s_u_r_e-_l_i_s_t.  The function _f_c_l_o_s_u_r_e-_a_l_i_s_t returns
         an assoc list giving the symbols and values in  the
         fclosure.   The  predicate  _f_c_l_o_s_u_r_e_p returns t iff
         its  argument  is  a  fclosure.   Other   functions
         imported  from  Lisp  Machine  Lisp are _s_y_m_e_v_a_l-_i_n-
         _f_c_l_o_s_u_r_e,   _l_e_t-_f_c_l_o_s_e_d,    and    _s_e_t-_i_n-_f_c_l_o_s_u_r_e.
         Lastly,  the function _f_c_l_o_s_u_r_e-_f_u_n_c_t_i_o_n returns the
         function argument.


      _8._4._3.  _i_n_t_e_r_n_a_l _s_t_r_u_c_t_u_r_e

              Currently, closures are  implemented  as  vec-
         tors, with property being the symbol fclosure.  The
         functional object is the first entry.  The  remain-
         ing  entries are structures which point to the sym-
         bols and values for the closure, (with a  reference
         count  to  determine  if  a  recursive  closure  is


The Franz Lisp Manual                              PS2:9-143


         active).


   _8._5.  _f_o_r_e_i_g_n _s_u_b_r_o_u_t_i_n_e_s _a_n_d _f_u_n_c_t_i_o_n_s

           FRANZ LISP has the ability  to  dynamically  load
      object  files  produced by other compilers and to call
      functions defined in those files.  These functions are
      called _f_o_r_e_i_g_n functions.* There are  seven  types  of
      foreign functions.  They are characterized by the type
      of result they  return,  and  by  differences  in  the
      interpretation of their arguments.  They come from two
      families: a group  suited  for  languages  which  pass
      arguments  by  reference  (e.g.  Fortran), and a group
      suited for languages which  pass  arguments  by  value
      (e.g. C).


      There are four types in the first group:

      subroutine
           This does not return anything.  The  Lisp  system
           always returns t after calling a subroutine.

      function
           This returns whatever the function returns.  This
           must  be  a valid Lisp object or it may cause the
           Lisp system to fail.

      integer-function
           This returns an integer  which  the  Lisp  system
           makes into a fixnum and returns.

      real-function
           This returns a double precision real number which
           the Lisp system makes into a flonum and returns.


      There are three types in the second group:

      c-function
           This is like an integer function, except for  its
           different interpretation of arguments.

____________________
9   *This topic is also discussed in Report  PAM-124  of  the
Center  for  Pure  and  Applied  Mathematics,  UCB, entitled
``Parlez-Vous Franz?  An Informal Introduction to  Interfac-
ing Foreign Functions to Franz LISP'', by James R. Larus


9


PS2:9-144                              The Franz Lisp Manual


      double-c-function
           This is like a real-function.

      vector-c-function
           This is for C functions which return a structure.
           The  first  argument  to such functions must be a
           vector (of type vectori), into which  the  result
           is  stored.  The second Lisp argument becomes the
           first argument to the C function, and so on

      A foreign function is accessed through a binary object
      just like a compiled Lisp function.  The difference is
      that the discipline field of a  binary  object  for  a
      foreign  function is a string whose first character is
      given in the following table:


8                     ____________________________
                      letter         type
8                     ________________________________________________________
                        s         subroutine
8                     ____________________________
                        f          function
8                     ____________________________
                        i      integer-function
8                     ____________________________
                        r       real-function.
8                     ____________________________
                        c         c-function
8                     ____________________________
                        v      vector-c-function
8                     ____________________________
                        d      double-c-function
8                     ____________________________
7                     |7|7|7|7|7|7|7|7|7|7|7|


                             |7|7|7|7|7|7|7|7|7|7|7|


                                                 |7|7|7|7|7|7|7|7|7|7|7|


      Two functions  are  provided  for  setting-up  foreign
      functions.   _C_f_a_s_l  loads an object file into the Lisp
      system and sets up one foreign function binary object.
      If there are more than one function in an object file,
      _g_e_t_a_d_d_r_e_s_s can be used to set  up  additional  foreign
      function objects.

           Foreign  functions are  called  just  like  other
      functions,  e.g  (_f_u_n_n_a_m_e _a_r_g_1 _a_r_g_2).  When a function
      in the Fortran group  is  called,  the  arguments  are
      evaluated  and  then  examined.  List, hunk and symbol
      arguments are passed unchanged to  the  foreign  func-
      tion.   Fixnum  and flonum arguments are copied into a
      temporary location and  a  pointer  to  the  value  is
      passed (this is because Fortran uses call by reference
      and it is dangerous to modify the contents of a fixnum
      or  flonum  which  something else might point to).  If
      the argument is an array object, the data field of the
      array  object  is passed to the foreign function (This
      is the easiest way to send large amounts  of  data  to


9


The Franz Lisp Manual                              PS2:9-145


      and receive large amounts of data from a foreign func-
      tion).  If a binary object is an argument,  the  entry
      field of that object is passed to the foreign function
      (the entry field is the address of a function, so this
      amounts to passing a function as an argument).

           When a function in the C group is called,  fixnum
      and flownum arguments are passed by value.  For almost
      all other arguments, the address is merely provided to
      the  C  routine.   The  only exception arises when you
      want to invoke a C routine which  expects  a  ``struc-
      ture''  argument.  Recall that a (rarely used) feature
      of the C language is the ability to pass structures by
      value.   This  copies  the  structure  onto the stack.
      Since the Franz's nearest equivalent to a C  structure
      is  a  vector, we provide an escape clause to copy the
      contents of an immediate-type vector by value.  If the
      property  field  of  a vectori argument, is the symbol
      "value-structure-argument", then the  binary  data  of
      this immediate-type vector is copied into the argument
      list of the C routine.

           The method a foreign function uses to access  the
      arguments   provided  by  Lisp  is  dependent  on  the
      language  of  the  foreign  function.   The  following
      scripts  demonstrate  how  how  Lisp can interact with
      three languages: C, Pascal and Fortran.  C and  Pascal
      have  pointer  types and the first script shows how to
      use pointers to extract information from Lisp objects.
      There  are  two  functions  defined for each language.
      The first (cfoo in C, pfoo in Pascal)  is  given  four
      arguments,  a  fixnum, a flonum-block array, a hunk of
      at least two fixnums and a list of at least  two  fix-
      nums.   To  demonstrate  that  the values were passed,
      each ?foo function prints its arguments (or  parts  of
      them).   The  ?foo  function  then modifies the second
      element of the flonum-block array and returns a  3  to
      Lisp.   The second function (cmemq in C, pmemq in Pas-
      cal) acts just like the Lisp _m_e_m_q function (except  it
      won't work for fixnums whereas the lisp _m_e_m_q will work
      for small fixnums).  In the script, typed input is  in
      _b_o_l_d,  computer output is in roman and comments are in
      _i_t_a_l_i_c.


____________________________________________________________

_T_h_e_s_e _a_r_e _t_h_e _C _c_o_d_e_d _f_u_n_c_t_i_o_n_s
% cat ch8auxc.c
/* demonstration of c coded foreign integer-function */

/* the following will be used to extract fixnums out of a list of fixnums */
struct listoffixnumscell


PS2:9-146                              The Franz Lisp Manual


{    struct listoffixnumscell *cdr;
     int *fixnum;
};

struct listcell
{       struct listcell *cdr;
        int car;
};

cfoo(a,b,c,d)
int *a;
double b[];
int *c[];
struct listoffixnumscell *d;
{
    printf("a: %d, b[0]: %f, b[1]: %f0, *a, b[0], b[1]);
    printf(" c (first): %d   c (second): %d0,
               *c[0],*c[1]);
    printf(" ( %d %d ... ) ", *(d->fixnum), *(d->cdr->fixnum));
    b[1] = 3.1415926;
    return(3);
}

struct listcell *
cmemq(element,list)
int element;
struct listcell *list;
{
   for( ; list && element != list->car ;  list = list->cdr);
   return(list);
}


_T_h_e_s_e _a_r_e _t_h_e _P_a_s_c_a_l _c_o_d_e_d _f_u_n_c_t_i_o_n_s
% cat ch8auxp.p
type    pinteger = ^integer;
        realarray = array[0..10] of real;
        pintarray = array[0..10] of pinteger;
        listoffixnumscell = record
                                cdr  : ^listoffixnumscell;
                                fixnum : pinteger;
                            end;
        plistcell = ^listcell;
        listcell = record
                      cdr : plistcell;
                      car : integer;
                   end;

function pfoo ( var a : integer ;
                var b : realarray;
                var c : pintarray;
                var d : listoffixnumscell) : integer;
begin


The Franz Lisp Manual                              PS2:9-147


   writeln(' a:',a, ' b[0]:', b[0], ' b[1]:', b[1]);
   writeln(' c (first):', c[0]^,' c (second):', c[1]^);
   writeln(' ( ', d.fixnum^, d.cdr^.fixnum^, ' ...) ');
   b[1] := 3.1415926;
   pfoo := 3
end ;

{ the function pmemq looks for the Lisp pointer given as the first argument
  in the list pointed to by the second argument.
  Note that we declare " a : integer " instead of " var a : integer " since
  we are interested in the pointer value instead of what it points to (which
  could be any Lisp object)
}
function pmemq( a : integer; list : plistcell) : plistcell;
begin
 while (list <> nil) and (list^.car <> a) do list := list^.cdr;
 pmemq := list;
end ;


_T_h_e _f_i_l_e_s _a_r_e _c_o_m_p_i_l_e_d
% cc -c ch8auxc.c
1.0u 1.2s 0:15 14% 30+39k 33+20io 147pf+0w
% pc -c ch8auxp.p
3.0u 1.7s 0:37 12% 27+32k 53+32io 143pf+0w


% lisp
Franz Lisp, Opus 38.60
_F_i_r_s_t _t_h_e _f_i_l_e_s _a_r_e _l_o_a_d_e_d _a_n_d _w_e _s_e_t _u_p _o_n_e  _f_o_r_e_i_g_n  _f_u_n_c_-
_t_i_o_n  _b_i_n_a_r_y.  _W_e _h_a_v_e _t_w_o _f_u_n_c_t_i_o_n_s _i_n _e_a_c_h _f_i_l_e _s_o _w_e _m_u_s_t
_c_h_o_o_s_e _o_n_e _t_o _t_e_l_l _c_f_a_s_l _a_b_o_u_t.  _T_h_e _c_h_o_i_c_e _i_s _a_r_b_i_t_r_a_r_y.
-> (cfasl 'ch8auxc.o '_cfoo 'cfoo "integer-function")
/usr/lib/lisp/nld -N -A /usr/local/lisp -T 63000 ch8auxc.o -e _cfoo -o /tmp/Li7055.0  -lc
#63000-"integer-function"
-> (cfasl 'ch8auxp.o '_pfoo 'pfoo "integer-function" "-lpc")
/usr/lib/lisp/nld -N -A /tmp/Li7055.0 -T 63200 ch8auxp.o -e _pfoo -o /tmp/Li7055.1 -lpc -lc
#63200-"integer-function"
_H_e_r_e _w_e _s_e_t _u_p _t_h_e _o_t_h_e_r _f_o_r_e_i_g_n _f_u_n_c_t_i_o_n _b_i_n_a_r_y _o_b_j_e_c_t_s
-> (getaddress '_cmemq 'cmemq "function" '_pmemq 'pmemq "function")
#6306c-"function"
_W_e _w_a_n_t _t_o _c_r_e_a_t_e _a_n_d _i_n_i_t_i_a_l_i_z_e _a_n _a_r_r_a_y  _t_o  _p_a_s_s  _t_o  _t_h_e
_c_f_o_o  _f_u_n_c_t_i_o_n.  _I_n _t_h_i_s _c_a_s_e _w_e _c_r_e_a_t_e _a_n _u_n_n_a_m_e_d _a_r_r_a_y _a_n_d
_s_t_o_r_e _i_t _i_n _t_h_e _v_a_l_u_e _c_e_l_l _o_f _t_e_s_t_a_r_r.  _W_h_e_n  _w_e  _c_r_e_a_t_e  _a_n
_a_r_r_a_y  _t_o  _p_a_s_s  _t_o  _t_h_e  _P_a_s_c_a_l _p_r_o_g_r_a_m _w_e _w_i_l_l _u_s_e _a _n_a_m_e_d
_a_r_r_a_y _j_u_s_t _t_o _d_e_m_o_n_s_t_r_a_t_e _t_h_e _d_i_f_f_e_r_e_n_t _w_a_y _t_h_a_t  _n_a_m_e_d  _a_n_d
_u_n_n_a_m_e_d _a_r_r_a_y_s _a_r_e _c_r_e_a_t_e_d _a_n_d _a_c_c_e_s_s_e_d.
-> (setq testarr (array nil flonum-block 2))
array[2]
-> (store (funcall testarr 0) 1.234)
1.234
-> (store (funcall testarr 1) 5.678)
5.678


PS2:9-148                              The Franz Lisp Manual


-> (cfoo 385 testarr (hunk 10 11 13 14) '(15 16 17))
a: 385, b[0]: 1.234000, b[1]: 5.678000
 c (first): 10   c (second): 11
 ( 15 16 ... )
 3
_N_o_t_e _t_h_a_t _c_f_o_o _h_a_s _r_e_t_u_r_n_e_d _3 _a_s _i_t _s_h_o_u_l_d.  _I_t _a_l_s_o _h_a_d _t_h_e
_s_i_d_e  _e_f_f_e_c_t  _o_f  _c_h_a_n_g_i_n_g  _t_h_e _s_e_c_o_n_d _v_a_l_u_e _o_f _t_h_e _a_r_r_a_y _t_o
_3._1_4_1_5_9_2_6  _w_h_i_c_h _c_h_e_c_k _n_e_x_t.
-> (funcall testarr 1)
3.1415926


_I_n _p_r_e_p_a_r_a_t_i_o_n _f_o_r _c_a_l_l_i_n_g _p_f_o_o _w_e _c_r_e_a_t_e _a_n _a_r_r_a_y.
-> (array test flonum-block 2)
array[2]
-> (store (test 0) 1.234)
1.234
-> (store (test 1) 5.678)
5.678
-> (pfoo 385 (getd 'test) (hunk 10 11 13 14) '(15 16 17))
 a:       385 b[0]:  1.23400000000000E+00 b[1]:  5.67800000000000E+00
 c (first):        10 c (second):        11
 (         15        16 ...)
3
-> (test 1)
3.1415926

 _N_o_w _t_o _t_e_s_t _o_u_t _t_h_e _m_e_m_q'_s
-> (cmemq 'a '(b c a d e f))
(_a _d _e _f)
-> (pmemq 'e '(a d f g a x))
_n_i_l
____________________________________________________________


           The Fortran example will be much shorter since in
      Fortran  you can't follow pointers as you can in other
      languages.  The Fortran function ffoo is  given  three
      arguments:  a  fixnum, a fixnum-block array and a flo-
      num.  These arguments are printed out to  verify  that
      they  made it and then the first value of the array is
      modified.  The function  returns  a  double  precision
      value  which  is  converted  to  a  flonum by lisp and
      printed.  Note that the entry point  corresponding  to
      the  Fortran function ffoo is _ffoo_ as opposed to the
      C and Pascal convention of preceding the name with  an
      underscore.

____________________________________________________________
9

9


The Franz Lisp Manual                              PS2:9-149


% cat ch8auxf.f
        double precision function ffoo(a,b,c)
        integer a,b(10)
        double precision c
        print 2,a,b(1),b(2),c
2       format(' a=',i4,', b(1)=',i5,', b(2)=',i5,' c=',f6.4)
        b(1) = 22
        ffoo = 1.23456
        return
        end
% f77 -c ch8auxf.f
ch8auxf.f:
   ffoo:
0.9u 1.8s 0:12 22% 20+22k 54+48io 158pf+0w
% lisp
Franz Lisp, Opus 38.60
-> (cfasl 'ch8auxf.o '_ffoo_ 'ffoo "real-function" "-lF77 -lI77")
/usr/lib/lisp/nld -N -A /usr/local/lisp -T 63000 ch8auxf.o -e _ffoo_
-o /tmp/Li11066.0 -lF77 -lI77 -lc
#6307c-"real-function"

-> (array test fixnum-block 2)
array[2]
-> (store (test 0) 10)
10
-> (store (test 1) 11)
11
-> (ffoo 385 (getd 'test) 5.678)
 a= 385, b(1)=   10, b(2)=   11 c=5.6780
1.234559893608093
-> (test 0)
22

____________________________________________________________


9

9


                            CHAPTER  9


                        Arrays and Vectors


           Arrays and vectors are two  means  of  expressing
      aggregate  data objects in FRANZ LISP.  Vectors may be
      thought of as sequences of data.  They are intended as
      a  vehicle  for  user-defined data types.  This use of
      vectors is still experimental and subject to revision.
      As  a simple data structure, they are similar to hunks
      and strings.  Vectors are used to implement  closures,
      and  are useful to communicate with foreign functions.
      Both of these topics  were  discussed  in  Chapter  8.
      Later  in this chapter, we describe the current imple-
      mentation of vectors, and will advise the user what is
      most likely to change.

           Arrays in FRANZ LISP provide a programmable  data
      structure  access  mechanism.   One  possible  use for
      FRANZ LISP arrays is to implement Maclisp style arrays
      which  are  simple vectors of fixnums, flonums or gen-
      eral lisp values.  This is described in more detail in
      9.3  but  first  we will describe how array references
      are handled by the lisp system.

           The structure of an  array  object  is  given  in
      1.3.10 and reproduced here for your convenience.


8   _______________________________________________________________
     Subpart name     Get value   Set value          Type

8   ______________________________________________________________________________________________________________________________
    access function   getaccess   putaccess      binary, list
                                                   or symbol
8   _______________________________________________________________
       auxiliary       getaux      putaux           lispval
8   _______________________________________________________________
         data         arrayref     replace    block of contiguous
                                     set            lispval
8   _______________________________________________________________
        length        getlength   putlength         fixnum
8   _______________________________________________________________
         delta        getdelta    putdelta          fixnum
8   _______________________________________________________________
7   |7|7|7|7|7|7|7|7|7|7|7|


                    |7|7|7|7|7|7|7|7|7|7|7|


                                |7|7|7|7|7|7|7|7|7|7|7|


                                            |7|7|7|7|7|7|7|7|7|7|7|


                                                                  |7|7|7|7|7|7|7|7|7|7|7|


9PS2:9-150                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-151


   _9._1.  _g_e_n_e_r_a_l _a_r_r_a_y_s   Suppose the evaluator is  told  to
      evaluate (_f_o_o _a _b) and the function cell of the symbol
      foo contains an  array  object  (which  we  will  call
      foo_arr_obj).   First  the evaluator will evaluate and
      stack the values of _a and _b.  Next it will  stack  the
      array  object  foo_arr_obj.   Finally it will call the
      access function of foo_arr_obj.  The  access  function
      should  be  a lexpr[|-] or a symbol whose function cell
      contains a lexpr.  The access function is  responsible
      for  locating  and  returning  a value from the array.
      The array access function is  free  to  interpret  the
      arguments  as it wishes.  The Maclisp compatible array
      access function which  is  provided  in  the  standard
      FRANZ  LISP  system  interprets  the arguments as sub-
      scripts in the same way as languages like Fortran  and
      Pascal.

           The array access function  will  also  be  called
      upon  to  store  elements  in the array.  For example,
      (_s_t_o_r_e (_f_o_o _a _b) _c) will automatically expand to  (foo
      c  a  b)  and when the evaluator is called to evaluate
      this, it will evaluate the arguments _c, _b and _a.  Then
      it will stack the array object (which is stored in the
      function cell of foo) and call the array access  func-
      tion  with  (now)  four  arguments.   The array access
      function must be able to tell this is a  store  opera-
      tion,  which it can do by checking the number of argu-
      ments it has been given (a  lexpr  can  do  this  very
      easily).


   _9._2.  _s_u_b_p_a_r_t_s _o_f _a_n _a_r_r_a_y _o_b_j_e_c_t   An array  is  created
      by allocating an array object with _m_a_r_r_a_y and  filling
      in the fields.  Certain lisp functions  interpret  the
      values  of the subparts of the array object in special
      ways as described  in  the  following  text.   Placing
      illegal  values  in  these subparts may cause the lisp
      system to fail.


      _9._2._1.  _a_c_c_e_s_s _f_u_n_c_t_i_o_n   The purpose  of  the  access
         function has been described above.  The contents of
         the access function should be  a  lexpr,  either  a
         binary  (compiled  function) or a list (interpreted
         function).  It may also be a symbol whose  function
____________________
9   [|-]A lexpr is a function which accepts any number of  ar-
guments which are evaluated before the function is called.


9


PS2:9-152                              The Franz Lisp Manual


         cell contains a function definition.  This  subpart
         is used by _e_v_a_l, _f_u_n_c_a_l_l, and _a_p_p_l_y when evaluating
         array references.


      _9._2._2.  _a_u_x_i_l_i_a_r_y   This can be used for any  purpose.
         If  it is a list and the first element of that list
         is the symbol unmarked_array then the data  subpart
         will  not  be marked by the garbage collector (this
         is used in the Maclisp compatible array package and
         has  the  potential  for  causing strange errors if
         used incorrectly).


      _9._2._3.  _d_a_t_a   This is either nil or points to a block
         of  data  space  allocated  by  _s_e_g_m_e_n_t  or  _s_m_a_l_l-
         _s_e_g_m_e_n_t.


      _9._2._4.  _l_e_n_g_t_h   This is a fixnum whose value  is  the
         number of elements in the data block.  This is used
         by the garbage collector and by _a_r_r_a_y_r_e_f to  deter-
         mine if your index is in bounds.


      _9._2._5.  _d_e_l_t_a   This is a fixnum whose  value  is  the
         number  of bytes in each element of the data block.
         This will be four for an array of fixnums or  value
         cells,  and eight for an array of flonums.  This is
         used by the garbage collector and _a_r_r_a_y_r_e_f as well.


   _9._3.  _T_h_e _M_a_c_l_i_s_p _c_o_m_p_a_t_i_b_l_e _a_r_r_a_y _p_a_c_k_a_g_e

           A Maclisp style array is similar to what is known
      as  arrays  in other languages: a block of homogeneous
      data elements which is indexed by one or more integers
      called  subscripts.  The data elements can be all fix-
      nums, flonums or general lisp objects.   An  array  is
      created  by  a  call  to the function _a_r_r_a_y or *_a_r_r_a_y.
      The only difference is that *_a_r_r_a_y evaluates its argu-
      ments.   This call: (_a_r_r_a_y _f_o_o _t _3 _5) sets up an array
      called foo of dimensions 3 by 5.  The  subscripts  are
      zero  based.  The first element is (_f_o_o _0 _0), the next
      is (_f_o_o _0 _1) and so on up to (_f_o_o _2 _4).  The  t  indi-
      cates  a  general  lisp  object array which means each
      element of foo can be any type.  Each element  can  be
      any  type  since  all that is stored in the array is a


The Franz Lisp Manual                              PS2:9-153


      pointer to a  lisp  object,  not  the  object  itself.
      _A_r_r_a_y  does  this  by  allocating an array object with
      _m_a_r_r_a_y and then allocating a segment of 15 consecutive
      value  cells  with _s_m_a_l_l-_s_e_g_m_e_n_t and storing a pointer
      to that segment in  the  data  subpart  of  the  array
      object.   The  length  and  delta subpart of the array
      object are filled in (with 15 and 4 respectively)  and
      the  access  function  subpart  is set to point to the
      appropriate  array  access  function.   In  this  case
      there is a special access function for two dimensional
      value cell arrays called arrac-twoD, and  this  access
      function  is  used.   The  auxiliary subpart is set to
      (t 3 5) which describes the  type  of  array  and  the
      bounds of the subscripts. Finally this array object is
      placed in the function cell of the  symbol  foo.   Now
      when (_f_o_o _1 _3) is evaluated, the array access function
      is invoked with three arguments: 1, 3  and  the  array
      object.   From the auxiliary field of the array object
      it gets a description of  the  particular  array.   It
      then determines which element (_f_o_o _1 _3) refers to  and
      uses arrayref to extract that element.  Since this  is
      an  array  of  value cells, what arrayref returns is a
      value cell whose value is what we want, so we evaluate
      the   value  cell  and  return  it  as  the  value  of
      (_f_o_o _1 _3).

           In Maclisp the call (_a_r_r_a_y _f_o_o _f_i_x_n_u_m _2_5) returns
      an  array  whose  data  object is a block of 25 memory
      words.  When fixnums are stored  in  this  array,  the
      actual  numbers  are stored instead of pointers to the
      numbers as is done  in  general  lisp  object  arrays.
      This  is  efficient  under  Maclisp but inefficient in
      FRANZ LISP since every time  a  value  was  referenced
      from an array it had to be copied and a pointer to the
      copy returned to prevent aliasing[|-].  Thus t,  fixnum
      and  flonum  arrays  are  all  implemented in the same
      manner.  This should not affect the  compatibility  of
      Maclisp  and  FRANZ  LISP.  If there is an application
      where a block of fixnums or flonums is required,  then
      the  exact  same effect of fixnum and flonum arrays in
      Maclisp can be  achieved  by  using  fixnum-block  and
      flonum-block  arrays.  Such arrays are required if you
____________________
9   [|-]Aliasing is when two  variables  are  share  the  same
storage  location.   For  example  if  the copying mentioned
weren't done then after (_s_e_t_q _x (_f_o_o _2)) was done, the value
of x and (foo 2) would share the same location.  Then should
the value of (foo 2) change, x's value would change as well.
This  is  considered  dangerous and as a result pointers are
never returned into the data space of arrays.


9


PS2:9-154                              The Franz Lisp Manual


      want to pass a large number of arguments to a  Fortran
      or C coded function and then get answers back.

           The Maclisp compatible array package is just  one
      example  of  how  a general array scheme can be imple-
      mented.  Another type of  array  you  could  implement
      would  be  hashed arrays.  The subscript could be any-
      thing, not just a number.  The access  function  would
      hash  the  subscript  and  use the result to select an
      array element.  With the  generality  of  arrays  also
      comes  extra cost; if you just want a simple aggregate
      of (less than 128) general lisp objects you  would  be
      wise to look into using hunks.


   _9._4.   _v_e_c_t_o_r_s    Vectors  were  invented  to   fix   two
      shortcommings with hunks.  They can be longer than 128
      elements.  They also have a tag associated with  them,
      which is intended to say, for example, "Think of me as
      an _B_l_o_b_i_t."  Thus a vector is an arbitrary sized  hunk
      with a property list.

           Continuing the example, the lisp kernel  may  not
      know how to print out or evaluate _b_l_o_b_i_t_s, but this is
      information which will be common to all  _b_l_o_b_i_t_s.   On
      the  other hand, for each individual blobits there are
      particulars  which  are  likely  to  change,  (height,
      weight,  eye-color).  This is the part that would pre-
      viously have been stored in the individual entries  in
      the hunk, and are stored in the data slots of the vec-
      tor.  Once again we summarize the structure of a  vec-
      tor in tabular form:


8           ________________________________________________
            Subpart name   Get value   Set value    Type

8           ________________________________________________________________________________________________
              datum[_i]       vref        vset      lispval
8           ________________________________________________
              property       vprop     vsetprop    lispval
                                       vputprop
8           ________________________________________________
                size         vsize         -       fixnum
8           ________________________________________________
7           |7|7|7|7|7|7|7|


                         |7|7|7|7|7|7|7|


                                     |7|7|7|7|7|7|7|


                                                 |7|7|7|7|7|7|7|


                                                           |7|7|7|7|7|7|7|


      Vectors are created specifying size and optional  fill
      value using the function (_n_e_w-_v_e_c_t_o_r  'x_size ['g_fill
      ['g_prop]]), or by  initial  values:  (_v_e_c_t_o_r  ['g_val
      ...]).


9


The Franz Lisp Manual                              PS2:9-155


   _9._5.  _a_n_a_t_o_m_y  _o_f  _v_e_c_t_o_r_s    There  are  some  technical
      details about vectors, that the user should know:


      _9._5._1.  _s_i_z_e   The user is not free to alter this.  It
         is noted when the vector is created, and is used by
         the garbage collector.  The garbage collector  will
         coallesce  two free vectors, which are neighbors in
         the heap.  Internally, this is kept as  the  number
         of  bytes of data.  Thus, a vector created by (_v_e_c_-
         _t_o_r 'foo), has a size of 4.


      _9._5._2.  _p_r_o_p_e_r_t_y   Currently, we expect  the  property
         to  be either a symbol, or a list whose first entry
         is a symbol.  The symbols fclosure  and  structure-
         value-argument  are  magic,  and  their  effect  is
         described in Chapter  8.   If  the  property  is  a
         (non-null)  symbol,  the vector will be printed out
         as <symbol>[<size>]. Another case is  if  the  pro-
         perty  is  actually  a (disembodied) property-list,
         which contains a value  for  the  indicator  print.
         The value is taken to be a Lisp function, which the
         printer will invoke with two arguments:  the vector
         and the current output port.  Otherwise, the vector
         will be printed as vector[<size>].  We  have  vague
         (as  yet unimplemented) ideas about similar mechan-
         isms for evaluation  properties.   Users  are  cau-
         tioned  against  putting anything other than nil in
         the property entry of a vector.


      _9._5._3.  _i_n_t_e_r_n_a_l _o_r_d_e_r   In memory, vectors start with
         a  longword containing the size (which is immediate
         data within the vector).  The next cell contains  a
         pointer  to  the property.  Any remaining cells (if
         any) are for data.  Vectors are handled differently
         from  any  other  object  in  FRANZ LISP, in that a
         pointer to a vector is pointer to  the  first  data
         cell,  i.e.  a pointer to the _t_h_i_r_d longword of the
         structure.  This was done for  efficiency  in  com-
         piled   code  and  for  uniformity  in  referencing
         immediate-vectors  (described  below).   The   user
         should  never return a pointer to any other part of
         a vector, as this may cause the  garbage  collector
         to follow an invalid pointer.


9

9


PS2:9-156                              The Franz Lisp Manual


   _9._6.  _i_m_m_e_d_i_a_t_e-_v_e_c_t_o_r_s   Immediate-vectors  are  similar
      to  vectors.   They  differ,  in  that binary data are
      stored in space directly within the vector.  Thus  the
      garbage  collector will preserve the vector itself (if
      used), and will only traverse the property cell.   The
      data  may  be  referenced as longwords, shortwords, or
      even bytes.   Shorts  and  bytes  are  returned  sign-
      extended.   The  compiler  open-codes such references,
      and will avoid  boxing  the  resulting  integer  data,
      where  possible.   Thus, immediate vectors may be used
      for efficiently processing character data.   They  are
      also  useful in storing results from functions written
      in other languages.


8          __________________________________________________
           Subpart name   Get value    Set value     Type

8          ____________________________________________________________________________________________________
             datum[_i]     vrefi-byte   vseti-byte   fixnum
                          vrefi-word   vseti-word   fixnum
                          vrefi-long   vseti-long   fixnum
8          __________________________________________________
             property       vprop       vsetprop    lispval
                                        vputprop
8          __________________________________________________
               size         vsize          -        fixnum
                          vsize-byte                fixnum
                          vsize-word                fixnum
8          __________________________________________________
7          |7|7|7|7|7|7|7|7|7|7|7|


                        |7|7|7|7|7|7|7|7|7|7|7|


                                     |7|7|7|7|7|7|7|7|7|7|7|


                                                  |7|7|7|7|7|7|7|7|7|7|7|


                                                            |7|7|7|7|7|7|7|7|7|7|7|


      To create immediate vectors specifying size  and  fill
      data,  you  can  use  the  functions _n_e_w-_v_e_c_t_o_r_i-_b_y_t_e,
      _n_e_w-_v_e_c_t_o_r_i-_w_o_r_d, or _n_e_w-_v_e_c_t_o_r_i-_l_o_n_g.  You  can  also
      use   the  functions  _v_e_c_t_o_r_i-_b_y_t_e,  _v_e_c_t_o_r_i-_w_o_r_d,  or
      _v_e_c_t_o_r_i-_l_o_n_g.  All of these functions are described in
      chapter 2.


9


                           CHAPTER  10


                        Exception Handling


   _1_0._1.  _E_r_r_s_e_t _a_n_d _E_r_r_o_r _H_a_n_d_l_e_r _F_u_n_c_t_i_o_n_s

           FRANZ LISP allows the user to handle in a  number
      of  ways  the  errors  which arise during computation.
      One way is through the use of the _e_r_r_s_e_t function.  If
      an  error occurs during the evaluation of the _e_r_r_s_e_t's
      first argument, then the locus of control will  return
      to the errset which will return nil (except in special
      cases, such as _e_r_r).  The other method of  error  han-
      dling  is  through an error handler function.  When an
      error occurs, the error handler is called and is given
      as  an argument a description  of the error which just
      occurred.  The error handler may take one of the  fol-
      lowing actions:

       (1)   it could take some drastic action like a  _r_e_s_e_t
             or a _t_h_r_o_w.

       (2)   it could, assuming that the error  is  continu-
             able,  return to the function which noticed the
             error.  The error  handler  indicates  that  it
             wants  to  return  a  value  from  the error by
             returning a list whose  _c_a_r  is  the  value  it
             wants to return.

       (3)   it could decide not to  handle  the  error  and
             return a non-list to indicate this fact.


   _1_0._2.  _T_h_e _A_n_a_t_o_m_y _o_f _a_n _e_r_r_o_r

           Each error is described by a list of these items:

       (1)   error type - This is a symbol  which  indicates
             the  general classification of the error.  This
             classification  may  determine  which  function
             handles this error.

       (2)   unique id - This is a  fixnum  unique  to  this
             error.

9

9The Franz Lisp Manual                              PS2:9-157


PS2:9-158                              The Franz Lisp Manual


       (3)   continuable - If  this  is  non-nil  then  this
             error  is continuable.  There are some who feel
             that every error should be continuable and  the
             reason that some (in fact most) errors in FRANZ
             LISP are not continuable is due to the laziness
             of the programmers.

       (4)   message string - This is a symbol  whose  print
             name is  a message describing the error.

       (5)   data - There may be from  zero  to  three  lisp
             values  which  help  describe  this  particular
             error.  For example, the unbound variable error
             contains  one  datum  value,  the  symbol whose
             value is unbound.   The  list  describing  that
             error might look like:
                (ER%misc 0 t |Unbound Variable:| foobar)


   _1_0._3.  _E_r_r_o_r _h_a_n_d_l_i_n_g _a_l_g_o_r_i_t_h_m

           This is the sequence of operations which is  done
      when an error occurs:

       (1)   If the symbol _E_R%_a_l_l has a non nil  value  then
             this  value  is  the  name  of an error handler
             function.   That  function  is  called  with  a
             description  of  the  error.   If that function
             returns (and of course it may  choose  not  to)
             and  the value is a list and this error is con-
             tinuable, then we return the _c_a_r of the list to
             the  function  which called the error.  Presum-
             ably the function  will use this value to retry
             the operation.  On the other hand, if the error
             handler returns a non list, then it has  chosen
             not  to handle this error, so  we go on to step
             (2).  Something special happens before we  call
             the  _E_R%_a_l_l error handler which does not happen
             in any of the  other  cases  we  will  describe
             below.  To help insure that we don't get infin-
             itely recursive errors  if _E_R%_a_l_l is set  to  a
             bad  value,  the  value of _E_R%_a_l_l is set to nil
             before the handler is called.  Thus it  is  the
             responsibility  of the _E_R%_a_l_l handler to `reen-
             able' itself by storing its name in _E_R%_a_l_l.

       (2)   Next the specific error handler for the type of
             error  which  just  occurred is called  (if one
             exists) to see if it wants to handle the error.
             The  names  of  the  handlers  for the specific
             types of errors are stored as the values of the
             symbols whose names are the types.  For example


The Franz Lisp Manual                              PS2:9-159


             the handler for miscellaneous errors is  stored
             as the value of _E_R%_m_i_s_c.  Of course, if _E_R%_m_i_s_c
             has a value of nil,  then  there  is  no  error
             handler  for  this  type  of error.  Appendix B
             contains list of all error types.  The  process
             of  classifying  the errors is not complete and
             thus most errors are lumped  into  the  ER%misc
             category.   Just  as  in  step  (1),  the error
             handler function may choose not to  handle  the
             error  by  returning a non-list, and then we go
             to step (3).

       (3)   Next a check is made to  see  if  there  is  an
             _e_r_r_s_e_t  surrounding  this  error.   If  so  the
             second argument to the _e_r_r_s_e_t call is examined.
             If  the second argument was not given or is non
             nil then the error message associated with this
             error is printed.  Finally  the stack is popped
             to the context  of  the  _e_r_r_s_e_t  and  then  the
             _e_r_r_s_e_t  returns nil.  If there was no _e_r_r_s_e_t we
             go to step (4).

       (4)   If the symbol _E_R%_t_p_l has a value then it is the
             name  of  an error handler which is called in a
             manner similar to that discussed above.  If  it
             chooses  not to handle the error, we go to step
             (5).

       (5)   At this point it has been determined  that  the
             user  doesn't  want to handle this error.  Thus
             the error message is printed out and a _r_e_s_e_t is
             done  to  send  the flow of control to the top-
             level.

           To summarize the error handling system:  When  an
      error occurs, you have two chances to handle it before
      the search for an _e_r_r_s_e_t is done.  Then, if  there  is
      no  _e_r_r_s_e_t,  you  have  one  more chance to handle the
      error before control jumps to the  top  level.   Every
      error  handler  works  in  the same way: It is given a
      description of the error (as described in the previous
      section).   It  may or may not return.  If it returns,
      then it returns either a list or a  non-list.   If  it
      returns  a list and the error is continuable, then the
      _c_a_r of the list is  returned  to  the  function  which
      noticed  the  error.   Otherwise the error handler has
      decided not to handle the error and we go on to  some-
      thing else.


9

9


PS2:9-160                              The Franz Lisp Manual


   _1_0._4.  _D_e_f_a_u_l_t _a_i_d_s

           There are two standard error handlers  which will
      probably handle the needs of most users.  One of these
      is the lisp coded function _b_r_e_a_k-_e_r_r-_h_a_n_d_l_e_r which  is
      the  default  value  of  _E_R%_t_p_l.   Thus when all other
      handlers have ignored an error, _b_r_e_a_k-_e_r_r-_h_a_n_d_l_e_r will
      take over.  It will print out the error message and go
      into a read-eval-print loop.  The other standard error
      handler   is   _d_e_b_u_g-_e_r_r-_h_a_n_d_l_e_r.    This  handler  is
      designed to be connected to  _E_R%_a_l_land  is  useful  if
      your  program  uses _e_r_r_s_e_t and you want to look at the
      error  before it is thrown up to the _e_r_r_s_e_t.


   _1_0._5.  _A_u_t_o_l_o_a_d_i_n_g

           When _e_v_a_l, _a_p_p_l_y or _f_u_n_c_a_l_l are told to  call  an
      undefined  function,  an  ER%undef  error is signaled.
      The default handler  for  this  error  is  _u_n_d_e_f-_f_u_n_c-
      _h_a_n_d_l_e_r.   This  function  checks the property list of
      the undefined function for the indicator autoload.  If
      present,  the  value  of  that indicator should be the
      name of the file which contains the definition of  the
      undefined  function.  _U_n_d_e_f-_f_u_n_c-_h_a_n_d_l_e_r will load the
      file and check if it has defined  the  function  which
      caused  the  error.  If it has, the error handler will
      return and the computation will  continue  as  if  the
      error did not occur.  This provides a way for the user
      to tell the lisp system about the location of commonly
      used functions.  The trace package sets up an autoload
      property to point to /usr/lib/lisp/trace.


   _1_0._6.  _I_n_t_e_r_r_u_p_t _p_r_o_c_e_s_s_i_n_g

           The  UNIX  operating  system  provides  one  user
      interrupt character which defaults to ^C.[|-] The  user
      may  select  a  lisp function to run when an interrupt
      occurs.  Since this interrupt could occur at any time,
      and  in  particular  could  occur  at  a time when the
      internal stack pointers were in an inconsistent state,
      the processing of the interrupt may be delayed until a
      safe time.  When the first ^C is typed, the lisp  sys-
      tem  sets a flag that an interrupt has been requested.
____________________
9   [|-]Actually there are two but the lisp  system  does  not
allow you to catch the QUIT interrupt.


9


The Franz Lisp Manual                              PS2:9-161


      This flag is  checked at safe places within the inter-
      preter  and in the _q_l_i_n_k_e_r function.  If the lisp sys-
      tem doesn't respond to the first ^C, another ^C should
      be  typed.  This will cause all of the transfer tables
      to be cleared forcing all calls from compiled code  to
      go  through  the  _q_l_i_n_k_e_r function where the interrupt
      flag will  be  checked.   If  the  lisp  system  still
      doesn't  respond,  a  third ^C will cause an immediate
      interrupt.  This interrupt will not necessarily be  in
      a  safe place so the user should _r_e_s_e_t the lisp system
      as soon as possible.


9

9


                           CHAPTER  11


                 The Joseph Lister Trace Package


           The Joseph Lister[|-] Trace package is  an  impor-
      tant tool for the interactive debugging of a Lisp pro-
      gram.  It allows you to examine selected  calls  to  a
      function  or  functions, and optionally to stop execu-
      tion of the Lisp program  to  examine  the  values  of
      variables.

           The trace package  is  a  set  of  Lisp  programs
      located  in  the  Lisp program library (usually in the
      file /usr/lib/lisp/trace.l).   Although  not  normally
      loaded  in the Lisp system, the package will be loaded
      in when the first call to _t_r_a_c_e is made.

(trace [ls_arg1 ...])

     WHERE:   the form of the ls_arg_i is described below.

     RETURNS: a list of the  function  sucessfully  modified
              for  tracing.   If  no  arguments are given to
              _t_r_a_c_e, a list of all functions currently being
              traced is returned.

     SIDE EFFECT: The function definitions of the  functions
                  to trace are modified.


The ls_arg_i can have one of the following forms:


  foo - when foo is entered and exited, the  trace  informa-
       tion will be printed.


  (foo break) - when foo is entered  and  exited  the  trace
       information  will  be  printed.  Also, just after the
       trace information for foo is printed upon entry,  you
       will  be put in  a special break loop.  The prompt is
       `T>' and you may type any Lisp  expression,  and  see
       its  value printed.  The _ith argument to the function
____________________
9   [|-]_L_i_s_t_e_r, _J_o_s_e_p_h     1st Baron  Lister  of  Lyme  Regis,
1827-1912; English surgeon: introduced antiseptic surgery.


9PS2:9-162                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-163


       just called can be accessed as (arg _i).  To leave the
       trace  loop, just type ^D or (tracereturn) and execu-
       tion will continue.  Note that ^D will work  only  on
       UNIX systems.


  (foo if expression) - when foo is entered and the  expres-
       sion evaluates to non-nil, then the trace information
       will be printed for both exit and entry.  If  expres-
       sion evaluates to nil, then no trace information will
       be printed.


  (foo ifnot expression) -  when  foo  is  entered  and  the
       expression  evaluates to nil, then the trace informa-
       tion will be printed for both  entry  and  exit.   If
       both  if and _i_f_n_o_t are specified, then the _i_f expres-
       sion must evaluate to non nil AND the  _i_f_n_o_t  expres-
       sion  must  evaluate to nil for the trace information
       to be printed out.


  (foo evalin expression) - when foo is  entered  and  after
       the  entry  trace  information is printed, expression
       will be evaluated. Exit  trace  information  will  be
       printed when foo exits.


  (foo evalout expression) -  when  foo  is  entered,  entry
       trace  information  will be printed.  When foo exits,
       and before the exit  trace  information  is  printed,
       expression will be evaluated.


  (foo evalinout expression) - this has the same  effect  as
       (trace (foo evalin expression evalout expression)).


  (foo lprint) - this tells _t_r_a_c_e to use the  level  printer
       when  printing  the arguments to and the result of  a
       call to foo.  The level printer prints only  the  top
       levels  of  list structure. Any structure below three
       levels is printed as a &.  This allows you  to  trace
       functions with massive arguments or results.


          The following trace options  permit  one  to  have
     greater control over each action which takes place when
     a function is traced.  These options are only meant  to
     be used by people who need special hooks into the trace
     package.  Most people should skip reading this section.
9

9


PS2:9-164                              The Franz Lisp Manual


  (foo traceenter tefunc) - this tells _t_r_a_c_e that the  func-
       tion  to  be  called  when  foo is entered is tefunc.
       tefunc should be a lambda of two arguments, the first
       argument  will  be  bound to the name of the function
       being traced, foo in this case.  The second  argument
       will  be  bound to the list of arguments to which foo
       should be applied.  The function tefunc should  print
       some  sort  of "entering foo" message.  It should not
       apply foo to the arguments,  however.  That  is  done
       later on.


  (foo traceexit txfunc) - this tells _t_r_a_c_e that  the  func-
       tion  to  be  called  when  foo  is exited is txfunc.
       txfunc should be a lambda of two arguments, the first
       argument  will  be  bound to the name of the function
       being traced, foo in this case.  The second  argument
       will  be bound to the result of the call to foo.  The
       function txfunc should print some  sort  of  "exiting
       foo" message.


  (foo evfcn evfunc) - this tells _t_r_a_c_e that the form evfunc
       should  be  evaluated to get the value of foo applied
       to its arguments. This option is a bit different from
       the  other  special options since evfunc will usually
       be an expression, not just the name  of  a  function,
       and  that  expression will be specific to the evalua-
       tion of  function  foo.   The  argument  list  to  be
       applied will be available as T-arglist.


  (foo printargs prfunc) - this tells _t_r_a_c_e to  used  prfunc
       to print the arguments  to be applied to the function
       foo.  prfunc should be a lambda of one argument.  You
       might  want  to use this option if you wanted a print
       function which could  handle  circular  lists.   This
       option  will work only if you do not specify your own
       _t_r_a_c_e_e_n_t_e_r function.  Specifying the option _l_p_r_i_n_t is
       just  a simple way of changing the printargs function
       to the level printer.


  (foo printres prfunc) - this tells _t_r_a_c_e to use prfunc  to
       print the result of evaluating foo.  prfunc should be
       a lambda of one argument.  This option will work only
       if  you  do  not specify your own _t_r_a_c_e_e_x_i_t function.
       Specifying the option _l_p_r_i_n_t changes printres to  the
       level printer.


9

9


The Franz Lisp Manual                              PS2:9-165


          You may specify more  than  one  option  for  each
     function traced. For example:

     (_t_r_a_c_e (_f_o_o _i_f (_e_q _3 (_a_r_g _1)) _b_r_e_a_k _l_p_r_i_n_t) (_b_a_r _e_v_a_l_i_n
     (_p_r_i_n_t _x_y_z_z_y)))

     This tells _t_r_a_c_e to trace two more functions,  foo  and
     bar.   Should  foo be called with the first argument _e_q
     to 3, then the entering foo  message  will  be  printed
     with  the  level  printer.   Next it will enter a trace
     break loop, allowing you to evaluate any  lisp  expres-
     sions.  When you exit the trace break loop, foo will be
     applied to its arguments and the resulting  value  will
     be printed, again using the level printer.  Bar is also
     traced, and each time bar is entered, an  entering  bar
     message  will  be  printed  and then the value of xyzzy
     will be printed.  Next bar will be applied to its argu-
     ments  and  the  result  will  be printed.  If you tell
     _t_r_a_c_e to trace a function which is already  traced,  it
     will  first  _u_n_t_r_a_c_e  it.   Thus if you want to specify
     more than one trace option for a function, you must  do
     it all at once.  The following is _n_o_t equivalent to the
     preceding call to _t_r_a_c_e for foo:

     (_t_r_a_c_e (_f_o_o  _i_f  (_e_q  _3  (_a_r_g  _1)))  (_f_o_o  _b_r_e_a_k)  (_f_o_o
     _l_p_r_i_n_t))

     In this example, only the last option, lprint, will  be
     in effect.

          If the symbol $tracemute is given a non nil value,
     printing  of  the  function name and arguments on entry
     and exit will be surpressed.  This is particularly use-
     ful  if  the  function you are tracing fails after many
     calls to it.  In this case  you  would  tell  _t_r_a_c_e  to
     trace  the function, set $tracemute to t, and begin the
     computation.  When an error occurs  you  can  use  _t_r_a_-
     _c_e_d_u_m_p to print out the current trace frames.

          Generally the trace package has its  own  internal
     names  for  the the lisp functions it uses, so that you
     can feel free to trace system functions like  _c_o_n_d  and
     not worry about adverse interaction with the actions of
     the trace package.  You can trace any type of function:
     lambda,  nlambda,  lexpr  or  macro whether compiled or
     interpreted and you can  even  trace  array  references
     (however  you  should  not attempt to store in an array
     which has been traced).

          When tracing compiled code keep in mind that  many
     function  calls  are  translated  directly  to  machine
     language  or other equivalent  function calls.  A  full
     list of open coded functions is listed at the beginning


PS2:9-166                              The Franz Lisp Manual


     of  the  liszt  compiler  source.   _T_r_a_c_e  will  do   a
     (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l)  to  insure that the new traced
     definitions it defines are called instead  of  the  old
     untraced  ones.  You may notice that compiled code will
     run slower after this is done.

(traceargs s_func [x_level])

     WHERE:   if x_level is missing it is assumed to be 1.

     RETURNS: the arguments to the x_level_t_h call to  traced
              function s_func are returned.

(tracedump)

     SIDE EFFECT: the  currently  active  trace  frames  are
                  printed  on  the terminal.  returns a list
                  of functions untraced.

(untrace [s_arg1 ...])

     RETURNS: a list of the functions which were untraced.

     NOTE: if no arguments  are  given,  all  functions  are
           untraced.

     SIDE EFFECT: the old function definitions of all traced
                  functions  are restored except in the case
                  where it appears that the current  defini-
                  tion  of  a  function  was  not created by
                  trace.


9

9


                           CHAPTER  12


                    Liszt - the lisp compiler


   _1_2._1.  _G_e_n_e_r_a_l _s_t_r_a_t_e_g_y _o_f _t_h_e _c_o_m_p_i_l_e_r

           The purpose of the lisp compiler,  Liszt,  is  to
      create  an  object  module which when brought into the
      lisp system using _f_a_s_l will have the  same  effect  as
      bringing in the corresponding lisp coded source module
      with _l_o_a_d with one important exception, functions will
      be  defined  as sequences of machine language instruc-
      tions, instead of lisp S-expressions.  Liszt is not  a
      function compiler, it is a _f_i_l_e compiler.  Such a file
      can contain more than  function  definitions;  it  can
      contain  other  lisp S-expressions which are evaluated
      at load time.  These other S-expressions will also  be
      stored in the object module produced by Liszt and will
      be evaluated at fasl time.

           As is almost universally true of Lisp  compilers,
      the  main  pass of Liszt is written in Lisp.  A subse-
      quent pass is the assembler,  for  which  we  use  the
      standard UNIX assembler.


   _1_2._2.  _R_u_n_n_i_n_g _t_h_e _c_o_m_p_i_l_e_r

           The compiler is normally run in this manner:
      % liszt foo
      will compile the file foo.l or foo (the preferred  way
      to indicate a lisp source file is to end the file name
      with `.l').  The result of  the  compilation  will  be
      placed  in  the  file  foo.o   if no fatal errors were
      detected.  All messages which Liszt  generates  go  to
      the  standard  output.  Normally each function name is
      printed  before  it  is  compiled   (the   -q   option
      suppresses this).


   _1_2._3.  _S_p_e_c_i_a_l _f_o_r_m_s

           Liszt makes one pass over  the  source  file.  It
      processes each form in this way:
9

9The Franz Lisp Manual                              PS2:9-167


PS2:9-168                              The Franz Lisp Manual


      _1_2._3._1.  _m_a_c_r_o _e_x_p_a_n_s_i_o_n

              If the form is a macro invocation (i.e it is a
         list  whose  car is a symbol whose function binding
         is  a  macro),  then  that  macro   invocation   is
         expanded.   This  is  repeated  until the top level
         form is not a macro invocation.  When Liszt begins,
         there are already some macros defined, in fact some
         functions (such as defun) are actually macros.  The
         user  may  define  his  own  macros as well.  For a
         macro to be used it must be  defined  in  the  Lisp
         system in which Liszt runs.


      _1_2._3._2.  _c_l_a_s_s_i_f_i_c_a_t_i_o_n

              After all macro expansion is done, the form is
         classified according to its _c_a_r (if the form is not
         a list, then it is classified as an _o_t_h_e_r).


         _1_2._3._2._1.  _e_v_a_l-_w_h_e_n

                 The   form   of   eval-when    is    (_e_v_a_l-
            _w_h_e_n (_t_i_m_e_1 _t_i_m_e_2 ...) _f_o_r_m_1 _f_o_r_m_2 ...)    where
            the time_i are one of  _e_v_a_l,  _c_o_m_p_i_l_e,  or  _l_o_a_d.
            The  compiler examines the form_i in sequence and
            the action taken depends on what is in the  time
            list.   If  _c_o_m_p_i_l_e is in the list then the com-
            piler will invoke _e_v_a_l on each form_i as it exam-
            ines  it.   If _l_o_a_d is in the list then the com-
            pile will recursively  call  itself  to  compile
            each form_i as it examines it.  Note that if _c_o_m_-
            _p_i_l_e and _l_o_a_d are in the  time  list,  then  the
            compiler  will  both  evaluate  and compile each
            form.  This is useful if you need a function  to
            be  defined in the compiler at both compile time
            (perhaps to aid macro expansion) and at run time
            (after the file is _f_a_s_led in).


         _1_2._3._2._2.  _d_e_c_l_a_r_e

                 Declare  is  used  to  provide  information
            about  functions  and variables to the compiler.
            It   is   (almost)    equivalent    to    (_e_v_a_l-
            _w_h_e_n (_c_o_m_p_i_l_e) ...).   You may declare functions
            to  be  one  of  three  types:  lambda  (*expr),
            nlambda  (*fexpr), lexpr (*lexpr).  The names in
            parenthesis  are  the  Maclisp  names  and   are


The Franz Lisp Manual                              PS2:9-169


            accepted  by  the compiler as well (and not just
            when the compiler is in  Maclisp  mode).   Func-
            tions  are  assumed to be lambdas until they are
            declared otherwise or are  defined  differently.
            The  compiler treats calls to lambdas and lexprs
            equivalently, so you needn't worry about declar-
            ing  lexprs  either.  It is important to declare
            nlambdas or define  them  before  calling  them.
            Another attribute you can declare for a function
            is localf which makes the function  `local'.   A
            local function's name is known only to the func-
            tions  defined  within  the  file  itself.   The
            advantage  of a local function is that is can be
            entered and exited very quickly and it can  have
            the  same name as a function in another file and
            there will be no name conflict.

                 Variables may be declared special or unspe-
            cial.   When  a special variable is lambda bound
            (either in a lambda, prog or do expression), its
            old  value  is  stored  away  on a stack for the
            duration of the lambda, prog or  do  expression.
            This  takes  time  and  is  often not necessary.
            Therefore the default classification  for  vari-
            ables  is  unspecial.  Space for unspecial vari-
            ables is dynamically allocated on a  stack.   An
            unspecial  variable  can  only  be accessed from
            within the function where it is created  by  its
            presence  in  a  lambda,  prog  or do expression
            variable list.  It is possible to  declare  that
            all  variables  are  special  as  will  be shown
            below.

                 You may declare any  number  of  things  in
            each declare statement.  A sample declaration is
            (_d_e_c_l_a_r_e
                 (_l_a_m_b_d_a _f_u_n_c_1 _f_u_n_c_2)
                 (*_f_e_x_p_r _f_u_n_c_3)
                 (*_l_e_x_p_r _f_u_n_c_4)
                 (_l_o_c_a_l_f _f_u_n_c_5)
                 (_s_p_e_c_i_a_l _v_a_r_1 _v_a_r_2 _v_a_r_3)
                 (_u_n_s_p_e_c_i_a_l _v_a_r_4))

                 You may also declare all  variables  to  be
            special  with  (_d_e_c_l_a_r_e (_s_p_e_c_i_a_l_s _t)).   You may
            declare that macro definitions  should  be  com-
            piled  as  well  as evaluated at compile time by
            (_d_e_c_l_a_r_e (_m_a_c_r_o_s _t)).  In fact, as was mentioned
            above,    declare    is    much    like   (_e_v_a_l-
            _w_h_e_n (_c_o_m_p_i_l_e) ...).  Thus if the compiler  sees
            (_d_e_c_l_a_r_e (_f_o_o _b_a_r))  and foo is defined, then it
            will evaluate (_f_o_o _b_a_r).  If foo is not  defined
            then an undefined declare attribute warning will


PS2:9-170                              The Franz Lisp Manual


            be issued.


         _1_2._3._2._3.  (_p_r_o_g_n '_c_o_m_p_i_l_e form1 form2 ... formn)

                 When the compiler sees this it simply  com-
            piles  form1  through  formn as if they too were
            seen at top level.  One use for this is to allow
            a  macro  at  top-level to expand into more than
            one function definition for the compiler to com-
            pile.


         _1_2._3._2._4.  _i_n_c_l_u_d_e/_i_n_c_l_u_d_e_f

                 _I_n_c_l_u_d_e and _i_n_c_l_u_d_e_f cause another file  to
            be  read  and  compiled  by  the  compiler.  The
            result is the same as if the included file  were
            textually  inserted into the original file.  The
            only difference between _i_n_c_l_u_d_e and _i_n_c_l_u_d_e_f  is
            that  include  doesn't evaluate its argument and
            includef does.  Nested includes are allowed.


         _1_2._3._2._5.  _d_e_f

                 A def form is used to  define  a  function.
            The  macros  _d_e_f_u_n  and _d_e_f_m_a_c_r_o expand to a def
            form.   If  the  function  being  defined  is  a
            lambda,  nlambda or lexpr then the compiler con-
            verts the  lisp  definition  to  a  sequence  of
            machine  language instructions.  If the function
            being defined is a macro, then the compiler will
            evaluate the definition, thus defining the macro
            withing the running Lisp compiler.  Furthermore,
            if  the  variable  _m_a_c_r_o_s  is  set  to a non nil
            value, then the macro definition  will  also  be
            translated  to machine language and thus will be
            defined when the object file is fasled in.   The
            variable    _m_a_c_r_o_s    is    set    to    t    by
            (_d_e_c_l_a_r_e (_m_a_c_r_o_s _t)).

                 When a function or macro definition is com-
            piled,  macro  expansion is done whenever possi-
            ble.  If the compiler can determine that a  form
            would  be evaluated if this function were inter-
            preted then it will macro expand  it.   It  will
            not  macro  expand arguments to a nlambda unless
            the characteristics of the nlambda is known  (as
            is  the  case  with  _c_o_n_d).  The map functions (


The Franz Lisp Manual                              PS2:9-171


            _m_a_p, _m_a_p_c, _m_a_p_c_a_r, and so on) are expanded to  a
            _d_o statement.  This allows the first argument to
            the map function to be a lambda expression which
            references local variables of the function being
            defined.


         _1_2._3._2._6.  _o_t_h_e_r _f_o_r_m_s

                 All other forms are simply  stored  in  the
            object  file  and are evaluated when the file is
            _f_a_s_led in.


   _1_2._4.  _U_s_i_n_g _t_h_e _c_o_m_p_i_l_e_r

           The previous section describes exactly  what  the
      compiler  does  with  its  input.  Generally you won't
      have to worry about all that  detail  as  files  which
      work  interpreted  will work compiled.  Following is a
      list of steps you should follow to insure that a  file
      will compile correctly.

      [1]  Make sure all macro definitions precede their use
           in  functions or other macro definitions.  If you
           want the macros to be around when you _f_a_s_l in the
           object  file you should include this statement at
           the beginning of the file: (_d_e_c_l_a_r_e (_m_a_c_r_o_s _t))

      [2]  Make sure all nlambdas are  defined  or  declared
           before  they  are  used.   If  the compiler comes
           across a call to a function which  has  not  been
           defined  in  the  current  file,  which  does not
           currently have a function binding, and whose type
           has  not  been  declared then it will assume that
           the function needs  its arguments evaluated (i.e.
           it  is  a lambda or lexpr) and will generate code
           accordingly.  This means that you do not have  to
           declare  nlambda functions like _s_t_a_t_u_s since they
           have an nlambda function binding.

      [3]  Locate all variables which are used for  communi-
           cating values between functions.  These variables
           must be declared special at the  beginning  of  a
           file.   In most cases there won't be many special
           declarations but if you fail to declare  a  vari-
           able  special  that  should be, the compiled code
           could fail in mysterious ways.  Let's look  at  a
           common  problem, assume that a file contains just
           these three lines:
9

9


PS2:9-172                              The Franz Lisp Manual


           (_d_e_f _a_a_a (_l_a_m_b_d_a (_g_l_o_b _l_o_c) (_b_b_b _l_o_c)))
           (_d_e_f _b_b_b (_l_a_m_b_d_a (_m_y_l_o_c) (_a_d_d _g_l_o_b _m_y_l_o_c)))
           (_d_e_f _c_c_c (_l_a_m_b_d_a (_g_l_o_b _l_o_c) (_b_b_b _l_o_c)))


           We can see that if we load in these  two  defini-
           tions then (aaa 3 4) is the same as (add 3 4) and
           will give us 7.  Suppose we compile the file con-
           taining  these  definitions.  When Liszt compiles
           aaa, it will assume that both glob  and  loc  are
           local  variables  and  will allocate space on the
           temporary stack for  their  values  when  aaa  is
           called.   Thus  the values of the local variables
           glob and loc will not affect the  values  of  the
           symbols  glob  and  loc  in the Lisp system.  Now
           Liszt moves on to function bbb.  Myloc is assumed
           to  be local.  When it sees the add statement, it
           find a reference to a variable called glob.  This
           variable is not a local variable to this function
           and therefore glob must refer to the value of the
           symbol  glob.   Liszt  will automatically declare
           glob to be special and it will print a warning to
           that  effect.   Thus subsequent uses of glob will
           always refer to the symbol glob.  Next Liszt com-
           piles ccc and treats glob as a special and loc as
           a local.  When the object file is _f_a_s_l'ed in, and
           (ccc  3  4) is evaluated, the symbol glob will be
           lambda bound to 3 bbb will  be  called  and  will
           return 7.  However (aaa 3 4) will fail since when
           bbb is called, glob will be unbound.  What should
           be done here is to put (_d_e_c_l_a_r_e (_s_p_e_c_i_a_l _g_l_o_b) at
           the beginning of the file.

      [4]  Make sure that all calls to _a_r_g  are  within  the
           lexpr  whose arguments they reference.  If _f_o_o is
           a compiled lexpr and it calls _b_a_r then _b_a_r cannot
           use  _a_r_g  to get at _f_o_o's arguments.  If both _f_o_o
           and _b_a_r are interpreted this will  work  however.
           The  macro _l_i_s_t_i_f_y can be used to put all of some
           of a lexprs arguments in a list which then can be
           passed to other functions.


   _1_2._5.  _C_o_m_p_i_l_e_r _o_p_t_i_o_n_s

           The compiler recognizes a number of options which
      are  described  below.  The options are typed anywhere
      on the command line preceded by  a  minus  sign.   The
      entire   command  line  is  scanned  and  all  options
      recorded before any action is taken.  Thus
      % liszt -mx foo
      % liszt -m -x foo


The Franz Lisp Manual                              PS2:9-173


      % liszt foo -mx
      are all equivalent. Before scanning the  command  line
      for  options,  liszt  looks for in the environment for
      the variable LISZT, and if found scans its value as if
      it  was  a  string  of  options.   The  meaning of the
      options are:

      C    The assembler language output of the compiler  is
           commented.   This  is  useful  when debugging the
           compiler and is not normally done since it  slows
           down compilation.

      I    The next command line  argument  is  taken  as  a
           filename, and loaded prior to compilation.

      e    Evaluate the next argument on  the  command  line
           before starting compilation.  For example
           % liszt -e '(setq foobar "foo string")' foo
           will evaluate the above s-expression.  Note  that
           the  shell  requires  that  the arguments be sur-
           rounded by single quotes.

      i    Compile this program in  interlisp  compatibility
           mode. This is not implemented yet.

      m    Compile this program in Maclisp mode.  The reader
           syntax  will be changed to the Maclisp syntax and
           a file of macro definitions  will  be  loaded  in
           (usually   named  /usr/lib/lisp/machacks).   This
           switch brings us sufficiently close to Maclisp to
           allow us to compile Macsyma, a large Maclisp pro-
           gram.  However Maclisp is a moving target and  we
           can't  guarantee  that this switch will allow you
           to compile any given program.

      o    Select a different object or  assembler  language
           file name.  For example
           % liszt foo -o xxx.o
           will compile foo and into xxx.o  instead  of  the
           default foo.o, and
           % liszt bar -S -o xxx.s
           will compile to  assembler  language  into  xxx.s
           instead of bar.s.

      p    place profiling code at  the  beginning  of  each
           non-local  function.   If the lisp system is also
           created with profiling in it, this  allows  func-
           tion  calling  frequency  to  be  determined (see
           _p_r_o_f(_1))

      q    Run in quiet mode. The names of  functions  being
           compiled and various "Note"'s are not printed.
9

9


PS2:9-174                              The Franz Lisp Manual


      Q    print compilation statistics and warn of  strange
           constructs.  This  is the inverse of the q switch
           and is the default.

      r    place bootstrap code  at  the  beginning  of  the
           object  file,  which when the object file is exe-
           cuted will cause a lisp system to be invoked  and
           the  object  file  _f_a_s_led  in.  This  is known as
           `autorun' and is described below.

      S    Create an assembler language file only.
           % liszt -S foo
           will create  the  file  assembler  language  file
           foo.s  and  will  not attempt to assemble it.  If
           this  option  is  not  specified,  the  assembler
           language  file  will be put in the temporary disk
           area under a automatically generated  name  based
           on the lisp compiler's process id.  Then if there
           are no compilation errors, the assembler will  be
           invoked to assemble the file.

      T    Print the assembler language output on the  stan-
           dard  output file.  This is useful when debugging
           the compiler.

      u    Run in UCI-Lisp mode.  The  character  syntax  is
           changed to that of UCI-Lisp and a UCI-Lisp compa-
           tibility package of macros is read in.

      w    Suppress warning messages.

      x    Create an cross reference file.
           % liszt -x foo
           not only compiles foo into foo.o  but  also  gen-
           erates  the file foo.x .  The file foo.x  is lisp
           readable and lists for each  function  all  func-
           tions  which  that function could call.  The pro-
           gram lxref reads one or more of these ".x"  files
           and  produces  a  human  readable cross reference
           listing.


   _1_2._6.  _a_u_t_o_r_u_n

           The object  file which liszt writes does not con-
      tain  all the functions necessary to run the lisp pro-
      gram which was compiled.  In order to use  the  object
      file,  a  lisp  system  must be started and the object
      file _f_a_s_led in.  When the -r switch is given to liszt,
      the  object file created will contain a small piece of
      bootstrap code at the beginning, and the  object  file
      will  be  made  executable.  Now, when the name of the


The Franz Lisp Manual                              PS2:9-175


      object file is given to the UNIX  command  interpreter
      (shell) to run, the bootstrap code at the beginning of
      the object file will cause a lisp system to be started
      and  the first action the lisp system will  take is to
      _f_a_s_l in the object file which started it.   In  effect
      the object file has created an environment in which it
      can run.

           Autorun  is  an  alternative  to  _d_u_m_p_l_i_s_p.   The
      advantage  of  autorun  is  that the object file which
      starts the whole process is typically  small,  whereas
      the  minimum  _d_u_m_p_l_i_s_ped  file is very large (one half
      megabyte).  The disadvantage of autorun  is  that  the
      file  must  be _f_a_s_led into a lisp each time it is used
      whereas the file which _d_u_m_p_l_i_s_p creates can be run  as
      is.   liszt  itself  is  a _d_u_m_p_l_i_s_ped file since it is
      used so often and is large enough that too  much  time
      would  be  wasted _f_a_s_ling it in each time it was used.
      The lisp cross reference program, lxref, uses  _a_u_t_o_r_u_n
      since it is a small and rarely used program.

           In order to have the program _f_a_s_led in begin exe-
      cution  (rather  than  starting a lisp top level), the
      value of the symbol user-top-level should  be  set  to
      the  name  of the function to get control.  An example
      of this is shown next.


9

9


PS2:9-176                              The Franz Lisp Manual


    ____________________________________________________

    _w_e _w_a_n_t _t_o _r_e_p_l_a_c_e _t_h_e _u_n_i_x _d_a_t_e _p_r_o_g_r_a_m _w_i_t_h _o_n_e _w_r_i_t_t_e_n _i_n _l_i_s_p.

    % cat lispdate.l
    (defun mydate nil
       (patom "The date is ")
       (patom (status ctime))
       (terpr)
       (exit 0))
    (setq user-top-level 'mydate)

    % liszt -r lispdate
    Compilation begins with Lisp Compiler 5.2
    source: lispdate.l, result: lispdate.o
    mydate
    %Note: lispdate.l: Compilation complete
    %Note: lispdate.l:  Time: Real: 0:3, CPU: 0:0.28, GC: 0:0.00 for 0 gcs
    %Note: lispdate.l: Assembly begins
    %Note: lispdate.l: Assembly completed successfully
    3.0u 2.0s 0:17 29%

     _W_e _c_h_a_n_g_e _t_h_e _n_a_m_e _t_o _r_e_m_o_v_e _t_h_e "._o", (_t_h_i_s _i_s_n'_t _n_e_c_e_s_s_a_r_y)
    % mv lispdate.o lispdate

     _N_o_w _w_e _t_e_s_t _i_t _o_u_t
    % lispdate
    The date is Sat Aug  1 16:58:33 1981
    %
    ____________________________________________________


   _1_2._7.  _p_u_r_e _l_i_t_e_r_a_l_s

           Normally the quoted lisp objects (literals) which
      appear in functions are treated as constants. Consider
      this function:

      (_d_e_f _f_o_o
         (_l_a_m_b_d_a _n_i_l (_c_o_n_d ((_n_o_t (_e_q '_a  (_c_a_r  (_s_e_t_q  _x  '(_a
      _b)))))
                            (_p_r_i_n_t '_i_m_p_o_s_s_i_b_l_e!!))
                           (_t (_r_p_l_a_c_a _x '_d)))))

      At first glance it seems that the  first  cond  clause
      will  never  be  true,  since  the _c_a_r of (_a _b) should
      always be _a.  However if you run this function  twice,
      it will print 'impossible!!' the second time.  This is


The Franz Lisp Manual                              PS2:9-177


      because the following clause modifies  the  'constant'
      list  (_a _b)  with the _r_p_l_a_c_a function.  Such modifica-
      tion of literal lisp objects  can  cause  programs  to
      behave  strangely as the above example shows, but more
      importantly it can cause garbage  collection  problems
      if  done  to compiled code.  When a file is _f_a_s_led in,
      if the symbol $purcopylits is  non  nil,  the  literal
      lisp  data  is  put in 'pure' space, that is it put in
      space which needn't be looked at by the garabage  col-
      lector.   This  reduces the work the garbage collector
      must do but it is dangerous since if the literals  are
      modified  to point to non pure objects, the marker may
      not mark the non pure objects.  If  the  symbol  $pur-
      copylits  is  nil then the literal lisp data is put in
      impure space and the compiled code will act  like  the
      interpreted  code  when literal data is modified.  The
      default value for $purcopylits is t.


   _1_2._8.  _t_r_a_n_s_f_e_r _t_a_b_l_e_s

           A transfer table is setup by _f_a_s_l when the object
      file is loaded in.  There is one entry in the transfer
      table for each function which is called in that object
      file.   The  entry  for a call to the function _f_o_o has
      two parts whose contents are:

      [1]  function address - This will initially  point  to
           the internal  function _q_l_i_n_k_e_r.  It may some time
           in the future point to the function _f_o_o  if  cer-
           tain  conditions  are  satisfied  (more  on  this
           below).

      [2]  function name - This is a pointer to  the  symbol
           _f_o_o.  This will be used by _q_l_i_n_k_e_r.


      When a call is made to the function _f_o_o the call  will
      actually  be made to the address in the transfer table
      entry  and  will  end  up  in  the  _q_l_i_n_k_e_r  function.
      _Q_l_i_n_k_e_r will determine that _f_o_o was the function being
      called by locating the  function  name  entry  in  the
      transfer table[|-].  If the function  being  called  is
____________________
9   [|-]_Q_l_i_n_k_e_r does this by tracing back the call stack until
it finds the _c_a_l_l_s machine instruction which called it.  The
address field of the  _c_a_l_l_s  contains  the  address  of  the
transfer table entry.


9


PS2:9-178                              The Franz Lisp Manual


      not compiled then _q_l_i_n_k_e_r just calls _f_u_n_c_a_l_l  to  per-
      form  the  function  call.   If _f_o_o is compiled and if
      (_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k)  is  non  nil,  then  _q_l_i_n_k_e_r  will
      modify the function address part of the transfer table
      to  point  directly  to  the  function  _f_o_o.   Finally
      _q_l_i_n_k_e_r will call _f_o_o directly .  The next time a call
      is made to _f_o_o the call will go directly  to  _f_o_o  and
      not  through  _q_l_i_n_k_e_r.  This will result in a substan-
      tial  speedup  in  compiled  code  to  compiled   code
      transfers.  A disadvantage is that no debugging infor-
      mation is left on the stack, so _s_h_o_w_s_t_a_c_k and _b_a_k_t_r_a_c_e
      are  useless.   Another  disadvantage  is  that if you
      redefine a compiled function either through loading in
      a  new  version or interactively defining it, then the
      old version may still be called from compiled code  if
      the  fast  linking  described  above  has already been
      done.  The  solution  to  these  problems  is  to  use
      (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _v_a_l_u_e).  If value is

      _n_i_l  All transfer tables will  be  cleared,  i.e.  all
           function  addresses  will  be  set  to  point  to
           _q_l_i_n_k_e_r.  This means that the next time  a  func-
           tion  is  called  _q_l_i_n_k_e_r will be called and will
           look at the current definition.   Also,  no  fast
           links  will  be  set  up since (_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k)
           will be nil.  The end result  is  that  _s_h_o_w_s_t_a_c_k
           and  _b_a_k_t_r_a_c_e  will work and the function defini-
           tion at the time of call will always be used.

      _o_n   This causes the lisp system  to  go  through  all
           transfer  tables  and  set up fast links wherever
           possible.  This is normally used after  you  have
           _f_a_s_led  in  all  of your files. Furthermore since
           (_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k) is not nil, _q_l_i_n_k_e_r will  make
           new  fast  links  if  the situation arises (which
           isn't likely unless you _f_a_s_l in another file).

      _t    This or any other value not previously  mentioned
           will just make (_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k) be non nil, and
           as a result fast links will be made   by  _q_l_i_n_k_e_r
           if the called function is compiled.


   _1_2._9.  _F_i_x_n_u_m _f_u_n_c_t_i_o_n_s

           The compiler will generate inline arithmetic code
      for  fixnum only functions.  Such functions include +,
      -, *,  /, \, 1+ and 1-.  The code  generated  will  be
      much  faster than using _a_d_d, _d_i_f_f_e_r_e_n_c_e, etc.  However
      it will only work if the arguments to and  results  of
      the functions are fixnums.  No type checking is done.
9

9


                           CHAPTER  13


            The CMU User Toplevel and the File Package


      This documentation was written by Don Cohen,  and  the
      functions  described  below  were imported from PDP-10
      CMULisp.

      _N_o_n _C_M_U _u_s_e_r_s _n_o_t_e: this is not the default top  level
      for  your  Lisp system.  In order to start up this top
      level, you should type (_l_o_a_d '_c_m_u_e_n_v).


   _1_3._1.  _U_s_e_r _C_o_m_m_a_n_d _I_n_p_u_t _T_o_p _L_e_v_e_l

      The top-level is the  function  that  reads  what  you
      type, evaluates it and prints the result.  The _n_e_w_l_i_s_p
      top-level was inspired by the CMULisp top-level (which
      was  inspired  by interlisp) but is much simpler.  The
      top-level is a function (of zero arguments)  that  can
      be  called  by  your  program.   If you prefer another
      top-level, just redefine the  top-level  function  and
      type  "(reset)" to start running it.  The current top-
      level simply calls the functions  tlread,  tleval  and
      tlprint  to  read, evaluate and print.  These are sup-
      posed to be replaceable by the  user.   The  only  one
      that  would  make  sense  to replace is tlprint, which
      currently uses a function that refuses to go  below  a
      certain  level  and prints "...]" when it finds itself
      printing a circular list.  One might want  to  pretty-
      print  the  results  instead.   The  current top-level
      numbers the lines that you type to it,  and  remembers
      the  last  n  "events"  (where  n  can  be  set but is
      defaulted to 25).  One can refer to  these  events  in
      the following "top-level commands":


9

9The Franz Lisp Manual                              PS2:9-179


PS2:9-180                              The Franz Lisp Manual


    ____________________________________________________

    _T_O_P_L_E_V_E_L _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

    ??      prints events - both the input and the result.  If you just type
            "??" you will see all of the recorded events.  "?? 3" will show
            only event 3, and "?? 3 6" will show events 3 through 6.

    redo    pretends that you typed the same thing that was typed before.  If
            you type "redo 3" event number 3 is redone.  "redo -3" redoes the
            thing 3 events ago.  "redo" is the same as "redo -1".

    ed      calls the editor and then does whatever the editor returns.  Thus
            if you want to do event 5 again except for some small change, you
            can type "ed 5", make the change and leave the editor.  "ed -3"
            and "ed" are analogous to redo.
    ____________________________________________________


Finally, you can get the value of event 7 with the  function
(valueof 7).  The other interesting feature of the top-level
is that it makes outermost parentheses superfluous  for  the
most  part.   This  works the same way as in CMULisp, so you
can use the help for an explanation.  If you're not sure and
don't  want  to  risk  it  you  can  always just include the
parentheses.


(top-level)

     SIDE EFFECT: _t_o_p-_l_e_v_e_l is the  LISP top level function.
                  As well as  being the  top level  function
                  with  which  the user interacts, it can be
                  called  recursively  by  the   user or any
                  function.  Thus, the   top  level  can  be
                  invoked  from  inside  the  editor,  break
                  package, or a user  function to  make  its
                  commands available to the user.

     NOTE: The  CMU FRANZ  LISP  top-level    uses  _l_i_n_e_r_e_a_d
           rather   than _r_e_a_d.  The difference will not usu-
           ally be noticeable.  The principal  thing  to  be
           careful   about is that input  to the function or
           system being called cannot appear   on  the  same
           line as the  top-level call.  For example, typing
           (_e_d_i_t_f _f_o_o)_f_P _o_n _o_n_e   _l_i_n_e  _w_i_l_l  _e_d_i_t  _f_o_o  _a_n_d
           _e_v_a_l_u_a_t_e  _P, _n_o_t _e_d_i_t _f_o_o _a_n_d _e_x_e_c_u_t_e _t_h_e  _p _c_o_m_-
           _m_a_n_d _i_n _t_h_e _e_d_i_t_o_r.  _t_o_p-_l_e_v_e_l  _s_p_e_c_i_a_l_l_y  _r_e_c_o_g_-
           _n_i_z_e_s _t_h_e _f_o_l_l_o_w_i_n_g _c_o_m_m_a_n_d_s:

9

9


The Franz Lisp Manual                              PS2:9-181


(valueof '_g__e_v_e_n_t_s_p_e_c)

     RETURNS: the value(s)  of  the  event(s)  specified  by
              g_eventspec.   If a single event is specified,
              its value will be returned.  If more than  one
              event  is specified, or an event has more than
              one subevent (as for _r_e_d_o,  etc),  a  list  of
              vlaues will be returned.


   _1_3._2.  _T_h_e _F_i_l_e _P_a_c_k_a_g_e

      Users typically define functions in lisp and then want
      to  save  them  for  the  next  session.   If  you  do
      (_c_h_a_n_g_e_s), a list of  the  functions  that  are  newly
      defined  or  changed  will  be printed.  When you type
      (_d_s_k_o_u_t_s), the functions associated with files will be
      saved in the new versions of those files.  In order to
      associate functions with files you can either add them
      to  the  _f_i_l_e_f_n_s  list of an existing file or create a
      new file to hold them.  This is  done  with  the  _f_i_l_e
      function.   If  you  type  (_f_i_l_e  _n_e_w) the system will
      create a variable called  _n_e_w_f_n_s.   You  may  add  the
      names of the functions to go into that file to _n_e_w_f_n_s.
      After you do (_c_h_a_n_g_e_s), the functions which are in  no
      other  file  are  stored  in  the  value  of  the atom
      _c_h_a_n_g_e_s.  To put these all  in  the  new  file,  (_s_e_t_q
      _n_e_w_f_n_s  (_a_p_p_e_n_d  _n_e_w_f_n_s  _c_h_a_n_g_e_s)).   Now  if  you  do
      (_c_h_a_n_g_e_s), all of  the  changed  functions  should  be
      associated  with  files.  In order to save the changes
      on the files, do (_d_s_k_o_u_t_s).  All of the changed  files
      (such  as  NEW)  will  be written.  To recover the new
      functions the next time you run FRANZ LISP, do  (_d_s_k_i_n
      _n_e_w).


9

9


PS2:9-182                              The Franz Lisp Manual


    ____________________________________________________

    Script started on Sat Mar 14 11:50:32 1981
    $ newlisp
    Welcome to newlisp...
    1.(defun square (x) (* x x))            ; define a new function
    square
    2.(changes)                             ; See, this function is associated
                                            ; with no file.
    <no-file>      (square)nil
    3.(file 'new)                           ; So let's declare file NEW.
    new
    4.newfns                                ; It doesn't have anything on it yet.
    nil
    5.(setq newfns '(square))               ; Add the function associated
    (square)                                ; with no file to file NEW.
    6.(changes)                             ; CHANGES magically notices this fact.

    new            (square)nil
    7.(dskouts)                             ; We write the file.
    creating new
    (new)
    8.(dskin new)                           ; We read it in!
    (new)
    14.Bye
    $
    script done on Sat Mar 14 11:51:48 1981

    ____________________________________________________


(changes s_flag)

     RETURNS: Changes computes a list  containing  an  entry
              for  each  file  which defines atoms that have
              been marked changed.  The entry  contains  the
              file   name  and  the  changed  atoms  defined
              therein.  There is also a  special  entry  for
              changes  to atoms which are not defined in any
              known file.  The global variable _f_i_l_e_l_s_t  con-
              tains  the  list of "known" files.  If no flag
              is passed this  result  is  printed  in  human
              readable  form  and the value returned is t if
              there were any changes and nil if not.  Other-
              wise  nothing is printed and the computer list
              is returned.  The global variable _c_h_a_n_g_e_s con-
              tains  the  atoms which are marked changed but
              not yet associated with any file.  The _c_h_a_n_g_e_s
              function  attempts  to  associate  these names


The Franz Lisp Manual                              PS2:9-183


              with files, and any that  are  not  found  are
              considered  to belong to no file.  The _c_h_a_n_g_e_s
              property is the means by which  changed  func-
              tions  are associated with files.  When a file
              is read in or written out its _c_h_a_n_g_e_s property
              is removed.

(dc s_word s_id [ g_descriptor1  ... ] <text> <esc>)

     RETURNS: _d_c defines comments.   It  is  exceptional  in
              that  its  behavior is very context dependent.
              When _d_c  is  executed  from  _d_s_k_i_n  it  simply
              records  the fact that the comment exists.  It
              is expected that in interactive mode  comments
              will  be  found via _g_e_t_d_e_f - this allows large
              comments which do not take up  space  in  your
              core image.  When _d_c is executed from the ter-
              minal it expects you to type a comment. _d_s_k_o_u_t
              will  write  out  the comments that you define
              and also copy the comments on the old  version
              of the file, so that the new version will keep
              the old comments even though they  were  never
              actually  brought  into core.  The optional id
              is  a  mechanism  for   distinguishing   among
              several  comments  associated  with  the  same
              word.  It defaults to  nil.   However  if  you
              define  two  comments  with  the  same id, the
              second is considered to be a  replacement  for
              the first. The behavior of _d_c is determined by
              the value of the global variable  _d_e_f-_c_o_m_m_e_n_t.
              _d_e_f-_c_o_m_m_e_n_t  contains  the  name of a function
              that is run.  Its arguments are the  word,  id
              and  attribute  list. _d_e_f-_c_o_m_m_e_n_t is initially
              _d_c-_d_e_f_i_n_e.  Other functions rebind it  to  _d_c-
              _h_e_l_p,  _d_c-_u_s_e_r_h_e_l_p,  and  the  value of _d_s_k_i_n-
              _c_o_m_m_e_n_t.  The comment property of an atom is a
              list  of  entries,  each representing one com-
              ment.  Atomic entries are assumed to be  iden-
              tifiers of comments on a file but not in core.
              In-core comments are represented by a list  of
              the  id,  the  attribute  list and the comment
              text.  The comment text is an uninterned atom.
              Comments  may be deleted or reordered by edit-
              ing the comment property.


9

9


PS2:9-184                              The Franz Lisp Manual


(dskin l_filenames)

     SIDE EFFECT: READ-EVAL-PRINTs  the  contents  of    the
                  given  files.  This is the function to use
                  to read files created  by  _d_s_k_o_u_t.   _d_s_k_i_n
                  also  declares the files that it reads (if
                  a _f_i_l_e-_f_n_s list is defined and the file is
                  otherwise  declarable  by  _f_i_l_e ), so that
                  changes to it can be recorded.


(dskout s_file1 ...)

     SIDE EFFECT: For each file  specified,  _d_s_k_o_u_t  assumes
                  the   list  named  filenameFNS (i.e.,  the
                  file  name,   excluding  extension,   con-
                  catenated   with  _f_n_s )  contains  a  list
                  of function names, etc., to be loaded  Any
                  previous  version  of  the  file  will  be
                  renamed  to have extension ".back".

(dskouts s_file1 ...)

     SIDE EFFECT: applies _d_s_k_o_u_t to and  prints the name  of
                  each  s_filei    (with    no    additional
                  arguments,   assuming filenameFNS to be  a
                  list  to  be loaded) for  which s_file_i is
                  either not in _f_i_l_e_l_s_t  (meaning  it  is  a
                  new   file not previously declared by _f_i_l_e
                  or  given  as  an   argument   to   _d_s_k_i_n,
                  _d_s_k_o_u_t_s,  or _d_s_k_o_u_t_s) or is in _f_i_l_e_l_s_t and
                  has some recorded changes  to  definitions
                  of  atoms  in  filenameFNS, as recorded by
                  _m_a_r_k!_c_h_a_n_g_e_d and  noted  by  changes.   If
                  _f_i_l_ei  is not  specified, _f_i_l_e_l_s_t  will be
                  used.  This  is the  most common   way  of
                  using  dskouts.   Typing   (_d_s_k_o_u_t_s)  will
                  save  every  file  reported  by  (_c_h_a_n_g_e_s)
                  to have changed definitions.


(dv s_atom g_value)

     EQUIVALENT TO: (_s_e_t_q   _a_t_o_m    '_v_a_l_u_e).     _d_v    calls
                    _m_a_r_k!_c_h_a_n_g_e_d.


9

9


The Franz Lisp Manual                              PS2:9-185


(file 's_file)

     SIDE EFFECT: declares its argument to be a file  to  be
                  used  for  reporting and saving changes to
                  functions by adding the  file  name  to  a
                  list  of  files,  _f_i_l_e_l_s_t.  _f_i_l_e is called
                  for each file argument of  _d_s_k_i_n,  _d_s_k_o_u_t,
                  and _d_s_k_o_u_t_s.

(file-fns 's_file)

     RETURNS: the name of the  fileFNS  list  for  its  file
              argument s_file.

(getdef 's_file ['s_i1 ...])

     SIDE EFFECT: selectively executes definitions for atoms
                  s_i1  ... from the specified file.  Any of
                  the words to be defined which end with "@"
                  will be treated as patterns in which the @
                  matchs any suffix (just like the  editor).
                  _g_e_t_d_e_f  is driven by _g_e_t_d_e_f_t_a_b_l_e (and thus
                  may be programmed).  It looks for lines in
                  the  file  that  start  with a word in the
                  table.  The first character must be a  "("
                  or "[" followed by the word, followed by a
                  space, return or something else that  will
                  not  be considered as part of the identif-
                  ier by _r_e_a_d, e.g.,  "("  is  unacceptable.
                  When  one  is found the next word is read.
                  If it matches one of  the  identifiers  in
                  the call to _g_e_t_d_e_f then the table entry is
                  executed.  The table entry is  a  function
                  of  the  expression starting in this line.
                  Output from _d_s_k_o_u_t is in acceptable format
                  for _g_e_t_d_e_f.  _g_e_t_d_e_f

     RETURNS: a list of the words which match  the  ones  it
              looked for, for which it found (but, depending
              on the table, perhaps did not execute) in  the
              file.

     NOTE: _g_e_t_d_e_f_t_a_b_l_e is the table that drives _g_e_t_d_e_f.   It
           is in the form of an association list.  Each ele-
           ment is a dotted pair consisting of the name of a
           function for which _g_e_t_d_e_f searches and a function
           of one argument to be executed when it is found.


9

9


PS2:9-186                              The Franz Lisp Manual


(mark!changed 's_f)

     SIDE EFFECT: records the fact that  the  definition  of
                  s_f has been changed.  It is automatically
                  called by _d_e_f, _d_e_f_u_n, _d_e, _d_f, _d_e_f_p_r_o_p, _d_m,
                  _d_v,  and  the  editor when a definition is
                  altered.


9

9


                           CHAPTER  14


                        The LISP Stepper


   _1_4._1.  _S_i_m_p_l_e _U_s_e _O_f _S_t_e_p_p_i_n_g

(step s_arg1...)

     NOTE: The LISP "stepping" package is intended  to  give
           the  LISP  programmer a facility analogous to the
           Instruction  Step  mode  of  running  a   machine
           language  program.  The user interface is through
           the function (fexpr) step, which sets switches to
           put the LISP interpreter in and out of "stepping"
           mode.  The most common _s_t_e_p  invocations  follow.
           These  invocations  are usually typed at the top-
           level, and will take effect immediately (i.e. the
           next  S-expression  typed in will be evaluated in
           stepping mode).


    ____________________________________________________

    (_s_t_e_p _t)                                ; Turn on stepping mode.
    (_s_t_e_p _n_i_l)                      ; Turn off stepping mode.
    ____________________________________________________


     SIDE EFFECT: In stepping mode, the LISP evaluator  will
                  print  out  each  S-exp  to  be  evaluated
                  before evaluation, and the returned  value
                  after  evaluation,  calling  itself recur-
                  sively to display the  stepped  evaluation
                  of  each argument, if the S-exp is a func-
                  tion call.  In stepping mode, the  evalua-
                  tor  will wait after displaying each S-exp
                  before evaluation for a command  character
                  from the console.


9

9The Franz Lisp Manual                              PS2:9-187


PS2:9-188                              The Franz Lisp Manual


    ____________________________________________________

    _S_T_E_P _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

    <return>                        Continue stepping recursively.

    c                               Show returned value from this level
                                    only, and continue stepping upward.

    e                               Only step interpreted code.

    g                               Turn off stepping mode. (but continue
                                    evaluation without stepping).

    n <number>                      Step through <number> evaluations without
                                    stopping

    p                               Redisplay current form in full
                                    (i.e. rebind prinlevel and prinlength to nil)

    b                               Get breakpoint

    q                               Quit

    d                               Call debug
    ____________________________________________________


   _1_4._2.  _A_d_v_a_n_c_e_d _F_e_a_t_u_r_e_s


      _1_4._2._1.  _S_e_l_e_c_t_i_v_e_l_y _T_u_r_n_i_n_g _O_n _S_t_e_p_p_i_n_g.

         If
                (_s_t_e_p _f_o_o_1 _f_o_o_2 ...)

         is typed at top level, stepping will  not  commence
         immediately,  but  rather  when the evaluator first
         encounters an S-expression  whose  car  is  one  of
         _f_o_o_1,  _f_o_o_2,  etc.   This form will then display at
         the console, and the evaluator will be in  stepping
         mode waiting for a command character.

              Normally the stepper intercepts calls to  _f_u_n_-
         _c_a_l_l  and  _e_v_a_l.   When _f_u_n_c_a_l_l is intercepted, the
         arguments  to  the  function  have   already   been
         evaluated   but   when  _e_v_a_l  is  intercepted,  the


The Franz Lisp Manual                              PS2:9-189


         arguments have not been  evaluated.   To  differen-
         tiate  the  two  cases,  when  printing the form in
         evaluation, the stepper preceded intercepted  calls
         to  _f_u_n_c_a_l_l  with  "f:".  Calls to _f_u_n_c_a_l_l are nor-
         mally caused by compiled lisp  code  calling  other
         functions, whereas calls to _e_v_a_l usually occur when
         lisp code is interpreted.  To step  only  calls  to
         eval use:         (_s_t_e_p _e)


      _1_4._2._2.  _S_t_e_p_p_i_n_g _W_i_t_h _B_r_e_a_k_p_o_i_n_t_s.

              For the moment, step is turned off  inside  of
         error  breaks, but not by the break function.  Upon
         exiting the error,  step  is  reenabled.   However,
         executing  (_s_t_e_p _n_i_l) inside a error loop will turn
         off stepping globally, i.e. within the error  loop,
         and after return has be made from the loop.


   _1_4._3.  _O_v_e_r_h_e_a_d _o_f _S_t_e_p_p_i_n_g.

           If stepping mode has been  turned  off  by  (_s_t_e_p
      _n_i_l),  the  execution  overhead of having the stepping
      packing in your LISP is identically nil.  If one stops
      stepping  by  typing  "g", every call to eval incurs a
      small    overhead--several    machine    instructions,
      corresponding  to  the compiled code for a simple cond
      and one function pushdown.  Running  with  (_s_t_e_p  _f_o_o_1
      _f_o_o_2 ...) can be more expensive, since a member of the
      car of the current form into the list (_f_o_o_1 _f_o_o_2  ...)
      is required at each call to eval.


   _1_4._4.  _E_v_a_l_h_o_o_k _a_n_d _F_u_n_c_a_l_l_h_o_o_k

           There are hooks in the FRANZ LISP interpreter  to
      permit  a user written function to gain control of the
      evaluation process.  These hooks are used by the  Step
      package  just described.  There are two hooks and they
      have been strategically placed in the  two  key  func-
      tions  in the interpreter: _e_v_a_l (which all interpreted
      code goes through) and  _f_u_n_c_a_l_l  (which  all  compiled
      code  goes through if (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l) has been
      done).  The hook in _e_v_a_l is compatible  with  Maclisp,
      but there is no Maclisp equivalent of the hook in _f_u_n_-
      _c_a_l_l.

9

9


PS2:9-190                              The Franz Lisp Manual


           To arm the hooks two  forms  must  be  evaluated:
      (*_r_s_e_t _t)  and  (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t).   Once  that  is
      done, _e_v_a_l and _f_u_n_c_a_l_l do a special  check  when  they
      enter.

           If  _e_v_a_l  is  given  a  form  to  evaluate,   say
      (_f_o_o _b_a_r),  and  the symbol `evalhook' is non nil, say
      its value is `ehook', then _e_v_a_l will lambda  bind  the
      symbols  `evalhook'  and `funcallhook' to nil and will
      call ehook passing (_f_o_o _b_a_r) as the argument.   It  is
      ehook's   responsibility  to  evaluate  (_f_o_o _b_a_r)  and
      return its value.  Typically ehook will call the func-
      tion  `evalhook'  to  evaluate  (_f_o_o _b_a_r).   Note that
      `evalhook' is a symbol whose  function  binding  is  a
      system  function  described  in  Chapter  4, and whose
      value binding, if non nil, is the name of a user writ-
      ten  function  (or  a  lambda  expression, or a binary
      object) which  will  gain  control  whenever  eval  is
      called.  `evalhook' is also the name of the _s_t_a_t_u_s tag
      which must be set for all of this to work.

           If _f_u_n_c_a_l_l is given a function, say  foo,  and  a
      set of already evaluated arguments, say barv and bazv,
      and if the symbol `funcallhook' has a non  nil  value,
      say  `fhook', then _f_u_n_c_a_l_l will lambda bind `evalhook'
      and `funcallhook' to nil  and  will  call  fhook  with
      arguments  barv,  bazv  and foo.  Thus fhook must be a
      lexpr since it may be given any number  of  arguments.
      The  function  to  call, foo in this case, will be the
      _l_a_s_t of the arguments given to fhook.   It  is  fhooks
      responsibility  to do the function call and return the
      value.  Typically fhook will call  the  function  _f_u_n_-
      _c_a_l_l_h_o_o_k  to  do the funcall.  This is an example of a
      funcallhook function which  just prints the  arguments
      on each entry to funcall and the return value.


9

9


The Franz Lisp Manual                              PS2:9-191


    ____________________________________________________

    -> (_d_e_f_u_n _f_h_o_o_k _n (_l_e_t ((_f_o_r_m (_c_o_n_s (_a_r_g _n) (_l_i_s_t_i_f_y (_1- _n))))
                            (_r_e_t_v_a_l))
                           (_p_a_t_o_m "_c_a_l_l_i_n_g ")(_p_r_i_n_t _f_o_r_m)(_t_e_r_p_r)
                           (_s_e_t_q _r_e_t_v_a_l (_f_u_n_c_a_l_l_h_o_o_k _f_o_r_m '_f_h_o_o_k))
                           (_p_a_t_o_m "_r_e_t_u_r_n_s ")(_p_r_i_n_t _r_e_t_v_a_l)(_t_e_r_p_r)
                           _r_e_t_v_a_l))
    fhook
    -> (*_r_s_e_t _t) (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t) (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l)
    -> (_s_e_t_q _f_u_n_c_a_l_l_h_o_o_k '_f_h_o_o_k)
    calling (print fhook)           ;; now all compiled code is traced
    fhookreturns nil
    calling (terpr)

    returns nil
    calling (patom "-> ")
    -> returns "-> "
    calling (read nil Q00000)
    (_a_r_r_a_y _f_o_o _t _1_0)                ;; to test it, we see what happens when
    returns (array foo t 10)        ;; we make an array
    calling (eval (array foo t 10))
    calling (append (10) nil)
    returns (10)
    calling (lessp 1 1)
    returns nil
    calling (apply times (10))
    returns 10
    calling (small-segment value 10)
    calling (boole 4 137 127)
    returns 128
     ... there is plenty more ...
    ____________________________________________________


9

9


                           CHAPTER  15


                        The FIXIT Debugger


   _1_5._1.  _I_n_t_r_o_d_u_c_t_i_o_n   FIXIT is  a  debugging  environment
      for  FRANZ LISP users doing program development.  This
      documentation and  FIXIT  were  written  by  David  S.
      Touretzky  of  Carnegie-Mellon University for MACLisp,
      and adapted to FRANZ LISP  by  Mitch  Marcus  of  Bell
      Labs.  One of FIXIT's goals is to get the program run-
      ning again  as  quickly  as  possible.   The  user  is
      assisted  in  making  changes to his functions "on the
      fly", i.e. in the midst of execution, and then  compu-
      tation is resumed.

           To enter the debugger type (_d_e_b_u_g).  The debugger
      goes  into  its  own  read-eval-print  loop.  Like the
      top-level, the debugger  understands  certain  special
      commands.   One  of these is help, which prints a list
      of the available commands.  The basic idea is that you
      are  somewhere  in a stack of calls to eval.  The com-
      mand "bka" is probably the most appropriate for  look-
      ing  at  the stack.  There are commands to move up and
      down.  If you want to know the value of "x" as of some
      place  in  the  stack, move to that place and type "x"
      (or (cdr x) or anything else that you  might  want  to
      evaluate).   All  evaluation is done as of the current
      stack position.  You can fix the problem  by  changing
      the  values of variables, editing functions or expres-
      sions in the stack etc.  Then you  can  continue  from
      the current stack position (or anywhere else) with the
      "redo" command.  Or you can simply  return  the  right
      answer with the "return" command.

           When it is not immediately obvious why  an  error
      has  occurred  or  how the program got itself into its
      current state, FIXIT comes to the rescue by  providing
      a powerful debugging loop in which the user can:

      -  examine the stack

      -  evaluate expressions in context

      -  enter stepping mode

      -  restart the computation at any point
9

9PS2:9-192                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-193


      The result is that program errors can be  located  and
      fixed  extremely  rapidly, and with a minimum of frus-
      tration.

           The debugger can only work effectively when extra
      information  is  kept about forms in evaluation by the
      lisp system.  Evaluating (*_r_s_e_t _t) tells the lisp sys-
      tem to maintain this information. If you are debugging
      compiled code you should also be sure  that  the  com-
      piled   code  to  compiled  code  linkage  tables  are
      unlinked, i.e do (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l).


(debug [ s_msg ])

     NOTE: Within a program, you  may  enter  a  debug  loop
           directly  by putting in a call to _d_e_b_u_g where you
           would normally put a call to _b_r_e_a_k.  Also, within
           a break loop you may enter FIXIT by typing _d_e_b_u_g.
           If an argument is given to DEBUG, it  is  treated
           as  a message to be printed before the debug loop
           is entered.  Thus you can put (_d_e_b_u_g |_j_u_s_t _b_e_f_o_r_e
           _l_o_o_p|)  into  a  program to indicate what part of
           the program is being debugged.


9

9


PS2:9-194                              The Franz Lisp Manual


    ____________________________________________________

    _F_I_X_I_T _C_o_m_m_a_n_d _S_u_m_m_a_r_y

    TOP     go to top of stack (latest expression)
    BOT     go to bottom of stack (first expression)
    P       show current expression (with ellipsis)
    PP      show current expression in full
    WHERE   give current stack position
    HELP    types the abbreviated command summary found
            in /usr/lisp/doc/fixit.help.  H and ? work too.
    U       go up one stack frame
    U n     go up n stack frames
    U f     go up to the next occurrence of function f
    U n f   go up n occurrences of function f
    UP      go up to the next user-written function
    UP n    go up n user-written functions
     ...the DN and DNFN commands are similar, but go down
     ...instead of up.
    OK      resume processing; continue after an error or debug loop
    REDO    restart the computation with the current stack frame.
            The OK command is equivalent to TOP followed by REDO.
    REDO f  restart the computation with the last call to function f.
            (The stack is searched downward from the current position.)
    STEP    restart the computation at the current stack frame,
            but first turn on stepping mode.  (Assumes Rich stepper is loaded.)
    RETURN e   return from the current position in the computation
               with the value of expression e.
    BK..    print a backtrace.  There are many backtrace commands,
            formed by adding suffixes to the BK command.  "BK" gives
            a backtrace showing only user-written functions, and uses
            ellipsis.  The BK command may be suffixed by one or more
            of the following modifiers:
     ..F..   show function names instead of expressions
     ..A..   show all functions/expressions, not just user-written ones
     ..V..   show variable bindings as well as functions/expressions
     ..E..   show everything in the expression, i.e. don't use ellipsis
     ..C..   go no further than the current position on the stack
            Some of the more useful combinations are BKFV, BKFA,
            and BKFAV.
    BK.. n    show only n levels of the stack (starting at the top).
              (BK n counts only user functions; BKA n counts all functions.)
    BK.. f    show stack down to first call of function f
    BK.. n f  show stack down to nth call of function f
    ____________________________________________________


9

9


The Franz Lisp Manual                              PS2:9-195


   _1_5._2.  _I_n_t_e_r_a_c_t_i_o_n _w_i_t_h _t_r_a_c_e    FIXIT  knows  about  the
      standard  Franz trace package, and tries to make trac-
      ing invisible  while  in  the  debug  loop.   However,
      because  of  the  way _t_r_a_c_e works, it may sometimes be
      the case that the functions on the  stack  are  really
      un_i_n_t_e_r_ned  atoms  that have the same name as a traced
      function.  (This  only  happens  when  a  function  is
      traced  WHEREIN  another one.)  FIXIT will call atten-
      tion to _t_r_a_c_e'_s hackery by printing an appropriate tag
      next to these stack entries.


   _1_5._3.  _I_n_t_e_r_a_c_t_i_o_n _w_i_t_h _s_t_e_p   The _s_t_e_p function  may  be
      invoked from within FIXIT via the STEP command.  FIXIT
      initially turns off stepping when the  debug  loop  is
      entered.   If  you  step through a function and get an
      error, FIXIT will still be invoked normally.   At  any
      time  during  stepping, you may explicitly enter FIXIT
      via the "D" (debug) command.


   _1_5._4.  _M_u_l_t_i_p_l_e _e_r_r_o_r _l_e_v_e_l_s   FIXIT will evaluate  arbi-
      trary LISP expressions in its debug loop.  The evalua-
      tion is not done within an _e_r_r_s_e_t,  so,  if  an  error
      occurs,  another  invocation  of  the  debugger can be
      made.  When there are multiple errors  on  the  stack,
      FIXIT  displays  a  barrier  symbol between each level
      that looks something  like  <------------UDF-->.   The
      UDF in this case stands for UnDefined Function.  Thus,
      the upper level debug loop was invoked by an undefined
      function error that occurred while in the lower loop.


9

9


                           CHAPTER  16


                         The LISP Editor


   _1_6._1.  _T_h_e _E_d_i_t_o_r_s

      It is quite possible to use VI, Emacs or  other  stan-
      dard editors to edit your lisp programs, and many peo-
      ple do just that.  However there is a  lisp  structure
      editor  which  is particularly good for the editing of
      lisp programs, and  operates  in  a  rather  different
      fashion,  namely  within a lisp environment.  applica-
      tion.  It is handy to know how to use  it  for  fixing
      problems  without  exiting  from the lisp system (e.g.
      from the debugger  so  you  can  continue  to  execute
      rather  than having to start over.)  The editor is not
      quite like the top-level  and  debugger,  in  that  it
      expects  you  to  type editor commands to it.  It will
      not evaluate whatever you happen to type.   (There  is
      an editor command to evaluate things, though.)

      The editor is available (assuming your system  is  set
      up  correctly  with  a  lisp  library) by typing (load
      'cmufncs) and (load 'cmuedit).

      The  most  frequent  use of the editor  is  to  change
      function  definitions  by starting the editor with one
      of the  commands  described  in  section  16.14.  (see
      _e_d_i_t_f),   values   (_e_d_i_t_v),  properties  (_e_d_i_t_p),  and
      expressions  (_e_d_i_t_e).  The  beginner   is  advised  to
      start  with  the  following (very basic) commands: _o_k,
      _u_n_d_o, _p, #, under which are  explained  two  different
      basic commands which  start with numbers, and f.

      This documentation, and the editor, were imported from
      PDP-10  CMULisp by Don Cohen.  PDP-10 CMULisp is based
      on UCILisp, and the editor itself was derived from  an
      early  version of Interlisp.  Lars Ericson, the author
      of this section, has provided this very  concise  sum-
      mary.   Tutorial  examples  and implementation details
      may be found in the Interlisp Reference Manual,  where
      a similar editor is described.


9

9PS2:9-196                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-197


   _1_6._2.  _S_c_o_p_e _o_f _A_t_t_e_n_t_i_o_n

      Attention-changing commands allow you  to  look  at  a
      different  part  of a Lisp expression you are editing.
      The sub-structure upon which the editor's attention is
      centered  is called "the current expression".   Chang-
      ing the current expression  means  shifting  attention
      and not actually modifying any structure.

____________________________________________________________

_S_C_O_P_E _O_F _A_T_T_E_N_T_I_O_N _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_n (_n>_0) . Makes the nth element of the current expression be
the new current expression.

-_n (_n>_0). Makes the nth element from the end of the  current
expression be the new current expression.

_0. Makes the  next  higher expression  be  the  new  correct
expression.   If  the  intention  is  to go back to the next
higher left parenthesis, use the command !0.

_u_p .  If a p command would cause  the  editor  to  type  ...
before  typing  the current expression, (the current expres-
sion is a tail of the next higher expression)  then  has  no
effect;  else, up makes the old current expression the first
element in the new current expression.

!_0 . Goes back to the next higher left parenthesis.

^ .  Makes the top level expression be the  current  expres-
sion.

_n_x .  Makes the current expression be the next expression.

(_n_x _n) equivalent to n nx commands.

!_n_x .  Makes current expression be the next expression at  a
higher  level.  Goes through any number of right parentheses
to get to the next expression.

 _b_k .  Makes the current expression be the previous  expres-
sion in the next higher expression.

(_n_t_h _n) _n>_0 .  Makes the list starting with the nth  element
of the current expression be the current expression.

(_n_t_h $) - _g_e_n_e_r_a_l_i_z_e_d _n_t_h _c_o_m_m_a_n_d. nth locates $,  and  then
backs up to the current level, where the new current expres-
sion is the tail whose first element contains, however  dee-
ply,  the  expression  that was the terminus of the location
operation.


PS2:9-198                              The Franz Lisp Manual


:: .  (pattern ::  .  $)  e.g., (cond :: return).   finds  a
cond that contains a return, at any depth.

(_b_e_l_o_w _c_o_m _x) .  The below command is useful for locating  a
substructure  by  specifying something  it contains.  (below
cond) will cause the cond  clause  containing   the  current
expression  to  become  the new current expression.  Suppose
you are editing a list of lists, and want to find a  sublist
that  contains a foo (at any depth).  Then simply executes f
foo (below ).

(_n_e_x _x) .  same as (_b_e_l_o_w _x) followed by nx.   For  example,
if  you are deep inside of a selectq clause, you can advance
to the next clause with (_n_e_x _s_e_l_e_c_t_q).

_n_e_x.  The  atomic  form  of  _n_e_x is useful if  you  will  be
performing  repeated   executions   of  (_n_e_x  _x).  By simply
marking  the  chain corresponding to x,  you can use _n_e_x  to
step through the sublists.
____________________________________________________________


   _1_6._3.  _P_a_t_t_e_r_n _M_a_t_c_h_i_n_g _C_o_m_m_a_n_d_s

      Many editor commands that  search  take  patterns.   A
      pattern _p_a_t matches with x if:

____________________________________________________________

_P_A_T_T_E_R_N _S_P_E_C_I_F_I_C_A_T_I_O_N _S_U_M_M_A_R_Y

- _p_a_t is _e_q to x.

- _p_a_t is &.

- _p_a_t is a number and equal to x.

- if (car _p_a_t) is the atom *any*, (cdr _p_a_t)  is  a  list  of
patterns,  and  _p_a_t matches x if and only if one of the pat-
terns on (cdr _p_a_t) matches x.

- if _p_a_t is a literal atom or string, and (nthchar  _p_a_t  -1)
is @, then _p_a_t matches with any literal atom or string which
has the same initial characters as _p_a_t, e.g.   ver@  matches
with verylongatom, as well as "verylongstring".

- if (car _p_a_t) is the atom --, _p_a_t matches  x  if  (a)  (cdr
_p_a_t)=nil,  i.e.   _p_a_t=(--), e.g., (a --) matches (a) (a b c)
and (a .  b) in other words, -- can  match  any  tail  of  a
list.   (b)  (cdr _p_a_t) matches with some tail of x, e.g.  (a


The Franz Lisp Manual                              PS2:9-199


-- (&)) will match with (a b c (d)), but not (a b c  d),  or
(a  b c (d) e).  however, note that (a -- (&) --) will match
with (a b c (d) e).  in other words, -- will match any inte-
rior segment of a list.

- if (car _p_a_t) is the atom ==, _p_a_t matches x if and only  if
(cdr  _p_a_t) is _e_q to x.  (this pattern is for use by programs
that call the editor as a subroutine, since  any  non-atomic
expression  in a command typed in by the user obviously can-
not be _e_q to existing structure.) -  otherwise  if  x  is  a
list,  _p_a_t  matches x if (car _p_a_t) matches (car x), and (cdr
_p_a_t) matches (cdr x).

- when searching, the pattern  matching  routine  is  called
only  to  match  with  elements in the structure, unless the
pattern begins with :::, in which case cdr of the pattern is
matched  against tails in the structure.  (in this case, the
tail does not have to be a proper tail, e.g.   (:::   a  --)
will  match  with the element (a b c) as well as with cdr of
(x a b c), since (a b c) is a tail of (a b c).)
____________________________________________________________


      _1_6._3._1.  _C_o_m_m_a_n_d_s _T_h_a_t _S_e_a_r_c_h

____________________________________________________________

_S_E_A_R_C_H _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_f _p_a_t_t_e_r_n .  f informs the editor that the next  command  is
to  be  interpreted as a pattern.  If no pattern is given on
the same line as the f then the last  pattern  is  used.   f
pattern means find the next instance of pattern.

(_f _p_a_t_t_e_r_n _n).  Finds the next instance of pattern.

(_f _p_a_t_t_e_r_n _t).  similar to f pattern, except,  for  example,
if the current expression is (cond ..), f cond will look for
the next cond, but (f cond t) will 'stay here'.

(_f _p_a_t_t_e_r_n  _n)  _n>_0.   Finds  the  nth  place  that  pattern
matches.   If the current expression is (foo1 foo2 foo3), (f
f00@ 3) will find foo3.

(_f _p_a_t_t_e_r_n) _o_r (_f _p_a_t_t_e_r_n _n_i_l).  only matches with  elements
at  the top level of the current expression.  If the current
expression is (_p_r_o_g _n_i_l (_s_e_t_q _x (_c_o_n_d & &)) (_c_o_n_d &) ...)  f
(cond  --)  will  find  the cond inside the setq, whereas (f
(cond --)) will find the top level cond,  i.e.,  the  second
one.


PS2:9-200                              The Franz Lisp Manual


(_s_e_c_o_n_d . $) .  same as (lc .  $) followed by another (lc  .
$)  except  that  if the first succeeds and second fails, no
change is made to the edit chain.

(_t_h_i_r_d . $) .  Similar to second.

(_f_s _p_a_t_t_e_r_n_1 ... _p_a_t_t_e_r_n_n) .  equivalent to f pattern1  fol-
lowed by f pattern2 ...  followed by f pattern n, so that if
f pattern m fails, edit chain is left at place  pattern  m-1
matched.

(_f= _e_x_p_r_e_s_s_i_o_n _x) .  Searches for a structure eq to  expres-
sion.

(_o_r_f _p_a_t_t_e_r_n_1 ... _p_a_t_t_e_r_n_n) .  Searches  for  an  expression
that is matched by either pattern1 or ...  patternn.

_b_f _p_a_t_t_e_r_n .  backwards find.   If the current expression is
(_p_r_o_g _n_i_l (_s_e_t_q _x (_s_e_t_q _y (_l_i_s_t _z))) (_c_o_n_d ((_s_e_t_q _w --) --))
--) f list followed  by  bf  setq  will  leave  the  current
expression  as (setq y (list z)), as will f cond followed by
bf setq

(_b_f _p_a_t_t_e_r_n _t).  backwards  find.   Search  always  includes
current  expression,  i.e., starts at end of current expres-
sion and works backward, then ascends and backs up, etc.
____________________________________________________________


         _1_6._3._1._1.   _L_o_c_a_t_i_o_n _S_p_e_c_i_f_i_c_a_t_i_o_n_s    Many  editor
            commands  use  a  method  of specifying position
            called  a  location  specification.   The  meta-
            symbol $ is used to denote a location specifica-
            tion.   $ is a list of commands  interpreted  as
            described above.  $ can also be atomic, in which
            case it is interpreted as (list $).  a  location
            specification  is  a  list of edit commands that
            are executed in  the  normal  fashion  with  two
            exceptions.   first, all commands not recognized
            by the editor are interpreted as though they had
            been  preceded  by f. The location specification
            (cond 2 3) specifies  the  3rd  element  in  the
            first clause of the next cond.

            the if command and the ## function provide a way
            of  using  in  location specifications arbitrary
            predicates applied to elements  in  the  current
            expression.

            In insert, delete, replace and change, if  $  is


The Franz Lisp Manual                              PS2:9-201


            nil (empty), the corresponding operation is per-
            formed on the current edit chain, i.e.  (replace
            with  (car x)) is equivalent to (:(car x)).  for
            added readability, here is also permitted, e.g.,
            (insert  (print  x)  before  here)  will  insert
            (print x) before the current expression (but not
            change  the  edit chain).  It is perfectly legal
            to ascend to insert, replace,  or  delete.   for
            example  (insert  (_r_e_t_u_r_n) after ^ prog -1) will
            go to the top, find the first prog, and insert a
            (_r_e_t_u_r_n)  at its end, and not change the current
            edit chain.

            The a, b,  and  :   commands  all  make  special
            checks in e1 thru em for expressions of the form
            (## . coms).  In this case, the expression  used
            for  inserting  or  replacing  is  a copy of the
            current expression after executing coms, a  list
            of  edit  commands.    (insert (## f cond -1 -1)
            after3)  will make a copy of the  last  form  in
            the  last clause of the next cond, and insert it
            after the third element of the  current  expres-
            sion.

            $.  In descriptions of  the  editor,  the  meta-
            symbol $ is used to denote a location specifica-
            tion.   $ is a list of commands  interpreted  as
            described above.  $ can also be atomic.

____________________________________________________________

_L_O_C_A_T_I_O_N _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

(_l_c . $) .  Provides a way of explicitly invoking the  loca-
tion operation.  (lc cond 2 3) will perform search.

(_l_c_l . $) .  Same as lc except search is confined to current
expression.   To  find a cond containing a _r_e_t_u_r_n, one might
use the location specification (cond (lcl  _r_e_t_u_r_n)  )  where
the   would reverse the effects of the lcl command, and make
the final current expression be the cond.
____________________________________________________________


      _1_6._3._2.  _T_h_e _E_d_i_t _C_h_a_i_n   The edit-chain is a list  of
         which  the first element is the the one you are now
         editing ("current expression"), the next element is
         what  would  become  the  current expression if you
         were to do a 0, etc., until the last element  which
         is the expression that was passed to the editor.


PS2:9-202                              The Franz Lisp Manual


____________________________________________________________

_E_D_I_T _C_H_A_I_N _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_m_a_r_k .  Adds the current edit chain to the front of the list
marklst.

_ .  Makes the new edit chain be (car marklst).

(_ _p_a_t_t_e_r_n) .  Ascends the edit chain  looking  for  a  link
which matches pattern.  for example:

__ .  Similar to _ but also erases the mark.

\ . Makes the edit chain be the value of unfind.  unfind  is
set  to  the current edit chain by each command that makes a
"big jump", i.e., a command that usually performs more  than
a  single  ascent or descent, namely ^, _, __, !nx, all com-
mands that involve a search, e.g., f, lc, ::, below,  et  al
and                      and                     themselves.
if the user types f cond, and then f car,   would  take  him
back  to the cond.  another  would take him back to the car,
etc.

\_p .  Restores the edit chain to its state as  of  the  last
print  operation.   If  the edit chain has not changed since
the last printing, \p restores it to its  state  as  of  the
printing before that one.  If the user types p followed by 3
2 1 p, \p will  return  to  the  first  p,  i.e.,  would  be
equivalent to 0 0 0.  Another \p would then take him back to
the second p.
____________________________________________________________


   _1_6._4.  _P_r_i_n_t_i_n_g _C_o_m_m_a_n_d_s

____________________________________________________________

_P_R_I_N_T_I_N_G _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_p  Prints current expression in  abbreviated  form.   (p  m)
prints  mth  element  of  current  expression in abbreviated
form.  (p m n) prints mth element of current  expression  as
though  printlev  were  given  a depth of n.  (p 0 n) prints
current expression as though printlev were given a depth  of
n.  (p cond 3) will work.

?  .  prints the current expression as though printlev  were
given a depth of 100.
9

9


The Franz Lisp Manual                              PS2:9-203


_p_p .  pretty-prints the current expression.

_p_p*.  is like pp, but forces comments to be shown.
____________________________________________________________


   _1_6._5.  _S_t_r_u_c_t_u_r_e _M_o_d_i_f_i_c_a_t_i_o_n _C_o_m_m_a_n_d_s

      All structure modification commands are undoable.  See
      _u_n_d_o.


____________________________________________________________

_S_T_R_U_C_T_U_R_E _M_O_D_I_F_I_C_A_T_I_O_N _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

# [_e_d_i_t_o_r _c_o_m_m_a_n_d_s] (n)  n>1 deletes the corresponding  ele-
ment from the current expression.

(_n _e_1 ...  _e_m) _n,_m>_1 replaces the nth element in the current
expression with e1 ...  em.

(-_n _e_1 ...  _e_m) _n,_m>_1 inserts e1 ...  em before the  n  ele-
ment in the current expression.

(_n _e_1 ...  _e_m) (the letter "n" for "next" or "nconc", not  a
number)  m>1  attaches  e1 ...  em at the end of the current
expression.

(_a _e_1 ... _e_m) .   inserts  e1  ...   em  after  the  current
expression (or after its first element if it is a tail).

(_b _e_1 ... _e_m) .  inserts  e1  ...   em  before  the  current
expression.   to  insert  foo before the last element in the
current expression, perform -1 and then (b foo).

(: _e_1 ... _e_m) .  replaces the current expression by  e1  ...
em.     If the current expression is a tail then replace its
first element.

_d_e_l_e_t_e _o_r (:)  .  deletes the current expression, or if  the
current expression is a tail, deletes its first element.

(_d_e_l_e_t_e . $).  does a (lc .  $) followed by delete.  current
edit chain is not changed.

(_i_n_s_e_r_t _e_1 ... _e_m _b_e_f_o_r_e . $) .  similar to  (lc.   $)  fol-
lowed by (b e1 ... em).

(_i_n_s_e_r_t _e_1 ...  _e_m _a_f_t_e_r .  $).  similar  to  insert  before


PS2:9-204                              The Franz Lisp Manual


except uses a instead of b.

(_i_n_s_e_r_t _e_1 ...  _e_m _f_o_r .   $).   similar  to  insert  before
except uses :  for b.

(_r_e_p_l_a_c_e $ _w_i_t_h _e_1 ... _e_m) .  here $ is the segment  of  the
command between replace and with.

(_c_h_a_n_g_e $ _t_o _e_1 ... _e_m) .  same as replace with.
____________________________________________________________


   _1_6._6.  _E_x_t_r_a_c_t_i_o_n _a_n_d _E_m_b_e_d_d_i_n_g _C_o_m_m_a_n_d_s

____________________________________________________________

_E_X_T_R_A_C_T_I_O_N _A_N_D _E_M_B_E_D_D_I_N_G _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

(_x_t_r . $) .  replaces the original current  expression  with
the expression that is current after performing (lcl . $).

(_m_b_d _x) .  x is a list, substitutes the  current  expression
for  all  instances  of  the  atom  * in x, and replaces the
current expression with the  result  of  that  substitution.
(mbd x) :  x atomic, same as (mbd (x *)).

(_e_x_t_r_a_c_t $_1 _f_r_o_m $_2) .  extract is an editor  command  which
replaces  the  current expression with one of its subexpres-
sions (from any depth).  ($1 is the segment between  extract
and  from.)    example:  if the current expression is (print
(cond ((null x) y) (t z))) then following  (extract  y  from
cond), the current expression will be (print y).  (extract 2
-1 from cond), (extract y from 2), (extract  2  -1  from  2)
will all produce the same result.

(_e_m_b_e_d $ _i_n . _x) .  embed replaces  the  current  expression
with  a new expression which contains it as a subexpression.
($ is the segment between embed and in.)   example:   (embed
print  in setq x), (embed 3 2 in _r_e_t_u_r_n), (embed cond 3 1 in
(or * (null x))).
____________________________________________________________


   _1_6._7.  _M_o_v_e _a_n_d _C_o_p_y _C_o_m_m_a_n_d_s


9

9


The Franz Lisp Manual                              PS2:9-205


____________________________________________________________

_M_O_V_E _A_N_D _C_O_P_Y _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

(_m_o_v_e $_1 _t_o _c_o_m . $_2) .  ($1 is the segment between move and
to.)  where com is before, after, or the name of a list com-
mand, e.g., :, n, etc.  If $2 is nil, or (here), the current
position specifies where the operation is to take place.  If
$1 is nil, the move command allows the user to specify  some
place  the  current  expression  is to be moved to.   if the
current expression is (a b d c), (move 2 to  after  4)  will
make the new current expression be (a c d b).

(_m_v _c_o_m . $) .  is the same as (move here to com . $).

(_c_o_p_y $_1 _t_o _c_o_m . $_2)  is like move except that  the  source
expression is not deleted.

(_c_p _c_o_m . $).  is like mv except that the source  expression
is not deleted.
____________________________________________________________


   _1_6._8.    _P_a_r_e_n_t_h_e_s_e_s _M_o_v_i_n_g _C_o_m_m_a_n_d_s      The    commands
      presented  in  this section permit modification of the
      list structure itself, as opposed  to  modifying  com-
      ponents  thereof.   their  effect  can be described as
      inserting  or  removing  a  single   left   or   right
      parenthesis, or pair of left and right parentheses.

____________________________________________________________

_P_A_R_E_N_T_H_E_S_E_S _M_O_V_I_N_G _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

(_b_i _n _m) .  both in.  inserts  parentheses  before  the  nth
element and after the mth element in the current expression.
example:  if the current expression is (a b (c d  e)  f  g),
then (bi 2 4) will modify it to be (a (b (c d e) f) g).  (bi
n) :  same as (bi n n).  example:  if the current expression
is (a b (c d e) f g), then (bi -2) will modify it to be (a b
(c d e) (f) g).

(_b_o _n) .  both out.  removes both parentheses from  the  nth
element.   example:   if the current expression is (a b (c d
e) f g), then (bo d) will modify it to be (a b c d e f g).

(_l_i _n) .  left in.  inserts a left  parenthesis  before  the
nth  element (and a matching right parenthesis at the end of
the current expression).  example:  if the  current  expres-
sion  is (a b (c d e) f g), then (li 2) will modify it to be


PS2:9-206                              The Franz Lisp Manual


(a (b (c d e) f g)).

(_l_o _n) .  left  out.  removes  a  left parenthesis  from the
nth  element.  all  elements  following  the nth element are
deleted.  example: if the current expression is (a b (c d e)
f g), then  (lo  3) will modify it to be (a b c d e).

(_r_i _n _m) .  right  in.  move  the  right parenthesis at  the
end of the nth element in to after the mth element.  inserts
a  right parenthesis  after  the mth element of the nth ele-
ment.   The  rest  of  the  nth element is brought up to the
level of the  current expression.   example: if the  current
expression  is (a (b c d e) f g), (ri 2 2) will modify it to
be (a (b c) d e f g).

(_r_o _n) .  right  out.  move the right parenthesis at the end
of  the  nth  element out to the  end of the current expres-
sion.  removes the right parenthesis from the  nth  element,
moving it to the end of the current expression. all elements
following the nth  element  are moved  inside of   the   nth
element.  example: if the current expression is (a b (c d e)
f  g),  (ro  3) will modify  it to be (a b (c d e f g)).

(_r _x _y)  replaces  all  instances  of x by y in the  current
expression,  e.g.,  (r  caadr  cadar).   x  can  be  the  s-
expression (or atom) to be substituted for, or can be a pat-
tern which specifies that s-expression (or atom).

(_s_w _n _m)  switches the nth and mth elements of  the  current
expression.  for example, if the current expression is (list
(cons (car x) (car y)) (cons (cdr y))),   (sw   2  3)   will
modify  it  to be (list (cons (cdr x) (cdr y)) (cons (car x)
(car y))).   (sw car  cdr) would produce the same result.
____________________________________________________________


      _1_6._8._1.  _U_s_i_n_g _t_o _a_n_d _t_h_r_u

         to, thru, extract, embed, delete, replace, and move
         can  be  made to operate on several contiguous ele-
         ments, i.e., a segment of a list, by using  the  to
         or   thru  command  in  their  respective  location
         specifications.  thru and to  are  intended  to  be
         used   in  conjunction with extract, embed, delete,
         replace, and move.    to and thru can also be  used
         directly  with  xtr  (which  takes after a location
         specification), as in (xtr (2 thru  4))  (from  the
         current expression).

9

9


The Franz Lisp Manual                              PS2:9-207


____________________________________________________________

_T_O _A_N_D _T_H_R_U _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

($_1 _t_o $_2)    .   same  as  thru  except  last  element  not
included.

($_1 _t_o).  same as ($1 thru -1)

($_1 _t_h_r_u $_2)  .  If the current expression is (a  (b  (c  d)
(e)  (f  g  h)  i)  j  k), following (c thru g), the current
expression will be ((c d) (e) (f g h)).  If both $1  and  $2
are  numbers, and $2 is greater than $1, then $2 counts from
the beginning of the current expression, the same as $1.  in
other  words,  if the current expression is (a b c d e f g),
(3 thru 4) means (c thru d), not (c thru f).  in this  case,
the corresponding bi command is (bi 1 $2-$1+1).

($_1 _t_h_r_u). same as ($_1 _t_h_r_u -_1).
____________________________________________________________


   _1_6._9.  _U_n_d_o_i_n_g _C_o_m_m_a_n_d_s   each command that causes struc-
      ture  modification  automatically adds an entry to the
      front of undolst containing the  information  required
      to  restore all pointers that were changed by the com-
      mand.  The undo command undoes the  last,  i.e.,  most
      recent such command.

____________________________________________________________

_U_N_D_O _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_u_n_d_o .  the  undo  command  undoes  most  recent,  structure
modification  command  that  has  not  yet  been undone, and
prints the name of that command, e.g., mbd undone.  The edit
chain  is  then exactly what it was before the 'undone' com-
mand had been performed.

!_u_n_d_o .  undoes  all  modifications  performed  during  this
editing session, i.e., this call to the editor.

_u_n_b_l_o_c_k .  removes  an  undo-block. If executed  at  a  non-
blocked  state,  i.e., if undo or !undo could operate, types
not blocked.

_t_e_s_t .  adds an undo-block at the front  of  undolst.   note
that  test   together   with  !undo  provide  a  'tentative'
mode  for editing, i.e., the user can perform  a  number  of
changes,  and  then  undo  all  of  them with a single !undo


PS2:9-208                              The Franz Lisp Manual


command.

_u_n_d_o_l_s_t [_v_a_l_u_e].  each editor command that causes  structure
modification  automatically  adds  an  entry to the front of
undolst containing the information required to  restore  all
pointers that were changed by the command.

??   prints the entries on undolst.  The entries are  listed
most recent entry first.
____________________________________________________________


   _1_6._1_0.  _C_o_m_m_a_n_d_s _t_h_a_t _E_v_a_l_u_a_t_e

____________________________________________________________

_E_V_A_L_U_A_T_I_O_N _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_e .  only when typed in, (i.e., (insert  d  before  e)  will
treat  e  as  a  pattern) causes  the  editor  to  call  the
lisp interpreter giving it the next input as argument.

(_e  _x)  evaluates  x, and prints the result.  (e x  t)  same
as (e x) but does not print.

(_i _c _x_1 ... _x_n)  same as (c y1 ...  yn) where yi=(eval  xi).
example:   (i  3  (cdr foo)) will replace the 3rd element of
the current expression with the cdr of the value of foo.  (i
n foo (car fie)) will attach the value of foo and car of the
value of fie to the end of the current  expression.   (i  f=
foo t) will search for an expression eq to the value of foo.
If c is not an atom, it is evaluated as well.

(_c_o_m_s _x_1 ... _x_n) .  each  xi  is  evaluated  and  its  value
executed as a command.  The i command is not very convenient
for computing an entire edit command for  execution,   since
it  computes  the command name and its arguments separately.
also, the i command cannot be used  to  compute  an   atomic
command.   The  coms  and comsq  commands provide more  gen-
eral ways of computing commands.  (coms  (cond  (x  (list  1
x))))  will replace the first element of the current expres-
sion with the value of x if non-nil, otherwise  do  nothing.
(nil as a command is a nop.)

(_c_o_m_s_q _c_o_m_1 ... _c_o_m_n) .  executes com1 ... comn.   comsq  is
mainly  useful in conjunction with the  coms command.    for
example,  suppose the user wishes to compute an entire  list
of  commands  for  evaluation,  as opposed to computing each
command one at a time  as does  the coms command.  he  would
then  write  (coms  (cons (quote comsq) x)) where x computed


The Franz Lisp Manual                              PS2:9-209


the list of commands, e.g.,   (coms   (cons   (quote  comsq)
(get  foo (quote commands))))
____________________________________________________________


   _1_6._1_1.  _C_o_m_m_a_n_d_s _t_h_a_t _T_e_s_t

____________________________________________________________

_T_E_S_T_I_N_G _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

(_i_f _x)  generates an error unless the value of (eval  x)  is
non-nil,  i.e., if (eval x) causes an error or (eval x)=nil,
if will cause an error.  (if x coms1 coms2) if (eval  x)  is
non-nil,  execute  coms1;  if (eval x) causes an error or is
equal to nil, execute coms2.  (if x coms1)   if   (eval   x)
is  non-nil,  execute  coms1; otherwise generate  an  error.

(_l_p . _c_o_m_s) .  repeatedly executes coms, a list of commands,
until  an   error   occurs.      (lp  f  print (n  t))  will
attach  a t  at the end of every  print  expression.  (lp  f
print  (if  (##  3) nil ((n t)))) will attach a t at the end
of each print expression  which  does  not  already  have  a
second  argument.   (i.e.   the  form   (## 3) will cause an
error if the edit command 3 causes an error, thereby select-
ing  ((n t)) as the list of commands to be executed.  The if
could also  be written  as  (if  (cddr (##)) nil ((n t))).).

(_l_p_q . _c_o_m_s)  same as lp but does not print n occurrences.

(_o_r_r _c_o_m_s_1 ... _c_o_m_s_n) .  orr begins by  executing  coms1,  a
list  of  commands.   If  no  error occurs, orr is finished.
otherwise, orr restores the edit  chain  to   its   original
value,   and  continues by executing coms2, etc.  If none of
the command lists execute without  errors,   i.e.,  the  orr
"drops off the end", orr generates an error.  otherwise, the
edit chain is left as of the completion of the first command
list  which executes  without error.
____________________________________________________________


   _1_6._1_2.  _E_d_i_t_o_r _M_a_c_r_o_s

      Many of the more sophisticated branching  commands  in
      the  editor, such as orr, if,  etc.,  are  most  often
      used  in  conjunction with  edit  macros.   The  macro
      feature  permits  the  user to define new commands and


PS2:9-210                              The Franz Lisp Manual


      thereby  expand  the  editor's  repertoire.  (however,
      built in commands always  take  precedence  over  mac-
      ros, i.e.,  the  editor's repertoire can be  expanded,
      but  not  modified.) macros are defined by using the m
      command.

      (_m _c . _c_o_m_s)  for c an atom, m defines c as an  atomic
      command.   (if a macro  is  redefined, its new defini-
      tion replaces its old.) executing c is then  the  same
      as  executing  the  list of  commands  coms.    macros
      can  also define list commands,  i.e.,  commands  that
      take  arguments.  (m (c) (arg[1] ... arg[n]) . coms) c
      an atom.  m defines c as a list command.  executing (c
      e1  ...   en)  is then  performed  by substituting  e1
      for  arg[1],  ...    en  for arg[n]  throughout  coms,
      and  then  executing  coms.   a  list  command  can be
      defined via a macro  so  as  to   take   a  fixed   or
      indefinite   number  of  'arguments'.   The form given
      above specified a macro with a fixed number  of  argu-
      ments,  as indicated by its argument list.   if the of
      arguments.  (m (c) args . coms) c,  args  both  atoms,
      defines  c as  a  list command.  executing  (c  e1 ...
      en) is performed by substituting (e1 ...   en),  i.e.,
      cdr of the command, for args throughout coms, and then
      executing coms.

      (m bp bk up p) will define bp as  an  atomic   command
      which   does three things,  a bk, an up, and a p. note
      that macros can use commands defined by macros as well
      as  built  in  commands  in  their definitions.    for
      example, suppose  z  is  defined by (m z -1 (if  (null
      (##))  nil  (p))),  i.e.  z does a -1, and then if the
      current expression is not nil, a p. now we can  define
      zz  by  (m zz  -1 z), and zzz by (m zzz -1 -1 z) or (m
      zzz -1 zz).  we could define a more general bp  by  (m
      (bp)  (n) (bk n) up p).    (bp 3)  would  perform  (bk
      3), followed  by  an  up,  followed  by a p.  The com-
      mand  second  can  be defined as a macro by (m (2nd) x
      (orr ((lc .  x) (lc .  x)))).

      Note  that  for  all editor commands, 'built in'  com-
      mands  as  well  as commands defined by macros, atomic
      definitions  and  list  definitions   are   completely
      independent.   in  other  words,  the  existence of an
      atomic definition for c in no way  affects  the treat-
      ment  of  c  when it appears as car of a list command,
      and the existence of a list definition for c in no way
      affects  the  treatment  of   c  when it appears as an
      atom.  in particular, c can be used  as  the  name  of
      either  an atomic command, or a list command, or both.
      in the latter case, two  entirely  different   defini-
      tions   can   be   used.    note  also  that once c is
      defined as an atomic command via a  macro  definition,


The Franz Lisp Manual                              PS2:9-211


      it  will  not  be searched for when used in a location
      specification, unless c is preceded by an f.   (insert
      --   before  bp)  would not search for bp, but instead
      perform a bk, an up, and a p, and then do  the  inser-
      tion.  The corresponding also holds true for list com-
      mands.

      (_b_i_n_d . _c_o_m_s)  bind  is  an  edit   command  which  is
      useful  mainly  in macros.  it binds three dummy vari-
      ables #1, #2, #3, (initialized to nil), and then  exe-
      cutes   the   edit  commands   coms.   note that these
      bindings are only in effect  while  the  commands  are
      being executed, and that bind can be used recursively;
      it will  rebind #1, #2,   and   #3  each  time  it  is
      invoked.

      _u_s_e_r_m_a_c_r_o_s  [_v_a_l_u_e].   this   variable   contains  the
      users editing macros .   if you want to save your mac-
      ros then you  should  save  usermacros.   you   should
      probably  also  save editcomsl.

      _e_d_i_t_c_o_m_s_l [_v_a_l_u_e].  editcomsl  is  the  list of  "list
      commands"  recognized  by  the editor.  (these are the
      ones of the form (command arg1 arg2 ...).)


   _1_6._1_3.  _M_i_s_c_e_l_l_a_n_e_o_u_s _E_d_i_t_o_r _C_o_m_m_a_n_d_s

____________________________________________________________

_M_I_S_C_E_L_L_A_N_E_O_U_S _E_D_I_T_O_R _C_O_M_M_A_N_D _S_U_M_M_A_R_Y

_o_k .  Exits from the editor.

_n_i_l .  Unless preceded by f or bf, is always a  null  opera-
tion.

_t_t_y:  .  Calls  the  editor  recursively.  The user can then
type in commands, and have them executed.  The tty:  command
is completed when  the  user exits  from  the lower   editor
(with   ok   or  stop).  the tty:  command is extremely use-
ful. it enables the user to  set  up a  complex   operation,
and   perform   interactive attention-changing commands part
way through it. for example the command  (move  3  to  after
cond  3  p  tty:)  allows  the user to interact, in  effect,
within  the move  command.      he can  verify  for  himself
that  the  correct  location has been found, or complete the
specification "by hand". in effect, tty: says "I'll tell you
what you should do when you get there."

_s_t_o_p .  exits from the editor with an error.  mainly for use


PS2:9-212                              The Franz Lisp Manual


in  conjunction  with  tty:  commands that the user wants to
abort.  since all of the commands in the editor are   errset
protected, the user must exit from the editor via a command.
stop provides a way of distinguishing between  a  successful
and unsuccessful  (from the user's  standpoint) editing ses-
sion.

_t_l .  tl  calls (top-level).  to return to the  editor  just
use the _r_e_t_u_r_n top-level command.

_r_e_p_a_c_k .  permits the 'editing' of an atom or string.

(_r_e_p_a_c_k $) does (lc . $) followed by  repack,  e.g.  (repack
this@).

(_m_a_k_e_f_n _f_o_r_m _a_r_g_s _n _m) .  makes (car form) an expr with  the
nth  through mth  elements  of  the  current expression with
each occurrence  of  an element of (cdr  form)  replaced  by
the  corresponding  element  of  args.   The nth through mth
elements  are replaced  by form.

(_m_a_k_e_f_n _f_o_r_m _a_r_g_s _n).  same as (makefn form args n n).

(_s _v_a_r . $) .  sets var (using setq) to the current  expres-
sion  after  performing  (lc .    $).    (s  foo)  will  set
foo to the current expression, (s foo -1 1) will set foo  to
the first element in the last element of the current expres-
sion.
____________________________________________________________


   _1_6._1_4.  _E_d_i_t_o_r _F_u_n_c_t_i_o_n_s


(editf s_x1 ...)

     SIDE EFFECT: edits a function. s_x1 is the name of  the
                  function,  any additional arguments are an
                  optional list of commands.

     RETURNS: s_x1.

     NOTE: if s_x1 is not an editable function,  editf  gen-
           erates an fn not editable error.


9

9


The Franz Lisp Manual                              PS2:9-213


(edite l_expr l_coms s_atm))
edits an expression.  its  value  is  the  last  element  of
(editl (list l_expr) l_coms s_atm nil nil).


(editracefn s_com)
is available to help the user debug complex edit macros,  or
subroutine  calls  to   the   editor.  editracefn  is  to be
defined by the user.  whenever the value of  editracefn   is
non-nil,   the   editor   calls  the   function   editracefn
before executing  each command (at  any  level),  giving  it
that command as its argument.  editracefn is initially equal
to nil, and undefined.


(editv s_var [ g_com1 ... ])

     SIDE EFFECT: similar  to  editf,  for  editing  values.
                  editv  sets  the  variable  to  the  value
                  returned.

     RETURNS: the name  of  the  variable  whose  value  was
              edited.


(editp s_x)

     SIDE EFFECT: similar  to  editf  for  editing  property
                  lists. used if x is nil.

     RETURNS: the atom whose property list was edited.


(editl coms atm marklst mess)

     SIDE EFFECT: editl is the editor.  its  first  argument
                  is  the  edit  chain,  and its value is an
                  edit chain, namely the value of l  at  the
                  time  editl  is  exited.   (l is a special
                  variable, and so can be examined or set by
                  edit  commands.    ^  is  equivalent to (e
                  (setq l(last l)) t).)  coms is an optional
                  list  of  commands.  for interactive edit-
                  ing, coms is nil.   in  this  case,  editl
                  types  edit  and then waits for input from
                  the teletype.  (if mess is not  nil  editl
                  types  it  instead  of edit.  for example,
                  the tty:  command is essentially  (setq  l
                  (editl  l  nil  nil  nil  (quote tty:))).)
                  exit occurs only via an ok, stop, or  save
                  command.   If  coms is not nil, no message
                  is typed,  and  each  member  of  coms  is
                  treated  as a command and executed.  If an


PS2:9-214                              The Franz Lisp Manual


                  error occurs in the execution  of  one  of
                  the  commands, no error message is printed
                  , the rest of the  commands  are  ignored,
                  and  editl  exits with an error, i.e., the
                  effect is the same as though a  stop  com-
                  mand  had  been executed.  If all commands
                  execute successfully,  editl  returns  the
                  current  value  of l.  marklst is the list
                  of marks.  on calls from editf, atm is the
                  name  of  the  function  being  edited; on
                  calls from editv, the name  of  the  vari-
                  able,  and  calls  from editp, the atom of
                  which some property of its  property  list
                  is being edited.  The property list of atm
                  is used by the save command for saving the
                  state  of  the  edit.   save will not save
                  anything if  atm=nil  i.e.,  when  editing
                  arbitrary  expressions  via edite or editl
                  directly.


(editfns s_x [ g_coms1 ... ])
fsubr function, used to perform the same editing  operations
on  several  functions.  editfns maps down the list of func-
tions, prints the name of each function, and calls the  edi-
tor (via editf) on that function.

     EXAMPLE: editfns foofns (r fie fum)) will change  every
              fie   to   fum   in  each  of the functions on
              foofns.

     NOTE: the  call  to  the  editor is  errset  protected,
           so  that if the editing of one function causes an
           error, editfns will proceed to  the  next   func-
           tion.     in  the  above  example,  if one of the
           functions did not contain a fie,  the  r  command
           would   cause   an  error, but editing would con-
           tinue with  the  next  function.   The  value  of
           editfns is nil.


(edit4e pat y)

     SIDE EFFECT: is the pattern match routine.

     RETURNS: t if pat matches y. see edit-match for defini-
              tion of 'match'.

     NOTE: before  each  search  operation  in  the   editor
           begins,  the   entire   pattern  is  scanned  for
           atoms  or strings that end  in  at-signs.   These
           are  replaced  by  patterns  of  the  form  (cons
           (quote  /@)  (explodec   atom)).       from   the


The Franz Lisp Manual                              PS2:9-215


           standpoint   of  edit4e, pattern type 5, atoms or
           strings  ending  in  at-signs,  is   really   "if
           car[pat]  is the atom @ (at-sign), pat will match
           with  any  literal atom  or  string  whose   ini-
           tial   character codes (up to the @) are the same
           as those in cdr[pat]." if  the  user  wishes   to
           call  edit4e  directly, he must therefore convert
           any patterns which contain   atoms   or   strings
           ending  in  at-signs  to  the  form recognized by
           edit4e.   this  can  be  done  via  the  function
           editfpat.

(editfpat pat flg)
makes a copy of pat with all patterns of type 5  (see  edit-
match)  converted to the form expected by edit4e. flg should
be passed as nil (flg=t is for internal use by the editor).


(editfindp x pat flg)

     NOTE: Allows a program to use the edit find command  as
           a  pure  predicate from outside the editor.  x is
           an expression, pat a pattern.  The value of edit-
           findp  is  t  if the command f pat would succeed,
           nil otherwise.  editfindp calls editfpat to  con-
           vert  pat  to the form expected by edit4e, unless
           flg=t.    if the program is applying editfindp to
           several different expressions using the same pat-
           tern, it will be more efficient to call  editfpat
           once,  and then call editfindp with the converted
           pattern and flg=t.


(## g_com1 ...)

     RETURNS: what the current  expression  would  be  after
              executing the edit commands com1 ...  starting
              from the present  edit  chain.   generates  an
              error  if  any  of  comi  cause  errors.   The
              current edit chain is never changed.  example:
              (i  r  (quote x) (## (cons ..z))) replaces all
              x's in the current  expression  by  the  first
              cons containing a z.


9

9


                           CHAPTER  17


                           Hash Tables


   _1_7._1.  _O_v_e_r_v_i_e_w

           A hash table is an object  that  can  efficiently
      map  a  given object to another.  Each hash table is a
      collection of entries,  each  of  which  associates  a
      unique  _k_e_y  with  a _v_a_l_u_e.  There are elemental func-
      tions to add, delete, and find entries based on a par-
      ticular key.  Finding a value in a hash table is rela-
      tively fast compared to  looking  up  values  in,  for
      example, an assoc list or property list.

           Adding a key to a hash table  modifies  the  hash
      table, and so it is a descructive operation.

           There are two different  kinds  of  hash  tables:
      those that use the function _e_q_u_a_l for the comparing of
      keys, and those that use _e_q, the default.  If a key is
      "eq"  to  another  object,  then  a  match is assumed.
      Likewise with "equal".


   _1_7._2.  _F_u_n_c_t_i_o_n_s

(makeht 'x_size ['s_test])

     RETURNS: A hash  table  of  x_size  hash  buckets.   If
              present, s_test is used as the test to compare
              keys in the hash table, the default being  eq.
              _E_q_u_a_l  might  be  used  to create a hash table
              where the keys are to be lists  (or  any  lisp
              object).

     NOTE: At this time, hash tables are implemented on  top
           of vectors.


9

9PS2:9-216                              The Franz Lisp Manual


The Franz Lisp Manual                              PS2:9-217


(hash-table-p 'H_arg)

     RETURNS: t if H_arg is a hash table.

     NOTE: Since hash tables are really  vectors,  the  lisp
           type of a hash table is a vector, so that given a
           vector, this function will return t.

(gethash 'g_key 'H_htable ['g_default])

     RETURNS: the value associated the  key  g_key  in  hash
              table  H_htable.   If  there  is  not an entry
              given by the key and g_default  is  specified,
              then  g_default is returned, otherwise, a sym-
              bol that is unbound is returned.  This  is  so
              that nil can be a associated with a key.

     NOTE: _s_e_t_f may be used to set the value assocaited with
           a key.

(remhash 'g_key 'H_htable)

     RETURNS: t if there was an entry for g_key in the  hash
              table H_htable, nil otherwise.  In the case of
              a match, the entry and associated  object  are
              removed from the hash table.

(maphash 'u_func 'H_htable)

     RETURNS: nil.

     NOTE: The function u_func is applied to  every  element
           in  the  hash  table  H_htable.   The function is
           called with two arguments: the key and  value  of
           an  element.   The mapped function should not add
           or delete  object  from  the  table  because  the
           results would be unpredicable.

(clrhash 'H_htable)

     RETURNS: the hash table cleared of all entries.


9

9


PS2:9-218                              The Franz Lisp Manual


(hash-table-count 'H_htable)

     RETURNS: the number of entries in  H_htable.   Given  a
              new  hash table with no entries, this function
              returns zero.


9

9


The Franz Lisp Manual                              PS2:9-219


    ____________________________________________________

    ; make a vanilla hash table using "eq" to compare items...
    -> (setq black-box (makeht 20))
    hash-table[26]
    -> (hash-table-p black-box)
    t
    -> (hash-table-count black-box)
    0
    -> (setf (gethash 'key black-box) '(the value associated with the key))
    key
    -> (gethash 'key black-box)
    (the value associated with the key)
    -> (hash-table-count black-box)
    1
    -> (addhash 'composer black-box 'franz)
    composer
    -> (gethash 'composer black-box)
    franz
    -> (maphash '(lambda (key val) (msg "key " key " value " val N)) black-box)
    key composer value franz
    key key value (the value associated with the key)
    nil
    -> (clrhash black-box)
    hash-table[26]
    -> (hash-table-count black-box)
    0
    -> (maphash '(lambda (key val) (msg "key " key " value " val N)) black-box)
    nil

    ; here is an example using "equal" as the comparator
    -> (setq ht (makeht 10 'equal))
    hash-table[16]
    -> (setf (gethash '(this is a key) ht) '(and this is the value))
    (this is a key)
    -> (gethash '(this is a key) ht)
    (and this is the value)
    ; the reader makes a new list each time you type it...
    -> (setq x '(this is a key))
    (this is a key)
    -> (setq y '(this is a key))
    (this is a key)
    ; so these two lists are really different lists that compare "equal"
    ; not "eq"
    -> (eq x y)
    nil
    ; but since we are using "equal" to compare keys, we are OK...
    -> (gethash x ht)
    (and this is the value)
    -> (gethash y ht)
    (and this is the value)
    ____________________________________________________


PS2:9-220                              The Franz Lisp Manual


9

9