Initial git import

[sxemacs] / info / lispref / eval.texi

@c -*-texinfo-*-
@c This is part of the SXEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/eval.info

@node Evaluation, Control Structures, Symbols, Top
@chapter Evaluation
@cindex evaluation
@cindex  interpreter
@cindex interpreter
@cindex value of expression

  The @dfn{evaluation} of expressions in SXEmacs 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}.

@ifnottex
@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 that computes
the value of an expression that 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 ifnottex

@cindex forms
@cindex expression
  A Lisp object that 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}.

  Evaluation of a function call ultimately calls the function specified
in it.  @xref{Functions and Commands}.  The execution of the function may itself work
by evaluating the function definition; or the function may be a Lisp
primitive implemented in C, or it may be a byte-compiled function
(@pxref{Byte Compilation}).

@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 that 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)}.

  The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).

@node Eval
@section Eval
@c ??? Perhaps this should be the last section in the chapter.

  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.

  @strong{Please note:} it is generally cleaner and more flexible to call
functions that are stored in data structures, rather than to evaluate
expressions stored in data structures.  Using functions provides the
ability to pass information to them as arguments.

  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
(eval 'foo)
     @result{} bar
@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

@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
during the evaluation.

You can use the variable @code{load-read-function} to specify a function
for @code{eval-region} to use instead of @code{read} for reading
expressions.  @xref{How Programs Do Loading}.

@code{eval-region} always returns @code{nil}.
@end deffn

@cindex evaluation of buffer contents
@deffn Command eval-buffer buffer &optional stream
This is like @code{eval-region} except that it operates on the whole
contents of @var{buffer}.
@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
internal uses of those functions, such as for calling the functions
mentioned in Lisp expressions, 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 1000.  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 that 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-most-recent}
;;   @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 SXEmacs evaluates a form depends on its data type.  SXEmacs 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.  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}; you cannot set or bind them to any other values.  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
Executing the function itself evaluates its body; 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.

@defun indirect-function object
This function returns the meaning of @var{object} as a function.  If
@var{object} is a symbol, then it finds @var{object}'s function
definition and starts over with that value.  If @var{object} is not a
symbol, then it returns @var{object} 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 in evaluating a function call is to evaluate the
remaining elements of the list from left to right.  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.

  Ordinary evaluation of a macro call finishes by evaluating the
expansion.  However, the macro expansion is not necessarily evaluated
right away, or at all, because other programs also expand macro calls,
and they may or may not evaluate the expansions.

  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 computed when the expansion is computed.

  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: The argument @code{(assq 'handler list)} appears in the
expansion.

@xref{Macros}, for a complete description of SXEmacs 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
SXEmacs 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-current-buffer
@pxref{Excursions}

@item save-excursion
@pxref{Excursions}

@item save-restriction
@pxref{Narrowing}

@item save-selected-window
@pxref{Excursions}

@item save-window-excursion
@pxref{Window Configurations}

@item setq
@pxref{Setting Variables}

@item setq-default
@pxref{Creating Buffer-Local}

@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
SXEmacs Lisp and Common Lisp.  @code{setq}, @code{if}, and
@code{catch} are special forms in both SXEmacs Lisp and Common Lisp.
@code{defun} is a special form in SXEmacs Lisp, but a macro in Common
Lisp.  @code{save-excursion} is a special form in SXEmacs Lisp, but
does not 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 SXEmacs 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 SXEmacs.  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

  Quoting is a technique to modify the evaluation behaviour of
expressions.  This is achieved by wrapping the expression into a
special form.  The lisp reader will now evualate this special form
instead of the original expression.

SXEmacs basically knows about 3 quoting forms: @code{quote},
@code{function} and @code{backquote}.  Moreover, all of these possess
an alternative read syntax, @code{'}, @code{#'} and @code{`}
respectively.  In programs you will find almost exclusively the
abbreviated variants which also facilitate human reading of program
sources.  You can test yourself in the example section below. @c :)

@menu
* Quoting with quote::          The special form `quote' (')
* Quoting with function::       The special form `function' (#')
* Quoting with backquote::      The special form `backquote' (`)
* Nested quoting::              How to nest quoting forms
@end menu


@node Quoting with quote
@subsection Quoting with @code{quote}
@findex quote
@findex @samp{'}

  The special form @code{quote} returns its single argument, as written,
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.)

@defspec quote object
This special form returns @var{object}, without evaluating it.
@end defspec

@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@cindex apostrophe for quoting
@cindex quoting short forms
  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

  Numeric constants, indefinite symbols, string constants, character
constants and the special forms @code{t} and @code{nil} evaluate
themselves.  Quoting them is allowed but optional.  Vector constants
created with the bracket notation (@code{[ ]}) are also immune against
quoting.  @xref{Self-Evaluating Forms}.

@example
@group
'12
  @result{} 12
'2.333
  @result{} 2.333
'1/2
  @result{} 1/2
'2+5Z
  @result{} 2+5Z
'Z/12Z
  @result{} Z/12Z
'1+2i
  @result{} 1+2i
'0.5-0.5i
  @result{} 0.50000-0.50000i
@end group

@group
'+infinity
  @result{} +infinity
'-infinity
  @result{} -infinity
'complex-infinity
  @result{} complex-infinity
'not-a-number
  @result{} not-a-number
@end group

@group
'"string"
  @result{} "string"
(eval ''#r"\a\b\c")
  @result{} "\\a\\b\\c"
@end group

@group
'?a
  @result{} ?a
'?'
  @result{} ?\'
@end group

@group
't
  @result{} t
'nil
  @result{} nil
@end group

@group
[a b c]
  @result{} [a b c]
'[a b c]
  @result{} [a b c]
@end group
@end example


@node Quoting with function
@subsection Quoting with @code{function}
@findex function
@findex @samp{#'}

  The special form @code{function} returns its single argument, as
written, without evaluating it, and indicates thereby that this
argument is to be treated as function.  This is mandatory only if you
intend to compile your program and want the byte-compiler to
optimise your code accordingly.  Any other lisp code will accept both
the ordinarily quoted and the function-quoted form.  Because of this
SXEmacs does allow you to evaluate the value cell of a function-quoted
object.  However, this is bad style and may lead to problems in case
of byte-compilation.

@defspec function function-object
@cindex function quoting
This special form returns @var{function-object} without evaluating it.
In this, it is equivalent to @code{quote}.  However, it serves as a
note to the SXEmacs Lisp compiler that @var{function-object} is intended
to be used only as a function, and therefore can safely be compiled.
Contrast this with @code{quote}, in @ref{Quoting with quote}.
@end defspec

@cindex @samp{#'} for quoting
@cindex quoting short forms
  As for @code{quote}, there is also an abbreviated read syntax for
@code{function}.  A sharpsign character followed by an apostrophe
(@samp{#'}) followed by a a Lisp object in read syntax expands to a
list whose first element is @code{function}, and whose second element
is the object.  Thus, the read syntax @code{#'y} is an abbreviation for
@code{(function y)}.

  This effect can be used in macros to distinguish explicitly between
variable and function bindings, see example below, also
@pxref{Macros}.  However, since the rest of SXEmacs accepts both the
@code{quote}d and the @code{function}-quoted form equally and coerces
them to the desired form internally, macros or functions which diverge
from this norm should contain a clear remark in their docstring.

@noindent
Here are some examples of expressions that use @code{function}:
@example
@group
(function car)
  @result{} car
@end group
@group
#'car
  @result{} car
@end group
@group
'#'car
  => (function car)
@end group
@group
(symbol-function #'funcall)
  @result{} #<subr funcall>
(symbol-value #'nil)
  @result{} nil
@end group
@end example

@noindent
As mentioned above, an example for a macro which distinguishes between
@samp{'} and @samp{#'}.

@example
@group
(defmacro picky-funcall (symbol &rest arguments)
  (let ((type (car-safe symbol))
        (name (car (cdr-safe symbol)))
        (qargs (list 'quote arguments)))
    (cond ((eq type 'function)
           (list 'apply symbol qargs))
          ((eq type 'quote)
           (list 'apply name qargs))
          (t
           (error "I don't know what to do with `%s'." symbol)))))
@end group
@end example

@noindent
Now we define both a function with the name @samp{test} and a variable
with the name @samp{test}.  Afterwards we apply each to our
@code{picky-funcall}.

@example
@group
(defun test (a b)
  (+ a b))
  @result{} test
(defvar test '-)
  @result{} test
@end group

@group
(picky-funcall #'test 4 2)
  @result{} 6
(picky-funcall 'test 4 2)
  @result{} 2
@end group

@group
(picky-funcall test 4 2)
@error{} Cannot decide if `test' contains a variable or function.
@end group
@end example

  Again, the behaviour of @code{picky-funcall} is unusual in SXEmacs,
you should try to avoid it wherever you can.  In contrast, quoting
functions with @samp{#'} (or the @code{function} form) is usual and
even recommended because it clarifies your intention to both human
readers and the lisp expression reader.

  Also note, in a function definition you have no definite chance to
distinguish between any of the quoting forms.  This would revert
function indirection anyway.  However, if you intend to treat
variables different from functions you could try to guess using
@code{symbol-name}, @code{symbol-function} and @code{symbol-value}
(@pxref{Symbols}).

  As for quoting, self-evaluating forms are not affected by
function quotation.  However, function quoting such forms is most
likely wrong anyway so we will not give examples here.

  Nonetheless there is a macro definition to turn lambda-lists
(@pxref{Anonymous Functions}) into self-evaluating objects.

@smallexample
@group
(lambda (x) (+ x x))
  @result{} (lambda (x) (+ x x))
@end group
@end smallexample

@noindent
The true expansion of @code{(lambda @dots{})} is @code{(function (lambda @dots{}))}.


@node Quoting with backquote
@subsection Quoting with @code{`} (backquote)
@findex backquote
@findex @samp{`}
@cindex backquote (list substitution)
@cindex @samp{`} (list substitution)

  While @code{'} quotes its expression completely it is very
complicated to quote, say, a list of several elements but leave one
element unquoted (i.e. evaluate it).  The result would probably look
like:
@smallexample
(setq e 5)
(list 'a 'b 'c 'd e 'e 'e 'e)
  @result{} (a b c d 5 e e e)
@end smallexample

  In this sense, a backquote is somewhat the reverse operation of a
@samp{'}.  Backquote allows you to quote the entire list, but
selectively evaluate elements of that list.  However, in the simplest
case, it is identical to @code{quote}.  These two forms yield
identical results:

@example
@group
`(a list of (+ 2 3) elements)
  @result{} (a list of (+ 2 3) elements)
@end group
@group
'(a list of (+ 2 3) elements)
  @result{} (a list of (+ 2 3) elements)
@end group
@end example

  However, unlike @code{quote} which has a special read-syntax,
backquoting is implemented as macro and the routines @code{backquote}
and @code{`} do not coincide.

@unnumberedsubsec The @samp{,} marker
@findex @samp{,@@} @r{(with backquote)}
@cindex selective replace (with backquote)

The special marker @samp{,} can be used inside of the argument to
inhibit the quotation for this particular expression.  Thus the
backquote alternative of the motivation example above could be:

@smallexample
@group
(setq e 10)
`(a b c d ,e e e e)
  @result{} (a b c d 10 e e e)
@end group
@end smallexample

  Please note, the comma is not treated specially by the lisp reader,
thus it is a perfectly valid part of a symbol.  If you want to protect
against strange behaviour @strong{do not use a leading @samp{,} in
your variable or function names}.  In reality symbols with leading
commas can be of great use in nested quoting constructions,
@pxref{Nested quoting}.  However, make sure that none of such bindings
escapes to the normal lisp environment.

@unnumberedsubsec The @samp{,@@} marker
@findex @samp{,@@} @r{(with backquote)}
@cindex splicing (with backquote)

  With the special marker @samp{,@@} inside of a backquoted expression
you can @dfn{splice} an evaluated value into the resulting list.  The
elements of the spliced list become elements at the same level as the
other elements of the resulting list.  The equivalent code without
using @samp{`} is often unreadable.

  Like the comma operator @samp{,@@} is not treated specially by the
lisp reader either.  You will have to take care for symbol names with
leading @samp{,@@} in foreign (i.e. non-backquoting) contexts and
their bindings yourself.

@noindent
Let us now look at a more pragmatic example of backquoting.

@example
@group
(defun interior (function fix-arg)
  "Return the insertion of FIX-ARG in FUNCTION,
that is a function which is derived from FUNCTION by fixating the
first argument to FIX-ARG and keeping the rest variable.

This process is often referred to as currying.
Mathematically it is a special interior product (hence the name)."
  (let* ((body (indirect-function function))
         (args
          (cond ((subrp body)
                 (error "Error: Cannot handle built-in functions."))
                ((compiled-function-p body)
                 (compiled-function-arglist body))
                (t
                 (cadr body))))
         (newarglist
          (if args
              (cdr args)
            (error "Error: %s accepts no arguments." function)))
         (newargs
          (delq '&optional (copy-list newarglist))))
    `(lambda ,newarglist
       (,function ',fix-arg ,@@newargs))))
  @result{} interior
@end group
@end example

  This definition is far from perfect but sufficient for our
purposes.  Since we excluded built-in functions in the above code we
define a simple lisp equivalent of the @code{list} function.

@example
@group
(defun list-demo (a b c d)
  "Return the list (A B C D)."
  (list a b c d))
  @result{} list-demo
@end group

@group
(list-demo 1 'a 2 t)
  @result{} (1 a 2 t)
@end group
@end example

@noindent
Now we look at the interior product of @samp{?a} and
@code{list-demo}.

@example
@group
(interior #'list-demo ?a)
  @result{} (lambda (b c d) (list-demo (quote ?a) b c d))
@end group
@end example

  As you can see, @code{,function} and @code{,fix-arg} have been
replaced with the according argument passed to @code{interior}.
Additionally we quote the replace of @code{,fix-arg} to prevent
another expansion of the replacement during the call of the resulting
function.  Also note how the list in @var{newargs} which had the local
binding @samp{(b c d)} within @code{interior} has been spliced into the
function call expression.

@smallexample
@group
(fset #'list-demo-a (interior #'list-demo ?a))
  @result{} (lambda (b c d) (list-demo (quote ?a) b c d))
(list-demo-a 'and 3 'args)
  => (?a and 3 args)
@end group
@end smallexample

  Now let's have a glance at a prominent annoyance.  The
@var{function} argument of the @code{mapcar} function is passed
exactly one argument (an element of the given list).  Sometimes it is
wishful to map a two-argument function whose first argument is
constant during the mapping anyway.  In this scenario our
@code{interior} comes in very handy.

@example
@group
(defvar demo-hook nil)
  => demo-hook
(mapcar (interior #'add-hook 'demo-hook) '(first-fun another-fun))
  @result{} ((first-fun) (another-fun first-fun))
demo-hook
  @result{} (another-fun first-fun)
@end group
@end example

@unnumberedsubsec The @samp{,.} marker
@findex @samp{,.} @r{(with backquote)}
@cindex destructive splicing (with backquote)

  Instead of the splicing operator @samp{,@@} which internally uses
@code{append} to splice an expression into the list at place, you can
always use the destructive form @samp{,.} instead which internally
uses @code{nconc}.  Refer to the documentation of @code{nconc} for
more information, @pxref{Rearrangement}.

@example
@group
(setq test-list '(a b))
  @result{} (a b)
@end group

@group
`(,.test-list ,(+ 2 3))
  @result{} (a b 5)
`(,.test-list ,(+ 3 4))
  @result{} (a b 5 7)
@end group

@group
test-list
  @result{} (a b 5 7)
@end group
@end example


@node Nested quoting
@subsection Nested quoting

  Simple nested quotations have already been used throughout this
section.  Indeed, function quoting and symbol quoting may be used
combined in order and any nesting level.  Trying to quote of a
self-evaluating or special form necessarily leads to double quoting
it.  Thus @code{''?a} will become @code{(quote ?a)}.

  Furthermore, we have already seen that backquoting empowers us to
create a mixture of quoted and evaluated parts of an expression.  We
shall now look at the various oddities which may arise particularly in
nested quotation scenarios.

@example
@group
(setq y 'x
      x 'y)
@end group

@group
`(,y `(,y ,@@(+ 2 3)) ,@@(+ 2 3))
  @result{} (x (bq-list* y (+ 2 3)) . 5)

`(,y ,`(,y ,@@(+ 2 3)) ,@@(+ 2 3))
  => (x (x . 5) . 5)

`(,y ,'`(,y ,@@(+ 2 3)) ,@@(+ 2 3))
  @result{} (x (backquote ((\, y) (\,@ (+ 2 3)))) . 5)
@end group
@end example

  In the first example, you can behold the dequoting strategy of
nested backquotes.  Like other lisp implementations and dialects the
nested structure is somewhat preserved.  Substitutions are made only
for dequoted (or marked as such) elements appearing at the same
nesting level as the outermost backquote.  But evaluation takes place
at all nesting levels likewise.  Inner backquote lists are evaluated
but remain quoted within the outer backquote list unless these are
marked themselves for dequoting and substitution.  For your
information, the @code{bq-list*} macro behaves like Common Lisp's
@code{list*} form.

@noindent
Evaluation of the inner expression yields:
@smallexample
@group
(bq-list* y (+ 2 3))
  @result{} (x . 5)
@end group
@end smallexample

@noindent
This evaluation explains the second example.

  Sometimes it is useful to leave inner backquote lists entirely
untouched, for example in macros which in turn define other macros
which then use backquote lists in their definition.  Example 3
demonstrates how this can be achieved.

@unnumberedsubsec Dequoting across nesting bounds

  There is no definite concept (yet).  You will achieve what you want
if you carefully quote your expressions.  Although you need to use the
expanded names for @code{`}, @code{,}, @code{,@@} and @code{,.}.

@smallexample
@group
(let ((y 'x)
      (x 'y))
  `(,y (,'backquote (,y  ,',y))))
  @result{} (x (backquote (x (\, y))))
@end group
@end smallexample

@noindent
With growing nesting complexity list constructors may well be more
flexible.

@smallexample
@group
(let ((y 'x)
      (x 'y))
  (list y (list 'backquote (list y '(\, y)))))
  @result{} (x (backquote (x (\, y))))
@end group
@end smallexample

  In the future we may provide a more comprehensible concept where the
above scenario would simply read @code{`(,y ``(,y ,,y))}.  On the
other hand you can create your own solutions of backquotations using
-- better said abusing -- the comma read-syntax.  The idea is to
locally make all variables self-evaluating and explicitly specify an
expansion for commatised variables.  To get this right, this is one
method out of many and it it a matter of personal taste.  The next
(very) simple example merely demonstrates the idea and does not
represent a concept nor a special elisp feature at all:

@smallexample
(let* ((x 'x)
       (y 'y)
       (,x 'top-level)
       (,y x)
       (,,x ,x)
       (,,y ,x))
  (list x y ,x ,y ,,x ,,y))
@end smallexample