;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Introduction to Functions =Text: 3INTRODUCTION TO FUNCTIONS* In the description of evaluation on 4(EVAL-0)Evaluation*, we said that evaluation of a function form works by applying the function to the results of evaluating the argument subforms. What is a function, and what does it mean to apply it? In Zetalisp there are many kinds of functions, and applying them may do many different kinds of things. For full details, see 4(FUNCTIONS-0)Functions*. Here we explain the most basic kinds of functions and how they work. In particular, this section explains 1lambda lists* and all their important features. The simplest kind of user-defined function is the 1lambda-expression*, which is a list that looks like: 3(lambda 1lambda-list* 1body1* 1body2*...)* The first element of the lambda-expression is the symbol 2lambda*; the second element is a list called the 1lambda list*, and the rest of the elements are called the 1body*. The lambda list, in its simplest form, is just a list of variables. Assuming that this simple form is being used, here is what happens when a lambda expression is applied to some arguments. First, the number of arguments and the number of variables in the lambda list must be the same, or else an error is signaled. Each variable is bound to the corresponding argument value. Then the forms of the body are evaluated sequentially. After this, the bindings are all undone, and the value of the last form in the body is returned. This may sound something like the description of 2let*, above. The most important difference is that the lambda-expression is not a form at all; if you try to evaluate a lambda-expression, you get an error because 2lambda* is not a defined function. The lambda-expression is a 1function*, not a form. A 2let* form gets evaluated, and the values to which the variables are bound come from the evaluation of some subforms inside the 2let* form; a lambda-expression gets applied, and the values are the arguments to which it is applied. The variables in the lambda list are sometimes called 1parameters*, by analogy with other languages. Some other terminologies would refer to these as 1formal parameters*, and to arguments as 1actual parameters*. Lambda lists can have more complex structure than simply being a list of variables. There are additional features accessible by using certain keywords (which start with 2&*) and/or lists as elements of the lambda list. The principal weakness of simple lambda lists is that any function written with one must only take a certain, fixed number of arguments. As we know, many very useful functions, such as 2list*, 2append*, 2+*, and so on, accept a varying number of arguments. Maclisp solved this problem by the use of 1lexprs* and 1lsubrs*, which were somewhat inelegant since the parameters had to be referred to by numbers instead of names (e.g. 2(arg 3)*). (For compatibility reasons, Zetalisp supports 1lexpr*s, but they should not be used in new programs.) Simple lambda lists also require that arguments be matched with parameters by their position in the sequence. This makes calls hard to read when there are a great many arguments. Keyword parameters enable the use of other, more readable styles of call. In general, a function in Zetalisp has zero or more 1positional* parameters, followed if desired by a single 1rest* parameter, followed by zero or more 1keyword* parameters. The positional parameters may be 1required* or 1optional*, but all the optional parameters must follow all the required ones. The required/optional distinction does not apply to the rest parameter; all keyword parameters are optional. The caller must provide enough arguments so that each of the required parameters gets bound, but he may provide extra arguments for some of the optional parameters. Also, if there is a rest parameter, he can provide as many extra arguments as he wants, and the rest parameter is bound to a list of all these extras. Optional parameters may have a 1default-form*, which is a form to be evaluated to produce the default value for the parameter if no argument is supplied. Positional parameters are matched with arguments by the position of the arguments in the argument list. Keyword parameters are matched with their arguments by matching the keyword name; the arguments need not appear in the same order as the parameters. If an optional positional argument is omitted, then no further arguments can be present. Keyword parameters allow the caller to decide independently for each one whether to specify it. Here is the exact algorithm used to match up the arguments with the parameters: 2Required positional parameters:* The first required positional parameter is bound to the first argument. 2apply* continues to bind successive required positional parameters to the successive arguments. If, during this process, there are no arguments left but there are still some required parameters which have not been bound yet, it is an error (``too few arguments''). 2Optional positional parameters:* After all required parameters are handled, 2apply* continues with the optional positional parameters, if any. It binds each successive parameter to the next argument. If, during this process, there are no arguments left, each remaining optional parameter's default-form is evaluated, and the parameter is bound to it. This is done one parameter at a time; that is, first one default-form is evaluated, and then the parameter is bound to it, then the next default-form is evaluated, and so on. This allows the default for an argument to depend on the previous argument. 2After the positional parameters:* Now, if there are no remaining parameters (rest or keyword), and there are no remaining arguments, we are finished. If there are no more parameters but there are still some arguments remaining, an error is signaled (``too many arguments''). If parameters remain, all the remaining arguments are used for 1both* the rest parameter, if any, and the keyword parameters. 2Rest parameter:* If there is a rest parameter, it is bound to a list of all the remaining arguments. If there are no remaining arguments, it is bound to 2nil*. 2Keyword parameters:* If there are keyword parameters, the same remaining arguments are used to bind them, as follows. The arguments for the keyword parameters are treated as a list of alternating keyword symbols and associated values. Each symbol is matched with 2eq* against the allowed parameter keywords, which have by default the same names as the parameters but in the 2keyword* package. (You can specify the keyword symbol explicitly in the lambda list if you must; see below.) Often the symbol arguments are constants in the program, and it is convenient for this usage that keywords all evaluate to themselves, but it is permissible for them to be computed by expressions. If any keyword parameter has not received a value when all the arguments have been processed, the default-form for the parameter is evaluated and the parameter is bound to its value. All keyword parameters are optional. There may be a keyword symbol among the arguments which does not match any keyword parameter name. By default this is an error, but the lambda list can specify that there should be no error using 2&allow-other-keys*. Also, if one of the keyword symbols among the arguments is 2:allow-other-keys* and the value that follows it is non-2nil* then there is no error. When there is no error, for either reason, the non-matching symbols and their associated values are simply ignored. The function can access these symbols and values through the rest parameter, if there is one. It is common for a function to check only for certain keywords, and pass its rest parameter to another function using 2apply*; that function will check for the keywords that concern it. The way you express which parameters are required, optional, rest and keyword is by means of specially recognized symbols, which are called 2&-1keywords**, in the lambda list. All such symbols' print names begin with the character `2&*'. A list of all such symbols is the value of the symbol 2lambda-list-keywords*. The keywords used here are 2&key*, 2&optional* and 2&rest*. The way they are used is best explained by means of examples; the following are typical lambda lists, followed by descriptions of which parameters are positional, rest or keyword; and required or optional. 3(a b c)* 2a*, 2b*, and 2c* are all required and positional. The function must be passed three arguments. 3(a b &optional c)* 2a* and 2b* are required, 2c* is optional. All three are positional. The function may be passed either two or three arguments. 3(&optional a b c)* 2a*, 2b*, and 2c* are all optional and positional. The function may be passed zero, one, two or three arguments. 3(&rest a)* 2a* is a rest parameter. The function may be passed any number of arguments. 3(a b &optional c d &rest e)* 2a* and 2b* are required positional, 2c* and 2d* are optional positional, and 2e* is rest. The function may be passed two or more arguments. 3(&key a b)* 2a* and 2b* are both keyword parameters. A typical call would look like 3(foo :b 69 :a '(some elements))* or 3(foo :a '(some elements) :b 69)* or 3(foo :a '(some elements))* This illustrates that the parameters can be matched in either order, or omitted. If a keyword is specified twice, the first value is used. 3(x &optional y &rest z &key a b)* 2x* is required positional, 2y* is optional positional, 2z* is rest, and 2a* and 2b* are keyword. One or more arguments are allowed. One or two arguments specify only the positional parameters. Arguments beyond the second specify both the rest parameter and the keyword parameters, so that 3(foo 1 2 :b '(a list))* specifies 21* for 2x*, 22* for 2y*, 2(:b (a list))* for 2z*, and 2(a list)* for 2b*. It does not specify 2a*. 3(&rest z &key a b c &allow-other-keys)* 2z* is rest, and 2a*, 2b* and 2c* are keyword parameters. 2&allow-other-keys* says that absolutely any keyword symbols may appear among the arguments; these symbols and the values that follow them have no effect on the keyword parameters, but do become part of the value of 2z*. 3(&rest z &key &allow-other-keys)* This is equivalent to 2(&rest z)*. So, for that matter, is the previous example, if the function does not use the values of 2a*, 2b* and 2c*. In all of the cases above, the 1default-form* for each optional parameter is 2nil*. To specify your own default forms, instead of putting a symbol as the element of a lambda list, put in a list whose first element is the symbol (the parameter itself) and whose second element is the default-form. Only optional parameters may have default forms; required parameters are never defaulted, and rest parameters always default to 2nil*. For example: 3(a &optional (b 3))* The default-form for 2b* is 23*. 2a* is a required parameter, and so it doesn't have a default form. 3(&optional (a 'foo) &rest d &key b (c (symeval a)))* 2a*'s default-form is 2'foo*, 2b*'s is 2nil*, and 2c*'s is 2(symeval a)*. Note that if the function were called on no arguments, 2a* would be bound to the symbol 2foo*, and 2c* would be bound to the value of the symbol 2foo*; this illustrates the fact that each variable is bound immediately after its default-form is evaluated, and so later default-forms may take advantage of earlier parameters in the lambda list. 2b* and 2d* would be bound to 2nil*. Occasionally it is important to know whether a certain optional parameter was defaulted or not. Just by looking at the value one cannot distinguish between omitting it and passing the default value explicitly as an argument. The way to tell for sure is to put a third element into the list: the third element should be a variable (a symbol), and that variable is bound to 2nil* if the parameter was not passed by the caller (and so was defaulted), or 2t* if the parameter was passed. The new variable is called a ``supplied-p'' variable; it is bound to 2t* if the parameter is supplied. For example: 3(a &optional (b 3 c))* The default-form for 2b* is 23*, and the supplied-p variable for 2b* is 2c*. If the function is called with one argument, 2b* is bound to 23* and 2c* is bound to 2nil*. If the function is called with two arguments, 2b* is bound to the value that was passed by the caller (which might be 23*), and 2c* is bound to 2t*. It is possible to specify a keyword parameter's symbol independently of its parameter name. To do this, use 1two* nested lists to specify the parameter. The outer list is the one which can contain the default-form and supplied-p variable, if the parameter is optional. The first element of this list, instead of a symbol, is again a list, whose elements are the keyword symbol and the parameter variable name. For example: 3(&key ((:a a)) ((:b b) t))* This is equivalent to 2(&key a (b t))*. 3(&key ((:base base-value)))* This defines an argument which callers specify with the keyword 2:base*, but which within the function is referred to as the variable 2base-value* so as to avoid binding the value of 2base*, which is a synonym for 2*print-base** and controls how numbers are printed. It is also possible to include, in the lambda list, some other symbols, which are bound to the values of their default-forms upon entry to the function. These are 1not* parameters, and they are never bound to arguments; they just get bound, as if they appeared in a 2let** form. (Whether you use aux-variables or bind the variables with 2let** is a stylistic decision.) To include such symbols, put them after any parameters, preceeded by the 2&*-keyword 2&aux*. Examples: 3(a &optional b &rest c &aux d (e 5) (f (cons a e)))* 2d*, 2e*, and 2f* are bound, when the function is called, to 2nil*, 25*, and a cons of the first argument and 5. You could, equivalently, use 2(a &optional b &rest c)* as the lamda list and write 2(let* (d* 2(e 5) (f (cons a e))) ...)* around the body of the function. It is important to realize that the list of arguments to which a rest-parameter is bound is set up in whatever way is most efficiently implemented, rather than in the way that is most convenient for the function receiving the arguments. It is not guaranteed to be a ``real'' list. Sometimes the rest-args list is a stack list (see 4(MANLISTSTR-2)Stack Lists*) stored in the function-calling stack, and loses its validity when the function returns. If a rest-argument is to be returned or made part of permanent list-structure, it must first be copied (see 2copylist*, 4(MANLISTSTR-1)Lists*), as you must always assume that it is one of these special lists. The system does not detect the error of omitting to copy a rest-argument; you will simply find that you have a value which seems to change behind your back. At other times the rest-args list may be an argument that was given to 2apply*; therefore it is not safe to 2rplaca* this list as you may modify permanent data structure. An attempt to 2rplacd* a rest-args list is unsafe in this case, while in the first case it would cause an error, since lists in the stack are impossible to 2rplacd*. 3lambda-parameters-limit* 1Constant* Has as its value the limit on the number of parameters that a lambda list may have. The implementation limit on the number of parameters allowed is at least this many. There is no promise that this many is forbidden, but it is a promise that any number less than this many is permitted. =Node: Lambda-list Keywords =Text: 3LAMBDA-LIST KEYWORDS* This section documents all the keywords that may appear in the lambda list or argument list (see 4(FUNCTIONS-0)Functions*) of a function, a macro, or a special form. Some of them are allowed everywhere, while others are only allowed in one of these contexts; those are so indicated. You need only know about 2&optional*, 2&key*, and 2&rest* in order to understand the documentation of system functions in this manual. 3lambda-list-keywords* 1Constant* The value of this variable is a list of all of the allowed `2&*' keywords. A list of them follows. 2&optional* Separates the required arguments of a function from the optional arguments. See 4(FUNCTIONS-0)Functions*. 2&rest* Separates the required and optional arguments of a function from the rest argument. There may be only one rest argument. See 4(FUNCTIONS-0)Functions* for full information about rest arguments. 2&key* Separates the positional arguments and rest argument of a function from the keyword arguments. See 4(FUNCTIONS-0)Functions*. 2&allow-other-keys* In a function that accepts keyword arguments, says that keywords that are not recognized are allowed. They and the corresponding values are ignored, as far as keyword arguments are concerned, but they do become part of the rest argument, if there is one. 2&aux* Separates the arguments of a function from the auxiliary variables. Following 2&aux* you can put entries of the form 3(1variable* 1initial-value-form*)* or just 1variable* if you want it initialized to 2nil* or don't care what the initial value is. 2&special* Declares the following arguments and/or auxiliary variables to be special within the scope of this function. 2&local* Turns off a preceding 2&special* for the variables that follow. 2"e* Declares that the following arguments are not to be evaluated. This is how you create a special function. See the caveats about special forms on 4(FUNCTIONS-1)Special Forms and Functions*. 2&eval* Turns off a preceding 2"e* for the arguments which follow. 2&list-of* This is for macros defined by 2defmacro* only. Refer to 4(MACROS-1)Defmacro*. 2&body* This is for macros defined by 2defmacro* only. It is similar to 2&rest*, but declares to 2grindef* and the code-formatting module of the editor that the body forms of a special form follow and should be indented accordingly. Refer to 4(MACROS-1)Defmacro*. 2&whole* This is for macros defined by 2defmacro* only. It means that the following argument is bound to the entire macro call form being expanded. Refer to 4(MACROS-1)Defmacro*. 2&environment* This is for macros defined by 2defmacro* only. It means that the following argument is bound to an environment structure which records the local 2macrolet* macro definitions in effect for subforms of the macro call form. Refer to 4(MACROS-1)Defmacro*. =Node: Local Functions =Text: 3LOCAL FUNCTIONS* The constructs 2flet* and 2labels* permit you to define a function name in a lexical context only. If the same name has a global function definition, it is shadowed temporarily. Function definitions established by 2flet* (or 2labels*) are to global definitions made with 2defun* as lexical variable bindings made with 2let* are to global bindings made with 2defvar*. They always have lexical scope. 3flet* 1local-functions* 1body...* 1Special Form* Executes 1body* with local function definitions in effect according to 1local-functions*. 1local-functions* should be a list of elements which look like 3(1name* 1lambda-list* 1function-body*...)* just like the cdr of a 2defun* form. The meaning of this element of 1local-functions* is to define 1name* locally with the indicated definition. Within the lexical scope of 1body*, using 1name* as a function name accesses the local definition. Example: 3(flet ((triple (x) (* x 3)))* 3 (print (triple -1))* 3 (mapcar (function triple) '(1 2 1.2)))* prints the number -3 and returns a list 2(3 6 3.6)*. Each local function is closed in the environment outside the 2flet*. As a result, the local functions cannot call each other. 3(flet ((foo (x) (bar x t))* 3 (bar (y z) (list y z)))* 3 (foo t))* calls the local definition of 2foo*, which calls the 1global* definition of 2bar*, because the body of 2foo* is not within the scope of the local definition of 2bar*. Functions defined with 2flet* inside of a compiled function can be referred to by name in a function spec of the form 2(:internal 1outer-function-name* 1flet-name*)*. See 4(FUNCTIONS-1)Function Specs*. 3labels* 1local-functions* 1body...* 1Special Form* Is like 1flet* except that the local functions can call each other. They are closed in the environment inside the 2labels*, so all the local function names are accessible inside the bodies of the local functions. 2labels* is one of the most ancient Lisp constructs, but was typically not implemented in second generation Lisp systems in which no efficient form of closure existed. 3(labels ((walk (x)* 3 (typecase x* 3 (cons (walk (car x)) (walk (cdr x)))* 3 (t (if (eq x 'haha) (print 'found-it))))))* 3 (walk foo))* allows 2walk* to call itself recursively because 2walk*'s body is inside the scope of the definition of 2walk*. See also 2macrolet*, an analogous construct for defining macros locally (4(MACROS-1)Local Macro Definitions*).