Return to ch4.r CVS log

Up to [CSRG BSD Unix] / 43BSD / ucb / lisp / lisplib / manual

Annotation of 43BSD/ucb/lisp/lisplib/manual/ch4.r, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: 
        !             4: 
        !             5: 
        !             6: 
        !             7: 
        !             8: 
        !             9: 
        !            10: 
        !            11: 
        !            12: 
        !            13: 
        !            14: 
        !            15: 
        !            16: 
        !            17: 
        !            18: 
        !            19: 
        !            20: 
        !            21: 
        !            22: 
        !            23: 
        !            24: 
        !            25: 
        !            26: 
        !            27: 
        !            28: 
        !            29: 
        !            30: 
        !            31: 
        !            32: 
        !            33: 
        !            34: 
        !            35: 
        !            36: 
        !            37: 
        !            38: 
        !            39: 
        !            40: 
        !            41: 
        !            42: 
        !            43: 
        !            44: 
        !            45: 
        !            46: 
        !            47: 
        !            48: 
        !            49: 
        !            50: 
        !            51: 
        !            52: 
        !            53: 
        !            54: 
        !            55: 
        !            56: 
        !            57: 
        !            58: 
        !            59: 
        !            60: 9
        !            61: 
        !            62: 9
        !            63: 
        !            64: 
        !            65: 
        !            66: 
        !            67: 
        !            68: 
        !            69: 
        !            70: 
        !            71: 
        !            72: 
        !            73:                          CHAPTER  4
        !            74: 
        !            75: 
        !            76:                      Special Functions
        !            77: 
        !            78: 
        !            79: 
        !            80: 
        !            81: (and [g_arg1 ...])
        !            82: 
        !            83:      RETURNS: the value of the last argument  if  all  argu-
        !            84:               ments  evaluate  to a non-nil value, otherwise
        !            85:               _a_n_d returns nil.  It returns t if there are no
        !            86:               arguments.
        !            87: 
        !            88:      NOTE: the arguments are evaluated  left  to  right  and
        !            89:            evaluation  will cease with the first nil encoun-
        !            90:            tered.
        !            91: 
        !            92: (apply 'u_func 'l_args)
        !            93: 
        !            94:      RETURNS: the result of applying function u_func to  the
        !            95:               arguments in the list l_args.
        !            96: 
        !            97:      NOTE: If u_func is a lambda, then  the  (_l_e_n_g_t_h _l__a_r_g_s)
        !            98:            should  equal the number of formal parameters for
        !            99:            the u_func.  If u_func is  a  nlambda  or  macro,
        !           100:            then l_args is bound to the single formal parame-
        !           101:            ter.
        !           102: 
        !           103: 
        !           104: 
        !           105: 
        !           106: 
        !           107: 
        !           108: 
        !           109: 
        !           110: 
        !           111: 
        !           112: 
        !           113: 
        !           114: 
        !           115: 
        !           116: 
        !           117: 
        !           118: 
        !           119: 
        !           120: 
        !           121: 
        !           122: 
        !           123: 
        !           124: 
        !           125: 9
        !           126: 
        !           127: 9Special Functions                                        4-2
        !           128: 
        !           129: 
        !           130: 
        !           131: 
        !           132: 
        !           133: 
        !           134: 
        !           135: Special Functions                                        4-1
        !           136: 
        !           137: 
        !           138: 
        !           139:     ____________________________________________________
        !           140: 
        !           141:     ; _a_d_d_1 is a lambda of 1 argument
        !           142:     -> (_a_p_p_l_y '_a_d_d_1 '(_3))
        !           143:     4
        !           144: 
        !           145:     ; we will define _p_l_u_s_1 as a macro which will be equivalent to _a_d_d_1
        !           146:     -> (_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))))
        !           147:     plus1
        !           148:     -> (_p_l_u_s_1 _3)
        !           149:     4
        !           150: 
        !           151:     ; now if we _a_p_p_l_y a macro we obtain the form it changes to.
        !           152:     -> (_a_p_p_l_y '_p_l_u_s_1 '(_p_l_u_s_1 _3))
        !           153:     (add1 3)
        !           154: 
        !           155:     ; if we _f_u_n_c_a_l_l a macro however, the result of the macro is _e_v_a_led
        !           156:     ; before it is returned.
        !           157:     -> (_f_u_n_c_a_l_l '_p_l_u_s_1 '(_p_l_u_s_1 _3))
        !           158:     4
        !           159: 
        !           160:     ; for this particular macro, the _c_a_r of the _a_r_g is not checked
        !           161:     ; so that this too will work
        !           162:     -> (_a_p_p_l_y '_p_l_u_s_1 '(_f_o_o _3))
        !           163:     (add1 3)
        !           164: 
        !           165:     ____________________________________________________
        !           166: 
        !           167: 
        !           168: 
        !           169: 
        !           170: (arg ['x_numb])
        !           171: 
        !           172:      RETURNS: if x_numb  is  specified  then  the  x_numb'_t_h
        !           173:               argument  to  the enclosing lexpr If x_numb is
        !           174:               not specified then this returns the number  of
        !           175:               arguments to the enclosing lexpr.
        !           176: 
        !           177:      NOTE: it is an error to the interpreter  if  x_numb  is
        !           178:            given and out of range.
        !           179: 
        !           180: 
        !           181: 
        !           182: 
        !           183: 
        !           184: 
        !           185: 
        !           186: 
        !           187: 
        !           188: 
        !           189: 
        !           190: 9
        !           191: 
        !           192: 9                                   Printed: January 31, 1984
        !           193: 
        !           194: 
        !           195: 
        !           196: 
        !           197: 
        !           198: 
        !           199: 
        !           200: Special Functions                                        4-2
        !           201: 
        !           202: 
        !           203: (break [g_message ['g_pred]])
        !           204: 
        !           205:      WHERE:   if g_message is not given it is assumed to  be
        !           206:               the null string, and if g_pred is not given it
        !           207:               is assumed to be t.
        !           208: 
        !           209:      RETURNS: the value of (*_b_r_e_a_k '_g__p_r_e_d '_g__m_e_s_s_a_g_e)
        !           210: 
        !           211: (*break 'g_pred 'g_message)
        !           212: 
        !           213:      RETURNS: nil immediately if g_pred  is  nil,  else  the
        !           214:               value  of  the next (return 'value) expression
        !           215:               typed in at top level.
        !           216: 
        !           217:      SIDE EFFECT: If the  predicate,  g_pred,  evaluates  to
        !           218:                   non-null, the lisp system stops and prints
        !           219:                   out `Break '  followed  by  g_message.  It
        !           220:                   then  enters a break loop which allows one
        !           221:                   to interactively debug a program.  To con-
        !           222:                   tinue  execution  from a break you can use
        !           223:                   the _r_e_t_u_r_n  function.  to  return  to  top
        !           224:                   level  or another break level, you can use
        !           225:                   _r_e_t_b_r_k or _r_e_s_e_t.
        !           226: 
        !           227: (caseq 'g_key-form l_clause1 ...)
        !           228: 
        !           229:      WHERE:   l_clause_i is a list of the form  (g_comparator
        !           230:               ['g_form_i  ...]).  The comparators may be sym-
        !           231:               bols, small fixnums, a list of  small  fixnums
        !           232:               or symbols.
        !           233: 
        !           234:      NOTE: The way caseq works is that it  evaluates  g_key-
        !           235:            form, yielding a value we will call the selector.
        !           236:            Each clause is examined  until  the  selector  is
        !           237:            found consistent with the comparator.  For a sym-
        !           238:            bol, or a fixnum, this means the two must be  _e_q.
        !           239:            For  a list, this means that the selector must be
        !           240:            _e_q to some element of the list.
        !           241: 
        !           242:            The comparator consisting of  the  symbol  t  has
        !           243:            special  semantics: it matches anything, and con-
        !           244:            sequently, should be the last comparator.
        !           245: 
        !           246:            In any case, having chosen a clause, _c_a_s_e_q evalu-
        !           247:            ates each form within that clause and
        !           248: 
        !           249:      RETURNS: the value of the last form.  If no comparators
        !           250:               are matched, _c_a_s_e_q returns nil.
        !           251: 
        !           252: 
        !           253: 
        !           254: 
        !           255: 9
        !           256: 
        !           257: 9                                   Printed: January 31, 1984
        !           258: 
        !           259: 
        !           260: 
        !           261: 
        !           262: 
        !           263: 
        !           264: 
        !           265: Special Functions                                        4-3
        !           266: 
        !           267: 
        !           268: 
        !           269:     ____________________________________________________
        !           270: 
        !           271:     Here are two ways of defining the same function:
        !           272:     ->(_d_e_f_u_n _f_a_t_e (_p_e_r_s_o_n_n_a)
        !           273:             (_c_a_s_e_q _p_e_r_s_o_n_n_a
        !           274:               (_c_o_w '(_j_u_m_p_e_d _o_v_e_r _t_h_e _m_o_o_n))
        !           275:               (_c_a_t '(_p_l_a_y_e_d _n_e_r_o))
        !           276:               ((_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))
        !           277:               (_t '(_l_i_v_e_d _h_a_p_p_i_l_y _e_v_e_r _a_f_t_e_r))))
        !           278:     fate
        !           279:     ->(_d_e_f_u_n _f_a_t_e (_p_e_r_s_o_n_n_a)
        !           280:             (_c_o_n_d
        !           281:                     ((_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))
        !           282:                     ((_e_q _p_e_r_s_o_n_n_a '_c_a_t) '(_p_l_a_y_e_d _n_e_r_o))
        !           283:                     ((_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))
        !           284:                     (_t '(_l_i_v_e_d _h_a_p_p_i_l_y _e_v_e_r _a_f_t_e_r))))
        !           285:     fate
        !           286:     ____________________________________________________
        !           287: 
        !           288: 
        !           289: 
        !           290: 
        !           291: (catch g_exp [ls_tag])
        !           292: 
        !           293:      WHERE:   if ls_tag is not given, it is  assumed  to  be
        !           294:               nil.
        !           295: 
        !           296:      RETURNS: the result of (*_c_a_t_c_h '_l_s__t_a_g _g__e_x_p)
        !           297: 
        !           298:      NOTE: catch is defined as a macro.
        !           299: 
        !           300: (*catch 'ls_tag g_exp)
        !           301: 
        !           302:      WHERE:   ls_tag is either a symbol or a  list  of  sym-
        !           303:               bols.
        !           304: 
        !           305:      RETURNS: the result of evaluating g_exp  or  the  value
        !           306:               thrown during the evaluation of g_exp.
        !           307: 
        !           308:      SIDE EFFECT: this first sets up a `catch frame' on  the
        !           309:                   lisp  runtime  stack.   Then  it begins to
        !           310:                   evaluate g_exp.  If g_exp  evaluates  nor-
        !           311:                   mally,  its  value  is returned.  If, how-
        !           312:                   ever, a value is thrown during the evalua-
        !           313:                   tion of g_exp then this *catch will return
        !           314:                   with that value if one of these  cases  is
        !           315:                   true:
        !           316: 
        !           317:      (1)  the tag thrown to is ls_tag
        !           318: 
        !           319:      (2)  ls_tag is a list and the tag thrown to is a member
        !           320:           of this list
        !           321: 
        !           322: 
        !           323:                                    Printed: January 31, 1984
        !           324: 
        !           325: 
        !           326: 
        !           327: 
        !           328: 
        !           329: 
        !           330: 
        !           331: Special Functions                                        4-4
        !           332: 
        !           333: 
        !           334:      (3)  ls_tag is nil.
        !           335: 
        !           336:      NOTE: Errors are  implemented  as  a  special  kind  of
        !           337:            throw.   A  catch  with  no tag will not catch an
        !           338:            error but a catch whose tag  is  the  error  type
        !           339:            will  catch  that  type of error.  See Chapter 10
        !           340:            for more information.
        !           341: 
        !           342: (comment [g_arg ...])
        !           343: 
        !           344:      RETURNS: the symbol comment.
        !           345: 
        !           346:      NOTE: This does absolutely nothing.
        !           347: 
        !           348: (cond [l_clause1 ...])
        !           349: 
        !           350:      RETURNS: the last value evaluated in the  first  clause
        !           351:               satisfied.   If  no clauses are satisfied then
        !           352:               nil is returned.
        !           353: 
        !           354:      NOTE: This is  the  basic  conditional  `statement'  in
        !           355:            lisp.   The  clauses  are  processed from left to
        !           356:            right.   The  first  element  of  a   clause   is
        !           357:            evaluated.   If  it evaluated to a non-null value
        !           358:            then that clause is satisfied and  all  following
        !           359:            elements  of that clause are evaluated.  The last
        !           360:            value computed is returned as the  value  of  the
        !           361:            cond.  If there is just one element in the clause
        !           362:            then its value is returned.  If the first element
        !           363:            of a clause evaluates to nil, then the other ele-
        !           364:            ments of that clause are not  evaluated  and  the
        !           365:            system moves to the next clause.
        !           366: 
        !           367: (cvttointlisp)
        !           368: 
        !           369:      SIDE EFFECT: The reader is modified to conform with the
        !           370:                   Interlisp syntax.  The character % is made
        !           371:                   the escape character and special  meanings
        !           372:                   for  comma,  backquote  and  backslash are
        !           373:                   removed. Also the reader is told  to  con-
        !           374:                   vert upper case to lower case.
        !           375: 
        !           376: 
        !           377: 
        !           378: 
        !           379: 
        !           380: 
        !           381: 
        !           382: 
        !           383: 
        !           384: 
        !           385: 
        !           386: 9
        !           387: 
        !           388: 9                                   Printed: January 31, 1984
        !           389: 
        !           390: 
        !           391: 
        !           392: 
        !           393: 
        !           394: 
        !           395: 
        !           396: Special Functions                                        4-5
        !           397: 
        !           398: 
        !           399: (cvttofranzlisp)
        !           400: 
        !           401:      SIDE EFFECT: FRANZ LISP's default syntax is reinstated.
        !           402:                   One  would  run this function after having
        !           403:                   run any of  the  other  _c_v_t_t_o-  functions.
        !           404:                   Backslash  is  made  the escape character,
        !           405:                   super-brackets work again, and the  reader
        !           406:                   distinguishes   between  upper  and  lower
        !           407:                   case.
        !           408: 
        !           409: (cvttomaclisp)
        !           410: 
        !           411:      SIDE EFFECT: The reader is  modified  to  conform  with
        !           412:                   Maclisp  syntax.   The character / is made
        !           413:                   the escape character and the special mean-
        !           414:                   ings for backslash, left and right bracket
        !           415:                   are removed.  The  reader  is  made  case-
        !           416:                   insensitive.
        !           417: 
        !           418: (cvttoucilisp)
        !           419: 
        !           420:      SIDE EFFECT: The reader is modified to conform with UCI
        !           421:                   Lisp  syntax.  The character / is made the
        !           422:                   escape character, tilde is made  the  com-
        !           423:                   ment character, exclamation point takes on
        !           424:                   the  unquote  function  normally  held  by
        !           425:                   comma,  and  backslash,  comma,  semicolon
        !           426:                   become normal characters.  Here  too,  the
        !           427:                   reader is made case-insensitive.
        !           428: 
        !           429: (debug s_msg)
        !           430: 
        !           431:      SIDE EFFECT: Enter  the  Fixit  package  described   in
        !           432:                   Chapter  15.   This  package allows you to
        !           433:                   examine the evaluation  stack  in  detail.
        !           434:                   To  leave the Fixit package type 'ok'.
        !           435: 
        !           436: (debugging 'g_arg)
        !           437: 
        !           438:      SIDE EFFECT: If g_arg is non-null,  Franz  unlinks  the
        !           439:                   transfer  tables, does a (*_r_s_e_t _t) to turn
        !           440:                   on  evaluation  monitoring  and  sets  the
        !           441:                   all-error  catcher  (ER%all)  to be _d_e_b_u_g-
        !           442:                   _e_r_r-_h_a_n_d_l_e_r.  If g_arg is nil, all of  the
        !           443:                   above changes are undone.
        !           444: 
        !           445: 
        !           446: 
        !           447: 
        !           448: 
        !           449: 
        !           450: 
        !           451: 9
        !           452: 
        !           453: 9                                   Printed: January 31, 1984
        !           454: 
        !           455: 
        !           456: 
        !           457: 
        !           458: 
        !           459: 
        !           460: 
        !           461: Special Functions                                        4-6
        !           462: 
        !           463: 
        !           464: (declare [g_arg ...])
        !           465: 
        !           466:      RETURNS: nil
        !           467: 
        !           468:      NOTE: this is a no-op to the evaluator.  It has special
        !           469:            meaning to the compiler (see Chapter 12).
        !           470: 
        !           471: (def s_name (s_type l_argl g_exp1 ...))
        !           472: 
        !           473:      WHERE:   s_type is one of  lambda,  nlambda,  macro  or
        !           474:               lexpr.
        !           475: 
        !           476:      RETURNS: s_name
        !           477: 
        !           478:      SIDE EFFECT: This defines the function  s_name  to  the
        !           479:                   lisp  system.   If  s_type  is  nlambda or
        !           480:                   macro then the argument list  l_argl  must
        !           481:                   contain exactly one non-nil symbol.
        !           482: 
        !           483: (defmacro s_name l_arg g_exp1 ...)
        !           484: (defcmacro s_name l_arg g_exp1 ...)
        !           485: 
        !           486:      RETURNS: s_name
        !           487: 
        !           488:      SIDE EFFECT: This defines the  macro  s_name.  _d_e_f_m_a_c_r_o
        !           489:                   makes  it  easy  to  write macros since it
        !           490:                   makes the syntax just like _d_e_f_u_n.  Further
        !           491:                   information   on  _d_e_f_m_a_c_r_o  is  in  8.3.2.
        !           492:                   _d_e_f_c_m_a_c_r_o defines compiler-only macros, or
        !           493:                   cmacros.  A  cmacro  is stored on the pro-
        !           494:                   perty list of a symbol under the indicator
        !           495:                   cmacro.  Thus a function can have a normal
        !           496:                   definition and a cmacro  definition.   For
        !           497:                   an  example of the use of cmacros, see the
        !           498:                   definitions   of   nthcdr   and   nth   in
        !           499:                   /usr/lib/lisp/common2.l
        !           500: 
        !           501: (defun s_name [s_mtype] ls_argl g_exp1 ... )
        !           502: 
        !           503:      WHERE:   s_mtype is one of fexpr, expr, args or macro.
        !           504: 
        !           505:      RETURNS: s_name
        !           506: 
        !           507:      SIDE EFFECT: This defines the function s_name.
        !           508: 
        !           509:      NOTE: this exists for Maclisp compatibility, it is just
        !           510:            a  macro  which changes the defun form to the def
        !           511:            form.   An  s_mtype  of  fexpr  is  converted  to
        !           512:            nlambda  and of expr to lambda. Macro remains the
        !           513:            same.  If ls_arg1 is a non-nil symbol,  then  the
        !           514:            type  is  assumed  to be lexpr and ls_arg1 is the
        !           515:            symbol which is bound to the number of args  when
        !           516:            the function is entered.
        !           517: 
        !           518: 
        !           519:                                    Printed: January 31, 1984
        !           520: 
        !           521: 
        !           522: 
        !           523: 
        !           524: 
        !           525: 
        !           526: 
        !           527: Special Functions                                        4-7
        !           528: 
        !           529: 
        !           530:            For compatibility with  the  Lisp  Machine  Lisp,
        !           531:            there are three types of optional parameters that
        !           532:            can occur in ls_argl:   &_o_p_t_i_o_n_a_l  declares  that
        !           533:            the  following  symbols  are optional, and may or
        !           534:            may not appear in the argument list to the  func-
        !           535:            tion, &_r_e_s_t _s_y_m_b_o_l declares that all forms in the
        !           536:            function call that are not accounted for by  pre-
        !           537:            vious  lambda bindings are to be assigned to _s_y_m_-
        !           538:            _b_o_l, and &_a_u_x _f_o_r_m_1 ... _f_o_r_m_n declares  that  the
        !           539:            _f_o_r_m_i  are either symbols, in which case they are
        !           540:            lambda bound to nil, or lists, in which case  the
        !           541:            first  element of the list is lambda bound to the
        !           542:            second, evaluated element.
        !           543: 
        !           544: 
        !           545:     ____________________________________________________
        !           546: 
        !           547:     ; _d_e_f and _d_e_f_u_n here are used to define identical functions
        !           548:     ; you can decide for yourself which is easier to use.
        !           549:     -> (_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))))
        !           550:     append1
        !           551: 
        !           552:     -> (_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)))
        !           553:     append1
        !           554: 
        !           555:     ; Using the & forms...
        !           556:     -> (_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)
        !           557:             (_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
        !           558:                             "_c _i_s " _c _N))
        !           559:             (_m_s_g "_r_e_s_t _i_s " _z _N
        !           560:                  "_r_e_t_v_a_l _i_s " _r_e_t_v_a_l _N))
        !           561:     test
        !           562:     -> (_t_e_s_t _1 _2 _3 _4)
        !           563:     Optional arg present
        !           564:     c is 3
        !           565:     rest is (4)
        !           566:     retval is 0
        !           567:     ____________________________________________________
        !           568: 
        !           569: 
        !           570: 
        !           571: 
        !           572: 
        !           573: 
        !           574: 
        !           575: 
        !           576: 
        !           577: 
        !           578: 
        !           579: 
        !           580: 
        !           581: 
        !           582: 9
        !           583: 
        !           584: 9                                   Printed: January 31, 1984
        !           585: 
        !           586: 
        !           587: 
        !           588: 
        !           589: 
        !           590: 
        !           591: 
        !           592: Special Functions                                        4-8
        !           593: 
        !           594: 
        !           595: (defvar s_variable ['g_init])
        !           596: 
        !           597:      RETURNS: s_variable.
        !           598: 
        !           599:      NOTE: This form is put at the top level in files,  like
        !           600:            _d_e_f_u_n.
        !           601: 
        !           602:      SIDE EFFECT: This declares s_variable to be special. If
        !           603:                   g_init   is   present  and  s_variable  is
        !           604:                   unbound  when  the  file   is   read   in,
        !           605:                   s_variable  will  be  set  to the value of
        !           606:                   g_init.  An advantage  of  `(defvar  foo)'
        !           607:                   over  `(declare (special foo))' is that if
        !           608:                   a file containing defvars  is  loaded  (or
        !           609:                   fasl'ed)  in during compilation, the vari-
        !           610:                   ables mentioned in the  defvar's  will  be
        !           611:                   declared  special.   The  only way to have
        !           612:                   that effect with `(declare (special foo))'
        !           613:                   is to _i_n_c_l_u_d_e the file.
        !           614: 
        !           615: (do l_vrbs l_test g_exp1 ...)
        !           616: 
        !           617:      RETURNS: the last form in the cdr of l_test  evaluated,
        !           618:               or  a  value  explicitly  given  by  a  return
        !           619:               evaluated within the do body.
        !           620: 
        !           621:      NOTE: This is the basic iteration form for FRANZ  LISP.
        !           622:            l_vrbs  is a list of zero or more var-init-repeat
        !           623:            forms.  A var-init-repeat form looks like:
        !           624:                 (s_name [g_init [g_repeat]])
        !           625:            There  are  three  cases  depending  on  what  is
        !           626:            present  in the form.  If just s_name is present,
        !           627:            this means that when the do is entered, s_name is
        !           628:            lambda-bound  to nil and is never modified by the
        !           629:            system (though the program is certainly  free  to
        !           630:            modify    its    value).     If   the   form   is
        !           631:            (s_name 'g_init) then the only difference is that
        !           632:            s_name  is  lambda-bound  to  the value of g_init
        !           633:            instead of nil.  If g_repeat is also present then
        !           634:            s_name is lambda-bound to g_init when the loop is
        !           635:            entered and after each pass through the  do  body
        !           636:            s_name is  bound to the value of g_repeat.
        !           637:            l_test is either nil or has the form  of  a  cond
        !           638:            clause.   If  it  is nil then the do body will be
        !           639:            evaluated only once and the do will  return  nil.
        !           640:            Otherwise,  before  the  do body is evaluated the
        !           641:            car of l_test is evaluated and if the  result  is
        !           642:            non-null,  this  signals  an  end to the looping.
        !           643:            Then  the  rest  of  the  forms  in  l_test   are
        !           644:            evaluated  and  the  value  of  the  last  one is
        !           645:            returned as the value of the do.  If the  cdr  of
        !           646:            l_test  is nil, then nil is returned -- thus this
        !           647:            is not exactly like a cond clause.
        !           648: 
        !           649: 
        !           650:                                    Printed: January 31, 1984
        !           651: 
        !           652: 
        !           653: 
        !           654: 
        !           655: 
        !           656: 
        !           657: 
        !           658: Special Functions                                        4-9
        !           659: 
        !           660: 
        !           661:            g_exp1 and those forms  which  follow  constitute
        !           662:            the  do  body.  A do body is like a prog body and
        !           663:            thus may have labels and one may  use  the  func-
        !           664:            tions go and return.
        !           665:            The sequence of evaluations is this:
        !           666: 
        !           667:      (1)  the init forms are evaluated  left  to  right  and
        !           668:           stored in temporary locations.
        !           669: 
        !           670:      (2)  Simultaneously all do variables are  lambda  bound
        !           671:           to the value of their init forms or nil.
        !           672: 
        !           673:      (3)  If l_test is non-null, then the car  is  evaluated
        !           674:           and  if  it  is non-null, the rest of the forms in
        !           675:           l_test  are  evaluated  and  the  last  value   is
        !           676:           returned as the value of the do.
        !           677: 
        !           678:      (4)  The forms in the do body  are  evaluated  left  to
        !           679:           right.
        !           680: 
        !           681:      (5)  If l_test is nil the do function returns with  the
        !           682:           value nil.
        !           683: 
        !           684:      (6)  The repeat forms are evaluated and saved  in  tem-
        !           685:           porary locations.
        !           686: 
        !           687:      (7)  The variables with repeat forms are simultaneously
        !           688:           bound to the values of those forms.
        !           689: 
        !           690:      (8)  Go to step 3.
        !           691: 
        !           692:      NOTE: there is an alternate form of  do  which  can  be
        !           693:            used  when  there is only one do variable.  It is
        !           694:            described next.
        !           695: 
        !           696: 
        !           697: 
        !           698: 
        !           699: 
        !           700: 
        !           701: 
        !           702: 
        !           703: 
        !           704: 
        !           705: 
        !           706: 
        !           707: 
        !           708: 
        !           709: 
        !           710: 
        !           711: 
        !           712: 
        !           713: 9
        !           714: 
        !           715: 9                                   Printed: January 31, 1984
        !           716: 
        !           717: 
        !           718: 
        !           719: 
        !           720: 
        !           721: 
        !           722: 
        !           723: Special Functions                                       4-10
        !           724: 
        !           725: 
        !           726: 
        !           727:     ____________________________________________________
        !           728: 
        !           729:     ; this is  a simple function which numbers the elements of a list.
        !           730:     ; It uses a _d_o function with two local variables.
        !           731:     -> (_d_e_f_u_n _p_r_i_n_t_e_m (_l_i_s)
        !           732:                  (_d_o ((_x_x _l_i_s (_c_d_r _x_x))
        !           733:                       (_i _1 (_1+ _i)))
        !           734:                      ((_n_u_l_l _x_x) (_p_a_t_o_m "_a_l_l _d_o_n_e") (_t_e_r_p_r))
        !           735:                      (_p_r_i_n_t _i)
        !           736:                      (_p_a_t_o_m ": ")
        !           737:                      (_p_r_i_n_t (_c_a_r _x_x))
        !           738:                      (_t_e_r_p_r)))
        !           739:     printem
        !           740:     -> (_p_r_i_n_t_e_m '(_a _b _c _d))
        !           741:     1: a
        !           742:     2: b
        !           743:     3: c
        !           744:     4: d
        !           745:     all done
        !           746:     nil
        !           747:     ->
        !           748:     ____________________________________________________
        !           749: 
        !           750: 
        !           751: 
        !           752: 
        !           753: (do s_name g_init g_repeat g_test g_exp1 ...)
        !           754: 
        !           755:      NOTE: this is another, less general,  form of  do.   It
        !           756:            is evaluated by:
        !           757: 
        !           758:      (1)  evaluating g_init
        !           759: 
        !           760:      (2)  lambda binding s_name to value of g_init
        !           761: 
        !           762:      (3)  g_test is evaluated and if it is not  nil  the  do
        !           763:           function returns with nil.
        !           764: 
        !           765:      (4)  the do body is evaluated beginning at g_exp1.
        !           766: 
        !           767:      (5)  the repeat form is evaluated and stored in s_name.
        !           768: 
        !           769:      (6)  go to step 3.
        !           770: 
        !           771:      RETURNS: nil
        !           772: 
        !           773: 
        !           774: 
        !           775: 
        !           776: 
        !           777: 
        !           778: 9
        !           779: 
        !           780: 9                                   Printed: January 31, 1984
        !           781: 
        !           782: 
        !           783: 
        !           784: 
        !           785: 
        !           786: 
        !           787: 
        !           788: Special Functions                                       4-11
        !           789: 
        !           790: 
        !           791: (environment [l_when1 l_what1 l_when2 l_what2 ...])
        !           792: (environment-maclisp [l_when1 l_what1 l_when2 l_what2 ...])
        !           793: (environment-lmlisp [l_when1 l_what1 l_when2 l_what2 ...])
        !           794: 
        !           795:      WHERE:   the when's  are  a  subset  of  (eval  compile
        !           796:               load),  and  the symbols have the same meaning
        !           797:               as they do in 'eval-when'.
        !           798: 
        !           799:               The what's may be
        !           800:                       (files file1 file2 ... fileN),
        !           801:               which insure that the named files are  loaded.
        !           802:               To  see  if  file_i  is  loaded, it looks for a
        !           803:               'version'  property  under  file_i's   property
        !           804:               list.   Thus  to prevent multiple loading, you
        !           805:               should put
        !           806:                       (putprop 'myfile t 'version),
        !           807:               at the end of myfile.l.
        !           808: 
        !           809:               Another acceptable form for a what is
        !           810:               (syntax type)
        !           811:               Where type is either maclisp,  intlisp,  ucil-
        !           812:               isp, franzlisp.
        !           813: 
        !           814:      SIDE EFFECT: _e_n_v_i_r_o_n_m_e_n_t-_m_a_c_l_i_s_p sets  the  environment
        !           815:                   to that which `liszt -m' would generate.
        !           816: 
        !           817:                   _e_n_v_i_r_o_n_m_e_n_t-_l_m_l_i_s_p   sets  up   the   lisp
        !           818:                   machine  environment. This is like maclisp
        !           819:                   but it has additional macros.
        !           820: 
        !           821:                   For these specialized  environments,  only
        !           822:                   the     files    clauses    are    useful.
        !           823:                           (environment-maclisp      (compile
        !           824:                   eval) (files foo bar))
        !           825: 
        !           826:      RETURNS: the last list of files requested.
        !           827: 
        !           828: (err ['s_value [nil]])
        !           829: 
        !           830:      RETURNS: nothing (it never returns).
        !           831: 
        !           832:      SIDE EFFECT: This causes an error and if this error  is
        !           833:                   caught  by an _e_r_r_s_e_t then that _e_r_r_s_e_t will
        !           834:                   return s_value instead  of  nil.   If  the
        !           835:                   second  arg  is given, then it must be nil
        !           836:                   (MAClisp compatibility).
        !           837: 
        !           838: 
        !           839: 
        !           840: 
        !           841: 
        !           842: 
        !           843: 9
        !           844: 
        !           845: 9                                   Printed: January 31, 1984
        !           846: 
        !           847: 
        !           848: 
        !           849: 
        !           850: 
        !           851: 
        !           852: 
        !           853: Special Functions                                       4-12
        !           854: 
        !           855: 
        !           856: (error ['s_message1 ['s_message2]])
        !           857: 
        !           858:      RETURNS: nothing (it never returns).
        !           859: 
        !           860:      SIDE EFFECT: s_message1 and s_message2 are  _p_a_t_o_med  if
        !           861:                   they  are  given  and  then  _e_r_r is called
        !           862:                   (with  no  arguments),  which  causes   an
        !           863:                   error.
        !           864: 
        !           865: (errset g_expr [s_flag])
        !           866: 
        !           867:      RETURNS: a list of one  element,  which  is  the  value
        !           868:               resulting from evaluating g_expr.  If an error
        !           869:               occurs during the evaluation of  g_expr,  then
        !           870:               the locus of control will return to the _e_r_r_s_e_t
        !           871:               which will then return nil (unless  the  error
        !           872:               was  caused  by a call to _e_r_r, with a non-null
        !           873:               argument).
        !           874: 
        !           875:      SIDE EFFECT: S_flag  is  evaluated  before  g_expr   is
        !           876:                   evaluated. If s_flag is not given, then it
        !           877:                   is assumed to be t.  If  an  error  occurs
        !           878:                   during   the  evaluation  of  g_expr,  and
        !           879:                   s_flag evaluated to a non-null value, then
        !           880:                   the  error  message  associated  with  the
        !           881:                   error is printed before control returns to
        !           882:                   the errset.
        !           883: 
        !           884: (eval 'g_val ['x_bind-pointer])
        !           885: 
        !           886:      RETURNS: the result of evaluating g_val.
        !           887: 
        !           888:      NOTE: The evaluator evaluates g_val in this way:
        !           889:            If g_val is a symbol, then the evaluator  returns
        !           890:            its  value.   If  g_val had never been assigned a
        !           891:            value, then this  causes  an  `Unbound  Variable'
        !           892:            error.   If  x_bind-pointer  is  given,  then the
        !           893:            variable  is  evaluated  with  respect  to   that
        !           894:            pointer  (see  _e_v_a_l_f_r_a_m_e  for  details  on  bind-
        !           895:            pointers).
        !           896: 
        !           897:            If g_val is of type  value,  then  its  value  is
        !           898:            returned.   If  g_val  is  of any other type than
        !           899:            list, g_val is returned.
        !           900: 
        !           901:            If g_val is a list object then g_val is either  a
        !           902:            function  call  or array reference.  Let g_car be
        !           903:            the  first  element  of  g_val.   We  continually
        !           904:            evaluate g_car until we end up with a symbol with
        !           905:            a non-null  function  binding  or  a  non-symbol.
        !           906:            Call what we end up with: g_func.
        !           907: 
        !           908:            G_func must be one of three types:  list,  binary
        !           909: 
        !           910: 
        !           911:                                    Printed: January 31, 1984
        !           912: 
        !           913: 
        !           914: 
        !           915: 
        !           916: 
        !           917: 
        !           918: 
        !           919: Special Functions                                       4-13
        !           920: 
        !           921: 
        !           922:            or array.  If it is a list then the first element
        !           923:            of the list, which we shall call g_functype, must
        !           924:            be  either  lambda,  nlambda, macro or lexpr.  If
        !           925:            g_func is a binary, then its discipline, which we
        !           926:            shall call g_functype, is either lambda, nlambda,
        !           927:            macro or a string.  If g_func is  an  array  then
        !           928:            this  form  is evaluated specially, see Chapter 9
        !           929:            on arrays.  If g_func is a list or  binary,  then
        !           930:            g_functype  will  determine  how the arguments to
        !           931:            this function, the cdr of g_val,  are  processed.
        !           932:            If g_functype is a string, then this is a foreign
        !           933:            function call (see 8.5 for more details).
        !           934: 
        !           935:            If g_functype is lambda or lexpr,  the  arguments
        !           936:            are  evaluated  (by calling _e_v_a_l recursively) and
        !           937:            stacked.  If g_functype is nlambda then the argu-
        !           938:            ment  list  is  stacked.   If g_functype is macro
        !           939:            then the entire form, g_val is stacked.
        !           940: 
        !           941:            Next, the formal variables are lambda bound.  The
        !           942:            formal  variables  are  the  cadr  of g_func.  If
        !           943:            g_functype is  nlambda,  lexpr  or  macro,  there
        !           944:            should  only  be one formal variable.  The values
        !           945:            on the stack are lambda bound to the formal vari-
        !           946:            ables  except  in  the case of a lexpr, where the
        !           947:            number of actual arguments is bound to the formal
        !           948:            variable.
        !           949: 
        !           950:            After  the  binding  is  done,  the  function  is
        !           951:            invoked,  either by jumping to the entry point in
        !           952:            the case of a binary or by evaluating the list of
        !           953:            forms  beginning  at  cddr g_func.  The result of
        !           954:            this function invocation is returned as the value
        !           955:            of the call to eval.
        !           956: 
        !           957: (evalframe 'x_pdlpointer)
        !           958: 
        !           959:      RETURNS: an evalframe  descriptor  for  the  evaluation
        !           960:               frame    just    before    x_pdlpointer.    If
        !           961:               x_pdlpointer is nil, it returns the evaluation
        !           962:               frame  of  the  frame  just before the current
        !           963:               call to _e_v_a_l_f_r_a_m_e.
        !           964: 
        !           965:      NOTE: An evalframe descriptor describes a call to _e_v_a_l,
        !           966:            _a_p_p_l_y or _f_u_n_c_a_l_l.  The form of the descriptor is
        !           967:            (_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-
        !           968:            _i_n_d_e_x _l_b_o_t-_i_n_d_e_x)
        !           969:            where type is `eval' if this describes a call  to
        !           970:            _e_v_a_l  or  `apply'  if  this is a call to _a_p_p_l_y or
        !           971:            _f_u_n_c_a_l_l.    pdl-pointer   is   a   number   which
        !           972:            describes this context. It can be passed to _e_v_a_l_-
        !           973:            _f_r_a_m_e to obtain the next descriptor  and  can  be
        !           974:            passed  to  _f_r_e_t_u_r_n  to  cause a return from this
        !           975: 
        !           976: 
        !           977:                                    Printed: January 31, 1984
        !           978: 
        !           979: 
        !           980: 
        !           981: 
        !           982: 
        !           983: 
        !           984: 
        !           985: Special Functions                                       4-14
        !           986: 
        !           987: 
        !           988:            context.  bind-pointer is the  size  of  variable
        !           989:            binding  stack  when  this  evaluation began. The
        !           990:            bind-pointer can be given as a second argument to
        !           991:            _e_v_a_l  to  order to evaluate variables in the same
        !           992:            context as this  evaluation. If  type  is  `eval'
        !           993:            then  expression  will  have  the form (_f_u_n_c_t_i_o_n-
        !           994:            _n_a_m_e _a_r_g_1 ...).  If type is `apply' then  expres-
        !           995:            sion    will    have    the    form    (_f_u_n_c_t_i_o_n-
        !           996:            _n_a_m_e (_a_r_g_1 ...)).  np-index  and  lbot-index  are
        !           997:            pointers  into  the argument stack (also known as
        !           998:            the _n_a_m_e_s_t_a_c_k array) at the time of call.   lbot-
        !           999:            index  points  to  the  first  argument, np-index
        !          1000:            points one beyond the last argument.
        !          1001:            In order for there to be enough  information  for
        !          1002:            _e_v_a_l_f_r_a_m_e to return, you must call (*_r_s_e_t _t).
        !          1003: 
        !          1004:      EXAMPLE: (_p_r_o_g_n (_e_v_a_l_f_r_a_m_e _n_i_l))
        !          1005:               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
        !          1006:               _n_i_l)) _1 _8 _7)
        !          1007: 
        !          1008: (evalhook 'g_form 'su_evalfunc ['su_funcallfunc])
        !          1009: 
        !          1010:      RETURNS: the result of evaluating g_form  after  lambda
        !          1011:               binding  `evalhook'  to su_evalfunc and, if it
        !          1012:               is  given,  lambda  binding  `funcallhook'  to
        !          1013:               su_funcallhook.
        !          1014: 
        !          1015:      NOTE: As explained in 14.4, the function _e_v_a_l may  pass
        !          1016:            the  job  of  evaluating  a form to a user `hook'
        !          1017:            function when  various  switches  are  set.   The
        !          1018:            hook  function  normally  prints  the  form to be
        !          1019:            evaluated on the terminal and then  evaluates  it
        !          1020:            by  calling  _e_v_a_l_h_o_o_k.   _E_v_a_l_h_o_o_k does the lambda
        !          1021:            binding mentioned above and then  calls  _e_v_a_l  to
        !          1022:            evaluate  the  form  after  setting  an  internal
        !          1023:            switch to tell _e_v_a_l not to call the  user's  hook
        !          1024:            function  just  this  one  time.  This allows the
        !          1025:            evaluation process to advance one  step  and  yet
        !          1026:            insure  that  further  calls  to  _e_v_a_l will cause
        !          1027:            traps to the hook  function  (if  su_evalfunc  is
        !          1028:            non-null).
        !          1029:            In order for  _e_v_a_l_h_o_o_k  to  work,  (*_r_s_e_t _t)  and
        !          1030:            (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t)  must  have been done previ-
        !          1031:            ously.
        !          1032: 
        !          1033: 
        !          1034: 
        !          1035: 
        !          1036: 
        !          1037: 
        !          1038: 
        !          1039: 
        !          1040: 9
        !          1041: 
        !          1042: 9                                   Printed: January 31, 1984
        !          1043: 
        !          1044: 
        !          1045: 
        !          1046: 
        !          1047: 
        !          1048: 
        !          1049: 
        !          1050: Special Functions                                       4-15
        !          1051: 
        !          1052: 
        !          1053: (exec s_arg1 ...)
        !          1054: 
        !          1055:      RETURNS: the result of forking and executing  the  com-
        !          1056:               mand   named   by   concatenating  the  s_arg_i
        !          1057:               together with spaces in between.
        !          1058: 
        !          1059: (exece 's_fname ['l_args ['l_envir]])
        !          1060: 
        !          1061:      RETURNS: the error code  from  the  system  if  it  was
        !          1062:               unable  to  execute  the  command s_fname with
        !          1063:               arguments l_args and with the environment  set
        !          1064:               up  as specified in l_envir.  If this function
        !          1065:               is successful, it will not return, instead the
        !          1066:               lisp  system  will be overlaid by the new com-
        !          1067:               mand.
        !          1068: 
        !          1069: (freturn 'x_pdl-pointer 'g_retval)
        !          1070: 
        !          1071:      RETURNS: g_retval from  the  context  given  by  x_pdl-
        !          1072:               pointer.
        !          1073: 
        !          1074:      NOTE: A  pdl-pointer  denotes  a   certain   expression
        !          1075:            currently  being evaluated. The pdl-pointer for a
        !          1076:            given expression can be obtained from _e_v_a_l_f_r_a_m_e.
        !          1077: 
        !          1078: (frexp 'f_arg)
        !          1079: 
        !          1080:      RETURNS: a  list  cell  (_e_x_p_o_n_e_n_t  .  _m_a_n_t_i_s_s_a)   which
        !          1081:               represents the given flonum
        !          1082: 
        !          1083:      NOTE: The exponent will be a fixnum, the mantissa a  56
        !          1084:            bit bignum.  If you think of the the binary point
        !          1085:            occurring right  after  the  high  order  bit  of
        !          1086:            mantissa, then f_arg = 2[exponent] * mantissa.
        !          1087: 
        !          1088: (funcall 'u_func ['g_arg1 ...])
        !          1089: 
        !          1090:      RETURNS: the value of applying function u_func  to  the
        !          1091:               arguments  g_arg_i  and  then  evaluating  that
        !          1092:               result if u_func is a macro.
        !          1093: 
        !          1094:      NOTE: If u_func is a macro or nlambda then there should
        !          1095:            be only one g_arg.  _f_u_n_c_a_l_l is the function which
        !          1096:            the evaluator uses to evaluate lists.  If _f_o_o  is
        !          1097:            a    lambda    or    lexpr    or    array,   then
        !          1098:            (_f_u_n_c_a_l_l '_f_o_o '_a '_b '_c)    is    equivalent    to
        !          1099:            (_f_o_o '_a '_b '_c).    If   _f_o_o  is  a  nlambda  then
        !          1100:            (_f_u_n_c_a_l_l '_f_o_o '(_a _b _c)) is equivalent to (_f_o_o _a _b
        !          1101:            _c).    Finally,   if   _f_o_o   is   a   macro  then
        !          1102:            (_f_u_n_c_a_l_l '_f_o_o '(_f_o_o _a _b _c))  is   equivalent   to
        !          1103:            (_f_o_o _a _b _c).
        !          1104: 
        !          1105: 9
        !          1106: 
        !          1107: 9                                   Printed: January 31, 1984
        !          1108: 
        !          1109: 
        !          1110: 
        !          1111: 
        !          1112: 
        !          1113: 
        !          1114: 
        !          1115: Special Functions                                       4-16
        !          1116: 
        !          1117: 
        !          1118: (funcallhook 'l_form 'su_funcallfunc ['su_evalfunc])
        !          1119: 
        !          1120:      RETURNS: the result of _f_u_n_c_a_l_ling the  (_c_a_r _l__f_o_r_m)  on
        !          1121:               the   already   evaluated   arguments  in  the
        !          1122:               (_c_d_r _l__f_o_r_m)  after   lambda   binding   `fun-
        !          1123:               callhook'  to  su_funcallfunc  and,  if  it is
        !          1124:               given,   lambda    binding    `evalhook'    to
        !          1125:               su_evalhook.
        !          1126: 
        !          1127:      NOTE: This function is designed to continue the evalua-
        !          1128:            tion  process  with  as  little  work as possible
        !          1129:            after a funcallhook trap has occurred. It is  for
        !          1130:            this  reason  that the form of l_form is unortho-
        !          1131:            dox: its _c_a_r is the name of the function to  call
        !          1132:            and  its  _c_d_r  are  a  list of arguments to stack
        !          1133:            (without evaluating  again)  before  calling  the
        !          1134:            given function.  After stacking the arguments but
        !          1135:            before calling _f_u_n_c_a_l_l an internal switch is  set
        !          1136:            to  prevent  _f_u_n_c_a_l_l from passing the job of fun-
        !          1137:            calling to su_funcallfunc.  If _f_u_n_c_a_l_l is  called
        !          1138:            recursively   in   funcalling   l_form   and   if
        !          1139:            su_funcallfunc is non-null, then the arguments to
        !          1140:            _f_u_n_c_a_l_l  will actually be given to su_funcallfunc
        !          1141:            (a lexpr) to be funcalled.
        !          1142:            In order for  _e_v_a_l_h_o_o_k  to  work,  (*_r_s_e_t _t)  and
        !          1143:            (_s_s_t_a_t_u_s _e_v_a_l_h_o_o_k _t)  must  have been done previ-
        !          1144:            ously.  A more detailed description  of  _e_v_a_l_h_o_o_k
        !          1145:            and _f_u_n_c_a_l_l_h_o_o_k is given in Chapter 14.
        !          1146: 
        !          1147: (function u_func)
        !          1148: 
        !          1149:      RETURNS: the function binding of u_func  if  it  is  an
        !          1150:               symbol   with  a  function  binding  otherwise
        !          1151:               u_func is returned.
        !          1152: 
        !          1153: (getdisc 'y_func)
        !          1154: 
        !          1155:      RETURNS: the discipline of the machine  coded  function
        !          1156:               (either lambda, nlambda or macro).
        !          1157: 
        !          1158: (go g_labexp)
        !          1159: 
        !          1160:      WHERE:   g_labexp is either a symbol or an expression.
        !          1161: 
        !          1162:      SIDE EFFECT: If g_labexp is an expression, that expres-
        !          1163:                   sion  is  evaluated and should result in a
        !          1164:                   symbol.  The locus  of  control  moves  to
        !          1165:                   just  following the symbol g_labexp in the
        !          1166:                   current prog or do body.
        !          1167: 
        !          1168:      NOTE: this is only valid in the context of a prog or do
        !          1169:            body.   The  interpreter  and compiler will allow
        !          1170:            non-local _g_o's although the compiler won't  allow
        !          1171: 
        !          1172: 
        !          1173:                                    Printed: January 31, 1984
        !          1174: 
        !          1175: 
        !          1176: 
        !          1177: 
        !          1178: 
        !          1179: 
        !          1180: 
        !          1181: Special Functions                                       4-17
        !          1182: 
        !          1183: 
        !          1184:            a _g_o to leave a function body.  The compiler will
        !          1185:            not allow g_labexp to be an expression.
        !          1186: 
        !          1187: (if 'g_a 'g_b)
        !          1188: (if 'g_a 'g_b 'g_c ...)
        !          1189: (if 'g_a then  'g_b [...] [elseif 'g_c then 'g_d ...]  [else
        !          1190: 'g_e [...])
        !          1191: (if 'g_a then  'g_b [...] [elseif 'g_c thenret]  [else  'g_d
        !          1192: [...])
        !          1193: 
        !          1194:      NOTE: The various forms of _i_f are intended to be a more
        !          1195:            readable  conditional  statement,  to  be used in
        !          1196:            place of _c_o_n_d.  There are two  varieties  of  _i_f,
        !          1197:            with  keywords,  and  without.   The keyword-less
        !          1198:            variety is inherited from common  Maclisp  usage.
        !          1199:            A  keyword-less, two argument _i_f is equivalent to
        !          1200:            a one-clause _c_o_n_d, i.e. (_c_o_n_d (a b)).   Any other
        !          1201:            keyword-less  _i_f  must  have at least three argu-
        !          1202:            ments.  The first two  arguments  are  the  first
        !          1203:            clause  of the equivalent _c_o_n_d, and all remaining
        !          1204:            arguments are shoved into a second clause  begin-
        !          1205:            ning  with  t.   Thus,  the  second form of _i_f is
        !          1206:            equivalent to
        !          1207:                    (_c_o_n_d (a b) (t c ...)).
        !          1208: 
        !          1209:            The keyword variety has the following grouping of
        !          1210:            arguments:   a   predicate,  a  then-clause,  and
        !          1211:            optional   else-clause.    The    predicate    is
        !          1212:            evaluated,  and  if  the  result  is non-nil, the
        !          1213:            then-clause  will  be  performed,  in  the  sense
        !          1214:            described  below.  Otherwise, (i.e. the result of
        !          1215:            the predicate evaluation was precisely nil),  the
        !          1216:            else-clause will be performed.
        !          1217: 
        !          1218:            Then-clauses will either consist entirely of  the
        !          1219:            single  keyword  thenret,  or will start with the
        !          1220:            keyword then, and be followed  by  at  least  one
        !          1221:            general  expression.   (These general expressions
        !          1222:            must not be one of the keywords.)  To  actuate  a
        !          1223:            thenret  means to cease further evaluation of the
        !          1224:            _i_f, and to return the value of the predicate just
        !          1225:            calculated.  The performance of the longer clause
        !          1226:            means to  evaluate  each  general  expression  in
        !          1227:            turn, and then return the last value calculated.
        !          1228: 
        !          1229:            The else-clause may begin with the  keyword  else
        !          1230:            and  be  followed by at least one general expres-
        !          1231:            sion.  The rendition of this clause is just  like
        !          1232:            that  of a then-clause.  An else-clause may begin
        !          1233:            alternatively with the  keyword  elseif,  and  be
        !          1234:            followed  (recursively)  by  a  predicate,  then-
        !          1235:            clause, and optional else-clause.  Evaluation  of
        !          1236:            this  clause,  is  just evaluation of an _i_f-form,
        !          1237: 
        !          1238: 
        !          1239:                                    Printed: January 31, 1984
        !          1240: 
        !          1241: 
        !          1242: 
        !          1243: 
        !          1244: 
        !          1245: 
        !          1246: 
        !          1247: Special Functions                                       4-18
        !          1248: 
        !          1249: 
        !          1250:            with the same predicate, then- and else-clauses.
        !          1251: 
        !          1252: (I-throw-err 'l_token)
        !          1253: 
        !          1254:      WHERE:   l_token is the _c_d_r of the value returned  from
        !          1255:               a *_c_a_t_c_h with the tag ER%unwind-protect.
        !          1256: 
        !          1257:      RETURNS: nothing (never returns in the current context)
        !          1258: 
        !          1259:      SIDE EFFECT: The error or throw denoted by  l_token  is
        !          1260:                   continued.
        !          1261: 
        !          1262:      NOTE: This function is used to implement _u_n_w_i_n_d-_p_r_o_t_e_c_t
        !          1263:            which allows the processing of a transfer of con-
        !          1264:            trol though a certain context to be  interrupted,
        !          1265:            a  user  function  to  be  executed  and than the
        !          1266:            transfer of control to  continue.   The  form  of
        !          1267:            l_token is either
        !          1268:            (_t _t_a_g _v_a_l_u_e) for a throw or
        !          1269:            (_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
        !          1270:            ...]) for an error.
        !          1271:            This function is not to be used for  implementing
        !          1272:            throws  or errors and is only documented here for
        !          1273:            completeness.
        !          1274: 
        !          1275: (let l_args g_exp1 ... g_exprn)
        !          1276: 
        !          1277:      RETURNS: the result of evaluating  g_exprn  within  the
        !          1278:               bindings given by l_args.
        !          1279: 
        !          1280:      NOTE: l_args is either nil (in which case _l_e_t  is  just
        !          1281:            like  _p_r_o_g_n)  or it is a list of binding objects.
        !          1282:            A binding object is a  list  (_s_y_m_b_o_l _e_x_p_r_e_s_s_i_o_n).
        !          1283:            When a _l_e_t is entered, all of the expressions are
        !          1284:            evaluated and then simultaneously lambda-bound to
        !          1285:            the  corresponding  symbols.   In  effect,  a _l_e_t
        !          1286:            expression  is  just  like  a  lambda  expression
        !          1287:            except  the  symbols and their initial values are
        !          1288:            next to each other, making the expression  easier
        !          1289:            to  understand.  There are some added features to
        !          1290:            the _l_e_t expression: A binding object can just  be
        !          1291:            a   symbol,   in   which   case   the  expression
        !          1292:            corresponding to that  symbol  is  `nil'.   If  a
        !          1293:            binding object is a list and the first element of
        !          1294:            that list is another  list,  then  that  list  is
        !          1295:            assumed  to be a binding template and _l_e_t will do
        !          1296:            a _d_e_s_e_t_q on it.
        !          1297: 
        !          1298: 
        !          1299: 
        !          1300: 
        !          1301: 
        !          1302: 9
        !          1303: 
        !          1304: 9                                   Printed: January 31, 1984
        !          1305: 
        !          1306: 
        !          1307: 
        !          1308: 
        !          1309: 
        !          1310: 
        !          1311: 
        !          1312: Special Functions                                       4-19
        !          1313: 
        !          1314: 
        !          1315: (let* l_args g_exp1 ... g_expn)
        !          1316: 
        !          1317:      RETURNS: the result of evaluating  g_exprn  within  the
        !          1318:               bindings given by l_args.
        !          1319: 
        !          1320:      NOTE: This is identical to _l_e_t except  the  expressions
        !          1321:            in  the  binding  list  l_args  are evaluated and
        !          1322:            bound sequentially instead of in parallel.
        !          1323: 
        !          1324: (lexpr-funcall 'g_function ['g_arg1 ...] 'l_argn)
        !          1325: 
        !          1326:      NOTE: This is a cross between funcall and  apply.   The
        !          1327:            last  argument,  must be a list (possibly empty).
        !          1328:            The element of list arg are stack  and  then  the
        !          1329:            function is funcalled.
        !          1330: 
        !          1331:      EXAMPLE: (lexpr-funcall 'list 'a '(b c d)) is the  same
        !          1332:               as
        !          1333:                (funcall 'list 'a 'b 'c 'd)
        !          1334: 
        !          1335: (listify 'x_count)
        !          1336: 
        !          1337:      RETURNS: a list of x_count  of  the  arguments  to  the
        !          1338:               current function (which must be a lexpr).
        !          1339: 
        !          1340:      NOTE: normally  arguments   1   through   x_count   are
        !          1341:            returned.  If x_count is negative then  a list of
        !          1342:            last abs(x_count) arguments are returned.
        !          1343: 
        !          1344: (map 'u_func 'l_arg1 ...)
        !          1345: 
        !          1346:      RETURNS: l_arg1
        !          1347: 
        !          1348:      NOTE: The function u_func is applied to successive sub-
        !          1349:            lists  of  the  l_arg_i.  All sublists should have
        !          1350:            the same length.
        !          1351: 
        !          1352: (mapc 'u_func 'l_arg1 ...)
        !          1353: 
        !          1354:      RETURNS: l_arg1.
        !          1355: 
        !          1356:      NOTE: The function u_func is applied to successive ele-
        !          1357:            ments  of  the  argument lists.  All of the lists
        !          1358:            should have the same length.
        !          1359: 
        !          1360: 
        !          1361: 
        !          1362: 
        !          1363: 
        !          1364: 
        !          1365: 
        !          1366: 
        !          1367: 9
        !          1368: 
        !          1369: 9                                   Printed: January 31, 1984
        !          1370: 
        !          1371: 
        !          1372: 
        !          1373: 
        !          1374: 
        !          1375: 
        !          1376: 
        !          1377: Special Functions                                       4-20
        !          1378: 
        !          1379: 
        !          1380: (mapcan 'u_func 'l_arg1 ...)
        !          1381: 
        !          1382:      RETURNS: nconc applied to the results of the functional
        !          1383:               evaluations.
        !          1384: 
        !          1385:      NOTE: The function u_func is applied to successive ele-
        !          1386:            ments of the argument lists.  All sublists should
        !          1387:            have the same length.
        !          1388: 
        !          1389: (mapcar 'u_func 'l_arg1 ...)
        !          1390: 
        !          1391:      RETURNS: a list of the values returned from  the  func-
        !          1392:               tional application.
        !          1393: 
        !          1394:      NOTE: the function u_func is applied to successive ele-
        !          1395:            ments of the argument lists.  All sublists should
        !          1396:            have the same length.
        !          1397: 
        !          1398: (mapcon 'u_func 'l_arg1 ...)
        !          1399: 
        !          1400:      RETURNS: nconc applied to the results of the functional
        !          1401:               evaluation.
        !          1402: 
        !          1403:      NOTE: the function u_func is applied to successive sub-
        !          1404:            lists of the argument lists.  All sublists should
        !          1405:            have the same length.
        !          1406: 
        !          1407: (maplist 'u_func 'l_arg1 ...)
        !          1408: 
        !          1409:      RETURNS: a  list  of  the  results  of  the  functional
        !          1410:               evaluations.
        !          1411: 
        !          1412:      NOTE: the function u_func is applied to successive sub-
        !          1413:            lists  of  the  arguments  lists.   All  sublists
        !          1414:            should have the same length.
        !          1415: 
        !          1416:      Readers may find the following summary table useful  in
        !          1417:      remembering  the  differences  between  the six mapping
        !          1418:      functions:
        !          1419: 
        !          1420: 
        !          1421: 8     ________________________________________________________________
        !          1422:                                       Value returned is
        !          1423: 
        !          1424:                          l_arg1   list of results   _n_c_o_n_c of results
        !          1425: 7       Argument to
        !          1426:        functional is
        !          1427: 8    ________________________________________________________________
        !          1428: 
        !          1429:      elements of list    mapc        mapcar             mapcan
        !          1430: 
        !          1431:          sublists        map         maplist            mapcon
        !          1432: 8    ________________________________________________________________
        !          1433: 7   |7|7|7|7|7|7|7|7|
        !          1434: 
        !          1435: 
        !          1436: 
        !          1437: 
        !          1438: 
        !          1439: 
        !          1440: 
        !          1441:                      |7|7|7|7|7|7|7|7|
        !          1442: 
        !          1443: 
        !          1444: 
        !          1445: 
        !          1446: 
        !          1447: 
        !          1448: 
        !          1449:                                                                    |7|7|7|7|7|7|7|7|
        !          1450: 
        !          1451: 
        !          1452: 
        !          1453: 
        !          1454: 
        !          1455: 
        !          1456: 
        !          1457: 
        !          1458: 
        !          1459: 
        !          1460: 
        !          1461: 
        !          1462: 9                                   Printed: January 31, 1984
        !          1463: 
        !          1464: 
        !          1465: 
        !          1466: 
        !          1467: 
        !          1468: 
        !          1469: 
        !          1470: Special Functions                                       4-21
        !          1471: 
        !          1472: 
        !          1473: (mfunction t_entry 's_disc)
        !          1474: 
        !          1475:      RETURNS: a lisp  object  of  type  binary  composed  of
        !          1476:               t_entry and s_disc.
        !          1477: 
        !          1478:      NOTE: t_entry is a pointer to the machine  code  for  a
        !          1479:            function,  and  s_disc  is  the  discipline (e.g.
        !          1480:            lambda).
        !          1481: 
        !          1482: (oblist)
        !          1483: 
        !          1484:      RETURNS: a list of all symbols on the oblist.
        !          1485: 
        !          1486: (or [g_arg1 ... ])
        !          1487: 
        !          1488:      RETURNS: the value of the first non-null  argument   or
        !          1489:               nil if all arguments evaluate to nil.
        !          1490: 
        !          1491:      NOTE: Evaluation proceeds left to right  and  stops  as
        !          1492:            soon  as one of the arguments evaluates to a non-
        !          1493:            null value.
        !          1494: 
        !          1495: (prog l_vrbls g_exp1 ...)
        !          1496: 
        !          1497:      RETURNS: the value explicitly given in a return form or
        !          1498:               else  nil if no return is done by the time the
        !          1499:               last g_exp_i is evaluated.
        !          1500: 
        !          1501:      NOTE: the local variables are lambda-bound to nil, then
        !          1502:            the  g_exp_i  are  evaluated  from  left to right.
        !          1503:            This is a prog body (obviously)  and  this  means
        !          1504:            than  any symbols seen are not evaluated, but are
        !          1505:            treated as labels.  This also means that return's
        !          1506:            and go's are allowed.
        !          1507: 
        !          1508: (prog1 'g_exp1 ['g_exp2 ...])
        !          1509: 
        !          1510:      RETURNS: g_exp1
        !          1511: 
        !          1512: (prog2 'g_exp1 'g_exp2 ['g_exp3 ...])
        !          1513: 
        !          1514:      RETURNS: g_exp2
        !          1515: 
        !          1516:      NOTE: the forms are evaluated from left  to  right  and
        !          1517:            the value of g_exp2 is returned.
        !          1518: 
        !          1519: 
        !          1520: 
        !          1521: 
        !          1522: 
        !          1523: 
        !          1524: 
        !          1525: 9
        !          1526: 
        !          1527: 9                                   Printed: January 31, 1984
        !          1528: 
        !          1529: 
        !          1530: 
        !          1531: 
        !          1532: 
        !          1533: 
        !          1534: 
        !          1535: Special Functions                                       4-22
        !          1536: 
        !          1537: 
        !          1538: (progn 'g_exp1 ['g_exp2 ...])
        !          1539: 
        !          1540:      RETURNS: the last g_exp_i.
        !          1541: 
        !          1542: (progv 'l_locv 'l_initv g_exp1 ...)
        !          1543: 
        !          1544:      WHERE:   l_locv is a list of symbols and l_initv  is  a
        !          1545:               list of expressions.
        !          1546: 
        !          1547:      RETURNS: the value of the last g_exp_i evaluated.
        !          1548: 
        !          1549:      NOTE: The expressions in  l_initv  are  evaluated  from
        !          1550:            left  to  right and then lambda-bound to the sym-
        !          1551:            bols in l_locv.  If there are too few expressions
        !          1552:            in l_initv then the missing values are assumed to
        !          1553:            be nil.  If there are  too  many  expressions  in
        !          1554:            l_initv then the extra ones are ignored (although
        !          1555:            they  are  evaluated).   Then  the   g_exp_i   are
        !          1556:            evaluated  left to right.  The body of a progv is
        !          1557:            like the body of a progn, it is _n_o_t a prog  body.
        !          1558:            (C.f. _l_e_t)
        !          1559: 
        !          1560: (purcopy 'g_exp)
        !          1561: 
        !          1562:      RETURNS: a copy of g_exp with new pure cells  allocated
        !          1563:               wherever possible.
        !          1564: 
        !          1565:      NOTE: pure space is never swept up by the garbage  col-
        !          1566:            lector,  so  this  should only be done on expres-
        !          1567:            sions which are not likely to become  garbage  in
        !          1568:            the  future.   In  certain cases, data objects in
        !          1569:            pure space become read-only after a _d_u_m_p_l_i_s_p  and
        !          1570:            then  an attempt to modify the object will result
        !          1571:            in an illegal memory reference.
        !          1572: 
        !          1573: (purep 'g_exp)
        !          1574: 
        !          1575:      RETURNS: t iff the object g_exp is in pure space.
        !          1576: 
        !          1577: (putd 's_name 'u_func)
        !          1578: 
        !          1579:      RETURNS: u_func
        !          1580: 
        !          1581:      SIDE EFFECT: this sets the function binding  of  symbol
        !          1582:                   s_name to u_func.
        !          1583: 
        !          1584: 
        !          1585: 
        !          1586: 
        !          1587: 
        !          1588: 
        !          1589: 
        !          1590: 9
        !          1591: 
        !          1592: 9                                   Printed: January 31, 1984
        !          1593: 
        !          1594: 
        !          1595: 
        !          1596: 
        !          1597: 
        !          1598: 
        !          1599: 
        !          1600: Special Functions                                       4-23
        !          1601: 
        !          1602: 
        !          1603: (return ['g_val])
        !          1604: 
        !          1605:      RETURNS: g_val (or nil if g_val is  not  present)  from
        !          1606:               the enclosing prog or do body.
        !          1607: 
        !          1608:      NOTE: this form is only valid in the context of a  prog
        !          1609:            or do body.
        !          1610: 
        !          1611: (selectq 'g_key-form [l_clause1 ...])
        !          1612: 
        !          1613:      NOTE: This function is just  like  _c_a_s_e_q  (see  above),
        !          1614:            except  that  the  symbol  otherwise has the same
        !          1615:            semantics as the symbol t, when used  as  a  com-
        !          1616:            parator.
        !          1617: 
        !          1618: (setarg 'x_argnum 'g_val)
        !          1619: 
        !          1620:      WHERE:   x_argnum is greater than zero and less than or
        !          1621:               equal to the number of arguments to the lexpr.
        !          1622: 
        !          1623:      RETURNS: g_val
        !          1624: 
        !          1625:      SIDE EFFECT: the lexpr's x_argnum'th argument is set to
        !          1626:                   g-val.
        !          1627: 
        !          1628:      NOTE: this can only be used within the body of a lexpr.
        !          1629: 
        !          1630: (throw 'g_val [s_tag])
        !          1631: 
        !          1632:      WHERE:   if s_tag is not given, it  is  assumed  to  be
        !          1633:               nil.
        !          1634: 
        !          1635:      RETURNS: the value of (*_t_h_r_o_w '_s__t_a_g '_g__v_a_l).
        !          1636: 
        !          1637: (*throw 's_tag 'g_val)
        !          1638: 
        !          1639:      RETURNS: g_val from the first enclosing catch with  the
        !          1640:               tag s_tag or with no tag at all.
        !          1641: 
        !          1642:      NOTE: this is used in conjunction with *_c_a_t_c_h to  cause
        !          1643:            a clean jump to an enclosing context.
        !          1644: 
        !          1645: 
        !          1646: 
        !          1647: 
        !          1648: 
        !          1649: 
        !          1650: 
        !          1651: 
        !          1652: 
        !          1653: 
        !          1654: 
        !          1655: 9
        !          1656: 
        !          1657: 9                                   Printed: January 31, 1984
        !          1658: 
        !          1659: 
        !          1660: 
        !          1661: 
        !          1662: 
        !          1663: 
        !          1664: 
        !          1665: Special Functions                                       4-24
        !          1666: 
        !          1667: 
        !          1668: (unwind-protect g_protected [g_cleanup1 ...])
        !          1669: 
        !          1670:      RETURNS: the result of evaluating g_protected.
        !          1671: 
        !          1672:      NOTE: Normally g_protected is evaluated and  its  value
        !          1673:            remembered, then the g_cleanup_i are evaluated and
        !          1674:            finally  the  saved  value  of   g_protected   is
        !          1675:            returned.    If   something  should  happen  when
        !          1676:            evaluating g_protected which  causes  control  to
        !          1677:            pass  through  g_protected   and thus through the
        !          1678:            call to the unwind-protect, then  the  g_cleanup_i
        !          1679:            will  still  be  evaluated.   This  is  useful if
        !          1680:            g_protected does  something sensitive which  must
        !          1681:            be  cleaned  up  whether  or not g_protected com-
        !          1682:            pletes.
        !          1683: 
        !          1684: 
        !          1685: 
        !          1686: 
        !          1687: 
        !          1688: 
        !          1689: 
        !          1690: 
        !          1691: 
        !          1692: 
        !          1693: 
        !          1694: 
        !          1695: 
        !          1696: 
        !          1697: 
        !          1698: 
        !          1699: 
        !          1700: 
        !          1701: 
        !          1702: 
        !          1703: 
        !          1704: 
        !          1705: 
        !          1706: 
        !          1707: 
        !          1708: 
        !          1709: 
        !          1710: 
        !          1711: 
        !          1712: 
        !          1713: 
        !          1714: 
        !          1715: 
        !          1716: 
        !          1717: 
        !          1718: 
        !          1719: 
        !          1720: 9
        !          1721: 
        !          1722: 9                                   Printed: January 31, 1984
        !          1723: 
        !          1724: 
        !          1725: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.