This is elisp, produced by makeinfo version 4.0f from ./elisp.texi.
INFO-DIR-SECTION Editors
START-INFO-DIR-ENTRY
* Elisp: (elisp). The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY
This Info file contains edition 2.8 of the GNU Emacs Lisp Reference
Manual, corresponding to Emacs version 21.2.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Copying", with the Front-Cover texts being "A
GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of
the license is included in the section entitled "GNU Free Documentation
License".
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: elisp, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions
Defining Functions
==================
We usually give a name to a function when it is first created. This
is called "defining a function", and it is done with the `defun'
special form.
- Special Form: defun name argument-list body-forms
`defun' is the usual way to define new Lisp functions. It defines
the symbol NAME as a function that looks like this:
(lambda ARGUMENT-LIST . BODY-FORMS)
`defun' stores this lambda expression in the function cell of
NAME. It returns the value NAME, but usually we ignore this value.
As described previously (*note Lambda Expressions::),
ARGUMENT-LIST is a list of argument names and may include the
keywords `&optional' and `&rest'. Also, the first two of the
BODY-FORMS may be a documentation string and an interactive
declaration.
There is no conflict if the same symbol NAME is also used as a
variable, since the symbol's value cell is independent of the
function cell. *Note Symbol Components::.
Here are some examples:
(defun foo () 5)
=> foo
(foo)
=> 5
(defun bar (a &optional b &rest c)
(list a b c))
=> bar
(bar 1 2 3 4 5)
=> (1 2 (3 4 5))
(bar 1)
=> (1 nil nil)
(bar)
error--> Wrong number of arguments.
(defun capitalize-backwards ()
"Upcase the last letter of a word."
(interactive)
(backward-word 1)
(forward-word 1)
(backward-char 1)
(capitalize-word 1))
=> capitalize-backwards
Be careful not to redefine existing functions unintentionally.
`defun' redefines even primitive functions such as `car' without
any hesitation or notification. Redefining a function already
defined is often done deliberately, and there is no way to
distinguish deliberate redefinition from unintentional
redefinition.
- Function: defalias name definition
This special form defines the symbol NAME as a function, with
definition DEFINITION (which can be any valid Lisp function).
The proper place to use `defalias' is where a specific function
name is being defined--especially where that name appears
explicitly in the source file being loaded. This is because
`defalias' records which file defined the function, just like
`defun' (*note Unloading::).
By contrast, in programs that manipulate function definitions for
other purposes, it is better to use `fset', which does not keep
such records.
See also `defsubst', which defines a function like `defun' and tells
the Lisp compiler to open-code it. *Note Inline Functions::.
File: elisp, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions
Calling Functions
=================
Defining functions is only half the battle. Functions don't do
anything until you "call" them, i.e., tell them to run. Calling a
function is also known as "invocation".
The most common way of invoking a function is by evaluating a list.
For example, evaluating the list `(concat "a" "b")' calls the function
`concat' with arguments `"a"' and `"b"'. *Note Evaluation::, for a
description of evaluation.
When you write a list as an expression in your program, the function
name it calls is written in your program. This means that you choose
which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
function `funcall'. When you also need to determine at run time how
many arguments to pass, use `apply'.
- Function: funcall function &rest arguments
`funcall' calls FUNCTION with ARGUMENTS, and returns whatever
FUNCTION returns.
Since `funcall' is a function, all of its arguments, including
FUNCTION, are evaluated before `funcall' is called. This means
that you can use any expression to obtain the function to be
called. It also means that `funcall' does not see the expressions
you write for the ARGUMENTS, only their values. These values are
_not_ evaluated a second time in the act of calling FUNCTION;
`funcall' enters the normal procedure for calling a function at the
place where the arguments have already been evaluated.
The argument FUNCTION must be either a Lisp function or a
primitive function. Special forms and macros are not allowed,
because they make sense only when given the "unevaluated" argument
expressions. `funcall' cannot provide these because, as we saw
above, it never knows them in the first place.
(setq f 'list)
=> list
(funcall f 'x 'y 'z)
=> (x y z)
(funcall f 'x 'y '(z))
=> (x y (z))
(funcall 'and t nil)
error--> Invalid function: #<subr and>
Compare these examples with the examples of `apply'.
- Function: apply function &rest arguments
`apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
with one difference: the last of ARGUMENTS is a list of objects,
which are passed to FUNCTION as separate arguments, rather than a
single list. We say that `apply' "spreads" this list so that each
individual element becomes an argument.
`apply' returns the result of calling FUNCTION. As with
`funcall', FUNCTION must either be a Lisp function or a primitive
function; special forms and macros do not make sense in `apply'.
(setq f 'list)
=> list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
=> 10
(apply '+ '(1 2 3 4))
=> 10
(apply 'append '((a b c) nil (x y z) nil))
=> (a b c x y z)
For an interesting example of using `apply', see the description of
`mapcar', in *Note Mapping Functions::.
It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using `funcall' or `apply'. Functions that accept
function arguments are often called "functionals".
Sometimes, when you call a functional, it is useful to supply a no-op
function as the argument. Here are two different kinds of no-op
function:
- Function: identity arg
This function returns ARG and has no side effects.
- Function: ignore &rest args
This function ignores any arguments and returns `nil'.
File: elisp, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions
Mapping Functions
=================
A "mapping function" applies a given function to each element of a
list or other collection. Emacs Lisp has several such functions;
`mapcar' and `mapconcat', which scan a list, are described here. *Note
Creating Symbols::, for the function `mapatoms' which maps over the
symbols in an obarray. *Note Hash Access::, for the function `maphash'
which maps over key/value associations in a hash table.
These mapping functions do not allow char-tables because a char-table
is a sparse array whose nominal range of indices is very large. To map
over a char-table in a way that deals properly with its sparse nature,
use the function `map-char-table' (*note Char-Tables::).
- Function: mapcar function sequence
`mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
returns a list of the results.
The argument SEQUENCE can be any kind of sequence except a
char-table; that is, a list, a vector, a bool-vector, or a string.
The result is always a list. The length of the result is the
same as the length of SEQUENCE.
For example:
(mapcar 'car '((a b) (c d) (e f)))
=> (a c e)
(mapcar '1+ [1 2 3])
=> (2 3 4)
(mapcar 'char-to-string "abc")
=> ("a" "b" "c")
;; Call each function in `my-hooks'.
(mapcar 'funcall my-hooks)
(defun mapcar* (function &rest args)
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
;; If no list is exhausted,
(if (not (memq 'nil args))
;; apply function to CARs.
(cons (apply function (mapcar 'car args))
(apply 'mapcar* function
;; Recurse for rest of elements.
(mapcar 'cdr args)))))
(mapcar* 'cons '(a b c) '(1 2 3 4))
=> ((a . 1) (b . 2) (c . 3))
- Function: mapc function sequence
`mapc' is like `mapcar' except that FUNCTION is used for
side-effects only--the values it returns are ignored, not collected
into a list. `mapc' always returns SEQUENCE.
- Function: mapconcat function sequence separator
`mapconcat' applies FUNCTION to each element of SEQUENCE: the
results, which must be strings, are concatenated. Between each
pair of result strings, `mapconcat' inserts the string SEPARATOR.
Usually SEPARATOR contains a space or comma or other suitable
punctuation.
The argument FUNCTION must be a function that can take one
argument and return a string. The argument SEQUENCE can be any
kind of sequence except a char-table; that is, a list, a vector, a
bool-vector, or a string.
(mapconcat 'symbol-name
'(The cat in the hat)
" ")
=> "The cat in the hat"
(mapconcat (function (lambda (x) (format "%c" (1+ x))))
"HAL-8000"
"")
=> "IBM.9111"
File: elisp, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions
Anonymous Functions
===================
In Lisp, a function is a list that starts with `lambda', a byte-code
function compiled from such a list, or alternatively a primitive
subr-object; names are "extra". Although usually functions are defined
with `defun' and given names at the same time, it is occasionally more
concise to use an explicit lambda expression--an anonymous function.
Such a list is valid wherever a function name is.
Any method of creating such a list makes a valid function. Even
this:
(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
=> (lambda (x) (+ 12 x))
This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
it the value (_not_ the function definition!) of `silly'.
Here is how we might call this function:
(funcall silly 1)
=> 13
(It does _not_ work to write `(silly 1)', because this function is not
the _function definition_ of `silly'. We have not given `silly' any
function definition, just a value as a variable.)
Most of the time, anonymous functions are constants that appear in
your program. For example, you might want to pass one as an argument to
the function `mapcar', which applies any given function to each element
of a list.
Here we define a function `change-property' which uses a function as
its third argument:
(defun change-property (symbol prop function)
(let ((value (get symbol prop)))
(put symbol prop (funcall function value))))
Here we define a function that uses `change-property', passing it a
function to double a number:
(defun double-property (symbol prop)
(change-property symbol prop '(lambda (x) (* 2 x))))
In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function, like this:
(defun double-property (symbol prop)
(change-property symbol prop
(function (lambda (x) (* 2 x)))))
Using `function' instead of `quote' makes a difference if you
compile the function `double-property'. For example, if you compile
the second definition of `double-property', the anonymous function is
compiled as well. By contrast, if you compile the first definition
which uses ordinary `quote', the argument passed to `change-property'
is the precise list shown:
(lambda (x) (* x 2))
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what `change-property' will do
with the list. Perhaps it will check whether the CAR of the third
element is the symbol `*'! Using `function' tells the compiler it is
safe to go ahead and compile the constant function.
Nowadays it is possible to omit `function' entirely, like this:
(defun double-property (symbol prop)
(change-property symbol prop (lambda (x) (* 2 x))))
This is because `lambda' itself implies `function'.
We sometimes write `function' instead of `quote' when quoting the
name of a function, but this usage is just a sort of comment:
(function SYMBOL) == (quote SYMBOL) == 'SYMBOL
The read syntax `#'' is a short-hand for using `function'. For
example,
#'(lambda (x) (* x x))
is equivalent to
(function (lambda (x) (* x x)))
- Special Form: function function-object
This special form returns FUNCTION-OBJECT without evaluating it.
In this, it is equivalent to `quote'. However, it serves as a
note to the Emacs Lisp compiler that FUNCTION-OBJECT is intended
to be used only as a function, and therefore can safely be
compiled. Contrast this with `quote', in *Note Quoting::.
See `documentation' in *Note Accessing Documentation::, for a
realistic example using `function' and an anonymous function.
File: elisp, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions
Accessing Function Cell Contents
================================
The "function definition" of a symbol is the object stored in the
function cell of the symbol. The functions described here access, test,
and set the function cell of symbols.
See also the function `indirect-function' in *Note Function
Indirection::.
- Function: symbol-function symbol
This returns the object in the function cell of SYMBOL. If the
symbol's function cell is void, a `void-function' error is
signaled.
This function does not check that the returned object is a
legitimate function.
(defun bar (n) (+ n 2))
=> bar
(symbol-function 'bar)
=> (lambda (n) (+ n 2))
(fset 'baz 'bar)
=> bar
(symbol-function 'baz)
=> bar
If you have never given a symbol any function definition, we say that
that symbol's function cell is "void". In other words, the function
cell does not have any Lisp object in it. If you try to call such a
symbol as a function, it signals a `void-function' error.
Note that void is not the same as `nil' or the symbol `void'. The
symbols `nil' and `void' are Lisp objects, and can be stored into a
function cell just as any other object can be (and they can be valid
functions if you define them in turn with `defun'). A void function
cell contains no object whatsoever.
You can test the voidness of a symbol's function definition with
`fboundp'. After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.
- Function: fboundp symbol
This function returns `t' if the symbol has an object in its
function cell, `nil' otherwise. It does not check that the object
is a legitimate function.
- Function: fmakunbound symbol
This function makes SYMBOL's function cell void, so that a
subsequent attempt to access this cell will cause a `void-function'
error. (See also `makunbound', in *Note Void Variables::.)
(defun foo (x) x)
=> foo
(foo 1)
=>1
(fmakunbound 'foo)
=> foo
(foo 1)
error--> Symbol's function definition is void: foo
- Function: fset symbol definition
This function stores DEFINITION in the function cell of SYMBOL.
The result is DEFINITION. Normally DEFINITION should be a
function or the name of a function, but this is not checked. The
argument SYMBOL is an ordinary evaluated argument.
There are three normal uses of this function:
* Copying one symbol's function definition to another--in other
words, making an alternate name for a function. (If you
think of this as the definition of the new name, you should
use `defalias' instead of `fset'; see *Note Defining
Functions::.)
* Giving a symbol a function definition that is not a list and
therefore cannot be made with `defun'. For example, you can
use `fset' to give a symbol `s1' a function definition which
is another symbol `s2'; then `s1' serves as an alias for
whatever definition `s2' presently has. (Once again use
`defalias' instead of `fset' if you think of this as the
definition of `s1'.)
* In constructs for defining or altering functions. If `defun'
were not a primitive, it could be written in Lisp (as a
macro) using `fset'.
Here are examples of these uses:
;; Save `foo''s definition in `old-foo'.
(fset 'old-foo (symbol-function 'foo))
;; Make the symbol `car' the function definition of `xfirst'.
;; (Most likely, `defalias' would be better than `fset' here.)
(fset 'xfirst 'car)
=> car
(xfirst '(1 2 3))
=> 1
(symbol-function 'xfirst)
=> car
(symbol-function (symbol-function 'xfirst))
=> #<subr car>
;; Define a named keyboard macro.
(fset 'kill-two-lines "\^u2\^k")
=> "\^u2\^k"
;; Here is a function that alters other functions.
(defun copy-function-definition (new old)
"Define NEW with the same function definition as OLD."
(fset new (symbol-function old)))
When writing a function that extends a previously defined function,
the following idiom is sometimes used:
(fset 'old-foo (symbol-function 'foo))
(defun foo ()
"Just like old-foo, except more so."
(old-foo)
(more-so))
This does not work properly if `foo' has been defined to autoload. In
such a case, when `foo' calls `old-foo', Lisp attempts to define
`old-foo' by loading a file. Since this presumably defines `foo'
rather than `old-foo', it does not produce the proper results. The
only way to avoid this problem is to make sure the file is loaded
before moving aside the old definition of `foo'.
But it is unmodular and unclean, in any case, for a Lisp file to
redefine a function defined elsewhere. It is cleaner to use the advice
facility (*note Advising Functions::).
File: elisp, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions
Inline Functions
================
You can define an "inline function" by using `defsubst' instead of
`defun'. An inline function works just like an ordinary function
except for one thing: when you compile a call to the function, the
function's definition is open-coded into the caller.
Making a function inline makes explicit calls run faster. But it
also has disadvantages. For one thing, it reduces flexibility; if you
change the definition of the function, calls already inlined still use
the old definition until you recompile them. Since the flexibility of
redefining functions is an important feature of Emacs, you should not
make a function inline unless its speed is really crucial.
Another disadvantage is that making a large function inline can
increase the size of compiled code both in files and in memory. Since
the speed advantage of inline functions is greatest for small
functions, you generally should not make large functions inline.
It's possible to define a macro to expand into the same code that an
inline function would execute. (*Note Macros::.) But the macro would
be limited to direct use in expressions--a macro cannot be called with
`apply', `mapcar' and so on. Also, it takes some work to convert an
ordinary function into a macro. To convert it into an inline function
is very easy; simply replace `defun' with `defsubst'. Since each
argument of an inline function is evaluated exactly once, you needn't
worry about how many times the body uses the arguments, as you do for
macros. (*Note Argument Evaluation::.)
Inline functions can be used and open-coded later on in the same
file, following the definition, just like macros.
File: elisp, Node: Related Topics, Prev: Inline Functions, Up: Functions
Other Topics Related to Functions
=================================
Here is a table of several functions that do things related to
function calling and function definitions. They are documented
elsewhere, but we provide cross references here.
`apply'
See *Note Calling Functions::.
`autoload'
See *Note Autoload::.
`call-interactively'
See *Note Interactive Call::.
`commandp'
See *Note Interactive Call::.
`documentation'
See *Note Accessing Documentation::.
`eval'
See *Note Eval::.
`funcall'
See *Note Calling Functions::.
`function'
See *Note Anonymous Functions::.
`ignore'
See *Note Calling Functions::.
`indirect-function'
See *Note Function Indirection::.
`interactive'
See *Note Using Interactive::.
`interactive-p'
See *Note Interactive Call::.
`mapatoms'
See *Note Creating Symbols::.
`mapcar'
See *Note Mapping Functions::.
`map-char-table'
See *Note Char-Tables::.
`mapconcat'
See *Note Mapping Functions::.
`undefined'
See *Note Key Lookup::.
File: elisp, Node: Macros, Next: Customization, Prev: Functions, Up: Top
Macros
******
"Macros" enable you to define new control constructs and other
language features. A macro is defined much like a function, but instead
of telling how to compute a value, it tells how to compute another Lisp
expression which will in turn compute the value. We call this
expression the "expansion" of the macro.
Macros can do this because they operate on the unevaluated
expressions for the arguments, not on the argument values as functions
do. They can therefore construct an expansion containing these
argument expressions or parts of them.
If you are using a macro to do something an ordinary function could
do, just for the sake of speed, consider using an inline function
instead. *Note Inline Functions::.
* Menu:
* Simple Macro:: A basic example.
* Expansion:: How, when and why macros are expanded.
* Compiling Macros:: How macros are expanded by the compiler.
* Defining Macros:: How to write a macro definition.
* Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
File: elisp, Node: Simple Macro, Next: Expansion, Up: Macros
A Simple Example of a Macro
===========================
Suppose we would like to define a Lisp construct to increment a
variable value, much like the `++' operator in C. We would like to
write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a
macro definition that does the job:
(defmacro inc (var)
(list 'setq var (list '1+ var)))
When this is called with `(inc x)', the argument VAR is the symbol
`x'--_not_ the _value_ of `x', as it would be in a function. The body
of the macro uses this to construct the expansion, which is `(setq x
(1+ x))'. Once the macro definition returns this expansion, Lisp
proceeds to evaluate it, thus incrementing `x'.
File: elisp, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros
Expansion of a Macro Call
=========================
A macro call looks just like a function call in that it is a list
which starts with the name of the macro. The rest of the elements of
the list are the arguments of the macro.
Evaluation of the macro call begins like evaluation of a function
call except for one crucial difference: the macro arguments are the
actual expressions appearing in the macro call. They are not evaluated
before they are given to the macro definition. By contrast, the
arguments of a function are results of evaluating the elements of the
function call list.
Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked. The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a `&rest' argument. And the macro body executes and returns
its value just as a function body does.
The second crucial difference between macros and functions is that
the value returned by the macro body is not the value of the macro call.
Instead, it is an alternate expression for computing that value, also
known as the "expansion" of the macro. The Lisp interpreter proceeds
to evaluate the expansion as soon as it comes back from the macro.
Since the expansion is evaluated in the normal manner, it may contain
calls to other macros. It may even be a call to the same macro, though
this is unusual.
You can see the expansion of a given macro call by calling
`macroexpand'.
- Function: macroexpand form &optional environment
This function expands FORM, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something
which is not a macro call results. That is the value returned by
`macroexpand'. If FORM is not a macro call to begin with, it is
returned as given.
Note that `macroexpand' does not look at the subexpressions of
FORM (although some macro definitions may do so). Even if they
are macro calls themselves, `macroexpand' does not expand them.
The function `macroexpand' does not expand calls to inline
functions. Normally there is no need for that, since a call to an
inline function is no harder to understand than a call to an
ordinary function.
If ENVIRONMENT is provided, it specifies an alist of macro
definitions that shadow the currently defined macros. Byte
compilation uses this feature.
(defmacro inc (var)
(list 'setq var (list '1+ var)))
=> inc
(macroexpand '(inc r))
=> (setq r (1+ r))
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
=> inc2
(macroexpand '(inc2 r s))
=> (progn (inc r) (inc s)) ; `inc' not expanded here.
File: elisp, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
Macros and Byte Compilation
===========================
You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion. Why not have the macro body
produce the desired results directly? The reason has to do with
compilation.
When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and
receives an expansion. But instead of evaluating this expansion, it
compiles the expansion as if it had appeared directly in the program.
As a result, the compiled code produces the value and side effects
intended for the macro, but executes at full compiled speed. This would
not work if the macro body computed the value and side effects
itself--they would be computed at compile time, which is not useful.
In order for compilation of macro calls to work, the macros must
already be defined in Lisp when the calls to them are compiled. The
compiler has a special feature to help you do this: if a file being
compiled contains a `defmacro' form, the macro is defined temporarily
for the rest of the compilation of that file. To make this feature
work, you must put the `defmacro' in the same file where it is used,
and before its first use.
Byte-compiling a file executes any `require' calls at top-level in
the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions
are available during compilation is to require the files that define
them (*note Named Features::). To avoid loading the macro definition
files when someone _runs_ the compiled program, write
`eval-when-compile' around the `require' calls (*note Eval During
Compile::).
File: elisp, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
Defining Macros
===============
A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
function; expansion of the macro works by applying the function (with
`apply') to the list of unevaluated argument-expressions from the macro
call.
It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to functionals such as `mapcar'. In practice, all
Lisp macros have names, and they are usually defined with the special
form `defmacro'.
- Special Form: defmacro name argument-list body-forms...
`defmacro' defines the symbol NAME as a macro that looks like this:
(macro lambda ARGUMENT-LIST . BODY-FORMS)
(Note that the CDR of this list is a function--a lambda
expression.) This macro object is stored in the function cell of
NAME. The value returned by evaluating the `defmacro' form is
NAME, but usually we ignore this value.
The shape and meaning of ARGUMENT-LIST is the same as in a
function, and the keywords `&rest' and `&optional' may be used
(*note Argument List::). Macros may have a documentation string,
but any `interactive' declaration is ignored since macros cannot be
called interactively.
File: elisp, 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 ``'
syntax (usually 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)
Substitution with `,' is allowed at deeper levels of the list
structure also. For example:
(defmacro t-becomes-nil (variable)
`(if (eq ,variable t)
(setq ,variable nil)))
(t-becomes-nil foo)
== (if (eq foo t) (setq foo nil))
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 old Emacs versions, before 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, for compatibility with old Emacs
versions, but we recommend not using it in new programs.
File: elisp, 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:
* Wrong Time:: Do the work in the expansion, not in the macro.
* 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.
File: elisp, Node: Wrong Time, Next: Argument Evaluation, Up: Problems with Macros
Wrong Time
----------
The most common problem in writing macros is doing too some of the
real work prematurely--while expanding the macro, rather than in the
expansion itself. For instance, one real package had this nmacro
definition:
(defmacro my-set-buffer-multibyte (arg)
(if (fboundp 'set-buffer-multibyte)
(set-buffer-multibyte arg)))
With this erroneous macro definition, the program worked fine when
interpreted but failed when compiled. This macro definition called
`set-buffer-multibyte' during compilation, which was wrong, and then
did nothing when the compiled package was run. The definition that the
programmer really wanted was this:
(defmacro my-set-buffer-multibyte (arg)
(if (fboundp 'set-buffer-multibyte)
`(set-buffer-multibyte ,arg)))
This macro expands, if appropriate, into a call to
`set-buffer-multibyte' that will be executed when the compiled program
is actually run.
File: elisp, Node: Argument Evaluation, Next: Surprising Local Vars, Prev: Wrong Time, 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 fix introduces another problem, described in the
following section.
File: elisp, 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.
File: elisp, 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 the macro definition itself evaluates
any of the macro argument expressions, 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 problem with calling `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.
To avoid these problems, *don't evaluate an argument expression
while computing the macro expansion*. Instead, substitute the
expression into the macro expansion, so that its value will be computed
as part of executing the expansion. This is how the other examples in
this chapter work.
File: elisp, 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.
Therefore, you should avoid side effects in computation of the macro
expansion, unless you really know what you are doing.
One special kind of side effect can't be avoided: constructing Lisp
objects. Almost all macro expansions include constructed lists; that is
the whole point of most macros. This is usually safe; there is just one
case where you must be careful: when the object you construct is part
of a quoted constant in the macro expansion.
If the macro is expanded just once, in compilation, then the object
is constructed just once, during compilation. But in interpreted
execution, the macro is expanded each time the macro call runs, and this
means a new object is constructed each time.
In most clean Lisp code, this difference won't matter. It can matter
only if you perform side-effects on the objects constructed by the macro
definition. Thus, to avoid trouble, *avoid side effects on objects
constructed by macro definitions*. Here is an example of how such side
effects can get you into trouble:
(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.
File: elisp, Node: Customization, Next: Loading, Prev: Macros, 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 (*note Defining Faces::).
* Menu:
* Common Keywords::
* Group Definitions::
* Variable Definitions::
* Customization Types::
File: elisp, Node: Common Keywords, Next: Group Definitions, Up: Customization
Common Item Keywords
====================
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 LABEL'
Use LABEL, 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. Please don't overdo this, since the result would
be annoying.
`: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.
`(emacs-commentary-link LIBRARY)'
Link to the commentary section of a library; LIBRARY is a
string which specifies the library name.
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.