@end group
@end example
-@findex , @{(with Backquote)}
-The special marker, @code{,}, inside of the argument to backquote,
+@findex , @r{(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:
@end group
@end example
-@findex ,@@ @{(with Backquote)}
+@findex ,@@ @r{(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
@end group
@end example
-Emacs 18 had a bug which made the previous example fail. The bug
+Emacs 18 had a bug that 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:
@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).
+@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are
+implemented as reader macros, so they do not require parentheses. In
+Emacs Lisp they use function call syntax because reader macros are not
+supported (for simplicity's sake).
@end quotation
@node Problems with Macros
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.
+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
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:
+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
a function name. @xref{Symbol Components}.
The Lisp objects that constitute a Lisp program determine the textual
-form of the program--it is simply the read syntax for those Lisp
+form of the program---it is simply the read syntax for those Lisp
objects. This is why, for example, a variable in a textual Lisp program
is written using the read syntax for the symbol that represents the
variable.
local bindings.
@defspec let (bindings@dots{}) forms@dots{}
-This function binds variables according to @var{bindings} and then
+This special form binds variables according to @var{bindings} and then
evaluates all of the @var{forms} in textual order. The @code{let}-form
returns the value of the last form in @var{forms}.
@end example
@end defspec
- Here is a complete list of the other facilities which create local
+ Here is a complete list of the other facilities that create local
bindings:
@itemize @bullet
@node Defining Variables
@section Defining Global Variables
+@cindex variable definition
You may announce your intention to use a symbol as a global variable
-with a definition, using @code{defconst} or @code{defvar}.
+with a @dfn{variable definition}: a special form, either @code{defconst}
+or @code{defvar}.
In Emacs Lisp, definitions serve three purposes. First, they inform
people who read the code that certain symbols are @emph{intended} to be
a matter of intent, serving to inform human readers of whether programs
will change the variable. Emacs Lisp does not restrict the ways in
which a variable can be used based on @code{defconst} or @code{defvar}
-declarations. However, it also makes a difference for initialization:
+declarations. However, it does make a difference for initialization:
@code{defconst} unconditionally initializes the variable, while
@code{defvar} initializes it only if it is void.
@defun user-variable-p variable
@cindex user option
-This function returns @code{t} if @var{variable} is a user option--- a
+This function returns @code{t} if @var{variable} is a user option---a
variable intended to be set by the user for customization---and
@code{nil} otherwise. (Variables other than user options exist for the
internal purposes of Lisp programs, and users need not know about them.)
@var{symbol} is evaluated to obtain the symbol to set.
The most-local existing binding of the variable is the binding that is
-set; shadowed bindings are not affected. If @var{symbol} is not
-actually a symbol, a @code{wrong-type-argument} error is signaled.
+set; shadowed bindings are not affected.
@example
@group
@end group
@end example
+If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
+error is signaled.
+
+@example
+(set '(x y) 'z)
+@error{} Wrong type argument: symbolp, (x y)
+@end example
+
Logically speaking, @code{set} is a more fundamental primitive than
@code{setq}. Any use of @code{setq} can be trivially rewritten to use
@code{set}; @code{setq} could even be defined as a macro, given the
availability of @code{set}. However, @code{set} itself is rarely used;
-beginners hardly need to know about it. It is needed for choosing which
-variable to set is made at run time. For example, the command
+beginners hardly need to know about it. It is useful only for choosing
+at run time which variable to set. For example, the command
@code{set-variable}, which reads a variable name from the user and then
sets the variable, needs to use @code{set}.
@cindex CL note---@code{set} local
@quotation
-@b{Common Lisp note:} in Common Lisp, @code{set} always changes the
+@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
symbol's special value, ignoring any lexical bindings. In Emacs Lisp,
all variables and all bindings are (in effect) special, so @code{set}
always affects the most local existing binding.
@cindex CL note---special variables
@quotation
@b{Common Lisp note:} variables declared ``special'' in Common Lisp
-are dynamically scoped like variables in Emacs Lisp.
+are dynamically scoped, like variables in Emacs Lisp.
@end quotation
@menu
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
-value when you visit the file. @xref{Auto Major Mode}.
+values when you visit the file. @xref{Auto Major Mode}.
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
create a local binding for it.
@code{kill-local-variable} returns @var{variable}.
+
+This function is a command because it is sometimes useful to kill one
+buffer-local variable interactively, just as it is useful to create
+buffer-local variables interactively.
@end deffn
@defun kill-all-local-variables
buffer has a buffer-local binding. For example, you could use
@code{setq-default} to change the default setting of
@code{paragraph-start} for most buffers; and this would work even when
-you are in a C or Lisp mode buffer which has a buffer-local value for
+you are in a C or Lisp mode buffer that has a buffer-local value for
this variable.
@c Emacs 19 feature
@end defun
@c Emacs 19 feature
-@defun default-boundp variable
-The function @code{default-boundp} tells you whether @var{variable}'s
+@defun default-boundp symbol
+The function @code{default-boundp} tells you whether @var{symbol}'s
default value is nonvoid. If @code{(default-boundp 'foo)} returns
@code{nil}, then @code{(default-value 'foo)} would get an error.