Mercurial > hg > xemacs-beta

comparison man/lispref/variables.texi @ 4905:755ae5b97edb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Change "special form" to "special operator" in our sources. Add a compatible function alias, and the relevant manual index entries. src/ChangeLog addition: 2010-01-31 Aidan Kehoe <kehoea@parhasard.net> * symbols.c (Fspecial_operator_p, syms_of_symbols): * eval.c (print_subr, Finteractive_p, Ffuncall) (Ffunction_min_args, Ffunction_max_args, vars_of_eval): * editfns.c: * data.c (Fsubr_max_args): * doc.c (Fbuilt_in_symbol_file): Change "special form" to "special operator" in our sources. man/ChangeLog addition: 2010-01-31 Aidan Kehoe <kehoea@parhasard.net> * xemacs/programs.texi (Defuns): * lispref/variables.texi (Local Variables, Defining Variables) (Setting Variables, Default Value): * lispref/symbols.texi (Definitions): * lispref/searching.texi (Saving Match Data): * lispref/positions.texi (Excursions, Narrowing): * lispref/objects.texi (Primitive Function Type): * lispref/macros.texi (Defining Macros, Backquote): * lispref/lispref.texi (Top): * lispref/intro.texi (A Sample Function Description): * lispref/help.texi (Help Functions): * lispref/functions.texi (What Is a Function, Simple Lambda) (Defining Functions, Calling Functions, Anonymous Functions): * lispref/frames.texi (Input Focus): * lispref/eval.texi (Forms, Function Indirection) (Special Operators, Quoting): * lispref/edebug-inc.texi (Instrumenting) (Specification Examples): * lispref/debugging.texi (Internals of Debugger): * lispref/control.texi (Control Structures, Sequencing): (Conditionals, Combining Conditions, Iteration): (Catch and Throw, Handling Errors): * lispref/commands.texi (Defining Commands, Using Interactive): Terminology change; special operator -> special form. Don't attempt to change this in texinfo.texi or cl.texi, which use macros I don't understand. * lispref/macros.texi (Defining Macros): Give an anonymous macro example here. * lispref/positions.texi (Excursions): Correct some documentation that called a couple of macros special forms. * lispref/searching.texi (Saving Match Data): Drop some documentation of how to write code that works with Emacs 18. * lispref/specifiers.texi (Adding Specifications): Correct this; #'let-specifier is a macro, not a special operator. * lispref/windows.texi (Window Configurations) (Selecting Windows): Correct this, #'save-selected-window and #'save-window-excursion are macros, not special operators. lisp/ChangeLog addition: 2010-01-31 Aidan Kehoe <kehoea@parhasard.net> * obsolete.el: * loadhist.el (symbol-file): * help.el (describe-function-1): * bytecomp.el: (byte-compile-save-current-buffer): * byte-optimize.el (byte-optimize-form-code-walker): * subr.el (subr-arity): Change "special form" to "special operator" in these files, it's the more logical term. * subr.el (special-form-p): Provide this alias for #'special-operator-p.
author Aidan Kehoe <kehoea@parhasard.net>
date Sun, 31 Jan 2010 20:28:01 +0000
parents 57db42ba54fb
children 62b9ef1ed4ac
comparison
equal deleted inserted replaced
4904:e91e3e353805 4905:755ae5b97edb
126 These values are called @dfn{local}, and the variables so used are 126 These values are called @dfn{local}, and the variables so used are
127 called @dfn{local variables}. 127 called @dfn{local variables}.
128 128
129 For example, when a function is called, its argument variables receive 129 For example, when a function is called, its argument variables receive
130 new local values that last until the function exits. The @code{let} 130 new local values that last until the function exits. The @code{let}
131 special form explicitly establishes new local values for specified 131 special operator explicitly establishes new local values for specified
132 variables; these last until exit from the @code{let} form. 132 variables; these last until exit from the @code{let} form.
133 133
134 @cindex shadowing of variables 134 @cindex shadowing of variables
135 Establishing a local value saves away the previous value (or lack of 135 Establishing a local value saves away the previous value (or lack of
136 one) of the variable. When the life span of the local value is over, 136 one) of the variable. When the life span of the local value is over,
142 this replaces the local value; it does not alter the global value, or 142 this replaces the local value; it does not alter the global value, or
143 previous local values that are shadowed. To model this behavior, we 143 previous local values that are shadowed. To model this behavior, we
144 speak of a @dfn{local binding} of the variable as well as a local value. 144 speak of a @dfn{local binding} of the variable as well as a local value.
145 145
146 The local binding is a conceptual place that holds a local value. 146 The local binding is a conceptual place that holds a local value.
147 Entry to a function, or a special form such as @code{let}, creates the 147 Entry to a function, or a special operator such as @code{let}, creates the
148 local binding; exit from the function or from the @code{let} removes the 148 local binding; exit from the function or from the @code{let} removes the
149 local binding. As long as the local binding lasts, the variable's value 149 local binding. As long as the local binding lasts, the variable's value
150 is stored within it. Use of @code{setq} or @code{set} while there is a 150 is stored within it. Use of @code{setq} or @code{set} while there is a
151 local binding stores a different value into the local binding; it does 151 local binding stores a different value into the local binding; it does
152 not create a new binding. 152 not create a new binding.
163 the variable's global binding is its current binding. We also call the 163 the variable's global binding is its current binding. We also call the
164 current binding the @dfn{most-local existing binding}, for emphasis. 164 current binding the @dfn{most-local existing binding}, for emphasis.
165 Ordinary evaluation of a symbol always returns the value of its current 165 Ordinary evaluation of a symbol always returns the value of its current
166 binding. 166 binding.
167 167
168 The special forms @code{let} and @code{let*} exist to create 168 The special operators @code{let} and @code{let*} exist to create
169 local bindings. 169 local bindings.
170 170
171 @defspec let (bindings@dots{}) forms@dots{} 171 @defspec let (bindings@dots{}) forms@dots{}
172 This special form binds variables according to @var{bindings} and then 172 This special operator binds variables according to @var{bindings} and then
173 evaluates all of the @var{forms} in textual order. The @code{let}-form 173 evaluates all of the @var{forms} in textual order. The @code{let}-form
174 returns the value of the last form in @var{forms}. 174 returns the value of the last form in @var{forms}.
175 175
176 Each of the @var{bindings} is either @w{(i) a} symbol, in which case 176 Each of the @var{bindings} is either @w{(i) a} symbol, in which case
177 that symbol is bound to @code{nil}; or @w{(ii) a} list of the form 177 that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
197 @end group 197 @end group
198 @end example 198 @end example
199 @end defspec 199 @end defspec
200 200
201 @defspec let* (bindings@dots{}) forms@dots{} 201 @defspec let* (bindings@dots{}) forms@dots{}
202 This special form is like @code{let}, but it binds each variable right 202 This special operator is like @code{let}, but it binds each variable right
203 after computing its local value, before computing the local value for 203 after computing its local value, before computing the local value for
204 the next variable. Therefore, an expression in @var{bindings} can 204 the next variable. Therefore, an expression in @var{bindings} can
205 reasonably refer to the preceding symbols bound in this @code{let*} 205 reasonably refer to the preceding symbols bound in this @code{let*}
206 form. Compare the following example with the example above for 206 form. Compare the following example with the example above for
207 @code{let}. 207 @code{let}.
374 @node Defining Variables 374 @node Defining Variables
375 @section Defining Global Variables 375 @section Defining Global Variables
376 @cindex variable definition 376 @cindex variable definition
377 377
378 You may announce your intention to use a symbol as a global variable 378 You may announce your intention to use a symbol as a global variable
379 with a @dfn{variable definition}: a special form, either @code{defconst} 379 with a @dfn{variable definition}: a special operator, either @code{defconst}
380 or @code{defvar}. 380 or @code{defvar}.
381 381
382 In XEmacs Lisp, definitions serve three purposes. First, they inform 382 In XEmacs Lisp, definitions serve three purposes. First, they inform
383 people who read the code that certain symbols are @emph{intended} to be 383 people who read the code that certain symbols are @emph{intended} to be
384 used a certain way (as variables). Second, they inform the Lisp system 384 used a certain way (as variables). Second, they inform the Lisp system
402 loaded. Users would like to be able to set user options in their init 402 loaded. Users would like to be able to set user options in their init
403 files, and override the default values given in the definitions. For 403 files, and override the default values given in the definitions. For
404 this reason, user options must be defined with @code{defvar}. 404 this reason, user options must be defined with @code{defvar}.
405 405
406 @defspec defvar symbol [value [doc-string]] 406 @defspec defvar symbol [value [doc-string]]
407 This special form defines @var{symbol} as a value and initializes it. 407 This special operator defines @var{symbol} as a value and initializes it.
408 The definition informs a person reading your code that @var{symbol} is 408 The definition informs a person reading your code that @var{symbol} is
409 used as a variable that programs are likely to set or change. It is 409 used as a variable that programs are likely to set or change. It is
410 also used for all user option variables except in the preloaded parts of 410 also used for all user option variables except in the preloaded parts of
411 XEmacs. Note that @var{symbol} is not evaluated; the symbol to be 411 XEmacs. Note that @var{symbol} is not evaluated; the symbol to be
412 defined must appear explicitly in the @code{defvar}. 412 defined must appear explicitly in the @code{defvar}.
473 bar 473 bar
474 @result{} 23 474 @result{} 23
475 @end group 475 @end group
476 @end example 476 @end example
477 477
478 Here is an equivalent expression for the @code{defvar} special form: 478 Here is an equivalent expression for the @code{defvar} special operator:
479 479
480 @example 480 @example
481 @group 481 @group
482 (defvar @var{symbol} @var{value} @var{doc-string}) 482 (defvar @var{symbol} @var{value} @var{doc-string})
483 @equiv{} 483 @equiv{}
492 The @code{defvar} form returns @var{symbol}, but it is normally used 492 The @code{defvar} form returns @var{symbol}, but it is normally used
493 at top level in a file where its value does not matter. 493 at top level in a file where its value does not matter.
494 @end defspec 494 @end defspec
495 495
496 @defspec defconst symbol [value [doc-string]] 496 @defspec defconst symbol [value [doc-string]]
497 This special form defines @var{symbol} as a value and initializes it. 497 This special operator defines @var{symbol} as a value and initializes it.
498 It informs a person reading your code that @var{symbol} has a global 498 It informs a person reading your code that @var{symbol} has a global
499 value, established here, that will not normally be changed or locally 499 value, established here, that will not normally be changed or locally
500 bound by the execution of the program. The user, however, may be 500 bound by the execution of the program. The user, however, may be
501 welcome to change it. Note that @var{symbol} is not evaluated; the 501 welcome to change it. Note that @var{symbol} is not evaluated; the
502 symbol to be defined must appear explicitly in the @code{defconst}. 502 symbol to be defined must appear explicitly in the @code{defconst}.
551 the argument to @code{interactive}. 551 the argument to @code{interactive}.
552 552
553 @strong{Warning:} If the @code{defconst} and @code{defvar} special 553 @strong{Warning:} If the @code{defconst} and @code{defvar} special
554 forms are used while the variable has a local binding, they set the 554 forms are used while the variable has a local binding, they set the
555 local binding's value; the global binding is not changed. This is not 555 local binding's value; the global binding is not changed. This is not
556 what we really want. To prevent it, use these special forms at top 556 what we really want. To prevent it, use these special operators at top
557 level in a file, where normally no local binding is in effect, and make 557 level in a file, where normally no local binding is in effect, and make
558 sure to load the file before making a local binding for the variable. 558 sure to load the file before making a local binding for the variable.
559 559
560 @node Accessing Variables 560 @node Accessing Variables
561 @section Accessing Variable Values 561 @section Accessing Variable Values
614 The usual way to change the value of a variable is with the special 614 The usual way to change the value of a variable is with the special
615 form @code{setq}. When you need to compute the choice of variable at 615 form @code{setq}. When you need to compute the choice of variable at
616 run time, use the function @code{set}. 616 run time, use the function @code{set}.
617 617
618 @defspec setq [symbol form]@dots{} 618 @defspec setq [symbol form]@dots{}
619 This special form is the most common method of changing a variable's 619 This special operator is the most common method of changing a variable's
620 value. Each @var{symbol} is given a new value, which is the result of 620 value. Each @var{symbol} is given a new value, which is the result of
621 evaluating the corresponding @var{form}. The most-local existing 621 evaluating the corresponding @var{form}. The most-local existing
622 binding of the symbol is changed. 622 binding of the symbol is changed.
623 623
624 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you 624 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
1230 @code{paragraph-start} for most buffers; and this would work even when 1230 @code{paragraph-start} for most buffers; and this would work even when
1231 you are in a C or Lisp mode buffer that has a buffer-local value for 1231 you are in a C or Lisp mode buffer that has a buffer-local value for
1232 this variable. 1232 this variable.
1233 1233
1234 @c Emacs 19 feature 1234 @c Emacs 19 feature
1235 The special forms @code{defvar} and @code{defconst} also set the 1235 The special operators @code{defvar} and @code{defconst} also set the
1236 default value (if they set the variable at all), rather than any local 1236 default value (if they set the variable at all), rather than any local
1237 value. 1237 value.
1238 1238
1239 @defun default-value symbol 1239 @defun default-value symbol
1240 This function returns @var{symbol}'s default value. This is the value 1240 This function returns @var{symbol}'s default value. This is the value