"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/lispref/macros.texi" between
xemacs-21.4.22.tar.gz and xemacs-21.4.24.tar.bz2

About: XEmacs (an alternative to GNU Emacs) is a highly customizable open source text editor and application development system (current version).

macros.texi  (xemacs-21.4.22):macros.texi  (xemacs-21.4.24.tar.bz2)
skipping to change at line 35 skipping to change at line 35
@menu @menu
* Simple Macro:: A basic example. * Simple Macro:: A basic example.
* Expansion:: How, when and why macros are expanded. * Expansion:: How, when and why macros are expanded.
* Compiling Macros:: How macros are expanded by the compiler. * Compiling Macros:: How macros are expanded by the compiler.
* Defining Macros:: How to write a macro definition. * Defining Macros:: How to write a macro definition.
* Backquote:: Easier construction of list structure. * Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times. * Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables. Don't hide the user's variables.
@end menu @end menu
@node Simple Macro @node Simple Macro, Expansion, Macros, Macros
@section A Simple Example of a Macro @section A Simple Example of a Macro
Suppose we would like to define a Lisp construct to increment a 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))}. write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
Here's a macro definition that does the job: Here's a macro definition that does the job:
@findex inc @findex inc
@example @example
@group @group
skipping to change at line 57 skipping to change at line 57
(list 'setq var (list '1+ var))) (list 'setq var (list '1+ var)))
@end group @end group
@end example @end example
When this is called with @code{(inc x)}, the argument @code{var} has 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 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 of the macro uses this to construct the expansion, which is @code{(setq
x (1+ x))}. Once the macro definition returns this expansion, Lisp x (1+ x))}. Once the macro definition returns this expansion, Lisp
proceeds to evaluate it, thus incrementing @code{x}. proceeds to evaluate it, thus incrementing @code{x}.
@node Expansion @node Expansion, Compiling Macros, Simple Macro, Macros
@section Expansion of a Macro Call @section Expansion of a Macro Call
@cindex expansion of macros @cindex expansion of macros
@cindex macro call @cindex macro call
A macro call looks just like a function call in that it is a list which 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 starts with the name of the macro. The rest of the elements of the list
are the arguments of the macro. are the arguments of the macro.
Evaluation of the macro call begins like evaluation of a function call Evaluation of the macro call begins like evaluation of a function call
except for one crucial difference: the macro arguments are the actual except for one crucial difference: the macro arguments are the actual
skipping to change at line 138 skipping to change at line 138
@result{} inc2 @result{} inc2
@end group @end group
@group @group
(macroexpand '(inc2 r s)) (macroexpand '(inc2 r s))
@result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
@end group @end group
@end smallexample @end smallexample
@end defun @end defun
@node Compiling Macros @node Compiling Macros, Defining Macros, Expansion, Macros
@section Macros and Byte Compilation @section Macros and Byte Compilation
@cindex byte-compiling macros @cindex byte-compiling macros
You might ask why we take the trouble to compute an expansion for a 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 macro and then evaluate the expansion. Why not have the macro body
produce the desired results directly? The reason has to do with produce the desired results directly? The reason has to do with
compilation. compilation.
When a macro call appears in a Lisp program being compiled, the Lisp When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and compiler calls the macro definition just as the interpreter would, and
skipping to change at line 172 skipping to change at line 172
Byte-compiling a file executes any @code{require} calls at top-level 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 in the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions proper compilation. One way to ensure that necessary macro definitions
are available during compilation is to require the files that define are available during compilation is to require the files that define
them (@pxref{Named Features}). To avoid loading the macro definition files them (@pxref{Named Features}). To avoid loading the macro definition files
when someone @emph{runs} the compiled program, write when someone @emph{runs} the compiled program, write
@code{eval-when-compile} around the @code{require} calls (@pxref{Eval @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
During Compile}). During Compile}).
@node Defining Macros @node Defining Macros, Backquote, Compiling Macros, Macros
@section Defining Macros @section Defining Macros
A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should 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 be a function; expansion of the macro works by applying the function
(with @code{apply}) to the list of unevaluated argument-expressions (with @code{apply}) to the list of unevaluated argument-expressions
from the macro call. from the macro call.
It is possible to use an anonymous Lisp macro just like an anonymous 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 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, an anonymous macro to functionals such as @code{mapcar}. In practice,
skipping to change at line 205 skipping to change at line 205
value returned by evaluating the @code{defmacro} form is @var{name}, but value returned by evaluating the @code{defmacro} form is @var{name}, but
usually we ignore this value. usually we ignore this value.
The shape and meaning of @var{argument-list} is the same as in a 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 function, and the keywords @code{&rest} and @code{&optional} may be used
(@pxref{Argument List}). Macros may have a documentation string, but (@pxref{Argument List}). Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be any @code{interactive} declaration is ignored since macros cannot be
called interactively. called interactively.
@end defspec @end defspec
@node Backquote @node Backquote, Problems with Macros, Defining Macros, Macros
@section Backquote @section Backquote
@cindex backquote (list substitution) @cindex backquote (list substitution)
@cindex ` (list substitution) @cindex ` (list substitution)
@findex ` @findex `
Macros often need to construct large list structures from a mixture of Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro constants and nonconstant parts. To make this easier, use the macro
@samp{`} (often called @dfn{backquote}). @samp{`} (often called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate Backquote allows you to quote a list, but selectively evaluate
skipping to change at line 298 skipping to change at line 298
of parentheses around the entire backquote construct. Likewise, each of parentheses around the entire backquote construct. Likewise, each
@samp{,} or @samp{,@@} substitution required an extra level of @samp{,} or @samp{,@@} substitution required an extra level of
parentheses surrounding both the @samp{,} or @samp{,@@} and the parentheses surrounding both the @samp{,} or @samp{,@@} and the
following expression. The old syntax required whitespace between the following expression. The old syntax required whitespace between the
@samp{`}, @samp{,} or @samp{,@@} and the following expression. @samp{`}, @samp{,} or @samp{,@@} and the following expression.
This syntax is still accepted, but no longer recommended except for This syntax is still accepted, but no longer recommended except for
compatibility with old Emacs versions. compatibility with old Emacs versions.
@end quotation @end quotation
@node Problems with Macros @node Problems with Macros, , Backquote, Macros
@section Common Problems Using Macros @section Common Problems Using Macros
The basic facts of macro expansion have counterintuitive consequences. The basic facts of macro expansion have counterintuitive consequences.
This section describes some important consequences that can lead to This section describes some important consequences that can lead to
trouble, and rules to follow to avoid trouble. trouble, and rules to follow to avoid trouble.
@menu @menu
* Argument Evaluation:: The expansion should evaluate each macro arg once. * Argument Evaluation:: The expansion should evaluate each macro arg once.
* Surprising Local Vars:: Local variable bindings in the expansion * Surprising Local Vars:: Local variable bindings in the expansion
require special care. require special care.
* Eval During Expansion:: Don't evaluate them; put them in the expansion. * Eval During Expansion:: Don't evaluate them; put them in the expansion.
* Repeated Expansion:: Avoid depending on how many times expansion is done. * Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu @end menu
@node Argument Evaluation @node Argument Evaluation, Surprising Local Vars, Problems with Macros, Problems with Macros
@subsection Evaluating Macro Arguments Repeatedly @subsection Evaluating Macro Arguments Repeatedly
When defining a macro you must pay attention to the number of times When defining a macro you must pay attention to the number of times
the arguments will be evaluated when the expansion is executed. The the arguments will be evaluated when the expansion is executed. The
following macro (used to facilitate iteration) illustrates the problem. following macro (used to facilitate iteration) illustrates the problem.
This macro allows us to write a simple ``for'' loop such as one might This macro allows us to write a simple ``for'' loop such as one might
find in Pascal. find in Pascal.
@findex for @findex for
@smallexample @smallexample
skipping to change at line 419 skipping to change at line 419
,@@body ,@@body
(inc ,var)))) (inc ,var))))
@end group @end group
@end smallexample @end smallexample
Unfortunately, this introduces another problem. Unfortunately, this introduces another problem.
@ifinfo @ifinfo
Proceed to the following node. Proceed to the following node.
@end ifinfo @end ifinfo
@node Surprising Local Vars @node Surprising Local Vars, Eval During Expansion, Argument Evaluation, Problem s with Macros
@subsection Local Variables in Macro Expansions @subsection Local Variables in Macro Expansions
@ifinfo @ifinfo
In the previous section, the definition of @code{for} was fixed as In the previous section, the definition of @code{for} was fixed as
follows to make the expansion evaluate the macro arguments the proper follows to make the expansion evaluate the macro arguments the proper
number of times: number of times:
@smallexample @smallexample
@group @group
(defmacro for (var from init to final do &rest body) (defmacro for (var from init to final do &rest body)
skipping to change at line 488 skipping to change at line 488
,@@body ,@@body
(inc ,var))))) (inc ,var)))))
@end group @end group
@end smallexample @end smallexample
@noindent @noindent
This creates an uninterned symbol named @code{max} and puts it in the This creates an uninterned symbol named @code{max} and puts it in the
expansion instead of the usual interned symbol @code{max} that appears expansion instead of the usual interned symbol @code{max} that appears
in expressions ordinarily. in expressions ordinarily.
@node Eval During Expansion @node Eval During Expansion, Repeated Expansion, Surprising Local Vars, Problems with Macros
@subsection Evaluating Macro Arguments in Expansion @subsection Evaluating Macro Arguments in Expansion
Another problem can happen if you evaluate any of the macro argument Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling expressions during the computation of the expansion, such as by calling
@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the @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 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 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 macro body, the macro argument binding is the most local binding of this
variable, so any references inside the form being evaluated do refer variable, so any references inside the form being evaluated do refer
to it. Here is an example: to it. Here is an example:
skipping to change at line 533 skipping to change at line 533
it probably won't do what you intend in a compiled program. The it probably won't do what you intend in a compiled program. The
byte-compiler runs macro definitions while compiling the program, when byte-compiler runs macro definitions while compiling the program, when
the program's own computations (which you might have wished to access 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 with @code{eval}) don't occur and its local variable bindings don't
exist. exist.
The safe way to work with the run-time value of an expression is to 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 put the expression into the macro expansion, so that its value is
computed as part of executing the expansion. computed as part of executing the expansion.
@node Repeated Expansion @node Repeated Expansion, , Eval During Expansion, Problems with Macros
@subsection How Many Times is the Macro Expanded? @subsection How Many Times is the Macro Expanded?
Occasionally problems result from the fact that a macro call is Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is expanded each time it is evaluated in an interpreted function, but is
expanded only once (during compilation) for a compiled function. If the expanded only once (during compilation) for a compiled function. If the
macro definition has side effects, they will work differently depending macro definition has side effects, they will work differently depending
on how many times the macro is expanded. on how many times the macro is expanded.
In particular, constructing objects is a kind of side effect. If the In particular, constructing objects is a kind of side effect. If the
macro is called once, then the objects are constructed only once. In macro is called once, then the objects are constructed only once. In
 End of changes. 10 change blocks. 
10 lines changed or deleted 10 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)