@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
-@node Macros, Loading, Functions, Top
+@node Macros, Customization, Functions, Top
@chapter Macros
@cindex macros
@end group
@end example
- When this is called with @code{(inc x)}, the argument @code{var} has
-the value @code{x}---@emph{not} the @emph{value} of @code{x}. The body
-of the macro uses this to construct the expansion, which is @code{(setq
-x (1+ x))}. Once the macro definition returns this expansion, Lisp
-proceeds to evaluate it, thus incrementing @code{x}.
+ When this is called with @code{(inc x)}, the argument @var{var} is the
+symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
+be in a function. The body of the macro uses this to construct the
+expansion, which is @code{(setq x (1+ x))}. Once the macro definition
+returns this expansion, Lisp proceeds to evaluate it, thus incrementing
+@code{x}.
@node Expansion
@section Expansion of a Macro Call
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 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
-@code{defmacro} form, the macro is defined temporarily for the rest of
-the compilation of that file. To use this feature, you must define the
-macro in the same file where it is used and before its first use.
+ 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 @code{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 @code{defmacro} in the same file where it
+is used, and before its first use.
Byte-compiling a file executes any @code{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 file that defines
-them. @xref{Features}.
+are available during compilation is to require the files that define
+them (@pxref{Named Features}). To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
@node Defining Macros
@section Defining Macros
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 mapping functions such as @code{mapcar}. In
-practice, all Lisp macros have names, and they are usually defined with
-the special form @code{defmacro}.
+an anonymous macro to functionals such as @code{mapcar}. In practice,
+all Lisp macros have names, and they are usually defined with the
+special form @code{defmacro}.
@defspec defmacro name argument-list body-forms@dots{}
@code{defmacro} defines the symbol @var{name} as a macro that looks
(macro lambda @var{argument-list} . @var{body-forms})
@end example
+(Note that the @sc{cdr} of this list is a function---a lambda expression.)
This macro object is stored in the function cell of @var{name}. The
value returned by evaluating the @code{defmacro} form is @var{name}, but
usually we ignore this value.
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
+@findex `
Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts. To make this easier, use the macro
-@code{`} (often called @dfn{backquote}).
+constants and nonconstant parts. To make this easier, use the @samp{`}
+syntax (usually called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
@example
@group
-(` (a list of (+ 2 3) elements))
+`(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@group
-(quote (a list of (+ 2 3) elements))
+'(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@end example
@findex , @r{(with Backquote)}
-The special marker @code{,} inside of the argument to backquote
+The special marker @samp{,} inside of the argument to backquote
indicates a value that isn't constant. Backquote evaluates the
-argument of @code{,} and puts the value in the list structure:
+argument of @samp{,} and puts the value in the list structure:
@example
@group
@result{} (a list of 5 elements)
@end group
@group
-(` (a list of (, (+ 2 3)) elements))
+`(a list of ,(+ 2 3) elements)
@result{} (a list of 5 elements)
@end group
+@end example
+
+ Substitution with @samp{,} is allowed at deeper levels of the list
+structure also. For example:
+
+@example
+@group
+(defmacro t-becomes-nil (variable)
+ `(if (eq ,variable t)
+ (setq ,variable nil)))
+@end group
+
+@group
+(t-becomes-nil foo)
+ @equiv{} (if (eq foo t) (setq foo nil))
+@end group
@end example
@findex ,@@ @r{(with Backquote)}
@cindex splicing (with backquote)
-You can also @dfn{splice} an evaluated value into the resulting list,
-using the special marker @code{,@@}. The elements of the spliced list
+ You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @samp{,@@}. 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 @code{`} is often unreadable.
+list. The equivalent code without using @samp{`} is often unreadable.
Here are some examples:
@example
@result{} (1 2 3 4 2 3)
@end group
@group
-(` (1 (,@@ some-list) 4 (,@@ some-list)))
+`(1 ,@@some-list 4 ,@@some-list)
@result{} (1 2 3 4 2 3)
@end group
@result{} (use the words foo bar as elements)
@end group
@group
-(` (use the words (,@@ (cdr list)) as elements))
+`(use the words ,@@(cdr list) as elements)
@result{} (use the words foo bar as elements)
@end group
@end example
-Emacs 18 had a bug that made the previous example fail. The bug
-affected @code{,@@} followed only by constant elements. If you are
-concerned with Emacs 18 compatibility, you can work around the bug like
-this:
-
-@example
-(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)}))
-@end example
-
-@noindent
-@code{(,@@ nil)} avoids the problem by being a nonconstant element that
-does not affect the result.
-
-@defmac ` list
-This macro quotes @var{list} except for any sublists of the form
-@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}. Backquote
-replaces these sublists with the value of @var{subexp} (as a single
-element) or @var{listexp} (by splicing). Backquote copies the structure
-of @var{list} down to the places where variable parts are substituted.
+In old Emacs versions, before version 19.29, @samp{`} used a different
+syntax which required an extra level of parentheses around the entire
+backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution
+required an extra level of parentheses surrounding both the @samp{,} or
+@samp{,@@} and the following expression. The old syntax required
+whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
+following expression.
-@ignore @c these work now!
-There are certain contexts in which @samp{,} would not be recognized and
-should not be used:
-
-@smallexample
-@group
-;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.}
-(` (a . (, 1))) ; @r{Not @code{(a . 1)}}
- @result{} (a \, 1)
-@end group
-
-@group
-;; @r{Use of @samp{,} in a vector.}
-(` [a (, 1) c]) ; @r{Not @code{[a 1 c]}}
- @error{} Wrong type argument
-@end group
-@end smallexample
-@end ignore
-@end defmac
-
-@cindex CL note---@samp{,}, @samp{,@@} as functions
-@quotation
-@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are
-implemented as reader macros, so they do not require parentheses. In
-Emacs Lisp they use function call syntax because reader macros are not
-supported (for simplicity's sake).
-@end quotation
+This syntax is still accepted, for compatibility with old Emacs
+versions, but we recommend not using it in new programs.
@node Problems with Macros
@section Common Problems Using Macros
@end smallexample
@noindent
-(The arguments @code{from}, @code{to}, and @code{do} in this macro are
+The arguments @code{from}, @code{to}, and @code{do} in this macro are
``syntactic sugar''; they are entirely ignored. The idea is that you
will write noise words (such as @code{from}, @code{to}, and @code{do})
-in those positions in the macro call.)
+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))))))
+ `(let ((,var ,init))
+ (while (<= ,var ,final)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
@group
(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))))))
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
- Unfortunately, this introduces another problem.
-@ifinfo
-Proceed to the following node.
-@end ifinfo
+ Unfortunately, this fix introduces another problem,
+described in the following section.
@node Surprising Local Vars
@subsection Local Variables in Macro Expansions
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
@end group
@group
- (` (let (((, var) (, init))
- (max (, final)))
- (while (<= (, var) max)
- (,@@ body)
- (inc (, var))))))
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
@end ifinfo
local variable named @code{max} which the user does not expect. This
causes trouble in examples such as the following:
-@example
+@smallexample
@group
(let ((max 0))
(for x from 0 to 10 do
(if (< max this)
(setq max this)))))
@end group
-@end example
+@end smallexample
@noindent
The references to @code{max} inside the body of the @code{for}, which
(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)))))))
+ `(let ((,var ,init)
+ (,tempvar ,final))
+ (while (<= ,var ,tempvar)
+ ,@@body
+ (inc ,var)))))
@end group
@end smallexample
@node Eval During Expansion
@subsection 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
+ Another problem can happen if the macro definition itself
+evaluates any of the macro argument expressions, such as by calling
@code{eval} (@pxref{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:
+variable, so any references inside the form being evaluated do refer to
+it. Here is an example:
@example
@group
@code{x}, because @code{a} conflicts with the macro argument variable
@code{a}.
- Another reason not to call @code{eval} in a macro definition is that
+ Another problem with calling @code{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 @code{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.
+ To avoid these problems, @strong{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.
@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?
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:
+ 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, @strong{avoid side effects on
+objects constructed by macro definitions}. Here is an example of how
+such side effects can get you into trouble:
@lisp
@group
HCoop / bpt / emacs.git / blobdiff