Commit 03988c98 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 98366438
......@@ -208,7 +208,7 @@ keymaps.texi
lists.texi cyd
loading.texi
locals.texi
macros.texi
macros.texi cyd
maps.texi
markers.texi
minibuf.texi
......
2012-02-05 Chong Yidong <cyd@gnu.org>
* customize.texi (Common Keywords): Minor clarifications.
Document custom-unlispify-remove-prefixes.
(Variable Definitions): Backquotes in defcustom seem to work fine
now. Various other copyedits.
* eval.texi (Backquote): Move from macros.texi.
* 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.
2012-02-05 Glenn Morris <rgm@gnu.org>
* debugging.texi (Error Debugging): Mention debug-on-event default.
......
......@@ -24,9 +24,10 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
@section Common Item Keywords
@cindex customization keywords
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
This section describes some keywords that apply to all kinds.
The customization declarations that we will describe in the next few
sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
arguments for specifying various information. This section describes
keywords that apply to all types of customization declarations.
All of these keywords, except @code{:tag}, can be used more than once
in a given item. Each use of the keyword has an independent effect.
......@@ -108,8 +109,7 @@ You can specify the text to use in the customization buffer by adding
for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
the Emacs manual which appears in the buffer as @samp{foo}.
An item can have more than one external link; however, most items have
none at all.
You can use this keyword more than once, to add multiple links.
@item :load @var{file}
@kindex load@r{, customization keyword}
......@@ -136,14 +136,13 @@ version. The value @var{version} must be a string.
@kindex package-version@r{, customization keyword}
This keyword specifies that the item was first introduced in
@var{package} version @var{version}, or that its meaning or default
value was changed in that version. The value of @var{package} is a
symbol and @var{version} is a string.
value was changed in that version. This keyword takes priority over
@code{:version}.
This keyword takes priority over @code{:version}.
@var{package} should be the official name of the package, such as MH-E
or Gnus. If the package @var{package} is released as part of Emacs,
@var{package} and @var{version} should appear in the value of
@var{package} should be the official name of the package, as a symbol
(e.g.@: @code{MH-E}). @var{version} should be a string. If the
package @var{package} is released as part of Emacs, @var{package} and
@var{version} should appear in the value of
@code{customize-package-emacs-version-alist}.
@end table
......@@ -226,41 +225,31 @@ also use this keyword in @code{defgroup}:
@table @code
@item :prefix @var{prefix}
@kindex prefix@r{, @code{defgroup} keyword}
If the name of an item in the group starts with @var{prefix}, then the
tag for that item is constructed (by default) by omitting @var{prefix}.
One group can have any number of prefixes.
If the name of an item in the group starts with @var{prefix}, and the
customizable variable @code{custom-unlispify-remove-prefixes} is
non-@code{nil}, the item's tag will omit @var{prefix}. A group can
have any number of prefixes.
@end table
@end defmac
The prefix-discarding feature is currently turned off, which means
that @code{:prefix} currently has no effect. We did this because we
found that discarding the specified prefixes often led to confusing
names for options. This happened because the people who wrote the
@code{defgroup} definitions for various groups added @code{:prefix}
keywords whenever they make logical sense---that is, whenever the
variables in the library have a common prefix.
In order to obtain good results with @code{:prefix}, it would be
necessary to check the specific effects of discarding a particular
prefix, given the specific items in a group and their names and
documentation. If the resulting text is not clear, then @code{:prefix}
should not be used in that case.
@defopt custom-unlispify-remove-prefixes
If this variable is non-@code{nil}, the prefixes specified by a
group's @code{:prefix} keyword are omitted from tag names, whenever
the user customizes the group.
It should be possible to recheck all the customization groups, delete
the @code{:prefix} specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.
The default value is @code{nil}, i.e.@: the prefix-discarding feature
is disabled. This is because discarding prefixes often leads to
confusing names for options and faces.
@end defopt
@node Variable Definitions
@section Defining Customization Variables
@cindex define customization options
@cindex customization variables, how to define
Use @code{defcustom} to declare user-customizable variables.
@defmac defcustom option standard doc [keyword value]@dots{}
This macro declares @var{option} as a customizable @dfn{user option}.
You should not quote @var{option}.
This macro declares @var{option} as a user option (i.e.@: a
customizable variable). You should not quote @var{option}.
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
......@@ -275,31 +264,25 @@ cases applies, @code{defcustom} installs the result of evaluating
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
standard value. So be sure to use an expression which is harmless to
evaluate at any time. We recommend avoiding backquotes in
@var{standard}, because they are not expanded when editing the value,
so list values will appear to have the wrong structure.
evaluate at any time.
The argument @var{doc} specifies the documentation string for the
variable.
Every @code{defcustom} should specify @code{:group} at least once.
If you specify the @code{:set} keyword, to make the variable take other
special actions when set through the customization buffer, the
variable's documentation string should tell the user specifically how
to do the same job in hand-written Lisp code.
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
mode (@code{eval-defun}), a special feature of @code{eval-defun}
arranges to set the variable unconditionally, without testing whether
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
If you put a @code{defcustom} in a file that is preloaded at dump time
(@pxref{Building Emacs}), and the standard value installed for the
variable at that time might not be correct, use
If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
(@pxref{Building Emacs}), the standard value installed at dump time
might be incorrect, e.g.@: because another variable that it depends on
has not been assigned the right value yet. In that case, use
@code{custom-reevaluate-setting}, described below, to re-evaluate the
standard value during or after Emacs startup.
standard value after Emacs starts up.
@end defmac
@code{defcustom} accepts the following additional keywords:
......@@ -330,6 +313,9 @@ the value properly for this option (which may not mean simply setting
the option as a Lisp variable). The default for @var{setfunction} is
@code{set-default}.
If you specify this keyword, the variable's documentation string
should describe how to do the same job in hand-written Lisp code.
@item :get @var{getfunction}
@kindex get@r{, @code{defcustom} keyword}
Specify @var{getfunction} as the way to extract the value of this
......@@ -341,7 +327,7 @@ value). The default is @code{default-value}.
You have to really understand the workings of Custom to use
@code{:get} correctly. It is meant for values that are treated in
Custom as variables but are not actually stored in Lisp variables. It
is almost surely a mistake to specify @code{getfunction} for a value
is almost surely a mistake to specify @var{getfunction} for a value
that really is stored in a Lisp variable.
@item :initialize @var{function}
......@@ -380,16 +366,15 @@ already set or has been customized; otherwise, just use
These functions behave like @code{custom-initialize-set}
(@code{custom-initialize-default}, respectively), but catch errors.
If an error occurs during initialization, they set the variable to
@code{nil} using @code{set-default}, and throw no error.
These two functions are only meant for options defined in pre-loaded
files, where some variables or functions used to compute the option's
value may not yet be defined. The option normally gets updated in
@file{startup.el}, ignoring the previously computed value. Because of
this typical usage, the value which these two functions compute
normally only matters when, after startup, one unsets the option's
value and then reevaluates the defcustom. By that time, the necessary
variables and functions will be defined, so there will not be an error.
@code{nil} using @code{set-default}, and signal no error.
These functions are meant for options defined in pre-loaded files,
where the @var{standard} expression may signal an error because some
required variable or function is not yet defined. The value normally
gets updated in @file{startup.el}, ignoring the value computed by
@code{defcustom}. After startup, if one unsets the value and
reevaluates the @code{defcustom}, the @var{standard} expression can be
evaluated without error.
@end table
@item :risky @var{value}
......@@ -457,18 +442,16 @@ is an expression that evaluates to the value.
@defun custom-reevaluate-setting symbol
This function re-evaluates the standard value of @var{symbol}, which
should be a user option declared via @code{defcustom}. (If the
should be a user option declared via @code{defcustom}. If the
variable was customized, this function re-evaluates the saved value
instead.) This is useful for customizable options that are defined
before their value could be computed correctly, such as variables
defined in packages that are loaded at dump time, but depend on the
run-time information. For example, the value could be a file whose
precise name depends on the hierarchy of files when Emacs runs, or a
name of a program that needs to be searched at run time.
A good place to put calls to this function is in the function
@code{command-line} that is run during startup (@pxref{Startup Summary})
or in the various hooks it calls.
instead. Then it sets the user option to that value (using the
option's @code{:set} property if that is defined).
This is useful for customizable options that are defined before their
value could be computed correctly. For example, during startup Emacs
calls this function for some user options that were defined in
pre-loaded Emacs Lisp files, but whose initial values depend on
information available only at run-time.
@end defun
@defun custom-variable-p arg
......
......@@ -374,6 +374,7 @@ Evaluation
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in
the program).
* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
Kinds of Forms
......@@ -482,7 +483,6 @@ Macros
* 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.
......
......@@ -23,6 +23,7 @@ function @code{eval}.
* Intro Eval:: Evaluation in the scheme of things.
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in the program).
* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
@end menu
......@@ -579,6 +580,96 @@ Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
@node Backquote
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
@findex `
@dfn{Backquote constructs} allow 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}
@iftex
@end iftex
@ifnottex
(described in the previous section; @pxref{Quoting}).
@end ifnottex
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. The Emacs Lisp evaluator
evaluates the argument of @samp{,}, and puts the value in the list
structure:
@example
@group
`(a list of ,(+ 2 3) elements)
@result{} (a list of 5 elements)
@end group
@end example
@noindent
Substitution with @samp{,} is allowed at deeper levels of the list
structure also. For example:
@example
@group
`(1 2 (3 ,(+ 4 5)))
@result{} (1 2 (3 9))
@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 Eval
@section Eval
......
......@@ -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
......
......@@ -390,6 +390,7 @@ Evaluation
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in
the program).
* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
Kinds of Forms
......@@ -501,7 +502,6 @@ Macros
* 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.
......
......@@ -389,6 +389,7 @@ Evaluation
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in
the program).
* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
Kinds of Forms
......@@ -500,7 +501,6 @@ Macros
* 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.
......
2012-02-05 Chong Yidong <cyd@gnu.org>
* custom.el (defcustom): Doc fix.
2012-02-05 Glenn Morris <rgm@gnu.org>
* font-lock.el (lisp-font-lock-keywords-2): Add with-wrapper-hook.
......
......@@ -229,6 +229,9 @@ The following keywords are meaningful:
VALUE should be a feature symbol. If you save a value
for this option, then when your `.emacs' file loads the value,
it does (require VALUE) first.
:set-after VARIABLES
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
:risky Set SYMBOL's `risky-local-variable' property to VALUE.
:safe Set SYMBOL's `safe-local-variable' property to VALUE.
See Info node `(elisp) File Local Variables'.
......@@ -300,9 +303,6 @@ The following common keywords are also meaningful.
Load file FILE (a string) before displaying this customization
item. Loading is done with `load', and only if the file is
not already loaded.
:set-after VARIABLES
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
If SYMBOL has a local binding, then this form affects the local
binding. This is normally not what you want. Thus, if you need
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment