@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, 2004 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
* 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.
+* Indenting Macros:: Specifying how to indent macro calls.
@end menu
@node Simple Macro
@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
@end smallexample
@end defun
+
+@defun macroexpand-all form &optional environment
+@cindex macro expansion in entire form
+@code{macroexpand-all} expands macros like @code{macroexpand}, but
+will look for and expand all macros in @var{form}, not just at the
+top-level. If no macros are expanded, the return value is @code{eq}
+to @var{form}.
+
+Repeating the example used for @code{macroexpand} above with
+@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
+expand the embedded calls to @code{inc}:
+
+@smallexample
+(macroexpand-all '(inc2 r s))
+ @result{} (progn (setq r (1+ r)) (setq s (1+ s)))
+@end smallexample
+
+@end defun
+
@node Compiling Macros
@section Macros and Byte Compilation
@cindex byte-compiling macros
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
(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.
called interactively.
@end defspec
+ The body of the macro definition can include a @code{declare} form,
+which can specify how @key{TAB} should indent macro calls, and how to
+step through them for Edebug.
+
+@defmac declare @var{specs}@dots{}
+@anchor{Definition of declare}
+A @code{declare} form is used in a macro definition to specify various
+additional information about it. Two kinds of specification are
+currently supported:
+
+@table @code
+@item (debug @var{edebug-form-spec})
+Specify how to step through macro calls for Edebug.
+@xref{Instrumenting Macro Calls}, for more details.
+
+@item (indent @var{indent-spec})
+Specify how to indent calls to this macro. @xref{Indenting Macros},
+for more details.
+@end table
+
+A @code{declare} form only has its special effect in the body of a
+@code{defmacro} form if it immediately follows the documentation
+string, if present, or the argument list otherwise. (Strictly
+speaking, @emph{several} @code{declare} forms can follow the
+documentation string or argument list, but since a @code{declare} form
+can have several @var{specs}, they can always be combined into a
+single form.) When used at other places in a @code{defmacro} form, or
+outside a @code{defmacro} form, @code{declare} just returns @code{nil}
+without evaluating any @var{specs}.
+@end defmac
+
+ No macro absolutely needs a @code{declare} form, because that form
+has no effect on how the macro expands, on what the macro means in the
+program. It only affects secondary features: indentation and Edebug.
+
@node Backquote
@section Backquote
@cindex backquote (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
-@samp{`} (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
`(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,
+ 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 @samp{`} is often unreadable.
@end group
@end example
-@quotation
-Before Emacs 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{,@@} substition 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.
+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.
-This syntax is still accepted, but no longer recommended except for
-compatibility with old Emacs versions.
-@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
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.
* Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu
+@node Wrong Time
+@subsection Wrong Time
+
+ The most common problem in writing macros is doing some of the
+real work prematurely---while expanding the macro, rather than in the
+expansion itself. For instance, one real package had this macro
+definition:
+
+@example
+(defmacro my-set-buffer-multibyte (arg)
+ (if (fboundp 'set-buffer-multibyte)
+ (set-buffer-multibyte arg)))
+@end example
+
+With this erroneous macro definition, the program worked fine when
+interpreted but failed when compiled. This macro definition called
+@code{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:
+
+@example
+(defmacro my-set-buffer-multibyte (arg)
+ (if (fboundp 'set-buffer-multibyte)
+ `(set-buffer-multibyte ,arg)))
+@end example
+
+@noindent
+This macro expands, if appropriate, into a call to
+@code{set-buffer-multibyte} that will be executed when the compiled
+program is actually run.
+
@node Argument Evaluation
@subsection Evaluating Macro Arguments Repeatedly
(let ((i 1))
(while (<= i 3)
(setq square (* i i))
- (princ (format "%d %d" i square))
+ (princ (format "\n%d %d" i square))
(inc i)))
@end group
@group
@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:
@end group
@end smallexample
-Here is a macro definition that creates this expansion:
+Here is a macro definition that creates this expansion:
@smallexample
@group
@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
-@ifinfo
+@ifnottex
In the previous section, the definition of @code{for} was fixed as
follows to make the expansion evaluate the macro arguments the proper
number of times:
(inc ,var))))
@end group
@end smallexample
-@end ifinfo
+@end ifnottex
The new definition of @code{for} has a new problem: it introduces a
local variable named @code{max} which the user does not expect. This
@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
allocation construct. You wouldn't use @code{setcar} on a constant such
as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
either.
+
+@node Indenting Macros
+@section Indenting Macros
+
+ You can use the @code{declare} form in the macro definition to
+specify how to @key{TAB} should indent indent calls to the macro. You
+write it like this:
+
+@example
+(declare (indent @var{indent-spec}))
+@end example
+
+@noindent
+Here are the possibilities for @var{indent-spec}:
+
+@table @asis
+@item @code{nil}
+This is the same as no property---use the standard indentation pattern.
+@item @code{defun}
+Handle this function like a @samp{def} construct: treat the second
+line as the start of a @dfn{body}.
+@item an integer, @var{number}
+The first @var{number} arguments of the function are
+@dfn{distinguished} arguments; the rest are considered the body
+of the expression. A line in the expression is indented according to
+whether the first argument on it is distinguished or not. If the
+argument is part of the body, the line is indented @code{lisp-body-indent}
+more columns than the open-parenthesis starting the containing
+expression. If the argument is distinguished and is either the first
+or second argument, it is indented @emph{twice} that many extra columns.
+If the argument is distinguished and not the first or second argument,
+the line uses the standard pattern.
+@item a symbol, @var{symbol}
+@var{symbol} should be a function name; that function is called to
+calculate the indentation of a line within this expression. The
+function receives two arguments:
+@table @asis
+@item @var{state}
+The value returned by @code{parse-partial-sexp} (a Lisp primitive for
+indentation and nesting computation) when it parses up to the
+beginning of this line.
+@item @var{pos}
+The position at which the line being indented begins.
+@end table
+@noindent
+It should return either a number, which is the number of columns of
+indentation for that line, or a list whose car is such a number. The
+difference between returning a number and returning a list is that a
+number says that all following lines at the same nesting level should
+be indented just like this one; a list says that following lines might
+call for different indentations. This makes a difference when the
+indentation is being computed by @kbd{C-M-q}; if the value is a
+number, @kbd{C-M-q} need not recalculate indentation for the following
+lines until the end of the list.
+@end table
+
+@ignore
+ arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
+@end ignore