Sync with r21-2-35.

[chise/xemacs-chise.git-] / info / lispref.info-11

This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).           XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   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.

\1f
File: lispref.info,  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.

   Byte-compiling a file executes any `require' calls at top-level in
the file.  This is in case the file needs the required packages for
proper compilation.  One way to ensure that necessary macro definitions
are available during compilation is to require the files that define
them (*note Named Features::).  To avoid loading the macro definition
files when someone _runs_ the compiled program, write
`eval-when-compile' around the `require' calls (*note Eval During
Compile::).

\1f
File: lispref.info,  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 functionals 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.

\1f
File: lispref.info,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros

Backquote
=========

   Macros often need to construct large list structures from a mixture
of constants and nonconstant parts.  To make this easier, use the macro
``' (often called "backquote").

   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)
     '(a list of (+ 2 3) elements)
          => (a list of (+ 2 3) elements)

   The special marker `,' inside of the argument to backquote indicates
a value that isn't constant.  Backquote evaluates the argument of `,'
and puts the value in the list structure:

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

   You can also "splice" an evaluated value into the resulting list,
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)
          => (use the words foo bar as elements)

     In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
     version 19.29), ``' used a different syntax which required an
     extra level of parentheses around the entire backquote construct.
     Likewise, each `,' or `,@' substitution required an extra level of
     parentheses surrounding both the `,' or `,@' and the following
     expression.  The old syntax required whitespace between the ``',
     `,' or `,@' and the following expression.

     This syntax is still accepted, but no longer recommended except for
     compatibility with old Emacs versions.

\1f
File: lispref.info,  Node: Problems with Macros,  Prev: Backquote,  Up: Macros

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

   The basic facts of macro expansion have counterintuitive
consequences.  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.

\1f
File: lispref.info,  Node: Argument Evaluation,  Next: Surprising Local Vars,  Up: Problems with Macros

Evaluating Macro Arguments Repeatedly
-------------------------------------

   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.
     For example, (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.)

   Here's an equivalent definition simplified through use of backquote:

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

   Both forms of this definition (with backquote and without) suffer
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.

\1f
File: lispref.info,  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 already 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' that 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.

\1f
File: lispref.info,  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 'c)
     (foo a) ==> (setq a t)
          => t                  ; but this set `a', not `c'.

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

   Another reason not to call `eval' in a macro definition is that it
probably won't do what you intend in a compiled program.  The
byte-compiler runs macro definitions while compiling the program, when
the program's own computations (which you might have wished to access
with `eval') don't occur and its local variable bindings don't exist.

   The safe way to work with the run-time value of an expression is to
put the expression into the macro expansion, so that its value is
computed as part of executing the expansion.

\1f
File: lispref.info,  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 empty-object ()
       (list 'quote (cons nil nil)))
     
     (defun initialize (condition)
       (let ((object (empty-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 `empty-object' is
expanded during compilation, producing a single "constant" `(nil)' that
is reused and altered each time `initialize' is called.

   One way to avoid pathological cases like this is to think of
`empty-object' as a funny kind of constant, not as a memory allocation
construct.  You wouldn't use `setcar' on a constant such as `'(nil)',
so naturally you won't use it on `(empty-object)' either.

\1f
File: lispref.info,  Node: Customization,  Up: Top

Writing Customization Definitions
*********************************

   This chapter describes how to declare user options for customization,
and also customization groups for classifying them.  We use the term
"customization item" to include both kinds of customization
definitions--as well as face definitions.

* Menu:

* Common Keywords::
* Group Definitions::
* Variable Definitions::
* Customization Types::

\1f
File: lispref.info,  Node: Common Keywords,  Next: Group Definitions,  Up: Customization

Common Keywords for All Kinds of Items
======================================

   All kinds of customization declarations (for variables and groups,
and for faces) accept keyword arguments for specifying various
information.  This section describes some keywords that apply to all
kinds.

   All of these keywords, except `:tag', can be used more than once in
a given item.  Each use of the keyword has an independent effect.  The
keyword `:tag' is an exception because any given item can only display
one name.

`:tag NAME'
     Use NAME, a string, instead of the item's name, to label the item
     in customization menus and buffers.

`:group GROUP'
     Put this customization item in group GROUP.  When you use `:group'
     in a `defgroup', it makes the new group a subgroup of GROUP.

     If you use this keyword more than once, you can put a single item
     into more than one group.  Displaying any of those groups will
     show this item.  Be careful not to overdo this!

`:link LINK-DATA'
     Include an external link after the documentation string for this
     item.  This is a sentence containing an active field which
     references some other documentation.

     There are three alternatives you can use for LINK-DATA:

    `(custom-manual INFO-NODE)'
          Link to an Info node; INFO-NODE is a string which specifies
          the node name, as in `"(emacs)Top"'.  The link appears as
          `[manual]' in the customization buffer.

    `(info-link INFO-NODE)'
          Like `custom-manual' except that the link appears in the
          customization buffer with the Info node name.

    `(url-link URL)'
          Link to a web page; URL is a string which specifies the URL.
          The link appears in the customization buffer as URL.

     You can specify the text to use in the customization buffer by
     adding `:tag NAME' after the first element of the LINK-DATA; for
     example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
     Emacs manual which appears in the buffer as `foo'.

     An item can have more than one external link; however, most items
     have none at all.

`:load FILE'
     Load file FILE (a string) before displaying this customization
     item.  Loading is done with `load-library', and only if the file is
     not already loaded.

`:require FEATURE'
     Require feature FEATURE (a symbol) when installing a value for
     this item (an option or a face) that was saved using the
     customization feature.  This is done by calling `require'.

     The most common reason to use `:require' is when a variable enables
     a feature such as a minor mode, and just setting the variable
     won't have any effect unless the code which implements the mode is
     loaded.

\1f
File: lispref.info,  Node: Group Definitions,  Next: Variable Definitions,  Prev: Common Keywords,  Up: Customization

Defining Custom Groups
======================

   Each Emacs Lisp package should have one main customization group
which contains all the options, faces and other groups in the package.
If the package has a small number of options and faces, use just one
group and put everything in it.  When there are more than twelve or so
options and faces, then you should structure them into subgroups, and
put the subgroups under the package's main customization group.  It is
OK to put some of the options and faces in the package's main group
alongside the subgroups.

   The package's main or only group should be a member of one or more of
the standard customization groups.  (To display the full list of them,
use `M-x customize'.)  Choose one or more of them (but not too many),
and add your group to each of them using the `:group' keyword.

   The way to declare new customization groups is with `defgroup'.

 - Macro: defgroup group members doc [keyword value]...
     Declare GROUP as a customization group containing MEMBERS.  Do not
     quote the symbol GROUP.  The argument DOC specifies the
     documentation string for the group.

     The argument MEMBERS is a list specifying an initial set of
     customization items to be members of the group.  However, most
     often MEMBERS is `nil', and you specify the group's members by
     using the `:group' keyword when defining those members.

     If you want to specify group members through MEMBERS, each element
     should have the form `(NAME WIDGET)'.  Here NAME is a symbol, and
     WIDGET is a widget type for editing that symbol.  Useful widgets
     are `custom-variable' for a variable, `custom-face' for a face,
     and `custom-group' for a group.

     In addition to the common keywords (*note Common Keywords::), you
     can use this keyword in `defgroup':

    `:prefix PREFIX'
          If the name of an item in the group starts with PREFIX, then
          the tag for that item is constructed (by default) by omitting
          PREFIX.

          One group can have any number of prefixes.

\1f
File: lispref.info,  Node: Variable Definitions,  Next: Customization Types,  Prev: Group Definitions,  Up: Customization

Defining Customization Variables
================================

   Use `defcustom' to declare user-editable variables.

 - Macro: defcustom option default doc [keyword value]...
     Declare OPTION as a customizable user option variable.  Do not
     quote OPTION.  The argument DOC specifies the documentation string
     for the variable.

     If OPTION is void, `defcustom' initializes it to DEFAULT.  DEFAULT
     should be an expression to compute the value; be careful in
     writing it, because it can be evaluated on more than one occasion.

     The following additional keywords are defined:

    `:type TYPE'
          Use TYPE as the data type for this option.  It specifies which
          values are legitimate, and how to display the value.  *Note
          Customization Types::, for more information.

    `:options LIST'
          Specify LIST as the list of reasonable values for use in this
          option.

          Currently this is meaningful only when the type is `hook'.
          In that case, the elements of LIST should be functions that
          are useful as elements of the hook value.  The user is not
          restricted to using only these functions, but they are
          offered as convenient alternatives.

    `:version VERSION'
          This option specifies that the variable was first introduced,
          or its default value was changed, in Emacs version VERSION.
          The value VERSION must be a string.  For example,

               (defcustom foo-max 34
                 "*Maximum number of foo's allowed."
                 :type 'integer
                 :group 'foo
                 :version "20.3")

    `:set SETFUNCTION'
          Specify SETFUNCTION as the way to change the value of this
          option.  The function SETFUNCTION should take two arguments,
          a symbol and the new value, and should do whatever is
          necessary to update the value properly for this option (which
          may not mean simply setting the option as a Lisp variable).
          The default for SETFUNCTION is `set-default'.

    `:get GETFUNCTION'
          Specify GETFUNCTION as the way to extract the value of this
          option.  The function GETFUNCTION should take one argument, a
          symbol, and should return the "current value" for that symbol
          (which need not be the symbol's Lisp value).  The default is
          `default-value'.

    `:initialize FUNCTION'
          FUNCTION should be a function used to initialize the variable
          when the `defcustom' is evaluated.  It should take two
          arguments, the symbol and value.  Here are some predefined
          functions meant for use in this way:

         `custom-initialize-set'
               Use the variable's `:set' function to initialize the
               variable, but do not reinitialize it if it is already
               non-void.  This is the default `:initialize' function.

         `custom-initialize-default'
               Like `custom-initialize-set', but use the function
               `set-default' to set the variable, instead of the
               variable's `:set' function.  This is the usual choice
               for a variable whose `:set' function enables or disables
               a minor mode; with this choice, defining the variable
               will not call the minor mode function, but customizing
               the variable will do so.

         `custom-initialize-reset'
               Always use the `:set' function to initialize the
               variable.  If the variable is already non-void, reset it
               by calling the `:set' function using the current value
               (returned by the `:get' method).

         `custom-initialize-changed'
               Use the `:set' function to initialize the variable, if
               it is already set or has been customized; otherwise,
               just use `set-default'.

   The `:require' option is useful for an option that turns on the
operation of a certain feature.  Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
to be loaded.  You can do that with `:require'.  *Note Common
Keywords::.  Here is an example, from the library `paren.el':

     (defcustom show-paren-mode nil
       "Toggle Show Paren mode...."
       :set (lambda (symbol value)
              (show-paren-mode (or value 0)))
       :initialize 'custom-initialize-default
       :type 'boolean
       :group 'paren-showing
       :require 'paren)

   Internally, `defcustom' uses the symbol property `standard-value' to
record the expression for the default value, and `saved-value' to
record the value saved by the user with the customization buffer.  The
`saved-value' property is actually a list whose car is an expression
which evaluates to the value.

\1f
File: lispref.info,  Node: Customization Types,  Prev: Variable Definitions,  Up: Customization

Customization Types
===================

   When you define a user option with `defcustom', you must specify its
"customization type".  That is a Lisp object which describes (1) which
values are legitimate and (2) how to display the value in the
customization buffer for editing.

   You specify the customization type in `defcustom' with the `:type'
keyword.  The argument of `:type' is evaluated; since types that vary
at run time are rarely useful, normally you use a quoted constant.  For
example:

     (defcustom diff-command "diff"
       "*The command to use to run diff."
       :type '(string)
       :group 'diff)

   In general, a customization type is a list whose first element is a
symbol, one of the customization type names defined in the following
sections.  After this symbol come a number of arguments, depending on
the symbol.  Between the type symbol and its arguments, you can
optionally write keyword-value pairs (*note Type Keywords::).

   Some of the type symbols do not use any arguments; those are called
"simple types".  For a simple type, if you do not use any keyword-value
pairs, you can omit the parentheses around the type symbol.  For
example just `string' as a customization type is equivalent to
`(string)'.

* Menu:

* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::

\1f
File: lispref.info,  Node: Simple Types,  Next: Composite Types,  Up: Customization Types

Simple Types
------------

   This section describes all the simple customization types.

`sexp'
     The value may be any Lisp object that can be printed and read
     back.  You can use `sexp' as a fall-back for any option, if you
     don't want to take the time to work out a more specific type to
     use.

`integer'
     The value must be an integer, and is represented textually in the
     customization buffer.

`number'
     The value must be a number, and is represented textually in the
     customization buffer.

`string'
     The value must be a string, and the customization buffer shows
     just the contents, with no delimiting `"' characters and no
     quoting with `\'.

`regexp'
     Like `string' except that the string must be a valid regular
     expression.

`character'
     The value must be a character code.  A character code is actually
     an integer, but this type shows the value by inserting the
     character in the buffer, rather than by showing the number.

`file'
     The value must be a file name, and you can do completion with
     `M-<TAB>'.

`(file :must-match t)'
     The value must be a file name for an existing file, and you can do
     completion with `M-<TAB>'.

`directory'
     The value must be a directory name, and you can do completion with
     `M-<TAB>'.

`symbol'
     The value must be a symbol.  It appears in the customization
     buffer as the name of the symbol.

`function'
     The value must be either a lambda expression or a function name.
     When it is a function name, you can do completion with `M-<TAB>'.

`variable'
     The value must be a variable name, and you can do completion with
     `M-<TAB>'.

`face'
     The value must be a symbol which is a face name.

`boolean'
     The value is boolean--either `nil' or `t'.  Note that by using
     `choice' and `const' together (see the next section), you can
     specify that the value must be `nil' or `t', but also specify the
     text to describe each value in a way that fits the specific
     meaning of the alternative.

\1f
File: lispref.info,  Node: Composite Types,  Next: Splicing into Lists,  Prev: Simple Types,  Up: Customization Types

Composite Types
---------------

   When none of the simple types is appropriate, you can use composite
types, which build new types from other types.  Here are several ways of
doing that:

`(restricted-sexp :match-alternatives CRITERIA)'
     The value may be any Lisp object that satisfies one of CRITERIA.
     CRITERIA should be a list, and each elements should be one of
     these possibilities:

        * A predicate--that is, a function of one argument that returns
          non-`nil' if the argument fits a certain type.  This means
          that objects of that type are acceptable.

        * A quoted constant--that is, `'OBJECT'.  This means that
          OBJECT itself is an acceptable value.

     For example,

          (restricted-sexp :match-alternatives (integerp 't 'nil))

     allows integers, `t' and `nil' as legitimate values.

     The customization buffer shows all legitimate values using their
     read syntax, and the user edits them textually.

`(cons CAR-TYPE CDR-TYPE)'
     The value must be a cons cell, its CAR must fit CAR-TYPE, and its
     CDR must fit CDR-TYPE.  For example, `(cons string symbol)' is a
     customization type which matches values such as `("foo" . foo)'.

     In the customization buffer, the CAR and the CDR are displayed and
     edited separately, each according to the type that you specify for
     it.

`(list ELEMENT-TYPES...)'
     The value must be a list with exactly as many elements as the
     ELEMENT-TYPES you have specified; and each element must fit the
     corresponding ELEMENT-TYPE.

     For example, `(list integer string function)' describes a list of
     three elements; the first element must be an integer, the second a
     string, and the third a function.

     In the customization buffer, the each element is displayed and
     edited separately, according to the type specified for it.

`(vector ELEMENT-TYPES...)'
     Like `list' except that the value must be a vector instead of a
     list.  The elements work the same as in `list'.

`(choice ALTERNATIVE-TYPES...)'
     The value must fit at least one of ALTERNATIVE-TYPES.  For
     example, `(choice integer string)' allows either an integer or a
     string.

     In the customization buffer, the user selects one of the
     alternatives using a menu, and can then edit the value in the
     usual way for that alternative.

     Normally the strings in this menu are determined automatically
     from the choices; however, you can specify different strings for
     the menu by including the `:tag' keyword in the alternatives.  For
     example, if an integer stands for a number of spaces, while a
     string is text to use verbatim, you might write the customization
     type this way,

          (choice (integer :tag "Number of spaces")
                  (string :tag "Literal text"))

     so that the menu offers `Number of spaces' and `Literal Text'.

     In any alternative for which `nil' is not a valid value, other than
     a `const', you should specify a valid default for that alternative
     using the `:value' keyword.  *Note Type Keywords::.

`(const VALUE)'
     The value must be VALUE--nothing else is allowed.

     The main use of `const' is inside of `choice'.  For example,
     `(choice integer (const nil))' allows either an integer or `nil'.

     `:tag' is often used with `const', inside of `choice'.  For
     example,

          (choice (const :tag "Yes" t)
                  (const :tag "No" nil)
                  (const :tag "Ask" foo))

`(function-item FUNCTION)'
     Like `const', but used for values which are functions.  This
     displays the documentation string as well as the function name.
     The documentation string is either the one you specify with
     `:doc', or FUNCTION's own documentation string.

`(variable-item VARIABLE)'
     Like `const', but used for values which are variable names.  This
     displays the documentation string as well as the variable name.
     The documentation string is either the one you specify with
     `:doc', or VARIABLE's own documentation string.

`(set ELEMENTS...)'
     The value must be a list and each element of the list must be one
     of the ELEMENTS specified.  This appears in the customization
     buffer as a checklist.

`(repeat ELEMENT-TYPE)'
     The value must be a list and each element of the list must fit the
     type ELEMENT-TYPE.  This appears in the customization buffer as a
     list of elements, with `[INS]' and `[DEL]' buttons for adding more
     elements or removing elements.

\1f
File: lispref.info,  Node: Splicing into Lists,  Next: Type Keywords,  Prev: Composite Types,  Up: Customization Types

Splicing into Lists
-------------------

   The `:inline' feature lets you splice a variable number of elements
into the middle of a list or vector.  You use it in a `set', `choice'
or `repeat' type which appears among the element-types of a `list' or
`vector'.

   Normally, each of the element-types in a `list' or `vector'
describes one and only one element of the list or vector.  Thus, if an
element-type is a `repeat', that specifies a list of unspecified length
which appears as one element.

   But when the element-type uses `:inline', the value it matches is
merged directly into the containing sequence.  For example, if it
matches a list with three elements, those become three elements of the
overall sequence.  This is analogous to using `,@' in the backquote
construct.

   For example, to specify a list whose first element must be `t' and
whose remaining arguments should be zero or more of `foo' and `bar',
use this customization type:

     (list (const t) (set :inline t foo bar))

This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
bar)'.

   When the element-type is a `choice', you use `:inline' not in the
`choice' itself, but in (some of) the alternatives of the `choice'.
For example, to match a list which must start with a file name,
followed either by the symbol `t' or two strings, use this
customization type:

     (list file
           (choice (const t)
                   (list :inline t string string)))

If the user chooses the first alternative in the choice, then the
overall list has two elements and the second element is `t'.  If the
user chooses the second alternative, then the overall list has three
elements and the second and third must be strings.

\1f
File: lispref.info,  Node: Type Keywords,  Prev: Splicing into Lists,  Up: Customization Types

Type Keywords
-------------

   You can specify keyword-argument pairs in a customization type after
the type name symbol.  Here are the keywords you can use, and their
meanings:

`:value DEFAULT'
     This is used for a type that appears as an alternative inside of
     `choice'; it specifies the default value to use, at first, if and
     when the user selects this alternative with the menu in the
     customization buffer.

     Of course, if the actual value of the option fits this
     alternative, it will appear showing the actual value, not DEFAULT.

     If `nil' is not a valid value for the alternative, then it is
     essential to specify a valid default with `:value'.

`:format FORMAT-STRING'
     This string will be inserted in the buffer to represent the value
     corresponding to the type.  The following `%' escapes are available
     for use in FORMAT-STRING:

    `%[BUTTON%]'
          Display the text BUTTON marked as a button.  The `:action'
          attribute specifies what the button will do if the user
          invokes it; its value is a function which takes two
          arguments--the widget which the button appears in, and the
          event.

          There is no way to specify two different buttons with
          different actions.

    `%{SAMPLE%}'
          Show SAMPLE in a special face specified by `:sample-face'.

    `%v'
          Substitute the item's value.  How the value is represented
          depends on the kind of item, and (for variables) on the
          customization type.

    `%d'
          Substitute the item's documentation string.

    `%h'
          Like `%d', but if the documentation string is more than one
          line, add an active field to control whether to show all of
          it or just the first line.

    `%t'
          Substitute the tag here.  You specify the tag with the `:tag'
          keyword.

    `%%'
          Display a literal `%'.

`:action ACTION'
     Perform ACTION if the user clicks on a button.

`:button-face FACE'
     Use the face FACE (a face name or a list of face names) for button
     text displayed with `%[...%]'.

`:button-prefix PREFIX'
`:button-suffix SUFFIX'
     These specify the text to display before and after a button.  Each
     can be:

    `nil'
          No text is inserted.

    a string
          The string is inserted literally.

    a symbol
          The symbol's value is used.

`:tag TAG'
     Use TAG (a string) as the tag for the value (or part of the value)
     that corresponds to this type.

`:doc DOC'
     Use DOC as the documentation string for this value (or part of the
     value) that corresponds to this type.  In order for this to work,
     you must specify a value for `:format', and use `%d' or `%h' in
     that value.

     The usual reason to specify a documentation string for a type is to
     provide more information about the meanings of alternatives inside
     a `:choice' type or the parts of some other composite type.

`:help-echo MOTION-DOC'
     When you move to this item with `widget-forward' or
     `widget-backward', it will display the string MOTION-DOC in the
     echo area.

`:match FUNCTION'
     Specify how to decide whether a value matches the type.  The
     corresponding value, FUNCTION, should be a function that accepts
     two arguments, a widget and a value; it should return non-`nil' if
     the value is acceptable.

\1f
File: lispref.info,  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.  XEmacs 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 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.
* Named 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.

\1f
File: lispref.info,  Node: How Programs Do Loading,  Next: Autoload,  Up: Loading

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

   XEmacs Lisp has several interfaces for loading.  For example,
`autoload' creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
function's real definition (*note Autoload::).  `require' loads a file
if it isn't already loaded (*note Named 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 is FILENAME with
     `.elc' appended.  If such a file exists, it is loaded.  If there
     is no file by that name, then `load' looks for a file named
     `FILENAME.el'.  If that file exists, it is loaded.  Finally, if
     neither of those names is found, `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 `nil' stands for the default
     directory.  `load' tries all three possible suffixes in the first
     directory in `load-path', then all three suffixes in the second
     directory, and so on.

     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 unhandled errors while loading a file terminate loading.  If
     the load was done for the sake of `autoload', any function
     definitions made during the loading are undone.

     If `load' can't find the file to load, then normally it signals the
     error `file-error' (with `Cannot open load file FILENAME').  But
     if MISSING-OK is non-`nil', then `load' just returns `nil'.

     You can use the variable `load-read-function' to specify a function
     for `load' to use instead of `read' for reading expressions.  See
     below.

     `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 that exists; otherwise its
     default value is specified in `emacs/src/paths.h' when XEmacs is
     built.

     The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
     (or `;', according to the operating system) separates directory
     names, 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"
                              "~/emacs")
                        load-path))

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

     The command line options `-l' or `-load' specify a Lisp library to
     load as part of Emacs startup.  Since this file might be in the
     current directory, Emacs 18 temporarily adds the current directory
     to the front of `load-path' so the file can be found there.  Newer
     Emacs versions also find such files in the current directory, but
     without altering `load-path'.

     Dumping Emacs uses a special value of `load-path'.  If the value of
     `load-path' at the end of dumping is unchanged (that is, still the
     same special value), the dumped Emacs switches to the ordinary
     `load-path' value when it starts up, as described above.  But if
     `load-path' has any other value at the end of dumping, that value
     is used for execution of the dumped Emacs also.

     Therefore, if you want to change `load-path' temporarily for
     loading a few libraries in `site-init.el' or `site-load.el', you
     should bind `load-path' locally with `let' around the calls to
     `load'.

 - Function: locate-file filename path-list &optional suffixes mode
     This function searches for a file in the same way that `load' does,
     and returns the file found (if any). (In fact, `load' uses this
     function to search through `load-path'.) It searches for FILENAME
     through PATH-LIST, expanded by one of the optional SUFFIXES
     (string of suffixes separated by `:'s), checking for access MODE
     (0|1|2|4 = exists|executable|writable|readable), default readable.

     `locate-file' keeps hash tables of the directories it searches
     through, in order to speed things up.  It tries valiantly to not
     get confused in the face of a changing and unpredictable
     environment, but can occasionally get tripped up.  In this case,
     you will have to call `locate-file-clear-hashing' to get it back
     on track.  See that function for details.

 - Function: locate-file-clear-hashing path
     This function clears the hash records for the specified list of
     directories.  `locate-file' uses a hashing scheme to speed lookup,
     and will correctly track the following environmental changes:

        * changes of any sort to the list of directories to be searched.

        * addition and deletion of non-shadowing files (see below) from
          the directories in the list.

        * byte-compilation of a .el file into a .elc file.

     `locate-file' will primarily get confused if you add a file that
     shadows (i.e. has the same name as) another file further down in
     the directory list.  In this case, you must call
     `locate-file-clear-hashing'.

 - Variable: load-in-progress
     This variable is non-`nil' if Emacs is in the process of loading a
     file, and it is `nil' otherwise.

 - Variable: load-read-function
     This variable specifies an alternate expression-reading function
     for `load' and `eval-region' to use instead of `read'.  The
     function should accept one argument, just as `read' does.

     Normally, the variable's value is `nil', which means those
     functions should use `read'.

 - User Option: load-warn-when-source-newer
     This variable specifies whether `load' should check whether the
     source is newer than the binary.  If this variable is true, then
     when a `.elc' file is being loaded and the corresponding `.el' is
     newer, a warning message will be printed.  The default is `nil',
     but it is bound to `t' during the initial loadup.

 - User Option: load-warn-when-source-only
     This variable specifies whether `load' should warn when loading a
     `.el' file instead of an `.elc'.  If this variable is true, then
     when `load' is called with a filename without an extension, and
     the `.elc' version doesn't exist but the `.el' version does, then
     a message will be printed.  If an explicit extension is passed to
     `load', no warning will be printed.  The default is `nil', but it
     is bound to `t' during the initial loadup.

 - User Option: load-ignore-elc-files
     This variable specifies whether `load' should ignore `.elc' files
     when a suffix is not given.  This is normally used only to
     bootstrap the `.elc' files when building XEmacs, when you use the
     command `make all-elc'. (This forces the `.el' versions to be
     loaded in the process of compiling those same files, so that
     existing out-of-date `.elc' files do not make it mess things up.)

   To learn how `load' is used to build XEmacs, see *Note Building
XEmacs::.