[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
provide
and require
are an alternative to
autoload
for loading files automatically. They work in terms of
named features. Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.
A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should provide the feature. Another program that uses them may ensure they are defined by requiring the feature. This loads the file of definitions if it hasn't been loaded already.
To require the presence of a feature, call require
with the
feature name as argument. require
looks in the global variable
features
to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call provide
at the top level to add the feature to
features
; if it fails to do so, require
signals an error.
For example, in `emacs/lisp/prolog.el',
the definition for run-prolog
includes the following code:
(defun run-prolog () "Run an inferior Prolog process, with I/O via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode)) |
The expression (require 'comint)
loads the file `comint.el'
if it has not yet been loaded. This ensures that make-comint
is
defined. Features are normally named after the files that provide them,
so that require
need not be given the file name.
The `comint.el' file contains the following top-level expression:
(provide 'comint) |
This adds comint
to the global features
list, so that
(require 'comint)
will henceforth know that nothing needs to be
done.
When require
is used at top level in a file, it takes effect
when you byte-compile that file (see section 16. Byte Compilation) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about. It also avoids byte-compiler
warnings for functions and variables defined in the file loaded with
require
.
Although top-level calls to require
are evaluated during
byte compilation, provide
calls are not. Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a provide
followed by a require
for the same
feature, as in the following example.
(provide 'my-feature) ; Ignored by byte compiler,
; evaluated by |
The compiler ignores the provide
, then processes the
require
by loading the file in question. Loading the file does
execute the provide
call, so the subsequent require
call
does nothing when the file is loaded.
The direct effect of calling provide
is to add feature to
the front of the list features
if it is not already in the list.
The argument feature must be a symbol. provide
returns
feature.
features => (bar bish) (provide 'foo) => foo features => (foo bar bish) |
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluating its contents, any function definitions or
provide
calls that occurred during the load are undone.
See section 15.4 Autoload.
(featurep feature)
; see below). The
argument feature must be a symbol.
If the feature is not present, then require
loads filename
with load
. If filename is not supplied, then the name of
the symbol feature is used as the base file name to load.
However, in this case, require
insists on finding feature
with an added suffix; a file whose name is just feature won't be
used.
If loading the file fails to provide feature, require
signals an error, `Required feature feature was not
provided', unless noerror is non-nil
.
t
if feature has been provided in the
current Emacs session (i.e., if feature is a member of
features
.)
provide
. The order of the elements in the
features
list is not significant.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |