REF CONTROL Titch Le Bek, Rob Duncan, 1986 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< LISP CONTROL PROCEDURES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file briefly describes the functions, variables and constants documented in Chapter 7 of the standard Common Lisp guide, which is: Common Lisp: The Language (Guy L. Steele, Digital Press, 1984). ------------------------------------------------- 1 A Listing of Functions Variables and Constants ------------------------------------------------- (apply fn arg &rest args) [function] Returns the result of applying fn to the list of arguments (arg . args). fn may be a symbol, function object, or list of the form (setf symbol). call-arguments-limit [constant] The upper exclusive bound on the number of arguments that may be passed to a function. Value in this implementation: 536870912. (block name {form}*) [special-form] Executes forms from left to right returning the result of the last form evaluated as the value of the block named. (boundp symbol) [function] True if the dynamic variable named by symbol has a value; nil otherwise. (case keyform {({({key}*) | key} {form}*)}*) [macro] case is similar to cond in selecting one clause and then executing all its consequents. It differs in its mechanism for clause selection: the keyform is evaluated to produce a key-object. If the key-object is eql to one of the given keys then the {form}* of the clause in which the matching key occurred are evaluated, and the value of the last form is the value of the whole case construct. The keys are not evaluated so must all be literals and no key can appear in more than one clause. The symbols t and otherwise can be used in the last clause of the case in place of a list of keys; that clause will then match any key-object not matched by a previous clause. If no clause matches the key-object, case returns nil. (catch tag {form}*) [special-form] The {form}* are evaluated as an implicit progn. If the catch tag is matched by a throw tag during the execution of {form}* then the evaluation of {form}* is aborted and the multiple values resulting from the throw are returned as the result of the catch. Otherwise the results of the last form are returned. catch tags are compared with EQ, so should not be numbers or characters. (cond {(test {form}*)}*) [macro] cond has a number of clauses which are lists of forms. Each clause consists of a test followed by zero or more consequents. The first test that evaluates to non-nil is selected, its consequents are evaluated and the result of the last form is returned. All other clauses are ignored. If cond runs out of clauses it returns the value nil. (define-modify-macro name lambda-list function [doc-string]) [macro] Defines a read-modify-write macro called name. function is applied to the old contents of a generalized variable (the first subform of the macro) to get the new contents. lambda-list describes the remaining arguments for the function. doc-string is documentation for the macro name being defined. incf is an example of such a macro. (define-setf-method function lambda-list [macro] {declaration | doc-string}* {form}*) define-setf-method defines how to setf a generalized variable reference that is obtained by evaluating its name function. lambda-list describes the subforms of function. The result of evaluating {form}* is the five values representing the setf method. (defsetf access-fn update-fn [doc-string]) [macro] (defsetf access-fn lambda-list ({var}*) {declaration | doc-string}* {form}*) defsetf defines how to setf a generalized variable which is obtained by evaluating the function or macro access-fn. update-fn names a function that takes one more argument than access-fn. When setf is given a place that is a call on access-fn it expands into a call on update-fn that is given all the arguments to access-fn and also the new value. lambda-list describes the arguments of access-fn. var describes the value to be stored into the generalized variable reference which is returned by setf. (do ({(var [init [step]])}*) [macro] (end-test {result-form}*) {declaration}* {tag | statement}*) do provides a generalized iteration facility with an arbitrary number of "index variables" each of which may have an initial value init and a stepping form step. Before the first iteration, all the initial vars are bound in parallel to their init values; before subsequent iterations, the vars are assigned to in parallel with their step values (vars without steps are left unchanged). Each iteration proceeds by evaluating end-test; if this is nil, execution continues with the body of the do, otherwise {result-form}* is evaluated and the result of the last form is returned as the result of the whole do construct. (do* ({(var [init [step]])}*) [macro] (end-test {result-form}*) {declaration}* {tag | statement}*) do* is exactly like do except that the initial bindings of vars to init values and the updating of vars with their step values is done sequentially rather than in parallel. This means that the init or step form for a variable var-j can make use of the new value of any variable var-i which precedes it in the list of index variables. (dolist (var list [form]) {declaration}* {tag | statement}*) [macro] dolist provides straightforward iteration over the elements of the evaluated form list. The body is executed once for each element of the list with the variable var bound to it, then form is evaluated and the result is the value of dolist. var is bound in form to nil. (dotimes (var count [form]) {declaration}* {tag | statement}*) [macro] dotimes provides straightforward iteration over a sequence of integers. count must be a form which evaluates to an integer; the body of the loop is evaluated exactly once for each integer from 0 (inclusive) to count (exclusive) with var bound to the integer, then form is evaluated and the result is the value of dotimes. var is bound in form to the number of times the loop body was executed. (fboundp fname) [function] If fname is a symbol, returns true if that symbol has a global function definition. If fname is a list of the form (setf symbol), returns true if a setf method has been defined for symbol. In either case returns nil if fname is undefined. (fdefinition fname) [function] Returns the global function definition of fname, which may be either a symbol or list of the form (setf symbol). An error is signaled if fname is not defined. (flet ({(name lambda-list [decs-and-doc] body)}*) [special-form] {declaration}* {form}*) Establishes local function definitions for each name, and then executes {form}*, returning the value of the last form. Each local function definition is similar in form to a defun statement. The scope of the local function bindings is just {form}*. Thus flet cannot be used to define recursive (or mutually recursive) local functions. (For this, use labels). (fmakunbound fname) [function] Removes the global function definition of fname. Returns fname as the result value. fname may be a symbol or a list of the form (setf symbol). (funcall fn &rest args) [function] Returns the result of fn applied to args. fn may be a symbol, function object, or list of the form (setf symbol). (function fn) [special-form] Returns the function object denoted by fn in the current lexical environment. fn may be a symbol, lambda expression, or list of the form (setf symbol). The form (function fn) may be abbreviated to #'fn. (get-setf-method form &optional env) [function] Returns five values constituting the setf method for form. env specifies the lexical environment. It defaults to nil (the null lexical environment). (get-setf-method-multiple-value form &optional env) [function] Returns five values constituting the setf method for form. This is the same as get-setf-method except that it does not check the number of store variables. It is used in cases that allow storing multiple into a generalized variable. (go tag) [special-form] Used to do a "go to" within a tagbody construct. The tag must be a symbol or an integer; it is not evaluated. go transfers control to the point in the body labelled by a tag eql to the one given. An error is signaled if no such tag can be found. go does not return a value. (if test then [else]) [special-form] Corresponds to the "if-then-else" construct of most languages. test is evaluated. If the result is non nil then the form then is selected,otherwise the form else is selected. else may be ommited, in which case if returns nil if test is nil. (labels ({(name lambda-list [decs-and-doc] body)}*) [special-form] {declaration}* {form}*) Establishes local function definitions for each name, and then executes {form}*, returning the value of the last form. Each local function definition is similar in form to a defun statement. labels, unlike flet, can be used to define recursive or mutually recursive local functions. This is because the scope of the new function bindings encompasses not only {form}* but also their definitions. (let ({var | (var [value])}*) [special-form] {declaration}* {form}*) Used to execute a series of forms with specified variables bound to specified values. The variable bindings are performed in parallel. The bindings are lexical with indefinite extent. let evaluates all the {form}* returning the result of the last form. (let* ({var | (var [value])}*) [special-form] {declaration}* {form}*) let* is similar to let but the bindings of variables are performed sequentially. This allows value forms to refer to variables previously bound in the let* form. (loop {form}*) [macro] See REF * LOOP. (loop-finish) [macro] Causes control to be returned from a loop. Only legal inside a loop form. (macrolet ({(name lambda-list [decs-and-doc] body)}*) [special-form] {declaration}* {form}*) Similar to flet: establishes local macro definitions which are valid within the lexical scope of the main body {form}*. Each local macro definition is similar in form to a defmacro statement. (makunbound symbol) [function] makunbound causes the dynamic variable symbol to become unbound (have no value). (mapc function list &rest lists) [function] mapc works like mapcar but does not accumulate the results of the calling function: it is used for its side effects rather than its returned values. Returns list. (mapcan function list &rest lists) [function] mapcan is like mapcar except that it combines the results of function using nconc instead of list. This allows the mapped function to return a variable number of items to be put into the output list. (mapcar function list &rest lists) [function] mapcar operates on successive elements of lists. It applies function first to the car of each list, then to the cadr and so on; function must take as many arguments as there are lists in lists. It terminates as soon as the shortest argument list has been exhausted, and returns a list of the results of the successive function calls. (mapcon function list &rest lists) [function] mapcon is like maplist except that it combines the results of function using nconc instead of list. It allows the mapped function to return a variable number of items to be put into the output list. (mapl function list &rest lists) [function] mapl is like maplist but does not accumulate the results of the calling function: it is used when the function is being called for its side effects rather than its returned values. Returns list. (maplist function list &rest lists) [function] maplist is like mapcar except that function is first applied to the complete lists and successive cdr's of the lists rather than successive elements. (multiple-value-bind ({var}*) {values-form}* [macro] {declaration}* {form}*) Each var is bound to the respective value returned by values-form. The {form}* are executed with the bound variables and the results are returned. (multiple-value-call function {form}*) [special-form] function is evaluated to obtain a function and then all the forms are evaluated and their results (which may be more than one for each) are saved. The result is whatever is returned by applying function to all of the results. (multiple-value-list form) [macro] multiple-value-list evaluates form and returns a list of the multiple values it returned. It is the inverse of values-list. (multiple-value-prog1 form {form}*) [special-form] Evaluates the first form and saves all the values produced. The other forms are evaluated and their results discarded. The values of the first form are returned. (multiple-value-setq ({var}*) form) [macro] form is evaluated and the variables of {var}* are set to the values returned. nil is assigned to variables without values and if there are more values than variables they are discarded. The first value returned by form is returned. This is nil if there are zero values. multiple-values-limit [constant] The upper exclusive bound on the number of values that may be returned from a function. Value in this implementation: 536870912. (nth-value n form) [macro] Returns the n'th value produced by evaulating form. n is also evaluated. (prog ({var | (var [macro] {declaration}* {tag | statement}*) prog is a synthesis of let, block, and tagbody. It allows bound variables and the use of return and go. The variable list is processed exactly as the list in a let statement. The prog body is executed as a tagbody construct. go may be used to transfer control to a tag. return may be used to exit from a prog construct. (prog* ({var | (var [init])}*) [macro] {declaration}* {tag | statement}*) prog* is the same as prog except that the binding and initialization of the temporary variables is sequential so that the init form for each one can use the values of previous ones. (prog1 {form}*) [macro] prog1 is similar to progn but it returns the value of the first form after evaluating the others. It is used to evaluate an expression with side effects and return a value that must be computed before the side effects happen. (prog2 {form}*) [macro] prog2 is similar to prog1 but it returns the value of its second form. (progn {form}*) [special-form] Evaluates the forms sequentially discarding all their values except that of the last form whose value(s) are returned. (progv {var}* {values}* {form}*) [special-form] Allows binding of dynamic variables whose names may be determined at run time. The sequence of forms is evaluated with the dynamic variables named in {var}* bound to corresponding values in {values}*. The results are those of the last form in {form}*. The bindings of the dynamic variables are undone on exit from the progv form. (psetf {place value}*) [macro] psetf is like setf except that if there is more than one pair the assignments are done in parallel. psetf always returns nil. (psetq {var form}*) [macro] psetq is like setq except the assignments happen in parallel. All the forms are evaluated and the variables are set to the resulting values. The value of psetq is nil. (quote object) [special-form] object may be any Lisp object. quote ensures that object is not evaluated. object is written as a constant value in the program. (return [result]) [macro] return is identical to (return-from nil). It returns from a block named nil. Blocks estalished implicitly by iteration constructs such as do are named nil, so that return will exit properly. (return-from name [form]) [special-form] return-from is used to return from a block. name is not evaluated and must be a symbol. A block construct with the same name must lexically enclose the occurrance of return-from. Whatever the evaluation of result produces is immediately returned from the block. (rotatef {place}*) [macro] place is a generalized variable acceptable to setf. The values in place1 through placen are accessed and saved. Values 2 through n and value 1 are then stored into place1 through placen : It is as if all the places form an end-around shift register that is rotated one place to the left with the value of place1 being shifted around the end to placen. (set symbol value) [function] Returns the dynamic variable symbol with value as its value. (setf {place value}*) [macro] place evaluates to an access function. setf expands into an update form that stores the result of evaluating the form value into the place referred to by the access-form. If there is more than one place value pair they are processed sequentially. (setq {var form}*) [special-form] setq is the "simple variable assignment statement" of Lisp. Its arguments are in variable value pairs. Corresponding values are assigned sequentially so later forms may use earlier evaluated variable values. setq may be used for assignment of both lexical and special variables. (shiftf {place}+ value) [macro] Each place is any form acceptable as a generalized variable to setf. The values in place1 through to placen are accessed and saved. value is evaluated for a total of n+1 values. Values 2 through n+1 are stored into place1 through placen and the value of place1 is returned. (special-form-p symbol) [function] Returns a non-nil value if symbol is a special form, and otherwise nil. (symbol-function symbol) [function] Returns the current global function definition named by symbol. (symbol-macrolet ({(var expansion)}*) [special-form] {declaration}* {form}*) For defining symbol macros. During the processing of {form}*, each occurence of a var is replaced by the associated expansion. (symbol-value symbol) [function] Returns the current value of the dynamic variable named by symbol. (tagbody {tag | form}*) [special-form] Each element of the body is processed from left to right. A tag is ignored; a form is evaluated and its results discarded. If the end of the body is reached the tagbody returns nil. The scope of the tag is lexical and the extent is dynamic. It is permissible for a go to jump to a tagbody that is not the innermost tagbody construct containing that go. (throw tag result-form) [special-form] The throw tag is evaluated. The results of evaluating result-form are saved. If the throw tag matches the tag of a catch then control is transferred to the matching catch construct whose value(s) are those of result-form (typecase keyform {(type {form}*)}*) [macro] (typecase keyform (type-1 consequent-1-1 consequent-1-2 ...) (type-2 consequent-2-1 consequent-2-2 ...) (...) Structurally typecase is similar to cond and case. It evaluates keyform to produce a key-object. typecase selects the clause whose type matches key-object. The consequents of that clause are evaluated and the value of the last form returned. typecase returns nil if no clause is satisfied. It may contain an explicit t or Otherwise default clause. (unless test {form}*) [macro] unless first evaluates test. If the result is not nil the {form}* is not evaluated, and nil is returned. Otherwise the forms are evaluated sequentially and the value of the last one is returned. (unwind-protect form {form}*) [special-form] Guarantees to execute {form}* after evaluating form, even if form terminates abnormally (by a throw, for example). Returns whatever results from form and discards all the results from {form}*. (values &rest args) [function] All of the args are returned in order as values. The expression (values) is the standard idiom for returning zero values from a function. (values-list list) [function] All of the elements of list are returned as multiple values. (when test {form}*) [macro] when first evaluates test. If the result is nil then {form}* is not evaluated and nil is returned. Otherwise the {form}* is evaluated sequentially and the value of the last one is returned. --- C.all/lisp/ref/control --- Copyright University of Sussex 1993. All rights reserved.