;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4Iteration* =Text: 3ITERATION do* 1Special Form* The 2do* special form provides a simple generalized iteration facility, with an arbitrary number of ``index variables'' whose values are saved when the 2do* is entered and restored when it is left, i.e. they are bound by the 2do*. The index variables are used in the iteration performed by 2do*. At the beginning, they are initialized to specified values, and then at the end of each trip around the loop the values of the index variables are changed according to specified rules. 2do* allows the programmer to specify a predicate which determines when the iteration will terminate. The value to be returned as the result of the form may, optionally, be specified. 2do* comes in two varieties, new-style and old-style. The old-style 2do* is obsolete and exists for Maclisp compatibility only. The more general, ``new-style'' 2do* looks like: 3(do ((1var init repeat*) ...)* 3 (1end-test exit-form* ...)* 3 1body*...)* The first item in the form is a list of zero or more index variable specifiers. Each index variable specifier is a list of the name of a variable 1var*, an initial value form 1init*, which defaults to 2nil* if it is omitted, and a repeat value form 1repeat*. If 1repeat* is omitted, the 1var* is not changed between repetitions. If 1init* is omitted, the 1var* is initialized to 2nil*. An index variable specifier can also be just the name of a variable, rather than a list. In this case, the variable has an initial value of 2nil*, and is not changed between repetitions. All assignment to the index variables is done in parallel. At the beginning of the first iteration, all the 1init* forms are evaluated, then the 1vars* are bound to the values of the 1init* forms, their old values being saved in the usual way. Note that the 1init* forms are evaluated 1before* the 1vars* are bound, i.e. lexically 1outside* of the 2do*. At the beginning of each succeeding iteration those 1vars* that have 1repeat* forms get set to the values of their respective 1repeat* forms. Note that all the 1repeat* forms are evaluated before any of the 1vars* is set. The second element of the 2do*-form is a list of an end-testing predicate form 1end-test*, and zero or more forms, called the 1exit-forms*. This resembles a 2cond* clause. At the beginning of each iteration, after processing of the variable specifiers, the 1end-test* is evaluated. If the result is 2nil*, execution proceeds with the body of the 2do*. If the result is not 2nil*, the 1exit-forms* are evaluated from left to right and then 2do* returns. The value of the 2do* is the value of the last 1exit-form*, or 2nil* if there were no 1exit-forms* (1not* the value of the 1end-test*, as you might expect by analogy with 2cond*). Note that the 1end-test* gets evaluated before the first time the body is evaluated. 2do* first initializes the variables from the 1init* forms, then it checks the 1end-test*, then it processes the body, then it deals with the 1repeat* forms, then it tests the 1end-test* again, and so on. If the 2end-test* returns a non-2nil* value the first time, then the body is not executed. If the second element of the form is 2nil*, there is no 1end-test* nor 1exit-forms*, and the 1body* of the 2do* is executed only once. In this type of 2do* it is an error to have 1repeats*. This type of 2do* is no more powerful than 2let*; it is obsolete and provided only for Maclisp compatibility. If the second element of the form is 2(nil)*, the 1end-test* is never true and there are no 1exit-forms*. The 1body* of the 2do* is executed over and over. The resulting infinite loop can be terminated by use of 2return* or 2throw*. 2do* implicitly creates a 2block* with name 2nil*, so 2return* can be used lexically within a 2do* to exit it immediately. This unbinds the 2do* variables and the 2do* form returns whatever values were specified in the 2return* form. See 4(FLOWCTL-2)Static Non-Local Exits* for more information on these matters. The 1body* of the 2do* is actually treated as a 2tagbody*, so that it may contain 2go* tags (see 4(FLOWCTL-2)Tags and Gotos*), but this usage is discouraged as it is often unclear. Examples of the new form of 3do*: 3(do ((i 0 (1+ i)) *; This is just the same as the above example, 3 (n (array-length foo-array)))* 3 ((= i n)) *; but written as a new-style 2do*. 3 (aset 0 foo-array i)) *; Note how the 2setq* is avoided. 3(do ((z list (cdr z)) *; z starts as 2list* and is cdr'd each time. 3 (y other-list) *; y starts as 2other-list*, and is unchanged by the do. 3 (x) *; x starts as 2nil* and is not changed by the 2do*. 3 w) *; w starts as 2nil* and is not changed by the 2do*. 3 (nil) *; The end-test is 2nil*, so this is an infinite loop. 3 1body*) *; Presumably the 1body* uses 2return* somewhere. The construction 3(do ((x e (cdr x))* 3 (oldx x x))* 3 ((null x))* 3 1body*)* exploits parallel assignment to index variables. On the first iteration, the value of 2oldx* is whatever value 2x* had before the 2do* was entered. On succeeding iterations, 2oldx* contains the value that 2x* had on the previous iteration. The 1body* of a 2do* may contains no forms at all. Very often an iterative algorithm can be most clearly expressed entirely in the 1repeats* and 1exit-forms* of a new-style 2do*, and the 1body* is empty. For example, 3(do ((x x (cdr x))* 3 (y y (cdr y))* 3 (z nil (cons (f x y) z))) ;*exploits parallel assignment. 3 ((or (null x) (null y))* 3 (nreverse z)) ;*typical use of 2nreverse*. 3 ) ;*no 2do*-body required. is like 2(maplist 'f x y)* (see 4(FLOWCTL-2)Mapping*). The old-style 2do* exists only for Maclisp compatibility. It looks like: 3(do 1var* 1init* 1repeat* 1end-test* 1body*...)* The first time through the loop 1var* gets the value of the 1init* form; the remaining times through the loop it gets the value of the 1repeat* form, which is re-evaluated each time. Note that the 1init* form is evaluated before 1var* is bound, i.e. lexically 1outside* of the 2do*. Each time around the loop, after 1var* is set, 1end-test* is evaluated. If it is non-2nil*, the 2do* finishes and returns 2nil*. If the 1end-test* evaluated to 2nil*, the 1body* of the loop is executed. As with the new-style do, 2return* and 2go* may be used in the body, and they have the same meaning. Also see 2loop* (4(ASSEMBLER-1)Introduction*), a general iteration facility based on a keyword syntax rather than a list-structure syntax. 3do** 1Special Form* In a word, 2do** is to 2do* as 2let** is to 2let*. 2do** works like 2do* but binds and steps the variables sequentially instead of in parallel. This means that the 1init* form for one variable can use the values of previous variables. The 1repeat* forms refer to the new values of previous variables instead of their old values. Here is an example: 3(do* ((x xlist (cdr x))* 3 (y (car x) (car x)))* 3 (print (list x y)))* On each iteration, 1y*'s value is the car of 1x*. The same construction with 2do* might get an error on entry since 1x* might not be bound yet. 3do-named* 1Special Form* 2do-named* is like 2do* but defines a 2block* with a name explicitly specified by the programmer in addition to the 2block* named 2nil* which every 2do* defines. This makes it possible to use 2return-from* to return from this 2do-named* even from within an inner 2do*. An ordinary 2return* there would return from the inner 2do* instead. 2do-named* is obsolete now that 2block*, which is more general and more coherent, exists. See 4(FLOWCTL-2)Static Non-Local Exits* for more information on 2block* and 2return-from*. The syntax of 2do-named* is like 2do* except that the symbol 2do-named* is immediately followed by the 2block* name, which should be a symbol. Example: 3(do-named george ((a 1 (1+ a))* 3 (d 'foo))* 3 ((> a 4) 7)* 3 (do ((c b (cdr c)))* 3 ((null c))* 3 ...* 3 (return-from george (cons b d))* 3 ...))* is equivalent to 3(block george* 3 (do ((a 1 (1+ a))* 3 (d 'foo))* 3 ((> a 4) 7)* 3 (do ((c b (cdr c)))* 3 ((null c))* 3 ...* 3 (return-from george (cons b d))* 3 ...)))* 2t* as the name of a 2do-named* behaves somewhat peculiarly, and therefore should be avoided. 3do*-named* 1Special Form* This special form offers a combination of the features of 2do** and those of 2do-named*. It is obsolete, as is 2do-named*, since it is cleaner to use 2block*. 3dotimes* 1(index* 1count* 1[value-expression])* 1body...* 1Macro* 2dotimes* is a convenient abbreviation for the most common integer iteration. 2dotimes* performs 1body* the number of times given by the value of 1count*, with 1index* bound to 20*, 21*, etc. on successive iterations. When the 1count* is exhausted, the value of 1value-expression* is returned; or 2nil*, if 1value-expression* is missing. Example: 3(dotimes (i (truncate m n))* 3 (frob i))* is equivalent to: 3(do ((i 0 (1+ i))* 3 (count (truncate m n)))* 3 (( i count))* 3 (frob i))* except that the name 2count* is not used. Note that 2i* takes on values starting at zero rather than one, and that it stops before taking the value 2(truncate m n)* rather than after. You can use 2return* and 2go* and 2tagbody*-tags inside the body, as with 2do*. 2dotimes* forms return the value of 1value-expression*, or 2nil*, unless returned from explicitly with 2return*. For example: 3(dotimes (i 5)* 3 (if (eq (aref a i) 'foo)* 3 (return i)))* This form searches the array that is the value of 2a*, looking for the symbol 2foo*. It returns the fixnum index of the first element of 2a* that is 2foo*, or else 2nil* if none of the elements are 2foo*. 3dolist* 1(item* 1list* 1[value-expression])* 1body...* 1Macro* 2dolist* is a convenient abbreviation for the most common list iteration. 2dolist* performs 1body* once for each element in the list which is the value of 1list*, with 1item* bound to the successive elements. If the list is exhausted, the value of 1value-expression* is returned; or 2nil*, if 1value-expression* is missing. Example: 3(dolist (item (frobs foo))* 3 (mung item))* is equivalent to: 3(do ((lst (frobs foo) (cdr lst))* 3 (item))* 3 ((null lst))* 3 (setq item (car lst))* 3 (mung item))* except that the name 2lst* is not used. You can use 2return* and 2go* and 2tagbody*-tags inside the body, as with 2do*. 3do-forever* 1body...* 1Macro* Executes the forms in the body over and over, or until a non-local exit (such as 2return*). =Node: 4Static Non-Local Exits* =Text: 3STATIC NON-LOCAL EXITS* The static non-local exit allows code deep within a construct to jump to the end of that construct instantly, not executing anything except 2unwind-protect*'s on the way. The construct which defines a static level that can be exited non-locally is called 2block* and the construct which exits it is called 2return-from*. The 2block* being exited must be lexically visible from the 2return-from* which says to exit it; this is what `static' means. By contrast, 2catch* and 2throw* provide for dynamic non-local exits; refer to the following section. Here is an example of using a static non-local exit: 3(block top* 3 (let ((v1 (do-1)))* 3 (when (all-done v1) (return-from top v1))* 3 (do-2))* 3 (do-3)* 3 ...* 3 (do-last))* If 2(all-done v1)* returns non-2nil*, the entire 2block* immediately returns the value of 2v1*. Otherwise, the rest of the body of the block is executed sequentially, and ultimately the value or values of 2(do-last)* are returned. Note that the 2return-from* form is very unusual: it does not ever return a value itself, in the conventional sense. It isn't useful to write 2(setq a (return-from foo 3))*, because when the 2return-from* form is evaluated, the containing 2block* is immediately exited, and the 2setq* never happens. The fact that 2block*'s and 2return-from*'s are matched up lexically means you cannot do this: 3(defun foo (a)* 3 (block foo1* 3 (bar a)))* 3(defun bar (x)* 3 (return-from foo1 x))* The 2(return-from foo1 x)* gets an error because there is no lexically visible 2block* named 2foo1*. The suitable 2block* in the caller, 2foo*, is not even noticed. Static handling allows the compiler to produce good code for 2return-from*. It is also useful with functional arguments: 3(defun first-symbol (list)* 3 (block done* 3 (mapc #'(lambda (elt)* 3 (if (symbolp elt) (return-from done elt)))* 3 list)))* The 2return-from done* sees the 2block done* lexically. Even if 2mapc* had a 2block* in it named 2done* it would have no effect on the execution of 2first-symbol*. When a function is defined with 2defun* with a name which is a symbol, a 2block* whose name is the function name is automatically placed around the body of the function definition. For example, 3(defun foo (a)* 3 (if (evenp a) * 3 (return-from foo (list a)))* 3 (1+ a))* 3(foo 4) => (4)* 3(foo 5) => 6* A function written explicitly with 2lambda* does not have a 2block* unless you write one yourself. A named 2prog*, or a 2do-named*, implicitly defines a 2block* with the specified name. So you can exit those constructs with 2return-from*. In fact, the ability to name 2prog*'s was the original way to define a place for 2return-from* to exit, before 2block* was invented. Every 2prog*, 2do* or 2loop*, whether named or not, implicitly defines a 2block* named 2nil*. Thus, named 2prog*'s define 1two* 2block*'s, one named 2nil* and one named whatever name you specify. As a result, you can use 2return* (an abbreviation for 2return-from nil*) to return from the innermost lexically containing 2prog*, 2do* or 2loop* (or from a 2block nil* if you happen to write one). This function is like 2assq*, but it returns an additional value which is the index in the table of the entry it found. For example, 3(defun assqn (x table)* 3 (do ((l table (cdr l))* 3 (n 0 (1+ n)))* 3 ((null l) nil)* 3 (if (eq (caar l) x)* 3 (return (values (car l) n)))))* There is one exception to this: a 2prog*, 2do* or 2loop* with name 2t* defines only the block named 2t*, no block named 2nil*. The compiler used to make use of this feature in expanding certain built-in constructs into others. 3block* 1name* 1body...* 1Special Form* Executes 1body*, returning the values of the last form in 1body*, but permitting non-local exit using 2return-from* forms present lexically within 1body*. 1name* is not evaluated, and is used to match up 2return-from* forms with their 2block*'ss. 3(block foo* 3 (return-from foo 24) t) => 24* 3(block foo t) => t return-from* 1name* 1values* 1Special Form* Performs a non-local exit from the innermost lexically containing 2block* whose name is 1name*. 1name* is not evaluated. When the compiler is used, 2return-from*'s are matched up with 2block*'s at compile time. 1values* is evaluated and its values become the values of the exited 2block* form. A 2return-from* form may appear as or inside an argument to a regular function, but if the 2return-from* is executed then the function will never actually be called. For example, 3(block done* 3 (foo (if a (return-from done t) nil)))* 2foo* is actually called only if 2a*'s value is 2nil*. This style of coding is not recommended when 2foo* is actually a function. 2return-from* can also be used with zero value forms, or with several value forms. Then 1one* value is returned from each value form. Originally 2return-from* always returned only one value from each value form, even when there was only one value form. Passing back all the values when there is a single 1values* form is a later change, which is also the Common Lisp standard. In fact, the single value form case is much more powerful and subsumes all the others. For example, 3(return-from foo 1 2)* is equivalent to 3(return-from foo (values 1 2))* and 3(return-from foo)* is equivalent to 3(return-from foo (values))* It is unfortunate that the case of one value form is treated differently from all other cases, but the power of being able to propagate any number of values from a single form is worth it. To return precisely one value, use 2(return-from foo (values 1form*))*. It is legal to write simply 2(return-from foo)*, which returns no values from the 2block*. See 4(EVAL-4)Multiple Values* for more information. 3return* 1values* 1Special Form* Is equivalent to 2(return-from nil 1values*)*. It returns from a 2block* whose name is 2nil*. In addition, 2break* (see 4(MISCELL-2)The Lisp Listen Loop*) recognizes the typed-in form 2(return 1value*)* specially. 2break* evaluates 1value* and returns it. 3return-list* 1list* 1Special Form* This function is like 2return* except that each element of 1list* is returned as a separate value from the 2block* that is exited. 2return-list* is obsolete, since 2(return (values-list 1list*))* does the same thing. =Node: 4Tags and Gotos* =Text: 3TAGS AND GOTOS* Jumping to a label or 1tag* is another kind of static non-local exit. Compared with 2return-from*, it allows more flexibility in choosing where to send control to, but does not allow values to be sent along. This is because the tag does not have any way of saying what to 1do* with any values. To define a tag, the 2tagbody* special form is used. In the body of a 2tagbody*, all lists are treated as forms to be evaluated (called 1statements* when they occur in this context). If no goto happens, all the forms are evaluated in sequence and then the 2tagbody* form returns 2nil*. Thus, the statements are evaluated only for effect. An element of the 2tagbody*'s body which is a symbol is not a statement but a tag instead. It identifies a place in the sequence of statements which you can go to. Going to a tag is accomplished by the form 2(go 1tag*)*, executed at any point lexically within the 2tagbody*. 2go* transfers control immediately to the first statement following 1tag* in its 2tagbody*, pausing only to deal with any 2unwind-protect*s that are being exited as a result. If there are no more statements after 1tag* in its 2tagbody*, then that 2tagbody* returns 2nil* immediately. All lexically containing 2tagbody*'s are eligible to contain the specified tag, with the innermost 2tagbody* taking priority. If no suitable tag is found, an error is signaled. The compiler matches 2go*'s with tags at compile time and issues a compiler warning if no tag is found. Example: 3(block nil* 3 (tagbody* 3 (setq x 1some frob*)* 3 loop* 3 1do something** 3 (if 1some predicate* (go endtag))* 3 1do something more** 3 (if (minusp x) (go loop))* 3 endtag* 3 (return z)))* is a kind of iteration made out of go-to's. This 2tagbody* can never exit normally because the 2return* in the last statement takes control away from it. This use of a 2return* and 2block* is how one encapsulates a 2tagbody* to produce a non-2nil* value. It works to 2go* from an internal 2lambda* function to a tag in a lexically containing function, as in 3(defun foo (a)* 3 (tagbody* 3 t1* 3 (bar #'(lambda () (go t1)))))* If 2bar* ever invokes its argument, control goes to 2t1* and 2bar* is invoked anew. Not very useful, but it illustrates the technique. 3tagbody* 1statements-and-tags...* 1Special Form* Executes all the elements of 1statements-and-tags* which are lists (the statements), and then returns 2nil*. But meanwhile, all elements of 1statements-and-tags* which are symbols (the tags) are available for use with 2go* in any of the statements. Atoms other than symbols are meaningless in a 2tagbody*. The reason that 2tagbody* returns 2nil* rather than the value of the last statement is that the designers of Common Lisp decided that one could not reliably return a value from the 2tagbody* by writing it as the last statement since some of the time the expression for the desired value would be a symbol rather than a list, and then it would be taken as a tag rather than the last statement and it would not work. 3go* 1tag* 1Special Form* The 2go* special form is used to ``go-to'' a tag defined in a lexically containing 2tagbody* form (or other form which implicitly expands into a 2tagbody*, such as 2prog*, 2do* or 2loop*). 1tag* must be a symbol. It is not evaluated. 3prog* 1Special Form* 2prog* is an archaic special form which provides temporary variables, static non-local exits, and tags for 2go*. These aspects of 2prog* were individually abstracted out to inspire 2let*, 2block* and 2tagbody*. Now 2prog* is obsolete, as it is much cleaner to use 2let*, 2block*, 2tagbody* or all three of them, or 2do* or 2loop*. But 2prog* appears in so many programs that it cannot be eliminated. A typical 2prog* looks like 2(prog (1variables*...) 1body*...)*, which is equivalent to 3(block nil* 3 (let (1variables*...)* 3 (tagbody 1body*...)))* If the first subform of a 2prog* is a non-2nil* symbol (rather than a list of variables), it is the name of the 2prog*, and 2return-from* (see 4(FLOWCTL-2)Static Non-Local Exits*) can be used to return from it. A 1named prog* looks like 3(prog 1name* (1variables*...) 1body*...)* and is equivalent to 3(block 1name** 3 (block nil* 3 (let (1variables*...)* 3 (tagbody 1body*...)))) prog** 1Special Form* The 2prog** special form is almost the same as 2prog*. The only difference is that the binding and initialization of the temporary variables is done 1sequentially*, so each one can depend on the previous ones. Thus, the equivalent code would use 2let** rather than 2let*. =Node: 4Dynamic Non-Local Exits* =Text: 3DYNAMIC NON-LOCAL EXITS catch* 1tag* 1body...* 1Special Form* 2catch* is a special form used with the 2throw* function to do non-local exits. First 1tag* is evaluated; the result is called the 1tag* of the 2catch*. Then the 1body* forms are evaluated sequentially, and the values of the last form are returned. However, if, during the evaluation of the body, the function 2throw* is called with the same tag as the tag of the 2catch*, then the evaluation of the body is aborted, and the 2catch* form immediately returns the values of the second argument to 2throw* without further evaluating the current 1body* form or the rest of the body. The 1tag*'s are used to match up 2throw*'s with 2catch*'s. 2(catch 'foo 1form*)* catches a 2(throw* 2'foo 1form*)* but not a 2(throw 'bar 1form*)*. It is an error if 2throw* is done when there is no suitable 2catch* (or 2catch-all*; see below). Any Lisp object may be used as a 2catch* tag. The values 2t* and 2nil* for 1tag* are special: a 2catch* whose tag is one of these values catches throws regardless of tag. These are only for internal use by 2unwind-protect* and 2catch-all* respectively. The only difference between 2t* and 2nil* is in the error checking; 2t* implies that after a ``cleanup handler'' is executed control will be thrown again to the same tag, therefore it is an error if a specific catch for this tag does not exist higher up in the stack. With 2nil*, the error check isn't done. Example: 3(catch 'negative* 3 (values* 3 (mapcar #'(lambda (x) * 3 (cond ((minusp x)* 3 (throw 'negative * 3 (values x :negative)))* 3 (t (f x)) )))* 3 y)* 3 :positive))* returns a list of 2f* of each element of 2y*, and 2:positive*, if they are all positive, otherwise the first negative member of 2y*, and 2:negative*. 3catch-continuation* 1tag* 1throw-cont* 1non-throw-cont* 1body...* 1Macro* 3catch-continuation-if* 1cond-form* 1tag* 1throw-cont* 1non-throw-cont* 1body...* The 2catch-continuation* special form makes it convenient to discriminate whether exit is normal or due to a throw. The 1body* is executed inside a 2catch* on 1tag* (which is evaluated). If 1body* returns normally, the function 1non-throw-cont* is called, passing all the values returned by the last form in 1body* as arguments. This function's values are returned from the 2catch-continuation*. If on the other hand a throw to 1tag* occurs, the values thrown are passed to the function 1throw-cont*, and its values are returned. If a continuation is explicitly written as 2nil*, it is not called at all. The arguments that would have been passed to it are returned instead. This is equivalent to using 2values* as the function; but explicit 2nil* is optimized, so use that. 2catch-continuation-if* differs only in that the catch is not done if the value of the 1cond-form* is 2nil*. In this case, the non-throw continuation if any is always called. In the general case, consing is necessary to record the multiple values, but if a continuation is an explicit 2#'(lambda ...)* with a fixed number of arguments, or if a continuation is 2nil*, it is open coded and the consing is avoided. 3throw* 1tag* 1values-form* 1Special Form* 2throw* is the primitive for exiting from a surrounding 2catch*. 1tag* is evaluated, and the result is matched (with 2eq*) against the tags of all active 2catch*'es; the innermost matching one is exited. If no matching 2catch* is dynamically active, an error is signaled. All the values of 1values-form* are returned from the exited 2catch*. 2catch*'es with tag 2nil* always match any 2throw*. They are really 2catch-all*'s. So do 2catch*'es with tag 2t*, which are 2unwind-protect*'s, but if the only matching 2catch*'es are these then an error is signaled anyway. This is because an 2unwind-protect* always throws again after its cleanup forms are finished; if there is nothing to catch after the last 2unwind-protect*, an error will happen then, and it is better to detect the error sooner. The values 2t*, 2nil*, and 20* for 1tag* are reserved and used for internal purposes. 2nil* may not be used, because it would cause confusion in handling of 2unwind-protect*'s. 2t* may only be used with 2*unwind-stack*. 20* and 2nil* are used internally when returning out of an 2unwind-protect*. 3*catch* 1form* 1tag* 1Macro* 3*throw* 1form* 1tag* Old, obsolete names for 2catch* and 2throw*. 3sys:throw-tag-not-seen* (3error*) 1Condition* This is signaled when 2throw* (or 2*unwind-stack*) is used and there is no 2catch* for the specified tag. The condition instance supports these extra operations: 2:tag* The tag being thrown to. 2:value* The value being thrown (the second argument to 2throw*). 2:count* 2:action*The additional two arguments given to 2*unwind-stack*, if that was used. The error occurs in the environment of the 2throw*; no unwinding has yet taken place. The proceed type 2:new-tag* expects one argument, a tag to throw to instead. 3*unwind-stack* 1tag* 1value* 1active-frame-count* 1action* This is a generalization of 2throw* provided for program-manipulating programs such as the debugger. 1tag* and 1value* are the same as the corresponding arguments to 2throw*. A 1tag* of 2t* invokes a special feature whereby the entire stack is unwound, and then the function 1action* is called (see below). During this process 2unwind-protect*'s receive control, but 2catch-all*'s do not. This feature is provided for the benefit of system programs which want to unwind a stack completely. 1active-frame-count*, if non-2nil*, is the number of frames to be unwound. The definition of a frame is implementation-dependent. If this counts down to zero before a suitable 2catch* is found, the 2*unwind-stack* terminates and 1that frame* returns 1value* to whoever called it. This is similar to Maclisp's 2freturn* function. If 1action* is non-2nil*, whenever the 2*unwind-stack* would be ready to terminate (either due to 1active-frame-count* or due to 1tag* being caught as in 2throw*), instead 1action* is called with one argument, 1value*. If 1tag* is 2t*, meaning throw out the whole way, then the function 1action* is not allowed to return. Otherwise the function 1action* may return and its value will be returned instead of 1value* from the 2catch*--or from an arbitrary function if 1active-frame-count* is in use. In this case the 2catch* does not return multiple values as it normally does when thrown to. Note that it is often useful for 1action* to be a stack-group. Note that if both 1active-frame-count* and 1action* are 2nil*, 2*unwind-stack* is identical to 2throw*. 3unwind-protect* 1protected-form* 1cleanup-form...* 1Special Form* Sometimes it is necessary to evaluate a form and make sure that certain side-effects take place after the form is evaluated; a typical example is: 3(progn* 3 (turn-on-water-faucet)* 3 (hairy-function 3 nil 'foo)* 3 (turn-off-water-faucet))* The non-local exit facilities of Lisp create situations in which the above code won't work, however: if 2hairy-function* should use 2throw*, 2return* or 2go* to transfer control outside of the 2progn* form, then 2(turn-off-water-faucet)* will never be evaluated (and the faucet will presumably be left running). This is particularly likely if 2hairy-function* gets an error and the user tells the debugger to give up and flush the computation. In order to allow the above program to work, it can be rewritten using 2unwind-protect* as follows: 3(unwind-protect* 3 (progn (turn-on-water-faucet)* 3 (hairy-function 3 nil 'foo))* 3 (turn-off-water-faucet))* If 2hairy-function* transfers control out of the evaluation of the 2unwind-protect*, the 2(turn-off-water-faucet)* form is evaluated during the transfer of control, before control arrives at the 2catch*, 2block* or 2go* tag to which it is being transferred. If the 2progn* returns normally, then the 2(turn-off-water-faucet)* is evaluated, and the 2unwind-protect* returns the result of the 2progn*. The general form of 2unwind-protect* looks like 3(unwind-protect* 3 1protected-form** 3 1cleanup-form1** 3 1cleanup-form2** 3 ...)* 1protected-form* is evaluated, and when it returns or when it attempts to transfer control out of the 2unwind-protect*, the 1cleanup-forms* are evaluated. The value of the 2unwind-protect* is the value of 1protected-form*. Multiple values returned by the 1protected-form* are propagated back through the 2unwind-protect*. The cleanup forms are run in the variable-binding environment that you would expect: that is, variables bound outside the scope of the 2unwind-protect* special form can be accessed, but variables bound inside the 1protected-form* can't be. In other words, the stack is unwound to the point just outside the 1protected-form*, then the cleanup handler is run, and then the stack is unwound some more. 3catch-all* 1body...* 1Macro* 2(catch-all 1form*)* is like 2(catch 1some-tag form*)* except that it catches a 2throw* to any tag at all. Since the tag thrown to is one of the returned values, the caller of 2catch-all* may continue throwing to that tag if he wants. The one thing that 2catch-all* does not catch is a 2*unwind-stack* with a tag of 2t*. 2catch-all* is a macro which expands into 2catch* with a 1tag* of 2nil*. 2catch-all* returns all the values thrown to it, or returned by the body, plus three additional values: the tag thrown to, the active-frame-count, and the action. The tag value is 2nil* if the body returned normally. The last two values are the third and fourth arguments to 2*unwind-stack* (see 4(FLOWCTL-2)Dynamic Non-Local Exits*) if that was used, or 2nil* if an ordinary 2throw* was done or if the body returned normally. If you think you want this, most likely you are mistaken and you really want 2unwind-protect*. =Node: 4Mapping* =Text: 3MAPPING map* 1fcn* &rest 1lists* 3mapl* 1fcn* &rest 1lists* 3mapc* 1fcn* &rest 1lists* 3maplist* 1fcn* &rest 1lists* 3mapcar* 1fcn* &rest 1lists* 3mapcon* 1fcn* &rest 1lists* 3mapcan* 1fcn* &rest 1lists* Mapping is a type of iteration in which a function is successively applied to pieces of a list. There are several options for the way in which the pieces of the list are chosen and for what is done with the results returned by the applications of the function. For example, 2mapcar* operates on successive 1elements* of the list. As it goes down the list, it calls the function giving it an element of the list as its one argument: first the car, then the cadr, then the caddr, etc., continuing until the end of the list is reached. The value returned by 2mapcar* is a list of the results of the successive calls to the function. An example of the use of 2mapcar* would be 2mapcar*'ing the function 2abs* over the list 2(1 -2 -4.5 6.0e15 -4.2)*, which would be written as 2(mapcar (function abs) '(1 -2 -4.5 6.0e15 -4.2))*. The result is 2(1 2 4.5 6.0e15 4.2)*. In general, the mapping functions take any number of arguments. For example, 3(mapcar 1f* 1x1* 1x2* ... 1xn*)* In this case 1f* must be a function of 1n* arguments. 2mapcar* proceeds down the lists 1x1, x2, ...,* 1xn* in parallel. The first argument to 1f* comes from 1x1*, the second from 1x2*, etc. The iteration stops as soon as any of the lists is exhausted. (If there are no lists at all, then there are no lists to be exhausted, so 1f* is called repeatedly without end. This is an obscure way to write an infinite loop. It is supported for consistency.) If you want to call a function of many arguments where one of the arguments successively takes on the values of the elements of a list and the other arguments are constant, you can use a circular list for the other arguments to 2mapcar*. The function 2circular-list* is useful for creating such lists; see 4(MANLISTSTR-1)Lists*. There are five other mapping functions besides 2mapcar*. 2maplist* is like 2mapcar* except that the function is applied to the list and successive cdrs of that list rather than to successive elements of the list. 2map* (or 2mapl*) and 2mapc* are like 2maplist* and 2mapcar* respectively, except that they don't return any useful value. These functions are used when the function is being called merely for its side-effects, rather than its returned values. 2mapcan* and 2mapcon* are like 2mapcar* and 2maplist* respectively, except that they combine the results of the function using 2nconc* instead of 2list*. That is, 2mapcon* could have been defined by 3(defun mapcon (f x y)* 3 (apply 'nconc (maplist f x y)))* Of course, this definition is less general than the real one. Sometimes a 2do* or a straightforward recursion is preferable to a map; however, the mapping functions should be used wherever they naturally apply because this increases the clarity of the code. Often 1f* is a lambda-expression, rather than a symbol; for example, 3(mapcar (function (lambda (x) (cons x something)))* 3 some-list)* The functional argument to a mapping function must be a function, acceptable to 2apply*--it cannot be a macro or the name of a special form. Here is a table showing the relations between the six map functions. 3 applies function to* 3 | successive | successive |* 3 | sublists | elements |* 3 ---------------+--------------+---------------+* 3 its own | | | * 3 second | map(l) | mapc |* 3 argument | | |* 3 ---------------+--------------+---------------+* 3 list of the | | |* 3returns function | maplist | mapcar |* 3 results | | |* 3 ---------------+--------------+---------------+* 3 nconc of the | | |* 3 function | mapcon | mapcan |* 3 results | | |* 3 ---------------+--------------+---------------+* Note that 2map* and 2mapl* are synonymous. 2map* is the traditional name of this function. 2mapl* is the Common Lisp name. In Common Lisp, the function 2map* does something different and incompatible; see 2cli:map*, 4(GENERIC-1)Mapping On Sequences*. 2mapl* works the same in traditional Zetalisp and Common Lisp. There are also functions (2mapatoms* and 2mapatoms-all*) for mapping over all symbols in certain packages. See the explanation of packages (4(PACKAGES-0)Packages*). You can also do what the mapping functions do in a different way by using 2loop*. See 4(ASSEMBLER-1)Introduction*.