This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization Defining Custom Groups ====================== Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups. The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, use `M-x customize'.) Choose one or more of them (but not too many), and add your group to each of them using the `:group' keyword. The way to declare new customization groups is with `defgroup'. - Macro: defgroup group members doc [keyword value]... Declare GROUP as a customization group containing MEMBERS. Do not quote the symbol GROUP. The argument DOC specifies the documentation string for the group. It should not start with a `*' as in `defcustom'; that convention is for variables only. The argument MEMBERS is a list specifying an initial set of customization items to be members of the group. However, most often MEMBERS is `nil', and you specify the group's members by using the `:group' keyword when defining those members. If you want to specify group members through MEMBERS, each element should have the form `(NAME WIDGET)'. Here NAME is a symbol, and WIDGET is a widget type for editing that symbol. Useful widgets are `custom-variable' for a variable, `custom-face' for a face, and `custom-group' for a group. When a new group is introduced into Emacs, use this keyword in `defgroup': `:version VERSION' This option specifies that the group was first introduced in Emacs version VERSION. The value VERSION must be a string. Tag the group with a version like this when it is introduced, rather than the individual members (*note Variable Definitions::). In addition to the common keywords (*note Common Keywords::), you can also use this keyword in `defgroup': `:prefix PREFIX' If the name of an item in the group starts with PREFIX, then the tag for that item is constructed (by default) by omitting PREFIX. One group can have any number of prefixes. The prefix-discarding feature is currently turned off, which means that `:prefix' currently has no effect. We did this because we found that discarding the specified prefixes often led to confusing names for options. This happened because the people who wrote the `defgroup' definitions for various groups added `:prefix' keywords whenever they make logical sense--that is, whenever the variables in the library have a common prefix. In order to obtain good results with `:prefix', it would be necessary to check the specific effects of discarding a particular prefix, given the specific items in a group and their names and documentation. If the resulting text is not clear, then `:prefix' should not be used in that case. It should be possible to recheck all the customization groups, delete the `:prefix' specifications which give unclear results, and then turn this feature back on, if someone would like to do the work.  File: elisp, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization Defining Customization Variables ================================ Use `defcustom' to declare user-editable variables. - Macro: defcustom option default doc [keyword value]... Declare OPTION as a customizable user option variable. Do not quote OPTION. The argument DOC specifies the documentation string for the variable. It should often start with a `*' to mark it as a "user option" (*note Defining Variables::). Do not start the documentation string with `*' for options which cannot or normally should not be set with `set-variable'; examples of the former are global minor mode options such as `global-font-lock-mode' and examples of the latter are hooks. If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion. You should normally avoid using backquotes in DEFAULT because they are not expanded when editing the value, causing list values to appear to have the wrong structure. When you evaluate a `defcustom' form with `C-M-x' in Emacs Lisp mode (`eval-defun'), a special feature of `eval-defun' arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to `defvar'.) *Note Defining Variables::. `defcustom' accepts the following additional keywords: `:type TYPE' Use TYPE as the data type for this option. It specifies which values are legitimate, and how to display the value. *Note Customization Types::, for more information. `:options LIST' Specify LIST as the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives. This is meaningful only for certain types, currently including `hook', `plist' and `alist'. See the definition of the individual types for a description of how to use `:options'. `:version VERSION' This option specifies that the variable was first introduced, or its default value was changed, in Emacs version VERSION. The value VERSION must be a string. For example, (defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3") `:set SETFUNCTION' Specify SETFUNCTION as the way to change the value of this option. The function SETFUNCTION should take two arguments, a symbol and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for SETFUNCTION is `set-default'. `:get GETFUNCTION' Specify GETFUNCTION as the way to extract the value of this option. The function GETFUNCTION should take one argument, a symbol, and should return the "current value" for that symbol (which need not be the symbol's Lisp value). The default is `default-value'. `:initialize FUNCTION' FUNCTION should be a function used to initialize the variable when the `defcustom' is evaluated. It should take two arguments, the symbol and value. Here are some predefined functions meant for use in this way: `custom-initialize-set' Use the variable's `:set' function to initialize the variable, but do not reinitialize it if it is already non-void. This is the default `:initialize' function. `custom-initialize-default' Like `custom-initialize-set', but use the function `set-default' to set the variable, instead of the variable's `:set' function. This is the usual choice for a variable whose `:set' function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so. `custom-initialize-reset' Always use the `:set' function to initialize the variable. If the variable is already non-void, reset it by calling the `:set' function using the current value (returned by the `:get' method). `custom-initialize-changed' Use the `:set' function to initialize the variable, if it is already set or has been customized; otherwise, just use `set-default'. `:set-after VARIABLES' When setting variables according to saved customizations, make sure to set the variables VARIABLES before this one; in other words, delay setting this variable until after those others have been handled. Use `:set-after' if setting this variable won't work properly unless those other variables already have their intended values. The `:require' option is useful for an option that turns on the operation of a certain feature. Assuming that the package is coded to check the value of the option, you still need to arrange for the package to be loaded. You can do that with `:require'. *Note Common Keywords::. Here is an example, from the library `paren.el': (defcustom show-paren-mode nil "Toggle Show Paren mode..." :set (lambda (symbol value) (show-paren-mode (or value 0))) :initialize 'custom-initialize-default :type 'boolean :group 'paren-showing :require 'paren) If a customization item has a type such as `hook' or `alist', which supports `:options', you can add additional options to the item, outside the `defcustom' declaration, by calling `custom-add-option'. For example, if you define a function `my-lisp-mode-initialization' intended to be called from `emacs-lisp-mode-hook', you might want to add that to the list of options for `emacs-lisp-mode-hook', but not by editing its definition. You can do it thus: (custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization) - Function: custom-add-option symbol option To the customization SYMBOL, add OPTION. The precise effect of adding OPTION depends on the customization type of SYMBOL. Internally, `defcustom' uses the symbol property `standard-value' to record the expression for the default value, and `saved-value' to record the value saved by the user with the customization buffer. The `saved-value' property is actually a list whose car is an expression which evaluates to the value.  File: elisp, Node: Customization Types, Prev: Variable Definitions, Up: Customization Customization Types =================== When you define a user option with `defcustom', you must specify its "customization type". That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing. You specify the customization type in `defcustom' with the `:type' keyword. The argument of `:type' is evaluated; since types that vary at run time are rarely useful, normally you use a quoted constant. For example: (defcustom diff-command "diff" "*The command to use to run diff." :type '(string) :group 'diff) In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can optionally write keyword-value pairs (*note Type Keywords::). Some of the type symbols do not use any arguments; those are called "simple types". For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. For example just `string' as a customization type is equivalent to `(string)'. * Menu: * Simple Types:: * Composite Types:: * Splicing into Lists:: * Type Keywords::  File: elisp, Node: Simple Types, Next: Composite Types, Up: Customization Types Simple Types ------------ This section describes all the simple customization types. `sexp' The value may be any Lisp object that can be printed and read back. You can use `sexp' as a fall-back for any option, if you don't want to take the time to work out a more specific type to use. `integer' The value must be an integer, and is represented textually in the customization buffer. `number' The value must be a number, and is represented textually in the customization buffer. `string' The value must be a string, and the customization buffer shows just the contents, with no delimiting `"' characters and no quoting with `\'. `regexp' Like `string' except that the string must be a valid regular expression. `character' The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number. `file' The value must be a file name, and you can do completion with `M-'. `(file :must-match t)' The value must be a file name for an existing file, and you can do completion with `M-'. `directory' The value must be a directory name, and you can do completion with `M-'. `hook' The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. You can use the `:options' keyword in a hook variable's `defcustom' to specify a list of functions recommended for use in the hook; see *Note Variable Definitions::. `alist' The value must be a list of cons-cells, the CAR of each cell representing a key, and the CDR of the same cell representing an associated value. The user can add and delete key/value pairs, and edit both the key and the value of each pair. You can specify the key and value types like this: (alist :key-type KEY-TYPE :value-type VALUE-TYPE) where KEY-TYPE and VALUE-TYPE are customization type specifications. The default key type is `sexp', and the default value type is `sexp'. The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the `:options' (see *Note Variable Definitions::). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys specified by the `:options' keyword argument. The argument to the `:options' keywords should be a list of option specifications. Ordinarily, the options are simply atoms, which are the specified keys. For example: :options '("foo" "bar" "baz") specifies that there are three "known" keys, namely `"foo"', `"bar"' and `"baz"', which will always be shown first. You may want to restrict the value type for specific keys, for example, the value associated with the `"bar"' key can only be an integer. You can specify this by using a list instead of an atom in the option specification. The first element will specify the key, like before, while the second element will specify the value type. :options '("foo" ("bar" integer) "baz") Finally, you may want to change how the key is presented. By default, the key is simply shown as a `const', since the user cannot change the special keys specified with the `:options' keyword. However, you may want to use a more specialized type for presenting the key, like `function-item' if you know it is a symbol with a function binding. This is done by using a customization type specification instead of a symbol for the key. :options '("foo" ((function-item some-function) integer) "baz") Many alists use lists with two elements, instead of cons cells. For example, (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE).") instead of (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) "Each element is a cons-cell (KEY . VALUE).") Because of the way lists are implemented on top of cons cells, you can treat `list-alist' in the example above as a cons cell alist, where the value type is a list with a single element containing the real value. (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE)." :type '(alist :value-type (group integer))) The `group' widget is used here instead of `list' only because the formatting is better suited for the purpose. Similarily, you can have alists with more values associated with each key, using variations of this trick: (defcustom person-data '(("brian" 50 t) ("dorith" 55 nil) ("ken" 52 t)) "Alist of basic info about people. Each element has the form (NAME AGE MALE-FLAG)." :type '(alist :value-type (group age boolean))) (defcustom pets '(("brian") ("dorith" "dog" "guppy") ("ken" "cat")) "Alist of people's pets. In an element (KEY . VALUE), KEY is the person's name, and the VALUE is a list of that person's pets." :type '(alist :value-type (repeat string))) `plist' The `plist' custom type is similar to the `alist' (see above), except that the information is stored as a property list, i.e. a list of this form: (KEY VALUE KEY VALUE KEY VALUE ...) The default `:key-type' for `plist' is `symbol', rather than `sexp'. `symbol' The value must be a symbol. It appears in the customization buffer as the name of the symbol. `function' The value must be either a lambda expression or a function name. When it is a function name, you can do completion with `M-'. `variable' The value must be a variable name, and you can do completion with `M-'. `face' The value must be a symbol which is a face name, and you can do completion with `M-'. `boolean' The value is boolean--either `nil' or `t'. Note that by using `choice' and `const' together (see the next section), you can specify that the value must be `nil' or `t', but also specify the text to describe each value in a way that fits the specific meaning of the alternative. `coding-system' The value must be a coding-system name, and you can do completion with `M-'. `color' The value must be a valid color name, and you can do completion with `M-'. A sample is provided,  File: elisp, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types Composite Types --------------- When none of the simple types is appropriate, you can use composite types, which build new types from other types. Here are several ways of doing that: `(restricted-sexp :match-alternatives CRITERIA)' The value may be any Lisp object that satisfies one of CRITERIA. CRITERIA should be a list, and each element should be one of these possibilities: * A predicate--that is, a function of one argument that has no side effects, and returns either `nil' or non-`nil' according to the argument. Using a predicate in the list says that objects for which the predicate returns non-`nil' are acceptable. * A quoted constant--that is, `'OBJECT'. This sort of element in the list says that OBJECT itself is an acceptable value. For example, (restricted-sexp :match-alternatives (integerp 't 'nil)) allows integers, `t' and `nil' as legitimate values. The customization buffer shows all legitimate values using their read syntax, and the user edits them textually. `(cons CAR-TYPE CDR-TYPE)' The value must be a cons cell, its CAR must fit CAR-TYPE, and its CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a customization type which matches values such as `("foo" . foo)'. In the customization buffer, the CAR and the CDR are displayed and edited separately, each according to the type that you specify for it. `(list ELEMENT-TYPES...)' The value must be a list with exactly as many elements as the ELEMENT-TYPES you have specified; and each element must fit the corresponding ELEMENT-TYPE. For example, `(list integer string function)' describes a list of three elements; the first element must be an integer, the second a string, and the third a function. In the customization buffer, each element is displayed and edited separately, according to the type specified for it. `(vector ELEMENT-TYPES...)' Like `list' except that the value must be a vector instead of a list. The elements work the same as in `list'. `(choice ALTERNATIVE-TYPES...)' The value must fit at least one of ALTERNATIVE-TYPES. For example, `(choice integer string)' allows either an integer or a string. In the customization buffer, the user selects one of the alternatives using a menu, and can then edit the value in the usual way for that alternative. Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the `:tag' keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way, (choice (integer :tag "Number of spaces") (string :tag "Literal text")) so that the menu offers `Number of spaces' and `Literal Text'. In any alternative for which `nil' is not a valid value, other than a `const', you should specify a valid default for that alternative using the `:value' keyword. *Note Type Keywords::. `(radio ELEMENT-TYPES...)' This is similar to `choice', except that the choices are displayed using `radio buttons' rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (`function-item' customization types). `(const VALUE)' The value must be VALUE--nothing else is allowed. The main use of `const' is inside of `choice'. For example, `(choice integer (const nil))' allows either an integer or `nil'. `:tag' is often used with `const', inside of `choice'. For example, (choice (const :tag "Yes" t) (const :tag "No" nil) (const :tag "Ask" foo)) describes a variable for which `t' means yes, `nil' means no, and `foo' means "ask." `(other VALUE)' This alternative can match any Lisp value, but if the user chooses this alternative, that selects the value VALUE. The main use of `other' is as the last element of `choice'. For example, (choice (const :tag "Yes" t) (const :tag "No" nil) (other :tag "Ask" foo)) describes a variable for which `t' means yes, `nil' means no, and anything else means "ask." If the user chooses `Ask' from the menu of alternatives, that specifies the value `foo'; but any other value (not `t', `nil' or `foo') displays as `Ask', just like `foo'. `(function-item FUNCTION)' Like `const', but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with `:doc', or FUNCTION's own documentation string. `(variable-item VARIABLE)' Like `const', but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with `:doc', or VARIABLE's own documentation string. `(set TYPES...)' The value must be a list, and each element of the list must match one of the TYPES specified. This appears in the customization buffer as a checklist, so that each of TYPES may have either one corresponding element or none. It is not possible to specify two different elements that match the same one of TYPES. For example, `(set integer symbol)' allows one integer and/or one symbol in the list; it does not allow multiple integers or multiple symbols. As a result, it is rare to use nonspecific types such as `integer' in a `set'. Most often, the TYPES in a `set' are `const' types, as shown here: (set (const :bold) (const :italic)) Sometimes they describe possible elements in an alist: (set (cons :tag "Height" (const height) integer) (cons :tag "Width" (const width) integer)) That lets the user specify a height value optionally and a width value optionally. `(repeat ELEMENT-TYPE)' The value must be a list and each element of the list must fit the type ELEMENT-TYPE. This appears in the customization buffer as a list of elements, with `[INS]' and `[DEL]' buttons for adding more elements or removing elements.  File: elisp, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types Splicing into Lists ------------------- The `:inline' feature lets you splice a variable number of elements into the middle of a list or vector. You use it in a `set', `choice' or `repeat' type which appears among the element-types of a `list' or `vector'. Normally, each of the element-types in a `list' or `vector' describes one and only one element of the list or vector. Thus, if an element-type is a `repeat', that specifies a list of unspecified length which appears as one element. But when the element-type uses `:inline', the value it matches is merged directly into the containing sequence. For example, if it matches a list with three elements, those become three elements of the overall sequence. This is analogous to using `,@' in the backquote construct. For example, to specify a list whose first element must be `t' and whose remaining arguments should be zero or more of `foo' and `bar', use this customization type: (list (const t) (set :inline t foo bar)) This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo bar)'. When the element-type is a `choice', you use `:inline' not in the `choice' itself, but in (some of) the alternatives of the `choice'. For example, to match a list which must start with a file name, followed either by the symbol `t' or two strings, use this customization type: (list file (choice (const t) (list :inline t string string))) If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is `t'. If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings.  File: elisp, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types Type Keywords ------------- You can specify keyword-argument pairs in a customization type after the type name symbol. Here are the keywords you can use, and their meanings: `:value DEFAULT' This is used for a type that appears as an alternative inside of `choice'; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer. Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not DEFAULT. If `nil' is not a valid value for the alternative, then it is essential to specify a valid default with `:value'. `:format FORMAT-STRING' This string will be inserted in the buffer to represent the value corresponding to the type. The following `%' escapes are available for use in FORMAT-STRING: `%[BUTTON%]' Display the text BUTTON marked as a button. The `:action' attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments--the widget which the button appears in, and the event. There is no way to specify two different buttons with different actions. `%{SAMPLE%}' Show SAMPLE in a special face specified by `:sample-face'. `%v' Substitute the item's value. How the value is represented depends on the kind of item, and (for variables) on the customization type. `%d' Substitute the item's documentation string. `%h' Like `%d', but if the documentation string is more than one line, add an active field to control whether to show all of it or just the first line. `%t' Substitute the tag here. You specify the tag with the `:tag' keyword. `%%' Display a literal `%'. `:action ACTION' Perform ACTION if the user clicks on a button. `:button-face FACE' Use the face FACE (a face name or a list of face names) for button text displayed with `%[...%]'. `:button-prefix PREFIX' `:button-suffix SUFFIX' These specify the text to display before and after a button. Each can be: `nil' No text is inserted. a string The string is inserted literally. a symbol The symbol's value is used. `:tag TAG' Use TAG (a string) as the tag for the value (or part of the value) that corresponds to this type. `:doc DOC' Use DOC as the documentation string for this value (or part of the value) that corresponds to this type. In order for this to work, you must specify a value for `:format', and use `%d' or `%h' in that value. The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a `:choice' type or the parts of some other composite type. `:help-echo MOTION-DOC' When you move to this item with `widget-forward' or `widget-backward', it will display the string MOTION-DOC in the echo area. In addition, MOTION-DOC is used as the mouse `help-echo' string and may actually be a function or form evaluated to yield a help string as for `help-echo' text properties. `:match FUNCTION' Specify how to decide whether a value matches the type. The corresponding value, FUNCTION, should be a function that accepts two arguments, a widget and a value; it should return non-`nil' if the value is acceptable.  File: elisp, Node: Loading, Next: Byte Compilation, Prev: Customization, Up: Top Loading ******* Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file. The load functions evaluate all the expressions in a file just as the `eval-current-buffer' function evaluates all the expressions in a buffer. The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer. The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a "top-level form". There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. A file containing Lisp code is often called a "library". Thus, the "Rmail library" is a file containing code for Rmail mode. Similarly, a "Lisp library directory" is a directory of files containing Lisp code. * Menu: * How Programs Do Loading:: The `load' function and others. * Library Search:: Finding a library to load. * Loading Non-ASCII:: Non-ASCII characters in Emacs Lisp files. * Autoload:: Setting up a function to autoload. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Unloading:: How to ``unload'' a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded.  File: elisp, Node: How Programs Do Loading, Next: Library Search, Up: Loading 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 (*note Autoload::). `require' loads a file if it isn't already loaded (*note Named 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. *Note Library Search::. If you get a warning that `foo.elc' is older than `foo.el', it means you should consider recompiling `foo.el'. *Note Byte Compilation::. When loading a source file (not compiled), `load' performs character set translation just as Emacs would do when visiting the file. *Note 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'. *Note Eval::. For information about how `load' is used in building Emacs, see *Note Building Emacs::.  File: elisp, Node: Library Search, Next: Loading Non-ASCII, Prev: How Programs Do Loading, Up: Loading Library Search ============== When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable `load-path'. - User Option: load-path The value of this variable is a list of directories to search when loading files with `load'. Each element is a string (which must be a directory name) or `nil' (which stands for the current working directory). The value of `load-path' is initialized from the environment variable `EMACSLOADPATH', if that exists; otherwise its default value is specified in `emacs/src/paths.h' when Emacs is built. Then the list is expanded by adding subdirectories of the directories in the list. The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:' (or `;', according to the operating system) separates directory names, and `.' is used for the current default directory. Here is an example of how to set your `EMACSLOADPATH' variable from a `csh' `.login' file: setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp Here is how to set it using `sh': export EMACSLOADPATH EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp Here is an example of code you can place in your init file (*note Init File::) to add several directories to the front of your default `load-path': (setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" "~/emacs") load-path)) In this example, the path searches the current working directory first, followed then by the `/user/bil/emacs' directory, the `/usr/local/lisplib' directory, and the `~/emacs' directory, which are then followed by the standard directories for Lisp code. Dumping Emacs uses a special value of `load-path'. If the value of `load-path' at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary `load-path' value when it starts up, as described above. But if `load-path' has any other value at the end of dumping, that value is used for execution of the dumped Emacs also. Therefore, if you want to change `load-path' temporarily for loading a few libraries in `site-init.el' or `site-load.el', you should bind `load-path' locally with `let' around the calls to `load'. The default value of `load-path', when running an Emacs which has been installed on the system, includes two special directories (and their subdirectories as well): "/usr/local/share/emacs/VERSION/site-lisp" and "/usr/local/share/emacs/site-lisp" The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions. There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another. Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version. Emacs finds these directories' subdirectories and adds them to `load-path' when it starts up. Both immediate subdirectories and subdirectories multiple levels down are added to `load-path'. Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories named `RCS' or `CVS' are excluded. Also, a subdirectory which contains a file named `.nosearch' is excluded. You can use these methods to prevent certain subdirectories of the `site-lisp' directories from being searched. If you run Emacs from the directory where it was built--that is, an executable that has not been formally installed--then `load-path' normally contains two additional directories. These are the `lisp' and `site-lisp' subdirectories of the main build directory. (Both are represented as absolute file names.) - Command: locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library LIBRARY. It searches for the library in the same way `load' does, and the argument NOSUFFIX has the same meaning as in `load': don't add suffixes `.elc' or `.el' to the specified name LIBRARY. If the PATH is non-`nil', that list of directories is used instead of `load-path'. When `locate-library' is called from a program, it returns the file name as a string. When the user runs `locate-library' interactively, the argument INTERACTIVE-CALL is `t', and this tells `locate-library' to display the file name in the echo area.  File: elisp, Node: Loading Non-ASCII, Next: Autoload, Prev: Library Search, Up: Loading Loading Non-ASCII Characters ============================ When Emacs Lisp programs contain string constants with non-ASCII characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (*note Text Representations::). Which representation is used depends on how the file is read into Emacs. If it is read with decoding into multibyte representation, the text of the Lisp program will be multibyte text, and its string constants will be multibyte strings. If a file containing Latin-1 characters (for example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. *Note Coding Systems::. To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the `--unibyte' option. This means that string constants with non-ASCII characters translate into multibyte strings. The only exception is when a particular file specifies no decoding. The reason Emacs is designed this way is so that Lisp programs give predictable results, regardless of how Emacs was started. In addition, this enables programs that depend on using multibyte text to work even in a unibyte Emacs. Of course, such programs should be designed to notice whether the user prefers unibyte or multibyte text, by checking `default-enable-multibyte-characters', and convert representations appropriately. In most Emacs Lisp programs, the fact that non-ASCII strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing `-*-unibyte: t;-*-' in a comment on the file's first line. With that designator, the file will unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session. This can matter when making keybindings to non-ASCII characters written as `?vLITERAL'.