1 This is Info file ../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref/lispref.texi.
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)))))))
219 (for i from 1 to 3 do
220 (setq square (* i i))
221 (princ (format "\n%d %d" i square)))
226 (setq square (* i i))
227 (princ (format "%d %d" i square))
236 (The arguments `from', `to', and `do' in this macro are "syntactic
237 sugar"; they are entirely ignored. The idea is that you will write
238 noise words (such as `from', `to', and `do') in those positions in the
241 Here's an equivalent definition simplified through use of backquote:
243 (defmacro for (var from init to final do &rest body)
244 "Execute a simple \"for\" loop.
245 For example, (for i from 1 to 10 do (print i))."
247 (while (<= ,var ,final)
251 Both forms of this definition (with backquote and without) suffer
252 from the defect that FINAL is evaluated on every iteration. If FINAL
253 is a constant, this is not a problem. If it is a more complex form,
254 say `(long-complex-calculation x)', this can slow down the execution
255 significantly. If FINAL has side effects, executing it more than once
256 is probably incorrect.
258 A well-designed macro definition takes steps to avoid this problem by
259 producing an expansion that evaluates the argument expressions exactly
260 once unless repeated evaluation is part of the intended purpose of the
261 macro. Here is a correct expansion for the `for' macro:
266 (setq square (* i i))
267 (princ (format "%d %d" i square))
270 Here is a macro definition that creates this expansion:
272 (defmacro for (var from init to final do &rest body)
273 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
280 Unfortunately, this introduces another problem. Proceed to the
284 File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
286 Local Variables in Macro Expansions
287 -----------------------------------
289 In the previous section, the definition of `for' was fixed as
290 follows to make the expansion evaluate the macro arguments the proper
293 (defmacro for (var from init to final do &rest body)
294 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
302 The new definition of `for' has a new problem: it introduces a local
303 variable named `max' which the user does not expect. This causes
304 trouble in examples such as the following:
307 (for x from 0 to 10 do
308 (let ((this (frob x)))
312 The references to `max' inside the body of the `for', which are
313 supposed to refer to the user's binding of `max', really access the
314 binding made by `for'.
316 The way to correct this is to use an uninterned symbol instead of
317 `max' (*note Creating Symbols::.). The uninterned symbol can be bound
318 and referred to just like any other symbol, but since it is created by
319 `for', we know that it cannot already appear in the user's program.
320 Since it is not interned, there is no way the user can put it into the
321 program later. It will never appear anywhere except where put by
322 `for'. Here is a definition of `for' that works this way:
324 (defmacro for (var from init to final do &rest body)
325 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
326 (let ((tempvar (make-symbol "max")))
329 (while (<= ,var ,tempvar)
333 This creates an uninterned symbol named `max' and puts it in the
334 expansion instead of the usual interned symbol `max' that appears in
335 expressions ordinarily.
338 File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
340 Evaluating Macro Arguments in Expansion
341 ---------------------------------------
343 Another problem can happen if you evaluate any of the macro argument
344 expressions during the computation of the expansion, such as by calling
345 `eval' (*note Eval::.). If the argument is supposed to refer to the
346 user's variables, you may have trouble if the user happens to use a
347 variable with the same name as one of the macro arguments. Inside the
348 macro body, the macro argument binding is the most local binding of this
349 variable, so any references inside the form being evaluated do refer to
350 it. Here is an example:
353 (list 'setq (eval a) t))
356 (foo x) ==> (setq b t)
357 => t ; and `b' has been set.
360 (foo a) ==> (setq a t)
361 => t ; but this set `a', not `c'.
363 It makes a difference whether the user's variable is named `a' or
364 `x', because `a' conflicts with the macro argument variable `a'.
366 Another reason not to call `eval' in a macro definition is that it
367 probably won't do what you intend in a compiled program. The
368 byte-compiler runs macro definitions while compiling the program, when
369 the program's own computations (which you might have wished to access
370 with `eval') don't occur and its local variable bindings don't exist.
372 The safe way to work with the run-time value of an expression is to
373 put the expression into the macro expansion, so that its value is
374 computed as part of executing the expansion.
377 File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
379 How Many Times is the Macro Expanded?
380 -------------------------------------
382 Occasionally problems result from the fact that a macro call is
383 expanded each time it is evaluated in an interpreted function, but is
384 expanded only once (during compilation) for a compiled function. If the
385 macro definition has side effects, they will work differently depending
386 on how many times the macro is expanded.
388 In particular, constructing objects is a kind of side effect. If the
389 macro is called once, then the objects are constructed only once. In
390 other words, the same structure of objects is used each time the macro
391 call is executed. In interpreted operation, the macro is reexpanded
392 each time, producing a fresh collection of objects each time. Usually
393 this does not matter--the objects have the same contents whether they
394 are shared or not. But if the surrounding program does side effects on
395 the objects, it makes a difference whether they are shared. Here is an
398 (defmacro empty-object ()
399 (list 'quote (cons nil nil)))
401 (defun initialize (condition)
402 (let ((object (empty-object)))
404 (setcar object condition))
407 If `initialize' is interpreted, a new list `(nil)' is constructed each
408 time `initialize' is called. Thus, no side effect survives between
409 calls. If `initialize' is compiled, then the macro `empty-object' is
410 expanded during compilation, producing a single "constant" `(nil)' that
411 is reused and altered each time `initialize' is called.
413 One way to avoid pathological cases like this is to think of
414 `empty-object' as a funny kind of constant, not as a memory allocation
415 construct. You wouldn't use `setcar' on a constant such as `'(nil)',
416 so naturally you won't use it on `(empty-object)' either.
419 File: lispref.info, Node: Customization, Up: Top
421 Writing Customization Definitions
422 *********************************
424 This chapter describes how to declare user options for customization,
425 and also customization groups for classifying them. We use the term
426 "customization item" to include both kinds of customization
427 definitions--as well as face definitions.
432 * Group Definitions::
433 * Variable Definitions::
434 * Customization Types::
437 File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
439 Common Keywords for All Kinds of Items
440 ======================================
442 All kinds of customization declarations (for variables and groups,
443 and for faces) accept keyword arguments for specifying various
444 information. This section describes some keywords that apply to all
447 All of these keywords, except `:tag', can be used more than once in
448 a given item. Each use of the keyword has an independent effect. The
449 keyword `:tag' is an exception because any given item can only display
453 Use NAME, a string, instead of the item's name, to label the item
454 in customization menus and buffers.
457 Put this customization item in group GROUP. When you use `:group'
458 in a `defgroup', it makes the new group a subgroup of GROUP.
460 If you use this keyword more than once, you can put a single item
461 into more than one group. Displaying any of those groups will
462 show this item. Be careful not to overdo this!
465 Include an external link after the documentation string for this
466 item. This is a sentence containing an active field which
467 references some other documentation.
469 There are three alternatives you can use for LINK-DATA:
471 `(custom-manual INFO-NODE)'
472 Link to an Info node; INFO-NODE is a string which specifies
473 the node name, as in `"(emacs)Top"'. The link appears as
474 `[manual]' in the customization buffer.
476 `(info-link INFO-NODE)'
477 Like `custom-manual' except that the link appears in the
478 customization buffer with the Info node name.
481 Link to a web page; URL is a string which specifies the URL.
482 The link appears in the customization buffer as URL.
484 You can specify the text to use in the customization buffer by
485 adding `:tag NAME' after the first element of the LINK-DATA; for
486 example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
487 Emacs manual which appears in the buffer as `foo'.
489 An item can have more than one external link; however, most items
493 Load file FILE (a string) before displaying this customization
494 item. Loading is done with `load-library', and only if the file is
498 Require feature FEATURE (a symbol) when installing a value for
499 this item (an option or a face) that was saved using the
500 customization feature. This is done by calling `require'.
502 The most common reason to use `:require' is when a variable enables
503 a feature such as a minor mode, and just setting the variable
504 won't have any effect unless the code which implements the mode is
508 File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
510 Defining Custom Groups
511 ======================
513 Each Emacs Lisp package should have one main customization group
514 which contains all the options, faces and other groups in the package.
515 If the package has a small number of options and faces, use just one
516 group and put everything in it. When there are more than twelve or so
517 options and faces, then you should structure them into subgroups, and
518 put the subgroups under the package's main customization group. It is
519 OK to put some of the options and faces in the package's main group
520 alongside the subgroups.
522 The package's main or only group should be a member of one or more of
523 the standard customization groups. (To display the full list of them,
524 use `M-x customize'.) Choose one or more of them (but not too many),
525 and add your group to each of them using the `:group' keyword.
527 The way to declare new customization groups is with `defgroup'.
529 - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
530 Declare GROUP as a customization group containing MEMBERS. Do not
531 quote the symbol GROUP. The argument DOC specifies the
532 documentation string for the group.
534 The argument MEMBERS is a list specifying an initial set of
535 customization items to be members of the group. However, most
536 often MEMBERS is `nil', and you specify the group's members by
537 using the `:group' keyword when defining those members.
539 If you want to specify group members through MEMBERS, each element
540 should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
541 WIDGET is a widget type for editing that symbol. Useful widgets
542 are `custom-variable' for a variable, `custom-face' for a face,
543 and `custom-group' for a group.
545 In addition to the common keywords (*note Common Keywords::.), you
546 can use this keyword in `defgroup':
549 If the name of an item in the group starts with PREFIX, then
550 the tag for that item is constructed (by default) by omitting
553 One group can have any number of prefixes.
556 File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
558 Defining Customization Variables
559 ================================
561 Use `defcustom' to declare user-editable variables.
563 - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
564 Declare OPTION as a customizable user option variable. Do not
565 quote OPTION. The argument DOC specifies the documentation string
568 If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
569 should be an expression to compute the value; be careful in
570 writing it, because it can be evaluated on more than one occasion.
572 The following additional keywords are defined:
575 Use TYPE as the data type for this option. It specifies which
576 values are legitimate, and how to display the value. *Note
577 Customization Types::, for more information.
580 Specify LIST as the list of reasonable values for use in this
583 Currently this is meaningful only when the type is `hook'.
584 In that case, the elements of LIST should be functions that
585 are useful as elements of the hook value. The user is not
586 restricted to using only these functions, but they are
587 offered as convenient alternatives.
590 This option specifies that the variable was first introduced,
591 or its default value was changed, in Emacs version VERSION.
592 The value VERSION must be a string. For example,
594 (defcustom foo-max 34
595 "*Maximum number of foo's allowed."
601 Specify SETFUNCTION as the way to change the value of this
602 option. The function SETFUNCTION should take two arguments,
603 a symbol and the new value, and should do whatever is
604 necessary to update the value properly for this option (which
605 may not mean simply setting the option as a Lisp variable).
606 The default for SETFUNCTION is `set-default'.
609 Specify GETFUNCTION as the way to extract the value of this
610 option. The function GETFUNCTION should take one argument, a
611 symbol, and should return the "current value" for that symbol
612 (which need not be the symbol's Lisp value). The default is
615 `:initialize FUNCTION'
616 FUNCTION should be a function used to initialize the variable
617 when the `defcustom' is evaluated. It should take two
618 arguments, the symbol and value. Here are some predefined
619 functions meant for use in this way:
621 `custom-initialize-set'
622 Use the variable's `:set' function to initialize the
623 variable, but do not reinitialize it if it is already
624 non-void. This is the default `:initialize' function.
626 `custom-initialize-default'
627 Like `custom-initialize-set', but use the function
628 `set-default' to set the variable, instead of the
629 variable's `:set' function. This is the usual choice
630 for a variable whose `:set' function enables or disables
631 a minor mode; with this choice, defining the variable
632 will not call the minor mode function, but customizing
633 the variable will do so.
635 `custom-initialize-reset'
636 Always use the `:set' function to initialize the
637 variable. If the variable is already non-void, reset it
638 by calling the `:set' function using the current value
639 (returned by the `:get' method).
641 `custom-initialize-changed'
642 Use the `:set' function to initialize the variable, if
643 it is already set or has been customized; otherwise,
644 just use `set-default'.
646 The `:require' option is useful for an option that turns on the
647 operation of a certain feature. Assuming that the package is coded to
648 check the value of the option, you still need to arrange for the package
649 to be loaded. You can do that with `:require'. *Note Common
650 Keywords::. Here is an example, from the library `paren.el':
652 (defcustom show-paren-mode nil
653 "Toggle Show Paren mode...."
654 :set (lambda (symbol value)
655 (show-paren-mode (or value 0)))
656 :initialize 'custom-initialize-default
658 :group 'paren-showing
661 Internally, `defcustom' uses the symbol property `standard-value' to
662 record the expression for the default value, and `saved-value' to
663 record the value saved by the user with the customization buffer. The
664 `saved-value' property is actually a list whose car is an expression
665 which evaluates to the value.
668 File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
673 When you define a user option with `defcustom', you must specify its
674 "customization type". That is a Lisp object which describes (1) which
675 values are legitimate and (2) how to display the value in the
676 customization buffer for editing.
678 You specify the customization type in `defcustom' with the `:type'
679 keyword. The argument of `:type' is evaluated; since types that vary
680 at run time are rarely useful, normally you use a quoted constant. For
683 (defcustom diff-command "diff"
684 "*The command to use to run diff."
688 In general, a customization type is a list whose first element is a
689 symbol, one of the customization type names defined in the following
690 sections. After this symbol come a number of arguments, depending on
691 the symbol. Between the type symbol and its arguments, you can
692 optionally write keyword-value pairs (*note Type Keywords::.).
694 Some of the type symbols do not use any arguments; those are called
695 "simple types". For a simple type, if you do not use any keyword-value
696 pairs, you can omit the parentheses around the type symbol. For
697 example just `string' as a customization type is equivalent to
704 * Splicing into Lists::
708 File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
713 This section describes all the simple customization types.
716 The value may be any Lisp object that can be printed and read
717 back. You can use `sexp' as a fall-back for any option, if you
718 don't want to take the time to work out a more specific type to
722 The value must be an integer, and is represented textually in the
723 customization buffer.
726 The value must be a number, and is represented textually in the
727 customization buffer.
730 The value must be a string, and the customization buffer shows
731 just the contents, with no delimiting `"' characters and no
735 Like `string' except that the string must be a valid regular
739 The value must be a character code. A character code is actually
740 an integer, but this type shows the value by inserting the
741 character in the buffer, rather than by showing the number.
744 The value must be a file name, and you can do completion with
747 `(file :must-match t)'
748 The value must be a file name for an existing file, and you can do
749 completion with `M-<TAB>'.
752 The value must be a directory name, and you can do completion with
756 The value must be a symbol. It appears in the customization
757 buffer as the name of the symbol.
760 The value must be either a lambda expression or a function name.
761 When it is a function name, you can do completion with `M-<TAB>'.
764 The value must be a variable name, and you can do completion with
768 The value must be a symbol which is a face name.
771 The value is boolean--either `nil' or `t'. Note that by using
772 `choice' and `const' together (see the next section), you can
773 specify that the value must be `nil' or `t', but also specify the
774 text to describe each value in a way that fits the specific
775 meaning of the alternative.
778 File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
783 When none of the simple types is appropriate, you can use composite
784 types, which build new types from other types. Here are several ways of
787 `(restricted-sexp :match-alternatives CRITERIA)'
788 The value may be any Lisp object that satisfies one of CRITERIA.
789 CRITERIA should be a list, and each elements should be one of
792 * A predicate--that is, a function of one argument that returns
793 non-`nil' if the argument fits a certain type. This means
794 that objects of that type are acceptable.
796 * A quoted constant--that is, `'OBJECT'. This means that
797 OBJECT itself is an acceptable value.
801 (restricted-sexp :match-alternatives (integerp 't 'nil))
803 allows integers, `t' and `nil' as legitimate values.
805 The customization buffer shows all legitimate values using their
806 read syntax, and the user edits them textually.
808 `(cons CAR-TYPE CDR-TYPE)'
809 The value must be a cons cell, its CAR must fit CAR-TYPE, and its
810 CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
811 customization type which matches values such as `("foo" . foo)'.
813 In the customization buffer, the CAR and the CDR are displayed and
814 edited separately, each according to the type that you specify for
817 `(list ELEMENT-TYPES...)'
818 The value must be a list with exactly as many elements as the
819 ELEMENT-TYPES you have specified; and each element must fit the
820 corresponding ELEMENT-TYPE.
822 For example, `(list integer string function)' describes a list of
823 three elements; the first element must be an integer, the second a
824 string, and the third a function.
826 In the customization buffer, the each element is displayed and
827 edited separately, according to the type specified for it.
829 `(vector ELEMENT-TYPES...)'
830 Like `list' except that the value must be a vector instead of a
831 list. The elements work the same as in `list'.
833 `(choice ALTERNATIVE-TYPES...)'
834 The value must fit at least one of ALTERNATIVE-TYPES. For
835 example, `(choice integer string)' allows either an integer or a
838 In the customization buffer, the user selects one of the
839 alternatives using a menu, and can then edit the value in the
840 usual way for that alternative.
842 Normally the strings in this menu are determined automatically
843 from the choices; however, you can specify different strings for
844 the menu by including the `:tag' keyword in the alternatives. For
845 example, if an integer stands for a number of spaces, while a
846 string is text to use verbatim, you might write the customization
849 (choice (integer :tag "Number of spaces")
850 (string :tag "Literal text"))
852 so that the menu offers `Number of spaces' and `Literal Text'.
854 In any alternative for which `nil' is not a valid value, other than
855 a `const', you should specify a valid default for that alternative
856 using the `:value' keyword. *Note Type Keywords::.
859 The value must be VALUE--nothing else is allowed.
861 The main use of `const' is inside of `choice'. For example,
862 `(choice integer (const nil))' allows either an integer or `nil'.
864 `:tag' is often used with `const', inside of `choice'. For
867 (choice (const :tag "Yes" t)
868 (const :tag "No" nil)
869 (const :tag "Ask" foo))
871 `(function-item FUNCTION)'
872 Like `const', but used for values which are functions. This
873 displays the documentation string as well as the function name.
874 The documentation string is either the one you specify with
875 `:doc', or FUNCTION's own documentation string.
877 `(variable-item VARIABLE)'
878 Like `const', but used for values which are variable names. This
879 displays the documentation string as well as the variable name.
880 The documentation string is either the one you specify with
881 `:doc', or VARIABLE's own documentation string.
884 The value must be a list and each element of the list must be one
885 of the ELEMENTS specified. This appears in the customization
886 buffer as a checklist.
888 `(repeat ELEMENT-TYPE)'
889 The value must be a list and each element of the list must fit the
890 type ELEMENT-TYPE. This appears in the customization buffer as a
891 list of elements, with `[INS]' and `[DEL]' buttons for adding more
892 elements or removing elements.
895 File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
900 The `:inline' feature lets you splice a variable number of elements
901 into the middle of a list or vector. You use it in a `set', `choice'
902 or `repeat' type which appears among the element-types of a `list' or
905 Normally, each of the element-types in a `list' or `vector'
906 describes one and only one element of the list or vector. Thus, if an
907 element-type is a `repeat', that specifies a list of unspecified length
908 which appears as one element.
910 But when the element-type uses `:inline', the value it matches is
911 merged directly into the containing sequence. For example, if it
912 matches a list with three elements, those become three elements of the
913 overall sequence. This is analogous to using `,@' in the backquote
916 For example, to specify a list whose first element must be `t' and
917 whose remaining arguments should be zero or more of `foo' and `bar',
918 use this customization type:
920 (list (const t) (set :inline t foo bar))
922 This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
925 When the element-type is a `choice', you use `:inline' not in the
926 `choice' itself, but in (some of) the alternatives of the `choice'.
927 For example, to match a list which must start with a file name,
928 followed either by the symbol `t' or two strings, use this
933 (list :inline t string string)))
935 If the user chooses the first alternative in the choice, then the
936 overall list has two elements and the second element is `t'. If the
937 user chooses the second alternative, then the overall list has three
938 elements and the second and third must be strings.
941 File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
946 You can specify keyword-argument pairs in a customization type after
947 the type name symbol. Here are the keywords you can use, and their
951 This is used for a type that appears as an alternative inside of
952 `choice'; it specifies the default value to use, at first, if and
953 when the user selects this alternative with the menu in the
954 customization buffer.
956 Of course, if the actual value of the option fits this
957 alternative, it will appear showing the actual value, not DEFAULT.
959 If `nil' is not a valid value for the alternative, then it is
960 essential to specify a valid default with `:value'.
962 `:format FORMAT-STRING'
963 This string will be inserted in the buffer to represent the value
964 corresponding to the type. The following `%' escapes are available
965 for use in FORMAT-STRING:
968 Display the text BUTTON marked as a button. The `:action'
969 attribute specifies what the button will do if the user
970 invokes it; its value is a function which takes two
971 arguments--the widget which the button appears in, and the
974 There is no way to specify two different buttons with
978 Show SAMPLE in a special face specified by `:sample-face'.
981 Substitute the item's value. How the value is represented
982 depends on the kind of item, and (for variables) on the
986 Substitute the item's documentation string.
989 Like `%d', but if the documentation string is more than one
990 line, add an active field to control whether to show all of
991 it or just the first line.
994 Substitute the tag here. You specify the tag with the `:tag'
998 Display a literal `%'.
1001 Perform ACTION if the user clicks on a button.
1004 Use the face FACE (a face name or a list of face names) for button
1005 text displayed with `%[...%]'.
1007 `:button-prefix PREFIX'
1008 `:button-suffix SUFFIX'
1009 These specify the text to display before and after a button. Each
1013 No text is inserted.
1016 The string is inserted literally.
1019 The symbol's value is used.
1022 Use TAG (a string) as the tag for the value (or part of the value)
1023 that corresponds to this type.
1026 Use DOC as the documentation string for this value (or part of the
1027 value) that corresponds to this type. In order for this to work,
1028 you must specify a value for `:format', and use `%d' or `%h' in
1031 The usual reason to specify a documentation string for a type is to
1032 provide more information about the meanings of alternatives inside
1033 a `:choice' type or the parts of some other composite type.
1035 `:help-echo MOTION-DOC'
1036 When you move to this item with `widget-forward' or
1037 `widget-backward', it will display the string MOTION-DOC in the
1041 Specify how to decide whether a value matches the type. The
1042 corresponding value, FUNCTION, should be a function that accepts
1043 two arguments, a widget and a value; it should return non-`nil' if
1044 the value is acceptable.
1047 File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
1052 Loading a file of Lisp code means bringing its contents into the Lisp
1053 environment in the form of Lisp objects. XEmacs finds and opens the
1054 file, reads the text, evaluates each form, and then closes the file.
1056 The load functions evaluate all the expressions in a file just as
1057 the `eval-current-buffer' function evaluates all the expressions in a
1058 buffer. The difference is that the load functions read and evaluate
1059 the text in the file as found on disk, not the text in an Emacs buffer.
1061 The loaded file must contain Lisp expressions, either as source code
1062 or as byte-compiled code. Each form in the file is called a "top-level
1063 form". There is no special format for the forms in a loadable file;
1064 any form in a file may equally well be typed directly into a buffer and
1065 evaluated there. (Indeed, most code is tested this way.) Most often,
1066 the forms are function definitions and variable definitions.
1068 A file containing Lisp code is often called a "library". Thus, the
1069 "Rmail library" is a file containing code for Rmail mode. Similarly, a
1070 "Lisp library directory" is a directory of files containing Lisp code.
1074 * How Programs Do Loading:: The `load' function and others.
1075 * Autoload:: Setting up a function to autoload.
1076 * Repeated Loading:: Precautions about loading a file twice.
1077 * Named Features:: Loading a library if it isn't already loaded.
1078 * Unloading:: How to "unload" a library that was loaded.
1079 * Hooks for Loading:: Providing code to be run when
1080 particular libraries are loaded.
1083 File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
1085 How Programs Do Loading
1086 =======================
1088 XEmacs Lisp has several interfaces for loading. For example,
1089 `autoload' creates a placeholder object for a function in a file;
1090 trying to call the autoloading function loads the file to get the
1091 function's real definition (*note Autoload::.). `require' loads a file
1092 if it isn't already loaded (*note Named Features::.). Ultimately, all
1093 these facilities call the `load' function to do the work.
1095 - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
1096 This function finds and opens a file of Lisp code, evaluates all
1097 the forms in it, and closes the file.
1099 To find the file, `load' first looks for a file named
1100 `FILENAME.elc', that is, for a file whose name is FILENAME with
1101 `.elc' appended. If such a file exists, it is loaded. If there
1102 is no file by that name, then `load' looks for a file named
1103 `FILENAME.el'. If that file exists, it is loaded. Finally, if
1104 neither of those names is found, `load' looks for a file named
1105 FILENAME with nothing appended, and loads it if it exists. (The
1106 `load' function is not clever about looking at FILENAME. In the
1107 perverse case of a file named `foo.el.el', evaluation of `(load
1108 "foo.el")' will indeed find it.)
1110 If the optional argument NOSUFFIX is non-`nil', then the suffixes
1111 `.elc' and `.el' are not tried. In this case, you must specify
1112 the precise file name you want.
1114 If FILENAME is a relative file name, such as `foo' or
1115 `baz/foo.bar', `load' searches for the file using the variable
1116 `load-path'. It appends FILENAME to each of the directories
1117 listed in `load-path', and loads the first file it finds whose name
1118 matches. The current default directory is tried only if it is
1119 specified in `load-path', where `nil' stands for the default
1120 directory. `load' tries all three possible suffixes in the first
1121 directory in `load-path', then all three suffixes in the second
1122 directory, and so on.
1124 If you get a warning that `foo.elc' is older than `foo.el', it
1125 means you should consider recompiling `foo.el'. *Note Byte
1128 Messages like `Loading foo...' and `Loading foo...done' appear in
1129 the echo area during loading unless NOMESSAGE is non-`nil'.
1131 Any unhandled errors while loading a file terminate loading. If
1132 the load was done for the sake of `autoload', any function
1133 definitions made during the loading are undone.
1135 If `load' can't find the file to load, then normally it signals the
1136 error `file-error' (with `Cannot open load file FILENAME'). But
1137 if MISSING-OK is non-`nil', then `load' just returns `nil'.
1139 You can use the variable `load-read-function' to specify a function
1140 for `load' to use instead of `read' for reading expressions. See
1143 `load' returns `t' if the file loads successfully.
1145 - User Option: load-path
1146 The value of this variable is a list of directories to search when
1147 loading files with `load'. Each element is a string (which must be
1148 a directory name) or `nil' (which stands for the current working
1149 directory). The value of `load-path' is initialized from the
1150 environment variable `EMACSLOADPATH', if that exists; otherwise its
1151 default value is specified in `emacs/src/paths.h' when XEmacs is
1154 The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
1155 (or `;', according to the operating system) separates directory
1156 names, and `.' is used for the current default directory. Here is
1157 an example of how to set your `EMACSLOADPATH' variable from a
1158 `csh' `.login' file:
1160 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
1162 Here is how to set it using `sh':
1164 export EMACSLOADPATH
1165 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
1167 Here is an example of code you can place in a `.emacs' file to add
1168 several directories to the front of your default `load-path':
1171 (append (list nil "/user/bil/emacs"
1172 "/usr/local/lisplib"
1176 In this example, the path searches the current working directory
1177 first, followed then by the `/user/bil/emacs' directory, the
1178 `/usr/local/lisplib' directory, and the `~/emacs' directory, which
1179 are then followed by the standard directories for Lisp code.
1181 The command line options `-l' or `-load' specify a Lisp library to
1182 load as part of Emacs startup. Since this file might be in the
1183 current directory, Emacs 18 temporarily adds the current directory
1184 to the front of `load-path' so the file can be found there. Newer
1185 Emacs versions also find such files in the current directory, but
1186 without altering `load-path'.
1188 Dumping Emacs uses a special value of `load-path'. If the value of
1189 `load-path' at the end of dumping is unchanged (that is, still the
1190 same special value), the dumped Emacs switches to the ordinary
1191 `load-path' value when it starts up, as described above. But if
1192 `load-path' has any other value at the end of dumping, that value
1193 is used for execution of the dumped Emacs also.
1195 Therefore, if you want to change `load-path' temporarily for
1196 loading a few libraries in `site-init.el' or `site-load.el', you
1197 should bind `load-path' locally with `let' around the calls to
1200 - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
1201 This function searches for a file in the same way that `load' does,
1202 and returns the file found (if any). (In fact, `load' uses this
1203 function to search through `load-path'.) It searches for FILENAME
1204 through PATH-LIST, expanded by one of the optional SUFFIXES
1205 (string of suffixes separated by `:'s), checking for access MODE
1206 (0|1|2|4 = exists|executable|writeable|readable), default readable.
1208 `locate-file' keeps hash tables of the directories it searches
1209 through, in order to speed things up. It tries valiantly to not
1210 get confused in the face of a changing and unpredictable
1211 environment, but can occasionally get tripped up. In this case,
1212 you will have to call `locate-file-clear-hashing' to get it back
1213 on track. See that function for details.
1215 - Function: locate-file-clear-hashing PATH
1216 This function clears the hash records for the specified list of
1217 directories. `locate-file' uses a hashing scheme to speed lookup,
1218 and will correctly track the following environmental changes:
1220 * changes of any sort to the list of directories to be searched.
1222 * addition and deletion of non-shadowing files (see below) from
1223 the directories in the list.
1225 * byte-compilation of a .el file into a .elc file.
1227 `locate-file' will primarily get confused if you add a file that
1228 shadows (i.e. has the same name as) another file further down in
1229 the directory list. In this case, you must call
1230 `locate-file-clear-hashing'.
1232 - Variable: load-in-progress
1233 This variable is non-`nil' if Emacs is in the process of loading a
1234 file, and it is `nil' otherwise.
1236 - Variable: load-read-function
1237 This variable specifies an alternate expression-reading function
1238 for `load' and `eval-region' to use instead of `read'. The
1239 function should accept one argument, just as `read' does.
1241 Normally, the variable's value is `nil', which means those
1242 functions should use `read'.
1244 - User Option: load-warn-when-source-newer
1245 This variable specifies whether `load' should check whether the
1246 source is newer than the binary. If this variable is true, then
1247 when a `.elc' file is being loaded and the corresponding `.el' is
1248 newer, a warning message will be printed. The default is `nil',
1249 but it is bound to `t' during the initial loadup.
1251 - User Option: load-warn-when-source-only
1252 This variable specifies whether `load' should warn when loading a
1253 `.el' file instead of an `.elc'. If this variable is true, then
1254 when `load' is called with a filename without an extension, and
1255 the `.elc' version doesn't exist but the `.el' version does, then
1256 a message will be printed. If an explicit extension is passed to
1257 `load', no warning will be printed. The default is `nil', but it
1258 is bound to `t' during the initial loadup.
1260 - User Option: load-ignore-elc-files
1261 This variable specifies whether `load' should ignore `.elc' files
1262 when a suffix is not given. This is normally used only to
1263 bootstrap the `.elc' files when building XEmacs, when you use the
1264 command `make all-elc'. (This forces the `.el' versions to be
1265 loaded in the process of compiling those same files, so that
1266 existing out-of-date `.elc' files do not make it mess things up.)
1268 To learn how `load' is used to build XEmacs, see *Note Building