www.delorie.com/gnu/docs/elisp-manual-21/elisp_196.html   search  
Buy the book!

GNU Emacs Lisp Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.1 How Programs Do Loading

Emacs Lisp has several interfaces for loading. For example, autoload creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function's real definition (see section 15.4 Autoload). require loads a file if it isn't already loaded (see section 15.6 Features). Ultimately, all these facilities call the load function to do the work.

Function: load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

To find the file, load first looks for a file named `filename.elc', that is, for a file whose name is filename with `.elc' appended. If such a file exists, it is loaded. If there is no file by that name, then load looks for a file named `filename.el'. If that file exists, it is loaded. Finally, if neither of those names is found, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named `foo.el.el', evaluation of (load "foo.el") will indeed find it.)

If the optional argument nosuffix is non-nil, then the suffixes `.elc' and `.el' are not tried. In this case, you must specify the precise file name you want. By specifying the precise file name and using t for nosuffix, you can prevent perverse file names such as `foo.el.el' from being tried.

If the optional argument must-suffix is non-nil, then load insists that the file name used must end in either `.el' or `.elc', unless it contains an explicit directory name. If filename does not contain an explicit directory name, and does not end in a suffix, then load insists on adding one.

If filename is a relative file name, such as `foo' or `baz/foo.bar', load searches for the file using the variable load-path. It appends filename to each of the directories listed in load-path, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in load-path, where nil stands for the default directory. load tries all three possible suffixes in the first directory in load-path, then all three suffixes in the second directory, and so on. See section 15.2 Library Search.

If you get a warning that `foo.elc' is older than `foo.el', it means you should consider recompiling `foo.el'. See section 16. Byte Compilation.

When loading a source file (not compiled), load performs character set translation just as Emacs would do when visiting the file. See section 33.10 Coding Systems.

Messages like `Loading foo...' and `Loading foo...done' appear in the echo area during loading unless nomessage is non-nil.

Any unhandled errors while loading a file terminate loading. If the load was done for the sake of autoload, any function definitions made during the loading are undone.

If load can't find the file to load, then normally it signals the error file-error (with `Cannot open load file filename'). But if missing-ok is non-nil, then load just returns nil.

You can use the variable load-read-function to specify a function for load to use instead of read for reading expressions. See below.

load returns t if the file loads successfully.

Command: load-file filename
This command loads the file filename. If filename is a relative file name, then the current default directory is assumed. load-path is not used, and suffixes are not appended. Use this command if you wish to specify precisely the file name to load.

Command: load-library library
This command loads the library named library. It is equivalent to load, except in how it reads its argument interactively.

Variable: load-in-progress
This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise.

Variable: load-read-function
This variable specifies an alternate expression-reading function for load and eval-region to use instead of read. The function should accept one argument, just as read does.

Normally, the variable's value is nil, which means those functions should use read.

Note: Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the read-function argument to eval-region. See section 9.4 Eval.

For information about how load is used in building Emacs, see E.1 Building Emacs.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003