text: 
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  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
  
  9Special Functions                                        4-2
  
  
  
  
  
  
  
  Special Functions                                        4-1
  
  
  
      ____________________________________________________
  
      ; _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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-2
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-3
  
  
  
      ____________________________________________________
  
      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
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-4
  
  
       (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-5
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-6
  
  
  (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.
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-7
  
  
             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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-8
  
  
  (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.
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                        4-9
  
  
             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 simultaneously
            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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-10
  
  
  
      ____________________________________________________
  
      ; 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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-11
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-12
  
  
  (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
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-13
  
  
             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
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-14
  
  
             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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-15
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-16
  
  
  (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
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-17
  
  
             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,
  
  
                                     Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-18
  
  
             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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-19
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-20
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-21
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-22
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-23
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  
  
  
  
  Special Functions                                       4-24
  
  
  (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                                   Printed: January 31, 1984
  
  
  
  