diff options
author | Chong Yidong <cyd@gnu.org> | 2012-02-05 14:44:47 +0800 |
---|---|---|
committer | Chong Yidong <cyd@gnu.org> | 2012-02-05 14:44:47 +0800 |
commit | 03988c98dfbb4506ada95f52e4a34071627c3b49 (patch) | |
tree | a4c4d5fcbf9fa063519f5b688de89c2c1e3cadda /doc/lispref/macros.texi | |
parent | 98366438c7163579bfc47b0d2eabe875081d51b6 (diff) | |
download | emacs-03988c98dfbb4506ada95f52e4a34071627c3b49.tar.gz |
Updates to Macros and Customization chapters of Lisp manual.
* doc/lispref/customize.texi (Common Keywords): Minor clarifications.
Document custom-unlispify-remove-prefixes.
(Variable Definitions): Backquotes in defcustom seem to work fine
now. Various other copyedits.
* doc/lispref/macros.texi (Expansion): Minor clarification.
(Backquote): Move node to eval.texi.
(Defining Macros): Move an example from Backquote node.
(Argument Evaluation): No need to mention Pascal.
(Indenting Macros): Add xref to Defining Macros.
* doc/lispref/eval.texi (Backquote): Move from macros.texi.
* lisp/custom.el (defcustom): Doc fix.
Diffstat (limited to 'doc/lispref/macros.texi')
-rw-r--r-- | doc/lispref/macros.texi | 142 |
1 files changed, 32 insertions, 110 deletions
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 3804d963108..dca88d2b7c7 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -27,7 +27,6 @@ instead. @xref{Inline Functions}. * 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. @@ -78,10 +77,9 @@ 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 + The second crucial difference between macros and functions is that +the value returned by the macro body is an alternate Lisp expression, +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. @@ -221,7 +219,26 @@ 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, + Macros often need to construct large list structures from a mixture +of constants and nonconstant parts. To make this easier, use the +@samp{`} syntax (@pxref{Backquote}). For example: + +@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 +@end example + + The body of a 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. @@ -259,107 +276,11 @@ without evaluating any @var{specs}. has no effect on how the macro expands, on what the macro means in the program. It only affects the secondary features listed above. -@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 - @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 + Macro expansion can have counterintuitive consequences. This +section describes some important consequences that can lead to trouble, and rules to follow to avoid trouble. @menu @@ -407,9 +328,8 @@ program is actually run. 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. +following macro (used to facilitate iteration) illustrates the +problem. This macro allows us to write a ``for'' loop construct. @findex for @smallexample @@ -683,9 +603,9 @@ 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 calls to the macro. You -write it like this: + Within a macro definition, you can use the @code{declare} form +(@pxref{Defining Macros}) to specify how to @key{TAB} should indent +calls to the macro. An indentation specifiction is written like this: @example (declare (indent @var{indent-spec})) @@ -715,6 +635,7 @@ the line uses the standard pattern. @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 @@ -723,6 +644,7 @@ 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 |