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

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.

Features are normally named after the files that provide them, 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 'comint) loads the file comint.el if it has not yet been loaded. This ensures that make-comint is defined.

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

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.

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 while loading.

Function: provide feature

This function announces that feature is now loaded, or being loaded, into the current SXEmacs 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)

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

Function: require feature &optional filename

This function checks whether feature is present in the current SXEmacs 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 loading the file fails to provide feature, require signals an error, ‘Required feature feature was not provided’.

Function: featurep fexp

This function returns t if feature fexp is present in this SXEmacs. Use this to conditionalize execution of lisp code based on the presence or absence of emacs or environment extensions.

fexp can be a symbol, a number, or a list.

If fexp is a symbol, it is looked up in the features variable, and t is returned if it is found, nil otherwise.

If fexp is a number, the function returns t if this SXEmacs has an equal or greater number than fexp, nil otherwise. Note that minor SXEmacs version is expected to be 2 decimal places wide, so (featurep 22.1) will return nil on SXEmacs 22.1—you must write (featurep 22.01), unless you wish to match for SXEmacs 22.10.

If fexp is a list whose car is the symbol and, the function returns t if all the features in its cdr are present, nil otherwise.

If fexp is a list whose car is the symbol or, the function returns t if any the features in its cdr are present, nil otherwise.

If fexp is a list whose car is the symbol not, the function returns t if the feature is not present, nil otherwise.

Examples:

(featurep 'sxemacs)
     ⇒ ; t on SXEmacs.

(featurep '(and sxemacs gnus))
     ⇒ ; t on SXEmacs with Gnus loaded.

(featurep '(or tty-frames (and emacs 19.30)))
     ⇒ ; t if this Emacs supports TTY frames.

(featurep '(or (and sxemacs 22.01) (and xemacs 21.04) (and emacs 21.3)))
     ⇒ ; t on SXEmacs >=22.1, XEmacs >=21.4, or FSF Emacs >=21.3.

Please note: The advanced arguments of this function (anything other than a symbol) are not yet supported by FSF Emacs. If you feel they are useful for supporting multiple Emacs variants, lobby Richard Stallman at ‘<bug-gnu-emacs@prep.ai.mit.edu>’.

Variable: features

The value of this variable is a list of symbols that are the features loaded in the current SXEmacs 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.