Initial revision

1 files changed, 695 insertions, 0 deletions

diff --git a/lispref/eval.texi b/lispref/eval.texi
new file mode 100644
index 00000000000..c9b851f6b54
--- /dev/null
+++ b/lispref/eval.texi
@@ -0,0 +1,695 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/eval
+@node Evaluation, Control Structures, Symbols, Top
+@chapter Evaluation
+@cindex evaluation
+@cindex  interpreter
+@cindex interpreter
+@cindex value of expression
+
+  The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
+@dfn{Lisp interpreter}---a program that receives a Lisp object as input
+and computes its @dfn{value as an expression}.  How it does this depends
+on the data type of the object, according to rules described in this
+chapter.  The interpreter runs automatically to evaluate portions of
+your program, but can also be called explicitly via the Lisp primitive
+function @code{eval}.
+
+@ifinfo
+@menu
+* Intro Eval::  Evaluation in the scheme of things.
+* Eval::        How to invoke the Lisp interpreter explicitly.
+* Forms::       How various sorts of objects are evaluated.
+* Quoting::     Avoiding evaluation (to put constants in the program).
+@end menu
+
+@node Intro Eval
+@section Introduction to Evaluation
+
+  The Lisp interpreter, or evaluator, is the program which computes
+the value of an expression which is given to it.  When a function 
+written in Lisp is called, the evaluator computes the value of the
+function by evaluating the expressions in the function body.  Thus,
+running any Lisp program really means running the Lisp interpreter.
+
+  How the evaluator handles an object depends primarily on the data
+type of the object.
+@end ifinfo
+
+@cindex forms
+@cindex expression
+  A Lisp object which is intended for evaluation is called an
+@dfn{expression} or a @dfn{form}.  The fact that expressions are data
+objects and not merely text is one of the fundamental differences
+between Lisp-like languages and typical programming languages.  Any
+object can be evaluated, but in practice only numbers, symbols, lists
+and strings are evaluated very often.
+
+  It is very common to read a Lisp expression and then evaluate the
+expression, but reading and evaluation are separate activities, and
+either can be performed alone.  Reading per se does not evaluate
+anything; it converts the printed representation of a Lisp object to the
+object itself.  It is up to the caller of @code{read} whether this
+object is a form to be evaluated, or serves some entirely different
+purpose.  @xref{Input Functions}.
+
+  Do not confuse evaluation with command key interpretation.  The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses @code{call-interactively} to invoke the command.  The execution of
+the command itself involves evaluation if the command is written in
+Lisp, but that is not a part of command key interpretation itself.
+@xref{Command Loop}.
+
+@cindex recursive evaluation
+  Evaluation is a recursive process.  That is, evaluation of a form may
+call @code{eval} to evaluate parts of the form.  For example, evaluation
+of a function call first evaluates each argument of the function call,
+and then evaluates each form in the function body.  Consider evaluation
+of the form @code{(car x)}: the subform @code{x} must first be evaluated
+recursively, so that its value can be passed as an argument to the
+function @code{car}.
+
+@cindex environment
+  The evaluation of forms takes place in a context called the
+@dfn{environment}, which consists of the current values and bindings of
+all Lisp variables.@footnote{This definition of ``environment'' is
+specifically not intended to include all the data which can affect the
+result of a program.}  Whenever the form refers to a variable without
+creating a new binding for it, the value of the binding in the current
+environment is used.  @xref{Variables}.
+
+@cindex side effect
+  Evaluation of a form may create new environments for recursive
+evaluation by binding variables (@pxref{Local Variables}).  These
+environments are temporary and vanish by the time evaluation of the form
+is complete.  The form may also make changes that persist; these changes
+are called @dfn{side effects}.  An example of a form that produces side
+effects is @code{(setq foo 1)}.
+
+  Finally, evaluation of one particular function call, @code{byte-code},
+invokes the @dfn{byte-code interpreter} on its arguments.  Although the
+byte-code interpreter is not the same as the Lisp interpreter, it uses
+the same environment as the Lisp interpreter, and may on occasion invoke
+the Lisp interpreter.  (@xref{Byte Compilation}.)
+
+  The details of what evaluation means for each kind of form are
+described below (@pxref{Forms}).
+
+@node Eval
+@section Eval
+
+  Most often, forms are evaluated automatically, by virtue of their
+occurrence in a program being run.  On rare occasions, you may need to
+write code that evaluates a form that is computed at run time, such as
+after reading a form from text being edited or getting one from a
+property list.  On these occasions, use the @code{eval} function.
+
+    The functions and variables described in this section evaluate
+forms, specify limits to the evaluation process, or record recently
+returned values.  Loading a file also does evaluation
+(@pxref{Loading}).
+
+@defun eval form
+This is the basic function for performing evaluation.  It evaluates
+@var{form} in the current environment and returns the result.  How the
+evaluation proceeds depends on the type of the object (@pxref{Forms}).
+
+Since @code{eval} is a function, the argument expression that appears
+in a call to @code{eval} is evaluated twice: once as preparation before
+@code{eval} is called, and again by the @code{eval} function itself.
+Here is an example:
+
+@example
+@group
+(setq foo 'bar)
+     @result{} bar
+@end group
+@group
+(setq bar 'baz)
+     @result{} baz
+;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}}
+(eval foo)
+     @result{} baz
+@end group
+@end example
+
+The number of currently active calls to @code{eval} is limited to
+@code{max-lisp-eval-depth} (see below).
+@end defun
+
+@cindex evaluation of buffer contents
+@deffn Command eval-current-buffer &optional stream
+This function evaluates the forms in the current buffer.  It reads
+forms from the buffer and calls @code{eval} on them until the end of the
+buffer is reached, or until an error is signaled and not handled.
+
+If @var{stream} is supplied, the variable @code{standard-output} is
+bound to @var{stream} during the evaluation (@pxref{Output
+Functions}).
+
+@code{eval-current-buffer} always returns @code{nil}.
+@end deffn
+
+@deffn Command eval-region start end &optional stream
+This function evaluates the forms in the current buffer in the region
+defined by the positions @var{start} and @var{end}.  It reads forms from
+the region and calls @code{eval} on them until the end of the region is
+reached, or until an error is signaled and not handled.
+
+If @var{stream} is supplied, @code{standard-output} is bound to it
+for the duration of the command.
+
+@code{eval-region} always returns @code{nil}.
+@end deffn
+
+@defvar max-lisp-eval-depth
+This variable defines the maximum depth allowed in calls to @code{eval},
+@code{apply}, and @code{funcall} before an error is signaled (with error
+message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).  This counts
+calling the functions mentioned in Lisp expression, and recursive
+evaluation of function call arguments and function body forms.
+
+This limit, with the associated error when it is exceeded, is one way
+that Lisp avoids infinite recursion on an ill-defined function.
+@cindex Lisp nesting error
+
+The default value of this variable is 200.  If you set it to a value
+less than 100, Lisp will reset it to 100 if the given value is reached.
+
+@code{max-specpdl-size} provides another limit on nesting.
+@xref{Local Variables}.
+@end defvar
+
+@defvar values
+The value of this variable is a list of the values returned by all the
+expressions which were read from buffers (including the minibuffer),
+evaluated, and printed.  The elements are ordered most recent first.
+
+@example
+@group
+(setq x 1)
+     @result{} 1
+@end group
+@group
+(list 'A (1+ 2) auto-save-default)
+     @result{} (A 3 t)
+@end group
+@group
+values
+     @result{} ((A 3 t) 1 @dots{})
+@end group
+@end example
+
+This variable is useful for referring back to values of forms recently
+evaluated.  It is generally a bad idea to print the value of
+@code{values} itself, since this may be very long.  Instead, examine
+particular elements, like this:
+
+@example
+@group
+;; @r{Refer to the most recent evaluation result.}
+(nth 0 values)
+     @result{} (A 3 t)
+@end group
+@group
+;; @r{That put a new element on,}
+;;   @r{so all elements move back one.}
+(nth 1 values)
+     @result{} (A 3 t)
+@end group
+@group
+;; @r{This gets the element that was next-to-last}
+;;   @r{before this example.}
+(nth 3 values)
+     @result{} 1
+@end group
+@end example
+@end defvar
+
+@node Forms
+@section Kinds of Forms
+
+  A Lisp object that is intended to be evaluated is called a @dfn{form}.
+How Emacs evaluates a form depends on its data type.  Emacs has three
+different kinds of form that are evaluated differently: symbols, lists,
+and ``all other types''.  This section describes all three kinds,
+starting with ``all other types'' which are self-evaluating forms.
+
+@menu
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Indirection::    When a symbol appears as the car of a list,
+			      we find the real function via the symbol.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           ``Special forms'' are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+@end menu
+
+@node Self-Evaluating Forms
+@subsection Self-Evaluating Forms
+@cindex vector evaluation
+@cindex literal evaluation
+@cindex self-evaluating form
+
+  A @dfn{self-evaluating form} is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated.  Thus, the number 25 evaluates to
+25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
+Likewise, evaluation of a vector does not cause evaluation of the
+elements of the vector---it returns the same vector with its contents
+unchanged.
+
+@example
+@group
+'123               ; @r{An object, shown without evaluation.}
+     @result{} 123
+@end group
+@group
+123                ; @r{Evaluated as usual---result is the same.}
+     @result{} 123
+@end group
+@group
+(eval '123)        ; @r{Evaluated ``by hand''---result is the same.}
+     @result{} 123
+@end group
+@group
+(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
+     @result{} 123
+@end group
+@end example
+
+  It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually; however, it is
+possible to construct Lisp expressions containing these types by means
+of a Lisp program.  Here is an example:
+
+@example
+@group
+;; @r{Build an expression containing a buffer object.}
+(setq buffer (list 'print (current-buffer)))
+     @result{} (print #<buffer eval.texi>)
+@end group
+@group
+;; @r{Evaluate it.}
+(eval buffer)
+     @print{} #<buffer eval.texi>
+     @result{} #<buffer eval.texi>
+@end group
+@end example
+
+@node Symbol Forms
+@subsection Symbol Forms
+@cindex symbol evaluation
+
+  When a symbol is evaluated, it is treated as a variable.  The result
+is the variable's value, if it has one.  If it has none (if its value
+cell is void), an error is signaled.  For more information on the use of
+variables, see @ref{Variables}.
+
+  In the following example, we set the value of a symbol with
+@code{setq}.  Then we evaluate the symbol, and get back the value that
+@code{setq} stored.
+
+@example
+@group
+(setq a 123)
+     @result{} 123
+@end group
+@group
+(eval 'a)
+     @result{} 123
+@end group
+@group
+a
+     @result{} 123
+@end group
+@end example
+
+  The symbols @code{nil} and @code{t} are treated specially, so that the
+value of @code{nil} is always @code{nil}, and the value of @code{t} is
+always @code{t}.  Thus, these two symbols act like self-evaluating
+forms, even though @code{eval} treats them like any other symbol.
+
+@node Classifying Lists
+@subsection Classification of List Forms
+@cindex list form evaluation
+
+  A form that is a nonempty list is either a function call, a macro
+call, or a special form, according to its first element.  These three
+kinds of forms are evaluated in different ways, described below.  The
+remaining list elements constitute the @dfn{arguments} for the function,
+macro, or special form.
+
+  The first step in evaluating a nonempty list is to examine its first
+element.  This element alone determines what kind of form the list is
+and how the rest of the list is to be processed.  The first element is
+@emph{not} evaluated, as it would be in some Lisp dialects such as
+Scheme.
+
+@node Function Indirection
+@subsection Symbol Function Indirection
+@cindex symbol function indirection
+@cindex indirection
+@cindex void function
+
+  If the first element of the list is a symbol then evaluation examines
+the symbol's function cell, and uses its contents instead of the
+original symbol.  If the contents are another symbol, this process,
+called @dfn{symbol function indirection}, is repeated until it obtains a
+non-symbol.  @xref{Function Names}, for more information about using a
+symbol as a name for a function stored in the function cell of the
+symbol.
+
+  One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol.  Or a
+symbol may have a void function cell, in which case the subroutine
+@code{symbol-function} signals a @code{void-function} error.  But if
+neither of these things happens, we eventually obtain a non-symbol,
+which ought to be a function or other suitable object.
+
+@kindex invalid-function
+@cindex invalid function
+  More precisely, we should now have a Lisp function (a lambda
+expression), a byte-code function, a primitive function, a Lisp macro, a
+special form, or an autoload object.  Each of these types is a case
+described in one of the following sections.  If the object is not one of
+these types, the error @code{invalid-function} is signaled.
+
+  The following example illustrates the symbol indirection process.  We
+use @code{fset} to set the function cell of a symbol and
+@code{symbol-function} to get the function cell contents
+(@pxref{Function Cells}).  Specifically, we store the symbol @code{car}
+into the function cell of @code{first}, and the symbol @code{first} into
+the function cell of @code{erste}.
+
+@smallexample
+@group
+;; @r{Build this function cell linkage:}
+;;   -------------       -----        -------        -------
+;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
+;;   -------------       -----        -------        -------
+@end group
+@end smallexample
+
+@smallexample
+@group
+(symbol-function 'car)
+     @result{} #<subr car>
+@end group
+@group
+(fset 'first 'car)
+     @result{} car
+@end group
+@group
+(fset 'erste 'first)
+     @result{} first
+@end group
+@group
+(erste '(1 2 3))   ; @r{Call the function referenced by @code{erste}.}
+     @result{} 1
+@end group
+@end smallexample
+
+  By contrast, the following example calls a function without any symbol
+function indirection, because the first element is an anonymous Lisp
+function, not a symbol.
+
+@smallexample
+@group
+((lambda (arg) (erste arg))
+ '(1 2 3)) 
+     @result{} 1
+@end group
+@end smallexample
+
+@noindent
+After that function is called, its body is evaluated; this does
+involve symbol function indirection when calling @code{erste}.
+
+  The built-in function @code{indirect-function} provides an easy way to
+perform symbol function indirection explicitly.
+
+@c Emacs 19 feature
+@defun indirect-function function
+This function returns the meaning of @var{function} as a function.  If
+@var{function} is a symbol, then it finds @var{function}'s function
+definition and starts over with that value.  If @var{function} is not a
+symbol, then it returns @var{function} itself.
+
+Here is how you could define @code{indirect-function} in Lisp:
+
+@smallexample
+(defun indirect-function (function)
+  (if (symbolp function)
+      (indirect-function (symbol-function function))
+    function))
+@end smallexample
+@end defun
+
+@node Function Forms
+@subsection Evaluation of Function Forms
+@cindex function form evaluation
+@cindex function call
+
+  If the first element of a list being evaluated is a Lisp function
+object, byte-code object or primitive function object, then that list is
+a @dfn{function call}.  For example, here is a call to the function
+@code{+}:
+
+@example
+(+ 1 x)
+@end example
+
+  The first step ni evaluating a function call is to evaluate the
+remaining elements of the list in the order they appear.  The results
+are the actual argument values, one value for each list element.  The
+next step is to call the function with this list of arguments,
+effectively using the function @code{apply} (@pxref{Calling Functions}).
+If the function is written in Lisp, the arguments are used to bind the
+argument variables of the function (@pxref{Lambda Expressions}); then
+the forms in the function body are evaluated in order, and the value of
+the last body form becomes the value of the function call.
+
+@node Macro Forms
+@subsection Lisp Macro Evaluation
+@cindex macro call evaluation
+
+  If the first element of a list being evaluated is a macro object, then
+the list is a @dfn{macro call}.  When a macro call is evaluated, the
+elements of the rest of the list are @emph{not} initially evaluated.
+Instead, these elements themselves are used as the arguments of the
+macro.  The macro definition computes a replacement form, called the
+@dfn{expansion} of the macro, to be evaluated in place of the original
+form.  The expansion may be any sort of form: a self-evaluating
+constant, a symbol or a list.  If the expansion is itself a macro call,
+this process of expansion repeats until some other sort of form results.
+
+  Normally, the argument expressions are not evaluated as part of
+computing the macro expansion, but instead appear as part of the
+expansion, so they are evaluated when the expansion is evaluated.
+
+  For example, given a macro defined as follows:
+
+@example
+@group
+(defmacro cadr (x)
+  (list 'car (list 'cdr x)))
+@end group
+@end example
+
+@noindent
+an expression such as @code{(cadr (assq 'handler list))} is a macro
+call, and its expansion is:
+
+@example
+(car (cdr (assq 'handler list)))
+@end example
+
+@noindent
+Note that the argument @code{(assq 'handler list)} appears in the
+expansion.
+
+@xref{Macros}, for a complete description of Emacs Lisp macros.
+
+@node Special Forms
+@subsection Special Forms
+@cindex special form evaluation
+
+  A @dfn{special form} is a primitive function specially marked so that
+its arguments are not all evaluated.  Most special forms define control
+structures or perform variable bindings---things which functions cannot
+do.
+
+  Each special form has its own rules for which arguments are evaluated
+and which are used without evaluation.  Whether a particular argument is
+evaluated may depend on the results of evaluating other arguments.
+
+  Here is a list, in alphabetical order, of all of the special forms in
+Emacs Lisp with a reference to where each is described.
+
+@table @code
+@item and
+@pxref{Combining Conditions}
+
+@item catch
+@pxref{Catch and Throw}
+
+@item cond
+@pxref{Conditionals}
+
+@item condition-case
+@pxref{Handling Errors}
+
+@item defconst
+@pxref{Defining Variables}
+
+@item defmacro
+@pxref{Defining Macros}
+
+@item defun
+@pxref{Defining Functions}
+
+@item defvar
+@pxref{Defining Variables}
+
+@item function
+@pxref{Anonymous Functions}
+
+@item if
+@pxref{Conditionals}
+
+@item interactive
+@pxref{Interactive Call}
+
+@item let
+@itemx let*
+@pxref{Local Variables}
+
+@item or
+@pxref{Combining Conditions}
+
+@item prog1
+@itemx prog2
+@itemx progn
+@pxref{Sequencing}
+
+@item quote
+@pxref{Quoting}
+
+@item save-excursion
+@pxref{Excursions}
+
+@item save-restriction
+@pxref{Narrowing}
+
+@item save-window-excursion
+@pxref{Window Configurations}
+
+@item setq
+@pxref{Setting Variables}
+
+@item setq-default
+@pxref{Creating Buffer-Local}
+
+@item track-mouse
+@pxref{Mouse Tracking}
+
+@item unwind-protect
+@pxref{Nonlocal Exits}
+
+@item while
+@pxref{Iteration}
+
+@item with-output-to-temp-buffer
+@pxref{Temporary Displays}
+@end table
+
+@cindex CL note---special forms compared
+@quotation
+@b{Common Lisp note:} here are some comparisons of special forms in
+GNU Emacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
+@code{catch} are special forms in both Emacs Lisp and Common Lisp.
+@code{defun} is a special form in Emacs Lisp, but a macro in Common
+Lisp.  @code{save-excursion} is a special form in Emacs Lisp, but
+doesn't exist in Common Lisp.  @code{throw} is a special form in
+Common Lisp (because it must be able to throw multiple values), but it
+is a function in Emacs Lisp (which doesn't have multiple
+values).@refill
+@end quotation
+
+@node Autoloading
+@subsection Autoloading
+
+  The @dfn{autoload} feature allows you to call a function or macro
+whose function definition has not yet been loaded into Emacs.  It
+specifies which file contains the definition.  When an autoload object
+appears as a symbol's function definition, calling that symbol as a
+function automatically loads the specified file; then it calls the real
+definition loaded from that file.  @xref{Autoload}.
+
+@node Quoting
+@section Quoting
+@cindex quoting
+
+  The special form @code{quote} returns its single argument
+``unchanged''.
+
+@defspec quote object
+This special form returns @var{object}, without evaluating it.  This
+provides a way to include constant symbols and lists, which are not
+self-evaluating objects, in a program.  (It is not necessary to quote
+self-evaluating objects such as numbers, strings, and vectors.)
+
+@cindex @samp{'} for quoting
+@cindex quoting using apostrophe
+@cindex apostrophe for quoting
+Because @code{quote} is used so often in programs, Lisp provides a
+convenient read syntax for it.  An apostrophe character (@samp{'})
+followed by a Lisp object (in read syntax) expands to a list whose first
+element is @code{quote}, and whose second element is the object.  Thus,
+the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
+
+Here are some examples of expressions that use @code{quote}:
+
+@example
+@group
+(quote (+ 1 2))
+     @result{} (+ 1 2)
+@end group
+@group
+(quote foo)
+     @result{} foo
+@end group
+@group
+'foo
+     @result{} foo
+@end group
+@group
+''foo
+     @result{} (quote foo)
+@end group
+@group
+'(quote foo)
+     @result{} (quote foo)
+@end group
+@group
+['foo]
+     @result{} [(quote foo)]
+@end group
+@end example
+@end defspec
+
+  Other quoting constructs include @code{function} (@pxref{Anonymous
+Functions}), which causes an anonymous lambda expression written in Lisp
+to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote
+only part of a list, while computing and substituting other parts.