@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/macros
-@node Macros, Customization, Functions, Top
+@node Macros
@chapter Macros
@cindex macros
* 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.
* Indenting Macros:: Specifying how to indent macro calls.
case of a @code{&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 @dfn{expansion} of the macro. The Lisp interpreter
+ The second crucial difference between macros and functions is that
+the value returned by the macro body is an alternate Lisp expression,
+also known as the @dfn{expansion} of the macro. The Lisp interpreter
proceeds to evaluate the expansion as soon as it comes back from the
macro.
definitions that shadow the currently defined macros. Byte compilation
uses this feature.
-@smallexample
+@example
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
(macroexpand '(inc2 r s))
@result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
@end group
-@end smallexample
+@end example
@end defun
@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
expand the embedded calls to @code{inc}:
-@smallexample
+@example
(macroexpand-all '(inc2 r s))
@result{} (progn (setq r (1+ r)) (setq s (1+ s)))
-@end smallexample
+@end example
@end defun
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 files that define
-them (@pxref{Named Features}). To avoid loading the macro definition files
-when someone @emph{runs} the compiled program, write
+temporarily for the rest of the compilation of that file.
+
+ Byte-compiling a file also executes any @code{require} calls at
+top-level in the file, so you can ensure that necessary macro
+definitions are available during compilation by requiring 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}).
called interactively.
@end defspec
- The body of the macro definition can include a @code{declare} form,
+ Macros often need to construct large list structures from a mixture
+of constants and nonconstant parts. To make this easier, use the
+@samp{`} syntax (@pxref{Backquote}). For example:
+
+@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
+@end example
+
+ The body of a 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
+additional information about it. The following specifications are
currently supported:
@table @code
@item (indent @var{indent-spec})
Specify how to indent calls to this macro. @xref{Indenting Macros},
for more details.
+
+@item (doc-string @var{number})
+Specify which element of the macro is the documentation string, if
+any.
@end table
A @code{declare} form only has its special effect in the body of a
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)
-@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 @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
-special form @code{quote} (@pxref{Quoting}). For example, these
-two forms yield identical results:
-
-@example
-@group
-`(a list of (+ 2 3) elements)
- @result{} (a list of (+ 2 3) elements)
-@end group
-@group
-'(a list of (+ 2 3) elements)
- @result{} (a list of (+ 2 3) elements)
-@end group
-@end example
-
-@findex , @r{(with backquote)}
-The special marker @samp{,} inside of the argument to backquote
-indicates a value that isn't constant. Backquote evaluates the
-argument of @samp{,} and puts the value in the list structure:
-
-@example
-@group
-(list 'a 'list 'of (+ 2 3) 'elements)
- @result{} (a list of 5 elements)
-@end group
-@group
-`(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 @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.
-Here are some examples:
-
-@example
-@group
-(setq some-list '(2 3))
- @result{} (2 3)
-@end group
-@group
-(cons 1 (append some-list '(4) some-list))
- @result{} (1 2 3 4 2 3)
-@end group
-@group
-`(1 ,@@some-list 4 ,@@some-list)
- @result{} (1 2 3 4 2 3)
-@end group
-
-@group
-(setq list '(hack foo bar))
- @result{} (hack foo bar)
-@end group
-@group
-(cons 'use
- (cons 'the
- (cons 'words (append (cdr list) '(as elements)))))
- @result{} (use the words foo bar as elements)
-@end group
-@group
-`(use the words ,@@(cdr list) as elements)
- @result{} (use the words foo bar as elements)
-@end group
-@end example
-
-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, for compatibility with old Emacs
-versions, but support for it will be removed in the future.
+program. It only affects the secondary features listed above.
@node Problems with Macros
@section Common Problems Using Macros
- The basic facts of macro expansion have counterintuitive consequences.
-This section describes some important consequences that can lead to
+ Macro expansion can have counterintuitive consequences. This
+section describes some important consequences that can lead to
trouble, and rules to follow to avoid trouble.
@menu
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.
+following macro (used to facilitate iteration) illustrates the
+problem. This macro allows us to write a ``for'' loop construct.
@findex for
-@smallexample
+@example
@group
(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)))))))
+ (cons 'while
+ (cons (list '<= var final)
+ (append body (list (list 'inc var)))))))
@end group
@result{} for
@print{}3 9
@result{} nil
@end group
-@end smallexample
+@end example
@noindent
The arguments @code{from}, @code{to}, and @code{do} in this macro are
Here's an equivalent definition simplified through use of backquote:
-@smallexample
+@example
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
,@@body
(inc ,var))))
@end group
-@end smallexample
+@end example
Both forms of this definition (with backquote and without) suffer from
the defect that @var{final} is evaluated on every iteration. If
once unless repeated evaluation is part of the intended purpose of the
macro. Here is a correct expansion for the @code{for} macro:
-@smallexample
+@example
@group
(let ((i 1)
(max 3))
(princ (format "%d %d" i square))
(inc i)))
@end group
-@end smallexample
+@end example
Here is a macro definition that creates this expansion:
-@smallexample
+@example
@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))."
,@@body
(inc ,var))))
@end group
-@end smallexample
+@end example
Unfortunately, this fix introduces another problem,
described in the following section.
follows to make the expansion evaluate the macro arguments the proper
number of times:
-@smallexample
+@example
@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))."
,@@body
(inc ,var))))
@end group
-@end smallexample
+@end example
@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
causes trouble in examples such as the following:
-@smallexample
+@example
@group
(let ((max 0))
(for x from 0 to 10 do
(if (< max this)
(setq max this)))))
@end group
-@end smallexample
+@end example
@noindent
The references to @code{max} inside the body of the @code{for}, which
where put by @code{for}. Here is a definition of @code{for} that works
this way:
-@smallexample
+@example
@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))."
,@@body
(inc ,var)))))
@end group
-@end smallexample
+@end example
@noindent
This creates an uninterned symbol named @code{max} and puts it in the
@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:
+ Within a macro definition, you can use the @code{declare} form
+(@pxref{Defining Macros}) to specify how @key{TAB} should indent
+calls to the macro. An indentation specification is written like this:
@example
(declare (indent @var{indent-spec}))
@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
@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
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