Initial revision

1 files changed, 593 insertions, 0 deletions

diff --git a/lispref/macros.texi b/lispref/macros.texi
new file mode 100644
index 00000000000..49d2d8e639d
--- /dev/null
+++ b/lispref/macros.texi
@@ -0,0 +1,593 @@
+@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
+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.
+@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
+
+  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
+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}.
+
+@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
+
+@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.
+
+  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 file that defines
+them.  @xref{Features}.
+
+@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
+an anonymous macro to mapping functions such as @code{mapcar}.  In
+practice, all Lisp macros have names, and they are usually defined with
+the special form @code{defmacro}.
+
+@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
+
+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
+
+@node Backquote
+@section Backquote
+@cindex backquote (list substitution)
+@cindex ` (list substitution)
+
+  Macros often need to construct large list structures from a mixture of
+constants and nonconstant parts.  To make this easier, use the macro
+@code{`} (often called @dfn{backquote}).
+
+  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
+(` (a list of (+ 2 3) elements))
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@group
+(quote (a list of (+ 2 3) elements))
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@end example
+
+@findex , @{(with Backquote)}
+The special marker, @code{,}, inside of the argument to backquote,
+indicates a value that isn't constant.  Backquote evaluates the
+argument of @code{,} and puts the value in the list structure:
+
+@example
+@group
+(list 'a 'list 'of (+ 2 3) 'elements)
+     @result{} (a list of 5 elements)
+@end group
+@group
+(` (a list of (, (+ 2 3)) elements))
+     @result{} (a list of 5 elements)
+@end group
+@end example
+
+@findex ,@@ @{(with Backquote)}
+@cindex splicing (with backquote)
+You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @code{,@@}.  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 @code{`} is often unreadable.
+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
+(` (1 (,@@ some-list) 4 (,@@ some-list)))
+     @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
+(` (use the words (,@@ (cdr list)) as elements))
+     @result{} (use the words foo bar as elements)
+@end group
+@end example
+
+Emacs 18 had a bug which made the previous example fail.  The bug
+affected @code{,@@} followed only by constant elements.  If you are
+concerned with Emacs 18 compatibility, you can work around the bug like
+this:
+
+@example
+(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)}))
+@end example
+
+@noindent
+@code{(,@@ nil)} avoids the problem by being a nonconstant element that
+does not affect the result.
+
+@defmac ` list
+This macro quotes @var{list} except for any sublists of the form
+@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}.  Backquote
+replaces these sublists with the value of @var{subexp} (as a single
+element) or @var{listexp} (by splicing).  Backquote copies the structure
+of @var{list} down to the places where variable parts are substituted.
+
+@ignore  @c these work now!
+There are certain contexts in which @samp{,} would not be recognized and
+should not be used:
+
+@smallexample
+@group
+;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.}
+(` (a . (, 1)))                             ; @r{Not @code{(a . 1)}}
+     @result{} (a \, 1)                                
+@end group
+
+@group
+;; @r{Use of @samp{,} in a vector.}
+(` [a (, 1) c])                             ; @r{Not @code{[a 1 c]}}
+     @error{} Wrong type argument                      
+@end group
+@end smallexample
+@end ignore
+@end defmac
+
+@cindex CL note---@samp{,}, @samp{,@@} as functions
+@quotation
+@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are implemented
+as reader macros, so they do not require parentheses.  Emacs Lisp implements
+them as functions because reader macros are not supported (to save space).
+@end quotation
+
+@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
+* 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
+
+@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))
+    (princ (format "%d      %d" i square))
+    (inc i)))
+@end group
+@group
+
+     @print{}1       1
+     @print{}2       4
+     @print{}3       9
+@result{} nil
+@end group
+@end smallexample
+
+@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
+will write noise words (such as @code{from}, @code{to}, and @code{do})
+in those positions in the macro call.)
+
+This macro suffers 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.
+
+@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
+
+Here is a macro definition that creates this expansion: 
+
+@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 (((, var) (, init))
+           (max (, final)))
+       (while (<= (, var) max)
+         (,@@ body)
+         (inc (, var))))))
+@end group
+@end smallexample
+
+  Unfortunately, this introduces another problem.
+@ifinfo
+Proceed to the following node.
+@end ifinfo
+
+@node Surprising Local Vars
+@subsection Local Variables in Macro Expansions
+
+@ifinfo
+  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
+  (` (let (((, var) (, init))
+           (max (, final)))
+       (while (<= (, var) max)
+         (,@@ body)
+         (inc (, var))))))
+@end group
+@end smallexample
+@end ifinfo
+
+  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:
+
+@example
+@group
+(let ((max 0))
+  (for x from 0 to 10 do
+    (let ((this (frob x)))
+      (if (< max this)
+          (setq max this)))))
+@end group
+@end example
+
+@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
+bound and referred to just like any other symbol, but since it is created
+by @code{for}, we know that it cannot 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} which works this way:
+
+@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")))
+    (` (let (((, var) (, init))
+             ((, tempvar) (, final)))
+         (while (<= (, var) (, tempvar))
+                (,@@ body)
+                (inc (, var)))))))
+@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
+
+  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))
+     @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}.
+
+  Another reason not to call @code{eval} in a macro definition is that
+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.
+
+  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
+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.
+
+  In particular, constructing objects is a kind of side effect.  If the
+macro is called once, then the objects are constructed only once.  In
+other words, the same structure of objects is used each time the macro
+call is executed.  In interpreted operation, the macro is reexpanded
+each time, producing a fresh collection of objects each time.  Usually
+this does not matter---the objects have the same contents whether they
+are shared or not.  But if the surrounding program does side effects
+on the objects, it makes a difference whether they are shared.  Here is
+an example:
+
+@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.