   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Defining Named Functions
========================

   We usually give a name to a function when it is first created.  This
is called "defining a function", and it is done with the `defun'
special form.

 - Special Form: defun NAME ARGUMENT-LIST BODY-FORMS
     `defun' is the usual way to define new Lisp functions.  It defines
     the symbol NAME as a function that looks like this:

          (lambda ARGUMENT-LIST . BODY-FORMS)

     This lambda expression is stored in the function cell of NAME.
     The value returned by evaluating the `defun' form is NAME, but
     usually we ignore this value.

     As described previously (see Lambda Expressions.),
     ARGUMENT-LIST is a list of argument names and may include the
     keywords `&optional' and `&rest'.  Also, the first two forms in
     BODY-FORMS may be a documentation string and an interactive
     declaration.

     Note that the same symbol NAME may also be used as a global
     variable, since the value cell is independent of the function cell.

     Here are some examples:

          (defun foo () 5)
               => foo
          (foo)
               => 5

          (defun bar (a &optional b &rest c)
              (list a b c))
               => bar
          (bar 1 2 3 4 5)
               => (1 2 (3 4 5))
          (bar 1)
               => (1 nil nil)
          (bar)
          error--> Wrong number of arguments.

          (defun capitalize-backwards ()
            "Upcase the last letter of a word."
            (interactive)
            (backward-word 1)
            (forward-word 1)
            (backward-char 1)
            (capitalize-word 1))
               => capitalize-backwards

     Be careful not to redefine existing functions unintentionally.
     `defun' redefines even primitive functions such as `car' without
     any hesitation or notification.  Redefining a function already
     defined is often done deliberately, and there is no way to
     distinguish deliberate redefinition from unintentional
     redefinition.

Calling Functions
=================

   Defining functions is only half the battle.  Functions don't do
anything until you "call" them, i.e., tell them to run.  This process
is also known as "invocation".

   The most common way of invoking a function is by evaluating a list.
For example, evaluating the list `(concat "a" "b")' calls the function
`concat'.  See Evaluation, for a description of evaluation.

   When you write a list as an expression in your program, the function
name is part of the program.  This means that the choice of which
function to call is made when you write the program.  Usually that's
just what you want.  Occasionally you need to decide at run time which
function to call.  Then you can use the functions `funcall' and `apply'.

 - Function: funcall FUNCTION &rest ARGUMENTS
     `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
     FUNCTION returns.

     Since `funcall' is a function, all of its arguments, including
     FUNCTION, are evaluated before `funcall' is called.  This means
     that you can use any expression to obtain the function to be
     called.  It also means that `funcall' does not see the expressions
     you write for the ARGUMENTS, only their values.  These values are
     *not* evaluated a second time in the act of calling FUNCTION;
     `funcall' enters the normal procedure for calling a function at the
     place where the arguments have already been evaluated.

     The argument FUNCTION must be either a Lisp function or a
     primitive function.  Special forms and macros are not allowed,
     because they make sense only when given the "unevaluated" argument
     expressions.  `funcall' cannot provide these because, as we saw
     above, it never knows them in the first place.

          (setq f 'list)
               => list
          (funcall f 'x 'y 'z)
               => (x y z)
          (funcall f 'x 'y '(z))
               => (x y (z))
          (funcall 'and t nil)
          error--> Invalid function: #<subr and>

     Compare this example with that of `apply'.

 - Function: apply FUNCTION &rest ARGUMENTS
     `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
     with one difference: the last of ARGUMENTS is a list of arguments
     to give to FUNCTION, rather than a single argument.  We also say
     that this list is "appended" to the other arguments.

     `apply' returns the result of calling FUNCTION.  As with
     `funcall', FUNCTION must either be a Lisp function or a primitive
     function; special forms and macros do not make sense in `apply'.

          (setq f 'list)
               => list
          (apply f 'x 'y 'z)
          error--> Wrong type argument: listp, z
          (apply '+ 1 2 '(3 4))
               => 10
          (apply '+ '(1 2 3 4))
               => 10

          (apply 'append '((a b c) nil (x y z) nil))
               => (a b c x y z)

     An interesting example of using `apply' is found in the description
     of `mapcar'; see the following section.

   It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using `funcall' or `apply'.  Functions that accept
function arguments are often called "functionals".

   Sometimes, when you call such a function, it is useful to supply a
no-op function as the argument.  Here are two different kinds of no-op
function:

 - Function: identity ARG
     This function returns ARG and has no side effects.

 - Function: ignore &rest ARGS
     This function ignores any arguments and returns `nil'.

Mapping Functions
=================

   A "mapping function" applies a given function to each element of a
list or other collection.  Emacs Lisp has three such functions;
`mapcar' and `mapconcat', which scan a list, are described here.  For
the third mapping function, `mapatoms', see Creating Symbols.

 - Function: mapcar FUNCTION SEQUENCE
     `mapcar' applies FUNCTION to each element of SEQUENCE in turn.
     The results are made into a `nil'-terminated list.

     The argument SEQUENCE may be a list, a vector or a string.  The
     result is always a list.  The length of the result is the same as
     the length of SEQUENCE.

     For example:

          (mapcar 'car '((a b) (c d) (e f)))
               => (a c e)
          (mapcar '1+ [1 2 3])
               => (2 3 4)
          (mapcar 'char-to-string "abc")
               => ("a" "b" "c")

          ;; Call each function in `my-hooks'.
          (mapcar 'funcall my-hooks)

          (defun mapcar* (f &rest args)
            "Apply FUNCTION to successive cars of all ARGS, until one
          ends.  Return the list of results."
            ;; If no list is exhausted,
            (if (not (memq 'nil args))
                ;; Apply function to CARs.
                (cons (apply f (mapcar 'car args))
                      (apply 'mapcar* f
                             ;; Recurse for rest of elements.
                             (mapcar 'cdr args)))))

          (mapcar* 'cons '(a b c) '(1 2 3 4))
               => ((a . 1) (b . 2) (c . 3))

 - Function: mapconcat FUNCTION SEQUENCE SEPARATOR
     `mapconcat' applies FUNCTION to each element of SEQUENCE: the
     results, which must be strings, are concatenated.  Between each
     pair of result strings, `mapconcat' inserts the string SEPARATOR.
     Usually SEPARATOR contains a space or comma or other suitable
     punctuation.

     The argument FUNCTION must be a function that can take one
     argument and returns a string.

          (mapconcat 'symbol-name
                     '(The cat in the hat)
                     " ")
               => "The cat in the hat"

          (mapconcat (function (lambda (x) (format "%c" (1+ x))))
                     "HAL-8000"
                     "")
               => "IBM.9111"

Anonymous Functions
===================

   In Lisp, a function is a list that starts with `lambda' (or
alternatively a primitive subr-object); names are "extra".  Although
usually functions are defined with `defun' and given names at the same
time, it is occasionally more concise to use an explicit lambda
expression--an anonymous function.  Such a list is valid wherever a
function name is.

   Any method of creating such a list makes a valid function.  Even
this:

     (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
          => (lambda (x) (+ 12 x))

This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
it the value (*not* the function definition!) of `silly'.

   Here is how we might call this function:

     (funcall silly 1)
          => 13

(It does *not* work to write `(silly 1)', because this function is not
the *function definition* of `silly'.  We have not given `silly' any
function definition, just a value as a variable.)

   Most of the time, anonymous functions are constants that appear in
your program.  For example, you might want to pass one as an argument
to the function `mapcar', which applies any given function to each
element of a list.  Here we pass an anonymous function that multiplies
a number by two:

     (defun double-each (list)
       (mapcar '(lambda (x) (* 2 x)) list))
          => double-each
     (double-each '(2 11))
          => (4 22)

In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function.

 - Special Form: function FUNCTION-OBJECT
     This special form returns FUNCTION-OBJECT without evaluating it.
     In this, it is equivalent to `quote'.  However, it serves as a
     note to the Emacs Lisp compiler that FUNCTION-OBJECT is intended
     to be used only as a function, and therefore can safely be
     compiled.  See Quoting, for comparison.

   Using `function' instead of `quote' makes a difference inside a
function or macro that you are going to compile.  For example:

     (defun double-each (list)
       (mapcar (function (lambda (x) (* 2 x))) list))
          => double-each
     (double-each '(2 11))
          => (4 22)

If this definition of `double-each' is compiled, the anonymous function
is compiled as well.  By contrast, in the previous definition where
ordinary `quote' is used, the argument passed to `mapcar' is the
precise list shown:

     (lambda (arg) (+ arg 5))

The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what `mapcar' does with the
list.  Perhaps `mapcar' will check that the CAR of the third element is
the symbol `+'!  The advantage of `function' is that it tells the
compiler to go ahead and compile the constant function.

   We sometimes write `function' instead of `quote' when quoting the
name of a function, but this usage is just a sort of comment.

     (function SYMBOL) == (quote SYMBOL) == 'SYMBOL

   See `documentation' in Accessing Documentation, for a
realistic example using `function' and an anonymous function.

Accessing Function Cell Contents
================================

   The "function definition" of a symbol is the object stored in the
function cell of the symbol.  The functions described here access, test,
and set the function cell of symbols.

 - Function: symbol-function SYMBOL
     This returns the object in the function cell of SYMBOL.  If the
     symbol's function cell is void, a `void-function' error is
     signaled.

     This function does not check that the returned object is a
     legitimate function.

          (defun bar (n) (+ n 2))
               => bar
          (symbol-function 'bar)
               => (lambda (n) (+ n 2))
          (fset 'baz 'bar)
               => bar
          (symbol-function 'baz)
               => bar

   If you have never given a symbol any function definition, we say that
that symbol's function cell is "void".  In other words, the function
cell does not have any Lisp object in it.  If you try to call such a
symbol as a function, it signals a `void-function' error.

   Note that void is not the same as `nil' or the symbol `void'.  The
symbols `nil' and `void' are Lisp objects, and can be stored into a
function cell just as any other object can be (and they can be valid
functions if you define them in turn with `defun'); but `nil' or `void'
is *an object*.  A void function cell contains no object whatsoever.

   You can test the voidness of a symbol's function definition with
`fboundp'.  After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.

 - Function: fboundp SYMBOL
     Returns `t' if the symbol has an object in its function cell,
     `nil' otherwise.  It does not check that the object is a legitimate
     function.

 - Function: fmakunbound SYMBOL
     This function makes SYMBOL's function cell void, so that a
     subsequent attempt to access this cell will cause a `void-function'
     error.  (See also `makunbound', in Local Variables.)

          (defun foo (x) x)
               => x
          (fmakunbound 'foo)
               => x
          (foo 1)
          error--> Symbol's function definition is void: foo

 - Function: fset SYMBOL OBJECT
     This function stores OBJECT in the function cell of SYMBOL.  The
     result is OBJECT.  Normally OBJECT should be a function or the
     name of a function, but this is not checked.

     There are three normal uses of this function:

        * Copying one symbol's function definition to another.  (In
          other words, making an alternate name for a function.)

        * Giving a symbol a function definition that is not a list and
          therefore cannot be made with `defun'.  See Classifying Lists,
          for an example of this usage.

        * In constructs for defining or altering functions.  If `defun'
          were not a primitive, it could be written in Lisp (as a
          macro) using `fset'.

     Here are examples of the first two uses:

          ;; Give `first' the same definition `car' has.
          (fset 'first (symbol-function 'car))
               => #<subr car>
          (first '(1 2 3))
               => 1

          ;; Make the symbol `car' the function definition of `xfirst'.
          (fset 'xfirst 'car)
               => car
          (xfirst '(1 2 3))
               => 1
          (symbol-function 'xfirst)
               => car
          (symbol-function (symbol-function 'xfirst))
               => #<subr car>

          ;; Define a named keyboard macro.
          (fset 'kill-two-lines "\^u2\^k")
               => "\^u2\^k"

   When writing a function that extends a previously defined function,
the following idiom is often used:

     (fset 'old-foo (symbol-function 'foo))

     (defun foo ()
       "Just like old-foo, except more so."
       (old-foo)
       (more-so))

This does not work properly if `foo' has been defined to autoload.  In
such a case, when `foo' calls `old-foo', Lisp attempts to define
`old-foo' by loading a file.  Since this presumably defines `foo'
rather than `old-foo', it does not produce the proper results.  The
only way to avoid this problem is to make sure the file is loaded
before moving aside the old definition of `foo'.

   See also the function `indirect-function' in Function Indirection.

Inline Functions
================

   You can define an "inline function" by using `defsubst' instead of
`defun'.  An inline function works just like an ordinary function
except for one thing: when you compile a call to the function, the
function's definition is open-coded into the caller.

   Making a function inline makes explicit calls run faster.  But it
also has disadvantages.  For one thing, it reduces flexibility; if you
change the definition of the function, calls already inlined still use
the old definition until you recompile them.  Since the flexibility of
redefining functions is an important features of Emacs, you should not
make a function inline unless its speed is really crucial.

   Another disadvantage is that making a large function inline can
increase the size of compiled code both in files and in memory.  Since
the advantages of inline functions are greatest for small functions, you
generally should not make large functions inline.

   It's possible to define a macro to expand into the same code that an
inline function would execute.  But the macro would have a limitation:
you can use it only explicitly--a macro cannot be called with `apply',
`mapcar' and so on.  Also, it takes some work to convert an ordinary
function into a macro.  (see Macros.)  To convert it into an inline
function is very easy; simply replace `defun' with `defsubst'.

   Inline functions can be used and open coded later on in the same
file, following the definition, just like macros.

   Emacs versions prior to 19 did not have inline functions.

Other Topics Related to Functions
=================================

   Here is a table of several functions that do things related to
function calling and function definitions.  They are documented
elsewhere, but we provide cross references here.

`apply'
     See Calling Functions.

`autoload'
     See Autoload.

`call-interactively'
     See Interactive Call.

`commandp'
     See Interactive Call.

`documentation'
     See Accessing Documentation.

`eval'
     See Eval.

`funcall'
     See Calling Functions.

`ignore'
     See Calling Functions.

`indirect-function'
     See Function Indirection.

`interactive'
     See Using Interactive.

`interactive-p'
     See Interactive Call.

`mapatoms'
     See Creating Symbols.

`mapcar'
     See Mapping Functions.

`mapconcat'
     See Mapping Functions.

`undefined'
     See Key Lookup.

Macros
******

   "Macros" enable you to define new control constructs and other
language features.  A macro is defined much like a function, but instead
of telling how to compute a value, it tells how to compute another Lisp
expression which will in turn compute the value.  We call this
expression the "expansion" of the macro.

   Macros can do this because they operate on the unevaluated
expressions for the arguments, not on the argument values as functions
do.  They can therefore construct an expansion containing these
argument expressions or parts of them.

   If you are using a macro to do something an ordinary function could
do, just for the sake of speed, consider using an inline function
instead.  See Inline Functions.

A Simple Example of a Macro
===========================

   Suppose we would like to define a Lisp construct to increment a
variable value, much like the `++' operator in C.  We would like to
write `(inc x)' and have the effect of `(setq x (1+ x))'.  Here's a
macro definition that does the job:

     (defmacro inc (var)
        (list 'setq var (list '1+ var)))

   When this is called with `(inc x)', the argument `var' has the value
`x'--*not* the *value* of `x'.  The body of the macro uses this to
construct the expansion, which is `(setq x (1+ x))'.  Once the macro
definition returns this expansion, Lisp proceeds to evaluate it, thus
incrementing `x'.

Expansion of a Macro Call
=========================

   A macro call looks just like a function call in that it is a list
which starts with the name of the macro.  The rest of the elements of
the list are the arguments of the macro.

   Evaluation of the macro call begins like evaluation of a function
call except for one crucial difference: the macro arguments are the
actual expressions appearing in the macro call.  They are not evaluated
before they are given to the macro definition.  By contrast, the
arguments of a function are results of evaluating the elements of the
function call list.

   Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked.  The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a `&rest' argument.  And the macro body executes and returns
its value just as a function body does.

   The second crucial difference between macros and functions is that
the value returned by the macro body is not the value of the macro call.
Instead, it is an alternate expression for computing that value, also
known as the "expansion" of the macro.  The Lisp interpreter proceeds
to evaluate the expansion as soon as it comes back from the macro.

   Since the expansion is evaluated in the normal manner, it may contain
calls to other macros.  It may even be a call to the same macro, though
this is unusual.

   You can see the expansion of a given macro call by calling
`macroexpand'.

 - Function: macroexpand FORM &optional ENVIRONMENT
     This function expands FORM, if it is a macro call.  If the result
     is another macro call, it is expanded in turn, until something
     which is not a macro call results.  That is the value returned by
     `macroexpand'.  If FORM is not a macro call to begin with, it is
     returned as given.

     Note that `macroexpand' does not look at the subexpressions of
     FORM (although some macro definitions may do so).  Even if they
     are macro calls themselves, `macroexpand' does not expand them.

     The function `macroexpand' does not expand calls to inline
     functions.  Normally there is no need for that, since a call to an
     inline function is no harder to understand than a call to an
     ordinary function.

     If ENVIRONMENT is provided, it specifies an alist of macro
     definitions that shadow the currently defined macros.  This is used
     by byte compilation.

          (defmacro inc (var)
              (list 'setq var (list '1+ var)))
               => inc

          (macroexpand '(inc r))
               => (setq r (1+ r))

          (defmacro inc2 (var1 var2)
              (list 'progn (list 'inc var1) (list 'inc var2)))
               => inc2

          (macroexpand '(inc2 r s))
               => (progn (inc r) (inc s))  ; `inc' not expanded here.

Macros and Byte Compilation
===========================

   You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion.  Why not have the macro body
produce the desired results directly?  The reason has to do with
compilation.

   When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and
receives an expansion.  But instead of evaluating this expansion, it
compiles the expansion as if it had appeared directly in the program.
As a result, the compiled code produces the value and side effects
intended for the macro, but executes at full compiled speed.  This would
not work if the macro body computed the value and side effects
itself--they would be computed at compile time, which is not useful.

   In order for compilation of macro calls to work, the macros must be
defined in Lisp when the calls to them are compiled.  The compiler has a
special feature to help you do this: if a file being compiled contains a
`defmacro' form, the macro is defined temporarily for the rest of the
compilation of that file.  To use this feature, you must define the
macro in the same file where it is used and before its first use.

   While byte-compiling a file, any `require' calls at top-level are
executed.  One way to ensure that necessary macro definitions are
available during compilation is to require the file that defines them.
See Features.

Defining Macros
===============

   A Lisp macro is a list whose CAR is `macro'.  Its CDR should be a
function; expansion of the macro works by applying the function (with
`apply') to the list of unevaluated argument-expressions from the macro
call.

   It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to mapping functions such as `mapcar'.  In practice,
all Lisp macros have names, and they are usually defined with the
special form `defmacro'.

 - Special Form: defmacro NAME ARGUMENT-LIST BODY-FORMS...
     `defmacro' defines the symbol NAME as a macro that looks like this:

          (macro lambda ARGUMENT-LIST . BODY-FORMS)

     This macro object is stored in the function cell of NAME.  The
     value returned by evaluating the `defmacro' form is NAME, but
     usually we ignore this value.

     The shape and meaning of ARGUMENT-LIST is the same as in a
     function, and the keywords `&rest' and `&optional' may be used
     (see Argument List.).  Macros may have a documentation string,
     but any `interactive' declaration is ignored since macros cannot be
     called interactively.

Backquote
=========

   It could prove rather awkward to write macros of significant size,
simply due to the number of times the function `list' needs to be
called.  To make writing these forms easier, a macro ``' (often called
"backquote") exists.

   Backquote allows you to quote a list, but selectively evaluate
elements of that list.  In the simplest case, it is identical to the
special form `quote' (see Quoting.).  For example, these two forms
yield identical results:

     (` (a list of (+ 2 3) elements))
          => (a list of (+ 2 3) elements)
     (quote (a list of (+ 2 3) elements))
          => (a list of (+ 2 3) elements)

   By inserting a special marker, `,', inside of the argument to
backquote, it is possible to evaluate desired portions of the argument:

     (list 'a 'list 'of (+ 2 3) 'elements)
          => (a list of 5 elements)
     (` (a list of (, (+ 2 3)) elements))
          => (a list of 5 elements)

   It is also possible to have an evaluated list "spliced" into the
resulting list by using the special marker `,@'.  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 ``' is often
unreadable.  Here are some examples:

     (setq some-list '(2 3))
          => (2 3)
     (cons 1 (append some-list '(4) some-list))
          => (1 2 3 4 2 3)
     (` (1 (,@ some-list) 4 (,@ some-list)))
          => (1 2 3 4 2 3)

     (setq list '(hack foo bar))
          => (hack foo bar)
     (cons 'use
       (cons 'the
         (cons 'words (append (cdr list) '(as elements)))))
          => (use the words foo bar as elements)
     (` (use the words (,@ (cdr list)) as elements (,@ nil)))
          => (use the words foo bar as elements)

   The reason for `(,@ nil)' is to avoid a bug in Emacs version 18.
The bug occurs when a call to `,@' is followed only by constant
elements.  Thus,

     (` (use the words (,@ (cdr list)) as elements))

would not work, though it really ought to.  `(,@ nil)' avoids the
problem by being a nonconstant element that does not affect the result.

 - Macro: ` LIST
     This macro returns LIST as `quote' would, except that the list is
     copied each time this expression is evaluated, and any sublist of
     the form `(, SUBEXP)' is replaced by the value of SUBEXP.  Any
     sublist of the form `(,@ LISTEXP)' is replaced by evaluating
     LISTEXP and splicing its elements into the containing list in
     place of this sublist.  (A single sublist can in this way be
     replaced by any number of new elements in the containing list.)

     There are certain contexts in which `,' would not be recognized and
     should not be used:

          ;; Use of a `,' expression as the CDR of a list.
          (` (a . (, 1)))                             ; Not `(a . 1)'
               => (a \, 1)

          ;; Use of `,' in a vector.
          (` [a (, 1) c])                             ; Not `[a 1 c]'
               error--> Wrong type argument

          ;; Use of a `,' as the entire argument of ``'.
          (` (, 2))                                   ; Not 2
               => (\, 2)

     Common Lisp note: in Common Lisp, `,' and `,@' are implemented as
     reader macros, so they do not require parentheses.  Emacs Lisp
     implements them as functions because reader macros are not
     supported (to save space).

Common Problems Using Macros
============================

   The basic facts of macro expansion have all been described above, but
there consequences are often counterintuitive.  This section describes
some important consequences that can lead to trouble, and rules to
follow to avoid trouble.

Evaluating Macro Arguments Too Many Times
-----------------------------------------

   When defining a macro you must pay attention to the number of times
the arguments will be evaluated when the expansion is executed.  The
following macro (used to facilitate iteration) illustrates the problem.
This macro allows us to write a simple "for" loop such as one might
find in Pascal.

     (defmacro for (var from init to final do &rest body)
       "Execute a simple \"for\" loop, e.g.,
         (for i from 1 to 10 do (print i))."
       (list 'let (list (list var init))
             (cons 'while (cons (list '<= var final)
                                (append body (list (list 'inc var)))))))
     => for
     (for i from 1 to 3 do
        (setq square (* i i))
        (princ (format "\n%d %d" i square)))
     ==>

     (let ((i 1))
       (while (<= i 3)
         (setq square (* i i))
         (princ (format "%d      %d" i square))
         (inc i)))

     -|1       1
          -|2       4
          -|3       9
     => nil

(The arguments `from', `to', and `do' in this macro are "syntactic
sugar"; they are entirely ignored.  The idea is that you will write
noise words (such as `from', `to', and `do') in those positions in the
macro call.)

   This macro suffers from the defect that FINAL is evaluated on every
iteration.  If FINAL is a constant, this is not a problem.  If it is a
more complex form, say `(long-complex-calculation x)', this can slow
down the execution significantly.  If FINAL has side effects, executing
it more than once is probably incorrect.

   A well-designed macro definition takes steps to avoid this problem by
producing an expansion that evaluates the argument expressions exactly
once unless repeated evaluation is part of the intended purpose of the
macro.  Here is a correct expansion for the `for' macro:

     (let ((i 1)
           (max 3))
       (while (<= i max)
         (setq square (* i i))
         (princ (format "%d      %d" i square))
         (inc i)))

   Here is a macro definition that creates this expansion:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
       (` (let (((, var) (, init))
                (max (, final)))
            (while (<= (, var) max)
              (,@ body)
              (inc (, var))))))

   Unfortunately, this introduces another problem.

   Proceed to the following node.

Local Variables in Macro Expansions
-----------------------------------

   In the previous section, the definition of `for' was fixed as
follows to make the expansion evaluate the macro arguments the proper
number of times:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."

     (` (let (((, var) (, init))
                (max (, final)))
            (while (<= (, var) max)
              (,@ body)
              (inc (, var))))))

   The new definition of `for' has a new problem: it introduces a local
variable named `max' which the user does not expect.  This causes
trouble in examples such as the following:

     (let ((max 0))
       (for x from 0 to 10 do
         (let ((this (frob x)))
           (if (< max this)
               (setq max this)))))

The references to `max' inside the body of the `for', which are
supposed to refer to the user's binding of `max', really access the
binding made by `for'.

   The way to correct this is to use an uninterned symbol instead of
`max' (see Creating Symbols.).  The uninterned symbol can be bound
and referred to just like any other symbol, but since it is created by
`for', we know that it cannot appear in the user's program.  Since it
is not interned, there is no way the user can put it into the program
later.  It will never appear anywhere except where put by `for'.  Here
is a definition of `for' which works this way:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
       (let ((tempvar (make-symbol "max")))
         (` (let (((, var) (, init))
                  ((, tempvar) (, final)))
              (while (<= (, var) (, tempvar))
                     (,@ body)
                     (inc (, var)))))))

This creates an uninterned symbol named `max' and puts it in the
expansion instead of the usual interned symbol `max' that appears in
expressions ordinarily.

Evaluating Macro Arguments in Expansion
---------------------------------------

   Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
`eval' (see Eval.).  If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments.  Inside the
macro body, the macro argument binding is the most local binding of this
variable, so any references inside the form being evaluated do refer to
it.  Here is an example:

     (defmacro foo (a)
       (list 'setq (eval a) t))
          => foo
     (setq x 'b)
     (foo x) ==> (setq b t)
          => t                  ; and `b' has been set.
     ;; but
     (setq a 'b)
     (foo a) ==> (setq 'b t)     ; invalid!
     error--> Symbol's value is void: b

   It makes a difference whether the user types `a' or `x', because `a'
conflicts with the macro argument variable `a'.

   In general it is best to avoid calling `eval' in a macro definition
at all.

How Many Times is the Macro Expanded?
-------------------------------------

   Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is
expanded only once (during compilation) for a compiled function.  If the
macro definition has side effects, they will work differently depending
on how many times the macro is expanded.

   In particular, constructing objects is a kind of side effect.  If the
macro is called once, then the objects are constructed only once.  In
other words, the same structure of objects is used each time the macro
call is executed.  In interpreted operation, the macro is reexpanded
each time, producing a fresh collection of objects each time.  Usually
this does not matter--the objects have the same contents whether they
are shared or not.  But if the surrounding program does side effects on
the objects, it makes a difference whether they are shared.  Here is an
example:

     (defmacro new-object ()
       (list 'quote (cons nil nil)))

     (defun initialize (condition)
       (let ((object (new-object)))
         (if condition
     	(setcar object condition))
         object))

If `initialize' is interpreted, a new list `(nil)' is constructed each
time `initialize' is called.  Thus, no side effect survives between
calls.  If `initialize' is compiled, then the macro `new-object' is
expanded during compilation, producing a single "constant" `(nil)' that
is reused and altered each time `initialize' is called.

Loading
*******

   Loading a file of Lisp code means bringing its contents into the Lisp
environment in the form of Lisp objects.  Emacs finds and opens the
file, reads the text, evaluates each form, and then closes the file.

   The load functions evaluate all the expressions in a file just as
the `eval-current-buffer' function evaluates all the expressions in a
buffer.  The difference is that the load functions read and evaluate
the text in the file as found on disk, not the text in an Emacs buffer.

   The loaded file must contain Lisp expressions, either as source code
or, optionally, as byte-compiled code.  Each form in the file is called
a "top-level form".  There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there.  (Indeed, most code is tested this
way.)  Most often, the forms are function definitions and variable
definitions.

   A file containing Lisp code is often called a "library".  Thus, the
"Rmail library" is a file containing code for Rmail mode.  Similarly, a
"Lisp library directory" is a directory of files containing Lisp code.

How Programs Do Loading
=======================

   There are several interface functions for loading.  For example, the
`autoload' function creates a Lisp object that loads a file when it is
evaluated (see Autoload.).  `require' also causes files to be
loaded (see Features.).  Ultimately, all these facilities call the
`load' function to do the work.

 - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
     This function finds and opens a file of Lisp code, evaluates all
     the forms in it, and closes the file.

     To find the file, `load' first looks for a file named
     `FILENAME.elc', that is, for a file whose name has `.elc'
     appended.  If such a file exists, it is loaded.  But if there is
     no file by that name, then `load' looks for a file whose name has
     `.el' appended.  If that file exists, it is loaded.  Finally, if
     there is no file by either name, `load' looks for a file named
     FILENAME with nothing appended, and loads it if it exists.  (The
     `load' function is not clever about looking at FILENAME.  In the
     perverse case of a file named `foo.el.el', evaluation of `(load
     "foo.el")' will indeed find it.)

     If the optional argument NOSUFFIX is non-`nil', then the suffixes
     `.elc' and `.el' are not tried.  In this case, you must specify
     the precise file name you want.

     If FILENAME is a relative file name, such as `foo' or
     `baz/foo.bar', `load' searches for the file using the variable
     `load-path'.  It appends FILENAME to each of the directories
     listed in `load-path', and loads the first file it finds whose
     name matches.  The current default directory is tried only if it is
     specified in `load-path', where it is represented as `nil'.  All
     three possible suffixes are tried in the first directory in
     `load-path', then all three in the second directory in
     `load-path', etc.

     If you get a warning that `foo.elc' is older than `foo.el', it
     means you should consider recompiling `foo.el'.  See Byte Compilation.

     Messages like `Loading foo...' and `Loading foo...done' appear in
     the echo area during loading unless NOMESSAGE is non-`nil'.

     Any errors that are encountered while loading a file cause `load'
     to abort.  If the load was done for the sake of `autoload', certain
     kinds of top-level forms, those which define functions, are undone.

     The error `file-error' is signaled (with `Cannot open load file
     FILENAME') if no file is found.  No error is signaled if
     MISSING-OK is non-`nil'--then `load' just returns `nil'.

     `load' returns `t' if the file loads successfully.

 - User Option: load-path
     The value of this variable is a list of directories to search when
     loading files with `load'.  Each element is a string (which must be
     a directory name) or `nil' (which stands for the current working
     directory).  The value of `load-path' is initialized from the
     environment variable `EMACSLOADPATH', if it exists; otherwise it is
     set to the default specified in `emacs/src/paths.h' when Emacs is
     built.

     The syntax of `EMACSLOADPATH' is the same as that of `PATH';
     fields are separated by `:', and `.' is used for the current
     default directory.  Here is an example of how to set your
     `EMACSLOADPATH' variable from a `csh' `.login' file:

          setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp

     Here is how to set it using `sh':

          export EMACSLOADPATH
          EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp

     Here is an example of code you can place in a `.emacs' file to add
     several directories to the front of your default `load-path':

          (setq load-path
                (append
                 (list nil
                       "/user/bil/emacs"
                       "/usr/local/lisplib")
                 load-path))

     In this example, the path searches the current working directory
     first, followed then by the `/user/bil/emacs' directory and then by
     the `/usr/local/lisplib' directory, which are then followed by the
     standard directories for Lisp code.

     When Emacs version 18 processes command options `-l' or `-load'
     which specify Lisp libraries to be loaded, it temporarily adds the
     current directory to the front of `load-path' so that files in the
     current directory can be specified easily.  Newer Emacs versions
     also find such files in the current directory, but without
     altering `load-path'.

 - Variable: load-in-progress
     This variable is non-`nil' if Emacs is in the process of loading a
     file, and it is `nil' otherwise.  This is how `defun' and
     `provide' determine whether a load is in progress, so that their
     effect can be undone if the load fails.

   To learn how `load' is used to build Emacs, see Building Emacs.