comparison lispref/macros.texi @ 89910:548375b6b1f8

Update unicode branch

89909:68c22ea6027c

@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

* 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.
@end menu

@node Simple Macro
@section A Simple Example of a Macro

@group
(macroexpand '(inc2 r s))
     @result{} (progn (inc r) (inc s))  ; @r{@code{inc} not expanded here.}
@end group
@end smallexample
@end defun

@node Compiling Macros
@section Macros and Byte Compilation
@cindex byte-compiling macros

(@pxref{Argument List}).  Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be
called interactively.
@end defspec

@node Backquote
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
@findex `

@end menu

@node Wrong Time
@subsection Wrong Time

  The most common problem in writing macros is doing too some of the
real work prematurely---while expanding the macro, rather than in the
expansion itself.  For instance, one real package had this nmacro
definition:

@example
(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)

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.

89910:548375b6b1f8

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2004 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

* 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.
@end menu

@node Simple Macro
@section A Simple Example of a Macro

@group
(macroexpand '(inc2 r s))
     @result{} (progn (inc r) (inc s))  ; @r{@code{inc} not expanded here.}
@end group
@end smallexample
@end defun


@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
top-level.

In emacs-lisp, @code{macroexpand-all} guarantees that if no macros
are expanded, the return value will be @code{eq} to @var{form}.

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

@node Compiling Macros
@section Macros and Byte Compilation
@cindex byte-compiling macros

(@pxref{Argument List}).  Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be
called interactively.
@end defspec

  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.

@anchor{Definition of declare}
@defmac declare @var{specs}@dots{}
A @code{declare} form is used in a macro definition to specify various
additional information about it.  Two kinds of specification are
currently supported:

@table @code
@item (edebug @var{edebug-form-spec})
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

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 secondary features: indentation and Edebug.

@node Backquote
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
@findex `

@end menu

@node Wrong Time
@subsection Wrong Time

  The most common problem in writing macros is doing some of the
real work prematurely---while expanding the macro, rather than in the
expansion itself.  For instance, one real package had this macro
definition:

@example
(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)

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.

@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}.
@item a number, @var{number}
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

@ignore
   arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
@end ignore