1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file 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: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
58 Macros often need to construct large list structures from a mixture
59 of constants and nonconstant parts. To make this easier, use the macro
60 ``' (often called "backquote").
62 Backquote allows you to quote a list, but selectively evaluate
63 elements of that list. In the simplest case, it is identical to the
64 special form `quote' (*note Quoting::.). For example, these two forms
65 yield identical results:
67 `(a list of (+ 2 3) elements)
68 => (a list of (+ 2 3) elements)
69 '(a list of (+ 2 3) elements)
70 => (a list of (+ 2 3) elements)
72 The special marker `,' inside of the argument to backquote indicates
73 a value that isn't constant. Backquote evaluates the argument of `,'
74 and puts the value in the list structure:
76 (list 'a 'list 'of (+ 2 3) 'elements)
77 => (a list of 5 elements)
78 `(a list of ,(+ 2 3) elements)
79 => (a list of 5 elements)
81 You can also "splice" an evaluated value into the resulting list,
82 using the special marker `,@'. The elements of the spliced list become
83 elements at the same level as the other elements of the resulting list.
84 The equivalent code without using ``' is often unreadable. Here are
87 (setq some-list '(2 3))
89 (cons 1 (append some-list '(4) some-list))
91 `(1 ,@some-list 4 ,@some-list)
94 (setq list '(hack foo bar))
98 (cons 'words (append (cdr list) '(as elements)))))
99 => (use the words foo bar as elements)
100 `(use the words ,@(cdr list) as elements)
101 => (use the words foo bar as elements)
103 In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
104 version 19.29), ``' used a different syntax which required an
105 extra level of parentheses around the entire backquote construct.
106 Likewise, each `,' or `,@' substitution required an extra level of
107 parentheses surrounding both the `,' or `,@' and the following
108 expression. The old syntax required whitespace between the ``',
109 `,' or `,@' and the following expression.
111 This syntax is still accepted, but no longer recommended except for
112 compatibility with old Emacs versions.
115 File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
117 Common Problems Using Macros
118 ============================
120 The basic facts of macro expansion have counterintuitive
121 consequences. This section describes some important consequences that
122 can lead to trouble, and rules to follow to avoid trouble.
126 * Argument Evaluation:: The expansion should evaluate each macro arg once.
127 * Surprising Local Vars:: Local variable bindings in the expansion
128 require special care.
129 * Eval During Expansion:: Don't evaluate them; put them in the expansion.
130 * Repeated Expansion:: Avoid depending on how many times expansion is done.
133 File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
135 Evaluating Macro Arguments Repeatedly
136 -------------------------------------
138 When defining a macro you must pay attention to the number of times
139 the arguments will be evaluated when the expansion is executed. The
140 following macro (used to facilitate iteration) illustrates the problem.
141 This macro allows us to write a simple "for" loop such as one might
144 (defmacro for (var from init to final do &rest body)
145 "Execute a simple \"for\" loop.
146 For example, (for i from 1 to 10 do (print i))."
147 (list 'let (list (list var init))
148 (cons 'while (cons (list '<= var final)
149 (append body (list (list 'inc var)))))))
151 (for i from 1 to 3 do
152 (setq square (* i i))
153 (princ (format "\n%d %d" i square)))
158 (setq square (* i i))
159 (princ (format "%d %d" i square))
168 (The arguments `from', `to', and `do' in this macro are "syntactic
169 sugar"; they are entirely ignored. The idea is that you will write
170 noise words (such as `from', `to', and `do') in those positions in the
173 Here's an equivalent definition simplified through use of backquote:
175 (defmacro for (var from init to final do &rest body)
176 "Execute a simple \"for\" loop.
177 For example, (for i from 1 to 10 do (print i))."
179 (while (<= ,var ,final)
183 Both forms of this definition (with backquote and without) suffer
184 from the defect that FINAL is evaluated on every iteration. If FINAL
185 is a constant, this is not a problem. If it is a more complex form,
186 say `(long-complex-calculation x)', this can slow down the execution
187 significantly. If FINAL has side effects, executing it more than once
188 is probably incorrect.
190 A well-designed macro definition takes steps to avoid this problem by
191 producing an expansion that evaluates the argument expressions exactly
192 once unless repeated evaluation is part of the intended purpose of the
193 macro. Here is a correct expansion for the `for' macro:
198 (setq square (* i i))
199 (princ (format "%d %d" i square))
202 Here is a macro definition that creates this expansion:
204 (defmacro for (var from init to final do &rest body)
205 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
212 Unfortunately, this introduces another problem. Proceed to the
216 File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
218 Local Variables in Macro Expansions
219 -----------------------------------
221 In the previous section, the definition of `for' was fixed as
222 follows to make the expansion evaluate the macro arguments the proper
225 (defmacro for (var from init to final do &rest body)
226 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
234 The new definition of `for' has a new problem: it introduces a local
235 variable named `max' which the user does not expect. This causes
236 trouble in examples such as the following:
239 (for x from 0 to 10 do
240 (let ((this (frob x)))
244 The references to `max' inside the body of the `for', which are
245 supposed to refer to the user's binding of `max', really access the
246 binding made by `for'.
248 The way to correct this is to use an uninterned symbol instead of
249 `max' (*note Creating Symbols::.). The uninterned symbol can be bound
250 and referred to just like any other symbol, but since it is created by
251 `for', we know that it cannot already appear in the user's program.
252 Since it is not interned, there is no way the user can put it into the
253 program later. It will never appear anywhere except where put by
254 `for'. Here is a definition of `for' that works this way:
256 (defmacro for (var from init to final do &rest body)
257 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
258 (let ((tempvar (make-symbol "max")))
261 (while (<= ,var ,tempvar)
265 This creates an uninterned symbol named `max' and puts it in the
266 expansion instead of the usual interned symbol `max' that appears in
267 expressions ordinarily.
270 File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
272 Evaluating Macro Arguments in Expansion
273 ---------------------------------------
275 Another problem can happen if you evaluate any of the macro argument
276 expressions during the computation of the expansion, such as by calling
277 `eval' (*note Eval::.). If the argument is supposed to refer to the
278 user's variables, you may have trouble if the user happens to use a
279 variable with the same name as one of the macro arguments. Inside the
280 macro body, the macro argument binding is the most local binding of this
281 variable, so any references inside the form being evaluated do refer to
282 it. Here is an example:
285 (list 'setq (eval a) t))
288 (foo x) ==> (setq b t)
289 => t ; and `b' has been set.
292 (foo a) ==> (setq a t)
293 => t ; but this set `a', not `c'.
295 It makes a difference whether the user's variable is named `a' or
296 `x', because `a' conflicts with the macro argument variable `a'.
298 Another reason not to call `eval' in a macro definition is that it
299 probably won't do what you intend in a compiled program. The
300 byte-compiler runs macro definitions while compiling the program, when
301 the program's own computations (which you might have wished to access
302 with `eval') don't occur and its local variable bindings don't exist.
304 The safe way to work with the run-time value of an expression is to
305 put the expression into the macro expansion, so that its value is
306 computed as part of executing the expansion.
309 File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
311 How Many Times is the Macro Expanded?
312 -------------------------------------
314 Occasionally problems result from the fact that a macro call is
315 expanded each time it is evaluated in an interpreted function, but is
316 expanded only once (during compilation) for a compiled function. If the
317 macro definition has side effects, they will work differently depending
318 on how many times the macro is expanded.
320 In particular, constructing objects is a kind of side effect. If the
321 macro is called once, then the objects are constructed only once. In
322 other words, the same structure of objects is used each time the macro
323 call is executed. In interpreted operation, the macro is reexpanded
324 each time, producing a fresh collection of objects each time. Usually
325 this does not matter--the objects have the same contents whether they
326 are shared or not. But if the surrounding program does side effects on
327 the objects, it makes a difference whether they are shared. Here is an
330 (defmacro empty-object ()
331 (list 'quote (cons nil nil)))
333 (defun initialize (condition)
334 (let ((object (empty-object)))
336 (setcar object condition))
339 If `initialize' is interpreted, a new list `(nil)' is constructed each
340 time `initialize' is called. Thus, no side effect survives between
341 calls. If `initialize' is compiled, then the macro `empty-object' is
342 expanded during compilation, producing a single "constant" `(nil)' that
343 is reused and altered each time `initialize' is called.
345 One way to avoid pathological cases like this is to think of
346 `empty-object' as a funny kind of constant, not as a memory allocation
347 construct. You wouldn't use `setcar' on a constant such as `'(nil)',
348 so naturally you won't use it on `(empty-object)' either.
351 File: lispref.info, Node: Customization, Up: Top
353 Writing Customization Definitions
354 *********************************
356 This chapter describes how to declare user options for customization,
357 and also customization groups for classifying them. We use the term
358 "customization item" to include both kinds of customization
359 definitions--as well as face definitions.
364 * Group Definitions::
365 * Variable Definitions::
366 * Customization Types::
369 File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
371 Common Keywords for All Kinds of Items
372 ======================================
374 All kinds of customization declarations (for variables and groups,
375 and for faces) accept keyword arguments for specifying various
376 information. This section describes some keywords that apply to all
379 All of these keywords, except `:tag', can be used more than once in
380 a given item. Each use of the keyword has an independent effect. The
381 keyword `:tag' is an exception because any given item can only display
385 Use NAME, a string, instead of the item's name, to label the item
386 in customization menus and buffers.
389 Put this customization item in group GROUP. When you use `:group'
390 in a `defgroup', it makes the new group a subgroup of GROUP.
392 If you use this keyword more than once, you can put a single item
393 into more than one group. Displaying any of those groups will
394 show this item. Be careful not to overdo this!
397 Include an external link after the documentation string for this
398 item. This is a sentence containing an active field which
399 references some other documentation.
401 There are three alternatives you can use for LINK-DATA:
403 `(custom-manual INFO-NODE)'
404 Link to an Info node; INFO-NODE is a string which specifies
405 the node name, as in `"(emacs)Top"'. The link appears as
406 `[manual]' in the customization buffer.
408 `(info-link INFO-NODE)'
409 Like `custom-manual' except that the link appears in the
410 customization buffer with the Info node name.
413 Link to a web page; URL is a string which specifies the URL.
414 The link appears in the customization buffer as URL.
416 You can specify the text to use in the customization buffer by
417 adding `:tag NAME' after the first element of the LINK-DATA; for
418 example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
419 Emacs manual which appears in the buffer as `foo'.
421 An item can have more than one external link; however, most items
425 Load file FILE (a string) before displaying this customization
426 item. Loading is done with `load-library', and only if the file is
430 Require feature FEATURE (a symbol) when installing a value for
431 this item (an option or a face) that was saved using the
432 customization feature. This is done by calling `require'.
434 The most common reason to use `:require' is when a variable enables
435 a feature such as a minor mode, and just setting the variable
436 won't have any effect unless the code which implements the mode is
440 File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
442 Defining Custom Groups
443 ======================
445 Each Emacs Lisp package should have one main customization group
446 which contains all the options, faces and other groups in the package.
447 If the package has a small number of options and faces, use just one
448 group and put everything in it. When there are more than twelve or so
449 options and faces, then you should structure them into subgroups, and
450 put the subgroups under the package's main customization group. It is
451 OK to put some of the options and faces in the package's main group
452 alongside the subgroups.
454 The package's main or only group should be a member of one or more of
455 the standard customization groups. (To display the full list of them,
456 use `M-x customize'.) Choose one or more of them (but not too many),
457 and add your group to each of them using the `:group' keyword.
459 The way to declare new customization groups is with `defgroup'.
461 - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
462 Declare GROUP as a customization group containing MEMBERS. Do not
463 quote the symbol GROUP. The argument DOC specifies the
464 documentation string for the group.
466 The argument MEMBERS is a list specifying an initial set of
467 customization items to be members of the group. However, most
468 often MEMBERS is `nil', and you specify the group's members by
469 using the `:group' keyword when defining those members.
471 If you want to specify group members through MEMBERS, each element
472 should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
473 WIDGET is a widget type for editing that symbol. Useful widgets
474 are `custom-variable' for a variable, `custom-face' for a face,
475 and `custom-group' for a group.
477 In addition to the common keywords (*note Common Keywords::.), you
478 can use this keyword in `defgroup':
481 If the name of an item in the group starts with PREFIX, then
482 the tag for that item is constructed (by default) by omitting
485 One group can have any number of prefixes.
488 File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
490 Defining Customization Variables
491 ================================
493 Use `defcustom' to declare user-editable variables.
495 - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
496 Declare OPTION as a customizable user option variable. Do not
497 quote OPTION. The argument DOC specifies the documentation string
500 If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
501 should be an expression to compute the value; be careful in
502 writing it, because it can be evaluated on more than one occasion.
504 The following additional keywords are defined:
507 Use TYPE as the data type for this option. It specifies which
508 values are legitimate, and how to display the value. *Note
509 Customization Types::, for more information.
512 Specify LIST as the list of reasonable values for use in this
515 Currently this is meaningful only when the type is `hook'.
516 In that case, the elements of LIST should be functions that
517 are useful as elements of the hook value. The user is not
518 restricted to using only these functions, but they are
519 offered as convenient alternatives.
522 This option specifies that the variable was first introduced,
523 or its default value was changed, in Emacs version VERSION.
524 The value VERSION must be a string. For example,
526 (defcustom foo-max 34
527 "*Maximum number of foo's allowed."
533 Specify SETFUNCTION as the way to change the value of this
534 option. The function SETFUNCTION should take two arguments,
535 a symbol and the new value, and should do whatever is
536 necessary to update the value properly for this option (which
537 may not mean simply setting the option as a Lisp variable).
538 The default for SETFUNCTION is `set-default'.
541 Specify GETFUNCTION as the way to extract the value of this
542 option. The function GETFUNCTION should take one argument, a
543 symbol, and should return the "current value" for that symbol
544 (which need not be the symbol's Lisp value). The default is
547 `:initialize FUNCTION'
548 FUNCTION should be a function used to initialize the variable
549 when the `defcustom' is evaluated. It should take two
550 arguments, the symbol and value. Here are some predefined
551 functions meant for use in this way:
553 `custom-initialize-set'
554 Use the variable's `:set' function to initialize the
555 variable, but do not reinitialize it if it is already
556 non-void. This is the default `:initialize' function.
558 `custom-initialize-default'
559 Like `custom-initialize-set', but use the function
560 `set-default' to set the variable, instead of the
561 variable's `:set' function. This is the usual choice
562 for a variable whose `:set' function enables or disables
563 a minor mode; with this choice, defining the variable
564 will not call the minor mode function, but customizing
565 the variable will do so.
567 `custom-initialize-reset'
568 Always use the `:set' function to initialize the
569 variable. If the variable is already non-void, reset it
570 by calling the `:set' function using the current value
571 (returned by the `:get' method).
573 `custom-initialize-changed'
574 Use the `:set' function to initialize the variable, if
575 it is already set or has been customized; otherwise,
576 just use `set-default'.
578 The `:require' option is useful for an option that turns on the
579 operation of a certain feature. Assuming that the package is coded to
580 check the value of the option, you still need to arrange for the package
581 to be loaded. You can do that with `:require'. *Note Common
582 Keywords::. Here is an example, from the library `paren.el':
584 (defcustom show-paren-mode nil
585 "Toggle Show Paren mode...."
586 :set (lambda (symbol value)
587 (show-paren-mode (or value 0)))
588 :initialize 'custom-initialize-default
590 :group 'paren-showing
593 Internally, `defcustom' uses the symbol property `standard-value' to
594 record the expression for the default value, and `saved-value' to
595 record the value saved by the user with the customization buffer. The
596 `saved-value' property is actually a list whose car is an expression
597 which evaluates to the value.
600 File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
605 When you define a user option with `defcustom', you must specify its
606 "customization type". That is a Lisp object which describes (1) which
607 values are legitimate and (2) how to display the value in the
608 customization buffer for editing.
610 You specify the customization type in `defcustom' with the `:type'
611 keyword. The argument of `:type' is evaluated; since types that vary
612 at run time are rarely useful, normally you use a quoted constant. For
615 (defcustom diff-command "diff"
616 "*The command to use to run diff."
620 In general, a customization type is a list whose first element is a
621 symbol, one of the customization type names defined in the following
622 sections. After this symbol come a number of arguments, depending on
623 the symbol. Between the type symbol and its arguments, you can
624 optionally write keyword-value pairs (*note Type Keywords::.).
626 Some of the type symbols do not use any arguments; those are called
627 "simple types". For a simple type, if you do not use any keyword-value
628 pairs, you can omit the parentheses around the type symbol. For
629 example just `string' as a customization type is equivalent to
636 * Splicing into Lists::
640 File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
645 This section describes all the simple customization types.
648 The value may be any Lisp object that can be printed and read
649 back. You can use `sexp' as a fall-back for any option, if you
650 don't want to take the time to work out a more specific type to
654 The value must be an integer, and is represented textually in the
655 customization buffer.
658 The value must be a number, and is represented textually in the
659 customization buffer.
662 The value must be a string, and the customization buffer shows
663 just the contents, with no delimiting `"' characters and no
667 Like `string' except that the string must be a valid regular
671 The value must be a character code. A character code is actually
672 an integer, but this type shows the value by inserting the
673 character in the buffer, rather than by showing the number.
676 The value must be a file name, and you can do completion with
679 `(file :must-match t)'
680 The value must be a file name for an existing file, and you can do
681 completion with `M-<TAB>'.
684 The value must be a directory name, and you can do completion with
688 The value must be a symbol. It appears in the customization
689 buffer as the name of the symbol.
692 The value must be either a lambda expression or a function name.
693 When it is a function name, you can do completion with `M-<TAB>'.
696 The value must be a variable name, and you can do completion with
700 The value must be a symbol which is a face name.
703 The value is boolean--either `nil' or `t'. Note that by using
704 `choice' and `const' together (see the next section), you can
705 specify that the value must be `nil' or `t', but also specify the
706 text to describe each value in a way that fits the specific
707 meaning of the alternative.
710 File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
715 When none of the simple types is appropriate, you can use composite
716 types, which build new types from other types. Here are several ways of
719 `(restricted-sexp :match-alternatives CRITERIA)'
720 The value may be any Lisp object that satisfies one of CRITERIA.
721 CRITERIA should be a list, and each elements should be one of
724 * A predicate--that is, a function of one argument that returns
725 non-`nil' if the argument fits a certain type. This means
726 that objects of that type are acceptable.
728 * A quoted constant--that is, `'OBJECT'. This means that
729 OBJECT itself is an acceptable value.
733 (restricted-sexp :match-alternatives (integerp 't 'nil))
735 allows integers, `t' and `nil' as legitimate values.
737 The customization buffer shows all legitimate values using their
738 read syntax, and the user edits them textually.
740 `(cons CAR-TYPE CDR-TYPE)'
741 The value must be a cons cell, its CAR must fit CAR-TYPE, and its
742 CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
743 customization type which matches values such as `("foo" . foo)'.
745 In the customization buffer, the CAR and the CDR are displayed and
746 edited separately, each according to the type that you specify for
749 `(list ELEMENT-TYPES...)'
750 The value must be a list with exactly as many elements as the
751 ELEMENT-TYPES you have specified; and each element must fit the
752 corresponding ELEMENT-TYPE.
754 For example, `(list integer string function)' describes a list of
755 three elements; the first element must be an integer, the second a
756 string, and the third a function.
758 In the customization buffer, the each element is displayed and
759 edited separately, according to the type specified for it.
761 `(vector ELEMENT-TYPES...)'
762 Like `list' except that the value must be a vector instead of a
763 list. The elements work the same as in `list'.
765 `(choice ALTERNATIVE-TYPES...)'
766 The value must fit at least one of ALTERNATIVE-TYPES. For
767 example, `(choice integer string)' allows either an integer or a
770 In the customization buffer, the user selects one of the
771 alternatives using a menu, and can then edit the value in the
772 usual way for that alternative.
774 Normally the strings in this menu are determined automatically
775 from the choices; however, you can specify different strings for
776 the menu by including the `:tag' keyword in the alternatives. For
777 example, if an integer stands for a number of spaces, while a
778 string is text to use verbatim, you might write the customization
781 (choice (integer :tag "Number of spaces")
782 (string :tag "Literal text"))
784 so that the menu offers `Number of spaces' and `Literal Text'.
786 In any alternative for which `nil' is not a valid value, other than
787 a `const', you should specify a valid default for that alternative
788 using the `:value' keyword. *Note Type Keywords::.
791 The value must be VALUE--nothing else is allowed.
793 The main use of `const' is inside of `choice'. For example,
794 `(choice integer (const nil))' allows either an integer or `nil'.
796 `:tag' is often used with `const', inside of `choice'. For
799 (choice (const :tag "Yes" t)
800 (const :tag "No" nil)
801 (const :tag "Ask" foo))
803 `(function-item FUNCTION)'
804 Like `const', but used for values which are functions. This
805 displays the documentation string as well as the function name.
806 The documentation string is either the one you specify with
807 `:doc', or FUNCTION's own documentation string.
809 `(variable-item VARIABLE)'
810 Like `const', but used for values which are variable names. This
811 displays the documentation string as well as the variable name.
812 The documentation string is either the one you specify with
813 `:doc', or VARIABLE's own documentation string.
816 The value must be a list and each element of the list must be one
817 of the ELEMENTS specified. This appears in the customization
818 buffer as a checklist.
820 `(repeat ELEMENT-TYPE)'
821 The value must be a list and each element of the list must fit the
822 type ELEMENT-TYPE. This appears in the customization buffer as a
823 list of elements, with `[INS]' and `[DEL]' buttons for adding more
824 elements or removing elements.
827 File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
832 The `:inline' feature lets you splice a variable number of elements
833 into the middle of a list or vector. You use it in a `set', `choice'
834 or `repeat' type which appears among the element-types of a `list' or
837 Normally, each of the element-types in a `list' or `vector'
838 describes one and only one element of the list or vector. Thus, if an
839 element-type is a `repeat', that specifies a list of unspecified length
840 which appears as one element.
842 But when the element-type uses `:inline', the value it matches is
843 merged directly into the containing sequence. For example, if it
844 matches a list with three elements, those become three elements of the
845 overall sequence. This is analogous to using `,@' in the backquote
848 For example, to specify a list whose first element must be `t' and
849 whose remaining arguments should be zero or more of `foo' and `bar',
850 use this customization type:
852 (list (const t) (set :inline t foo bar))
854 This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
857 When the element-type is a `choice', you use `:inline' not in the
858 `choice' itself, but in (some of) the alternatives of the `choice'.
859 For example, to match a list which must start with a file name,
860 followed either by the symbol `t' or two strings, use this
865 (list :inline t string string)))
867 If the user chooses the first alternative in the choice, then the
868 overall list has two elements and the second element is `t'. If the
869 user chooses the second alternative, then the overall list has three
870 elements and the second and third must be strings.
873 File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
878 You can specify keyword-argument pairs in a customization type after
879 the type name symbol. Here are the keywords you can use, and their
883 This is used for a type that appears as an alternative inside of
884 `choice'; it specifies the default value to use, at first, if and
885 when the user selects this alternative with the menu in the
886 customization buffer.
888 Of course, if the actual value of the option fits this
889 alternative, it will appear showing the actual value, not DEFAULT.
891 If `nil' is not a valid value for the alternative, then it is
892 essential to specify a valid default with `:value'.
894 `:format FORMAT-STRING'
895 This string will be inserted in the buffer to represent the value
896 corresponding to the type. The following `%' escapes are available
897 for use in FORMAT-STRING:
900 Display the text BUTTON marked as a button. The `:action'
901 attribute specifies what the button will do if the user
902 invokes it; its value is a function which takes two
903 arguments--the widget which the button appears in, and the
906 There is no way to specify two different buttons with
910 Show SAMPLE in a special face specified by `:sample-face'.
913 Substitute the item's value. How the value is represented
914 depends on the kind of item, and (for variables) on the
918 Substitute the item's documentation string.
921 Like `%d', but if the documentation string is more than one
922 line, add an active field to control whether to show all of
923 it or just the first line.
926 Substitute the tag here. You specify the tag with the `:tag'
930 Display a literal `%'.
933 Perform ACTION if the user clicks on a button.
936 Use the face FACE (a face name or a list of face names) for button
937 text displayed with `%[...%]'.
939 `:button-prefix PREFIX'
940 `:button-suffix SUFFIX'
941 These specify the text to display before and after a button. Each
948 The string is inserted literally.
951 The symbol's value is used.
954 Use TAG (a string) as the tag for the value (or part of the value)
955 that corresponds to this type.
958 Use DOC as the documentation string for this value (or part of the
959 value) that corresponds to this type. In order for this to work,
960 you must specify a value for `:format', and use `%d' or `%h' in
963 The usual reason to specify a documentation string for a type is to
964 provide more information about the meanings of alternatives inside
965 a `:choice' type or the parts of some other composite type.
967 `:help-echo MOTION-DOC'
968 When you move to this item with `widget-forward' or
969 `widget-backward', it will display the string MOTION-DOC in the
973 Specify how to decide whether a value matches the type. The
974 corresponding value, FUNCTION, should be a function that accepts
975 two arguments, a widget and a value; it should return non-`nil' if
976 the value is acceptable.
979 File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
984 Loading a file of Lisp code means bringing its contents into the Lisp
985 environment in the form of Lisp objects. XEmacs finds and opens the
986 file, reads the text, evaluates each form, and then closes the file.
988 The load functions evaluate all the expressions in a file just as
989 the `eval-current-buffer' function evaluates all the expressions in a
990 buffer. The difference is that the load functions read and evaluate
991 the text in the file as found on disk, not the text in an Emacs buffer.
993 The loaded file must contain Lisp expressions, either as source code
994 or as byte-compiled code. Each form in the file is called a "top-level
995 form". There is no special format for the forms in a loadable file;
996 any form in a file may equally well be typed directly into a buffer and
997 evaluated there. (Indeed, most code is tested this way.) Most often,
998 the forms are function definitions and variable definitions.
1000 A file containing Lisp code is often called a "library". Thus, the
1001 "Rmail library" is a file containing code for Rmail mode. Similarly, a
1002 "Lisp library directory" is a directory of files containing Lisp code.
1006 * How Programs Do Loading:: The `load' function and others.
1007 * Autoload:: Setting up a function to autoload.
1008 * Repeated Loading:: Precautions about loading a file twice.
1009 * Named Features:: Loading a library if it isn't already loaded.
1010 * Unloading:: How to "unload" a library that was loaded.
1011 * Hooks for Loading:: Providing code to be run when
1012 particular libraries are loaded.
1015 File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
1017 How Programs Do Loading
1018 =======================
1020 XEmacs Lisp has several interfaces for loading. For example,
1021 `autoload' creates a placeholder object for a function in a file;
1022 trying to call the autoloading function loads the file to get the
1023 function's real definition (*note Autoload::.). `require' loads a file
1024 if it isn't already loaded (*note Named Features::.). Ultimately, all
1025 these facilities call the `load' function to do the work.
1027 - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
1028 This function finds and opens a file of Lisp code, evaluates all
1029 the forms in it, and closes the file.
1031 To find the file, `load' first looks for a file named
1032 `FILENAME.elc', that is, for a file whose name is FILENAME with
1033 `.elc' appended. If such a file exists, it is loaded. If there
1034 is no file by that name, then `load' looks for a file named
1035 `FILENAME.el'. If that file exists, it is loaded. Finally, if
1036 neither of those names is found, `load' looks for a file named
1037 FILENAME with nothing appended, and loads it if it exists. (The
1038 `load' function is not clever about looking at FILENAME. In the
1039 perverse case of a file named `foo.el.el', evaluation of `(load
1040 "foo.el")' will indeed find it.)
1042 If the optional argument NOSUFFIX is non-`nil', then the suffixes
1043 `.elc' and `.el' are not tried. In this case, you must specify
1044 the precise file name you want.
1046 If FILENAME is a relative file name, such as `foo' or
1047 `baz/foo.bar', `load' searches for the file using the variable
1048 `load-path'. It appends FILENAME to each of the directories
1049 listed in `load-path', and loads the first file it finds whose name
1050 matches. The current default directory is tried only if it is
1051 specified in `load-path', where `nil' stands for the default
1052 directory. `load' tries all three possible suffixes in the first
1053 directory in `load-path', then all three suffixes in the second
1054 directory, and so on.
1056 If you get a warning that `foo.elc' is older than `foo.el', it
1057 means you should consider recompiling `foo.el'. *Note Byte
1060 Messages like `Loading foo...' and `Loading foo...done' appear in
1061 the echo area during loading unless NOMESSAGE is non-`nil'.
1063 Any unhandled errors while loading a file terminate loading. If
1064 the load was done for the sake of `autoload', any function
1065 definitions made during the loading are undone.
1067 If `load' can't find the file to load, then normally it signals the
1068 error `file-error' (with `Cannot open load file FILENAME'). But
1069 if MISSING-OK is non-`nil', then `load' just returns `nil'.
1071 You can use the variable `load-read-function' to specify a function
1072 for `load' to use instead of `read' for reading expressions. See
1075 `load' returns `t' if the file loads successfully.
1077 - User Option: load-path
1078 The value of this variable is a list of directories to search when
1079 loading files with `load'. Each element is a string (which must be
1080 a directory name) or `nil' (which stands for the current working
1081 directory). The value of `load-path' is initialized from the
1082 environment variable `EMACSLOADPATH', if that exists; otherwise its
1083 default value is specified in `emacs/src/paths.h' when XEmacs is
1086 The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
1087 (or `;', according to the operating system) separates directory
1088 names, and `.' is used for the current default directory. Here is
1089 an example of how to set your `EMACSLOADPATH' variable from a
1090 `csh' `.login' file:
1092 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
1094 Here is how to set it using `sh':
1096 export EMACSLOADPATH
1097 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
1099 Here is an example of code you can place in a `.emacs' file to add
1100 several directories to the front of your default `load-path':
1103 (append (list nil "/user/bil/emacs"
1104 "/usr/local/lisplib"
1108 In this example, the path searches the current working directory
1109 first, followed then by the `/user/bil/emacs' directory, the
1110 `/usr/local/lisplib' directory, and the `~/emacs' directory, which
1111 are then followed by the standard directories for Lisp code.
1113 The command line options `-l' or `-load' specify a Lisp library to
1114 load as part of Emacs startup. Since this file might be in the
1115 current directory, Emacs 18 temporarily adds the current directory
1116 to the front of `load-path' so the file can be found there. Newer
1117 Emacs versions also find such files in the current directory, but
1118 without altering `load-path'.
1120 Dumping Emacs uses a special value of `load-path'. If the value of
1121 `load-path' at the end of dumping is unchanged (that is, still the
1122 same special value), the dumped Emacs switches to the ordinary
1123 `load-path' value when it starts up, as described above. But if
1124 `load-path' has any other value at the end of dumping, that value
1125 is used for execution of the dumped Emacs also.
1127 Therefore, if you want to change `load-path' temporarily for
1128 loading a few libraries in `site-init.el' or `site-load.el', you
1129 should bind `load-path' locally with `let' around the calls to
1132 - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
1133 This function searches for a file in the same way that `load' does,
1134 and returns the file found (if any). (In fact, `load' uses this
1135 function to search through `load-path'.) It searches for FILENAME
1136 through PATH-LIST, expanded by one of the optional SUFFIXES
1137 (string of suffixes separated by `:'s), checking for access MODE
1138 (0|1|2|4 = exists|executable|writeable|readable), default readable.
1140 `locate-file' keeps hash tables of the directories it searches
1141 through, in order to speed things up. It tries valiantly to not
1142 get confused in the face of a changing and unpredictable
1143 environment, but can occasionally get tripped up. In this case,
1144 you will have to call `locate-file-clear-hashing' to get it back
1145 on track. See that function for details.
1147 - Function: locate-file-clear-hashing PATH
1148 This function clears the hash records for the specified list of
1149 directories. `locate-file' uses a hashing scheme to speed lookup,
1150 and will correctly track the following environmental changes:
1152 * changes of any sort to the list of directories to be searched.
1154 * addition and deletion of non-shadowing files (see below) from
1155 the directories in the list.
1157 * byte-compilation of a .el file into a .elc file.
1159 `locate-file' will primarily get confused if you add a file that
1160 shadows (i.e. has the same name as) another file further down in
1161 the directory list. In this case, you must call
1162 `locate-file-clear-hashing'.
1164 - Variable: load-in-progress
1165 This variable is non-`nil' if Emacs is in the process of loading a
1166 file, and it is `nil' otherwise.
1168 - Variable: load-read-function
1169 This variable specifies an alternate expression-reading function
1170 for `load' and `eval-region' to use instead of `read'. The
1171 function should accept one argument, just as `read' does.
1173 Normally, the variable's value is `nil', which means those
1174 functions should use `read'.
1176 - User Option: load-warn-when-source-newer
1177 This variable specifies whether `load' should check whether the
1178 source is newer than the binary. If this variable is true, then
1179 when a `.elc' file is being loaded and the corresponding `.el' is
1180 newer, a warning message will be printed. The default is `nil',
1181 but it is bound to `t' during the initial loadup.
1183 - User Option: load-warn-when-source-only
1184 This variable specifies whether `load' should warn when loading a
1185 `.el' file instead of an `.elc'. If this variable is true, then
1186 when `load' is called with a filename without an extension, and
1187 the `.elc' version doesn't exist but the `.el' version does, then
1188 a message will be printed. If an explicit extension is passed to
1189 `load', no warning will be printed. The default is `nil', but it
1190 is bound to `t' during the initial loadup.
1192 - User Option: load-ignore-elc-files
1193 This variable specifies whether `load' should ignore `.elc' files
1194 when a suffix is not given. This is normally used only to
1195 bootstrap the `.elc' files when building XEmacs, when you use the
1196 command `make all-elc'. (This forces the `.el' versions to be
1197 loaded in the process of compiling those same files, so that
1198 existing out-of-date `.elc' files do not make it mess things up.)
1200 To learn how `load' is used to build XEmacs, see *Note Building