;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*-

=Node: What is a Function?

=Text:
3WHAT IS A FUNCTION?*

     Functions are the basic building blocks of Lisp programs.  This chapter describes the functions
in Zetalisp that are used to manipulate functions.  It also explains how to manipulate special forms
and macros.

     This chapter contains internal details intended for those writing programs to manipulate programs
as well as material suitable for the beginner.  Feel free to skip sections that look complicated or
uninteresting when reading this for the first time.

     There are many different kinds of functions in Zetalisp.  Here are the printed representations of
examples of some of them:  

        3foo*
        3(lambda (x) (car (last x)))*
        3(named-lambda foo (x) (car (last (x))))*
        3(subst (x) (car (last x)))*
        3#<dtp-fef-pointer append 1424771>*
        3#<dtp-u-entry last 270>*
        3#<dtp-closure 1477464>*

     We will examine these and other types of functions in detail later in this chapter.  There is one
thing they all have in common:  a function is a Lisp object that can be applied to arguments.  All of
the above objects may be applied to some arguments and will return a value.  Functions are Lisp
objects and so can be manipulated in all the usual ways; you can pass them as arguments, return
them as values, and make other Lisp objects refer to them.

=Node: Function Specs

=Text:
3FUNCTION SPECS*

     The name of a function does not have to be a symbol.  Various kinds of lists describe other
places where a function can be found.  A Lisp object that describes a place to find a function is
called a 1function spec*.  (`Spec' is short for `specification'.) Here are the printed representations of
some typical function specs:  

        3foo*
        3(:property foo bar)*
        3(:method tv:graphics-mixin :draw-line)*
        3(:internal foo 1)*
        3(:within foo bar)*
        3(:location #<dtp-locative 7435216>)*

     Function specs have two purposes:  they specify a place to 1remember* a function, and they
serve to 1name* functions.  The most common kind of function spec is a symbol, which specifies that
the function cell of the symbol is the place to remember the function.  We will see all the different
types of function spec, and what they mean, shortly.  Function specs are not the same thing as
functions.  You cannot, in general, apply a function spec to arguments.  The time to use a function
spec is when you want to 1do* something to the function, such as define it, look at its definition, or
compile it.

     Some kinds of functions remember their own names, and some don't.  The ``name'' remembered
by a function can be any kind of function spec, although it is usually a symbol.  In the examples of
functions in the previous section, the one starting with the symbol 2named-lambda*, the one whose
printed representation included 2dtp-fef-pointer*, and the 2dtp-u-entry* remembered names (the function
specs 2foo*, 2append*, and 2last* respectively).  The others didn't remember their names.

     To 1define a function spec* means to make that function spec remember a given function.
Programs do this by calling 2fdefine*; you give 2fdefine* a function spec and a function, and 2fdefine*
remembers the function in the place specified by the function spec.  The function associated with a
function spec is called the 1definition* of the function spec.  A single function can be the definition of
more than one function spec at the same time, or of no function specs.

     The definition of a function spec can be obtained with 2fdefinition*.  2(function 1function-spec*)*
does so too, but here 1function-spec* is not evaluated.  For example, 2(function foo)* evaluates to the
function definition of 2foo*.  2fdefinition* is used by programs whose purpose is to examine function
definitions, whereas 2function* is used in this way by programs of all sorts to obtain a specific
definition and use it.  See 4(EVAL-4)Some Functions and Special Forms*.

     To 1define a function* means to create a new function and define a given function spec as that
new function.  This is what the 2defun* special form does.  Several other special forms, such as
2defmethod* (4(FLAVOR-2)Flavor Functions*) and 2defselect*
(4(FUNCTIONS-2)Function-Defining Special Forms*), do this too.

     These special forms that define functions usually take a function spec, create a function whose
name is that function spec, and then define that function spec to be the newly-created function.
Most function definitions are done this way, and so usually if you go to a function spec and see
what function is there, the function's name is the same as the function spec.  However, if you define
a function named 2foo* with 2defun*, and then define the symbol 2bar* to be this same function, the name
of the function is unaffected; both 2foo* and 2bar* are defined to be the same function, and the name
of that function is 2foo*, not 2bar*.

     A function spec's definition in general consists of a 1basic definition* surrounded by
1encapsulations*.  Both the basic definition and the encapsulations are functions, but of recognizably
different kinds.  What 2defun* creates is a basic definition, and usually that is all there is.
Encapsulations are made by function-altering functions such as 2trace*, 2breakon* and 2advise*.  When
the function is called, the entire definition, which includes the tracing and advice, is used.  If the
function is redefined with 2defun*, only the basic definition is changed; the encapsulations are left in
place.  See the section on encapsulations, 4(FUNCTIONS-2)Encapsulations*.

     A function spec is a Lisp object of one of the following types:  

1a symbol*    The function is remembered in the function cell of the symbol.  See
              4(SYMBOLS-1)The Function Cell* for an explanation of function cells and the primitive
              functions to manipulate them.  

2(:property 1symbol* 1property*)*  
              The function is remembered on the property list of the symbol; doing 2(get 1symbol**
              1property2)** returns the function.  Storing functions on property lists is a frequently-used
              technique for dispatching (that is, deciding at run-time which function to call, on the
              basis of input data).

2(:method 1flavor-name* 1operation*)*  

2(:method 1flavor-name* 1method-type* 1operation*)
(:method 1flavor-name* 1method-type* 1operation* 1suboperation*)*The function is remembered inside
              internal data structures of the flavor system and is called automatically as part of
              handling the operation 1operation* on instances of 1flavor-name*.  See the chapter on
              flavors (4(FLAVOR-0)Objects, Message Passing, and Flavors*) for details.

2(:handler 1flavor-name* 1operation*)*  
              This is a name for the function actually called when an 1operation* message is sent to an
              instance of the flavor 1flavor-name*.  The difference between 2:handler* and 2:method* is that
              the handler may be a method inherited from some other flavor or a 1combined method*
              automatically written by the flavor system.  Methods are what you define in source files;
              handlers are not.  Note that redefining or encapsulating a handler affects only the named
              flavor, not any other flavors built out of it.  Thus 2:handler* function specs are often used
              with 2trace* (see 4(DEBUGGING-5)Tracing Function Execution*), 2breakon* 
              (4(DEBUGGING-5)Breakon*), and 2advise* (4(DEBUGGING-5)Advising a Function*).

2(:select-method 1function-spec* 1operation*)*  
              This function spec assumes that the definition of 1function-spec* is a select-method
              object (see 4(FUNCTIONS-1)Other Kinds of Functions*) containing an alist of operation 
              names and functions to handle them, and refers to one particular element of that alist:  the 
              one for operation 1operation*.

              The function is remembered in that alist element and is called when 1function-spec*'s
              definition is called with first argument 1operation*.

              2:select-method* function specs are most often used implicitly through 2defselect*.  One of
              the things done by 

                      3(defselect foo*
                      3  (:win (x) (cons 'win x))*
                      3  ...)*

              is to define the function spec 2(:select-method foo :win)*.

              2:select-method* function specs are explicitly given function definitions when you use
              2defselect-incremental* instead of 2defselect*, as in 

                      3(defselect-incremental foo)*
                      3(defun (:select-method foo :win) (ignore x)*
                      3  (cons 'win x))

2(:lambda-macro 1name*)**  
              This is a name for the function that expands the lambda macro 1name*.

2(:location 1pointer*)*  
              The function is stored in the cdr of 1pointer*, which may be a locative or a list.  This is
              for pointing at an arbitrary place that there is no other way to describe.  This form of
              function spec isn't useful in 2defun* (and related special forms) because the reader has no
              printed representation for locative pointers and always creates new lists; these function
              specs are intended for programs that manipulate functions (see
              4(FUNCTIONS-2)How Programs Manipulate Function Specs*).

2(:within 1within-function* 1function-to-affect*)*  
              This refers to the meaning of the symbol 1function-to-affect*, but only where it occurs in
              the text of the definition of 1within-function*.  If you define this function spec as
              anything but the symbol 1function-to-affect* itself, then that symbol is replaced
              throughout the definition of 1within-function* by a new symbol, which is then defined as
              you specify.  See the section on 2si:rename-within* encapsulations
              (4(FUNCTIONS-2)Rename-Within Encapsulations*) for more information.

              It is rarely useful to define a 2:within* function spec by hand, but often useful to trace or
              advise one.  For example, 

                      3(breakon '(:within myfunction eval))*

              allows you to break when 2eval* is called from 2myfunction*.  Simply doing 2(breakon 'eval)*
              will probably blow away your machine.

2(:internal 1function-spec* 1number*)*  
              Some Lisp functions contain internal functions, created by 2(function (lambda ...))* forms.
              These internal functions need names when compiled, but they do not have symbols as
              names; instead they are named by 2:internal* function-specs.  1function-spec* is the name
              of the containing function.  1number* is a sequence number; the first internal function the
              compiler comes across in a given function is numbered 0, the next 1, etc.  Internal
              functions are remembered inside the compiled function object of their containing function.

2(:internal 1function-spec* 1symbol*)*  
              If a Lisp function uses 2flet* to name an internal function, you can use the local name
              defined with 2flet* in the 2:internal* function spec instead of a number.  Here is an example
              of such a function:  

                      3(defun foo (a)*
                      3  (flet ((square (x) (* x x)))*
                      3    (+ a (square a))))*

              After compiling 2foo*, you could use the function spec 2(:internal foo square)* to refer to
              the internal function locally named 2square*.  You could also use 2(:internal foo 0)*.  If
              there are multiple 2flet*'s defining local functions with the same name, only the first can be
              referred to by name this way.  

     Here is an example defining a function whose name is not a symbol:  

        3(defun (:property foo bar-maker) (thing &optional kind)*
        3  (set-the 'bar thing (make-bar 'foo thing kind)))*

     This puts a function on 2foo*'s 2bar-maker* property.  Now you can say 

        3(funcall (get 'foo 'bar-maker) 'baz)*
or
        3(funcall #'(:property foo bar-maker) 'bax)*

     Unlike the other kinds of function spec, a symbol 1can* be used as a function.  If you apply a
symbol to arguments, the symbol's function definition is used instead.  If the definition of the first
symbol is another symbol, the definition of the second symbol is used, and so on, any number of
times.  But this is an exception; in general, you can't apply function specs to arguments.

     A keyword symbol that identifies function specs (i.e., that may appear in the car of a list which
is a function spec) is identified by a 2sys:function-spec-handler* property whose value is a function
that implements the various manipulations on function specs of that type.  The interface to this
function is internal and not documented in this manual.

     For compatibility with Maclisp, the function-defining special forms 2defun*, 2macro*, and 2defselect*
(and other defining forms built out of them, such as 2defmacro*) also accept a list 

        3(1symbol* 1property*)*

     as a function name.  This is translated into 

        3(:property 1symbol* 1property*)*

     1symbol* must not be one of the keyword symbols that identify a function spec, since that would
be ambiguous.

=Node: Simple Function Definitions

=Text:
3SIMPLE FUNCTION DEFINITIONS

defun*                                                                                       1Special Form*        
        The usual way of defining a function that is part of a program.  A 2defun* form looks like:  

                3(defun 1name* 1lambda-list**
                3  1body*...)*

        1name* is the function spec you wish to define as a function.  The 1lambda-list* is a list of the
        names to give to the arguments of the function.  Actually, it is a little more general than that;
        it can contain 1lambda-list keywords* such as 2&optional* and 2&rest*.  (These keywords are
        explained in 4(FUNCTIONS-0)Functions* and other keywords are explained in
        4(EVAL-3)Lambda-List Keywords*.) See 4(FUNCTIONS-2)Function-Defining Special Forms*
        for some additional syntactic features of 2defun*.

        2defun* creates a list that looks like 

                3(named-lambda 1name* 1lambda-list body*...)*

        and puts it in the function cell of 1name*.  1name* is now defined as a function and can be called
        by other forms.

        Examples:
                3(defun addone (x)*
                3  (1+ x))*

                3(defun foo (a &optional (b 5) c &rest e &aux j)*
                3  (setq j (+ (addone a) b))*
                3  (cond ((not (null c))*
                3         (cons j e))*
                3        (t j))) *

        2addone* is a function which expects a number as an argument, and returns a number one
        larger.  2foo* is a complicated function that takes one required argument, two optional
        arguments, and any number of additional arguments that are given to the function as a list
        named 2e*.

        A declaration (a list starting with 2declare*) can appear as the first element of the body.  It
        applies to the entire function definition; if it is a 2special* declaration, it applies to bindings made
        in the lambda list and to free references anywhere in the function.  For example, 

                3(defun foo (x)*
                3  (declare (special x))*
                3  (bar))             ;bar2 uses x free.**

        causes the binding of 2x* to be a dynamic binding, and 

                3(defun foo (&rest args)*
                3  (declare (arglist a b c))*
                3  (apply 'bar args))*

        causes 2(arglist 'foo)* to return 2(a b c)* rather than 2(&rest args)*, presumably because the
        former is more informative in the particular application.

        A documentation string can also appear at the beginning of the body; it may precede or follow
        a declaration.  This documentation string becomes part of the function's debugging info and
        can be obtained with the function 2documentation* (see 4(MISCELL-1)Documentation*).  The first
        line of the string should be a complete sentence that makes sense read by itself, since there
        are two editor commands to get at the documentation, one of which is ``brief'' and prints only
        the first line.  Example:  

                3(defun my-append (&rest lists)*
                3   "Like append but copies all the lists.*
                3This is like the Lisp function append, except that*
                3append copies all lists except the last, whereas*
                3this function copies all of its arguments*
                3including the last one."*
                3   ...)*

     A documentation string may not be the last element of the body; a string in that position is
interpreted as a form to evaluate and return and is not considered to be a documentation string.

     For more information on defining functions, and other ways of doing so, see
4(FUNCTIONS-2)Function-Defining Special Forms*.

=Node: User Operations on Functions

=Text:
3USER OPERATIONS ON FUNCTIONS*

     Here is a list of the various things a user (as opposed to a program) is likely to want to do to a
function.  In all cases, you specify a function spec to say where to find the function.

     To print out the definition of the function spec with indentation to make it legible, use 2grindef*
(see 4(READPRINT-3)Pretty-Printing Output Functions*).  This works only for interpreted functions.
If the definition is a compiled function, it can't be printed out as Lisp code, but its compiled code can
be printed by the 2disassemble* function (see 4(MISCELL-1)Poking Around in the Lisp World*).

     To find out about how to call the function, you can ask to see its documentation or its
argument names.  (The argument names are usually chosen to have mnemonic significance for the
caller).  Use 2arglist* (4(FUNCTIONS-2)How Programs Examine Functions*) to see the argument names
and 2documentation* (4(MISCELL-1)Documentation*) to see the documentation string.  There are also
editor commands for doing these things:  the 2Control-Shift-D* and 2Meta-Shift-D* commands are for
looking at a function's documentation, and 2Control-Shift-A* is for looking at an argument list.

     2Control-Shift-A* and 2Control-Shift-D* do not ask for the function name; they act on the function
that is called by the innermost expression which the cursor is inside.  Usually this is the function that
will be called by the form you are in the process of writing.  They are available in the rubout handler
as well.

     You can see the function's debugging info alist by means of the function 2debugging-info* (see
4(FUNCTIONS-2)How Programs Examine Functions*).

     When you are debugging, you can use 2trace* (see 4(DEBUGGING-5)Tracing Function Execution*) 
to obtain a printout or a break loop whenever the function is called.  You can use 2breakon* (see
4(DEBUGGING-5)Breakon*) to cause the error handler to be entered whenever the function is called; from
there, you can step through further function calls and returns.  You can customize the definition of
the function, either temporarily or permanently, using 2advise* (see 4(DEBUGGING-5)Advising a Function*).

=Node: Kinds of Functions

=Text:
3KINDS OF FUNCTIONS*

     There are many kinds of functions in Zetalisp.  This section briefly describes each kind of
function.  Note that a function is also a piece of data and can be passed as an argument, returned,
put in a list, and so forth.

     There are four kinds of functions, classified by how they work.

     First, there are 1interpreted* functions:  you define them with 2defun*, they are represented as list
structure, and they are interpreted by the Lisp evaluator.

     Secondly, there are 1compiled* functions:  they are defined by 2compile* or by loading a QFASL file,
they are represented by a special Lisp data type, and they are executed directly by the microcode.
Similar to compiled functions are microcode functions, which are written in microcode (either by hand
or by the micro-compiler) and executed directly by the hardware.

     Thirdly, there are various types of Lisp object that can be applied to arguments, but when they
are applied they dig up another function somewhere and apply it instead.  These include
select-methods, closures, instances, and entities.

     Finally, there are various types of Lisp object that, when called as functions, do something
special related to the specific data type.  These include arrays and stack-groups.

=Node: Interpreted Functions

=Text:
3INTERPRETED FUNCTIONS*

     An interpreted function is a piece of list structure that represents a program according to the
rules of the Lisp interpreter.  Unlike other kinds of functions, interpreted functions can be printed out
and read back in (they have a printed representation that the reader understands), can be
pretty-printed (see 4(READPRINT-3)Pretty-Printing Output Functions*), and can be examined with
the usual functions for list-structure manipulation.

     There are four kinds of interpreted functions:  2lambda*s, 2named-lambda*s, 2subst*s, and
2named-subst*s.  A 2lambda* function is the simplest kind.  It is a list that looks like this:  

        3(lambda 1lambda-list* 1form1* 1form2*...)*

     The symbol 2lambda* identifies this list as a 2lambda* function.  1lambda-list* is a description of what
arguments the function takes; see 4(FUNCTIONS-0)Functions* for details.  The 1forms* make up the body
of the function.  When the function is called, the argument variables are bound to the values of the
arguments as described by 1lambda-list*, and then the forms in the body are evaluated, one by one.
The values of the function are the values of its last form.

     A 2named-lambda* is like a 2lambda* but contains an extra element in which the system remembers
the function's name, documentation, and other information.  Having the function's name there allows
the error handler and other tools to give the user more information.  You would not normally write a
2named-lambda* yourself; 2named-lambda* exists so that 2defun* can use it.  A 2named-lambda* function
looks like this:  

        3(named-lambda 1name* 1lambda-list* 1body forms*...)*

     If the 1name* slot contains a symbol, it is the function's name.  Otherwise it is a list whose car is
the name and whose cdr is the function's debugging information alist.  (See 2debugging-info*,
4(FUNCTIONS-2)How Programs Examine Functions*.) Note that the name need not be a symbol; it
can be any function spec.  For example, 

        3(defun (foo bar) (x)*
        3  (car (reverse x)))*

     gives 2foo* a 2bar* property whose value is 

        3(named-lambda ((:property foo bar)) (x) (car (reverse x)))*

     A 2subst* is a function which is open-coded by the compiler.  A 2subst* is just like a 2lambda* as far
as the interpreter is concerned.  It is a list that looks like this:  

        3(subst 1lambda-list* 1form1* 1form2*...)*

     The difference between a 2subst* and a 2lambda* is the way they are handled by the compiler.  A
call to a normal function is compiled as a 1closed subroutine*; the compiler generates code to compute
the values of the arguments and then apply the function to those values.  A call to a 2subst* is
compiled as an 1open subroutine*; the compiler incorporates the body forms of the 2subst* into the
function being compiled, substituting the argument forms for references to the variables in the
2subst*'s 1lambda-list*.  2subst*'s are described more fully on 4(MACROS-1)Substitutable Functions*,
with the explanation of 2defsubst*.

     A 2named-subst* is the same as a 2subst* except that it has a name just as a 2named-lambda* does.
It looks like 

        3(named-subst 1name* 1lambda-list* 1form1* 1form2* ...)*

     where 1name* is interpreted the same way as in a 2named-lambda*.

=Node: Lambda Macros

=Text:
3LAMBDA MACROS*

     Lambda macros may appear in functions where 2lambda* would have previously appeared.  When
the compiler or interpreter detects a function whose car is a lambda macro, they expand the macro in
much the same way that ordinary Lisp macros are expanded--the lambda macro is called with the
function as its argument and is expected to return another function as its value.  The definition of a
lambda macro (that is, the function which expands it) may be accessed with the (2:lambda-macro
1name**) function spec.

     The value returned by the lambda macro expander function may be any valid function.  Usually it
is a list starting with 2lambda*, 2subst*, 2named-lambda* or 2named-subst*, but it could also be another use
of a lambda macro, or even a compiled function.

3lambda-macro* 1name* 1lambda-list* &body 1body*                                                1Macro*        
        By analogy with 2macro*, defines a lambda macro to be called 1name*.  1lambda-list* should consist
        of one variable, which is bound to the function that caused the lambda macro to be called.
        The lambda macro must return a function.  For example:  

                3(lambda-macro ilisp (x)*
                3  `(lambda (&optional ,@(second x) &rest ignore) . ,(cddr x)))*

        defines a lambda macro called 2ilisp* which can be used to define functions that accept
        arguments like a standard Interlisp function:  all arguments are optional and extra arguments
        are ignored.  A typical use would be:

                3(fun-with-functional-arg #'(ilisp (x y z) (list x y z)))*

        This passes to 2fun-with-functional-arg* a function which will ignore extra arguments beyond
        the third, and will default 2x*, 2y* and 2z* to 2nil*.  

3deflambda-macro*                                                                               1Macro*        
        2deflambda-macro* is like 2defmacro*, but defines a lambda macro instead of a normal macro.
        Here is how 2ilisp* could be defined using 2deflambda-macro*:  

                3(deflambda-macro ilisp (argument-list &body body)*
                3  `(lambda (&optional ,@argument-list &rest ignore) . ,body))

deffunction* 1function-spec* 1lambda-macro-name* 1lambda-list* &body 1body*                1Macro*        
        Defines a function with a definition that uses an arbitrary lambda macro instead of 2lambda*.  It
        takes arguments like 2defun*, expect that the argument immediatly following the function
        specifier is the name of the lambda macro to be used.  2deffunction* expands the lambda macro
        immediatly, so the lambda macro must have been previously defined.

        Example:  

                3(deffunction some-interlisp-like-function ilisp (x y z)*
                3  (list x y z))*

        would define a function called 2some-interlisp-like-function* with the definition 2(ilisp (x y z) (list*
        2x y z))*.

        2(defun foo ...)* could be considered an abbreviation for 2(deffunction foo lambda ...)* 

=Node: Compiled Functions

=Text:
3COMPILED FUNCTIONS*

     There are two kinds of compiled functions:  1macrocoded* functions and 1microcoded* functions.
The Lisp compiler converts 2lambda* and 2named-lambda* functions into macrocoded functions.  A
macrocoded function's printed representation looks like:  

        3#<dtp-fef-pointer append 1424771>*

     This type of Lisp object is also called a `Function Entry Frame', or `FEF' for short.  Like `car' and
`cdr', the name is historical in origin and doesn't really mean anything.  The object contains Lisp
Machine machine code that does the computation expressed by the function; it also contains a
description of the arguments accepted, any constants required, the name, documentation, and other
things.  Unlike Maclisp ``subr-objects'', macrocoded functions are full-fledged objects and can be
passed as arguments, stored in data structure, and applied to arguments.

     The printed representation of a microcoded function looks like:  

        3#<dtp-u-entry last 270>*

     Most microcompiled functions are basic Lisp primitives or subprimitives written in Lisp Machine
microcode.  You can also convert your own macrocode functions into microcode functions in some
circumstances, using the micro-compiler.

=Node: Other Kinds of functions

=Text:
3OTHER KINDS OF FUNCTIONS*

     A closure is a kind of function that contains another function and a set of special variable
bindings.  When the closure is applied, it puts the bindings into effect and then applies the other
function.  When that returns, the closure bindings are removed.  Closures are made with the function
2closure*.  See 4(CLOSURES-0)Closures* for more information.  Entities are slightly different from closures;
see 4(CLOSURES-1)Entities*.

     A select-method (internal type code 2dtp-select-method*) contains an alist of symbols and
functions.  When one is called, the first argument is looked up in the alist to find the particular
function to be called.  This function is applied to the rest of the arguments.  The alist may have a
list of symbols in place of a symbol, in which case the associated function is called if the first
argument is any of the symbols on the list.  If 2cdr* of 2last* of the alist is non-2nil*, it is a 1default
handler* function, which gets called if the message key is not found in the alist.  Select-methods can
be created with the 2defselect* special form (see 4(FUNCTIONS-2)Function-Defining Special Forms*).
If the select-method is the definition of a function-spec, the individual functions in the alist can be
referred to or defined using 2:select-method* function specs (see 4(FUNCTIONS-1)Function Specs*).

     An instance is a message-receiving object that has both a state and a table of
message-handling functions (called 1methods*).  Refer to the chapter on flavors
(4(FLAVOR-0)Objects, Message Passing, and Flavors*) for further information.

     An array can be used as a function.  The arguments to the array are the indices and the value
is the contents of the element of the array.  This is for Maclisp compatibility and is not
recommended usage.  Use 2aref* (4(ARRAYS-2)Accessing Array Elements*) instead.

     A stack group can be called as a function.  This is one way to pass control to another stack
group.  See 4(STACKGROUPS-0)Stack Groups*.

=Node: Special Forms and Functions

=Text:
3SPECIAL FORMS AND FUNCTIONS*

     The special forms of Zetalisp, such as 2quote*, 2let* and 2cond*, are actually implemented with an
unusual sort of function.

     First, let's restate the outline of how the evaluator works.  When the evaluator is given a list
whose first element is a symbol, the form may be a function form, a special form, or a macro form
(see 4(EVAL-0)Evaluation*).  If the definition of the symbol is a function, then the function is just
applied to the result of evaluating the rest of the subforms.  If the definition is a cons whose car is
2macro*, then it is a macro form; these are explained in 4(MACROS-0)Macros*.  What about special
forms?

     A special form is implemented by a function that is flagged to tell the evaluator to refrain from
evaluating some or all of the arguments to the function.  Such functions make use of the lambda-list
keyword 2&quote*.

     The evaluator, on seeing the 2&quote* in the lambda list of an interpreted function (or something
equivalent in a compiled function) skips the evaluation of the arguments to which the 2&quote* applies.
Aside from that, it calls the function normally.

     For example, 2quote* could be defined as 

        3(defun quote (&quote arg) arg)*

     Evaluation of 2(quote x)* would see the 2&quote* in the definition, implying that the argument 1arg*
should not be evaluated.  Therefore, the argument passed to the definition of 2quote* would be the
symbol 2x* rather than the value of 2x*.  From then on, the definition of 2quote* would execute in the
normal fashion, so 2x* would be the value of 2arg* and 2x* would be returned.

     2&quote* applies to all the following arguments, but it can be cancelled with 2&eval*.  A simple 2setq*
that accepted only one variable and one value could be defined as follows:  

        3(defun setq (&quote variable &eval value)*
        3  (set variable value))*

     The actual definition of 2setq* is more complicated and uses a lambda list 2(&quote &rest
variables-and-values)*.  Then it must go through the rest-argument, evaluating every other element.

     The definitions of special forms are designed with the assumption that they will be called by
2eval*.  It does not usually make much sense to call one with 2funcall* or 2apply*.  2funcall* and 2apply* do
not evaluate any arguments; they receive 1values* of arguments, rather than expressions for them, and
pass these values directly to the function to be called.  There is no evaluation for 2funcall* or 2apply*
to refrain from performing.  Most special forms explicitly call 2eval* on some of their arguments, or
parts of them, and if called with 2apply* or 2funcall* they will 1still* do so.  This behavior is rarely useful,
so calling special forms with 2apply* or 2funcall* should be avoided.  Encapsulations can do this
successfully, because they can arrange that quoted arguments are quoted also on entry to the
encapsulation.

     It is possible to define your own special form using 2&quote*.  Macros can also be used to
accomplish the same thing.  It is preferable to implement language extensions as macros rather than
special forms, because macros directly define a Lisp-to-Lisp translation and therefore can be
understood by both the interpreter and the compiler.  Special forms, on the other hand, only extend
the interpreter.  The compiler has to be modified in an 1ad hoc* way to understand each new special
form so that code using it can be compiled.  For example, it would not work for a compiled function
to call the interpreted definition of 2setq*; the 2set* in that definition would not be able to act on local
variables of the compiled function.

     Since all real programs are eventually compiled, writing your own special functions is strongly
discouraged.  The purpose of 2&quote* is to be used in the system's own standard special forms.

     New Lisp constructs in the system are also implemented as macros most of the time; macros are
less work for us, too.