XEmacs 21.2.36 "Notos"
[chise/xemacs-chise.git-] / man / lispref / loading.texi
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/loading.info
6 @node Loading, Byte Compilation, Macros, Top
7 @chapter Loading
8 @cindex loading
9 @cindex library
10 @cindex Lisp library
11
12   Loading a file of Lisp code means bringing its contents into the Lisp
13 environment in the form of Lisp objects.  XEmacs finds and opens the
14 file, reads the text, evaluates each form, and then closes the file.
15
16   The load functions evaluate all the expressions in a file just
17 as the @code{eval-current-buffer} function evaluates all the
18 expressions in a buffer.  The difference is that the load functions
19 read and evaluate the text in the file as found on disk, not the text
20 in an Emacs buffer.
21
22 @cindex top-level form
23   The loaded file must contain Lisp expressions, either as source code
24 or as byte-compiled code.  Each form in the file is called a
25 @dfn{top-level form}.  There is no special format for the forms in a
26 loadable file; any form in a file may equally well be typed directly
27 into a buffer and evaluated there.  (Indeed, most code is tested this
28 way.)  Most often, the forms are function definitions and variable
29 definitions.
30
31   A file containing Lisp code is often called a @dfn{library}.  Thus,
32 the ``Rmail library'' is a file containing code for Rmail mode.
33 Similarly, a ``Lisp library directory'' is a directory of files
34 containing Lisp code.
35
36 @menu
37 * How Programs Do Loading::     The @code{load} function and others.
38 * Autoload::                    Setting up a function to autoload.
39 * Repeated Loading::            Precautions about loading a file twice.
40 * Named Features::              Loading a library if it isn't already loaded.
41 * Unloading::                   How to ``unload'' a library that was loaded.
42 * Hooks for Loading::           Providing code to be run when
43                                   particular libraries are loaded.
44 @end menu
45
46 @node How Programs Do Loading
47 @section How Programs Do Loading
48
49   XEmacs Lisp has several interfaces for loading.  For example,
50 @code{autoload} creates a placeholder object for a function in a file;
51 trying to call the autoloading function loads the file to get the
52 function's real definition (@pxref{Autoload}).  @code{require} loads a
53 file if it isn't already loaded (@pxref{Named Features}).  Ultimately, all
54 these facilities call the @code{load} function to do the work.
55
56 @defun load filename &optional missing-ok nomessage nosuffix
57 This function finds and opens a file of Lisp code, evaluates all the
58 forms in it, and closes the file.
59
60 To find the file, @code{load} first looks for a file named
61 @file{@var{filename}.elc}, that is, for a file whose name is
62 @var{filename} with @samp{.elc} appended.  If such a file exists, it is
63 loaded.  If there is no file by that name, then @code{load} looks for a
64 file named @file{@var{filename}.el}.  If that file exists, it is loaded.
65 Finally, if neither of those names is found, @code{load} looks for a
66 file named @var{filename} with nothing appended, and loads it if it
67 exists.  (The @code{load} function is not clever about looking at
68 @var{filename}.  In the perverse case of a file named @file{foo.el.el},
69 evaluation of @code{(load "foo.el")} will indeed find it.)
70
71 If the optional argument @var{nosuffix} is non-@code{nil}, then the
72 suffixes @samp{.elc} and @samp{.el} are not tried.  In this case, you
73 must specify the precise file name you want.
74
75 If @var{filename} is a relative file name, such as @file{foo} or
76 @file{baz/foo.bar}, @code{load} searches for the file using the variable
77 @code{load-path}.  It appends @var{filename} to each of the directories
78 listed in @code{load-path}, and loads the first file it finds whose name
79 matches.  The current default directory is tried only if it is specified
80 in @code{load-path}, where @code{nil} stands for the default directory.
81 @code{load} tries all three possible suffixes in the first directory in
82 @code{load-path}, then all three suffixes in the second directory, and
83 so on.
84
85 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
86 means you should consider recompiling @file{foo.el}.  @xref{Byte
87 Compilation}.
88
89 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
90 in the echo area during loading unless @var{nomessage} is
91 non-@code{nil}.
92
93 @cindex load errors
94 Any unhandled errors while loading a file terminate loading.  If the
95 load was done for the sake of @code{autoload}, any function definitions
96 made during the loading are undone.
97
98 @kindex file-error
99 If @code{load} can't find the file to load, then normally it signals the
100 error @code{file-error} (with @samp{Cannot open load file
101 @var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
102 @code{load} just returns @code{nil}.
103
104 You can use the variable @code{load-read-function} to specify a function
105 for @code{load} to use instead of @code{read} for reading expressions.
106 See below.
107
108 @code{load} returns @code{t} if the file loads successfully.
109 @end defun
110
111 @ignore
112 @deffn Command load-file filename
113 This function loads the file @var{filename}.  If @var{filename} is an
114 absolute file name, then it is loaded.  If it is relative, then the
115 current default directory is assumed.  @code{load-path} is not used, and
116 suffixes are not appended.  Use this function if you wish to specify
117 the file to be loaded exactly.
118 @end deffn
119
120 @deffn Command load-library library
121 This function loads the library named @var{library}.  A library is
122 nothing more than a file that may be loaded as described earlier.  This
123 function is identical to @code{load}, save that it reads a file name
124 interactively with completion.
125 @end deffn
126 @end ignore
127
128 @defopt load-path
129 @cindex @code{EMACSLOADPATH} environment variable
130 The value of this variable is a list of directories to search when
131 loading files with @code{load}.  Each element is a string (which must be
132 a directory name) or @code{nil} (which stands for the current working
133 directory).  The value of @code{load-path} is initialized from the
134 environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
135 default value is specified in @file{emacs/src/paths.h} when XEmacs is
136 built.
137
138 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
139 @samp{:} (or @samp{;}, according to the operating system) separates
140 directory names, and @samp{.} is used for the current default directory.
141 Here is an example of how to set your @code{EMACSLOADPATH} variable from
142 a @code{csh} @file{.login} file:
143
144 @c This overfull hbox is OK.  --rjc 16mar92
145 @smallexample
146 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
147 @end smallexample
148
149 Here is how to set it using @code{sh}:
150
151 @smallexample
152 export EMACSLOADPATH
153 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
154 @end smallexample
155
156 Here is an example of code you can place in a @file{.emacs} file to add
157 several directories to the front of your default @code{load-path}:
158
159 @smallexample
160 @group
161 (setq load-path
162       (append (list nil "/user/bil/emacs"
163                     "/usr/local/lisplib"
164                     "~/emacs")
165               load-path))
166 @end group
167 @end smallexample
168
169 @c Wordy to rid us of an overfull hbox.  --rjc 15mar92
170 @noindent
171 In this example, the path searches the current working directory first,
172 followed then by the @file{/user/bil/emacs} directory, the
173 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
174 which are then followed by the standard directories for Lisp code.
175
176 The command line options @samp{-l} or @samp{-load} specify a Lisp
177 library to load as part of Emacs startup.  Since this file might be in
178 the current directory, Emacs 18 temporarily adds the current directory
179 to the front of @code{load-path} so the file can be found there.  Newer
180 Emacs versions also find such files in the current directory, but
181 without altering @code{load-path}.
182
183 Dumping Emacs uses a special value of @code{load-path}.  If the value of
184 @code{load-path} at the end of dumping is unchanged (that is, still the
185 same special value), the dumped Emacs switches to the ordinary
186 @code{load-path} value when it starts up, as described above.  But if
187 @code{load-path} has any other value at the end of dumping, that value
188 is used for execution of the dumped Emacs also.
189
190 Therefore, if you want to change @code{load-path} temporarily for
191 loading a few libraries in @file{site-init.el} or @file{site-load.el},
192 you should bind @code{load-path} locally with @code{let} around the
193 calls to @code{load}.
194 @end defopt
195
196 @defun locate-file filename path-list &optional suffixes mode
197 This function searches for a file in the same way that @code{load} does,
198 and returns the file found (if any). (In fact, @code{load} uses this
199 function to search through @code{load-path}.) It searches for
200 @var{filename} through @var{path-list}, expanded by one of the optional
201 @var{suffixes} (string of suffixes separated by @samp{:}s), checking for
202 access @var{mode} (0|1|2|4 = exists|executable|writable|readable),
203 default readable.
204
205 @code{locate-file} keeps hash tables of the directories it searches
206 through, in order to speed things up.  It tries valiantly to not get
207 confused in the face of a changing and unpredictable environment, but
208 can occasionally get tripped up.  In this case, you will have to call
209 @code{locate-file-clear-hashing} to get it back on track.  See that
210 function for details.
211 @end defun
212
213 @defun locate-file-clear-hashing path
214 This function clears the hash records for the specified list of
215 directories.  @code{locate-file} uses a hashing scheme to speed lookup, and
216 will correctly track the following environmental changes:
217
218 @itemize @bullet
219 @item
220 changes of any sort to the list of directories to be searched.
221 @item
222 addition and deletion of non-shadowing files (see below) from the
223 directories in the list.
224 @item
225 byte-compilation of a .el file into a .elc file.
226 @end itemize
227
228 @code{locate-file} will primarily get confused if you add a file that
229 shadows (i.e. has the same name as) another file further down in the
230 directory list.  In this case, you must call
231 @code{locate-file-clear-hashing}.
232 @end defun
233
234 @defvar load-in-progress
235 This variable is non-@code{nil} if Emacs is in the process of loading a
236 file, and it is @code{nil} otherwise.
237 @end defvar
238
239 @defvar load-read-function
240 This variable specifies an alternate expression-reading function for
241 @code{load} and @code{eval-region} to use instead of @code{read}.
242 The function should accept one argument, just as @code{read} does.
243
244 Normally, the variable's value is @code{nil}, which means those
245 functions should use @code{read}.
246 @end defvar
247
248 @defopt load-warn-when-source-newer
249 This variable specifies whether @code{load} should check whether the
250 source is newer than the binary.  If this variable is true, then when a
251 @samp{.elc} file is being loaded and the corresponding @samp{.el} is
252 newer, a warning message will be printed.  The default is @code{nil},
253 but it is bound to @code{t} during the initial loadup.
254 @end defopt
255
256 @defopt load-warn-when-source-only
257 This variable specifies whether @code{load} should warn when loading a
258 @samp{.el} file instead of an @samp{.elc}.  If this variable is true,
259 then when @code{load} is called with a filename without an extension,
260 and the @samp{.elc} version doesn't exist but the @samp{.el} version
261 does, then a message will be printed.  If an explicit extension is
262 passed to @code{load}, no warning will be printed.  The default is
263 @code{nil}, but it is bound to @code{t} during the initial loadup.
264 @end defopt
265
266 @defopt load-ignore-elc-files
267 This variable specifies whether @code{load} should ignore @samp{.elc}
268 files when a suffix is not given.  This is normally used only to
269 bootstrap the @samp{.elc} files when building XEmacs, when you use the
270 command @samp{make all-elc}. (This forces the @samp{.el} versions to be
271 loaded in the process of compiling those same files, so that existing
272 out-of-date @samp{.elc} files do not make it mess things up.)
273 @end defopt
274
275   To learn how @code{load} is used to build XEmacs, see @ref{Building XEmacs}.
276
277 @node Autoload
278 @section Autoload
279 @cindex autoload
280
281   The @dfn{autoload} facility allows you to make a function or macro
282 known in Lisp, but put off loading the file that defines it.  The first
283 call to the function automatically reads the proper file to install the
284 real definition and other associated code, then runs the real definition
285 as if it had been loaded all along.
286
287   There are two ways to set up an autoloaded function: by calling
288 @code{autoload}, and by writing a special ``magic'' comment in the
289 source before the real definition.  @code{autoload} is the low-level
290 primitive for autoloading; any Lisp program can call @code{autoload} at
291 any time.  Magic comments do nothing on their own; they serve as a guide
292 for the command @code{update-file-autoloads}, which constructs calls to
293 @code{autoload} and arranges to execute them when Emacs is built.  Magic
294 comments are the most convenient way to make a function autoload, but
295 only for packages installed along with Emacs.
296
297 @defun autoload function filename &optional docstring interactive type
298 This function defines the function (or macro) named @var{function} so as
299 to load automatically from @var{filename}.  The string @var{filename}
300 specifies the file to load to get the real definition of @var{function}.
301
302 The argument @var{docstring} is the documentation string for the
303 function.  Normally, this is the identical to the documentation string
304 in the function definition itself.  Specifying the documentation string
305 in the call to @code{autoload} makes it possible to look at the
306 documentation without loading the function's real definition.
307
308 If @var{interactive} is non-@code{nil}, then the function can be called
309 interactively.  This lets completion in @kbd{M-x} work without loading
310 the function's real definition.  The complete interactive specification
311 need not be given here; it's not needed unless the user actually calls
312 @var{function}, and when that happens, it's time to load the real
313 definition.
314
315 You can autoload macros and keymaps as well as ordinary functions.
316 Specify @var{type} as @code{macro} if @var{function} is really a macro.
317 Specify @var{type} as @code{keymap} if @var{function} is really a
318 keymap.  Various parts of Emacs need to know this information without
319 loading the real definition.
320
321 An autoloaded keymap loads automatically during key lookup when a prefix
322 key's binding is the symbol @var{function}.  Autoloading does not occur
323 for other kinds of access to the keymap.  In particular, it does not
324 happen when a Lisp program gets the keymap from the value of a variable
325 and calls @code{define-key}; not even if the variable name is the same
326 symbol @var{function}.
327
328 @cindex function cell in autoload
329 If @var{function} already has a non-void function definition that is not
330 an autoload object, @code{autoload} does nothing and returns @code{nil}.
331 If the function cell of @var{function} is void, or is already an autoload
332 object, then it is defined as an autoload object like this:
333
334 @example
335 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
336 @end example
337
338 For example, 
339
340 @example
341 @group
342 (symbol-function 'run-prolog)
343      @result{} (autoload "prolog" 169681 t nil)
344 @end group
345 @end example
346
347 @noindent
348 In this case, @code{"prolog"} is the name of the file to load, 169681
349 refers to the documentation string in the @file{DOC} file
350 (@pxref{Documentation Basics}), @code{t} means the function is
351 interactive, and @code{nil} that it is not a macro or a keymap.
352 @end defun
353
354 @cindex autoload errors
355   The autoloaded file usually contains other definitions and may require
356 or provide one or more features.  If the file is not completely loaded
357 (due to an error in the evaluation of its contents), any function
358 definitions or @code{provide} calls that occurred during the load are
359 undone.  This is to ensure that the next attempt to call any function
360 autoloading from this file will try again to load the file.  If not for
361 this, then some of the functions in the file might appear defined, but
362 they might fail to work properly for the lack of certain subroutines
363 defined later in the file and not loaded successfully.
364
365   XEmacs as distributed comes with many autoloaded functions.
366 The calls to @code{autoload} are in the file @file{loaddefs.el}.
367 There is a convenient way of updating them automatically.
368
369   If the autoloaded file fails to define the desired Lisp function or
370 macro, then an error is signaled with data @code{"Autoloading failed to
371 define function @var{function-name}"}.
372
373 @findex update-file-autoloads
374 @findex update-directory-autoloads
375   A magic autoload comment looks like @samp{;;;###autoload}, on a line
376 by itself, just before the real definition of the function in its
377 autoloadable source file.  The command @kbd{M-x update-file-autoloads}
378 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
379 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
380 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
381 autoloads for all files in the current directory.
382
383   The same magic comment can copy any kind of form into
384 @file{loaddefs.el}.  If the form following the magic comment is not a
385 function definition, it is copied verbatim.  You can also use a magic
386 comment to execute a form at build time @emph{without} executing it when
387 the file itself is loaded.  To do this, write the form @dfn{on the same
388 line} as the magic comment.  Since it is in a comment, it does nothing
389 when you load the source file; but @code{update-file-autoloads} copies
390 it to @file{loaddefs.el}, where it is executed while building Emacs.
391
392   The following example shows how @code{doctor} is prepared for
393 autoloading with a magic comment:
394
395 @smallexample
396 ;;;###autoload
397 (defun doctor ()
398   "Switch to *doctor* buffer and start giving psychotherapy."
399   (interactive)
400   (switch-to-buffer "*doctor*")
401   (doctor-mode))
402 @end smallexample
403
404 @noindent
405 Here's what that produces in @file{loaddefs.el}:
406
407 @smallexample
408 (autoload 'doctor "doctor"
409   "\
410 Switch to *doctor* buffer and start giving psychotherapy."
411   t)
412 @end smallexample
413
414 @noindent
415 The backslash and newline immediately following the double-quote are a
416 convention used only in the preloaded Lisp files such as
417 @file{loaddefs.el}; they tell @code{make-docfile} to put the
418 documentation string in the @file{DOC} file.  @xref{Building XEmacs}.
419
420 @node Repeated Loading
421 @section Repeated Loading
422 @cindex repeated loading
423
424   You may load one file more than once in an Emacs session.  For
425 example, after you have rewritten and reinstalled a function definition
426 by editing it in a buffer, you may wish to return to the original
427 version; you can do this by reloading the file it came from.
428
429   When you load or reload files, bear in mind that the @code{load} and
430 @code{load-library} functions automatically load a byte-compiled file
431 rather than a non-compiled file of similar name.  If you rewrite a file
432 that you intend to save and reinstall, remember to byte-compile it if
433 necessary; otherwise you may find yourself inadvertently reloading the
434 older, byte-compiled file instead of your newer, non-compiled file!
435
436   When writing the forms in a Lisp library file, keep in mind that the
437 file might be loaded more than once.  For example, the choice of
438 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
439 whether it is desirable to reinitialize the variable if the library is
440 reloaded: @code{defconst} does so, and @code{defvar} does not.
441 (@xref{Defining Variables}.)
442
443   The simplest way to add an element to an alist is like this:
444
445 @example
446 (setq minor-mode-alist
447       (cons '(leif-mode " Leif") minor-mode-alist))
448 @end example
449
450 @noindent
451 But this would add multiple elements if the library is reloaded.
452 To avoid the problem, write this:
453
454 @example
455 (or (assq 'leif-mode minor-mode-alist)
456     (setq minor-mode-alist
457           (cons '(leif-mode " Leif") minor-mode-alist)))
458 @end example
459
460   To add an element to a list just once, use @code{add-to-list}
461 (@pxref{Setting Variables}).
462
463   Occasionally you will want to test explicitly whether a library has
464 already been loaded.  Here's one way to test, in a library, whether it
465 has been loaded before:
466
467 @example
468 (defvar foo-was-loaded)
469
470 (if (not (boundp 'foo-was-loaded))
471     @var{execute-first-time-only})
472
473 (setq foo-was-loaded t)
474 @end example
475
476 @noindent
477 If the library uses @code{provide} to provide a named feature, you can
478 use @code{featurep} to test whether the library has been loaded.
479 @ifinfo
480 @xref{Named Features}.
481 @end ifinfo
482
483 @node Named Features
484 @section Features
485 @cindex features
486 @cindex requiring features
487 @cindex providing features
488
489   @code{provide} and @code{require} are an alternative to
490 @code{autoload} for loading files automatically.  They work in terms of
491 named @dfn{features}.  Autoloading is triggered by calling a specific
492 function, but a feature is loaded the first time another program asks
493 for it by name.
494
495   A feature name is a symbol that stands for a collection of functions,
496 variables, etc.  The file that defines them should @dfn{provide} the
497 feature.  Another program that uses them may ensure they are defined by
498 @dfn{requiring} the feature.  This loads the file of definitions if it
499 hasn't been loaded already.
500
501   To require the presence of a feature, call @code{require} with the
502 feature name as argument.  @code{require} looks in the global variable
503 @code{features} to see whether the desired feature has been provided
504 already.  If not, it loads the feature from the appropriate file.  This
505 file should call @code{provide} at the top level to add the feature to
506 @code{features}; if it fails to do so, @code{require} signals an error.
507 @cindex load error with require
508
509   Features are normally named after the files that provide them, so that
510 @code{require} need not be given the file name.
511
512   For example, in @file{emacs/lisp/prolog.el}, 
513 the definition for @code{run-prolog} includes the following code:
514
515 @smallexample
516 (defun run-prolog ()
517   "Run an inferior Prolog process, input and output via buffer *prolog*."
518   (interactive)
519   (require 'comint)
520   (switch-to-buffer (make-comint "prolog" prolog-program-name))
521   (inferior-prolog-mode))
522 @end smallexample
523
524 @noindent
525 The expression @code{(require 'comint)} loads the file @file{comint.el}
526 if it has not yet been loaded.  This ensures that @code{make-comint} is
527 defined.
528
529 The @file{comint.el} file contains the following top-level expression:
530
531 @smallexample
532 (provide 'comint)
533 @end smallexample
534
535 @noindent
536 This adds @code{comint} to the global @code{features} list, so that
537 @code{(require 'comint)} will henceforth know that nothing needs to be
538 done.
539
540 @cindex byte-compiling @code{require}
541   When @code{require} is used at top level in a file, it takes effect
542 when you byte-compile that file (@pxref{Byte Compilation}) as well as
543 when you load it.  This is in case the required package contains macros
544 that the byte compiler must know about.
545
546   Although top-level calls to @code{require} are evaluated during
547 byte compilation, @code{provide} calls are not.  Therefore, you can
548 ensure that a file of definitions is loaded before it is byte-compiled
549 by including a @code{provide} followed by a @code{require} for the same
550 feature, as in the following example.
551
552 @smallexample
553 @group
554 (provide 'my-feature)  ; @r{Ignored by byte compiler,}
555                        ;   @r{evaluated by @code{load}.}
556 (require 'my-feature)  ; @r{Evaluated by byte compiler.}
557 @end group
558 @end smallexample
559
560 @noindent
561 The compiler ignores the @code{provide}, then processes the
562 @code{require} by loading the file in question.  Loading the file does
563 execute the @code{provide} call, so the subsequent @code{require} call
564 does nothing while loading.
565
566 @defun provide feature
567 This function announces that @var{feature} is now loaded, or being
568 loaded, into the current XEmacs session.  This means that the facilities
569 associated with @var{feature} are or will be available for other Lisp
570 programs.
571
572 The direct effect of calling @code{provide} is to add @var{feature} to
573 the front of the list @code{features} if it is not already in the list.
574 The argument @var{feature} must be a symbol.  @code{provide} returns
575 @var{feature}.
576
577 @smallexample
578 features
579      @result{} (bar bish)
580
581 (provide 'foo)
582      @result{} foo
583 features
584      @result{} (foo bar bish)
585 @end smallexample
586
587 When a file is loaded to satisfy an autoload, and it stops due to an
588 error in the evaluating its contents, any function definitions or
589 @code{provide} calls that occurred during the load are undone.
590 @xref{Autoload}.
591 @end defun
592
593 @defun require feature &optional filename
594 This function checks whether @var{feature} is present in the current
595 XEmacs session (using @code{(featurep @var{feature})}; see below).  If it
596 is not, then @code{require} loads @var{filename} with @code{load}.  If
597 @var{filename} is not supplied, then the name of the symbol
598 @var{feature} is used as the file name to load.
599
600 If loading the file fails to provide @var{feature}, @code{require}
601 signals an error, @samp{Required feature @var{feature} was not
602 provided}.
603 @end defun
604
605 @defun featurep fexp
606 This function returns @code{t} if feature @var{fexp} is present in this
607 Emacs.  Use this to conditionalize execution of lisp code based on the
608 presence or absence of emacs or environment extensions.
609
610 @var{fexp} can be a symbol, a number, or a list.
611
612 If @var{fexp} is a symbol, it is looked up in the `features' variable,
613 and @code{t} is returned if it is found, @code{nil} otherwise.
614
615 If @var{fexp} is a number, the function returns @code{t} if this Emacs
616 has an equal or greater number than @code{fexp}, @code{nil} otherwise.
617 Note that minor Emacs version is expected to be 2 decimal places wide,
618 so @code{(featurep 20.4)} will return @code{nil} on XEmacs 20.4---you
619 must write @code{(featurep 20.04)}, unless you wish to match for XEmacs
620 20.40.
621
622 If @var{fexp} is a list whose car is the symbol @code{and}, the function
623 returns @code{t} if all the features in its cdr are present, @code{nil}
624 otherwise.
625
626 If @var{fexp} is a list whose car is the symbol @code{or}, the function
627 returns @code{t} if any the features in its cdr are present, @code{nil}
628 otherwise.
629
630 If @var{fexp} is a list whose car is the symbol @code{not}, the function 
631 returns @code{t} if the feature is not present, @code{nil} otherwise.
632
633 Examples:
634
635 @example
636 (featurep 'xemacs)
637      @result{} ; @r{t on XEmacs.}
638
639 (featurep '(and xemacs gnus))
640      @result{} ; @r{t on XEmacs with Gnus loaded.}
641
642 (featurep '(or tty-frames (and emacs 19.30)))
643      @result{} ; @r{t if this Emacs supports TTY frames.}
644
645 (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
646      @result{} ; @r{t on XEmacs 19.15 and later, or on}
647                ; @r{FSF Emacs 19.34 and later.}
648 @end example
649
650 @strong{Please note:} The advanced arguments of this function (anything other than a
651 symbol) are not yet supported by FSF Emacs.  If you feel they are useful
652 for supporting multiple Emacs variants, lobby Richard Stallman at
653 @samp{<bug-gnu-emacs@@prep.ai.mit.edu>}.
654 @end defun
655
656 @defvar features
657 The value of this variable is a list of symbols that are the features
658 loaded in the current XEmacs session.  Each symbol was put in this list
659 with a call to @code{provide}.  The order of the elements in the
660 @code{features} list is not significant.
661 @end defvar
662
663 @node Unloading
664 @section Unloading
665 @cindex unloading
666
667 @c Emacs 19 feature
668   You can discard the functions and variables loaded by a library to
669 reclaim memory for other Lisp objects.  To do this, use the function
670 @code{unload-feature}:
671
672 @deffn Command unload-feature feature &optional force
673 This command unloads the library that provided feature @var{feature}.
674 It undefines all functions, macros, and variables defined in that
675 library with @code{defconst}, @code{defvar}, @code{defun},
676 @code{defmacro}, @code{defsubst}, @code{define-function} and
677 @code{defalias}.  It then restores any autoloads formerly associated
678 with those symbols.  (Loading saves these in the @code{autoload}
679 property of the symbol.)
680
681 Ordinarily, @code{unload-feature} refuses to unload a library on which
682 other loaded libraries depend.  (A library @var{a} depends on library
683 @var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
684 optional argument @var{force} is non-@code{nil}, dependencies are
685 ignored and you can unload any library.
686 @end deffn
687
688   The @code{unload-feature} function is written in Lisp; its actions are
689 based on the variable @code{load-history}.
690
691 @defvar load-history
692 This variable's value is an alist connecting library names with the
693 names of functions and variables they define, the features they provide,
694 and the features they require.
695
696 Each element is a list and describes one library.  The @sc{car} of the
697 list is the name of the library, as a string.  The rest of the list is
698 composed of these kinds of objects:
699
700 @itemize @bullet
701 @item
702 Symbols that were defined by this library.
703 @item
704 Lists of the form @code{(require . @var{feature})} indicating
705 features that were required.
706 @item
707 Lists of the form @code{(provide . @var{feature})} indicating
708 features that were provided.
709 @end itemize
710
711 The value of @code{load-history} may have one element whose @sc{car} is
712 @code{nil}.  This element describes definitions made with
713 @code{eval-buffer} on a buffer that is not visiting a file.
714 @end defvar
715
716   The command @code{eval-region} updates @code{load-history}, but does so
717 by adding the symbols defined to the element for the file being visited,
718 rather than replacing that element.
719
720 @node Hooks for Loading
721 @section Hooks for Loading
722 @cindex loading hooks
723 @cindex hooks for loading
724
725 @ignore @c Not currently in XEmacs.  JWZ hates it.
726 You can ask for code to be executed if and when a particular library is
727 loaded, by calling @code{eval-after-load}.
728
729 @defun eval-after-load library form
730 This function arranges to evaluate @var{form} at the end of loading the
731 library @var{library}, if and when @var{library} is loaded.  If
732 @var{library} is already loaded, it evaluates @var{form} right away.
733
734 The library name @var{library} must exactly match the argument of
735 @code{load}.  To get the proper results when an installed library is
736 found by searching @code{load-path}, you should not include any
737 directory names in @var{library}.
738
739 An error in @var{form} does not undo the load, but does prevent
740 execution of the rest of @var{form}.
741 @end defun
742
743 In general, well-designed Lisp programs should not use this feature.
744 The clean and modular ways to interact with a Lisp library are (1)
745 examine and set the library's variables (those which are meant for
746 outside use), and (2) call the library's functions.  If you wish to
747 do (1), you can do it immediately---there is no need to wait for when
748 the library is loaded.  To do (2), you must load the library (preferably
749 with @code{require}).
750
751 But it is ok to use @code{eval-after-load} in your personal customizations
752 if you don't feel they must meet the design standards of programs to be
753 released.
754 @end ignore
755
756 @defvar after-load-alist
757 An alist of expressions to evaluate if and when particular libraries are
758 loaded.  Each element looks like this:
759
760 @example
761 (@var{filename} @var{forms}@dots{})
762 @end example
763
764 When @code{load} is run and the file-name argument is @var{filename},
765 the @var{forms} in the corresponding element are executed at the end of
766 loading.
767
768 @var{filename} must match exactly!  Normally @var{filename} is the name
769 of a library, with no directory specified, since that is how @code{load}
770 is normally called.  An error in @var{forms} does not undo the load, but
771 does prevent execution of the rest of the @var{forms}.
772
773 @ignore @c eval-after-load not in XEmacs
774 The function @code{load} checks @code{after-load-alist} in order to
775 implement @code{eval-after-load}.
776 @end ignore
777 @end defvar
778
779 @c Emacs 19 feature