diff options
| -rw-r--r-- | lispref/macros.texi | 51 | ||||
| -rw-r--r-- | lispref/variables.texi | 45 |
2 files changed, 63 insertions, 33 deletions
diff --git a/lispref/macros.texi b/lispref/macros.texi index 49d2d8e639d..13e85568eaf 100644 --- a/lispref/macros.texi +++ b/lispref/macros.texi @@ -224,8 +224,8 @@ two forms yield identical results: @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: @@ -240,7 +240,7 @@ 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 @@ -278,7 +278,7 @@ Here are some examples: @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: @@ -320,9 +320,10 @@ should not be used: @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 @@ -389,11 +390,26 @@ For example, (for i from 1 to 10 do (print i))." 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 @@ -475,11 +491,12 @@ 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: +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 diff --git a/lispref/variables.texi b/lispref/variables.texi index 2b12607d488..ffee1a39c45 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -20,7 +20,7 @@ symbol. The use of a symbol as a variable is independent of its use as 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. @@ -166,7 +166,7 @@ binding. 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}. @@ -217,7 +217,7 @@ form. Compare the following example with the example above for @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 @@ -365,9 +365,11 @@ more precisely, if its current binding is not void. It returns @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 @@ -381,7 +383,7 @@ variables in a program. 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. @@ -518,7 +520,7 @@ pi @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.) @@ -647,8 +649,7 @@ This function sets @var{symbol}'s value to @var{value}, then returns @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 @@ -681,18 +682,26 @@ one @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. @@ -726,7 +735,7 @@ located textually within the function or block that binds the variable. @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 @@ -1012,7 +1021,7 @@ But @code{save-excursion} as shown here avoids the problem: 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 @@ -1116,6 +1125,10 @@ buffer. However, if you set the variable again, that will once again 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 @@ -1156,7 +1169,7 @@ change a variable's default value regardless of whether the current 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 @@ -1172,8 +1185,8 @@ variable. If @var{symbol} is not buffer-local, this is equivalent to @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. |