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