;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Introduction to Flow of Control =Text: 3INTRODUCTION TO FLOW OF CONTROL* Lisp provides a variety of structures for flow of control. Function application is the basic method for construction of programs. Operations are written as the application of a function to its arguments. Usually, Lisp programs are written as a large collection of small functions, each of which implements a simple operation. These functions operate by calling one another, and so larger operations are defined in terms of smaller ones. A function may always call itself in Lisp. The calling of a function by itself is known as 1recursion*; it is analogous to mathematical induction. The performing of an action repeatedly (usually with some changes between repetitions) is called 1iteration*, and is provided as a basic control structure in most languages. The 1do* statement of PL/I, the 1for* statement of ALGOL/60, and so on are examples of iteration primitives. Lisp provides two general iteration facilities: 2do* and 2loop*, as well as a variety of special-purpose iteration facilities. (2loop* is sufficiently complex that it is explained in its own chapter later in the manual; see 4(LOOP-0)The LOOP Iteration Macro*.) A 1conditional* construct is one which allows a program to make a decision, and do one thing or another based on some logical condition. Lisp provides the simple one-way conditionals 2and* and 2or*, the simple two-way conditional 2if*, and more general multi-way conditionals such as 2cond* and 2selectq*. The choice of which form to use in any particular situation is a matter of personal taste and style. There are some 1non-local exit* control structures, analogous to the 1leave*, 1exit*, and 1escape* constructs in many modern languages. Zetalisp provides for both static (lexical) non-local exits with 2block* and 2return-from* and dynamic non-local exits with 2catch* and 2throw*. Another kind of non-local exit is the goto, provided by the 2tagbody* and 2go* constructs. Zetalisp also provides a coroutine capability, explained in the section on 1stack-groups* (4(STACKGROUPS-0)Stack Groups*), and a multiple-process facility (see 4(PROCESSES-0)Processes*). There is also a facility for generic function calling using message passing; see 4(FLAVOR-0)Objects, Message Passing, and Flavors*. =Node: 4Compound Statements* =Text: 3COMPOUND STATEMENTS progn* 1body...* 1Special Form* The 1body* forms are evaluated in order from left to right and the value of the last one is returned. 2progn* is the primitive control structure construct for "compound statements". Example: 3(foo (cdr a)* 3 (progn (setq b (extract frob))* 3 (car b))* 3 (cadr b))* Lambda-expressions, 2cond* forms, 2do* forms, and many other control structure forms use 2progn* implicitly, that is, they allow multiple forms in their bodies. 3prog1* 1first-form* 1body...* 1Special Form* 2prog1* is similar to 2progn*, but it returns the value of its 1first* form rather than its last. It is most commonly used to evaluate an expression with side effects, and return a value which must be computed 1before* the side effects happen. Example: 3(setq x (prog1 y (setq y x)))* interchanges the values of the variables 1x* and 1y*. 2prog1* never returns multiple values. 3prog2* 1first-form* 1second-form* 1body...* 1Special Form* 2prog2* is similar to 2progn* and 2prog1*, but it returns its 1second* form. It is included largely for compatibility with old programs. =Node: 4Conditionals* =Text: 3CONDITIONALS if* 1Special Form* 2if* is the simplest conditional form. The ``if-then'' form looks like: 3(if 1predicate-form* 1then-form*)* 1predicate-form* is evaluated, and if the result is non-2nil*, the 1then-form* is evaluated and its result is returned. Otherwise, 2nil* is returned. In the ``if-then-else'' form, it looks like 3(if 1predicate-form* 1then-form* 1else-form*)* 1predicate-form* is evaluated, and if the result is non-2nil*, the 1then-form* is evaluated and its result is returned. Otherwise, the 1else-form* is evaluated and its result is returned. If there are more than three subforms, 2if* assumes you want more than one 1else-form*; if the predicate returns 2nil*, they are evaluated sequentially and the result of the last one is returned. 3when* 1condition* 1body...* 1Macro* If 1condition* evaluates to something non-2nil*, the 1body* is executed and its value(s) returned. Otherwise, the value of the 2when* is 2nil* and the 1body* is not executed. 3unless* 1condition* 1body...* 1Macro* If 1condition* evaluates to 2nil*, the 1body* is executed and its value(s) returned. Otherwise, the value of the 2unless* is 2nil* and the 1body* is not executed. 3cond* 1Special Form* The 2cond* special form consists of the symbol 2cond* followed by several 1clauses*. Each clause consists of a predicate form, called the 1condition*, followed by zero or more 1body* forms. 3(cond (1condition body body*...)* 3 (1condition*)* 3 (1condition body* ...)* 3 ... )* The idea is that each clause represents a case which is selected if its condition is satisfied and the conditions of all preceding clauses were not satisfied. When a clause is selected, its body forms are evaluated. 2cond* processes its clauses in order from left to right. First, the condition of the current clause is evaluated. If the result is 2nil*, 2cond* advances to the next clause. Otherwise, the cdr of the clause is treated as a list of body forms which are evaluated in order from left to right. After evaluating the body forms, 2cond* returns without inspecting any remaining clauses. The value of the 2cond* form is the value of the last body form evaluated, or the value of the condition if there were no body forms in the clause. If 2cond* runs out of clauses, that is, if every condition evaluates to 2nil*, and thus no case is selected, the value of the 2cond* is 2nil*. Example: 3(cond ((zerop x) ;*First clause: 3 (+ y 3)) ; (zerop x)* is the condition. 3 ; (+ y 3)* is the body. 3 ((null y) ;*A clause with 2 body forms: 3 (setq y 4) ;* this 3 (cons x z)) ;* and this. 3 (z) ;*A clause with no body forms: the condition is 3 ;* just 2z*. If 2z* is non-2nil*, it is returned. 3 (t ;*A condition of 3t* 3 105) ;* is always satisfied. 3 ) ;*This is the end of the cond. 3cond-every* 1Macro* 2cond-every* has the same syntax as 2cond*, but executes every clause whose condition is satisfied, not just the first. If a condition is the symbol 2otherwise*, it is satisfied if and only if no preceding condition is satisfied. The value returned is the value of the last body form in the last clause whose condition is satisfied. Multiple values are not returned. 3and* 1form...* 1Special Form* 2and* evaluates the 1form*s one at a time, from left to right. If any 1form* evaluates to 2nil*, 2and* immediately returns 2nil* without evaluating the remaining 1forms*. If all the 1forms* evaluate to non-2nil* values, 2and* returns the value of the last 1form*. 2and* can be used in two different ways. You can use it as a logical 2and* function, because it returns a true value only if all of its arguments are true: 3(if (and socrates-is-a-person* 3 all-people-are-mortal)* 3 (setq socrates-is-mortal t))* Because the order of evaluation is well-defined, you can do 3(if (and (boundp 'x)* 3 (eq x 'foo))* 3 (setq y 'bar))* knowing that the 2x* in the 2eq* form will not be evaluated if 2x* is found to be void. You can also use 2and* as a simple conditional form: 3(and (setq temp (assq x y))* 3 (rplacd temp z))* 3(and bright-day* 3 glorious-day* 3 (princ "It is a bright and glorious day."))* but 2when* is usually preferable. Note: 2(and) => t*, which is the identity for the 2and* operation. 3or* 1form...* 1Special Form* 2or* evaluates the 1form*s one by one from left to right. If a 1form* evaluates to 2nil*, 2or* proceeds to evaluate the next 1form*. If there are no more 1form*s, 2or* returns 2nil*. But if a 1form* evaluates to a non-2nil* value, 2or* immediately returns that value without evaluating any remaining 1form*s. As with 2and*, 2or* can be used either as a logical 2or* function, or as a conditional: 3(or it-is-fish it-is-fowl)* 3(or it-is-fish it-is-fowl* 3 (print "It is neither fish nor fowl.")* but it is often possible and cleaner to use 2unless* in the latter case. Note: 2(or) => nil*, the identity for this operation. 3selectq* 1Macro* 3case* 3caseq* 2selectq* is a conditional which chooses one of its clauses to execute by comparing the value of a form against various constants using 2eql*. Its form is as follows: 3(selectq 1key-form** 3 (1test body*...)* 3 (1test body*...)* 3 (1test body*...)* 3 ...)* The first thing 2selectq* does is to evaluate 1key-form*; call the resulting value 1key*. Then 2selectq* considers each of the clauses in turn. If 1key* matches the clause's 1test*, the body of the clause is evaluated, and 2selectq* returns the value of the last body form. If there are no matches, 2selectq* returns 2nil*. A 1test* may be any of: 21) A symbol* If the 1key* is 2eql* to the symbol, it matches. 22) A number* If the 1key* is 2eql* to the number, it matches. 1key* must have the same type and the same value as the number. 23) A list* If the 1key* is 2eql* to one of the elements of the list, then it matches. The elements of the list should be symbols or numbers. 24) t or otherwise* The symbols 2t* and 2otherwise* are special tests which match anything. Either symbol may be used, it makes no difference; 2t* is mainly for compatibility with Maclisp's 2caseq* construct. To be useful, this should be the last clause in the 2selectq*. Example: 3(selectq x* 3 (foo (do-this))* 3 (bar (do-that))* 3 ((baz quux mum) (do-the-other-thing))* 3 (otherwise (ferror nil "Never heard of ~S" x)))* is equivalent to 3(cond ((eq x 'foo) (do-this))* 3 ((eq x 'bar) (do-that))* 3 ((memq x '(baz quux mum)) (do-the-other-thing))* 3 (t (ferror nil "Never heard of ~S" x)))* Note that the 1tests* are 1not* evaluated; if you want them to be evaluated use 2select* rather than 2selectq*. 2case* is the Common Lisp name for this construct. 2caseq* is the Maclisp name; it identical to 2selectq*, which is not totally compatible with Maclisp, because 2selectq* accepts 2otherwise* as well as 2t* where 2caseq* would not accept 2otherwise*, and because Maclisp does some error-checking that 2selectq* does not. Maclisp programs that use 2caseq* work correctly so long as they don't use the symbol 2otherwise* as a key. 3ecase* 1key-form* 1clauses...* 1Macro* Like 2case* except that an uncorrectable error is signaled if every clause fails. 2t* or 2otherwise* clauses are not allowed. 3ccase* 1place* 1clauses...* 1Macro* Like 2ecase* except that the error is correctable. The first argument is called 1place* because it must be 2setf*'able. If the user proceeds from the error, a new value is read and stored into 1place*; then the clauses are tested again using the new value. Errors repeat until a value is specified which makes some clause succeed. Also see 2defselect* (4(FUNCTIONS-2)Function-Defining Special Forms*), a special form for defining a function whose body is like a 2selectq*. 3select* 1Macro* 2select* is like 2selectq*, except that the elements of the 1tests* are evaluated before they are used. This creates a syntactic ambiguity: if 2(bar baz)* is seen the first element of a clause, is it a list of two forms, or is it one form? 2select* interprets it as a list of two forms. If you want to have a clause whose test is a single form, and that form is a list, you have to write it as a list of one form. Example: 3(select (frob x)* 3 (foo 1)* 3 ((bar baz) 2)* 3 (((current-frob)) 4)* 3 (otherwise 3))* is equivalent to 3(let ((var (frob x)))* 3 (cond ((eq var foo) 1)* 3 ((or (eq var bar) (eq var baz)) 2)* 3 ((eq var (current-frob)) 4)* 3 (t 3))) selector* 1Macro* 2selector* is like 2select*, except that you get to specify the function used for the comparison instead of 2eq*. For example, 3(selector (frob x) equal* 3 (('(one . two)) (frob-one x))* 3 (('(three . four)) (frob-three x))* 3 (otherwise (frob-any x)))* is equivalent to 3(let ((var (frob x)))* 3 (cond ((equal var '(one . two)) (frob-one x))* 3 ((equal var '(three . four)) (frob-three x))* 3 (t (frob-any x)))) select-match* 1Macro* 2select-match* is like 2select* but each clause can specify a pattern to match the key against. The general form of use looks like 3(select-match 1key-form** 3 (1pattern* 1condition* 1body*...)* 3 (1pattern* 1condition* 1body*...)* 3 ...* 3 (otherwise 1body*...))* The value of 1key-form* is matched against the 1patterns* one at a time until a match succeeds and the accompanying 1condition* evaluates to something non-2nil*. At this point the 1body* of that clause is executed and its value(s) returned. If all the patterns/conditions fail, the 1body* of the 2otherwise* clause (if any) is executed. A pattern can test the shape of the key object, and set variables which the 1condition* form can refer to. All the variables set by the patterns are bound locally to the 2select-match* form. The patterns are matched using 2list-match-p* (4(MANLISTSTR-1)Lists*). Example: 3(select-match '(a b c) * 3 (`(,x b ,x) t (vector x))* 3 (`((,x ,y) b . ,ignore) t (list x y))* 3 (`(,x b ,y) (symbolp x) (cons x y))* 3 (otherwise 'lose-big))* returns 2(a . c)*, having checked 2(symbolp 'a)*. The first clause matches only if the there are three elements, the first and third elements are 2equal* and the second element is 2b*. The second matches only if the first element is a list of length two and the second element is 2b*. The third clause accepts any list of length three whose second element is 2b*. The fourth clause accepts anything that did not match the previous clauses. 2select-match* generates highly optimized code using special instructions. 3dispatch* 1Macro* 2(dispatch 1byte-specifier* 1number* 1clauses...*)* is the same as 2select* (not 2selectq*), but the key is obtained by evaluating 2(ldb 1byte-specifier number*)*. 1byte-specifier* and 1number* are both evaluated. Byte specifiers and 2ldb* are explained on 4(NUMBERS-2)Byte Manipulation Functions*. Example: 3(princ (dispatch (byte 2 13) cat-type* 3 (0 "Siamese.")* 3 (1 "Persian.")* 3 (2 "Alley.")* 3 (3 (ferror nil* 3 "~S is not a known cat type."* 3 cat-type))))* It is not necessary to include all possible values of the byte which is dispatched on. 3selectq-every* 1Macro* 2selectq-every* has the same syntax as 2selectq*, but, like 2cond-every*, executes every selected clause instead of just the first one. If an 2otherwise* clause is present, it is selected if and only if no preceding clause is selected. The value returned is the value of the last form in the last selected clause. Multiple values are not returned. Example: 3(selectq-every animal* 3 ((cat dog) (setq legs 4))* 3 ((bird man) (setq legs 2))* 3 ((cat bird) (put-in-oven animal))* 3 ((cat dog man) (beware-of animal)))* =Node: 4Comparison Predicates* =Text: 3COMPARISON PREDICATES eq* 1x* 1y* 2(eq 1x y*) => t* if and only if 1x* and 1y* are the same object. It should be noted that things that print the same are not necessarily 2eq* to each other. In particular, numbers with the same value need not be 2eq*, and two similar lists are usually not 2eq*. Examples: 3(eq 'a 'b) => nil* 3(eq 'a 'a) => t* 3(eq (cons 'a 'b) (cons 'a 'b)) => nil* 3(setq x (cons 'a 'b)) (eq x x) => t* Note that in Zetalisp equal fixnums are 2eq*; this is not true in Maclisp. Equality does not imply 2eq*-ness for other types of numbers. To compare numbers, use 2=*; see 4(NUMBERS-1)Numeric Comparisons*. 3neq* 1x* 1y* 2(neq 1x y*)* = 2(not (eq 1x y*))*. This is provided simply as an abbreviation for typing convenience. 3eql* 1x* 1y* 2eql* is the same as 2eq* except that if 1x* and 1y* are numbers of the same type they are 2eql* if they are 2=*. 3equal* 1x* 1y* The 2equal* predicate returns 2t* if its arguments are similar (isomorphic) objects. Two numbers are 2equal* if they have the same value and type (for example, a float is never 2equal* to a fixnum, even if 2=* is true of them). For conses, 2equal* is defined recursively as the two cars being 2equal* and the two cdrs being equal. Two strings are 2equal* if they have the same length, and the characters composing them are the same; see 2string=*, 4(CHARSTR-2)Basic String Operations*. Alphabetic case is significant. All other objects are 2equal* if and only if they are 2eq*. Thus 2equal* could have been defined by: 3(defun equal (x y)* 3 (cond ((eq x y) t)* 3 ((and (numberp x) (numberp y))* 3 (= x y))* 3 ((and (stringp x) (stringp y))* 3 (string-equal x y))* 3 ((and (consp x) (consp y))* 3 (and (equal (car x) (car y))* 3 (equal (cdr x) (cdr y))))))* As a consequence of the above definition, it can be seen that 2equal* may compute forever when applied to looped list structure. In addition, 2eq* always implies 2equal*; that is, if 2(eq a b)* then 2(equal a b)*. An intuitive definition of 2equal* (which is not quite correct) is that two objects are 2equal* if they look the same when printed out. For example: 3(setq a '(1 2 3))* 3(setq b '(1 2 3))* 3(eq a b) => nil* 3(equal a b) => t* 3(equal "Foo" "foo") => nil equalp* 1x* 1y* 2equalp* is a broader kind of equality than 2equal*. Two objects that are 2equal* are always 2equalp*. In addition, numbers of different types are 2equalp* if they are 2=*. Two character objects are 2equalp* if they are 2char-equal* (that is, they are compared ignoring font, case and meta bits). Two arrays of any sort are 2equalp* if they have the same dimensions and corresponding elements are 2equalp*. In particular, this means that two strings are 2equalp* if they match ignoring case and font information. 3(equalp "Foo" "foo") => t* 3(equalp '1 '1.0) => t* 3(equalp '(1 "Foo") '(1.0 "foo")) => t* Because 2equalp* is a Common Lisp function, it regards a string as having character objects as its elements: 3(equalp "Foo" #(#/F #/o #/o)) => t* 3(equalp "Foo" #(#/F #/o #/o)) => nil not* 1x* 3null* 1x* 2not* returns 2t* if 1x* is 2nil*, else 2nil*. 2null* is the same as 2not*; both functions are included for the sake of clarity. Use 2null* to check whether something is 2nil*; use 2not* to invert the sense of a logical value. Some people prefer to distinguish between 2nil* as falsehood and 2nil* as the empty list by writing: 3(cond ((not (null lst)) ... )* 3 ( ... ))* rather than 3(cond (lst ... )* 3 ( ... ))* There is no loss of efficiency, since these compile into exactly the same instructions.