1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions
58 You can define an "inline function" by using `defsubst' instead of
59 `defun'. An inline function works just like an ordinary function
60 except for one thing: when you compile a call to the function, the
61 function's definition is open-coded into the caller.
63 Making a function inline makes explicit calls run faster. But it
64 also has disadvantages. For one thing, it reduces flexibility; if you
65 change the definition of the function, calls already inlined still use
66 the old definition until you recompile them. Since the flexibility of
67 redefining functions is an important feature of XEmacs, you should not
68 make a function inline unless its speed is really crucial.
70 Another disadvantage is that making a large function inline can
71 increase the size of compiled code both in files and in memory. Since
72 the speed advantage of inline functions is greatest for small
73 functions, you generally should not make large functions inline.
75 It's possible to define a macro to expand into the same code that an
76 inline function would execute. But the macro would have a limitation:
77 you can use it only explicitly--a macro cannot be called with `apply',
78 `mapcar' and so on. Also, it takes some work to convert an ordinary
79 function into a macro. (*Note Macros::.) To convert it into an inline
80 function is very easy; simply replace `defun' with `defsubst'. Since
81 each argument of an inline function is evaluated exactly once, you
82 needn't worry about how many times the body uses the arguments, as you
83 do for macros. (*Note Argument Evaluation::.)
85 Inline functions can be used and open-coded later on in the same
86 file, following the definition, just like macros.
89 File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions
91 Other Topics Related to Functions
92 =================================
94 Here is a table of several functions that do things related to
95 function calling and function definitions. They are documented
96 elsewhere, but we provide cross references here.
99 See *Note Calling Functions::.
102 See *Note Autoload::.
105 See *Note Interactive Call::.
108 See *Note Interactive Call::.
111 See *Note Accessing Documentation::.
117 See *Note Calling Functions::.
120 See *Note Calling Functions::.
123 See *Note Function Indirection::.
126 See *Note Using Interactive::.
129 See *Note Interactive Call::.
132 See *Note Creating Symbols::.
135 See *Note Mapping Functions::.
138 See *Note Mapping Functions::.
141 See *Note Key Lookup::.
144 File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top
149 "Macros" enable you to define new control constructs and other
150 language features. A macro is defined much like a function, but instead
151 of telling how to compute a value, it tells how to compute another Lisp
152 expression which will in turn compute the value. We call this
153 expression the "expansion" of the macro.
155 Macros can do this because they operate on the unevaluated
156 expressions for the arguments, not on the argument values as functions
157 do. They can therefore construct an expansion containing these
158 argument expressions or parts of them.
160 If you are using a macro to do something an ordinary function could
161 do, just for the sake of speed, consider using an inline function
162 instead. *Note Inline Functions::.
166 * Simple Macro:: A basic example.
167 * Expansion:: How, when and why macros are expanded.
168 * Compiling Macros:: How macros are expanded by the compiler.
169 * Defining Macros:: How to write a macro definition.
170 * Backquote:: Easier construction of list structure.
171 * Problems with Macros:: Don't evaluate the macro arguments too many times.
172 Don't hide the user's variables.
175 File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros
177 A Simple Example of a Macro
178 ===========================
180 Suppose we would like to define a Lisp construct to increment a
181 variable value, much like the `++' operator in C. We would like to
182 write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a
183 macro definition that does the job:
186 (list 'setq var (list '1+ var)))
188 When this is called with `(inc x)', the argument `var' has the value
189 `x'--_not_ the _value_ of `x'. The body of the macro uses this to
190 construct the expansion, which is `(setq x (1+ x))'. Once the macro
191 definition returns this expansion, Lisp proceeds to evaluate it, thus
195 File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros
197 Expansion of a Macro Call
198 =========================
200 A macro call looks just like a function call in that it is a list
201 which starts with the name of the macro. The rest of the elements of
202 the list are the arguments of the macro.
204 Evaluation of the macro call begins like evaluation of a function
205 call except for one crucial difference: the macro arguments are the
206 actual expressions appearing in the macro call. They are not evaluated
207 before they are given to the macro definition. By contrast, the
208 arguments of a function are results of evaluating the elements of the
211 Having obtained the arguments, Lisp invokes the macro definition just
212 as a function is invoked. The argument variables of the macro are bound
213 to the argument values from the macro call, or to a list of them in the
214 case of a `&rest' argument. And the macro body executes and returns
215 its value just as a function body does.
217 The second crucial difference between macros and functions is that
218 the value returned by the macro body is not the value of the macro call.
219 Instead, it is an alternate expression for computing that value, also
220 known as the "expansion" of the macro. The Lisp interpreter proceeds
221 to evaluate the expansion as soon as it comes back from the macro.
223 Since the expansion is evaluated in the normal manner, it may contain
224 calls to other macros. It may even be a call to the same macro, though
227 You can see the expansion of a given macro call by calling
230 - Function: macroexpand form &optional environment
231 This function expands FORM, if it is a macro call. If the result
232 is another macro call, it is expanded in turn, until something
233 which is not a macro call results. That is the value returned by
234 `macroexpand'. If FORM is not a macro call to begin with, it is
237 Note that `macroexpand' does not look at the subexpressions of
238 FORM (although some macro definitions may do so). Even if they
239 are macro calls themselves, `macroexpand' does not expand them.
241 The function `macroexpand' does not expand calls to inline
242 functions. Normally there is no need for that, since a call to an
243 inline function is no harder to understand than a call to an
246 If ENVIRONMENT is provided, it specifies an alist of macro
247 definitions that shadow the currently defined macros. Byte
248 compilation uses this feature.
251 (list 'setq var (list '1+ var)))
254 (macroexpand '(inc r))
257 (defmacro inc2 (var1 var2)
258 (list 'progn (list 'inc var1) (list 'inc var2)))
261 (macroexpand '(inc2 r s))
262 => (progn (inc r) (inc s)) ; `inc' not expanded here.
265 File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
267 Macros and Byte Compilation
268 ===========================
270 You might ask why we take the trouble to compute an expansion for a
271 macro and then evaluate the expansion. Why not have the macro body
272 produce the desired results directly? The reason has to do with
275 When a macro call appears in a Lisp program being compiled, the Lisp
276 compiler calls the macro definition just as the interpreter would, and
277 receives an expansion. But instead of evaluating this expansion, it
278 compiles the expansion as if it had appeared directly in the program.
279 As a result, the compiled code produces the value and side effects
280 intended for the macro, but executes at full compiled speed. This would
281 not work if the macro body computed the value and side effects
282 itself--they would be computed at compile time, which is not useful.
284 In order for compilation of macro calls to work, the macros must be
285 defined in Lisp when the calls to them are compiled. The compiler has a
286 special feature to help you do this: if a file being compiled contains a
287 `defmacro' form, the macro is defined temporarily for the rest of the
288 compilation of that file. To use this feature, you must define the
289 macro in the same file where it is used and before its first use.
291 Byte-compiling a file executes any `require' calls at top-level in
292 the file. This is in case the file needs the required packages for
293 proper compilation. One way to ensure that necessary macro definitions
294 are available during compilation is to require the files that define
295 them (*note Named Features::). To avoid loading the macro definition
296 files when someone _runs_ the compiled program, write
297 `eval-when-compile' around the `require' calls (*note Eval During
301 File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
306 A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
307 function; expansion of the macro works by applying the function (with
308 `apply') to the list of unevaluated argument-expressions from the macro
311 It is possible to use an anonymous Lisp macro just like an anonymous
312 function, but this is never done, because it does not make sense to pass
313 an anonymous macro to functionals such as `mapcar'. In practice, all
314 Lisp macros have names, and they are usually defined with the special
317 - Special Form: defmacro name argument-list body-forms...
318 `defmacro' defines the symbol NAME as a macro that looks like this:
320 (macro lambda ARGUMENT-LIST . BODY-FORMS)
322 This macro object is stored in the function cell of NAME. The
323 value returned by evaluating the `defmacro' form is NAME, but
324 usually we ignore this value.
326 The shape and meaning of ARGUMENT-LIST is the same as in a
327 function, and the keywords `&rest' and `&optional' may be used
328 (*note Argument List::). Macros may have a documentation string,
329 but any `interactive' declaration is ignored since macros cannot be
330 called interactively.
333 File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
338 Macros often need to construct large list structures from a mixture
339 of constants and nonconstant parts. To make this easier, use the macro
340 ``' (often called "backquote").
342 Backquote allows you to quote a list, but selectively evaluate
343 elements of that list. In the simplest case, it is identical to the
344 special form `quote' (*note Quoting::). For example, these two forms
345 yield identical results:
347 `(a list of (+ 2 3) elements)
348 => (a list of (+ 2 3) elements)
349 '(a list of (+ 2 3) elements)
350 => (a list of (+ 2 3) elements)
352 The special marker `,' inside of the argument to backquote indicates
353 a value that isn't constant. Backquote evaluates the argument of `,'
354 and puts the value in the list structure:
356 (list 'a 'list 'of (+ 2 3) 'elements)
357 => (a list of 5 elements)
358 `(a list of ,(+ 2 3) elements)
359 => (a list of 5 elements)
361 You can also "splice" an evaluated value into the resulting list,
362 using the special marker `,@'. The elements of the spliced list become
363 elements at the same level as the other elements of the resulting list.
364 The equivalent code without using ``' is often unreadable. Here are
367 (setq some-list '(2 3))
369 (cons 1 (append some-list '(4) some-list))
371 `(1 ,@some-list 4 ,@some-list)
374 (setq list '(hack foo bar))
378 (cons 'words (append (cdr list) '(as elements)))))
379 => (use the words foo bar as elements)
380 `(use the words ,@(cdr list) as elements)
381 => (use the words foo bar as elements)
383 In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
384 version 19.29), ``' used a different syntax which required an
385 extra level of parentheses around the entire backquote construct.
386 Likewise, each `,' or `,@' substitution required an extra level of
387 parentheses surrounding both the `,' or `,@' and the following
388 expression. The old syntax required whitespace between the ``',
389 `,' or `,@' and the following expression.
391 This syntax is still accepted, but no longer recommended except for
392 compatibility with old Emacs versions.
395 File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
397 Common Problems Using Macros
398 ============================
400 The basic facts of macro expansion have counterintuitive
401 consequences. This section describes some important consequences that
402 can lead to trouble, and rules to follow to avoid trouble.
406 * Argument Evaluation:: The expansion should evaluate each macro arg once.
407 * Surprising Local Vars:: Local variable bindings in the expansion
408 require special care.
409 * Eval During Expansion:: Don't evaluate them; put them in the expansion.
410 * Repeated Expansion:: Avoid depending on how many times expansion is done.
413 File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
415 Evaluating Macro Arguments Repeatedly
416 -------------------------------------
418 When defining a macro you must pay attention to the number of times
419 the arguments will be evaluated when the expansion is executed. The
420 following macro (used to facilitate iteration) illustrates the problem.
421 This macro allows us to write a simple "for" loop such as one might
424 (defmacro for (var from init to final do &rest body)
425 "Execute a simple \"for\" loop.
426 For example, (for i from 1 to 10 do (print i))."
427 (list 'let (list (list var init))
428 (cons 'while (cons (list '<= var final)
429 (append body (list (list 'inc var)))))))
432 (for i from 1 to 3 do
433 (setq square (* i i))
434 (princ (format "\n%d %d" i square)))
438 (setq square (* i i))
439 (princ (format "%d %d" i square))
447 (The arguments `from', `to', and `do' in this macro are "syntactic
448 sugar"; they are entirely ignored. The idea is that you will write
449 noise words (such as `from', `to', and `do') in those positions in the
452 Here's an equivalent definition simplified through use of backquote:
454 (defmacro for (var from init to final do &rest body)
455 "Execute a simple \"for\" loop.
456 For example, (for i from 1 to 10 do (print i))."
458 (while (<= ,var ,final)
462 Both forms of this definition (with backquote and without) suffer
463 from the defect that FINAL is evaluated on every iteration. If FINAL
464 is a constant, this is not a problem. If it is a more complex form,
465 say `(long-complex-calculation x)', this can slow down the execution
466 significantly. If FINAL has side effects, executing it more than once
467 is probably incorrect.
469 A well-designed macro definition takes steps to avoid this problem by
470 producing an expansion that evaluates the argument expressions exactly
471 once unless repeated evaluation is part of the intended purpose of the
472 macro. Here is a correct expansion for the `for' macro:
477 (setq square (* i i))
478 (princ (format "%d %d" i square))
481 Here is a macro definition that creates this expansion:
483 (defmacro for (var from init to final do &rest body)
484 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
491 Unfortunately, this introduces another problem. Proceed to the
495 File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
497 Local Variables in Macro Expansions
498 -----------------------------------
500 In the previous section, the definition of `for' was fixed as
501 follows to make the expansion evaluate the macro arguments the proper
504 (defmacro for (var from init to final do &rest body)
505 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
512 The new definition of `for' has a new problem: it introduces a local
513 variable named `max' which the user does not expect. This causes
514 trouble in examples such as the following:
517 (for x from 0 to 10 do
518 (let ((this (frob x)))
522 The references to `max' inside the body of the `for', which are
523 supposed to refer to the user's binding of `max', really access the
524 binding made by `for'.
526 The way to correct this is to use an uninterned symbol instead of
527 `max' (*note Creating Symbols::). The uninterned symbol can be bound
528 and referred to just like any other symbol, but since it is created by
529 `for', we know that it cannot already appear in the user's program.
530 Since it is not interned, there is no way the user can put it into the
531 program later. It will never appear anywhere except where put by
532 `for'. Here is a definition of `for' that works this way:
534 (defmacro for (var from init to final do &rest body)
535 "Execute a simple for loop: (for i from 1 to 10 do (print i))."
536 (let ((tempvar (make-symbol "max")))
539 (while (<= ,var ,tempvar)
543 This creates an uninterned symbol named `max' and puts it in the
544 expansion instead of the usual interned symbol `max' that appears in
545 expressions ordinarily.
548 File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
550 Evaluating Macro Arguments in Expansion
551 ---------------------------------------
553 Another problem can happen if you evaluate any of the macro argument
554 expressions during the computation of the expansion, such as by calling
555 `eval' (*note Eval::). If the argument is supposed to refer to the
556 user's variables, you may have trouble if the user happens to use a
557 variable with the same name as one of the macro arguments. Inside the
558 macro body, the macro argument binding is the most local binding of this
559 variable, so any references inside the form being evaluated do refer to
560 it. Here is an example:
563 (list 'setq (eval a) t))
566 (foo x) ==> (setq b t)
567 => t ; and `b' has been set.
570 (foo a) ==> (setq a t)
571 => t ; but this set `a', not `c'.
573 It makes a difference whether the user's variable is named `a' or
574 `x', because `a' conflicts with the macro argument variable `a'.
576 Another reason not to call `eval' in a macro definition is that it
577 probably won't do what you intend in a compiled program. The
578 byte-compiler runs macro definitions while compiling the program, when
579 the program's own computations (which you might have wished to access
580 with `eval') don't occur and its local variable bindings don't exist.
582 The safe way to work with the run-time value of an expression is to
583 put the expression into the macro expansion, so that its value is
584 computed as part of executing the expansion.
587 File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
589 How Many Times is the Macro Expanded?
590 -------------------------------------
592 Occasionally problems result from the fact that a macro call is
593 expanded each time it is evaluated in an interpreted function, but is
594 expanded only once (during compilation) for a compiled function. If the
595 macro definition has side effects, they will work differently depending
596 on how many times the macro is expanded.
598 In particular, constructing objects is a kind of side effect. If the
599 macro is called once, then the objects are constructed only once. In
600 other words, the same structure of objects is used each time the macro
601 call is executed. In interpreted operation, the macro is reexpanded
602 each time, producing a fresh collection of objects each time. Usually
603 this does not matter--the objects have the same contents whether they
604 are shared or not. But if the surrounding program does side effects on
605 the objects, it makes a difference whether they are shared. Here is an
608 (defmacro empty-object ()
609 (list 'quote (cons nil nil)))
611 (defun initialize (condition)
612 (let ((object (empty-object)))
614 (setcar object condition))
617 If `initialize' is interpreted, a new list `(nil)' is constructed each
618 time `initialize' is called. Thus, no side effect survives between
619 calls. If `initialize' is compiled, then the macro `empty-object' is
620 expanded during compilation, producing a single "constant" `(nil)' that
621 is reused and altered each time `initialize' is called.
623 One way to avoid pathological cases like this is to think of
624 `empty-object' as a funny kind of constant, not as a memory allocation
625 construct. You wouldn't use `setcar' on a constant such as `'(nil)',
626 so naturally you won't use it on `(empty-object)' either.
629 File: lispref.info, Node: Customization, Up: Top
631 Writing Customization Definitions
632 *********************************
634 This chapter describes how to declare user options for customization,
635 and also customization groups for classifying them. We use the term
636 "customization item" to include both kinds of customization
637 definitions--as well as face definitions.
642 * Group Definitions::
643 * Variable Definitions::
644 * Customization Types::
647 File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
649 Common Keywords for All Kinds of Items
650 ======================================
652 All kinds of customization declarations (for variables and groups,
653 and for faces) accept keyword arguments for specifying various
654 information. This section describes some keywords that apply to all
657 All of these keywords, except `:tag', can be used more than once in
658 a given item. Each use of the keyword has an independent effect. The
659 keyword `:tag' is an exception because any given item can only display
663 Use NAME, a string, instead of the item's name, to label the item
664 in customization menus and buffers.
667 Put this customization item in group GROUP. When you use `:group'
668 in a `defgroup', it makes the new group a subgroup of GROUP.
670 If you use this keyword more than once, you can put a single item
671 into more than one group. Displaying any of those groups will
672 show this item. Be careful not to overdo this!
675 Include an external link after the documentation string for this
676 item. This is a sentence containing an active field which
677 references some other documentation.
679 There are three alternatives you can use for LINK-DATA:
681 `(custom-manual INFO-NODE)'
682 Link to an Info node; INFO-NODE is a string which specifies
683 the node name, as in `"(emacs)Top"'. The link appears as
684 `[manual]' in the customization buffer.
686 `(info-link INFO-NODE)'
687 Like `custom-manual' except that the link appears in the
688 customization buffer with the Info node name.
691 Link to a web page; URL is a string which specifies the URL.
692 The link appears in the customization buffer as URL.
694 You can specify the text to use in the customization buffer by
695 adding `:tag NAME' after the first element of the LINK-DATA; for
696 example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
697 Emacs manual which appears in the buffer as `foo'.
699 An item can have more than one external link; however, most items
703 Load file FILE (a string) before displaying this customization
704 item. Loading is done with `load-library', and only if the file is
708 Require feature FEATURE (a symbol) when installing a value for
709 this item (an option or a face) that was saved using the
710 customization feature. This is done by calling `require'.
712 The most common reason to use `:require' is when a variable enables
713 a feature such as a minor mode, and just setting the variable
714 won't have any effect unless the code which implements the mode is
718 File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
720 Defining Custom Groups
721 ======================
723 Each Emacs Lisp package should have one main customization group
724 which contains all the options, faces and other groups in the package.
725 If the package has a small number of options and faces, use just one
726 group and put everything in it. When there are more than twelve or so
727 options and faces, then you should structure them into subgroups, and
728 put the subgroups under the package's main customization group. It is
729 OK to put some of the options and faces in the package's main group
730 alongside the subgroups.
732 The package's main or only group should be a member of one or more of
733 the standard customization groups. (To display the full list of them,
734 use `M-x customize'.) Choose one or more of them (but not too many),
735 and add your group to each of them using the `:group' keyword.
737 The way to declare new customization groups is with `defgroup'.
739 - Macro: defgroup group members doc [keyword value]...
740 Declare GROUP as a customization group containing MEMBERS. Do not
741 quote the symbol GROUP. The argument DOC specifies the
742 documentation string for the group.
744 The argument MEMBERS is a list specifying an initial set of
745 customization items to be members of the group. However, most
746 often MEMBERS is `nil', and you specify the group's members by
747 using the `:group' keyword when defining those members.
749 If you want to specify group members through MEMBERS, each element
750 should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
751 WIDGET is a widget type for editing that symbol. Useful widgets
752 are `custom-variable' for a variable, `custom-face' for a face,
753 and `custom-group' for a group.
755 In addition to the common keywords (*note Common Keywords::), you
756 can use this keyword in `defgroup':
759 If the name of an item in the group starts with PREFIX, then
760 the tag for that item is constructed (by default) by omitting
763 One group can have any number of prefixes.
766 File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
768 Defining Customization Variables
769 ================================
771 Use `defcustom' to declare user-editable variables.
773 - Macro: defcustom option default doc [keyword value]...
774 Declare OPTION as a customizable user option variable. Do not
775 quote OPTION. The argument DOC specifies the documentation string
778 If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
779 should be an expression to compute the value; be careful in
780 writing it, because it can be evaluated on more than one occasion.
782 The following additional keywords are defined:
785 Use TYPE as the data type for this option. It specifies which
786 values are legitimate, and how to display the value. *Note
787 Customization Types::, for more information.
790 Specify LIST as the list of reasonable values for use in this
793 Currently this is meaningful only when the type is `hook'.
794 In that case, the elements of LIST should be functions that
795 are useful as elements of the hook value. The user is not
796 restricted to using only these functions, but they are
797 offered as convenient alternatives.
800 This option specifies that the variable was first introduced,
801 or its default value was changed, in Emacs version VERSION.
802 The value VERSION must be a string. For example,
804 (defcustom foo-max 34
805 "*Maximum number of foo's allowed."
811 Specify SETFUNCTION as the way to change the value of this
812 option. The function SETFUNCTION should take two arguments,
813 a symbol and the new value, and should do whatever is
814 necessary to update the value properly for this option (which
815 may not mean simply setting the option as a Lisp variable).
816 The default for SETFUNCTION is `set-default'.
819 Specify GETFUNCTION as the way to extract the value of this
820 option. The function GETFUNCTION should take one argument, a
821 symbol, and should return the "current value" for that symbol
822 (which need not be the symbol's Lisp value). The default is
825 `:initialize FUNCTION'
826 FUNCTION should be a function used to initialize the variable
827 when the `defcustom' is evaluated. It should take two
828 arguments, the symbol and value. Here are some predefined
829 functions meant for use in this way:
831 `custom-initialize-set'
832 Use the variable's `:set' function to initialize the
833 variable, but do not reinitialize it if it is already
834 non-void. This is the default `:initialize' function.
836 `custom-initialize-default'
837 Like `custom-initialize-set', but use the function
838 `set-default' to set the variable, instead of the
839 variable's `:set' function. This is the usual choice
840 for a variable whose `:set' function enables or disables
841 a minor mode; with this choice, defining the variable
842 will not call the minor mode function, but customizing
843 the variable will do so.
845 `custom-initialize-reset'
846 Always use the `:set' function to initialize the
847 variable. If the variable is already non-void, reset it
848 by calling the `:set' function using the current value
849 (returned by the `:get' method).
851 `custom-initialize-changed'
852 Use the `:set' function to initialize the variable, if
853 it is already set or has been customized; otherwise,
854 just use `set-default'.
856 The `:require' option is useful for an option that turns on the
857 operation of a certain feature. Assuming that the package is coded to
858 check the value of the option, you still need to arrange for the package
859 to be loaded. You can do that with `:require'. *Note Common
860 Keywords::. Here is an example, from the library `paren.el':
862 (defcustom show-paren-mode nil
863 "Toggle Show Paren mode...."
864 :set (lambda (symbol value)
865 (show-paren-mode (or value 0)))
866 :initialize 'custom-initialize-default
868 :group 'paren-showing
871 Internally, `defcustom' uses the symbol property `standard-value' to
872 record the expression for the default value, and `saved-value' to
873 record the value saved by the user with the customization buffer. The
874 `saved-value' property is actually a list whose car is an expression
875 which evaluates to the value.
878 File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
883 When you define a user option with `defcustom', you must specify its
884 "customization type". That is a Lisp object which describes (1) which
885 values are legitimate and (2) how to display the value in the
886 customization buffer for editing.
888 You specify the customization type in `defcustom' with the `:type'
889 keyword. The argument of `:type' is evaluated; since types that vary
890 at run time are rarely useful, normally you use a quoted constant. For
893 (defcustom diff-command "diff"
894 "*The command to use to run diff."
898 In general, a customization type is a list whose first element is a
899 symbol, one of the customization type names defined in the following
900 sections. After this symbol come a number of arguments, depending on
901 the symbol. Between the type symbol and its arguments, you can
902 optionally write keyword-value pairs (*note Type Keywords::).
904 Some of the type symbols do not use any arguments; those are called
905 "simple types". For a simple type, if you do not use any keyword-value
906 pairs, you can omit the parentheses around the type symbol. For
907 example just `string' as a customization type is equivalent to
914 * Splicing into Lists::
918 File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
923 This section describes all the simple customization types.
926 The value may be any Lisp object that can be printed and read
927 back. You can use `sexp' as a fall-back for any option, if you
928 don't want to take the time to work out a more specific type to
932 The value must be an integer, and is represented textually in the
933 customization buffer.
936 The value must be a number, and is represented textually in the
937 customization buffer.
940 The value must be a string, and the customization buffer shows
941 just the contents, with no delimiting `"' characters and no
945 Like `string' except that the string must be a valid regular
949 The value must be a character code. A character code is actually
950 an integer, but this type shows the value by inserting the
951 character in the buffer, rather than by showing the number.
954 The value must be a file name, and you can do completion with
957 `(file :must-match t)'
958 The value must be a file name for an existing file, and you can do
959 completion with `M-<TAB>'.
962 The value must be a directory name, and you can do completion with
966 The value must be a symbol. It appears in the customization
967 buffer as the name of the symbol.
970 The value must be either a lambda expression or a function name.
971 When it is a function name, you can do completion with `M-<TAB>'.
974 The value must be a variable name, and you can do completion with
978 The value must be a symbol which is a face name.
981 The value is boolean--either `nil' or `t'. Note that by using
982 `choice' and `const' together (see the next section), you can
983 specify that the value must be `nil' or `t', but also specify the
984 text to describe each value in a way that fits the specific
985 meaning of the alternative.
988 File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
993 When none of the simple types is appropriate, you can use composite
994 types, which build new types from other types. Here are several ways of
997 `(restricted-sexp :match-alternatives CRITERIA)'
998 The value may be any Lisp object that satisfies one of CRITERIA.
999 CRITERIA should be a list, and each elements should be one of
1000 these possibilities:
1002 * A predicate--that is, a function of one argument that returns
1003 non-`nil' if the argument fits a certain type. This means
1004 that objects of that type are acceptable.
1006 * A quoted constant--that is, `'OBJECT'. This means that
1007 OBJECT itself is an acceptable value.
1011 (restricted-sexp :match-alternatives (integerp 't 'nil))
1013 allows integers, `t' and `nil' as legitimate values.
1015 The customization buffer shows all legitimate values using their
1016 read syntax, and the user edits them textually.
1018 `(cons CAR-TYPE CDR-TYPE)'
1019 The value must be a cons cell, its CAR must fit CAR-TYPE, and its
1020 CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
1021 customization type which matches values such as `("foo" . foo)'.
1023 In the customization buffer, the CAR and the CDR are displayed and
1024 edited separately, each according to the type that you specify for
1027 `(list ELEMENT-TYPES...)'
1028 The value must be a list with exactly as many elements as the
1029 ELEMENT-TYPES you have specified; and each element must fit the
1030 corresponding ELEMENT-TYPE.
1032 For example, `(list integer string function)' describes a list of
1033 three elements; the first element must be an integer, the second a
1034 string, and the third a function.
1036 In the customization buffer, the each element is displayed and
1037 edited separately, according to the type specified for it.
1039 `(vector ELEMENT-TYPES...)'
1040 Like `list' except that the value must be a vector instead of a
1041 list. The elements work the same as in `list'.
1043 `(choice ALTERNATIVE-TYPES...)'
1044 The value must fit at least one of ALTERNATIVE-TYPES. For
1045 example, `(choice integer string)' allows either an integer or a
1048 In the customization buffer, the user selects one of the
1049 alternatives using a menu, and can then edit the value in the
1050 usual way for that alternative.
1052 Normally the strings in this menu are determined automatically
1053 from the choices; however, you can specify different strings for
1054 the menu by including the `:tag' keyword in the alternatives. For
1055 example, if an integer stands for a number of spaces, while a
1056 string is text to use verbatim, you might write the customization
1059 (choice (integer :tag "Number of spaces")
1060 (string :tag "Literal text"))
1062 so that the menu offers `Number of spaces' and `Literal Text'.
1064 In any alternative for which `nil' is not a valid value, other than
1065 a `const', you should specify a valid default for that alternative
1066 using the `:value' keyword. *Note Type Keywords::.
1069 The value must be VALUE--nothing else is allowed.
1071 The main use of `const' is inside of `choice'. For example,
1072 `(choice integer (const nil))' allows either an integer or `nil'.
1074 `:tag' is often used with `const', inside of `choice'. For
1077 (choice (const :tag "Yes" t)
1078 (const :tag "No" nil)
1079 (const :tag "Ask" foo))
1081 `(function-item FUNCTION)'
1082 Like `const', but used for values which are functions. This
1083 displays the documentation string as well as the function name.
1084 The documentation string is either the one you specify with
1085 `:doc', or FUNCTION's own documentation string.
1087 `(variable-item VARIABLE)'
1088 Like `const', but used for values which are variable names. This
1089 displays the documentation string as well as the variable name.
1090 The documentation string is either the one you specify with
1091 `:doc', or VARIABLE's own documentation string.
1094 The value must be a list and each element of the list must be one
1095 of the ELEMENTS specified. This appears in the customization
1096 buffer as a checklist.
1098 `(repeat ELEMENT-TYPE)'
1099 The value must be a list and each element of the list must fit the
1100 type ELEMENT-TYPE. This appears in the customization buffer as a
1101 list of elements, with `[INS]' and `[DEL]' buttons for adding more
1102 elements or removing elements.
1105 File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
1110 The `:inline' feature lets you splice a variable number of elements
1111 into the middle of a list or vector. You use it in a `set', `choice'
1112 or `repeat' type which appears among the element-types of a `list' or
1115 Normally, each of the element-types in a `list' or `vector'
1116 describes one and only one element of the list or vector. Thus, if an
1117 element-type is a `repeat', that specifies a list of unspecified length
1118 which appears as one element.
1120 But when the element-type uses `:inline', the value it matches is
1121 merged directly into the containing sequence. For example, if it
1122 matches a list with three elements, those become three elements of the
1123 overall sequence. This is analogous to using `,@' in the backquote
1126 For example, to specify a list whose first element must be `t' and
1127 whose remaining arguments should be zero or more of `foo' and `bar',
1128 use this customization type:
1130 (list (const t) (set :inline t foo bar))
1132 This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
1135 When the element-type is a `choice', you use `:inline' not in the
1136 `choice' itself, but in (some of) the alternatives of the `choice'.
1137 For example, to match a list which must start with a file name,
1138 followed either by the symbol `t' or two strings, use this
1143 (list :inline t string string)))
1145 If the user chooses the first alternative in the choice, then the
1146 overall list has two elements and the second element is `t'. If the
1147 user chooses the second alternative, then the overall list has three
1148 elements and the second and third must be strings.
1151 File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
1156 You can specify keyword-argument pairs in a customization type after
1157 the type name symbol. Here are the keywords you can use, and their
1161 This is used for a type that appears as an alternative inside of
1162 `choice'; it specifies the default value to use, at first, if and
1163 when the user selects this alternative with the menu in the
1164 customization buffer.
1166 Of course, if the actual value of the option fits this
1167 alternative, it will appear showing the actual value, not DEFAULT.
1169 If `nil' is not a valid value for the alternative, then it is
1170 essential to specify a valid default with `:value'.
1172 `:format FORMAT-STRING'
1173 This string will be inserted in the buffer to represent the value
1174 corresponding to the type. The following `%' escapes are available
1175 for use in FORMAT-STRING:
1178 Display the text BUTTON marked as a button. The `:action'
1179 attribute specifies what the button will do if the user
1180 invokes it; its value is a function which takes two
1181 arguments--the widget which the button appears in, and the
1184 There is no way to specify two different buttons with
1188 Show SAMPLE in a special face specified by `:sample-face'.
1191 Substitute the item's value. How the value is represented
1192 depends on the kind of item, and (for variables) on the
1196 Substitute the item's documentation string.
1199 Like `%d', but if the documentation string is more than one
1200 line, add an active field to control whether to show all of
1201 it or just the first line.
1204 Substitute the tag here. You specify the tag with the `:tag'
1208 Display a literal `%'.
1211 Perform ACTION if the user clicks on a button.
1214 Use the face FACE (a face name or a list of face names) for button
1215 text displayed with `%[...%]'.
1217 `:button-prefix PREFIX'
1218 `:button-suffix SUFFIX'
1219 These specify the text to display before and after a button. Each
1223 No text is inserted.
1226 The string is inserted literally.
1229 The symbol's value is used.
1232 Use TAG (a string) as the tag for the value (or part of the value)
1233 that corresponds to this type.
1236 Use DOC as the documentation string for this value (or part of the
1237 value) that corresponds to this type. In order for this to work,
1238 you must specify a value for `:format', and use `%d' or `%h' in
1241 The usual reason to specify a documentation string for a type is to
1242 provide more information about the meanings of alternatives inside
1243 a `:choice' type or the parts of some other composite type.
1245 `:help-echo MOTION-DOC'
1246 When you move to this item with `widget-forward' or
1247 `widget-backward', it will display the string MOTION-DOC in the
1251 Specify how to decide whether a value matches the type. The
1252 corresponding value, FUNCTION, should be a function that accepts
1253 two arguments, a widget and a value; it should return non-`nil' if
1254 the value is acceptable.
1257 File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
1262 Loading a file of Lisp code means bringing its contents into the Lisp
1263 environment in the form of Lisp objects. XEmacs finds and opens the
1264 file, reads the text, evaluates each form, and then closes the file.
1266 The load functions evaluate all the expressions in a file just as
1267 the `eval-current-buffer' function evaluates all the expressions in a
1268 buffer. The difference is that the load functions read and evaluate
1269 the text in the file as found on disk, not the text in an Emacs buffer.
1271 The loaded file must contain Lisp expressions, either as source code
1272 or as byte-compiled code. Each form in the file is called a "top-level
1273 form". There is no special format for the forms in a loadable file;
1274 any form in a file may equally well be typed directly into a buffer and
1275 evaluated there. (Indeed, most code is tested this way.) Most often,
1276 the forms are function definitions and variable definitions.
1278 A file containing Lisp code is often called a "library". Thus, the
1279 "Rmail library" is a file containing code for Rmail mode. Similarly, a
1280 "Lisp library directory" is a directory of files containing Lisp code.
1284 * How Programs Do Loading:: The `load' function and others.
1285 * Autoload:: Setting up a function to autoload.
1286 * Repeated Loading:: Precautions about loading a file twice.
1287 * Named Features:: Loading a library if it isn't already loaded.
1288 * Unloading:: How to ``unload'' a library that was loaded.
1289 * Hooks for Loading:: Providing code to be run when
1290 particular libraries are loaded.
projects / chise / xemacs-chise.git- / blob