InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/gnu/elisp/elisp-9

GNU Info File | 1993-05-31 | 49.3 KB | 1,263 lines

This is Info file elisp, produced by Makeinfo-1.55 from the input file
elisp.texi.

   This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 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.


File: elisp,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Defining Functions,  Up: Functions

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'.  *Note 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'.


File: elisp,  Node: Mapping Functions,  Next: Anonymous Functions,  Prev: Calling Functions,  Up: Functions

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 *Note 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"


File: elisp,  Node: Anonymous Functions,  Next: Function Cells,  Prev: Mapping Functions,  Up: Functions

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.  *Note 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 *Note Accessing Documentation::, for a
realistic example using `function' and an anonymous function.


File: elisp,  Node: Function Cells,  Next: Inline Functions,  Prev: Anonymous Functions,  Up: Functions

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 *Note 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'.  *Note 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 *Note Function
Indirection::.


File: elisp,  Node: Inline Functions,  Next: Related Topics,  Prev: Function Cells,  Up: Functions

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.

   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.  (*Note 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.


File: elisp,  Node: Related Topics,  Prev: Inline Functions,  Up: 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 *Note Calling Functions::.

`autoload'
     See *Note Autoload::.

`call-interactively'
     See *Note Interactive Call::.

`commandp'
     See *Note Interactive Call::.

`documentation'
     See *Note Accessing Documentation::.

`eval'
     See *Note Eval::.

`funcall'
     See *Note Calling Functions::.

`ignore'
     See *Note Calling Functions::.

`indirect-function'
     See *Note Function Indirection::.

`interactive'
     See *Note Using Interactive::.

`interactive-p'
     See *Note Interactive Call::.

`mapatoms'
     See *Note Creating Symbols::.

`mapcar'
     See *Note Mapping Functions::.

`mapconcat'
     See *Note Mapping Functions::.

`undefined'
     See *Note Key Lookup::.


File: elisp,  Node: Macros,  Next: Loading,  Prev: Functions,  Up: Top

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.  *Note Inline Functions::.

* Menu:

* Simple Macro::            A basic example.
* Expansion::               How, when and why macros are expanded.
* Compiling Macros::        How macros are expanded by the compiler.
* Defining Macros::         How to write a macro definition.
* Backquote::               Easier construction of list structure.
* Problems with Macros::    Don't evaluate the macro arguments too many times.
                              Don't hide the user's variables.


File: elisp,  Node: Simple Macro,  Next: Expansion,  Prev: Macros,  Up: Macros

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'.


File: elisp,  Node: Expansion,  Next: Compiling Macros,  Prev: Simple Macro,  Up: Macros

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.


File: elisp,  Node: Compiling Macros,  Next: Defining Macros,  Prev: Expansion,  Up: Macros

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.
*Note Features::.


File: elisp,  Node: Defining Macros,  Next: Backquote,  Prev: Compiling Macros,  Up: Macros

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
     (*note Argument List::.).  Macros may have a documentation string,
     but any `interactive' declaration is ignored since macros cannot be
     called interactively.


File: elisp,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros

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' (*note 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).


File: elisp,  Node: Problems with Macros,  Prev: Backquote,  Up: Macros

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.

* Menu:

* Argument Evaluation::    The expansion should evaluate each macro arg once.
* Surprising Local Vars::  Local variable bindings in the expansion
                              require special care.
* Eval During Expansion::  Don't evaluate them; put them in the expansion.
* Repeated Expansion::     Avoid depending on how many times expansion is done.


File: elisp,  Node: Argument Evaluation,  Next: Surprising Local Vars,  Prev: Problems with Macros,  Up: Problems with Macros

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.


File: elisp,  Node: Surprising Local Vars,  Next: Eval During Expansion,  Prev: Argument Evaluation,  Up: Problems with Macros

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' (*note 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.


File: elisp,  Node: Eval During Expansion,  Next: Repeated Expansion,  Prev: Surprising Local Vars,  Up: Problems with Macros

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' (*note 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.


File: elisp,  Node: Repeated Expansion,  Prev: Eval During Expansion,  Up: Problems with Macros

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.


File: elisp,  Node: Loading,  Next: Byte Compilation,  Prev: Macros,  Up: Top

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.

* Menu:

* How Programs Do Loading::     The `load' function and others.
* Autoload::                    Setting up a function to autoload.
* Repeated Loading::            Precautions about loading a file twice.
* Features::                    Loading a library if it isn't already loaded.
* Unloading::            How to "unload" a library that was loaded.
* Hooks for Loading::        Providing code to be run when
                  particular libraries are loaded.


File: elisp,  Node: How Programs Do Loading,  Next: Autoload,  Up: Loading

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 (*note Autoload::.).  `require' also causes files to be
loaded (*note 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'.  *Note 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/local/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 *Note Building
Emacs::.


File: elisp,  Node: Autoload,  Next: Repeated Loading,  Prev: How Programs Do Loading,  Up: Loading

Autoload
========

   The "autoload" facility allows you to make a function or macro
available but put off loading its actual definition.  An attempt to call
a symbol whose definition is an autoload object automatically reads the
file to install the real definition and its other associated code, and
then calls the real definition.

   To prepare a function or macro for autoloading, you must call
`autoload', specifying the function name and the name of the file to be
loaded.  A file such as `emacs/lisp/loaddefs.el' usually does this when
Emacs is first built.

   The following example shows how `doctor' is prepared for autoloading
in `loaddefs.el':

     (autoload 'doctor "doctor"
       "\
     Switch to *doctor* buffer and start giving psychotherapy."
       t)

The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as `loaddefs.el';
they cause the documentation string to be put in the `etc/DOC' file.
(*Note Building Emacs::.)  In any other source file, you would write
just this:

     (autoload 'doctor "doctor"
       "Switch to *doctor* buffer and start giving psychotherapy."
       t)

   Calling `autoload' creates an autoload object containing the name of
the file and some other information, and makes this the function
definition of the specified symbol.  When you later try to call that
symbol as a function or macro, the file is loaded; the loading should
redefine that symbol with its proper definition.  After the file
completes loading, the function or macro is called as if it had been
there originally.

   If, at the end of loading the file, the desired Lisp function or
macro has not been defined, then the error `error' is signaled (with
data `"Autoloading failed to define function FUNCTION-NAME"').

   The autoloaded file may, of course, contain other definitions and may
require or provide one or more features.  If the file is not completely
loaded (due to an error in the evaluation of the contents) any function
definitions or `provide' calls that occurred during the load are
undone.  This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file.  If not for
this, then some of the functions in the file might appear defined, but
they may fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.

   Emacs as distributed comes with many autoloaded functions.  The
calls to `autoload' are in the file `loaddefs.el'.  There is a
convenient way of updating them automatically.

   Write `;;;###autoload' on a line by itself before a function
definition before the real definition of the function, in its
autoloadable source file; then the command `M-x update-file-autoloads'
automatically puts the `autoload' call into `loaddefs.el'.  `M-x
update-directory-autoloads' is more powerful; it updates autoloads for
all files in the current directory.

   You can also put other kinds of forms into `loaddefs.el', by writing
`;;;###autoload' followed on the same line by the form.  `M-x
update-file-autoloads' copies the form from that line.

   The commands for updating autoloads work by visiting and editing the
file `loaddefs.el'.  To make the result take effect, you must save that
file's buffer.

 - Function: autoload SYMBOL FILENAME &optional DOCSTRING INTERACTIVE
          TYPE
     This function defines the function (or macro) named SYMBOL so as
     to load automatically from FILENAME.  The string FILENAME is a
     file name which will be passed to `load' when the function is
     called.

     The argument DOCSTRING is the documentation string for the
     function.  Normally, this is the same string that is in the
     function definition itself.  This makes it possible to look at the
     documentation without loading the real definition.

     If INTERACTIVE is non-`nil', then the function can be called
     interactively.  This lets completion in `M-x' work without loading
     the function's real definition.  The complete interactive
     specification need not be given here.  If TYPE is `macro', then
     the function is really a macro.  If TYPE is `keymap', then the
     function is really a keymap.

     If SYMBOL already has a non-`nil' function definition that is not
     an autoload object, `autoload' does nothing and returns `nil'.  If
     the function cell of SYMBOL is void, or is already an autoload
     object, then it is set to an autoload object that looks like this:

          (autoload FILENAME DOCSTRING INTERACTIVE TYPE)

     For example,

          (symbol-function 'run-prolog)
               => (autoload "prolog" 169681 t nil)

     In this case, `"prolog"' is the name of the file to load, 169681
     refers to the documentation string in the `emacs/etc/DOC' file
     (*note Documentation Basics::.), `t' means the function is
     interactive, and `nil' that it is not a macro.


File: elisp,  Node: Repeated Loading,  Next: Features,  Prev: Autoload,  Up: Loading

Repeated Loading
================

   You may load a file more than once in an Emacs session.  For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file in which it is located.

   When you load or reload files, bear in mind that the `load' and
`load-library' functions automatically load a byte-compiled file rather
than a non-compiled file of similar name.  If you rewrite a file that
you intend to save and reinstall, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!

   When writing the forms in a library, keep in mind that the library
might be loaded more than once.  For example, the choice of `defvar'
vs. `defconst' for defining a variable depends on whether it is
desirable to reinitialize the variable if the library is reloaded:
`defconst' does so, and `defvar' does not.  (*Note Defining
Variables::.)

   The simplest way to add an element to an alist is like this:

     (setq minor-mode-alist
           (cons '(leif-mode " Leif") minor-mode-alist))

But this would add multiple elements if the library is reloaded.  To
avoid the problem, write this:

     (or (assq 'leif-mode minor-mode-alist)
         (setq minor-mode-alist
               (cons '(leif-mode " Leif") minor-mode-alist)))

   Occasionally you will want to test explicitly whether a library has
already been loaded; you can do so as follows:

     (if (not (boundp 'foo-was-loaded))
         EXECUTE-FIRST-TIME-ONLY)

     (setq foo-was-loaded t)