[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/macros.texi [gnus-5_10-branch]
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/macros.texi [gnus-5_10-branch] |
Date: |
Sat, 04 Sep 2004 08:21:24 -0400 |
Index: emacs/lispref/macros.texi
diff -c /dev/null emacs/lispref/macros.texi:1.16.2.1
*** /dev/null Sat Sep 4 12:02:44 2004
--- emacs/lispref/macros.texi Sat Sep 4 12:01:14 2004
***************
*** 0 ****
--- 1,755 ----
+ @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
+
+ @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.
+ * Indenting Macros:: Specifying how to indent macro calls.
+ @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 @var{var} is the
+ symbol @address@hidden 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}.
+
+ @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)) ; @address@hidden 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
+
+ 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
+ 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
+ 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}).
+
+ @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 functionals 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 address@hidden
+ @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
+
+ (Note that the @sc{cdr} of this list is a function---a lambda expression.)
+ 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
+
+ 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.
+
+ @defmac declare @address@hidden
+ @anchor{Definition of declare}
+ 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 (debug @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 `
+
+ Macros often need to construct large list structures from a mixture of
+ constants and nonconstant parts. To make this easier, use the @samp{`}
+ syntax (usually 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
+ '(a list of (+ 2 3) elements)
+ @result{} (a list of (+ 2 3) elements)
+ @end group
+ @end example
+
+ @findex , @r{(with Backquote)}
+ The special marker @samp{,} inside of the argument to backquote
+ indicates a value that isn't constant. Backquote evaluates the
+ argument of @samp{,} 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
+
+ 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:
+
+ @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
+
+ 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.
+
+ This syntax is still accepted, for compatibility with old Emacs
+ versions, but we recommend not using it in new programs.
+
+ @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
+ * Wrong Time:: Do the work in the expansion, not in the macro.
+ * 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 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)
+ (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.
+
+ @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.
+
+ 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))."
+ `(let ((,var ,init))
+ (while (<= ,var ,final)
+ ,@@body
+ (inc ,var))))
+ @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.
+
+ @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 fix introduces another problem,
+ described in the following section.
+
+ @node Surprising Local Vars
+ @subsection Local Variables in Macro Expansions
+
+ @ifnottex
+ 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 ifnottex
+
+ 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:
+
+ @smallexample
+ @group
+ (let ((max 0))
+ (for x from 0 to 10 do
+ (let ((this (frob x)))
+ (if (< max this)
+ (setq max this)))))
+ @end group
+ @end smallexample
+
+ @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 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:
+
+ @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 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))
+ @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 problem with calling @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.
+
+ To avoid these problems, @strong{don't evaluate an argument expression
+ while computing the macro expansion}. Instead, substitute the
+ 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.
+
+ @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.
+
+ 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:
+
+ @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.
+
+ @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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/macros.texi [gnus-5_10-branch],
Miles Bader <=