@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
containing Lisp code.
@menu
-* How Programs Do Loading:: The @code{load} function and others.
-* Library Search:: Finding a library to load.
-* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
-* 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.
+* How Programs Do Loading:: The @code{load} function and others.
+* Library Search:: Finding a library to load.
+* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
+* 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.
+* Where Defined:: Finding which file defined a certain symbol.
+* Unloading:: How to ``unload'' a library that was loaded.
+* Hooks for Loading:: Providing code to be run when
+ particular libraries are loaded.
@end menu
@node How Programs Do Loading
file, and it is @code{nil} otherwise.
@end defvar
-@anchor{Definition of load-read-function}
@defvar load-read-function
+@anchor{Definition of load-read-function}
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
just @var{filename} with no added suffix.
The argument @var{docstring} is the documentation string for the
-function. Normally, this should be identical to the documentation string
-in the function definition itself. Specifying the documentation string
-in the call to @code{autoload} makes it possible to look at the
-documentation without loading the function's real definition.
+function. Specifying the documentation string in the call to
+@code{autoload} makes it possible to look at the documentation without
+loading the function's real definition. Normally, this should be
+identical to the documentation string in the function definition
+itself. If it isn't, the function definition's documentation string
+takes effect when it is loaded.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment consists of @samp{;;;###autoload}, on a line
-by itself, just before the real definition of the function in its
+@cindex magic autoload comment
+@cindex autoload cookie
+@anchor{autoload cookie}
+ A magic autoload comment (often called an @dfn{autoload cookie})
+consists of @samp{;;;###autoload}, on a line by itself,
+just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
The simplest way to add an element to an alist is like this:
@example
-(setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist))
+(push '(leif-mode " Leif") minor-mode-alist)
@end example
@noindent
@example
(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+ (push '(leif-mode " Leif") minor-mode-alist))
@end example
- To add an element to a list just once, you can also use @code{add-to-list}
-(@pxref{Setting Variables}).
+@noindent
+or this:
+
+@example
+(add-to-list '(leif-mode " Leif") minor-mode-alist)
+@end example
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
with an added suffix; a file whose name is just @var{feature} won't be
used.
-If loading the file fails to provide @var{feature}, @code{require}
-signals an error, @samp{Required feature @var{feature} was not
-provided}, unless @var{noerror} is non-@code{nil}.
+If @var{noerror} is non-@code{nil}, that suppresses errors from actual
+loading of the file. In that case, @code{require} returns @code{nil}
+if loading the file fails. Normally, @code{require} returns
+@var{feature}.
+
+If loading the file succeeds but does not provide @var{feature},
+@code{require} signals an error, @samp{Required feature @var{feature}
+was not provided}.
@end defun
@defun featurep feature &optional subfeature
@code{features} list is not significant.
@end defvar
+@node Where Defined
+@section Which File Defined a Certain Symbol
+
+@defun symbol-file symbol &optional type
+This function returns the name of the file that defined @var{symbol}.
+If @var{type} is @code{nil}, then any kind of definition is
+acceptable. If @var{type} is @code{defun} or @code{defvar}, that
+specifies function definition only or variable definition only.
+
+The value is the file name as it was specified to @code{load}:
+either an absolute file name, or a library name
+(with no directory name and no @samp{.el} or @samp{.elc} at the end).
+It can also be @code{nil}, if the definition is not associated with any file.
+@end defun
+
+ The basis for @code{symbol-file} is the data in the variable
+@code{load-history}.
+
+@defvar load-history
+This variable's value is an alist connecting library names with the
+names of functions and variables they define, the features they provide,
+and the features they require.
+
+Each element is a list and describes one library. The @sc{car} of the
+list is the name of the library, as a string. The rest of the list
+elements have these forms:
+
+@table @code
+@item @var{var}
+The symbol @var{var} was defined as a variable.
+@item (defun . @var{fun})
+The function @var{fun} was defined.
+@item (t . @var{fun})
+The function @var{fun} was previously an autoload before this library
+redefined it as a function. The following element is always
+@code{(defun . @var{fun})}, which represents defining @var{fun} as a
+function.
+@item (autoload . @var{fun})
+The function @var{fun} was defined as an autoload.
+@item (require . @var{feature})
+The feature @var{feature} was required.
+@item (provide . @var{feature})
+The feature @var{feature} was provided.
+@end table
+
+The value of @code{load-history} may have one element whose @sc{car} is
+@code{nil}. This element describes definitions made with
+@code{eval-buffer} on a buffer that is not visiting a file.
+@end defvar
+
+ The command @code{eval-region} updates @code{load-history}, but does so
+by adding the symbols defined to the element for the file being visited,
+rather than replacing that element. @xref{Eval}.
+
@node Unloading
@section Unloading
@cindex unloading
The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.
-@defvar load-history
-This variable's value is an alist connecting library names with the
-names of functions and variables they define, the features they provide,
-and the features they require.
-
-Each element is a list and describes one library. The @sc{car} of the
-list is the name of the library, as a string. The rest of the list
-elements have these forms:
-
-@table @code
-@item @var{fun}
-The function @var{fun} was defined by this library.
-@item (t . @var{fun})
-The function @var{fun} was previously an autoload before this library
-redefined it as a function. The following element is always the
-symbol @var{fun}, which signifies that the library defined @var{fun}
-as a function.
-@item (autoload . @var{fun})
-The function @var{fun} was defined as an autoload.
-@item (defvar . @var{var})
-The symbol @var{var} was defined as a variable.
-@item (require . @var{feature})
-The feature @var{feature} was required.
-@item (provide . @var{feature})
-The feature @var{feature} was provided.
-@end table
-
-The value of @code{load-history} may have one element whose @sc{car} is
-@code{nil}. This element describes definitions made with
-@code{eval-buffer} on a buffer that is not visiting a file.
-@end defvar
-
- The command @code{eval-region} updates @code{load-history}, but does so
-by adding the symbols defined to the element for the file being visited,
-rather than replacing that element. @xref{Eval}.
-
@defvar unload-feature-special-hooks
This variable holds a list of hooks to be scanned before unloading a
library, to remove functions defined in the library.