(lispref.info)Features


Next: Unloading Prev: Repeated Loading Up: Loading

Features
========

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

   The use of named features simplifies the task of determining whether
required definitions have been defined.  A feature name is a symbol that
stands for a collection of functions, variables, etc.  A program that
needs the collection may ensure that they are defined by "requiring"
the feature.  If the file that contains the feature has not yet been
loaded, then it will be loaded (or an error will be signaled if it
cannot be loaded).  The file thus loaded must "provide" the required
feature or an error will be signaled.

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

   Features are normally named after the files they are provided in so
that `require' need not be given the file name.

   For example, in `emacs/lisp/prolog.el', the definition for
`run-prolog' includes the following code:

     (defun run-prolog ()
       "Run an inferior Prolog process,\
      input and output via buffer *prolog*."
       (interactive)
       (require 'comint)
       (switch-to-buffer (make-comint "prolog" prolog-program-name))
       (inferior-prolog-mode))

The expression `(require 'shell)' loads the file `shell.el' if it has
not yet been loaded.  This ensures that `make-shell' is defined.

   The `shell.el' file contains the following top-level expression:

     (provide 'shell)

This adds `shell' to the global `features' list when the `shell' file
is loaded, so that `(require 'shell)' will henceforth know that nothing
needs to be done.

   When `require' is used at top-level in a file, it takes effect if
you byte-compile that file (Note: Byte Compilation.).  This is in case
the required package contains macros that the byte compiler must know
about.

   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 `load'.
     (require 'my-feature)  ; Evaluated by byte compiler.

 - Function: provide FEATURE
     This function announces that FEATURE is now loaded, or being
     loaded, into the current Emacs session.  This means that the
     facilities associated with FEATURE are or will be available for
     other Lisp programs.

     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)

     During autoloading, 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.
     Note: Autoload.

 - Function: require FEATURE &optional FILENAME
     This function checks whether FEATURE is present in the current
     Emacs session (using `(featurep FEATURE)'; see below).  If it is
     not, then `require' loads FILENAME with `load'.  If FILENAME is
     not supplied, then the name of the symbol FEATURE is used as the
     file name to load.

     If FEATURE is not provided after the file has been loaded, Emacs
     will signal the error `error' (with data `Required feature FEATURE
     was not provided').

 - Function: featurep FEATURE
     This function returns `t' if FEATURE has been provided in the
     current Emacs session (i.e., FEATURE is a member of `features'.)

 - Variable: features
     The value of this variable is a list of symbols that are the
     features loaded in the current Emacs session.  Each symbol was put
     in this list with a call to `provide'.  The order of the elements
     in the `features' list is not significant.


automatically generated by info2www