1 This is ../info/lispref.info, produced by makeinfo version 3.12s from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
58 Macros often need to construct large list structures from a mixture
59 of constants and nonconstant parts. To make this easier, use the macro
60 ``' (often called "backquote").
62 Backquote allows you to quote a list, but selectively evaluate
63 elements of that list. In the simplest case, it is identical to the
64 special form `quote' (*note Quoting::). For example, these two forms
65 yield identical results:
67 `(a list of (+ 2 3) elements)
68 => (a list of (+ 2 3) elements)
69 '(a list of (+ 2 3) elements)
70 => (a list of (+ 2 3) elements)
72 The special marker `,' inside of the argument to backquote indicates
73 a value that isn't constant. Backquote evaluates the argument of `,'
74 and puts the value in the list structure:
76 (list 'a 'list 'of (+ 2 3) 'elements)
77 => (a list of 5 elements)
78 `(a list of ,(+ 2 3) elements)
79 => (a list of 5 elements)
81 You can also "splice" an evaluated value into the resulting list,
82 using the special marker `,@'. The elements of the spliced list become
83 elements at the same level as the other elements of the resulting list.
84 The equivalent code without using ``' is often unreadable. Here are
87 (setq some-list '(2 3))
89 (cons 1 (append some-list '(4) some-list))
91 `(1 ,@some-list 4 ,@some-list)
94 (setq list '(hack foo bar))
98 (cons 'words (append (cdr list) '(as elements)))))
99 => (use the words foo bar as elements)
100 `(use the words ,@(cdr list) as elements)
101 => (use the words foo bar as elements)
103 In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
104 version 19.29), ``' used a different syntax which required an
105 extra level of parentheses around the entire backquote construct.
106 Likewise, each `,' or `,@' substitution required an extra level of
107 parentheses surrounding both the `,' or `,@' and the following
108 expression. The old syntax required whitespace between the ``',
109 `,' or `,@' and the following expression.
111 This syntax is still accepted, but no longer recommended except for
112 compatibility with old Emacs versions.
115 File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
117 Common Problems Using Macros
118 ============================
120 The basic facts of macro expansion have counterintuitive
121 consequences. This section describes some important consequences that
122 can lead to trouble, and rules to follow to avoid trouble.
126 * Argument Evaluation:: The expansion should evaluate each macro arg once.
127 * Surprising Local Vars:: Local variable bindings in the expansion
128 require special care.
129 * Eval During Expansion:: Don't evaluate them; put them in the expansion.
130 * Repeated Expansion:: Avoid depending on how many times expansion is done.
133 File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
135 Evaluating Macro Arguments Repeatedly
136 -------------------------------------
138 When defining a macro you must pay attention to the number of times
139 the arguments will be evaluated when the expansion is executed. The
140 following macro (used to facilitate iteration) illustrates the problem.
141 This macro allows us to write a simple "for" loop such as one might
144 (defmacro for (var from init to final do &rest body)
145 "Execute a simple \"for\" loop.
146 For example, (for i from 1 to 10 do (print i))."
147 (list 'let (list (list var init))
148 (cons 'while (cons (list '<= var final)
149 (append body (list (list 'inc var)))))))
152 (for i from 1 to 3 do
153 (setq square (* i i))
154 (princ (format "\n%d %d" i square)))
158 (setq square (* i i))
159 (princ (format "%d %d" i square))
167 (The arguments `from', `to', and `do' in this macro are "syntactic
168 sugar"; they are entirely ignored. The idea is that you will write
169 noise words (such as `from', `to', and `do') in those positions in the
172 Here's an equivalent definition simplified through use of backquote:
174 (defmacro for (var from init to final do &rest body)
175 "Execute a simple \"for\" loop.
176 For example, (for i from 1 to 10 do (print i))."
178 (while (<= ,var ,final)
182 Both forms of this definition (with backquote and without) suffer
183 from the defect that FINAL is evaluated on every iteration. If FINAL
184 is a constant, this is not a problem. If it is a more complex form,
185 say `(long-complex-calculation x)', this can slow down the execution
186 significantly. If FINAL has side effects, executing it more than once
187 is probably incorrect.
189 A well-designed macro definition takes steps to avoid this problem by
190 producing an expansion that evaluates the argument expressions exactly
191 once unless repeated evaluation is part of the intended purpose of the
192 macro. Here is a correct expansion for the `for' macro:
197 (setq square (* i i))
198 (princ (format "%d %d" i square))
201 Here is a macro definition that creates this expansion:
203 (defmacro for (var from init to final do &rest body)
204 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
211 Unfortunately, this introduces another problem. Proceed to the
215 File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
217 Local Variables in Macro Expansions
218 -----------------------------------
220 In the previous section, the definition of `for' was fixed as
221 follows to make the expansion evaluate the macro arguments the proper
224 (defmacro for (var from init to final do &rest body)
225 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
232 The new definition of `for' has a new problem: it introduces a local
233 variable named `max' which the user does not expect. This causes
234 trouble in examples such as the following:
237 (for x from 0 to 10 do
238 (let ((this (frob x)))
242 The references to `max' inside the body of the `for', which are
243 supposed to refer to the user's binding of `max', really access the
244 binding made by `for'.
246 The way to correct this is to use an uninterned symbol instead of
247 `max' (*note Creating Symbols::). The uninterned symbol can be bound
248 and referred to just like any other symbol, but since it is created by
249 `for', we know that it cannot already appear in the user's program.
250 Since it is not interned, there is no way the user can put it into the
251 program later. It will never appear anywhere except where put by
252 `for'. Here is a definition of `for' that works this way:
254 (defmacro for (var from init to final do &rest body)
255 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
256 (let ((tempvar (make-symbol "max")))
259 (while (<= ,var ,tempvar)
263 This creates an uninterned symbol named `max' and puts it in the
264 expansion instead of the usual interned symbol `max' that appears in
265 expressions ordinarily.
268 File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
270 Evaluating Macro Arguments in Expansion
271 ---------------------------------------
273 Another problem can happen if you evaluate any of the macro argument
274 expressions during the computation of the expansion, such as by calling
275 `eval' (*note Eval::). If the argument is supposed to refer to the
276 user's variables, you may have trouble if the user happens to use a
277 variable with the same name as one of the macro arguments. Inside the
278 macro body, the macro argument binding is the most local binding of this
279 variable, so any references inside the form being evaluated do refer to
280 it. Here is an example:
283 (list 'setq (eval a) t))
286 (foo x) ==> (setq b t)
287 => t ; and `b' has been set.
290 (foo a) ==> (setq a t)
291 => t ; but this set `a', not `c'.
293 It makes a difference whether the user's variable is named `a' or
294 `x', because `a' conflicts with the macro argument variable `a'.
296 Another reason not to call `eval' in a macro definition is that it
297 probably won't do what you intend in a compiled program. The
298 byte-compiler runs macro definitions while compiling the program, when
299 the program's own computations (which you might have wished to access
300 with `eval') don't occur and its local variable bindings don't exist.
302 The safe way to work with the run-time value of an expression is to
303 put the expression into the macro expansion, so that its value is
304 computed as part of executing the expansion.
307 File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
309 How Many Times is the Macro Expanded?
310 -------------------------------------
312 Occasionally problems result from the fact that a macro call is
313 expanded each time it is evaluated in an interpreted function, but is
314 expanded only once (during compilation) for a compiled function. If the
315 macro definition has side effects, they will work differently depending
316 on how many times the macro is expanded.
318 In particular, constructing objects is a kind of side effect. If the
319 macro is called once, then the objects are constructed only once. In
320 other words, the same structure of objects is used each time the macro
321 call is executed. In interpreted operation, the macro is reexpanded
322 each time, producing a fresh collection of objects each time. Usually
323 this does not matter--the objects have the same contents whether they
324 are shared or not. But if the surrounding program does side effects on
325 the objects, it makes a difference whether they are shared. Here is an
328 (defmacro empty-object ()
329 (list 'quote (cons nil nil)))
331 (defun initialize (condition)
332 (let ((object (empty-object)))
334 (setcar object condition))
337 If `initialize' is interpreted, a new list `(nil)' is constructed each
338 time `initialize' is called. Thus, no side effect survives between
339 calls. If `initialize' is compiled, then the macro `empty-object' is
340 expanded during compilation, producing a single "constant" `(nil)' that
341 is reused and altered each time `initialize' is called.
343 One way to avoid pathological cases like this is to think of
344 `empty-object' as a funny kind of constant, not as a memory allocation
345 construct. You wouldn't use `setcar' on a constant such as `'(nil)',
346 so naturally you won't use it on `(empty-object)' either.
349 File: lispref.info, Node: Customization, Up: Top
351 Writing Customization Definitions
352 *********************************
354 This chapter describes how to declare user options for customization,
355 and also customization groups for classifying them. We use the term
356 "customization item" to include both kinds of customization
357 definitions--as well as face definitions.
362 * Group Definitions::
363 * Variable Definitions::
364 * Customization Types::
367 File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
369 Common Keywords for All Kinds of Items
370 ======================================
372 All kinds of customization declarations (for variables and groups,
373 and for faces) accept keyword arguments for specifying various
374 information. This section describes some keywords that apply to all
377 All of these keywords, except `:tag', can be used more than once in
378 a given item. Each use of the keyword has an independent effect. The
379 keyword `:tag' is an exception because any given item can only display
383 Use NAME, a string, instead of the item's name, to label the item
384 in customization menus and buffers.
387 Put this customization item in group GROUP. When you use `:group'
388 in a `defgroup', it makes the new group a subgroup of GROUP.
390 If you use this keyword more than once, you can put a single item
391 into more than one group. Displaying any of those groups will
392 show this item. Be careful not to overdo this!
395 Include an external link after the documentation string for this
396 item. This is a sentence containing an active field which
397 references some other documentation.
399 There are three alternatives you can use for LINK-DATA:
401 `(custom-manual INFO-NODE)'
402 Link to an Info node; INFO-NODE is a string which specifies
403 the node name, as in `"(emacs)Top"'. The link appears as
404 `[manual]' in the customization buffer.
406 `(info-link INFO-NODE)'
407 Like `custom-manual' except that the link appears in the
408 customization buffer with the Info node name.
411 Link to a web page; URL is a string which specifies the URL.
412 The link appears in the customization buffer as URL.
414 You can specify the text to use in the customization buffer by
415 adding `:tag NAME' after the first element of the LINK-DATA; for
416 example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
417 Emacs manual which appears in the buffer as `foo'.
419 An item can have more than one external link; however, most items
423 Load file FILE (a string) before displaying this customization
424 item. Loading is done with `load-library', and only if the file is
428 Require feature FEATURE (a symbol) when installing a value for
429 this item (an option or a face) that was saved using the
430 customization feature. This is done by calling `require'.
432 The most common reason to use `:require' is when a variable enables
433 a feature such as a minor mode, and just setting the variable
434 won't have any effect unless the code which implements the mode is
438 File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
440 Defining Custom Groups
441 ======================
443 Each Emacs Lisp package should have one main customization group
444 which contains all the options, faces and other groups in the package.
445 If the package has a small number of options and faces, use just one
446 group and put everything in it. When there are more than twelve or so
447 options and faces, then you should structure them into subgroups, and
448 put the subgroups under the package's main customization group. It is
449 OK to put some of the options and faces in the package's main group
450 alongside the subgroups.
452 The package's main or only group should be a member of one or more of
453 the standard customization groups. (To display the full list of them,
454 use `M-x customize'.) Choose one or more of them (but not too many),
455 and add your group to each of them using the `:group' keyword.
457 The way to declare new customization groups is with `defgroup'.
459 - Macro: defgroup group members doc [keyword value]...
460 Declare GROUP as a customization group containing MEMBERS. Do not
461 quote the symbol GROUP. The argument DOC specifies the
462 documentation string for the group.
464 The argument MEMBERS is a list specifying an initial set of
465 customization items to be members of the group. However, most
466 often MEMBERS is `nil', and you specify the group's members by
467 using the `:group' keyword when defining those members.
469 If you want to specify group members through MEMBERS, each element
470 should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
471 WIDGET is a widget type for editing that symbol. Useful widgets
472 are `custom-variable' for a variable, `custom-face' for a face,
473 and `custom-group' for a group.
475 In addition to the common keywords (*note Common Keywords::), you
476 can use this keyword in `defgroup':
479 If the name of an item in the group starts with PREFIX, then
480 the tag for that item is constructed (by default) by omitting
483 One group can have any number of prefixes.
486 File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
488 Defining Customization Variables
489 ================================
491 Use `defcustom' to declare user-editable variables.
493 - Macro: defcustom option default doc [keyword value]...
494 Declare OPTION as a customizable user option variable. Do not
495 quote OPTION. The argument DOC specifies the documentation string
498 If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
499 should be an expression to compute the value; be careful in
500 writing it, because it can be evaluated on more than one occasion.
502 The following additional keywords are defined:
505 Use TYPE as the data type for this option. It specifies which
506 values are legitimate, and how to display the value. *Note
507 Customization Types::, for more information.
510 Specify LIST as the list of reasonable values for use in this
513 Currently this is meaningful only when the type is `hook'.
514 In that case, the elements of LIST should be functions that
515 are useful as elements of the hook value. The user is not
516 restricted to using only these functions, but they are
517 offered as convenient alternatives.
520 This option specifies that the variable was first introduced,
521 or its default value was changed, in Emacs version VERSION.
522 The value VERSION must be a string. For example,
524 (defcustom foo-max 34
525 "*Maximum number of foo's allowed."
531 Specify SETFUNCTION as the way to change the value of this
532 option. The function SETFUNCTION should take two arguments,
533 a symbol and the new value, and should do whatever is
534 necessary to update the value properly for this option (which
535 may not mean simply setting the option as a Lisp variable).
536 The default for SETFUNCTION is `set-default'.
539 Specify GETFUNCTION as the way to extract the value of this
540 option. The function GETFUNCTION should take one argument, a
541 symbol, and should return the "current value" for that symbol
542 (which need not be the symbol's Lisp value). The default is
545 `:initialize FUNCTION'
546 FUNCTION should be a function used to initialize the variable
547 when the `defcustom' is evaluated. It should take two
548 arguments, the symbol and value. Here are some predefined
549 functions meant for use in this way:
551 `custom-initialize-set'
552 Use the variable's `:set' function to initialize the
553 variable, but do not reinitialize it if it is already
554 non-void. This is the default `:initialize' function.
556 `custom-initialize-default'
557 Like `custom-initialize-set', but use the function
558 `set-default' to set the variable, instead of the
559 variable's `:set' function. This is the usual choice
560 for a variable whose `:set' function enables or disables
561 a minor mode; with this choice, defining the variable
562 will not call the minor mode function, but customizing
563 the variable will do so.
565 `custom-initialize-reset'
566 Always use the `:set' function to initialize the
567 variable. If the variable is already non-void, reset it
568 by calling the `:set' function using the current value
569 (returned by the `:get' method).
571 `custom-initialize-changed'
572 Use the `:set' function to initialize the variable, if
573 it is already set or has been customized; otherwise,
574 just use `set-default'.
576 The `:require' option is useful for an option that turns on the
577 operation of a certain feature. Assuming that the package is coded to
578 check the value of the option, you still need to arrange for the package
579 to be loaded. You can do that with `:require'. *Note Common
580 Keywords::. Here is an example, from the library `paren.el':
582 (defcustom show-paren-mode nil
583 "Toggle Show Paren mode...."
584 :set (lambda (symbol value)
585 (show-paren-mode (or value 0)))
586 :initialize 'custom-initialize-default
588 :group 'paren-showing
591 Internally, `defcustom' uses the symbol property `standard-value' to
592 record the expression for the default value, and `saved-value' to
593 record the value saved by the user with the customization buffer. The
594 `saved-value' property is actually a list whose car is an expression
595 which evaluates to the value.
598 File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
603 When you define a user option with `defcustom', you must specify its
604 "customization type". That is a Lisp object which describes (1) which
605 values are legitimate and (2) how to display the value in the
606 customization buffer for editing.
608 You specify the customization type in `defcustom' with the `:type'
609 keyword. The argument of `:type' is evaluated; since types that vary
610 at run time are rarely useful, normally you use a quoted constant. For
613 (defcustom diff-command "diff"
614 "*The command to use to run diff."
618 In general, a customization type is a list whose first element is a
619 symbol, one of the customization type names defined in the following
620 sections. After this symbol come a number of arguments, depending on
621 the symbol. Between the type symbol and its arguments, you can
622 optionally write keyword-value pairs (*note Type Keywords::).
624 Some of the type symbols do not use any arguments; those are called
625 "simple types". For a simple type, if you do not use any keyword-value
626 pairs, you can omit the parentheses around the type symbol. For
627 example just `string' as a customization type is equivalent to
634 * Splicing into Lists::
638 File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
643 This section describes all the simple customization types.
646 The value may be any Lisp object that can be printed and read
647 back. You can use `sexp' as a fall-back for any option, if you
648 don't want to take the time to work out a more specific type to
652 The value must be an integer, and is represented textually in the
653 customization buffer.
656 The value must be a number, and is represented textually in the
657 customization buffer.
660 The value must be a string, and the customization buffer shows
661 just the contents, with no delimiting `"' characters and no
665 Like `string' except that the string must be a valid regular
669 The value must be a character code. A character code is actually
670 an integer, but this type shows the value by inserting the
671 character in the buffer, rather than by showing the number.
674 The value must be a file name, and you can do completion with
677 `(file :must-match t)'
678 The value must be a file name for an existing file, and you can do
679 completion with `M-<TAB>'.
682 The value must be a directory name, and you can do completion with
686 The value must be a symbol. It appears in the customization
687 buffer as the name of the symbol.
690 The value must be either a lambda expression or a function name.
691 When it is a function name, you can do completion with `M-<TAB>'.
694 The value must be a variable name, and you can do completion with
698 The value must be a symbol which is a face name.
701 The value is boolean--either `nil' or `t'. Note that by using
702 `choice' and `const' together (see the next section), you can
703 specify that the value must be `nil' or `t', but also specify the
704 text to describe each value in a way that fits the specific
705 meaning of the alternative.
708 File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
713 When none of the simple types is appropriate, you can use composite
714 types, which build new types from other types. Here are several ways of
717 `(restricted-sexp :match-alternatives CRITERIA)'
718 The value may be any Lisp object that satisfies one of CRITERIA.
719 CRITERIA should be a list, and each elements should be one of
722 * A predicate--that is, a function of one argument that returns
723 non-`nil' if the argument fits a certain type. This means
724 that objects of that type are acceptable.
726 * A quoted constant--that is, `'OBJECT'. This means that
727 OBJECT itself is an acceptable value.
731 (restricted-sexp :match-alternatives (integerp 't 'nil))
733 allows integers, `t' and `nil' as legitimate values.
735 The customization buffer shows all legitimate values using their
736 read syntax, and the user edits them textually.
738 `(cons CAR-TYPE CDR-TYPE)'
739 The value must be a cons cell, its CAR must fit CAR-TYPE, and its
740 CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
741 customization type which matches values such as `("foo" . foo)'.
743 In the customization buffer, the CAR and the CDR are displayed and
744 edited separately, each according to the type that you specify for
747 `(list ELEMENT-TYPES...)'
748 The value must be a list with exactly as many elements as the
749 ELEMENT-TYPES you have specified; and each element must fit the
750 corresponding ELEMENT-TYPE.
752 For example, `(list integer string function)' describes a list of
753 three elements; the first element must be an integer, the second a
754 string, and the third a function.
756 In the customization buffer, the each element is displayed and
757 edited separately, according to the type specified for it.
759 `(vector ELEMENT-TYPES...)'
760 Like `list' except that the value must be a vector instead of a
761 list. The elements work the same as in `list'.
763 `(choice ALTERNATIVE-TYPES...)'
764 The value must fit at least one of ALTERNATIVE-TYPES. For
765 example, `(choice integer string)' allows either an integer or a
768 In the customization buffer, the user selects one of the
769 alternatives using a menu, and can then edit the value in the
770 usual way for that alternative.
772 Normally the strings in this menu are determined automatically
773 from the choices; however, you can specify different strings for
774 the menu by including the `:tag' keyword in the alternatives. For
775 example, if an integer stands for a number of spaces, while a
776 string is text to use verbatim, you might write the customization
779 (choice (integer :tag "Number of spaces")
780 (string :tag "Literal text"))
782 so that the menu offers `Number of spaces' and `Literal Text'.
784 In any alternative for which `nil' is not a valid value, other than
785 a `const', you should specify a valid default for that alternative
786 using the `:value' keyword. *Note Type Keywords::.
789 The value must be VALUE--nothing else is allowed.
791 The main use of `const' is inside of `choice'. For example,
792 `(choice integer (const nil))' allows either an integer or `nil'.
794 `:tag' is often used with `const', inside of `choice'. For
797 (choice (const :tag "Yes" t)
798 (const :tag "No" nil)
799 (const :tag "Ask" foo))
801 `(function-item FUNCTION)'
802 Like `const', but used for values which are functions. This
803 displays the documentation string as well as the function name.
804 The documentation string is either the one you specify with
805 `:doc', or FUNCTION's own documentation string.
807 `(variable-item VARIABLE)'
808 Like `const', but used for values which are variable names. This
809 displays the documentation string as well as the variable name.
810 The documentation string is either the one you specify with
811 `:doc', or VARIABLE's own documentation string.
814 The value must be a list and each element of the list must be one
815 of the ELEMENTS specified. This appears in the customization
816 buffer as a checklist.
818 `(repeat ELEMENT-TYPE)'
819 The value must be a list and each element of the list must fit the
820 type ELEMENT-TYPE. This appears in the customization buffer as a
821 list of elements, with `[INS]' and `[DEL]' buttons for adding more
822 elements or removing elements.
825 File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
830 The `:inline' feature lets you splice a variable number of elements
831 into the middle of a list or vector. You use it in a `set', `choice'
832 or `repeat' type which appears among the element-types of a `list' or
835 Normally, each of the element-types in a `list' or `vector'
836 describes one and only one element of the list or vector. Thus, if an
837 element-type is a `repeat', that specifies a list of unspecified length
838 which appears as one element.
840 But when the element-type uses `:inline', the value it matches is
841 merged directly into the containing sequence. For example, if it
842 matches a list with three elements, those become three elements of the
843 overall sequence. This is analogous to using `,@' in the backquote
846 For example, to specify a list whose first element must be `t' and
847 whose remaining arguments should be zero or more of `foo' and `bar',
848 use this customization type:
850 (list (const t) (set :inline t foo bar))
852 This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
855 When the element-type is a `choice', you use `:inline' not in the
856 `choice' itself, but in (some of) the alternatives of the `choice'.
857 For example, to match a list which must start with a file name,
858 followed either by the symbol `t' or two strings, use this
863 (list :inline t string string)))
865 If the user chooses the first alternative in the choice, then the
866 overall list has two elements and the second element is `t'. If the
867 user chooses the second alternative, then the overall list has three
868 elements and the second and third must be strings.
871 File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
876 You can specify keyword-argument pairs in a customization type after
877 the type name symbol. Here are the keywords you can use, and their
881 This is used for a type that appears as an alternative inside of
882 `choice'; it specifies the default value to use, at first, if and
883 when the user selects this alternative with the menu in the
884 customization buffer.
886 Of course, if the actual value of the option fits this
887 alternative, it will appear showing the actual value, not DEFAULT.
889 If `nil' is not a valid value for the alternative, then it is
890 essential to specify a valid default with `:value'.
892 `:format FORMAT-STRING'
893 This string will be inserted in the buffer to represent the value
894 corresponding to the type. The following `%' escapes are available
895 for use in FORMAT-STRING:
898 Display the text BUTTON marked as a button. The `:action'
899 attribute specifies what the button will do if the user
900 invokes it; its value is a function which takes two
901 arguments--the widget which the button appears in, and the
904 There is no way to specify two different buttons with
908 Show SAMPLE in a special face specified by `:sample-face'.
911 Substitute the item's value. How the value is represented
912 depends on the kind of item, and (for variables) on the
916 Substitute the item's documentation string.
919 Like `%d', but if the documentation string is more than one
920 line, add an active field to control whether to show all of
921 it or just the first line.
924 Substitute the tag here. You specify the tag with the `:tag'
928 Display a literal `%'.
931 Perform ACTION if the user clicks on a button.
934 Use the face FACE (a face name or a list of face names) for button
935 text displayed with `%[...%]'.
937 `:button-prefix PREFIX'
938 `:button-suffix SUFFIX'
939 These specify the text to display before and after a button. Each
946 The string is inserted literally.
949 The symbol's value is used.
952 Use TAG (a string) as the tag for the value (or part of the value)
953 that corresponds to this type.
956 Use DOC as the documentation string for this value (or part of the
957 value) that corresponds to this type. In order for this to work,
958 you must specify a value for `:format', and use `%d' or `%h' in
961 The usual reason to specify a documentation string for a type is to
962 provide more information about the meanings of alternatives inside
963 a `:choice' type or the parts of some other composite type.
965 `:help-echo MOTION-DOC'
966 When you move to this item with `widget-forward' or
967 `widget-backward', it will display the string MOTION-DOC in the
971 Specify how to decide whether a value matches the type. The
972 corresponding value, FUNCTION, should be a function that accepts
973 two arguments, a widget and a value; it should return non-`nil' if
974 the value is acceptable.
977 File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
982 Loading a file of Lisp code means bringing its contents into the Lisp
983 environment in the form of Lisp objects. XEmacs finds and opens the
984 file, reads the text, evaluates each form, and then closes the file.
986 The load functions evaluate all the expressions in a file just as
987 the `eval-current-buffer' function evaluates all the expressions in a
988 buffer. The difference is that the load functions read and evaluate
989 the text in the file as found on disk, not the text in an Emacs buffer.
991 The loaded file must contain Lisp expressions, either as source code
992 or as byte-compiled code. Each form in the file is called a "top-level
993 form". There is no special format for the forms in a loadable file;
994 any form in a file may equally well be typed directly into a buffer and
995 evaluated there. (Indeed, most code is tested this way.) Most often,
996 the forms are function definitions and variable definitions.
998 A file containing Lisp code is often called a "library". Thus, the
999 "Rmail library" is a file containing code for Rmail mode. Similarly, a
1000 "Lisp library directory" is a directory of files containing Lisp code.
1004 * How Programs Do Loading:: The `load' function and others.
1005 * Autoload:: Setting up a function to autoload.
1006 * Repeated Loading:: Precautions about loading a file twice.
1007 * Named Features:: Loading a library if it isn't already loaded.
1008 * Unloading:: How to ``unload'' a library that was loaded.
1009 * Hooks for Loading:: Providing code to be run when
1010 particular libraries are loaded.
1013 File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
1015 How Programs Do Loading
1016 =======================
1018 XEmacs Lisp has several interfaces for loading. For example,
1019 `autoload' creates a placeholder object for a function in a file;
1020 trying to call the autoloading function loads the file to get the
1021 function's real definition (*note Autoload::). `require' loads a file
1022 if it isn't already loaded (*note Named Features::). Ultimately, all
1023 these facilities call the `load' function to do the work.
1025 - Function: load filename &optional missing-ok nomessage nosuffix
1026 This function finds and opens a file of Lisp code, evaluates all
1027 the forms in it, and closes the file.
1029 To find the file, `load' first looks for a file named
1030 `FILENAME.elc', that is, for a file whose name is FILENAME with
1031 `.elc' appended. If such a file exists, it is loaded. If there
1032 is no file by that name, then `load' looks for a file named
1033 `FILENAME.el'. If that file exists, it is loaded. Finally, if
1034 neither of those names is found, `load' looks for a file named
1035 FILENAME with nothing appended, and loads it if it exists. (The
1036 `load' function is not clever about looking at FILENAME. In the
1037 perverse case of a file named `foo.el.el', evaluation of `(load
1038 "foo.el")' will indeed find it.)
1040 If the optional argument NOSUFFIX is non-`nil', then the suffixes
1041 `.elc' and `.el' are not tried. In this case, you must specify
1042 the precise file name you want.
1044 If FILENAME is a relative file name, such as `foo' or
1045 `baz/foo.bar', `load' searches for the file using the variable
1046 `load-path'. It appends FILENAME to each of the directories
1047 listed in `load-path', and loads the first file it finds whose name
1048 matches. The current default directory is tried only if it is
1049 specified in `load-path', where `nil' stands for the default
1050 directory. `load' tries all three possible suffixes in the first
1051 directory in `load-path', then all three suffixes in the second
1052 directory, and so on.
1054 If you get a warning that `foo.elc' is older than `foo.el', it
1055 means you should consider recompiling `foo.el'. *Note Byte
1058 Messages like `Loading foo...' and `Loading foo...done' appear in
1059 the echo area during loading unless NOMESSAGE is non-`nil'.
1061 Any unhandled errors while loading a file terminate loading. If
1062 the load was done for the sake of `autoload', any function
1063 definitions made during the loading are undone.
1065 If `load' can't find the file to load, then normally it signals the
1066 error `file-error' (with `Cannot open load file FILENAME'). But
1067 if MISSING-OK is non-`nil', then `load' just returns `nil'.
1069 You can use the variable `load-read-function' to specify a function
1070 for `load' to use instead of `read' for reading expressions. See
1073 `load' returns `t' if the file loads successfully.
1075 - User Option: load-path
1076 The value of this variable is a list of directories to search when
1077 loading files with `load'. Each element is a string (which must be
1078 a directory name) or `nil' (which stands for the current working
1079 directory). The value of `load-path' is initialized from the
1080 environment variable `EMACSLOADPATH', if that exists; otherwise its
1081 default value is specified in `emacs/src/paths.h' when XEmacs is
1084 The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
1085 (or `;', according to the operating system) separates directory
1086 names, and `.' is used for the current default directory. Here is
1087 an example of how to set your `EMACSLOADPATH' variable from a
1088 `csh' `.login' file:
1090 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
1092 Here is how to set it using `sh':
1094 export EMACSLOADPATH
1095 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
1097 Here is an example of code you can place in a `.emacs' file to add
1098 several directories to the front of your default `load-path':
1101 (append (list nil "/user/bil/emacs"
1102 "/usr/local/lisplib"
1106 In this example, the path searches the current working directory
1107 first, followed then by the `/user/bil/emacs' directory, the
1108 `/usr/local/lisplib' directory, and the `~/emacs' directory, which
1109 are then followed by the standard directories for Lisp code.
1111 The command line options `-l' or `-load' specify a Lisp library to
1112 load as part of Emacs startup. Since this file might be in the
1113 current directory, Emacs 18 temporarily adds the current directory
1114 to the front of `load-path' so the file can be found there. Newer
1115 Emacs versions also find such files in the current directory, but
1116 without altering `load-path'.
1118 Dumping Emacs uses a special value of `load-path'. If the value of
1119 `load-path' at the end of dumping is unchanged (that is, still the
1120 same special value), the dumped Emacs switches to the ordinary
1121 `load-path' value when it starts up, as described above. But if
1122 `load-path' has any other value at the end of dumping, that value
1123 is used for execution of the dumped Emacs also.
1125 Therefore, if you want to change `load-path' temporarily for
1126 loading a few libraries in `site-init.el' or `site-load.el', you
1127 should bind `load-path' locally with `let' around the calls to
1130 - Function: locate-file filename path-list &optional suffixes mode
1131 This function searches for a file in the same way that `load' does,
1132 and returns the file found (if any). (In fact, `load' uses this
1133 function to search through `load-path'.) It searches for FILENAME
1134 through PATH-LIST, expanded by one of the optional SUFFIXES
1135 (string of suffixes separated by `:'s), checking for access MODE
1136 (0|1|2|4 = exists|executable|writeable|readable), default readable.
1138 `locate-file' keeps hash tables of the directories it searches
1139 through, in order to speed things up. It tries valiantly to not
1140 get confused in the face of a changing and unpredictable
1141 environment, but can occasionally get tripped up. In this case,
1142 you will have to call `locate-file-clear-hashing' to get it back
1143 on track. See that function for details.
1145 - Function: locate-file-clear-hashing path
1146 This function clears the hash records for the specified list of
1147 directories. `locate-file' uses a hashing scheme to speed lookup,
1148 and will correctly track the following environmental changes:
1150 * changes of any sort to the list of directories to be searched.
1152 * addition and deletion of non-shadowing files (see below) from
1153 the directories in the list.
1155 * byte-compilation of a .el file into a .elc file.
1157 `locate-file' will primarily get confused if you add a file that
1158 shadows (i.e. has the same name as) another file further down in
1159 the directory list. In this case, you must call
1160 `locate-file-clear-hashing'.
1162 - Variable: load-in-progress
1163 This variable is non-`nil' if Emacs is in the process of loading a
1164 file, and it is `nil' otherwise.
1166 - Variable: load-read-function
1167 This variable specifies an alternate expression-reading function
1168 for `load' and `eval-region' to use instead of `read'. The
1169 function should accept one argument, just as `read' does.
1171 Normally, the variable's value is `nil', which means those
1172 functions should use `read'.
1174 - User Option: load-warn-when-source-newer
1175 This variable specifies whether `load' should check whether the
1176 source is newer than the binary. If this variable is true, then
1177 when a `.elc' file is being loaded and the corresponding `.el' is
1178 newer, a warning message will be printed. The default is `nil',
1179 but it is bound to `t' during the initial loadup.
1181 - User Option: load-warn-when-source-only
1182 This variable specifies whether `load' should warn when loading a
1183 `.el' file instead of an `.elc'. If this variable is true, then
1184 when `load' is called with a filename without an extension, and
1185 the `.elc' version doesn't exist but the `.el' version does, then
1186 a message will be printed. If an explicit extension is passed to
1187 `load', no warning will be printed. The default is `nil', but it
1188 is bound to `t' during the initial loadup.
1190 - User Option: load-ignore-elc-files
1191 This variable specifies whether `load' should ignore `.elc' files
1192 when a suffix is not given. This is normally used only to
1193 bootstrap the `.elc' files when building XEmacs, when you use the
1194 command `make all-elc'. (This forces the `.el' versions to be
1195 loaded in the process of compiling those same files, so that
1196 existing out-of-date `.elc' files do not make it mess things up.)
1198 To learn how `load' is used to build XEmacs, see *Note Building