![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch4.n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / ucb / lisp / doc|
Return to ch4.n CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / ucb / lisp / doc |
1.1 ! root 1: .\" Copyright (c) 1980 Regents of the University of California. ! 2: .\" All rights reserved. The Berkeley software License Agreement ! 3: .\" specifies the terms and conditions for redistribution. ! 4: .\" ! 5: .\" @(#)ch4.n 6.2 (Berkeley) 5/14/86 ! 6: .\" ! 7: ." $Header: ch4.n,v 1.4 83/07/27 15:11:44 layer Exp $ ! 8: .pp ! 9: .Lc Special\ Functions 4 ! 10: .Lf and "[g_arg1 ...]" ! 11: .Re ! 12: the value of the last argument if all arguments evaluate ! 13: to a non-nil value, otherwise ! 14: .i and ! 15: returns nil. ! 16: It returns t if there are no arguments. ! 17: .No ! 18: the arguments are evaluated left to right and evaluation will cease ! 19: with the first nil encountered. ! 20: .Lf apply "'u_func 'l_args" ! 21: .Re ! 22: the result of applying function u_func to the arguments in the list l_args. ! 23: .No ! 24: If u_func is a lambda, then the \fI(length\ l_args)\fP should equal the ! 25: number of formal parameters for the u_func. ! 26: If u_func is a nlambda or macro, then l_args is bound to the single ! 27: formal parameter. ! 28: .Eb ! 29: ; \fIadd1\fP is a lambda of 1 argument ! 30: \-> \fI(apply 'add1 '(3))\fP ! 31: 4 ! 32: ! 33: ; we will define \fIplus1\fP as a macro which will be equivalent to \fIadd1\fP ! 34: \-> \fI(def plus1 (macro (arg) (list 'add1 (cadr arg))))\fP ! 35: plus1 ! 36: \-> \fI(plus1 3)\fP ! 37: 4 ! 38: ! 39: ; now if we \fIapply\fP a macro we obtain the form it changes to. ! 40: \-> \fI(apply 'plus1 '(plus1 3))\fP ! 41: (add1 3) ! 42: ! 43: ; if we \fIfuncall\fP a macro however, the result of the macro is \fIeval\fPed ! 44: ; before it is returned. ! 45: \-> \fI(funcall 'plus1 '(plus1 3))\fP ! 46: 4 ! 47: ! 48: ; for this particular macro, the \fIcar\fP of the \fIarg\fP is not checked ! 49: ; so that this too will work ! 50: \-> \fI(apply 'plus1 '(foo 3))\fP ! 51: (add1 3) ! 52: ! 53: .Ee ! 54: .Lf arg "['x_numb]" ! 55: .Re ! 56: if x_numb is specified then the x_numb'\fIth\fP argument to ! 57: the enclosing lexpr ! 58: If x_numb is not specified then this returns the number of arguments ! 59: to the enclosing lexpr. ! 60: .No ! 61: it is an error to the interpreter if x_numb is given and out of range. ! 62: .Lf break "[g_message ['g_pred]]" ! 63: .Wh ! 64: if g_message is not given it is assumed to be the null string, and ! 65: if g_pred is not given it is assumed to be t. ! 66: .Re ! 67: the value of \fI(*break 'g_pred 'g_message)\fP ! 68: .Lf *break "'g_pred 'g_message" ! 69: .Re ! 70: nil immediately if g_pred is nil, else ! 71: the value of the next (return 'value) expression typed in at top level. ! 72: .Se ! 73: If the predicate, g_pred, evaluates to non-null, ! 74: the lisp system stops and prints out `Break ' ! 75: followed by g_message. ! 76: It then enters a break loop ! 77: which allows one to interactively debug a program. ! 78: To continue execution from a break you can use the ! 79: .i return ! 80: function. ! 81: to return to top level or another break level, you can use ! 82: .i retbrk ! 83: or ! 84: .i reset . ! 85: .Lf caseq "'g_key-form l_clause1 ..." ! 86: .Wh ! 87: l_clause\fIi\fP is a list of the form ! 88: (g_comparator ['g_form\fIi\fP ...]). ! 89: The comparators may be symbols, small fixnums, a list of small fixnums or ! 90: symbols. ! 91: .No ! 92: The way caseq works is that it evaluates g_key-form, ! 93: yielding a value we will call the selector. ! 94: Each clause is examined until the selector is found ! 95: consistent with the comparator. ! 96: For a symbol, or a fixnum, this means the two must be \fIeq\fP. ! 97: For a list, this means that the selector must be \fIeq\fP to ! 98: some element of the list. ! 99: .br ! 100: .sp ! 101: The comparator consisting of the symbol \fBt\fP has special semantics: ! 102: it matches anything, and consequently, should be the last comparator. ! 103: .br ! 104: .sp ! 105: In any case, having chosen a clause, \fIcaseq\fP evaluates each form ! 106: within that clause and ! 107: .Re ! 108: the value of the last form. If no comparators are matched, ! 109: \fIcaseq\fP returns nil. ! 110: .Eb ! 111: Here are two ways of defining the same function: ! 112: \->\fI(defun fate (personna) ! 113: (caseq personna ! 114: (cow '(jumped over the moon)) ! 115: (cat '(played nero)) ! 116: ((dish spoon) '(ran away with each other)) ! 117: (t '(lived happily ever after))))\fP ! 118: fate ! 119: \->\fI(defun fate (personna) ! 120: (cond ! 121: ((eq personna 'cow) '(jumped over the moon)) ! 122: ((eq personna 'cat) '(played nero)) ! 123: ((memq personna '(dish spoon)) '(ran away with each other)) ! 124: (t '(lived happily ever after))))\fP ! 125: fate ! 126: .Ee ! 127: .Lf catch "g_exp [ls_tag]" ! 128: .Wh ! 129: if ls_tag is not given, it is assumed to be nil. ! 130: .Re ! 131: the result of \fI(*catch 'ls_tag g_exp)\fP ! 132: .No ! 133: catch is defined as a macro. ! 134: .Lf *catch "'ls_tag g_exp" ! 135: .Wh ! 136: ls_tag is either a symbol or a list of symbols. ! 137: .Re ! 138: the result of evaluating g_exp or the value thrown during the evaluation ! 139: of g_exp. ! 140: .Se ! 141: this first sets up a `catch frame' on the lisp runtime stack. ! 142: Then it begins to evaluate g_exp. ! 143: If g_exp evaluates normally, its value is returned. ! 144: If, however, a value is thrown during the evaluation of g_exp then ! 145: this *catch will return with that value if one of these cases ! 146: is true: ! 147: .nr $p 0 ! 148: .np ! 149: the tag thrown to is ls_tag ! 150: .np ! 151: ls_tag is a list and the tag thrown to is a member of this list ! 152: .np ! 153: ls_tag is nil. ! 154: .No ! 155: Errors are implemented as a special kind of throw. ! 156: A catch with no tag will not catch an error but a catch whose tag is ! 157: the error type will catch that type of error. ! 158: See Chapter 10 for more information. ! 159: .Lf comment "[g_arg ...]" ! 160: .Re ! 161: the symbol comment. ! 162: .No ! 163: This does absolutely nothing. ! 164: .Lf cond "[l_clause1 ...]" ! 165: .Re ! 166: the last value evaluated in the first clause satisfied. ! 167: If no clauses are satisfied then nil is returned. ! 168: .No ! 169: This is the basic conditional `statement' in lisp. ! 170: The clauses are processed from left to right. ! 171: The first element of a clause is evaluated. ! 172: If it evaluated to a non-null value then that clause is satisfied and ! 173: all following elements of that clause are evaluated. ! 174: The last value computed is returned as the value of the cond. ! 175: If there is just one element in the clause then its value is returned. ! 176: If the first element of a clause evaluates to nil, then the other ! 177: elements of that clause are not evaluated and the system moves to ! 178: the next clause. ! 179: .Lf cvttointlisp ! 180: .Se ! 181: The reader is modified to conform with the Interlisp syntax. ! 182: The character % is made the escape character and special meanings for ! 183: comma, backquote and backslash are removed. ! 184: Also the reader is told to convert upper case to lower case. ! 185: .Lf cvttofranzlisp ! 186: .Se ! 187: .Fr "'s" ! 188: default syntax is reinstated. ! 189: One would run this function after having run any ! 190: of the other ! 191: .i cvtto- ! 192: functions. ! 193: Backslash is made the escape character, super-brackets work again, ! 194: and the reader distinguishes between upper and ! 195: lower case. ! 196: .Lf cvttomaclisp ! 197: .Se ! 198: The reader is modified to conform with Maclisp syntax. ! 199: The character / is made the escape character and the special meanings ! 200: for backslash, left and right bracket are removed. ! 201: The reader is made case-insensitive. ! 202: .Lf cvttoucilisp ! 203: .Se ! 204: The reader is modified to conform with UCI Lisp syntax. ! 205: The character / is made the escape character, tilde is made the comment ! 206: character, exclamation point takes on the unquote function normally ! 207: held by comma, and backslash, comma, semicolon become normal ! 208: characters. ! 209: Here too, the reader is made case-insensitive. ! 210: .Lf debug "s_msg" ! 211: .Se ! 212: Enter the Fixit package described in Chapter 15. ! 213: This package allows you to examine the evaluation stack in detail. ! 214: To leave the Fixit package type 'ok'. ! 215: .Lf debugging "'g_arg" ! 216: .Se ! 217: If g_arg is non-null, ! 218: Franz unlinks the transfer tables, does a \fI(*rset\ t)\fP to turn on ! 219: evaluation monitoring and sets the all-error catcher (ER%all) to be ! 220: \fIdebug-err-handler\fP. ! 221: If g_arg is nil, ! 222: all of the above changes are undone. ! 223: .Lf declare "[g_arg ...]" ! 224: .Re ! 225: nil ! 226: .No ! 227: this is a no-op to the evaluator. ! 228: It has special meaning to the compiler (see Chapter 12). ! 229: .Lf def "s_name (s_type l_argl g_exp1 ...)" ! 230: .Wh ! 231: s_type is one of lambda, nlambda, macro or lexpr. ! 232: .Re ! 233: s_name ! 234: .Se ! 235: This defines the function s_name to the lisp system. ! 236: If s_type is nlambda or macro then the argument list l_argl must contain ! 237: exactly one non-nil symbol. ! 238: .Lf defmacro "s_name l_arg g_exp1 ..." ! 239: .Lx defcmacro "s_name l_arg g_exp1 ..." ! 240: .Re ! 241: s_name ! 242: .Se ! 243: This defines the macro s_name. ! 244: \fIdefmacro\fP makes it easy to write macros since it makes ! 245: the syntax just like \fIdefun\fP. ! 246: Further information on \fIdefmacro\fP is in \(sc8.3.2. ! 247: \fIdefcmacro\fP defines compiler-only macros, or cmacros. ! 248: A cmacro is stored on the property list of a ! 249: symbol under the indicator \fBcmacro\fP. ! 250: Thus a function can ! 251: have a normal definition and a cmacro definition. ! 252: For an example of the use of cmacros, see the definitions ! 253: of nthcdr and nth in /usr/lib/lisp/common2.l ! 254: .Lf defun "s_name [s_mtype] ls_argl g_exp1 ... " ! 255: .Wh ! 256: s_mtype is one of fexpr, expr, args or macro. ! 257: .Re ! 258: s_name ! 259: .Se ! 260: This defines the function s_name. ! 261: .No ! 262: this exists for Maclisp compatibility, it is just a macro which ! 263: changes the defun form to the def form. ! 264: An s_mtype of fexpr is converted to nlambda ! 265: and of expr to lambda. Macro remains the same. ! 266: If ls_arg1 is a non-nil symbol, then the type is assumed to be lexpr and ! 267: ls_arg1 is the symbol which is bound to the number of args when the ! 268: function is entered. ! 269: .br ! 270: For compatibility with the Lisp Machine Lisp, there are three types of ! 271: optional parameters that can occur in ls_argl: \fI&optional\fP declares that ! 272: the following symbols are optional, and may or may not appear in the ! 273: argument list to the function, \fI&rest symbol\fP ! 274: declares that all forms in the ! 275: function call that are not accounted for by previous lambda bindings ! 276: are to be assigned to \fIsymbol\fP, and \fI&aux form1 ... formn\fP ! 277: declares that the \fIformi\fP are either symbols, in which case they ! 278: are lambda bound to \fBnil\fP, or lists, in which case the first element ! 279: of the list is lambda bound to the second, evaluated element. ! 280: .Eb ! 281: ; \fIdef\fP and \fIdefun\fP here are used to define identical functions ! 282: ; you can decide for yourself which is easier to use. ! 283: \-> \fI(def append1 (lambda (lis extra) (append lis (list extra))))\fP ! 284: append1 ! 285: ! 286: \-> \fI(defun append1 (lis extra) (append lis (list extra)))\fP ! 287: append1 ! 288: ! 289: ; Using the & forms... ! 290: \-> \fI(defu\kCn test (a b &optional c &aux (retval 0) &rest z) ! 291: \h'|\nCu'\kB(if c them (msg \kA"Optional arg present" N ! 292: \h'|\nAu'"c is " c N)) ! 293: \h'|\nBu'(msg \kA"rest is " z N ! 294: \h'|\nAu'"retval is " retval N))\fP ! 295: test ! 296: \-> \fI(test 1 2 3 4)\fP ! 297: Optional arg present ! 298: c is 3 ! 299: rest is (4) ! 300: retval is 0 ! 301: .Ee ! 302: .Lf defvar "s_variable ['g_init]" ! 303: .Re ! 304: s_variable. ! 305: .No ! 306: This form is put at the top level in files, like \fIdefun\fB. ! 307: .Se ! 308: This declares s_variable to be special. If g_init is present ! 309: and s_variable is unbound when the file is read in, s_variable ! 310: will be set to the value of g_init. ! 311: An advantage of `(defvar foo)' over `(declare (special foo))' is that if ! 312: a file containing defvars is loaded (or fasl'ed) in during compilation, ! 313: the variables mentioned in the defvar's will be declared special. The only ! 314: way to have that effect with `(declare (special foo))' is to \fIinclude\fP ! 315: the file. ! 316: .Lf do "l_vrbs l_test g_exp1 ..." ! 317: .Re ! 318: the last form in the cdr of l_test evaluated, or a value explicitly given by ! 319: a return evaluated within the do body. ! 320: .No ! 321: This is the basic iteration form for ! 322: .Fr . ! 323: l_vrbs is a list of zero or more var-init-repeat forms. ! 324: A var-init-repeat form looks like: ! 325: .br ! 326: .tl ''(s_name [g_init [g_repeat]])'' ! 327: There are three cases depending on what is present in the form. ! 328: If just s_name is present, this means that when the do is entered, ! 329: s_name is lambda-bound to nil and is never modified by the system ! 330: (though the program is certainly free to modify its value). ! 331: If the form is (s_name\ 'g_init) then the only difference is that ! 332: s_name is lambda-bound to the value of g_init instead of nil. ! 333: If g_repeat is also present then s_name is lambda-bound to g_init ! 334: when the loop is entered and after each pass through the do body ! 335: s_name is bound to the value of g_repeat. ! 336: .br ! 337: l_test is either nil or has the form of a cond clause. ! 338: If it is nil then the do body will be evaluated only once and the ! 339: do will return nil. ! 340: Otherwise, before the do body is evaluated the car of l_test is ! 341: evaluated and if the result is non-null, this signals an end to ! 342: the looping. ! 343: Then the rest of the forms in l_test are evaluated ! 344: and the value of the last one is returned as the value of the do. ! 345: If the cdr of l_test is nil, then nil is returned -- thus this is not ! 346: exactly like a cond clause. ! 347: .br ! 348: g_exp1 and those forms which follow constitute the do body. ! 349: A do body is like a prog body and thus may have labels and one may ! 350: use the functions go and return. ! 351: .br ! 352: The sequence of evaluations is this: ! 353: .nr $p 0 ! 354: .np ! 355: the init forms are evaluated left to right and stored in temporary ! 356: locations. ! 357: .np ! 358: Simultaneously all do variables are lambda bound to the value of ! 359: their init forms or nil. ! 360: .np ! 361: If l_test is non-null, then the car is evaluated and if it is non-null, ! 362: the rest of the forms in l_test are evaluated and the last value is ! 363: returned as the value ! 364: of the do. ! 365: .np ! 366: The forms in the do body are evaluated left to right. ! 367: .np ! 368: If l_test is nil the do function returns with the value nil. ! 369: .np ! 370: The repeat forms are evaluated and saved in temporary locations. ! 371: .np ! 372: The variables with repeat forms are simultaneously ! 373: bound to the values of those forms. ! 374: .np ! 375: Go to step 3. ! 376: .No ! 377: there is an alternate form of do which can be used when there is ! 378: only one do variable. ! 379: It is described next. ! 380: .Eb ! 381: ; this is a simple function which numbers the elements of a list. ! 382: ; It uses a \fIdo\fP function with two local variables. ! 383: \-> \fI(defun printem (lis) ! 384: (do ((xx lis (cdr xx)) ! 385: (i 1 (1+ i))) ! 386: ((null xx) (patom "all done") (terpr)) ! 387: (print i) ! 388: (patom ": ") ! 389: (print (car xx)) ! 390: (terpr)))\fP ! 391: printem ! 392: \-> \fI(printem '(a b c d))\fP ! 393: 1: a ! 394: 2: b ! 395: 3: c ! 396: 4: d ! 397: all done ! 398: nil ! 399: \-> ! 400: .Ee ! 401: .Lf do "s_name g_init g_repeat g_test g_exp1 ..." ! 402: .nr $p 0 ! 403: .No ! 404: this is another, less general, form of do. ! 405: It is evaluated by: ! 406: .np ! 407: evaluating g_init ! 408: .np ! 409: lambda binding s_name to value of g_init ! 410: .np ! 411: g_test is evaluated and if it is not nil the do function returns with nil. ! 412: .np ! 413: the do body is evaluated beginning at g_exp1. ! 414: .np ! 415: the repeat form is evaluated and stored in s_name. ! 416: .np ! 417: go to step 3. ! 418: .Re ! 419: nil ! 420: .Lf environment "[l_when1 l_what1 l_when2 l_what2 ...]" ! 421: .Lx environment-maclisp "[l_when1 l_what1 l_when2 l_what2 ...]" ! 422: .Lx environment-lmlisp "[l_when1 l_what1 l_when2 l_what2 ...]" ! 423: .Wh ! 424: the when's are a subset of (eval compile load), and the symbols have the ! 425: same meaning as they do in 'eval-when'. ! 426: .br ! 427: .sp ! 428: The what's may be ! 429: .br ! 430: (files file1 file2 ... fileN), ! 431: .br ! 432: which insure that the named files are loaded. ! 433: To see if file\fIi\fP is loaded, ! 434: it looks for a 'version' property under ! 435: file\fIi\fP's property list. Thus to prevent multiple loading, ! 436: you should put ! 437: .br ! 438: (putprop 'myfile t 'version), ! 439: .br ! 440: at the end of myfile.l. ! 441: .br ! 442: .sp ! 443: Another acceptable form for a what is ! 444: .br ! 445: (syntax type) ! 446: .br ! 447: Where type is either maclisp, intlisp, ucilisp, franzlisp. ! 448: .Se ! 449: \fIenvironment-maclisp\fP sets the environment to that which ! 450: `liszt -m' would generate. ! 451: .br ! 452: .sp ! 453: \fIenvironment-lmlisp\fP sets up the lisp machine environment. This is like ! 454: maclisp but it has additional macros. ! 455: .br ! 456: .sp ! 457: For these specialized environments, only the \fBfiles\fP clauses are useful. ! 458: .Eg ! 459: (environment-maclisp (compile eval) (files foo bar)) ! 460: .Re ! 461: the last list of files requested. ! 462: .Lf err "['s_value [nil]]" ! 463: .Re ! 464: nothing (it never returns). ! 465: .Se ! 466: This causes an error and if this error is caught by an ! 467: .i errset ! 468: then that ! 469: .i errset ! 470: will return s_value instead of nil. ! 471: If the second arg is given, then it must be nil (\s-2MAC\s0lisp ! 472: compatibility). ! 473: .Lf error "['s_message1 ['s_message2]]" ! 474: .Re ! 475: nothing (it never returns). ! 476: .Se ! 477: s_message1 and s_message2 are \fIpatom\fPed if they are given and ! 478: then \fIerr\fP is called (with no arguments), which causes an error. ! 479: .Lf errset "g_expr [s_flag]" ! 480: .Re ! 481: a list of one element, which is the value resulting from evaluating g_expr. ! 482: If an error occurs during the evaluation of g_expr, then the locus of control ! 483: will return to the ! 484: .i errset ! 485: which will then return nil (unless the error was caused by a call to ! 486: .i err, ! 487: with a non-null argument). ! 488: .Se ! 489: S_flag is evaluated before g_expr is evaluated. ! 490: If s_flag is not given, then it is assumed to be t. ! 491: If an error occurs during the evaluation of g_expr, and s_flag evaluated to ! 492: a non-null value, then the error message associated with the ! 493: error is printed before control returns to the errset. ! 494: .Lf eval "'g_val ['x_bind-pointer]" ! 495: .Re ! 496: the result of evaluating g_val. ! 497: .No ! 498: The evaluator evaluates g_val in this way: ! 499: .br ! 500: If g_val is a symbol, then the evaluator returns its value. ! 501: If g_val had never been assigned a value, then this causes ! 502: an `Unbound Variable' error. ! 503: If x_bind-pointer is given, then the variable is evaluated with ! 504: respect to that pointer (see \fIevalframe\fP for details on bind-pointers). ! 505: .br ! 506: .sp ! 507: If g_val is of type value, then its value is returned. ! 508: If g_val is of any other type than list, g_val is returned. ! 509: .br ! 510: .sp ! 511: If g_val is a list object then g_val is either a function call or ! 512: array reference. ! 513: Let g_car be the first element of g_val. ! 514: We continually evaluate g_car until we end up with a symbol with ! 515: a non-null function binding ! 516: or a non-symbol. ! 517: Call what we end up with: g_func. ! 518: .br ! 519: .sp ! 520: G_func must be one of three types: list, binary or array. ! 521: If it is a list then the first element of the list, which ! 522: we shall call g_functype, must be either ! 523: lambda, nlambda, macro or lexpr. ! 524: If g_func is a binary, then its discipline, which we shall call ! 525: g_functype, is either lambda, nlambda, macro or a string. ! 526: If g_func is an array then this form is evaluated specially, see ! 527: Chapter 9 on arrays. ! 528: If g_func is a list or binary, then g_functype will determine how ! 529: the arguments to this function, the cdr of g_val, are processed. ! 530: If g_functype is a string, then this is a foreign function call (see \(sc8.5 ! 531: for more details). ! 532: .br ! 533: .sp ! 534: If g_functype is lambda or lexpr, the arguments are evaluated ! 535: (by calling ! 536: .i eval ! 537: recursively) and stacked. ! 538: If g_functype is nlambda then the argument list is stacked. ! 539: If g_functype is macro then the entire form, g_val is stacked. ! 540: .br ! 541: .sp ! 542: Next, the formal variables are lambda bound. ! 543: The formal variables are the cadr of g_func. If g_functype is ! 544: nlambda, lexpr or macro, there should only be one formal variable. ! 545: The values on the stack are lambda bound to the formal variables ! 546: except in the case of a lexpr, where the number of actual arguments ! 547: is bound to the formal variable. ! 548: .br ! 549: .sp ! 550: After the binding is done, the function is invoked, either by ! 551: jumping to the entry point in the case of a binary or ! 552: by evaluating the list of forms beginning at cddr g_func. ! 553: The result of this function invocation is returned as the value ! 554: of the call to eval. ! 555: .Lf evalframe "'x_pdlpointer" ! 556: .Re ! 557: an evalframe descriptor for the evaluation frame just before x_pdlpointer. ! 558: If x_pdlpointer is nil, it returns the evaluation frame of the frame just ! 559: before the current call to \fIevalframe\fP. ! 560: .No ! 561: An evalframe descriptor describes a call to \fIeval\fP, \fIapply\fP ! 562: or \fIfuncall\fP. ! 563: The form of the descriptor is ! 564: .br ! 565: \fI(type pdl-pointer expression bind-pointer np-index lbot-index)\fP ! 566: .br ! 567: where type is `eval' if this describes a call to \fIeval\fP or `apply' ! 568: if this is a call to \fIapply\fP or \fIfuncall\fP. ! 569: pdl-pointer is a number which describes ! 570: this context. ! 571: It can be passed to ! 572: .i evalframe ! 573: to obtain the next descriptor and ! 574: can be passed to ! 575: .i freturn ! 576: to cause a return from this context. ! 577: bind-pointer is the size of variable binding stack when this ! 578: evaluation began. ! 579: The bind-pointer can be given as a second argument ! 580: to \fIeval\fP to order to evaluate variables in the same context as ! 581: this evaluation. ! 582: If type is `eval' then expression ! 583: will have the form \fI(function-name\ arg1\ ...)\fP. ! 584: If type is `apply' then expression will have the form ! 585: \fI(function-name\ (arg1\ ...))\fP. ! 586: np-index and lbot-index are pointers into the ! 587: argument stack (also known as the \fInamestack\fP array) at the time of call. ! 588: lbot-index points to the first argument, np-index points one beyond ! 589: the last argument. ! 590: .br ! 591: In order for there to be enough information ! 592: for \fIevalframe\fP to return, you must call \fI(*rset\ t)\fP. ! 593: .Ex ! 594: \fI(progn (evalframe nil))\fP ! 595: .br ! 596: returns \fI(eval 2147478600 (progn (evalframe nil)) 1 8 7)\fP ! 597: .Lf evalhook "'g_form 'su_evalfunc ['su_funcallfunc]" ! 598: .Re ! 599: the result of evaluating g_form after lambda binding `evalhook' to ! 600: su_evalfunc and, if it is given, lambda binding `funcallhook' to ! 601: su_funcallhook. ! 602: .No ! 603: As explained in \(sc14.4, the function ! 604: .i eval ! 605: may pass the job of evaluating a form to a user `hook' function when ! 606: various switches are set. ! 607: The hook function normally prints the form to be evaluated on the ! 608: terminal and then evaluates it by calling ! 609: .i evalhook . ! 610: .i Evalhook ! 611: does the lambda binding mentioned above and then calls ! 612: .i eval ! 613: to evaluate the form after setting an internal switch to tell ! 614: .i eval ! 615: not to call the user's hook function just this one time. ! 616: This allows the evaluation process to advance one step and yet ! 617: insure that further calls to ! 618: .i eval ! 619: will cause traps to the hook function (if su_evalfunc is non-null). ! 620: .br ! 621: In order for \fIevalhook\fP to work, \fI(*rset\ t)\fP and ! 622: \fI(sstatus\ evalhook\ t)\fP must have been done previously. ! 623: .Lf exec "s_arg1 ..." ! 624: .Re ! 625: the result of forking and executing the command named by concatenating ! 626: the s_arg\fIi\fP together with spaces in between. ! 627: .Lf exece "'s_fname ['l_args ['l_envir]]" ! 628: .Re ! 629: the error code from the system if it was unable to ! 630: execute the command s_fname with arguments ! 631: l_args and with the environment set up as specified in l_envir. ! 632: If this function is successful, it will not return, instead the lisp ! 633: system will be overlaid by the new command. ! 634: .Lf freturn "'x_pdl-pointer 'g_retval" ! 635: .Re ! 636: g_retval from the context given by x_pdl-pointer. ! 637: .No ! 638: A pdl-pointer denotes a certain expression currently being evaluated. ! 639: The pdl-pointer for a given expression can be obtained from ! 640: .i evalframe . ! 641: .Lf frexp "'f_arg" ! 642: .Re ! 643: a list cell \fI(exponent . mantissa)\fP which represents the ! 644: given flonum ! 645: .No ! 646: The exponent will be a fixnum, the mantissa a 56 bit bignum. ! 647: If you think of the the binary point occurring right after the ! 648: high order bit of mantissa, then ! 649: f_arg\ =\ 2\*[exponent\*]\ *\ mantissa. ! 650: .Lf funcall "'u_func ['g_arg1 ...]" ! 651: .Re ! 652: the value of applying function u_func to the arguments g_arg\fIi\fP ! 653: and then evaluating that result if u_func is a macro. ! 654: .No ! 655: If u_func is a macro or nlambda then there should be only one g_arg. ! 656: \fIfuncall\fP is the function which the evaluator uses to evaluate ! 657: lists. ! 658: If \fIfoo\fP is a lambda or lexpr or array, ! 659: then \fI(funcall\ 'foo\ 'a\ 'b\ 'c)\fP ! 660: is equivalent to \fI(foo\ 'a\ 'b\ 'c)\fP. ! 661: If \fIfoo\fP is a nlambda ! 662: then \fI(funcall\ 'foo\ '(a\ b\ c))\fP is equivalent to ! 663: \fI(foo a b c)\fP. ! 664: Finally, if ! 665: .i foo ! 666: is a macro then ! 667: .i (funcall\ 'foo\ '(foo\ a\ b\ c)) ! 668: is equivalent to ! 669: .i (foo\ a\ b\ c) . ! 670: .Lf funcallhook "'l_form 'su_funcallfunc ['su_evalfunc]" ! 671: .Re ! 672: the result of \fIfuncall\fPing ! 673: the \fI(car\ l_form)\fP ! 674: on the already evaluated ! 675: arguments in the \fI(cdr\ l_form)\fP ! 676: after lambda binding `funcallhook' to ! 677: su_funcallfunc and, if it is given, lambda binding `evalhook' to ! 678: su_evalhook. ! 679: .No ! 680: This function is designed to continue the evaluation process ! 681: with as little work as possible after a funcallhook trap has occurred. ! 682: It is for this reason that the form of l_form is unorthodox: its ! 683: .i car ! 684: is the name of the function to call and its ! 685: .i cdr ! 686: are a list of arguments to stack (without evaluating again) ! 687: before calling the given function. ! 688: After stacking the arguments ! 689: but ! 690: before calling ! 691: .i funcall ! 692: an internal switch is set to prevent \fIfuncall\fP ! 693: from passing the job of funcalling to su_funcallfunc. ! 694: If \fIfuncall\fP is called recursively in funcalling l_form and ! 695: if su_funcallfunc is non-null, then ! 696: the arguments to ! 697: .i funcall ! 698: will actually be given to su_funcallfunc (a lexpr) ! 699: to be funcalled. ! 700: .br ! 701: In order for \fIevalhook\fP to work, \fI(*rset\ t)\fP and ! 702: \fI(sstatus\ evalhook\ t)\fP must have been done previously. ! 703: A more detailed description of ! 704: .i evalhook ! 705: and ! 706: .i funcallhook ! 707: is given in Chapter 14. ! 708: .Lf function "u_func" ! 709: .Re ! 710: the function binding of u_func if it is an symbol with a function binding ! 711: otherwise u_func is returned. ! 712: .Lf getdisc "'y_func" ! 713: .Re ! 714: the discipline of the machine coded function (either lambda, nlambda ! 715: or macro). ! 716: .Lf go "g_labexp" ! 717: .Wh ! 718: g_labexp is either a symbol or an expression. ! 719: .Se ! 720: If g_labexp is an expression, that expression is evaluated and ! 721: should ! 722: result in a symbol. ! 723: The locus of control moves to just following the symbol g_labexp in the ! 724: current prog or do body. ! 725: .No ! 726: this is only valid in the context of a prog or do body. ! 727: The interpreter and compiler will allow non-local ! 728: .i go 's ! 729: although the compiler won't allow a \fIgo\fP to leave a function body. ! 730: The compiler will not allow g_labexp to be an expression. ! 731: .Lf if "'g_a 'g_b" ! 732: .Lx if "'g_a 'g_b 'g_c ..." ! 733: .Lx if "'g_a \fBthen\fP 'g_b [...] [\fBelseif\fP 'g_c \fBthen\fP 'g_d ...] [\fBelse\fP 'g_e [...]" ! 734: .Lx if "'g_a \fBthen\fP 'g_b [...] [\fBelseif\fP 'g_c \fBthenret\fP] [\fBelse\fP 'g_d [...]" ! 735: .No ! 736: The various forms of \fIif\fP are intended to be a more readable ! 737: conditional statement, to be used in place of \fIcond\fP. There ! 738: are two varieties of \fIif\fP, with keywords, and without. The ! 739: keyword-less variety is inherited from common Maclisp usage. ! 740: A keyword-less, two argument \fIif\fP is equivalent to a one-clause ! 741: \fIcond\fP, i.e. (\fIcond\fP (a b)). Any other keyword-less \fIif\fP ! 742: must have at least three arguments. The first two arguments are the ! 743: first clause of the equivalent \fIcond\fP, and all remaining arguments ! 744: are shoved into a second clause beginning with \fBt\fP. Thus, the ! 745: second form of \fIif\fP is equivalent to ! 746: .br ! 747: (\fIcond\fP (a b) (t c ...)). ! 748: .br ! 749: .sp ! 750: The keyword variety has the following grouping of arguments: ! 751: a predicate, a then-clause, and optional ! 752: else-clause. The predicate is evaluated, and if the result is ! 753: non-nil, the then-clause will be performed, in the sense ! 754: described below. Otherwise, (i.e. the result of the predicate ! 755: evaluation was precisely nil), the else-clause will be performed. ! 756: .br ! 757: .sp ! 758: Then-clauses will either consist entirely ! 759: of the single keyword \fBthenret\fP, or will start with the keyword ! 760: \fBthen\fP, and be followed by at least one general expression. ! 761: (These general expressions must not be one of the keywords.) ! 762: To actuate a \fBthenret\fP means to cease further evaluation ! 763: of the \fIif\fP, and to return the value of the predicate just calculated. ! 764: The performance of the longer clause means to evaluate each general expression ! 765: in turn, and then return the last value calculated. ! 766: .br ! 767: .sp ! 768: The else-clause may begin with the keyword \fBelse\fP and be followed ! 769: by at least one general expression. ! 770: The rendition of this clause is just like that of a then-clause. ! 771: An else-clause ! 772: may begin alternatively with the keyword \fBelseif\fP, and be followed ! 773: (recursively) by a predicate, then-clause, and optional else-clause. ! 774: Evaluation of this clause, is just evaluation of an \fIif\fP-form, with ! 775: the same predicate, then- and else-clauses. ! 776: .Lf I-throw-err "'l_token" ! 777: .Wh ! 778: l_token is the \fIcdr\fP of the value returned from a \fI*catch\fP with ! 779: the tag ER%unwind-protect. ! 780: .Re ! 781: nothing (never returns in the current context) ! 782: .Se ! 783: The error or throw denoted by l_token is continued. ! 784: .No ! 785: This function is used to implement \fIunwind-protect\fP which allows the ! 786: processing of a transfer of control though a certain context to be ! 787: interrupted, a user function to be executed and than the transfer of ! 788: control to continue. ! 789: The form of l_token is either ! 790: .br ! 791: \fI(t tag value)\fP for a throw or ! 792: .br ! 793: \fI(nil type message valret contuab uniqueid [arg ...])\fP for an error. ! 794: .br ! 795: This function is not to be used for implementing throws or ! 796: errors and is only documented here for completeness. ! 797: .Lf let "l_args g_exp1 ... g_exprn" ! 798: .Re ! 799: the result of evaluating g_exprn within the bindings given by l_args. ! 800: .No ! 801: l_args is either nil (in which case ! 802: .i let ! 803: is just like ! 804: .i progn ) ! 805: or it is a list of binding objects. ! 806: A binding object is a list \fI(symbol\ expression)\fP. ! 807: When a ! 808: .i let ! 809: is entered, ! 810: all of the expressions are evaluated and then simultaneously ! 811: lambda-bound to the corresponding symbols. ! 812: In effect, a ! 813: .i let ! 814: expression is just like a lambda expression except the symbols and ! 815: their initial values are next to each other, making the expression ! 816: easier to understand. ! 817: There are some added features to the ! 818: .i let ! 819: expression: ! 820: A binding object can just be a symbol, in which case the expression ! 821: corresponding to that symbol is `nil'. ! 822: If a binding object is a list and the first element of that list is ! 823: another list, then that list is assumed to be a binding template ! 824: and ! 825: .i let ! 826: will do a ! 827: .i desetq ! 828: on it. ! 829: .Lf let* "l_args g_exp1 ... g_expn" ! 830: .Re ! 831: the result of evaluating g_exprn within the bindings given by l_args. ! 832: .No ! 833: This is identical to ! 834: .i let ! 835: except the expressions in the binding list l_args are evaluated ! 836: and bound sequentially instead of in parallel. ! 837: .Lf lexpr-funcall "'g_function ['g_arg1 ...] 'l_argn" ! 838: .No ! 839: This is a cross between funcall and apply. ! 840: The last argument, must be a list (possibly empty). ! 841: The element of list arg are stack and then the function is ! 842: funcalled. ! 843: .Ex ! 844: (lexpr-funcall 'list 'a '(b c d)) is the same as ! 845: (funcall 'list 'a 'b 'c 'd) ! 846: .Lf listify "'x_count" ! 847: .Re ! 848: a list of x_count of the arguments to the current function (which ! 849: must be a lexpr). ! 850: .No ! 851: normally arguments 1 through x_count are returned. ! 852: If x_count is negative then a list of last abs(x_count) arguments are ! 853: returned. ! 854: .Lf map "'u_func 'l_arg1 ..." ! 855: .Re ! 856: l_arg1 ! 857: .No ! 858: The function u_func is applied to successive sublists of the l_arg\fIi\fP. ! 859: All sublists should have the same length. ! 860: .\".pg ! 861: .Lf mapc "'u_func 'l_arg1 ..." ! 862: .Re ! 863: l_arg1. ! 864: .No ! 865: The function u_func is applied to successive elements of the argument ! 866: lists. ! 867: All of the lists should have the same length. ! 868: .Lf mapcan "'u_func 'l_arg1 ..." ! 869: .Re ! 870: nconc applied to the results of the functional evaluations. ! 871: .No ! 872: The function u_func is applied to successive elements of the ! 873: argument lists. ! 874: All sublists should have the same length. ! 875: .Lf mapcar "'u_func 'l_arg1 ..." ! 876: .Re ! 877: a list of the values returned from the functional application. ! 878: .No ! 879: the function u_func is applied to successive elements of the ! 880: argument lists. ! 881: All sublists should have the same length. ! 882: .Lf mapcon "'u_func 'l_arg1 ..." ! 883: .Re ! 884: nconc applied to the results of the functional evaluation. ! 885: .No ! 886: the function u_func is applied to successive sublists of the ! 887: argument lists. ! 888: All sublists should have the same length. ! 889: .Lf maplist "'u_func 'l_arg1 ..." ! 890: .Re ! 891: a list of the results of the functional evaluations. ! 892: .No ! 893: the function u_func is applied to successive sublists of the arguments ! 894: lists. ! 895: All sublists should have the same length. ! 896: .lp ! 897: Readers may find the following summary table useful in remembering ! 898: the differences between the six mapping functions: ! 899: .(b ! 900: .TS ! 901: box; ! 902: c | c s s. ! 903: \ Value returned is ! 904: ! 905: .T& ! 906: c | c c c. ! 907: T{ ! 908: .na ! 909: Argument to functional is ! 910: .ad ! 911: T} l_arg1 list of results \fInconc\fP of results ! 912: _ ! 913: .T& ! 914: c | c c c. ! 915: ! 916: elements of list mapc mapcar mapcan ! 917: ! 918: sublists map maplist mapcon ! 919: .TE ! 920: .)b ! 921: .Lf mfunction "t_entry 's_disc" ! 922: .Re ! 923: a lisp object of type binary composed of t_entry and s_disc. ! 924: .No ! 925: t_entry is a pointer to the machine code for a function, and s_disc is the ! 926: discipline (e.g. lambda). ! 927: .\".pg ! 928: .Lf oblist ! 929: .Re ! 930: a list of all symbols on the oblist. ! 931: .Lf or "[g_arg1 ... ]" ! 932: .Re ! 933: the value of the first non-null argument or nil if all arguments ! 934: evaluate to nil. ! 935: .No ! 936: Evaluation proceeds left to right and stops as soon as one of the arguments ! 937: evaluates to a non-null value. ! 938: .Lf prog "l_vrbls g_exp1 ..." ! 939: .Re ! 940: the value explicitly given in a return form ! 941: or else nil if no return is done by the time the last g_exp\fIi\fP is ! 942: evaluated. ! 943: .No ! 944: the local variables are lambda-bound to nil, ! 945: then the g_exp\fIi\fP ! 946: are evaluated from left to right. ! 947: This is a prog body (obviously) and this means than ! 948: any symbols seen are not evaluated, ! 949: but are treated as labels. ! 950: This also means that return's and go's are allowed. ! 951: .Lf prog1 "'g_exp1 ['g_exp2 ...]" ! 952: .Re ! 953: g_exp1 ! 954: .Lf prog2 "'g_exp1 'g_exp2 ['g_exp3 ...]" ! 955: .Re ! 956: g_exp2 ! 957: .No ! 958: the forms are evaluated from left to right and the value of g_exp2 is ! 959: returned. ! 960: .Lf progn "'g_exp1 ['g_exp2 ...]" ! 961: .Re ! 962: the last g_exp\fIi\fP. ! 963: .Lf progv "'l_locv 'l_initv g_exp1 ..." ! 964: .Wh ! 965: l_locv is a list of symbols and l_initv is a list of expressions. ! 966: .Re ! 967: the value of the last g_exp\fIi\fP evaluated. ! 968: .No ! 969: The expressions in l_initv are evaluated from left to right ! 970: and then lambda-bound to the symbols in l_locv. ! 971: If there are too few expressions in l_initv then the missing values ! 972: are assumed to be nil. ! 973: If there are too many expressions in l_initv then the extra ones are ! 974: ignored (although they are evaluated). ! 975: Then the g_exp\fIi\fP are evaluated left to right. ! 976: The body of a progv is like the body of a progn, it is ! 977: .i not ! 978: a prog body. ! 979: (C.f. ! 980: .i let ) ! 981: .Lf purcopy "'g_exp" ! 982: .Re ! 983: a copy of g_exp with new pure cells allocated wherever possible. ! 984: .No ! 985: pure space is never swept up by the garbage collector, so this should ! 986: only be done on expressions which are not likely to become garbage ! 987: in the future. ! 988: In certain cases, data objects in pure space become read-only after ! 989: a ! 990: .i dumplisp ! 991: and then an attempt to modify the object will result in an illegal memory ! 992: reference. ! 993: .Lf purep "'g_exp" ! 994: .Re ! 995: t iff the object g_exp is in pure space. ! 996: .Lf putd "'s_name 'u_func" ! 997: .Re ! 998: u_func ! 999: .Se ! 1000: this sets the function binding of symbol s_name to u_func. ! 1001: .Lf return "['g_val]" ! 1002: .Re ! 1003: g_val (or nil if g_val is not present) from the enclosing prog or do body. ! 1004: .No ! 1005: this form is only valid in the context of a prog or do body. ! 1006: .Lf selectq "'g_key-form [l_clause1 ...]" ! 1007: .No ! 1008: This function is just like \fIcaseq\fP (see above), except that ! 1009: the symbol \fBotherwise\fP has the same semantics as the ! 1010: symbol \fBt\fP, when used as a comparator. ! 1011: .Lf setarg "'x_argnum 'g_val" ! 1012: .Wh ! 1013: x_argnum is greater than zero and less than or equal to the number of ! 1014: arguments to the lexpr. ! 1015: .Re ! 1016: g_val ! 1017: .Se ! 1018: the lexpr's x_argnum'th argument is set to g-val. ! 1019: .No ! 1020: this can only be used within the body of a lexpr. ! 1021: .Lf throw "'g_val [s_tag]" ! 1022: .Wh ! 1023: if s_tag is not given, it is assumed to be nil. ! 1024: .Re ! 1025: the value of \fI(*throw 's_tag 'g_val)\fP. ! 1026: .Lf *throw "'s_tag 'g_val" ! 1027: .Re ! 1028: g_val from the first enclosing catch with ! 1029: the tag s_tag or with no tag at all. ! 1030: .No ! 1031: this is used in conjunction with ! 1032: .i *catch ! 1033: to cause a clean jump to an enclosing context. ! 1034: .Lf unwind-protect "g_protected [g_cleanup1 ...]" ! 1035: .Re ! 1036: the result of evaluating g_protected. ! 1037: .No ! 1038: Normally g_protected is evaluated and its value ! 1039: remembered, then the g_cleanup\fIi\fP ! 1040: are evaluated and finally the saved value of g_protected is returned. ! 1041: If something should happen when evaluating g_protected which causes ! 1042: control to pass through g_protected and thus through ! 1043: the call to the unwind-protect, ! 1044: then the g_cleanup\fIi\fP will still be evaluated. ! 1045: This is useful if g_protected does something sensitive which ! 1046: must be cleaned up whether or not g_protected completes.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.