1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
55 Macros and Byte Compilation
56 ===========================
58 You might ask why we take the trouble to compute an expansion for a
59 macro and then evaluate the expansion. Why not have the macro body
60 produce the desired results directly? The reason has to do with
63 When a macro call appears in a Lisp program being compiled, the Lisp
64 compiler calls the macro definition just as the interpreter would, and
65 receives an expansion. But instead of evaluating this expansion, it
66 compiles the expansion as if it had appeared directly in the program.
67 As a result, the compiled code produces the value and side effects
68 intended for the macro, but executes at full compiled speed. This would
69 not work if the macro body computed the value and side effects
70 itself--they would be computed at compile time, which is not useful.
72 In order for compilation of macro calls to work, the macros must be
73 defined in Lisp when the calls to them are compiled. The compiler has a
74 special feature to help you do this: if a file being compiled contains a
75 `defmacro' form, the macro is defined temporarily for the rest of the
76 compilation of that file. To use this feature, you must define the
77 macro in the same file where it is used and before its first use.
79 Byte-compiling a file executes any `require' calls at top-level in
80 the file. This is in case the file needs the required packages for
81 proper compilation. One way to ensure that necessary macro definitions
82 are available during compilation is to require the files that define
83 them (*note Named Features::). To avoid loading the macro definition
84 files when someone _runs_ the compiled program, write
85 `eval-when-compile' around the `require' calls (*note Eval During
89 File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
94 A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
95 function; expansion of the macro works by applying the function (with
96 `apply') to the list of unevaluated argument-expressions from the macro
99 It is possible to use an anonymous Lisp macro just like an anonymous
100 function, but this is never done, because it does not make sense to pass
101 an anonymous macro to functionals such as `mapcar'. In practice, all
102 Lisp macros have names, and they are usually defined with the special
105 - Special Form: defmacro name argument-list body-forms...
106 `defmacro' defines the symbol NAME as a macro that looks like this:
108 (macro lambda ARGUMENT-LIST . BODY-FORMS)
110 This macro object is stored in the function cell of NAME. The
111 value returned by evaluating the `defmacro' form is NAME, but
112 usually we ignore this value.
114 The shape and meaning of ARGUMENT-LIST is the same as in a
115 function, and the keywords `&rest' and `&optional' may be used
116 (*note Argument List::). Macros may have a documentation string,
117 but any `interactive' declaration is ignored since macros cannot be
118 called interactively.
121 File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
126 Macros often need to construct large list structures from a mixture
127 of constants and nonconstant parts. To make this easier, use the macro
128 ``' (often called "backquote").
130 Backquote allows you to quote a list, but selectively evaluate
131 elements of that list. In the simplest case, it is identical to the
132 special form `quote' (*note Quoting::). For example, these two forms
133 yield identical results:
135 `(a list of (+ 2 3) elements)
136 => (a list of (+ 2 3) elements)
137 '(a list of (+ 2 3) elements)
138 => (a list of (+ 2 3) elements)
140 The special marker `,' inside of the argument to backquote indicates
141 a value that isn't constant. Backquote evaluates the argument of `,'
142 and puts the value in the list structure:
144 (list 'a 'list 'of (+ 2 3) 'elements)
145 => (a list of 5 elements)
146 `(a list of ,(+ 2 3) elements)
147 => (a list of 5 elements)
149 You can also "splice" an evaluated value into the resulting list,
150 using the special marker `,@'. The elements of the spliced list become
151 elements at the same level as the other elements of the resulting list.
152 The equivalent code without using ``' is often unreadable. Here are
155 (setq some-list '(2 3))
157 (cons 1 (append some-list '(4) some-list))
159 `(1 ,@some-list 4 ,@some-list)
162 (setq list '(hack foo bar))
166 (cons 'words (append (cdr list) '(as elements)))))
167 => (use the words foo bar as elements)
168 `(use the words ,@(cdr list) as elements)
169 => (use the words foo bar as elements)
171 In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
172 version 19.29), ``' used a different syntax which required an
173 extra level of parentheses around the entire backquote construct.
174 Likewise, each `,' or `,@' substitution required an extra level of
175 parentheses surrounding both the `,' or `,@' and the following
176 expression. The old syntax required whitespace between the ``',
177 `,' or `,@' and the following expression.
179 This syntax is still accepted, but no longer recommended except for
180 compatibility with old Emacs versions.
183 File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
185 Common Problems Using Macros
186 ============================
188 The basic facts of macro expansion have counterintuitive
189 consequences. This section describes some important consequences that
190 can lead to trouble, and rules to follow to avoid trouble.
194 * Argument Evaluation:: The expansion should evaluate each macro arg once.
195 * Surprising Local Vars:: Local variable bindings in the expansion
196 require special care.
197 * Eval During Expansion:: Don't evaluate them; put them in the expansion.
198 * Repeated Expansion:: Avoid depending on how many times expansion is done.
201 File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
203 Evaluating Macro Arguments Repeatedly
204 -------------------------------------
206 When defining a macro you must pay attention to the number of times
207 the arguments will be evaluated when the expansion is executed. The
208 following macro (used to facilitate iteration) illustrates the problem.
209 This macro allows us to write a simple "for" loop such as one might
212 (defmacro for (var from init to final do &rest body)
213 "Execute a simple \"for\" loop.
214 For example, (for i from 1 to 10 do (print i))."
215 (list 'let (list (list var init))
216 (cons 'while (cons (list '<= var final)
217 (append body (list (list 'inc var)))))))
220 (for i from 1 to 3 do
221 (setq square (* i i))
222 (princ (format "\n%d %d" i square)))
226 (setq square (* i i))
227 (princ (format "%d %d" i square))
235 (The arguments `from', `to', and `do' in this macro are "syntactic
236 sugar"; they are entirely ignored. The idea is that you will write
237 noise words (such as `from', `to', and `do') in those positions in the
240 Here's an equivalent definition simplified through use of backquote:
242 (defmacro for (var from init to final do &rest body)
243 "Execute a simple \"for\" loop.
244 For example, (for i from 1 to 10 do (print i))."
246 (while (<= ,var ,final)
250 Both forms of this definition (with backquote and without) suffer
251 from the defect that FINAL is evaluated on every iteration. If FINAL
252 is a constant, this is not a problem. If it is a more complex form,
253 say `(long-complex-calculation x)', this can slow down the execution
254 significantly. If FINAL has side effects, executing it more than once
255 is probably incorrect.
257 A well-designed macro definition takes steps to avoid this problem by
258 producing an expansion that evaluates the argument expressions exactly
259 once unless repeated evaluation is part of the intended purpose of the
260 macro. Here is a correct expansion for the `for' macro:
265 (setq square (* i i))
266 (princ (format "%d %d" i square))
269 Here is a macro definition that creates this expansion:
271 (defmacro for (var from init to final do &rest body)
272 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
279 Unfortunately, this introduces another problem. Proceed to the
283 File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
285 Local Variables in Macro Expansions
286 -----------------------------------
288 In the previous section, the definition of `for' was fixed as
289 follows to make the expansion evaluate the macro arguments the proper
292 (defmacro for (var from init to final do &rest body)
293 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
300 The new definition of `for' has a new problem: it introduces a local
301 variable named `max' which the user does not expect. This causes
302 trouble in examples such as the following:
305 (for x from 0 to 10 do
306 (let ((this (frob x)))
310 The references to `max' inside the body of the `for', which are
311 supposed to refer to the user's binding of `max', really access the
312 binding made by `for'.
314 The way to correct this is to use an uninterned symbol instead of
315 `max' (*note Creating Symbols::). The uninterned symbol can be bound
316 and referred to just like any other symbol, but since it is created by
317 `for', we know that it cannot already appear in the user's program.
318 Since it is not interned, there is no way the user can put it into the
319 program later. It will never appear anywhere except where put by
320 `for'. Here is a definition of `for' that works this way:
322 (defmacro for (var from init to final do &rest body)
323 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
324 (let ((tempvar (make-symbol "max")))
327 (while (<= ,var ,tempvar)
331 This creates an uninterned symbol named `max' and puts it in the
332 expansion instead of the usual interned symbol `max' that appears in
333 expressions ordinarily.
336 File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
338 Evaluating Macro Arguments in Expansion
339 ---------------------------------------
341 Another problem can happen if you evaluate any of the macro argument
342 expressions during the computation of the expansion, such as by calling
343 `eval' (*note Eval::). If the argument is supposed to refer to the
344 user's variables, you may have trouble if the user happens to use a
345 variable with the same name as one of the macro arguments. Inside the
346 macro body, the macro argument binding is the most local binding of this
347 variable, so any references inside the form being evaluated do refer to
348 it. Here is an example:
351 (list 'setq (eval a) t))
354 (foo x) ==> (setq b t)
355 => t ; and `b' has been set.
358 (foo a) ==> (setq a t)
359 => t ; but this set `a', not `c'.
361 It makes a difference whether the user's variable is named `a' or
362 `x', because `a' conflicts with the macro argument variable `a'.
364 Another reason not to call `eval' in a macro definition is that it
365 probably won't do what you intend in a compiled program. The
366 byte-compiler runs macro definitions while compiling the program, when
367 the program's own computations (which you might have wished to access
368 with `eval') don't occur and its local variable bindings don't exist.
370 The safe way to work with the run-time value of an expression is to
371 put the expression into the macro expansion, so that its value is
372 computed as part of executing the expansion.
375 File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
377 How Many Times is the Macro Expanded?
378 -------------------------------------
380 Occasionally problems result from the fact that a macro call is
381 expanded each time it is evaluated in an interpreted function, but is
382 expanded only once (during compilation) for a compiled function. If the
383 macro definition has side effects, they will work differently depending
384 on how many times the macro is expanded.
386 In particular, constructing objects is a kind of side effect. If the
387 macro is called once, then the objects are constructed only once. In
388 other words, the same structure of objects is used each time the macro
389 call is executed. In interpreted operation, the macro is reexpanded
390 each time, producing a fresh collection of objects each time. Usually
391 this does not matter--the objects have the same contents whether they
392 are shared or not. But if the surrounding program does side effects on
393 the objects, it makes a difference whether they are shared. Here is an
396 (defmacro empty-object ()
397 (list 'quote (cons nil nil)))
399 (defun initialize (condition)
400 (let ((object (empty-object)))
402 (setcar object condition))
405 If `initialize' is interpreted, a new list `(nil)' is constructed each
406 time `initialize' is called. Thus, no side effect survives between
407 calls. If `initialize' is compiled, then the macro `empty-object' is
408 expanded during compilation, producing a single "constant" `(nil)' that
409 is reused and altered each time `initialize' is called.
411 One way to avoid pathological cases like this is to think of
412 `empty-object' as a funny kind of constant, not as a memory allocation
413 construct. You wouldn't use `setcar' on a constant such as `'(nil)',
414 so naturally you won't use it on `(empty-object)' either.
417 File: lispref.info, Node: Customization, Up: Top
419 Writing Customization Definitions
420 *********************************
422 This chapter describes how to declare user options for customization,
423 and also customization groups for classifying them. We use the term
424 "customization item" to include both kinds of customization
425 definitions--as well as face definitions.
430 * Group Definitions::
431 * Variable Definitions::
432 * Customization Types::
435 File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
437 Common Keywords for All Kinds of Items
438 ======================================
440 All kinds of customization declarations (for variables and groups,
441 and for faces) accept keyword arguments for specifying various
442 information. This section describes some keywords that apply to all
445 All of these keywords, except `:tag', can be used more than once in
446 a given item. Each use of the keyword has an independent effect. The
447 keyword `:tag' is an exception because any given item can only display
451 Use NAME, a string, instead of the item's name, to label the item
452 in customization menus and buffers.
455 Put this customization item in group GROUP. When you use `:group'
456 in a `defgroup', it makes the new group a subgroup of GROUP.
458 If you use this keyword more than once, you can put a single item
459 into more than one group. Displaying any of those groups will
460 show this item. Be careful not to overdo this!
463 Include an external link after the documentation string for this
464 item. This is a sentence containing an active field which
465 references some other documentation.
467 There are three alternatives you can use for LINK-DATA:
469 `(custom-manual INFO-NODE)'
470 Link to an Info node; INFO-NODE is a string which specifies
471 the node name, as in `"(emacs)Top"'. The link appears as
472 `[manual]' in the customization buffer.
474 `(info-link INFO-NODE)'
475 Like `custom-manual' except that the link appears in the
476 customization buffer with the Info node name.
479 Link to a web page; URL is a string which specifies the URL.
480 The link appears in the customization buffer as URL.
482 You can specify the text to use in the customization buffer by
483 adding `:tag NAME' after the first element of the LINK-DATA; for
484 example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
485 Emacs manual which appears in the buffer as `foo'.
487 An item can have more than one external link; however, most items
491 Load file FILE (a string) before displaying this customization
492 item. Loading is done with `load-library', and only if the file is
496 Require feature FEATURE (a symbol) when installing a value for
497 this item (an option or a face) that was saved using the
498 customization feature. This is done by calling `require'.
500 The most common reason to use `:require' is when a variable enables
501 a feature such as a minor mode, and just setting the variable
502 won't have any effect unless the code which implements the mode is
506 File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
508 Defining Custom Groups
509 ======================
511 Each Emacs Lisp package should have one main customization group
512 which contains all the options, faces and other groups in the package.
513 If the package has a small number of options and faces, use just one
514 group and put everything in it. When there are more than twelve or so
515 options and faces, then you should structure them into subgroups, and
516 put the subgroups under the package's main customization group. It is
517 OK to put some of the options and faces in the package's main group
518 alongside the subgroups.
520 The package's main or only group should be a member of one or more of
521 the standard customization groups. (To display the full list of them,
522 use `M-x customize'.) Choose one or more of them (but not too many),
523 and add your group to each of them using the `:group' keyword.
525 The way to declare new customization groups is with `defgroup'.
527 - Macro: defgroup group members doc [keyword value]...
528 Declare GROUP as a customization group containing MEMBERS. Do not
529 quote the symbol GROUP. The argument DOC specifies the
530 documentation string for the group.
532 The argument MEMBERS is a list specifying an initial set of
533 customization items to be members of the group. However, most
534 often MEMBERS is `nil', and you specify the group's members by
535 using the `:group' keyword when defining those members.
537 If you want to specify group members through MEMBERS, each element
538 should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
539 WIDGET is a widget type for editing that symbol. Useful widgets
540 are `custom-variable' for a variable, `custom-face' for a face,
541 and `custom-group' for a group.
543 In addition to the common keywords (*note Common Keywords::), you
544 can use this keyword in `defgroup':
547 If the name of an item in the group starts with PREFIX, then
548 the tag for that item is constructed (by default) by omitting
551 One group can have any number of prefixes.
554 File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
556 Defining Customization Variables
557 ================================
559 Use `defcustom' to declare user-editable variables.
561 - Macro: defcustom option default doc [keyword value]...
562 Declare OPTION as a customizable user option variable. Do not
563 quote OPTION. The argument DOC specifies the documentation string
566 If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
567 should be an expression to compute the value; be careful in
568 writing it, because it can be evaluated on more than one occasion.
570 The following additional keywords are defined:
573 Use TYPE as the data type for this option. It specifies which
574 values are legitimate, and how to display the value. *Note
575 Customization Types::, for more information.
578 Specify LIST as the list of reasonable values for use in this
581 Currently this is meaningful only when the type is `hook'.
582 In that case, the elements of LIST should be functions that
583 are useful as elements of the hook value. The user is not
584 restricted to using only these functions, but they are
585 offered as convenient alternatives.
588 This option specifies that the variable was first introduced,
589 or its default value was changed, in Emacs version VERSION.
590 The value VERSION must be a string. For example,
592 (defcustom foo-max 34
593 "*Maximum number of foo's allowed."
599 Specify SETFUNCTION as the way to change the value of this
600 option. The function SETFUNCTION should take two arguments,
601 a symbol and the new value, and should do whatever is
602 necessary to update the value properly for this option (which
603 may not mean simply setting the option as a Lisp variable).
604 The default for SETFUNCTION is `set-default'.
607 Specify GETFUNCTION as the way to extract the value of this
608 option. The function GETFUNCTION should take one argument, a
609 symbol, and should return the "current value" for that symbol
610 (which need not be the symbol's Lisp value). The default is
613 `:initialize FUNCTION'
614 FUNCTION should be a function used to initialize the variable
615 when the `defcustom' is evaluated. It should take two
616 arguments, the symbol and value. Here are some predefined
617 functions meant for use in this way:
619 `custom-initialize-set'
620 Use the variable's `:set' function to initialize the
621 variable, but do not reinitialize it if it is already
622 non-void. This is the default `:initialize' function.
624 `custom-initialize-default'
625 Like `custom-initialize-set', but use the function
626 `set-default' to set the variable, instead of the
627 variable's `:set' function. This is the usual choice
628 for a variable whose `:set' function enables or disables
629 a minor mode; with this choice, defining the variable
630 will not call the minor mode function, but customizing
631 the variable will do so.
633 `custom-initialize-reset'
634 Always use the `:set' function to initialize the
635 variable. If the variable is already non-void, reset it
636 by calling the `:set' function using the current value
637 (returned by the `:get' method).
639 `custom-initialize-changed'
640 Use the `:set' function to initialize the variable, if
641 it is already set or has been customized; otherwise,
642 just use `set-default'.
644 The `:require' option is useful for an option that turns on the
645 operation of a certain feature. Assuming that the package is coded to
646 check the value of the option, you still need to arrange for the package
647 to be loaded. You can do that with `:require'. *Note Common
648 Keywords::. Here is an example, from the library `paren.el':
650 (defcustom show-paren-mode nil
651 "Toggle Show Paren mode...."
652 :set (lambda (symbol value)
653 (show-paren-mode (or value 0)))
654 :initialize 'custom-initialize-default
656 :group 'paren-showing
659 Internally, `defcustom' uses the symbol property `standard-value' to
660 record the expression for the default value, and `saved-value' to
661 record the value saved by the user with the customization buffer. The
662 `saved-value' property is actually a list whose car is an expression
663 which evaluates to the value.
666 File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
671 When you define a user option with `defcustom', you must specify its
672 "customization type". That is a Lisp object which describes (1) which
673 values are legitimate and (2) how to display the value in the
674 customization buffer for editing.
676 You specify the customization type in `defcustom' with the `:type'
677 keyword. The argument of `:type' is evaluated; since types that vary
678 at run time are rarely useful, normally you use a quoted constant. For
681 (defcustom diff-command "diff"
682 "*The command to use to run diff."
686 In general, a customization type is a list whose first element is a
687 symbol, one of the customization type names defined in the following
688 sections. After this symbol come a number of arguments, depending on
689 the symbol. Between the type symbol and its arguments, you can
690 optionally write keyword-value pairs (*note Type Keywords::).
692 Some of the type symbols do not use any arguments; those are called
693 "simple types". For a simple type, if you do not use any keyword-value
694 pairs, you can omit the parentheses around the type symbol. For
695 example just `string' as a customization type is equivalent to
702 * Splicing into Lists::
706 File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
711 This section describes all the simple customization types.
714 The value may be any Lisp object that can be printed and read
715 back. You can use `sexp' as a fall-back for any option, if you
716 don't want to take the time to work out a more specific type to
720 The value must be an integer, and is represented textually in the
721 customization buffer.
724 The value must be a number, and is represented textually in the
725 customization buffer.
728 The value must be a string, and the customization buffer shows
729 just the contents, with no delimiting `"' characters and no
733 Like `string' except that the string must be a valid regular
737 The value must be a character code. A character code is actually
738 an integer, but this type shows the value by inserting the
739 character in the buffer, rather than by showing the number.
742 The value must be a file name, and you can do completion with
745 `(file :must-match t)'
746 The value must be a file name for an existing file, and you can do
747 completion with `M-<TAB>'.
750 The value must be a directory name, and you can do completion with
754 The value must be a symbol. It appears in the customization
755 buffer as the name of the symbol.
758 The value must be either a lambda expression or a function name.
759 When it is a function name, you can do completion with `M-<TAB>'.
762 The value must be a variable name, and you can do completion with
766 The value must be a symbol which is a face name.
769 The value is boolean--either `nil' or `t'. Note that by using
770 `choice' and `const' together (see the next section), you can
771 specify that the value must be `nil' or `t', but also specify the
772 text to describe each value in a way that fits the specific
773 meaning of the alternative.
776 File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
781 When none of the simple types is appropriate, you can use composite
782 types, which build new types from other types. Here are several ways of
785 `(restricted-sexp :match-alternatives CRITERIA)'
786 The value may be any Lisp object that satisfies one of CRITERIA.
787 CRITERIA should be a list, and each elements should be one of
790 * A predicate--that is, a function of one argument that returns
791 non-`nil' if the argument fits a certain type. This means
792 that objects of that type are acceptable.
794 * A quoted constant--that is, `'OBJECT'. This means that
795 OBJECT itself is an acceptable value.
799 (restricted-sexp :match-alternatives (integerp 't 'nil))
801 allows integers, `t' and `nil' as legitimate values.
803 The customization buffer shows all legitimate values using their
804 read syntax, and the user edits them textually.
806 `(cons CAR-TYPE CDR-TYPE)'
807 The value must be a cons cell, its CAR must fit CAR-TYPE, and its
808 CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
809 customization type which matches values such as `("foo" . foo)'.
811 In the customization buffer, the CAR and the CDR are displayed and
812 edited separately, each according to the type that you specify for
815 `(list ELEMENT-TYPES...)'
816 The value must be a list with exactly as many elements as the
817 ELEMENT-TYPES you have specified; and each element must fit the
818 corresponding ELEMENT-TYPE.
820 For example, `(list integer string function)' describes a list of
821 three elements; the first element must be an integer, the second a
822 string, and the third a function.
824 In the customization buffer, the each element is displayed and
825 edited separately, according to the type specified for it.
827 `(vector ELEMENT-TYPES...)'
828 Like `list' except that the value must be a vector instead of a
829 list. The elements work the same as in `list'.
831 `(choice ALTERNATIVE-TYPES...)'
832 The value must fit at least one of ALTERNATIVE-TYPES. For
833 example, `(choice integer string)' allows either an integer or a
836 In the customization buffer, the user selects one of the
837 alternatives using a menu, and can then edit the value in the
838 usual way for that alternative.
840 Normally the strings in this menu are determined automatically
841 from the choices; however, you can specify different strings for
842 the menu by including the `:tag' keyword in the alternatives. For
843 example, if an integer stands for a number of spaces, while a
844 string is text to use verbatim, you might write the customization
847 (choice (integer :tag "Number of spaces")
848 (string :tag "Literal text"))
850 so that the menu offers `Number of spaces' and `Literal Text'.
852 In any alternative for which `nil' is not a valid value, other than
853 a `const', you should specify a valid default for that alternative
854 using the `:value' keyword. *Note Type Keywords::.
857 The value must be VALUE--nothing else is allowed.
859 The main use of `const' is inside of `choice'. For example,
860 `(choice integer (const nil))' allows either an integer or `nil'.
862 `:tag' is often used with `const', inside of `choice'. For
865 (choice (const :tag "Yes" t)
866 (const :tag "No" nil)
867 (const :tag "Ask" foo))
869 `(function-item FUNCTION)'
870 Like `const', but used for values which are functions. This
871 displays the documentation string as well as the function name.
872 The documentation string is either the one you specify with
873 `:doc', or FUNCTION's own documentation string.
875 `(variable-item VARIABLE)'
876 Like `const', but used for values which are variable names. This
877 displays the documentation string as well as the variable name.
878 The documentation string is either the one you specify with
879 `:doc', or VARIABLE's own documentation string.
882 The value must be a list and each element of the list must be one
883 of the ELEMENTS specified. This appears in the customization
884 buffer as a checklist.
886 `(repeat ELEMENT-TYPE)'
887 The value must be a list and each element of the list must fit the
888 type ELEMENT-TYPE. This appears in the customization buffer as a
889 list of elements, with `[INS]' and `[DEL]' buttons for adding more
890 elements or removing elements.
893 File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
898 The `:inline' feature lets you splice a variable number of elements
899 into the middle of a list or vector. You use it in a `set', `choice'
900 or `repeat' type which appears among the element-types of a `list' or
903 Normally, each of the element-types in a `list' or `vector'
904 describes one and only one element of the list or vector. Thus, if an
905 element-type is a `repeat', that specifies a list of unspecified length
906 which appears as one element.
908 But when the element-type uses `:inline', the value it matches is
909 merged directly into the containing sequence. For example, if it
910 matches a list with three elements, those become three elements of the
911 overall sequence. This is analogous to using `,@' in the backquote
914 For example, to specify a list whose first element must be `t' and
915 whose remaining arguments should be zero or more of `foo' and `bar',
916 use this customization type:
918 (list (const t) (set :inline t foo bar))
920 This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
923 When the element-type is a `choice', you use `:inline' not in the
924 `choice' itself, but in (some of) the alternatives of the `choice'.
925 For example, to match a list which must start with a file name,
926 followed either by the symbol `t' or two strings, use this
931 (list :inline t string string)))
933 If the user chooses the first alternative in the choice, then the
934 overall list has two elements and the second element is `t'. If the
935 user chooses the second alternative, then the overall list has three
936 elements and the second and third must be strings.
939 File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
944 You can specify keyword-argument pairs in a customization type after
945 the type name symbol. Here are the keywords you can use, and their
949 This is used for a type that appears as an alternative inside of
950 `choice'; it specifies the default value to use, at first, if and
951 when the user selects this alternative with the menu in the
952 customization buffer.
954 Of course, if the actual value of the option fits this
955 alternative, it will appear showing the actual value, not DEFAULT.
957 If `nil' is not a valid value for the alternative, then it is
958 essential to specify a valid default with `:value'.
960 `:format FORMAT-STRING'
961 This string will be inserted in the buffer to represent the value
962 corresponding to the type. The following `%' escapes are available
963 for use in FORMAT-STRING:
966 Display the text BUTTON marked as a button. The `:action'
967 attribute specifies what the button will do if the user
968 invokes it; its value is a function which takes two
969 arguments--the widget which the button appears in, and the
972 There is no way to specify two different buttons with
976 Show SAMPLE in a special face specified by `:sample-face'.
979 Substitute the item's value. How the value is represented
980 depends on the kind of item, and (for variables) on the
984 Substitute the item's documentation string.
987 Like `%d', but if the documentation string is more than one
988 line, add an active field to control whether to show all of
989 it or just the first line.
992 Substitute the tag here. You specify the tag with the `:tag'
996 Display a literal `%'.
999 Perform ACTION if the user clicks on a button.
1002 Use the face FACE (a face name or a list of face names) for button
1003 text displayed with `%[...%]'.
1005 `:button-prefix PREFIX'
1006 `:button-suffix SUFFIX'
1007 These specify the text to display before and after a button. Each
1011 No text is inserted.
1014 The string is inserted literally.
1017 The symbol's value is used.
1020 Use TAG (a string) as the tag for the value (or part of the value)
1021 that corresponds to this type.
1024 Use DOC as the documentation string for this value (or part of the
1025 value) that corresponds to this type. In order for this to work,
1026 you must specify a value for `:format', and use `%d' or `%h' in
1029 The usual reason to specify a documentation string for a type is to
1030 provide more information about the meanings of alternatives inside
1031 a `:choice' type or the parts of some other composite type.
1033 `:help-echo MOTION-DOC'
1034 When you move to this item with `widget-forward' or
1035 `widget-backward', it will display the string MOTION-DOC in the
1039 Specify how to decide whether a value matches the type. The
1040 corresponding value, FUNCTION, should be a function that accepts
1041 two arguments, a widget and a value; it should return non-`nil' if
1042 the value is acceptable.
1045 File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
1050 Loading a file of Lisp code means bringing its contents into the Lisp
1051 environment in the form of Lisp objects. XEmacs finds and opens the
1052 file, reads the text, evaluates each form, and then closes the file.
1054 The load functions evaluate all the expressions in a file just as
1055 the `eval-current-buffer' function evaluates all the expressions in a
1056 buffer. The difference is that the load functions read and evaluate
1057 the text in the file as found on disk, not the text in an Emacs buffer.
1059 The loaded file must contain Lisp expressions, either as source code
1060 or as byte-compiled code. Each form in the file is called a "top-level
1061 form". There is no special format for the forms in a loadable file;
1062 any form in a file may equally well be typed directly into a buffer and
1063 evaluated there. (Indeed, most code is tested this way.) Most often,
1064 the forms are function definitions and variable definitions.
1066 A file containing Lisp code is often called a "library". Thus, the
1067 "Rmail library" is a file containing code for Rmail mode. Similarly, a
1068 "Lisp library directory" is a directory of files containing Lisp code.
1072 * How Programs Do Loading:: The `load' function and others.
1073 * Autoload:: Setting up a function to autoload.
1074 * Repeated Loading:: Precautions about loading a file twice.
1075 * Named Features:: Loading a library if it isn't already loaded.
1076 * Unloading:: How to ``unload'' a library that was loaded.
1077 * Hooks for Loading:: Providing code to be run when
1078 particular libraries are loaded.
1081 File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
1083 How Programs Do Loading
1084 =======================
1086 XEmacs Lisp has several interfaces for loading. For example,
1087 `autoload' creates a placeholder object for a function in a file;
1088 trying to call the autoloading function loads the file to get the
1089 function's real definition (*note Autoload::). `require' loads a file
1090 if it isn't already loaded (*note Named Features::). Ultimately, all
1091 these facilities call the `load' function to do the work.
1093 - Function: load filename &optional missing-ok nomessage nosuffix
1094 This function finds and opens a file of Lisp code, evaluates all
1095 the forms in it, and closes the file.
1097 To find the file, `load' first looks for a file named
1098 `FILENAME.elc', that is, for a file whose name is FILENAME with
1099 `.elc' appended. If such a file exists, it is loaded. If there
1100 is no file by that name, then `load' looks for a file named
1101 `FILENAME.el'. If that file exists, it is loaded. Finally, if
1102 neither of those names is found, `load' looks for a file named
1103 FILENAME with nothing appended, and loads it if it exists. (The
1104 `load' function is not clever about looking at FILENAME. In the
1105 perverse case of a file named `foo.el.el', evaluation of `(load
1106 "foo.el")' will indeed find it.)
1108 If the optional argument NOSUFFIX is non-`nil', then the suffixes
1109 `.elc' and `.el' are not tried. In this case, you must specify
1110 the precise file name you want.
1112 If FILENAME is a relative file name, such as `foo' or
1113 `baz/foo.bar', `load' searches for the file using the variable
1114 `load-path'. It appends FILENAME to each of the directories
1115 listed in `load-path', and loads the first file it finds whose name
1116 matches. The current default directory is tried only if it is
1117 specified in `load-path', where `nil' stands for the default
1118 directory. `load' tries all three possible suffixes in the first
1119 directory in `load-path', then all three suffixes in the second
1120 directory, and so on.
1122 If you get a warning that `foo.elc' is older than `foo.el', it
1123 means you should consider recompiling `foo.el'. *Note Byte
1126 Messages like `Loading foo...' and `Loading foo...done' appear in
1127 the echo area during loading unless NOMESSAGE is non-`nil'.
1129 Any unhandled errors while loading a file terminate loading. If
1130 the load was done for the sake of `autoload', any function
1131 definitions made during the loading are undone.
1133 If `load' can't find the file to load, then normally it signals the
1134 error `file-error' (with `Cannot open load file FILENAME'). But
1135 if MISSING-OK is non-`nil', then `load' just returns `nil'.
1137 You can use the variable `load-read-function' to specify a function
1138 for `load' to use instead of `read' for reading expressions. See
1141 `load' returns `t' if the file loads successfully.
1143 - User Option: load-path
1144 The value of this variable is a list of directories to search when
1145 loading files with `load'. Each element is a string (which must be
1146 a directory name) or `nil' (which stands for the current working
1147 directory). The value of `load-path' is initialized from the
1148 environment variable `EMACSLOADPATH', if that exists; otherwise its
1149 default value is specified in `emacs/src/paths.h' when XEmacs is
1152 The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
1153 (or `;', according to the operating system) separates directory
1154 names, and `.' is used for the current default directory. Here is
1155 an example of how to set your `EMACSLOADPATH' variable from a
1156 `csh' `.login' file:
1158 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
1160 Here is how to set it using `sh':
1162 export EMACSLOADPATH
1163 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
1165 Here is an example of code you can place in a `.emacs' file to add
1166 several directories to the front of your default `load-path':
1169 (append (list nil "/user/bil/emacs"
1170 "/usr/local/lisplib"
1174 In this example, the path searches the current working directory
1175 first, followed then by the `/user/bil/emacs' directory, the
1176 `/usr/local/lisplib' directory, and the `~/emacs' directory, which
1177 are then followed by the standard directories for Lisp code.
1179 The command line options `-l' or `-load' specify a Lisp library to
1180 load as part of Emacs startup. Since this file might be in the
1181 current directory, Emacs 18 temporarily adds the current directory
1182 to the front of `load-path' so the file can be found there. Newer
1183 Emacs versions also find such files in the current directory, but
1184 without altering `load-path'.
1186 Dumping Emacs uses a special value of `load-path'. If the value of
1187 `load-path' at the end of dumping is unchanged (that is, still the
1188 same special value), the dumped Emacs switches to the ordinary
1189 `load-path' value when it starts up, as described above. But if
1190 `load-path' has any other value at the end of dumping, that value
1191 is used for execution of the dumped Emacs also.
1193 Therefore, if you want to change `load-path' temporarily for
1194 loading a few libraries in `site-init.el' or `site-load.el', you
1195 should bind `load-path' locally with `let' around the calls to
1198 - Function: locate-file filename path-list &optional suffixes mode
1199 This function searches for a file in the same way that `load' does,
1200 and returns the file found (if any). (In fact, `load' uses this
1201 function to search through `load-path'.) It searches for FILENAME
1202 through PATH-LIST, expanded by one of the optional SUFFIXES
1203 (string of suffixes separated by `:'s), checking for access MODE
1204 (0|1|2|4 = exists|executable|writeable|readable), default readable.
1206 `locate-file' keeps hash tables of the directories it searches
1207 through, in order to speed things up. It tries valiantly to not
1208 get confused in the face of a changing and unpredictable
1209 environment, but can occasionally get tripped up. In this case,
1210 you will have to call `locate-file-clear-hashing' to get it back
1211 on track. See that function for details.
1213 - Function: locate-file-clear-hashing path
1214 This function clears the hash records for the specified list of
1215 directories. `locate-file' uses a hashing scheme to speed lookup,
1216 and will correctly track the following environmental changes:
1218 * changes of any sort to the list of directories to be searched.
1220 * addition and deletion of non-shadowing files (see below) from
1221 the directories in the list.
1223 * byte-compilation of a .el file into a .elc file.
1225 `locate-file' will primarily get confused if you add a file that
1226 shadows (i.e. has the same name as) another file further down in
1227 the directory list. In this case, you must call
1228 `locate-file-clear-hashing'.
1230 - Variable: load-in-progress
1231 This variable is non-`nil' if Emacs is in the process of loading a
1232 file, and it is `nil' otherwise.
1234 - Variable: load-read-function
1235 This variable specifies an alternate expression-reading function
1236 for `load' and `eval-region' to use instead of `read'. The
1237 function should accept one argument, just as `read' does.
1239 Normally, the variable's value is `nil', which means those
1240 functions should use `read'.
1242 - User Option: load-warn-when-source-newer
1243 This variable specifies whether `load' should check whether the
1244 source is newer than the binary. If this variable is true, then
1245 when a `.elc' file is being loaded and the corresponding `.el' is
1246 newer, a warning message will be printed. The default is `nil',
1247 but it is bound to `t' during the initial loadup.
1249 - User Option: load-warn-when-source-only
1250 This variable specifies whether `load' should warn when loading a
1251 `.el' file instead of an `.elc'. If this variable is true, then
1252 when `load' is called with a filename without an extension, and
1253 the `.elc' version doesn't exist but the `.el' version does, then
1254 a message will be printed. If an explicit extension is passed to
1255 `load', no warning will be printed. The default is `nil', but it
1256 is bound to `t' during the initial loadup.
1258 - User Option: load-ignore-elc-files
1259 This variable specifies whether `load' should ignore `.elc' files
1260 when a suffix is not given. This is normally used only to
1261 bootstrap the `.elc' files when building XEmacs, when you use the
1262 command `make all-elc'. (This forces the `.el' versions to be
1263 loaded in the process of compiling those same files, so that
1264 existing out-of-date `.elc' files do not make it mess things up.)
1266 To learn how `load' is used to build XEmacs, see *Note Building