+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
-
-Backquote
-=========
-
- Macros often need to construct large list structures from a mixture
-of constants and nonconstant parts. To make this easier, use the macro
-``' (often called "backquote").
-
- Backquote allows you to quote a list, but selectively evaluate
-elements of that list. In the simplest case, it is identical to the
-special form `quote' (*note Quoting::.). For example, these two forms
-yield identical results:
-
- `(a list of (+ 2 3) elements)
- => (a list of (+ 2 3) elements)
- '(a list of (+ 2 3) elements)
- => (a list of (+ 2 3) elements)
-
- The special marker `,' inside of the argument to backquote indicates
-a value that isn't constant. Backquote evaluates the argument of `,'
-and puts the value in the list structure:
-
- (list 'a 'list 'of (+ 2 3) 'elements)
- => (a list of 5 elements)
- `(a list of ,(+ 2 3) elements)
- => (a list of 5 elements)
-
- You can also "splice" an evaluated value into the resulting list,
-using the special marker `,@'. The elements of the spliced list become
-elements at the same level as the other elements of the resulting list.
-The equivalent code without using ``' is often unreadable. Here are
-some examples:
-
- (setq some-list '(2 3))
- => (2 3)
- (cons 1 (append some-list '(4) some-list))
- => (1 2 3 4 2 3)
- `(1 ,@some-list 4 ,@some-list)
- => (1 2 3 4 2 3)
-
- (setq list '(hack foo bar))
- => (hack foo bar)
- (cons 'use
- (cons 'the
- (cons 'words (append (cdr list) '(as elements)))))
- => (use the words foo bar as elements)
- `(use the words ,@(cdr list) as elements)
- => (use the words foo bar as elements)
-
- In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
- version 19.29), ``' used a different syntax which required an
- extra level of parentheses around the entire backquote construct.
- Likewise, each `,' or `,@' substitution required an extra level of
- parentheses surrounding both the `,' or `,@' and the following
- expression. The old syntax required whitespace between the ``',
- `,' or `,@' and the following expression.
-
- This syntax is still accepted, but no longer recommended except for
- compatibility with old Emacs versions.
-
-\1f
-File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
-
-Common Problems Using Macros
-============================
-
- The basic facts of macro expansion have counterintuitive
-consequences. This section describes some important consequences that
-can lead to trouble, and rules to follow to avoid trouble.
-
-* Menu:
-
-* Argument Evaluation:: The expansion should evaluate each macro arg once.
-* Surprising Local Vars:: Local variable bindings in the expansion
- require special care.
-* Eval During Expansion:: Don't evaluate them; put them in the expansion.
-* Repeated Expansion:: Avoid depending on how many times expansion is done.
-
-\1f
-File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
-
-Evaluating Macro Arguments Repeatedly
--------------------------------------
-
- When defining a macro you must pay attention to the number of times
-the arguments will be evaluated when the expansion is executed. The
-following macro (used to facilitate iteration) illustrates the problem.
-This macro allows us to write a simple "for" loop such as one might
-find in Pascal.
-
- (defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
- For example, (for i from 1 to 10 do (print i))."
- (list 'let (list (list var init))
- (cons 'while (cons (list '<= var final)
- (append body (list (list 'inc var)))))))
- => for
- (for i from 1 to 3 do
- (setq square (* i i))
- (princ (format "\n%d %d" i square)))
- ==>
-
- (let ((i 1))
- (while (<= i 3)
- (setq square (* i i))
- (princ (format "%d %d" i square))
- (inc i)))
-
-
- -|1 1
- -|2 4
- -|3 9
- => nil
-
-(The arguments `from', `to', and `do' in this macro are "syntactic
-sugar"; they are entirely ignored. The idea is that you will write
-noise words (such as `from', `to', and `do') in those positions in the
-macro call.)
-
- Here's an equivalent definition simplified through use of backquote:
-
- (defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
- For example, (for i from 1 to 10 do (print i))."
- `(let ((,var ,init))
- (while (<= ,var ,final)
- ,@body
- (inc ,var))))
-
- Both forms of this definition (with backquote and without) suffer
-from the defect that FINAL is evaluated on every iteration. If FINAL
-is a constant, this is not a problem. If it is a more complex form,
-say `(long-complex-calculation x)', this can slow down the execution
-significantly. If FINAL has side effects, executing it more than once
-is probably incorrect.
-
- A well-designed macro definition takes steps to avoid this problem by
-producing an expansion that evaluates the argument expressions exactly
-once unless repeated evaluation is part of the intended purpose of the
-macro. Here is a correct expansion for the `for' macro:
-
- (let ((i 1)
- (max 3))
- (while (<= i max)
- (setq square (* i i))
- (princ (format "%d %d" i square))
- (inc i)))
-
- Here is a macro definition that creates this expansion:
-
- (defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
- `(let ((,var ,init)
- (max ,final))
- (while (<= ,var max)
- ,@body
- (inc ,var))))
-
- Unfortunately, this introduces another problem. Proceed to the
-following node.
-
-\1f
-File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
-
-Local Variables in Macro Expansions
------------------------------------
-
- In the previous section, the definition of `for' was fixed as
-follows to make the expansion evaluate the macro arguments the proper
-number of times:
-
- (defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
-
- `(let ((,var ,init)
- (max ,final))
- (while (<= ,var max)
- ,@body
- (inc ,var))))
-
- The new definition of `for' has a new problem: it introduces a local
-variable named `max' which the user does not expect. This causes
-trouble in examples such as the following:
-
- (let ((max 0))
- (for x from 0 to 10 do
- (let ((this (frob x)))
- (if (< max this)
- (setq max this)))))
-
-The references to `max' inside the body of the `for', which are
-supposed to refer to the user's binding of `max', really access the
-binding made by `for'.
-
- The way to correct this is to use an uninterned symbol instead of
-`max' (*note Creating Symbols::.). The uninterned symbol can be bound
-and referred to just like any other symbol, but since it is created by
-`for', we know that it cannot already appear in the user's program.
-Since it is not interned, there is no way the user can put it into the
-program later. It will never appear anywhere except where put by
-`for'. Here is a definition of `for' that works this way:
-
- (defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
- (let ((tempvar (make-symbol "max")))
- `(let ((,var ,init)
- (,tempvar ,final))
- (while (<= ,var ,tempvar)
- ,@body
- (inc ,var)))))
-
-This creates an uninterned symbol named `max' and puts it in the
-expansion instead of the usual interned symbol `max' that appears in
-expressions ordinarily.
-
-\1f
-File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
-
-Evaluating Macro Arguments in Expansion
----------------------------------------
-
- Another problem can happen if you evaluate any of the macro argument
-expressions during the computation of the expansion, such as by calling
-`eval' (*note Eval::.). If the argument is supposed to refer to the
-user's variables, you may have trouble if the user happens to use a
-variable with the same name as one of the macro arguments. Inside the
-macro body, the macro argument binding is the most local binding of this
-variable, so any references inside the form being evaluated do refer to
-it. Here is an example:
-
- (defmacro foo (a)
- (list 'setq (eval a) t))
- => foo
- (setq x 'b)
- (foo x) ==> (setq b t)
- => t ; and `b' has been set.
- ;; but
- (setq a 'c)
- (foo a) ==> (setq a t)
- => t ; but this set `a', not `c'.
-
- It makes a difference whether the user's variable is named `a' or
-`x', because `a' conflicts with the macro argument variable `a'.
-
- Another reason not to call `eval' in a macro definition is that it
-probably won't do what you intend in a compiled program. The
-byte-compiler runs macro definitions while compiling the program, when
-the program's own computations (which you might have wished to access
-with `eval') don't occur and its local variable bindings don't exist.
-
- The safe way to work with the run-time value of an expression is to
-put the expression into the macro expansion, so that its value is
-computed as part of executing the expansion.
-
-\1f
-File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
-
-How Many Times is the Macro Expanded?
--------------------------------------
-
- Occasionally problems result from the fact that a macro call is
-expanded each time it is evaluated in an interpreted function, but is
-expanded only once (during compilation) for a compiled function. If the
-macro definition has side effects, they will work differently depending
-on how many times the macro is expanded.
-
- In particular, constructing objects is a kind of side effect. If the
-macro is called once, then the objects are constructed only once. In
-other words, the same structure of objects is used each time the macro
-call is executed. In interpreted operation, the macro is reexpanded
-each time, producing a fresh collection of objects each time. Usually
-this does not matter--the objects have the same contents whether they
-are shared or not. But if the surrounding program does side effects on
-the objects, it makes a difference whether they are shared. Here is an
-example:
-
- (defmacro empty-object ()
- (list 'quote (cons nil nil)))
-
- (defun initialize (condition)
- (let ((object (empty-object)))
- (if condition
- (setcar object condition))
- object))
-
-If `initialize' is interpreted, a new list `(nil)' is constructed each
-time `initialize' is called. Thus, no side effect survives between
-calls. If `initialize' is compiled, then the macro `empty-object' is
-expanded during compilation, producing a single "constant" `(nil)' that
-is reused and altered each time `initialize' is called.
-
- One way to avoid pathological cases like this is to think of
-`empty-object' as a funny kind of constant, not as a memory allocation
-construct. You wouldn't use `setcar' on a constant such as `'(nil)',
-so naturally you won't use it on `(empty-object)' either.
-
-\1f
-File: lispref.info, Node: Customization, Up: Top
-
-Writing Customization Definitions
-*********************************
-
- This chapter describes how to declare user options for customization,
-and also customization groups for classifying them. We use the term
-"customization item" to include both kinds of customization
-definitions--as well as face definitions.
-
-* Menu:
-
-* Common Keywords::
-* Group Definitions::
-* Variable Definitions::
-* Customization Types::
-
-\1f
-File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
-
-Common Keywords for All Kinds of Items
-======================================
-
- All kinds of customization declarations (for variables and groups,
-and for faces) accept keyword arguments for specifying various
-information. This section describes some keywords that apply to all
-kinds.
-
- All of these keywords, except `:tag', can be used more than once in
-a given item. Each use of the keyword has an independent effect. The
-keyword `:tag' is an exception because any given item can only display
-one name.
-
-`:tag NAME'
- Use NAME, a string, instead of the item's name, to label the item
- in customization menus and buffers.
-
-`:group GROUP'
- Put this customization item in group GROUP. When you use `:group'
- in a `defgroup', it makes the new group a subgroup of GROUP.
-
- If you use this keyword more than once, you can put a single item
- into more than one group. Displaying any of those groups will
- show this item. Be careful not to overdo this!
-
-`:link LINK-DATA'
- Include an external link after the documentation string for this
- item. This is a sentence containing an active field which
- references some other documentation.
-
- There are three alternatives you can use for LINK-DATA:
-
- `(custom-manual INFO-NODE)'
- Link to an Info node; INFO-NODE is a string which specifies
- the node name, as in `"(emacs)Top"'. The link appears as
- `[manual]' in the customization buffer.
-
- `(info-link INFO-NODE)'
- Like `custom-manual' except that the link appears in the
- customization buffer with the Info node name.
-
- `(url-link URL)'
- Link to a web page; URL is a string which specifies the URL.
- The link appears in the customization buffer as URL.
-
- You can specify the text to use in the customization buffer by
- adding `:tag NAME' after the first element of the LINK-DATA; for
- example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
- Emacs manual which appears in the buffer as `foo'.
-
- An item can have more than one external link; however, most items
- have none at all.
-
-`:load FILE'
- Load file FILE (a string) before displaying this customization
- item. Loading is done with `load-library', and only if the file is
- not already loaded.
-
-`:require FEATURE'
- Require feature FEATURE (a symbol) when installing a value for
- this item (an option or a face) that was saved using the
- customization feature. This is done by calling `require'.
-
- The most common reason to use `:require' is when a variable enables
- a feature such as a minor mode, and just setting the variable
- won't have any effect unless the code which implements the mode is
- loaded.
-
-\1f
-File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
-
-Defining Custom Groups
-======================
-
- Each Emacs Lisp package should have one main customization group
-which contains all the options, faces and other groups in the package.
-If the package has a small number of options and faces, use just one
-group and put everything in it. When there are more than twelve or so
-options and faces, then you should structure them into subgroups, and
-put the subgroups under the package's main customization group. It is
-OK to put some of the options and faces in the package's main group
-alongside the subgroups.
-
- The package's main or only group should be a member of one or more of
-the standard customization groups. (To display the full list of them,
-use `M-x customize'.) Choose one or more of them (but not too many),
-and add your group to each of them using the `:group' keyword.
-
- The way to declare new customization groups is with `defgroup'.
-
- - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
- Declare GROUP as a customization group containing MEMBERS. Do not
- quote the symbol GROUP. The argument DOC specifies the
- documentation string for the group.
-
- The argument MEMBERS is a list specifying an initial set of
- customization items to be members of the group. However, most
- often MEMBERS is `nil', and you specify the group's members by
- using the `:group' keyword when defining those members.
-
- If you want to specify group members through MEMBERS, each element
- should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
- WIDGET is a widget type for editing that symbol. Useful widgets
- are `custom-variable' for a variable, `custom-face' for a face,
- and `custom-group' for a group.
-
- In addition to the common keywords (*note Common Keywords::.), you
- can use this keyword in `defgroup':
-
- `:prefix PREFIX'
- If the name of an item in the group starts with PREFIX, then
- the tag for that item is constructed (by default) by omitting
- PREFIX.
-
- One group can have any number of prefixes.
-
-\1f
-File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
-
-Defining Customization Variables
-================================
-
- Use `defcustom' to declare user-editable variables.
-
- - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
- Declare OPTION as a customizable user option variable. Do not
- quote OPTION. The argument DOC specifies the documentation string
- for the variable.
-
- If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
- should be an expression to compute the value; be careful in
- writing it, because it can be evaluated on more than one occasion.
-
- The following additional keywords are defined:
-
- `:type TYPE'
- Use TYPE as the data type for this option. It specifies which
- values are legitimate, and how to display the value. *Note
- Customization Types::, for more information.
-
- `:options LIST'
- Specify LIST as the list of reasonable values for use in this
- option.
-
- Currently this is meaningful only when the type is `hook'.
- In that case, the elements of LIST should be functions that
- are useful as elements of the hook value. The user is not
- restricted to using only these functions, but they are
- offered as convenient alternatives.
-
- `:version VERSION'
- This option specifies that the variable was first introduced,
- or its default value was changed, in Emacs version VERSION.
- The value VERSION must be a string. For example,
-
- (defcustom foo-max 34
- "*Maximum number of foo's allowed."
- :type 'integer
- :group 'foo
- :version "20.3")
-
- `:set SETFUNCTION'
- Specify SETFUNCTION as the way to change the value of this
- option. The function SETFUNCTION should take two arguments,
- a symbol and the new value, and should do whatever is
- necessary to update the value properly for this option (which
- may not mean simply setting the option as a Lisp variable).
- The default for SETFUNCTION is `set-default'.
-
- `:get GETFUNCTION'
- Specify GETFUNCTION as the way to extract the value of this
- option. The function GETFUNCTION should take one argument, a
- symbol, and should return the "current value" for that symbol
- (which need not be the symbol's Lisp value). The default is
- `default-value'.
-
- `:initialize FUNCTION'
- FUNCTION should be a function used to initialize the variable
- when the `defcustom' is evaluated. It should take two
- arguments, the symbol and value. Here are some predefined
- functions meant for use in this way:
-
- `custom-initialize-set'
- Use the variable's `:set' function to initialize the
- variable, but do not reinitialize it if it is already
- non-void. This is the default `:initialize' function.
-
- `custom-initialize-default'
- Like `custom-initialize-set', but use the function
- `set-default' to set the variable, instead of the
- variable's `:set' function. This is the usual choice
- for a variable whose `:set' function enables or disables
- a minor mode; with this choice, defining the variable
- will not call the minor mode function, but customizing
- the variable will do so.
-
- `custom-initialize-reset'
- Always use the `:set' function to initialize the
- variable. If the variable is already non-void, reset it
- by calling the `:set' function using the current value
- (returned by the `:get' method).
-
- `custom-initialize-changed'
- Use the `:set' function to initialize the variable, if
- it is already set or has been customized; otherwise,
- just use `set-default'.
-
- The `:require' option is useful for an option that turns on the
-operation of a certain feature. Assuming that the package is coded to
-check the value of the option, you still need to arrange for the package
-to be loaded. You can do that with `:require'. *Note Common
-Keywords::. Here is an example, from the library `paren.el':
-
- (defcustom show-paren-mode nil
- "Toggle Show Paren mode...."
- :set (lambda (symbol value)
- (show-paren-mode (or value 0)))
- :initialize 'custom-initialize-default
- :type 'boolean
- :group 'paren-showing
- :require 'paren)
-
- Internally, `defcustom' uses the symbol property `standard-value' to
-record the expression for the default value, and `saved-value' to
-record the value saved by the user with the customization buffer. The
-`saved-value' property is actually a list whose car is an expression
-which evaluates to the value.
-
-\1f
-File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
-
-Customization Types
-===================
-
- When you define a user option with `defcustom', you must specify its
-"customization type". That is a Lisp object which describes (1) which
-values are legitimate and (2) how to display the value in the
-customization buffer for editing.
-
- You specify the customization type in `defcustom' with the `:type'
-keyword. The argument of `:type' is evaluated; since types that vary
-at run time are rarely useful, normally you use a quoted constant. For
-example:
-
- (defcustom diff-command "diff"
- "*The command to use to run diff."
- :type '(string)
- :group 'diff)
-
- In general, a customization type is a list whose first element is a
-symbol, one of the customization type names defined in the following
-sections. After this symbol come a number of arguments, depending on
-the symbol. Between the type symbol and its arguments, you can
-optionally write keyword-value pairs (*note Type Keywords::.).
-
- Some of the type symbols do not use any arguments; those are called
-"simple types". For a simple type, if you do not use any keyword-value
-pairs, you can omit the parentheses around the type symbol. For
-example just `string' as a customization type is equivalent to
-`(string)'.
-
-* Menu:
-
-* Simple Types::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-
-\1f
-File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
-
-Simple Types
-------------
-
- This section describes all the simple customization types.
-
-`sexp'
- The value may be any Lisp object that can be printed and read
- back. You can use `sexp' as a fall-back for any option, if you
- don't want to take the time to work out a more specific type to
- use.
-
-`integer'
- The value must be an integer, and is represented textually in the
- customization buffer.
-
-`number'
- The value must be a number, and is represented textually in the
- customization buffer.
-
-`string'
- The value must be a string, and the customization buffer shows
- just the contents, with no delimiting `"' characters and no
- quoting with `\'.
-
-`regexp'
- Like `string' except that the string must be a valid regular
- expression.
-
-`character'
- The value must be a character code. A character code is actually
- an integer, but this type shows the value by inserting the
- character in the buffer, rather than by showing the number.
-
-`file'
- The value must be a file name, and you can do completion with
- `M-<TAB>'.
-
-`(file :must-match t)'
- The value must be a file name for an existing file, and you can do
- completion with `M-<TAB>'.
-
-`directory'
- The value must be a directory name, and you can do completion with
- `M-<TAB>'.
-
-`symbol'
- The value must be a symbol. It appears in the customization
- buffer as the name of the symbol.
-
-`function'
- The value must be either a lambda expression or a function name.
- When it is a function name, you can do completion with `M-<TAB>'.
-
-`variable'
- The value must be a variable name, and you can do completion with
- `M-<TAB>'.
-
-`face'
- The value must be a symbol which is a face name.
-
-`boolean'
- The value is boolean--either `nil' or `t'. Note that by using
- `choice' and `const' together (see the next section), you can
- specify that the value must be `nil' or `t', but also specify the
- text to describe each value in a way that fits the specific
- meaning of the alternative.
-
-\1f
-File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
-
-Composite Types
----------------
-
- When none of the simple types is appropriate, you can use composite
-types, which build new types from other types. Here are several ways of
-doing that:
-
-`(restricted-sexp :match-alternatives CRITERIA)'
- The value may be any Lisp object that satisfies one of CRITERIA.
- CRITERIA should be a list, and each elements should be one of
- these possibilities:
-
- * A predicate--that is, a function of one argument that returns
- non-`nil' if the argument fits a certain type. This means
- that objects of that type are acceptable.
-
- * A quoted constant--that is, `'OBJECT'. This means that
- OBJECT itself is an acceptable value.
-
- For example,
-
- (restricted-sexp :match-alternatives (integerp 't 'nil))
-
- allows integers, `t' and `nil' as legitimate values.
-
- The customization buffer shows all legitimate values using their
- read syntax, and the user edits them textually.
-
-`(cons CAR-TYPE CDR-TYPE)'
- The value must be a cons cell, its CAR must fit CAR-TYPE, and its
- CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
- customization type which matches values such as `("foo" . foo)'.
-
- In the customization buffer, the CAR and the CDR are displayed and
- edited separately, each according to the type that you specify for
- it.
-
-`(list ELEMENT-TYPES...)'
- The value must be a list with exactly as many elements as the
- ELEMENT-TYPES you have specified; and each element must fit the
- corresponding ELEMENT-TYPE.
-
- For example, `(list integer string function)' describes a list of
- three elements; the first element must be an integer, the second a
- string, and the third a function.
-
- In the customization buffer, the each element is displayed and
- edited separately, according to the type specified for it.
-
-`(vector ELEMENT-TYPES...)'
- Like `list' except that the value must be a vector instead of a
- list. The elements work the same as in `list'.
-
-`(choice ALTERNATIVE-TYPES...)'
- The value must fit at least one of ALTERNATIVE-TYPES. For
- example, `(choice integer string)' allows either an integer or a
- string.
-
- In the customization buffer, the user selects one of the
- alternatives using a menu, and can then edit the value in the
- usual way for that alternative.
-
- Normally the strings in this menu are determined automatically
- from the choices; however, you can specify different strings for
- the menu by including the `:tag' keyword in the alternatives. For
- example, if an integer stands for a number of spaces, while a
- string is text to use verbatim, you might write the customization
- type this way,
-
- (choice (integer :tag "Number of spaces")
- (string :tag "Literal text"))
-
- so that the menu offers `Number of spaces' and `Literal Text'.
-
- In any alternative for which `nil' is not a valid value, other than
- a `const', you should specify a valid default for that alternative
- using the `:value' keyword. *Note Type Keywords::.
-
-`(const VALUE)'
- The value must be VALUE--nothing else is allowed.
-
- The main use of `const' is inside of `choice'. For example,
- `(choice integer (const nil))' allows either an integer or `nil'.
-
- `:tag' is often used with `const', inside of `choice'. For
- example,
-
- (choice (const :tag "Yes" t)
- (const :tag "No" nil)
- (const :tag "Ask" foo))
-
-`(function-item FUNCTION)'
- Like `const', but used for values which are functions. This
- displays the documentation string as well as the function name.
- The documentation string is either the one you specify with
- `:doc', or FUNCTION's own documentation string.
-
-`(variable-item VARIABLE)'
- Like `const', but used for values which are variable names. This
- displays the documentation string as well as the variable name.
- The documentation string is either the one you specify with
- `:doc', or VARIABLE's own documentation string.
-
-`(set ELEMENTS...)'
- The value must be a list and each element of the list must be one
- of the ELEMENTS specified. This appears in the customization
- buffer as a checklist.
-
-`(repeat ELEMENT-TYPE)'
- The value must be a list and each element of the list must fit the
- type ELEMENT-TYPE. This appears in the customization buffer as a
- list of elements, with `[INS]' and `[DEL]' buttons for adding more
- elements or removing elements.
-
-\1f
-File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
-
-Splicing into Lists
--------------------
-
- The `:inline' feature lets you splice a variable number of elements
-into the middle of a list or vector. You use it in a `set', `choice'
-or `repeat' type which appears among the element-types of a `list' or
-`vector'.
-
- Normally, each of the element-types in a `list' or `vector'
-describes one and only one element of the list or vector. Thus, if an
-element-type is a `repeat', that specifies a list of unspecified length
-which appears as one element.
-
- But when the element-type uses `:inline', the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using `,@' in the backquote
-construct.
-
- For example, to specify a list whose first element must be `t' and
-whose remaining arguments should be zero or more of `foo' and `bar',
-use this customization type:
-
- (list (const t) (set :inline t foo bar))
-
-This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
-bar)'.
-
- When the element-type is a `choice', you use `:inline' not in the
-`choice' itself, but in (some of) the alternatives of the `choice'.
-For example, to match a list which must start with a file name,
-followed either by the symbol `t' or two strings, use this
-customization type:
-
- (list file
- (choice (const t)
- (list :inline t string string)))
-
-If the user chooses the first alternative in the choice, then the
-overall list has two elements and the second element is `t'. If the
-user chooses the second alternative, then the overall list has three
-elements and the second and third must be strings.
-
-\1f
-File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
-
-Type Keywords
--------------
-
- You can specify keyword-argument pairs in a customization type after
-the type name symbol. Here are the keywords you can use, and their
-meanings:
-
-`:value DEFAULT'
- This is used for a type that appears as an alternative inside of
- `choice'; it specifies the default value to use, at first, if and
- when the user selects this alternative with the menu in the
- customization buffer.
-
- Of course, if the actual value of the option fits this
- alternative, it will appear showing the actual value, not DEFAULT.
-
- If `nil' is not a valid value for the alternative, then it is
- essential to specify a valid default with `:value'.
-
-`:format FORMAT-STRING'
- This string will be inserted in the buffer to represent the value
- corresponding to the type. The following `%' escapes are available
- for use in FORMAT-STRING:
-
- `%[BUTTON%]'
- Display the text BUTTON marked as a button. The `:action'
- attribute specifies what the button will do if the user
- invokes it; its value is a function which takes two
- arguments--the widget which the button appears in, and the
- event.
-
- There is no way to specify two different buttons with
- different actions.
-
- `%{SAMPLE%}'
- Show SAMPLE in a special face specified by `:sample-face'.
-
- `%v'
- Substitute the item's value. How the value is represented
- depends on the kind of item, and (for variables) on the
- customization type.
-
- `%d'
- Substitute the item's documentation string.
-
- `%h'
- Like `%d', but if the documentation string is more than one
- line, add an active field to control whether to show all of
- it or just the first line.
-
- `%t'
- Substitute the tag here. You specify the tag with the `:tag'
- keyword.
-
- `%%'
- Display a literal `%'.
-
-`:action ACTION'
- Perform ACTION if the user clicks on a button.
-
-`:button-face FACE'
- Use the face FACE (a face name or a list of face names) for button
- text displayed with `%[...%]'.
-
-`:button-prefix PREFIX'
-`:button-suffix SUFFIX'
- These specify the text to display before and after a button. Each
- can be:
-
- `nil'
- No text is inserted.
-
- a string
- The string is inserted literally.
-
- a symbol
- The symbol's value is used.
-
-`:tag TAG'
- Use TAG (a string) as the tag for the value (or part of the value)
- that corresponds to this type.
-
-`:doc DOC'
- Use DOC as the documentation string for this value (or part of the
- value) that corresponds to this type. In order for this to work,
- you must specify a value for `:format', and use `%d' or `%h' in
- that value.
-
- The usual reason to specify a documentation string for a type is to
- provide more information about the meanings of alternatives inside
- a `:choice' type or the parts of some other composite type.
-
-`:help-echo MOTION-DOC'
- When you move to this item with `widget-forward' or
- `widget-backward', it will display the string MOTION-DOC in the
- echo area.
-
-`:match FUNCTION'
- Specify how to decide whether a value matches the type. The
- corresponding value, FUNCTION, should be a function that accepts
- two arguments, a widget and a value; it should return non-`nil' if
- the value is acceptable.
-
-\1f
-File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
-
-Loading
-*******
-
- Loading a file of Lisp code means bringing its contents into the Lisp
-environment in the form of Lisp objects. XEmacs finds and opens the
-file, reads the text, evaluates each form, and then closes the file.
-
- The load functions evaluate all the expressions in a file just as
-the `eval-current-buffer' function evaluates all the expressions in a
-buffer. The difference is that the load functions read and evaluate
-the text in the file as found on disk, not the text in an Emacs buffer.
-
- The loaded file must contain Lisp expressions, either as source code
-or as byte-compiled code. Each form in the file is called a "top-level
-form". There is no special format for the forms in a loadable file;
-any form in a file may equally well be typed directly into a buffer and
-evaluated there. (Indeed, most code is tested this way.) Most often,
-the forms are function definitions and variable definitions.
-
- A file containing Lisp code is often called a "library". Thus, the
-"Rmail library" is a file containing code for Rmail mode. Similarly, a
-"Lisp library directory" is a directory of files containing Lisp code.
-
-* Menu:
-
-* How Programs Do Loading:: The `load' function and others.
-* Autoload:: Setting up a function to autoload.
-* Repeated Loading:: Precautions about loading a file twice.
-* Named Features:: Loading a library if it isn't already loaded.
-* Unloading:: How to "unload" a library that was loaded.
-* Hooks for Loading:: Providing code to be run when
- particular libraries are loaded.
-
-\1f
-File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
-
-How Programs Do Loading
-=======================
-
- XEmacs Lisp has several interfaces for loading. For example,
-`autoload' creates a placeholder object for a function in a file;
-trying to call the autoloading function loads the file to get the
-function's real definition (*note Autoload::.). `require' loads a file
-if it isn't already loaded (*note Named Features::.). Ultimately, all
-these facilities call the `load' function to do the work.
-
- - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
- This function finds and opens a file of Lisp code, evaluates all
- the forms in it, and closes the file.
-
- To find the file, `load' first looks for a file named
- `FILENAME.elc', that is, for a file whose name is FILENAME with
- `.elc' appended. If such a file exists, it is loaded. If there
- is no file by that name, then `load' looks for a file named
- `FILENAME.el'. If that file exists, it is loaded. Finally, if
- neither of those names is found, `load' looks for a file named
- FILENAME with nothing appended, and loads it if it exists. (The
- `load' function is not clever about looking at FILENAME. In the
- perverse case of a file named `foo.el.el', evaluation of `(load
- "foo.el")' will indeed find it.)
-
- If the optional argument NOSUFFIX is non-`nil', then the suffixes
- `.elc' and `.el' are not tried. In this case, you must specify
- the precise file name you want.
-
- If FILENAME is a relative file name, such as `foo' or
- `baz/foo.bar', `load' searches for the file using the variable
- `load-path'. It appends FILENAME to each of the directories
- listed in `load-path', and loads the first file it finds whose name
- matches. The current default directory is tried only if it is
- specified in `load-path', where `nil' stands for the default
- directory. `load' tries all three possible suffixes in the first
- directory in `load-path', then all three suffixes in the second
- directory, and so on.
-
- If you get a warning that `foo.elc' is older than `foo.el', it
- means you should consider recompiling `foo.el'. *Note Byte
- Compilation::.
-
- Messages like `Loading foo...' and `Loading foo...done' appear in
- the echo area during loading unless NOMESSAGE is non-`nil'.
-
- Any unhandled errors while loading a file terminate loading. If
- the load was done for the sake of `autoload', any function
- definitions made during the loading are undone.
-
- If `load' can't find the file to load, then normally it signals the
- error `file-error' (with `Cannot open load file FILENAME'). But
- if MISSING-OK is non-`nil', then `load' just returns `nil'.
-
- You can use the variable `load-read-function' to specify a function
- for `load' to use instead of `read' for reading expressions. See
- below.
-
- `load' returns `t' if the file loads successfully.
-
- - User Option: load-path
- The value of this variable is a list of directories to search when
- loading files with `load'. Each element is a string (which must be
- a directory name) or `nil' (which stands for the current working
- directory). The value of `load-path' is initialized from the
- environment variable `EMACSLOADPATH', if that exists; otherwise its
- default value is specified in `emacs/src/paths.h' when XEmacs is
- built.
-
- The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
- (or `;', according to the operating system) separates directory
- names, and `.' is used for the current default directory. Here is
- an example of how to set your `EMACSLOADPATH' variable from a
- `csh' `.login' file:
-
- setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
-
- Here is how to set it using `sh':
-
- export EMACSLOADPATH
- EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
-
- Here is an example of code you can place in a `.emacs' file to add
- several directories to the front of your default `load-path':
-
- (setq load-path
- (append (list nil "/user/bil/emacs"
- "/usr/local/lisplib"
- "~/emacs")
- load-path))
-
- In this example, the path searches the current working directory
- first, followed then by the `/user/bil/emacs' directory, the
- `/usr/local/lisplib' directory, and the `~/emacs' directory, which
- are then followed by the standard directories for Lisp code.
-
- The command line options `-l' or `-load' specify a Lisp library to
- load as part of Emacs startup. Since this file might be in the
- current directory, Emacs 18 temporarily adds the current directory
- to the front of `load-path' so the file can be found there. Newer
- Emacs versions also find such files in the current directory, but
- without altering `load-path'.
-
- Dumping Emacs uses a special value of `load-path'. If the value of
- `load-path' at the end of dumping is unchanged (that is, still the
- same special value), the dumped Emacs switches to the ordinary
- `load-path' value when it starts up, as described above. But if
- `load-path' has any other value at the end of dumping, that value
- is used for execution of the dumped Emacs also.
-
- Therefore, if you want to change `load-path' temporarily for
- loading a few libraries in `site-init.el' or `site-load.el', you
- should bind `load-path' locally with `let' around the calls to
- `load'.
-
- - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
- This function searches for a file in the same way that `load' does,
- and returns the file found (if any). (In fact, `load' uses this
- function to search through `load-path'.) It searches for FILENAME
- through PATH-LIST, expanded by one of the optional SUFFIXES
- (string of suffixes separated by `:'s), checking for access MODE
- (0|1|2|4 = exists|executable|writeable|readable), default readable.
-
- `locate-file' keeps hash tables of the directories it searches
- through, in order to speed things up. It tries valiantly to not
- get confused in the face of a changing and unpredictable
- environment, but can occasionally get tripped up. In this case,
- you will have to call `locate-file-clear-hashing' to get it back
- on track. See that function for details.
-
- - Function: locate-file-clear-hashing PATH
- This function clears the hash records for the specified list of
- directories. `locate-file' uses a hashing scheme to speed lookup,
- and will correctly track the following environmental changes:
-
- * changes of any sort to the list of directories to be searched.
-
- * addition and deletion of non-shadowing files (see below) from
- the directories in the list.
-
- * byte-compilation of a .el file into a .elc file.
-
- `locate-file' will primarily get confused if you add a file that
- shadows (i.e. has the same name as) another file further down in
- the directory list. In this case, you must call
- `locate-file-clear-hashing'.
-
- - Variable: load-in-progress
- This variable is non-`nil' if Emacs is in the process of loading a
- file, and it is `nil' otherwise.
-
- - Variable: load-read-function
- This variable specifies an alternate expression-reading function
- for `load' and `eval-region' to use instead of `read'. The
- function should accept one argument, just as `read' does.
-
- Normally, the variable's value is `nil', which means those
- functions should use `read'.
-
- - User Option: load-warn-when-source-newer
- This variable specifies whether `load' should check whether the
- source is newer than the binary. If this variable is true, then
- when a `.elc' file is being loaded and the corresponding `.el' is
- newer, a warning message will be printed. The default is `nil',
- but it is bound to `t' during the initial loadup.
-
- - User Option: load-warn-when-source-only
- This variable specifies whether `load' should warn when loading a
- `.el' file instead of an `.elc'. If this variable is true, then
- when `load' is called with a filename without an extension, and
- the `.elc' version doesn't exist but the `.el' version does, then
- a message will be printed. If an explicit extension is passed to
- `load', no warning will be printed. The default is `nil', but it
- is bound to `t' during the initial loadup.
-
- - User Option: load-ignore-elc-files
- This variable specifies whether `load' should ignore `.elc' files
- when a suffix is not given. This is normally used only to
- bootstrap the `.elc' files when building XEmacs, when you use the
- command `make all-elc'. (This forces the `.el' versions to be
- loaded in the process of compiling those same files, so that
- existing out-of-date `.elc' files do not make it mess things up.)
-
- To learn how `load' is used to build XEmacs, see *Note Building
-XEmacs::.
-
projects / chise / xemacs-chise.git.1 / blobdiff