comparison lispref/macros.texi @ 21007:66d807bdc5b4

*** empty log message ***

21006:00022857f529

@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 See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Loading, Functions, Top
@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

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.

  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.

  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

`(a list of ,(+ 2 3) elements)
     @result{} (a list of 5 elements)
@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:

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

@node Problems with Macros
@section Common Problems Using Macros

in expressions ordinarily.

@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
@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:

@example
@group
(defmacro foo (a)
  (list 'setq (eval a) t))

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.

@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?

  Occasionally problems result from the fact that a macro call is

21007:66d807bdc5b4

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Customization, Functions, Top
@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

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.

  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
proper compilation.  One way to ensure that necessary macro definitions
are available during compilation is to require the files that define

`(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:

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 we recommend not using it in new programs.
@end quotation

@node Problems with Macros
@section Common Problems Using Macros

in expressions ordinarily.

@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion

  Another problem can happen if you 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:

@example
@group
(defmacro foo (a)
  (list 'setq (eval a) t))

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.  This is what the other
examples in this chapter do.

@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?

  Occasionally problems result from the fact that a macro call is