@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998, 2001-2016 Free Software Foundation,
+@c Inc.
@c See the file elisp.texi for copying conditions.
-@node Macros, Customization, Functions, Top
+@node Macros
@chapter Macros
@cindex macros
@section A Simple Example of a Macro
Suppose we would like to define a Lisp construct to increment a
-variable value, much like the @code{++} operator in C. We would like to
+variable value, much like the @code{++} operator in C@. We would like to
write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
Here's a macro definition that does the job:
returns this expansion, Lisp proceeds to evaluate it, thus incrementing
@code{x}.
+@defun macrop object
+This predicate tests whether its argument is a macro, and returns
+@code{t} if so, @code{nil} otherwise.
+@end defun
+
@node Expansion
@section Expansion of a Macro Call
@cindex expansion of macros
calls to other macros. It may even be a call to the same macro, though
this is unusual.
+ Note that Emacs tries to expand macros when loading an uncompiled
+Lisp file. This is not always possible, but if it is, it speeds up
+subsequent execution. @xref{How Programs Do Loading}.
+
You can see the expansion of a given macro call by calling
@code{macroexpand}.
definitions that shadow the currently defined macros. Byte compilation
uses this feature.
-@smallexample
+@example
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
- @result{} inc
@end group
@group
@group
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
- @result{} inc2
@end group
@group
(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
+@defun macroexpand-1 form &optional environment
+This function expands macros like @code{macroexpand}, but it only
+performs one step of the expansion: if the result is another macro
+call, @code{macroexpand-1} will not expand it.
@end defun
@node Compiling Macros
@node Defining Macros
@section Defining Macros
+@cindex defining macros
+@cindex macro, how to define
- A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should
-be a function; expansion of the macro works by applying the function
-(with @code{apply}) to the list of unevaluated argument-expressions
-from the macro call.
+ A Lisp macro object is a list whose @sc{car} is @code{macro}, and
+whose @sc{cdr} is a function. Expansion of the macro works
+by applying the function (with @code{apply}) to the list of
+@emph{unevaluated} arguments 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 @code{mapcar}. In practice,
-all Lisp macros have names, and they are usually defined with the
-special form @code{defmacro}.
+function, but this is never done, because it does not make sense to
+pass an anonymous macro to functionals such as @code{mapcar}. In
+practice, all Lisp macros have names, and they are almost always
+defined with the @code{defmacro} macro.
-@defspec defmacro name argument-list body-forms@dots{}
-@code{defmacro} defines the symbol @var{name} as a macro that looks
-like this:
+@defmac defmacro name args [doc] [declare] body@dots{}
+@code{defmacro} defines the symbol @var{name} (which should not be
+quoted) as a macro that looks like this:
@example
-(macro lambda @var{argument-list} . @var{body-forms})
+(macro lambda @var{args} . @var{body})
@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.
-
-The shape and meaning of @var{argument-list} is the same as in a
-function, and the keywords @code{&rest} and @code{&optional} may be used
-(@pxref{Argument List}). Macros may have a documentation string, but
-any @code{interactive} declaration is ignored since macros cannot be
-called interactively.
-@end defspec
+(Note that the @sc{cdr} of this list is a lambda expression.) This
+macro object is stored in the function cell of @var{name}. The
+meaning of @var{args} is the same as in a function, and the keywords
+@code{&rest} and @code{&optional} may be used (@pxref{Argument List}).
+Neither @var{name} nor @var{args} should be quoted. The return value
+of @code{defmacro} is undefined.
+
+@var{doc}, if present, should be a string specifying the macro's
+documentation string. @var{declare}, if present, should be a
+@code{declare} form specifying metadata for the macro (@pxref{Declare
+Form}). Note that macros cannot have interactive declarations, since
+they cannot be called interactively.
+@end defmac
Macros often need to construct large list structures from a mixture
of constants and nonconstant parts. To make this easier, use the
@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. The following specifications are
-currently supported:
-
-@table @code
-@item (debug @var{edebug-form-spec})
-Specify how to step through macro calls for Edebug.
-@xref{Instrumenting Macro Calls}.
-
-@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
-@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 the secondary features listed above.
+which specifies additional properties about the macro. @xref{Declare
+Form}.
@node Problems with Macros
@section Common Problems Using Macros
+@cindex macro caveats
Macro expansion can have counterintuitive consequences. This
section describes some important consequences that can lead to
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 ``for'' loop construct.
+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
@group
(for i from 1 to 3 do
@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
-``syntactic sugar''; they are entirely ignored. The idea is that you
+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.
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
@group
(defmacro foo (a)
(list 'setq (eval a) t))
- @result{} foo
@end group
@group
(setq x 'b)
constructed each time @code{initialize} is called. Thus, no side effect
survives between calls. If @code{initialize} is compiled, then the
macro @code{empty-object} is expanded during compilation, producing a
-single ``constant'' @code{(nil)} that is reused and altered each time
+single constant @code{(nil)} that is reused and altered each time
@code{initialize} is called.
One way to avoid pathological cases like this is to think of
@section Indenting Macros
Within a macro definition, you can use the @code{declare} form
-(@pxref{Defining Macros}) to specify how to @key{TAB} should indent
+(@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}))
@end example
+@noindent
+@cindex @code{lisp-indent-function} property
+This results in the @code{lisp-indent-function} property being set on
+the macro name.
+
@noindent
Here are the possibilities for @var{indent-spec}:
function receives two arguments:
@table @asis
+@item @var{pos}
+The position at which the line being indented begins.
@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