1994-03-28 20:21:44 +00:00
|
|
|
@c -*-texinfo-*-
|
|
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
2005-08-10 14:29:01 +00:00
|
|
|
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2002, 2003,
|
|
|
|
@c 2004, 2005 Free Software Foundation, Inc.
|
1994-03-28 20:21:44 +00:00
|
|
|
@c See the file elisp.texi for copying conditions.
|
|
|
|
@setfilename ../info/macros
|
1998-02-28 01:53:53 +00:00
|
|
|
@node Macros, Customization, Functions, Top
|
1994-03-28 20:21:44 +00:00
|
|
|
@chapter Macros
|
|
|
|
@cindex macros
|
|
|
|
|
|
|
|
@dfn{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 @dfn{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. @xref{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.
|
2003-08-06 01:33:33 +00:00
|
|
|
* Indenting Macros:: Specifying how to indent macro calls.
|
1994-03-28 20:21:44 +00:00
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Simple Macro
|
|
|
|
@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
|
|
|
|
write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
|
|
|
|
Here's a macro definition that does the job:
|
|
|
|
|
|
|
|
@findex inc
|
|
|
|
@example
|
|
|
|
@group
|
|
|
|
(defmacro inc (var)
|
|
|
|
(list 'setq var (list '1+ var)))
|
|
|
|
@end group
|
|
|
|
@end example
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
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}.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@node Expansion
|
|
|
|
@section Expansion of a Macro Call
|
|
|
|
@cindex expansion of macros
|
|
|
|
@cindex 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 @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
|
|
|
|
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
|
|
|
|
@code{macroexpand}.
|
|
|
|
|
|
|
|
@defun macroexpand form &optional environment
|
|
|
|
@cindex macro expansion
|
|
|
|
This function expands @var{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
|
|
|
|
@code{macroexpand}. If @var{form} is not a macro call to begin with, it
|
|
|
|
is returned as given.
|
|
|
|
|
|
|
|
Note that @code{macroexpand} does not look at the subexpressions of
|
|
|
|
@var{form} (although some macro definitions may do so). Even if they
|
|
|
|
are macro calls themselves, @code{macroexpand} does not expand them.
|
|
|
|
|
|
|
|
The function @code{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 @var{environment} is provided, it specifies an alist of macro
|
|
|
|
definitions that shadow the currently defined macros. Byte compilation
|
|
|
|
uses this feature.
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
@group
|
|
|
|
(defmacro inc (var)
|
|
|
|
(list 'setq var (list '1+ var)))
|
|
|
|
@result{} inc
|
|
|
|
@end group
|
|
|
|
|
|
|
|
@group
|
|
|
|
(macroexpand '(inc r))
|
|
|
|
@result{} (setq r (1+ r))
|
|
|
|
@end 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 defun
|
|
|
|
|
2004-04-12 05:43:12 +00:00
|
|
|
|
|
|
|
@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
|
2005-02-27 00:01:41 +00:00
|
|
|
top-level. If no macros are expanded, the return value is @code{eq}
|
|
|
|
to @var{form}.
|
2004-04-12 05:43:12 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
|
1994-03-28 20:21:44 +00:00
|
|
|
@node Compiling Macros
|
|
|
|
@section Macros and Byte Compilation
|
|
|
|
@cindex byte-compiling macros
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
1998-02-28 01:53:53 +00:00
|
|
|
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.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
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
|
1995-06-06 19:21:15 +00:00
|
|
|
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}).
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@node Defining Macros
|
|
|
|
@section Defining Macros
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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
|
1995-06-06 19:21:15 +00:00
|
|
|
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}.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@defspec defmacro name argument-list body-forms@dots{}
|
|
|
|
@code{defmacro} defines the symbol @var{name} as a macro that looks
|
|
|
|
like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
(macro lambda @var{argument-list} . @var{body-forms})
|
|
|
|
@end example
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
(Note that the @sc{cdr} of this list is a function---a lambda expression.)
|
1994-03-28 20:21:44 +00:00
|
|
|
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
|
|
|
|
|
2003-08-06 01:33:33 +00:00
|
|
|
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.
|
|
|
|
|
2004-01-16 00:43:54 +00:00
|
|
|
@defmac declare @var{specs}@dots{}
|
2004-06-23 16:40:04 +00:00
|
|
|
@anchor{Definition of declare}
|
2004-01-16 00:43:54 +00:00
|
|
|
A @code{declare} form is used in a macro definition to specify various
|
|
|
|
additional information about it. Two kinds of specification are
|
|
|
|
currently supported:
|
2003-08-06 01:33:33 +00:00
|
|
|
|
|
|
|
@table @code
|
2004-07-23 18:25:57 +00:00
|
|
|
@item (debug @var{edebug-form-spec})
|
2003-08-06 01:33:33 +00:00
|
|
|
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
|
2004-01-16 00:43:54 +00:00
|
|
|
|
|
|
|
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
|
2003-08-06 01:33:33 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
1994-03-28 20:21:44 +00:00
|
|
|
@node Backquote
|
|
|
|
@section Backquote
|
|
|
|
@cindex backquote (list substitution)
|
|
|
|
@cindex ` (list substitution)
|
1995-06-05 12:23:13 +00:00
|
|
|
@findex `
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
Macros often need to construct large list structures from a mixture of
|
1998-04-20 17:43:57 +00:00
|
|
|
constants and nonconstant parts. To make this easier, use the @samp{`}
|
|
|
|
syntax (usually called @dfn{backquote}).
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
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
|
1995-06-05 12:23:13 +00:00
|
|
|
`(a list of (+ 2 3) elements)
|
1994-03-28 20:21:44 +00:00
|
|
|
@result{} (a list of (+ 2 3) elements)
|
|
|
|
@end group
|
|
|
|
@group
|
1995-06-05 12:23:13 +00:00
|
|
|
'(a list of (+ 2 3) elements)
|
1994-03-28 20:21:44 +00:00
|
|
|
@result{} (a list of (+ 2 3) elements)
|
|
|
|
@end group
|
|
|
|
@end example
|
|
|
|
|
1994-04-29 10:16:53 +00:00
|
|
|
@findex , @r{(with Backquote)}
|
1995-06-06 19:21:15 +00:00
|
|
|
The special marker @samp{,} inside of the argument to backquote
|
1994-03-28 20:21:44 +00:00
|
|
|
indicates a value that isn't constant. Backquote evaluates the
|
1995-06-06 19:21:15 +00:00
|
|
|
argument of @samp{,} and puts the value in the list structure:
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
@group
|
|
|
|
(list 'a 'list 'of (+ 2 3) 'elements)
|
|
|
|
@result{} (a list of 5 elements)
|
|
|
|
@end group
|
|
|
|
@group
|
1995-06-05 12:23:13 +00:00
|
|
|
`(a list of ,(+ 2 3) elements)
|
1994-03-28 20:21:44 +00:00
|
|
|
@result{} (a list of 5 elements)
|
|
|
|
@end group
|
1998-02-28 01:53:53 +00:00
|
|
|
@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
|
1994-03-28 20:21:44 +00:00
|
|
|
@end example
|
|
|
|
|
1994-04-29 10:16:53 +00:00
|
|
|
@findex ,@@ @r{(with Backquote)}
|
1994-03-28 20:21:44 +00:00
|
|
|
@cindex splicing (with backquote)
|
1998-02-28 01:53:53 +00:00
|
|
|
You can also @dfn{splice} an evaluated value into the resulting list,
|
1995-06-06 19:21:15 +00:00
|
|
|
using the special marker @samp{,@@}. The elements of the spliced list
|
1994-03-28 20:21:44 +00:00
|
|
|
become elements at the same level as the other elements of the resulting
|
1995-06-06 19:21:15 +00:00
|
|
|
list. The equivalent code without using @samp{`} is often unreadable.
|
1994-03-28 20:21:44 +00:00
|
|
|
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
|
1995-06-05 12:23:13 +00:00
|
|
|
`(1 ,@@some-list 4 ,@@some-list)
|
1994-03-28 20:21:44 +00:00
|
|
|
@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
|
1995-06-05 12:23:13 +00:00
|
|
|
`(use the words ,@@(cdr list) as elements)
|
1994-03-28 20:21:44 +00:00
|
|
|
@result{} (use the words foo bar as elements)
|
|
|
|
@end group
|
|
|
|
@end example
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
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.
|
1995-06-05 12:23:13 +00:00
|
|
|
|
1998-02-28 01:53:53 +00:00
|
|
|
This syntax is still accepted, for compatibility with old Emacs
|
|
|
|
versions, but we recommend not using it in new programs.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@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
|
|
|
|
trouble, and rules to follow to avoid trouble.
|
|
|
|
|
|
|
|
@menu
|
2001-06-23 16:11:23 +00:00
|
|
|
* Wrong Time:: Do the work in the expansion, not in the macro.
|
1994-03-28 20:21:44 +00:00
|
|
|
* 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.
|
|
|
|
@end menu
|
|
|
|
|
2001-06-23 16:11:23 +00:00
|
|
|
@node Wrong Time
|
|
|
|
@subsection Wrong Time
|
|
|
|
|
2004-01-16 00:43:54 +00:00
|
|
|
The most common problem in writing macros is doing some of the
|
2001-06-23 16:11:23 +00:00
|
|
|
real work prematurely---while expanding the macro, rather than in the
|
2004-01-16 00:43:54 +00:00
|
|
|
expansion itself. For instance, one real package had this macro
|
2001-06-23 16:11:23 +00:00
|
|
|
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.
|
|
|
|
|
1994-03-28 20:21:44 +00:00
|
|
|
@node Argument Evaluation
|
|
|
|
@subsection 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.
|
|
|
|
|
|
|
|
@findex for
|
|
|
|
@smallexample
|
|
|
|
@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)))))))
|
|
|
|
@end group
|
|
|
|
@result{} for
|
|
|
|
|
|
|
|
@group
|
|
|
|
(for i from 1 to 3 do
|
|
|
|
(setq square (* i i))
|
|
|
|
(princ (format "\n%d %d" i square)))
|
|
|
|
@expansion{}
|
|
|
|
@end group
|
|
|
|
@group
|
|
|
|
(let ((i 1))
|
|
|
|
(while (<= i 3)
|
|
|
|
(setq square (* i i))
|
2004-11-21 02:22:12 +00:00
|
|
|
(princ (format "\n%d %d" i square))
|
1994-03-28 20:21:44 +00:00
|
|
|
(inc i)))
|
|
|
|
@end group
|
|
|
|
@group
|
|
|
|
|
|
|
|
@print{}1 1
|
|
|
|
@print{}2 4
|
|
|
|
@print{}3 9
|
|
|
|
@result{} nil
|
|
|
|
@end group
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
@noindent
|
1998-04-20 17:43:57 +00:00
|
|
|
The arguments @code{from}, @code{to}, and @code{do} in this macro are
|
1994-03-28 20:21:44 +00:00
|
|
|
``syntactic sugar''; they are entirely ignored. The idea is that you
|
|
|
|
will write noise words (such as @code{from}, @code{to}, and @code{do})
|
1998-04-20 17:43:57 +00:00
|
|
|
in those positions in the macro call.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
1994-04-29 10:16:53 +00:00
|
|
|
Here's an equivalent definition simplified through use of backquote:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
@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))."
|
1995-06-06 19:21:15 +00:00
|
|
|
`(let ((,var ,init))
|
|
|
|
(while (<= ,var ,final)
|
|
|
|
,@@body
|
|
|
|
(inc ,var))))
|
1994-04-29 10:16:53 +00:00
|
|
|
@end group
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
Both forms of this definition (with backquote and without) suffer from
|
|
|
|
the defect that @var{final} is evaluated on every iteration. If
|
|
|
|
@var{final} is a constant, this is not a problem. If it is a more
|
|
|
|
complex form, say @code{(long-complex-calculation x)}, this can slow
|
|
|
|
down the execution significantly. If @var{final} has side effects,
|
|
|
|
executing it more than once is probably incorrect.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@cindex macro argument evaluation
|
|
|
|
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 @code{for} macro:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
@group
|
|
|
|
(let ((i 1)
|
|
|
|
(max 3))
|
|
|
|
(while (<= i max)
|
|
|
|
(setq square (* i i))
|
|
|
|
(princ (format "%d %d" i square))
|
|
|
|
(inc i)))
|
|
|
|
@end group
|
|
|
|
@end smallexample
|
|
|
|
|
2003-02-04 14:56:31 +00:00
|
|
|
Here is a macro definition that creates this expansion:
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@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))."
|
1995-06-06 19:21:15 +00:00
|
|
|
`(let ((,var ,init)
|
|
|
|
(max ,final))
|
|
|
|
(while (<= ,var max)
|
|
|
|
,@@body
|
|
|
|
(inc ,var))))
|
1994-03-28 20:21:44 +00:00
|
|
|
@end group
|
|
|
|
@end smallexample
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
Unfortunately, this fix introduces another problem,
|
|
|
|
described in the following section.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@node Surprising Local Vars
|
|
|
|
@subsection Local Variables in Macro Expansions
|
|
|
|
|
2000-01-05 15:18:01 +00:00
|
|
|
@ifnottex
|
1994-03-28 20:21:44 +00:00
|
|
|
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:
|
|
|
|
|
|
|
|
@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))."
|
|
|
|
@end group
|
|
|
|
@group
|
1995-06-06 19:21:15 +00:00
|
|
|
`(let ((,var ,init)
|
|
|
|
(max ,final))
|
|
|
|
(while (<= ,var max)
|
|
|
|
,@@body
|
|
|
|
(inc ,var))))
|
1994-03-28 20:21:44 +00:00
|
|
|
@end group
|
|
|
|
@end smallexample
|
2000-01-05 15:18:01 +00:00
|
|
|
@end ifnottex
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
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:
|
|
|
|
|
1994-05-28 14:52:37 +00:00
|
|
|
@smallexample
|
1994-03-28 20:21:44 +00:00
|
|
|
@group
|
|
|
|
(let ((max 0))
|
|
|
|
(for x from 0 to 10 do
|
|
|
|
(let ((this (frob x)))
|
|
|
|
(if (< max this)
|
|
|
|
(setq max this)))))
|
|
|
|
@end group
|
1994-05-28 14:52:37 +00:00
|
|
|
@end smallexample
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@noindent
|
|
|
|
The references to @code{max} inside the body of the @code{for}, which
|
|
|
|
are supposed to refer to the user's binding of @code{max}, really access
|
|
|
|
the binding made by @code{for}.
|
|
|
|
|
|
|
|
The way to correct this is to use an uninterned symbol instead of
|
|
|
|
@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be
|
1994-04-29 10:16:53 +00:00
|
|
|
bound and referred to just like any other symbol, but since it is
|
|
|
|
created by @code{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 @code{for}. Here is a definition of @code{for} that works
|
|
|
|
this way:
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@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 ((tempvar (make-symbol "max")))
|
1995-06-06 19:21:15 +00:00
|
|
|
`(let ((,var ,init)
|
|
|
|
(,tempvar ,final))
|
|
|
|
(while (<= ,var ,tempvar)
|
|
|
|
,@@body
|
|
|
|
(inc ,var)))))
|
1994-03-28 20:21:44 +00:00
|
|
|
@end group
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
This creates an uninterned symbol named @code{max} and puts it in the
|
|
|
|
expansion instead of the usual interned symbol @code{max} that appears
|
|
|
|
in expressions ordinarily.
|
|
|
|
|
|
|
|
@node Eval During Expansion
|
|
|
|
@subsection Evaluating Macro Arguments in Expansion
|
|
|
|
|
1998-05-19 03:45:57 +00:00
|
|
|
Another problem can happen if the macro definition itself
|
1998-02-28 01:53:53 +00:00
|
|
|
evaluates any of the macro argument expressions, such as by calling
|
1994-03-28 20:21:44 +00:00
|
|
|
@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
|
1998-02-28 01:53:53 +00:00
|
|
|
variable, so any references inside the form being evaluated do refer to
|
|
|
|
it. Here is an example:
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
@group
|
|
|
|
(defmacro foo (a)
|
|
|
|
(list 'setq (eval a) t))
|
|
|
|
@result{} foo
|
|
|
|
@end group
|
|
|
|
@group
|
|
|
|
(setq x 'b)
|
|
|
|
(foo x) @expansion{} (setq b t)
|
|
|
|
@result{} t ; @r{and @code{b} has been set.}
|
|
|
|
;; @r{but}
|
|
|
|
(setq a 'c)
|
|
|
|
(foo a) @expansion{} (setq a t)
|
|
|
|
@result{} t ; @r{but this set @code{a}, not @code{c}.}
|
|
|
|
|
|
|
|
@end group
|
|
|
|
@end example
|
|
|
|
|
|
|
|
It makes a difference whether the user's variable is named @code{a} or
|
|
|
|
@code{x}, because @code{a} conflicts with the macro argument variable
|
|
|
|
@code{a}.
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
Another problem with calling @code{eval} in a macro definition is that
|
1994-03-28 20:21:44 +00:00
|
|
|
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.
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
To avoid these problems, @strong{don't evaluate an argument expression
|
1998-05-19 03:45:57 +00:00
|
|
|
while computing the macro expansion}. Instead, substitute the
|
1998-04-20 17:43:57 +00:00
|
|
|
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.
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@node Repeated Expansion
|
|
|
|
@subsection 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.
|
|
|
|
|
1998-04-20 17:43:57 +00:00
|
|
|
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:
|
1994-03-28 20:21:44 +00:00
|
|
|
|
|
|
|
@lisp
|
|
|
|
@group
|
|
|
|
(defmacro empty-object ()
|
|
|
|
(list 'quote (cons nil nil)))
|
|
|
|
@end group
|
|
|
|
|
|
|
|
@group
|
|
|
|
(defun initialize (condition)
|
|
|
|
(let ((object (empty-object)))
|
|
|
|
(if condition
|
|
|
|
(setcar object condition))
|
|
|
|
object))
|
|
|
|
@end group
|
|
|
|
@end lisp
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
If @code{initialize} is interpreted, a new list @code{(nil)} is
|
|
|
|
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
|
|
|
|
@code{initialize} is called.
|
|
|
|
|
|
|
|
One way to avoid pathological cases like this is to think of
|
|
|
|
@code{empty-object} as a funny kind of constant, not as a memory
|
|
|
|
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.
|
2003-08-06 01:33:33 +00:00
|
|
|
|
|
|
|
@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}.
|
2005-02-27 00:01:41 +00:00
|
|
|
@item an integer, @var{number}
|
2003-08-06 01:33:33 +00:00
|
|
|
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
|
2003-09-01 15:45:59 +00:00
|
|
|
|
|
|
|
@ignore
|
|
|
|
arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
|
|
|
|
@end ignore
|