diff options
Diffstat (limited to 'doc/lispref')
38 files changed, 2577 insertions, 2343 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 4b9531c0e6c..d8e322790e7 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,321 @@ +2012-02-10 Leo Liu <sdl.web@gmail.com> + + * control.texi (Handling Errors): Change condition-case-no-debug + to condition-case-unless-debug. + +2012-02-10 Chong Yidong <cyd@gnu.org> + + * advice.texi (Defining Advice): Clarify ad-unadvise. + (Activation of Advice): Specifying the ACTIVATE flag in defadvice + is not abnormal. + (Advising Primitives): Node deleted; ad-define-subr-args has been + removed. + + * compile.texi (Speed of Byte-Code): Use float-time in example. + (Compilation Functions): Note that the log uses Compilation mode. + Don't discuss the contents of byte-code function object here. + (Compilation Functions): De-document internal function byte-code. + (Docs and Compilation): Minor clarifications. + + * objects.texi (Byte-Code Type): Add xref to Byte-Code Function + Objects. + +2012-02-10 Glenn Morris <rgm@gnu.org> + + * text.texi (Checksum/Hash): Rename node from MD5 Checksum. + Mention secure-hash. + * elisp.texi, vol1.texi, vol2.texi: Update menu entry. + +2012-02-10 Chong Yidong <cyd@gnu.org> + + * loading.texi (Loading): Don't emphasize "library" terminology. + (Library Search): load-path is not a user option. Mention role of + -L option and packages. Improve examples. + (Loading Non-ASCII): Don't mention unibyte Emacs, which is + obsolete. + (Autoload): Minor clarifications. + +2012-02-10 Glenn Morris <rgm@gnu.org> + + * files.texi (Magic File Names): Tweak remote-file-name-inhibit-cache. + + * modes.texi (Basic Major Modes): Mention tabulated-list-mode. + +2012-02-08 Glenn Morris <rgm@gnu.org> + + * loading.texi (Named Features): Update the require example. + +2012-02-07 Glenn Morris <rgm@gnu.org> + + * modes.texi (Defining Minor Modes): + Expand on args of defined minor modes. + +2012-02-07 Chong Yidong <cyd@gnu.org> + + * variables.texi (Creating Buffer-Local): Minor clarification + to buffer-local-variables doc (Bug#10715). + +2012-02-07 Glenn Morris <rgm@gnu.org> + + * display.texi (ImageMagick Images): General update. + Move most details of imagemagick-render-type to the variable's doc. + +2012-02-06 Glenn Morris <rgm@gnu.org> + + * keymaps.texi (Tool Bar): Mention separators. + (Inheritance and Keymaps): + Mention make-composed-keymap and multiple inheritance. + + * modes.texi (Running Hooks): Mention run-hook-wrapped. + + * control.texi (Handling Errors): + Mention condition-case-no-debug and with-demoted-errors. + +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. + (Simple Types): Copyedits. Document color selector. + (Composite Types): Copyedits. + (Splicing into Lists): Clarifications. + + * 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. + +2012-02-04 Glenn Morris <rgm@gnu.org> + + * backups.texi (Reverting): Mention revert-buffer-in-progress-p. + + * debugging.texi (Error Debugging): Mention debug-on-event. + * commands.texi (Misc Events): Mention sigusr1,2 and debugging. + + * modes.texi (Running Hooks): Try to clarify with-wrapper-hook. + + * text.texi (Buffer Contents): + Update filter-buffer-substring description. + +2012-02-04 Chong Yidong <cyd@gnu.org> + + * functions.texi (What Is a Function): Add closures. Mention + "return value" terminology. Add xref for command-execute. Remove + unused "keystroke command" terminology. + (Lambda Expressions): Give a different example than in the + following subsection. Add xref to Anonymous Functions. + (Function Documentation): Remove gratuitous markup. + (Function Names): Move introductory text to `What Is a Function'. + (Defining Functions): Fix defun argument spec. + (Anonymous Functions): Document lambda macro explicitly. Mention + effects on lexical binding. + (Function Cells): Downplay direct usage of fset. + (Closures): New node. + (Inline Functions): Remove "open-code" terminology. + (Declaring Functions): Minor tweak; .m is not C code. + + * variables.texi (Variables): Don't refer to "global value". + (Local Variables, Void Variables): Copyedits. + (Lexical Binding): Minor clarification of example. + (File Local Variables): Mention :safe and :risky defcustom args. + (Lexical Binding): Add xref to Closures node. + +2012-02-04 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (High-Level Completion): Updates for read-color. + +2012-02-03 Glenn Morris <rgm@gnu.org> + + * display.texi (GIF Images): Mention animation. + Remove commented-out old example of animation. + (Animated Images): New subsection. + * elisp.texi (Top): + * vol1.texi (Top): + * vol2.texi (Top): Add Animated Images menu entry. + + * display.texi (Image Formats): Remove oddly specific information + on versions of image libraries. + (GIF Images, TIFF Images): Minor rephrasing. + +2012-02-02 Glenn Morris <rgm@gnu.org> + + * processes.texi (Synchronous Processes): + Mention call-process's :file gets overwritten. + + * commands.texi (Reading One Event): + * help.texi (Help Functions): Document read-char-choice. + + * hooks.texi (Standard Hooks): + * modes.texi (Keymaps and Minor Modes): + * text.texi (Commands for Insertion): Document post-self-insert-hook. + + * hooks.texi (Standard Hooks): Add prog-mode-hook. + + * hooks.texi (Standard Hooks): + * modes.texi (Major Mode Conventions, Mode Hooks): + Document change-major-mode-after-body-hook. + +2012-02-01 Glenn Morris <rgm@gnu.org> + + * modes.texi (Defining Minor Modes): + Mention disabling global minor modes on a per-major-mode basis. + +2012-01-31 Chong Yidong <cyd@gnu.org> + + * syntax.texi (Parsing Expressions): Clarify intro (Bug#10657). + (Parser State): Remove unnecessary statement (Bug#10661). + + * eval.texi (Intro Eval): Add footnote about "sexp" terminology. + +2012-01-31 Glenn Morris <rgm@gnu.org> + + * modes.texi (Defining Minor Modes): + Document define-minor-mode's new :variable keyword. + +2012-01-29 Chong Yidong <cyd@gnu.org> + + * syntax.texi (Syntax Class Table): Tweak description of newline + char syntax (Bug#9619). + + * numbers.texi (Predicates on Numbers): Fix wholenump/natnump + description (Bug#10189). + +2012-01-29 Glenn Morris <rgm@gnu.org> + + * files.texi (Changing Files): Document SELinux support. + + * windows.texi (Window Sizes): Fix typo. + +2012-01-28 Chong Yidong <cyd@gnu.org> + + * display.texi (Fringe Indicators): Clarify fringe-indicator-alist + doc (Bug#8568). + + * frames.texi (Input Focus): Add NORECORD arg to + select-frame-set-input-focus. Clarify its role in select-frame. + + * text.texi (Transposition): We don't use transpose-region as an + internal subroutine (Bug#3249). + + * modes.texi (Example Major Modes): Update Lisp example code to + current sources. Delete the old non-derived-major-mode example, + which has diverged badly from current sources. + +2012-01-27 Glenn Morris <rgm@gnu.org> + + * makefile.w32-in (texinputdir): Fix (presumed) typo. + (VERSION, manual): Remove, unused. + +2012-01-27 Chong Yidong <cyd@gnu.org> + + * commands.texi (Command Overview): Minor clarification (Bug#10384). + +2012-01-26 Chong Yidong <cyd@gnu.org> + + * searching.texi (String Search): Document negative repeat count + (Bug#10507). + +2012-01-26 Glenn Morris <rgm@gnu.org> + + * variables.texi (Using Lexical Binding): + Mention that lexical-binding should be set in the first line. + +2012-01-26 Lars Ingebrigtsen <larsi@gnus.org> + + * macros.texi (Defining Macros): Don't claim that `declare' only + affects Edebug and indentation. + +2012-01-25 Lars Ingebrigtsen <larsi@gnus.org> + + * macros.texi (Defining Macros): Slight `declare' fixup. + +2012-01-25 Glenn Morris <rgm@gnu.org> + + * makefile.w32-in (texinputdir): + * Makefile.in (ENVADD): Add $emacsdir. (Bug#10603) + +2012-01-24 Chong Yidong <cyd@gnu.org> + + * variables.texi (Variables, Local Variables, Void Variables): + Edit to make the descriptions less specific to dynamic binding. + (Local Variables): Default max-specpdl-size is now 1300. + (Defining Variables): Edits for lexical scoping. Delete + information about starting docstrings with *. De-document + user-variable-p. + (Tips for Defining): Remove an unimportant discussion of quitting + in the middle of a load. + (Accessing Variables, Setting Variables): Discuss lexical binding. + (Variable Scoping): Rewrite. + (Scope, Extent, Impl of Scope): Nodes deleted. + (Dynamic Binding): New node, with material from Scope, Extent, and + Impl of Scope nodes. + (Dynamic Binding Tips): Rename from Using Scoping. + (Lexical Binding): Rewrite. + (Using Lexical Binding): Rename from Converting to Lexical + Binding. Convert to subsection. + + * customize.texi (Variable Definitions): Add custom-variable-p. + Move user-variable-p documentation here. + +2012-01-23 Chong Yidong <cyd@gnu.org> + + * strings.texi (Text Comparison): Minor qualification. + + * lists.texi (Cons Cells): Copyedits. + (List Elements): Mention push. + (List Variables): Mention pop. + (Rings): Move to sequences.texi. + + * sequences.texi (Sequence Functions): Don't repeat the + introduction already given in the parent. + (Vectors): Copyedits. + (Rings): Move from lists.texi. Note that this is specific to the + ring package. + + * symbols.texi (Definitions, Symbol Components): Mention variable + scoping issues. + (Plists and Alists): Copyedits. + + * eval.texi (Intro Eval, Symbol Forms): Minor tweaks for + correctness with lexical scoping. + (Eval): Copyedits. + +2012-01-21 Chong Yidong <cyd@gnu.org> + + * intro.texi (A Sample Function Description): Special notation + used for macros too. + + * objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits. + (Symbol Type): Add xref for keyword symbols. + (Sequence Type): Clarify differences between sequence types. + (Cons Cell Type): Add "linked list" index entry. + (Non-ASCII in Strings): Copyedits. + (Equality Predicates): Symbols with same name need not be eq. + + * numbers.texi (Float Basics): Document isnan, copysign, frexp and + ldexp. Move float-e and float-pi to Math Functions node. + +2012-01-21 Glenn Morris <rgm@gnu.org> + + * modes.texi (Auto Major Mode): + * variables.texi (File Local Variables): + Mention inhibit-local-variables-regexps. + +2012-01-19 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Window Configurations): Rewrite references to + persistent window parameters. + (Window Parameters): Fix description of persistent window + parameters. + 2012-01-16 Juanma Barranquero <lekktu@gmail.com> * windows.texi (Window Parameters): Use @pxref. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 0b616884ff2..4128eb06d7f 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -36,7 +36,7 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ +ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" # List of all the texinfo files in the manual: diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi index ee1950a589a..78b4ac9aa2d 100644 --- a/doc/lispref/advice.texi +++ b/doc/lispref/advice.texi @@ -13,30 +13,35 @@ for a library to customize functions defined within Emacs---cleaner than redefining the whole function. @cindex piece of advice - Each function can have multiple @dfn{pieces of advice}, separately -defined. Each defined piece of advice can be @dfn{enabled} or -@dfn{disabled} explicitly. All the enabled pieces of advice for any given -function actually take effect when you @dfn{activate} advice for that + Each function can have multiple @dfn{pieces of advice}, each of +which can be separately defined and then @dfn{enabled} or +@dfn{disabled}. All the enabled pieces of advice for any given +function actually take effect when you @dfn{activate advice} for that function, or when you define or redefine the function. Note that -enabling a piece of advice and activating advice for a function -are not the same thing. - - @strong{Usage Note:} Advice is useful for altering the behavior of -existing calls to an existing function. If you want the new behavior -for new calls, or for key bindings, you should define a new function -(or a new command) which uses the existing function. - - @strong{Usage note:} Advising a function can cause confusion in -debugging, since people who debug calls to the original function may -not notice that it has been modified with advice. Therefore, if you -have the possibility to change the code of that function (or ask -someone to do so) to run a hook, please solve the problem that way. -Advice should be reserved for the cases where you cannot get the -function changed. - - In particular, this means that a file in Emacs should not put advice -on a function in Emacs. There are currently a few exceptions to this -convention, but we aim to correct them. +enabling a piece of advice and activating advice for a function are +not the same thing. + + Advice is useful for altering the behavior of existing calls to an +existing function. If you want the new behavior for new function +calls or new key bindings, you should define a new function or +command, and have it use the existing function as a subroutine. + + Advising a function can cause confusion in debugging, since people +who debug calls to the original function may not notice that it has +been modified with advice. Therefore, if you have the possibility to +change the code of that function to run a hook, please solve the +problem that way. Advice should be reserved for the cases where you +cannot get the function changed. In particular, Emacs' own source +files should not put advice on functions in Emacs. There are +currently a few exceptions to this convention, but we aim to correct +them. + + Unless you know what you are doing, do @emph{not} advise a primitive +(@pxref{What Is a Function}). Some primitives are used by the advice +mechanism; advising them could cause an infinite recursion. Also, +many primitives are called directly from C code. Calls to the +primitive from Lisp code will take note of the advice, but calls from +C code will ignore the advice. @menu * Simple Advice:: A simple example to explain the basics of advice. @@ -48,7 +53,6 @@ convention, but we aim to correct them. * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. @end menu @@ -258,7 +262,7 @@ All subroutines used by the advice need to be available when the byte compiler expands the macro. @deffn Command ad-unadvise function -This command deletes the advice from @var{function}. +This command deletes all pieces of advice from @var{function}. @end deffn @deffn Command ad-unadvise-all @@ -355,13 +359,13 @@ replaced with the new one. @cindex advice, activating By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function that was advised. However, -the advice will be activated automatically if you define or redefine -the function later. You can request the activation of advice for a -function when you define the advice, by specifying the @code{activate} -flag in the @code{defadvice}. But normally you activate the advice -for a function by calling the function @code{ad-activate} or one of -the other activation commands listed below. +you @dfn{activate} advice for the function. However, the advice will +be activated automatically if you define or redefine the function +later. You can request the activation of advice for a function when +you define the advice, by specifying the @code{activate} flag in the +@code{defadvice}; or you can activate the advice separately by calling +the function @code{ad-activate} or one of the other activation +commands listed below. Separating the activation of advice from the act of defining it permits you to add several pieces of advice to one function efficiently, without @@ -680,39 +684,6 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of These argument constructs are not really implemented as Lisp macros. Instead they are implemented specially by the advice mechanism. -@node Advising Primitives -@section Advising Primitives -@cindex advising primitives - - Advising a primitive function (@pxref{What Is a Function}) is risky. -Some primitive functions are used by the advice mechanism; advising -them could cause an infinite recursion. Also, many primitive -functions are called directly from C code. Calls to the primitive -from Lisp code will take note of the advice, but calls from C code -will ignore the advice. - -When the advice facility constructs the combined definition, it needs -to know the argument list of the original function. This is not -always possible for primitive functions. When advice cannot determine -the argument list, it uses @code{(&rest ad-subr-args)}, which always -works but is inefficient because it constructs a list of the argument -values. You can use @code{ad-define-subr-args} to declare the proper -argument names for a primitive function: - -@defun ad-define-subr-args function arglist -This function specifies that @var{arglist} should be used as the -argument list for function @var{function}. -@end defun - -For example, - -@example -(ad-define-subr-args 'fset '(sym newdef)) -@end example - -@noindent -specifies the argument list for the function @code{fset}. - @node Combined Definition @section The Combined Definition diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 969220845d0..a4b3a0b9bef 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -696,6 +696,9 @@ operation, reverting preserves all the markers. If they are not identical, reverting does change the buffer; in that case, it preserves the markers in the unchanged text (if any) at the beginning and end of the buffer. Preserving any additional markers would be problematical. + +This command binds @code{revert-buffer-in-progress-p} to a +non-@code{nil} value while it operates. @end deffn You can customize how @code{revert-buffer} does its work by setting diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 4a0bc8a6b24..91e224a439f 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -75,18 +75,22 @@ function yourself (@pxref{Keyboard Macros}). character causes @dfn{quitting} (@pxref{Quitting}). @defvar pre-command-hook -The editor command loop runs this normal hook before each command. At -that time, @code{this-command} contains the command that is about to -run, and @code{last-command} describes the previous command. -@xref{Command Loop Info}. +This normal hook is run by the editor command loop before it executes +each command. At that time, @code{this-command} contains the command +that is about to run, and @code{last-command} describes the previous +command. @xref{Command Loop Info}. @end defvar @defvar post-command-hook -The editor command loop runs this normal hook after each command -(including commands terminated prematurely by quitting or by errors), -and also when the command loop is first entered. At that time, -@code{this-command} refers to the command that just ran, and -@code{last-command} refers to the command before that. +This normal hook is run by the editor command loop after it executes +each command (including commands terminated prematurely by quitting or +by errors). At that time, @code{this-command} refers to the command +that just ran, and @code{last-command} refers to the command before +that. + +This hook is also run when Emacs first enters the command loop (at +which point @code{this-command} and @code{last-command} are both +@code{nil}). @end defvar Quitting is suppressed while running @code{pre-command-hook} and @@ -1692,6 +1696,7 @@ parameters are used to display the help-echo text are described in These events are generated when the Emacs process receives the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data because signals do not carry additional information. +They can be useful for debugging (@pxref{Error Debugging}). To catch a user signal, bind the corresponding event to an interactive command in the @code{special-event-map} (@pxref{Active Keymaps}). @@ -2468,6 +2473,17 @@ The argument @var{prompt} is either a string to be displayed in the echo area as a prompt, or @code{nil}, meaning not to display a prompt. @end defun +@defun read-char-choice prompt chars &optional inhibit-quit +This function uses @code{read-key} to read and return a single +character. It ignores any input that is not a member of @var{chars}, +a list of accepted characters. Optionally, it will also ignore +keyboard-quit events while it is waiting for valid input. If you bind +@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value +while calling @code{read-char-choice}, then pressing @code{help-char} +causes it to evaluate @code{help-form} and display the result. It +then continues to wait for a valid input character, or keyboard-quit. +@end defun + @node Event Mod @subsection Modifying and Translating Input Events diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 4e21df78430..545f05d9d57 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -32,9 +32,6 @@ variable binding for @code{no-byte-compile} into it, like this: ;; -*-no-byte-compile: t; -*- @end example - @xref{Compilation Errors}, for how to investigate errors occurring in -byte compilation. - @menu * Speed of Byte-Code:: An example of speedup from byte compilation. * Compilation Functions:: Byte compilation functions. @@ -56,18 +53,16 @@ Here is an example: @example @group (defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) + "Return the time, in seconds, to run N iterations of a loop." + (let ((t1 (float-time))) + (while (> (setq n (1- n)) 0)) + (- (float-time) t1))) @result{} silly-loop @end group @group (silly-loop 50000000) -@result{} ("Wed Mar 11 21:10:19 2009" - "Wed Mar 11 21:10:41 2009") ; @r{22 seconds} +@result{} 10.235304117202759 @end group @group @@ -77,18 +72,17 @@ Here is an example: @group (silly-loop 50000000) -@result{} ("Wed Mar 11 21:12:26 2009" - "Wed Mar 11 21:12:32 2009") ; @r{6 seconds} +@result{} 3.705854892730713 @end group @end example - In this example, the interpreted code required 22 seconds to run, -whereas the byte-compiled code required 6 seconds. These results are -representative, but actual results will vary greatly. + In this example, the interpreted code required 10 seconds to run, +whereas the byte-compiled code required less than 4 seconds. These +results are representative, but actual results may vary. @node Compilation Functions @comment node-name, next, previous, up -@section The Compilation Functions +@section Byte-Compilation Functions @cindex compilation functions You can byte-compile an individual function or macro definition with @@ -96,43 +90,36 @@ the @code{byte-compile} function. You can compile a whole file with @code{byte-compile-file}, or several files with @code{byte-recompile-directory} or @code{batch-byte-compile}. - The byte compiler produces error messages and warnings about each file -in a buffer called @samp{*Compile-Log*}. These report things in your -program that suggest a problem but are not necessarily erroneous. + Sometimes, the byte compiler produces warning and/or error messages +(@pxref{Compiler Errors}, for details). These messages are recorded +in a buffer called @samp{*Compile-Log*}, which uses Compilation mode. +@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}. @cindex macro compilation - Be careful when writing macro calls in files that you may someday -byte-compile. Macro calls are expanded when they are compiled, so the -macros must already be defined for proper compilation. For more -details, see @ref{Compiling Macros}. If a program does not work the -same way when compiled as it does when interpreted, erroneous macro -definitions are one likely cause (@pxref{Problems with Macros}). -Inline (@code{defsubst}) functions are less troublesome; if you + Be careful when writing macro calls in files that you intend to +byte-compile. Since macro calls are expanded when they are compiled, +the macros need to be loaded into Emacs or the byte compiler will not +do the right thing. The usual way to handle this is with +@code{require} forms which specify the files containing the needed +macro definitions (@pxref{Named Features}). Normally, the +byte compiler does not evaluate the code that it is compiling, but it +handles @code{require} forms specially, by loading the specified +libraries. To avoid loading the macro definition files when someone +@emph{runs} the compiled program, write @code{eval-when-compile} +around the @code{require} calls (@pxref{Eval During Compile}). For +more details, @xref{Compiling Macros}. + + Inline (@code{defsubst}) functions are less troublesome; if you compile a call to such a function before its definition is known, the call will still work right, it will just run slower. - Normally, compiling a file does not evaluate the file's contents or -load the file. But it does execute any @code{require} calls at top -level in the file. One way to ensure that necessary macro definitions -are available during compilation is to require the file that defines -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - @defun byte-compile symbol This function byte-compiles the function definition of @var{symbol}, replacing the previous definition with the compiled one. The function definition of @var{symbol} must be the actual code for the function; -i.e., the compiler does not follow indirection to another symbol. -@code{byte-compile} returns the new, compiled definition of -@var{symbol}. - - If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. Lisp records -only one function definition for any symbol, and if that is already -compiled, non-compiled code is not available anywhere. So there is no -way to ``compile the same definition again.'' +@code{byte-compile} does not handle function indirection. The return +value is the byte-code function object which is the compiled +definition of @var{symbol} (@pxref{Byte-Code Objects}). @example @group @@ -153,16 +140,15 @@ way to ``compile the same definition again.'' @end group @end example -@noindent -The result is a byte-code function object. The string it contains is -the actual byte-code; each character in it is an instruction or an -operand of an instruction. The vector contains all the constants, -variable names and function names used by the function, except for -certain primitives that are coded as special instructions. - -If the argument to @code{byte-compile} is a @code{lambda} expression, -it returns the corresponding compiled code, but does not store -it anywhere. +If @var{symbol}'s definition is a byte-code function object, +@code{byte-compile} does nothing and returns @code{nil}. It does not +``compile the symbol's definition again'', since the original +(non-compiled) code has already been replaced in the symbol's function +cell by the byte-compiled code. + +The argument to @code{byte-compile} can also be a @code{lambda} +expression. In that case, the function returns the corresponding +compiled code but does not store it anywhere. @end defun @deffn Command compile-defun &optional arg @@ -252,19 +238,6 @@ files that have an up-to-date @samp{.elc} file. @end example @end defun -@defun byte-code code-string data-vector max-stack -@cindex byte-code interpreter -This function actually interprets byte-code. A byte-compiled function -is actually defined with a body that calls @code{byte-code}. Don't call -this function yourself---only the byte compiler knows how to generate -valid calls to this function. - -In Emacs version 18, byte-code was always executed by way of a call to -the function @code{byte-code}. Nowadays, byte-code is usually executed -as part of a byte-code function object, and only rarely through an -explicit call to @code{byte-code}. -@end defun - @node Docs and Compilation @section Documentation Strings and Compilation @cindex dynamic loading of documentation @@ -290,33 +263,11 @@ then further access to documentation strings in this file will probably give nonsense results. @end itemize - If your site installs Emacs following the usual procedures, these -problems will never normally occur. Installing a new version uses a new -directory with a different name; as long as the old version remains -installed, its files will remain unmodified in the places where they are -expected to be. - - However, if you have built Emacs yourself and use it from the -directory where you built it, you will experience this problem -occasionally if you edit and recompile Lisp files. When it happens, you -can cure the problem by reloading the file after recompiling it. - - You can turn off this feature at compile time by setting -@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful -mainly if you expect to change the file, and you want Emacs processes -that have already loaded it to keep working when the file changes. -You can do this globally, or for one source file by specifying a -file-local binding for the variable. One way to do that is by adding -this string to the file's first line: - -@example --*-byte-compile-dynamic-docstrings: nil;-*- -@end example - -@defvar byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. -@end defvar +@noindent +These problems normally occur only if you build Emacs yourself and use +it from the directory where you built it, and you happen to edit +and/or recompile the Lisp source files. They can be easily cured by +reloading each file after recompiling it. @cindex @samp{#@@@var{count}} @cindex @samp{#$} @@ -328,6 +279,23 @@ string.'' It is usually best not to use these constructs in Lisp source files, since they are not designed to be clear to humans reading the file. + You can disable the dynamic documentation string feature at compile +time by setting @code{byte-compile-dynamic-docstrings} to @code{nil}; +this is useful mainly if you expect to change the file, and you want +Emacs processes that have already loaded it to keep working when the +file changes. You can do this globally, or for one source file by +specifying a file-local binding for the variable. One way to do that +is by adding this string to the file's first line: + +@example +-*-byte-compile-dynamic-docstrings: nil;-*- +@end example + +@defvar byte-compile-dynamic-docstrings +If this is non-@code{nil}, the byte compiler generates compiled files +that are set up for dynamic loading of documentation strings. +@end defvar + @node Dynamic Loading @section Dynamic Loading of Individual Functions @@ -541,17 +509,16 @@ one you intend to suppress. @cindex byte-code function Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. +@dfn{byte-code function objects}. Whenever such an object appears as +a function to be called, Emacs uses the byte-code interpreter to +execute the byte-code. - Internally, a byte-code function object is much like a vector; -however, the evaluator handles this data type specially when it appears -as a function to be called. The printed representation for a byte-code -function object is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. - - A byte-code function object must have at least four elements; there is -no maximum number, but only the first six elements have any normal use. -They are: + Internally, a byte-code function object is much like a vector; its +elements can be accessed using @code{aref}. Its printed +representation is like that for a vector, with an additional @samp{#} +before the opening @samp{[}. It must have at least four elements; +there is no maximum number, but only the first six elements have any +normal use. They are: @table @var @item arglist @@ -588,7 +555,7 @@ representation. It is the definition of the command [arg 1 forward-sexp] 2 254435 - "p"] + "^p"] @end example The primitive way to create a byte-code object is with @@ -604,10 +571,6 @@ function yourself, because if they are inconsistent, Emacs may crash when you call the function. Always leave it to the byte compiler to create these objects; it makes the elements consistent (we hope). - You can access the elements of a byte-code object using @code{aref}; -you can also use @code{vconcat} to create a vector with the same -elements. - @node Disassembly @section Disassembled Byte-Code @cindex disassembled byte-code diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index e74f3e198bf..c23c93300a6 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -8,11 +8,11 @@ @cindex special forms for control structures @cindex control structures - A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). -We control the order of execution of these forms by enclosing them in -@dfn{control structures}. Control structures are special forms which -control when, whether, or how many times to execute the forms they -contain. + A Lisp program consists of a set of @dfn{expressions}, or +@dfn{forms} (@pxref{Forms}). We control the order of execution of +these forms by enclosing them in @dfn{control structures}. Control +structures are special forms which control when, whether, or how many +times to execute the forms they contain. @cindex textual order The simplest order of execution is sequential execution: first form @@ -891,9 +891,8 @@ establishing an error handler, with the special form @noindent This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs@footnote{ -Actually, you should use @code{ignore-errors} in such a simple case; -see below.}. +returning @code{nil} if an error occurs. (You can use the macro +@code{ignore-errors} for a simple case like this; see below.) The @code{condition-case} construct is often used to trap errors that are predictable, such as failure to open a file in a call to @@ -949,6 +948,13 @@ The effect of @code{debug} here is only to prevent given error will invoke the debugger only if @code{debug-on-error} and the other usual filtering mechanisms say it should. @xref{Error Debugging}. +@defmac condition-case-unless-debug var protected-form handlers@dots{} +The macro @code{condition-case-unless-debug} provides another way to +handle debugging of such forms. It behaves exactly like +@code{condition-case}, unless the variable @code{debug-on-error} is +non-@code{nil}, in which case it does not handle any errors at all. +@end defmac + Once Emacs decides that a certain handler handles the error, it returns control to that handler. To do so, Emacs unbinds all variable bindings made by binding constructs that are being exited, and @@ -1122,6 +1128,13 @@ Here's the example at the beginning of this subsection rewritten using @end smallexample @end defmac +@defmac with-demoted-errors body@dots{} +This macro is like a milder version of @code{ignore-errors}. Rather +than suppressing errors altogether, it converts them into messages. +Use this form around code that is not expected to signal errors, but +should be robust if one does occur. Note that this macro uses +@code{condition-case-unless-debug} rather than @code{condition-case}. +@end defmac @node Error Symbols @subsubsection Error Symbols and Condition Names diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index f8495513be4..4c3adee0db5 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -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,47 +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 causes the function @code{user-variable-p} to return @code{t} -when given @var{option} as an argument. @xref{Defining Variables}. -The argument @var{doc} specifies the documentation string for the -variable. (Note that there is no need to start @var{doc} with a -@samp{*}.) +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 @@ -281,16 +264,12 @@ 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. -Every @code{defcustom} should specify @code{:group} at least once. +The argument @var{doc} specifies the documentation string for the +variable. -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. +Every @code{defcustom} should specify @code{:group} at least once. 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} @@ -298,11 +277,12 @@ 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: @@ -333,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 @@ -344,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} @@ -383,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} @@ -460,18 +442,32 @@ 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 +This function returns non-@code{nil} if @var{arg} is a customizable +variable. A customizable variable is either a variable that has a +@code{standard-value} or @code{custom-autoload} property (usually +meaning it was declared with @code{defcustom}), or an alias for +another customizable variable. +@end defun + +@defun user-variable-p arg +This function is like @code{custom-variable-p}, except it also returns +@code{t} if the first character of the variable's documentation string +is the character @samp{*}. That is an obsolete way of indicating a +user option, so for most purposes you may consider +@code{user-variable-p} as equivalent to @code{custom-variable-p}. @end defun @node Customization Types @@ -523,30 +519,28 @@ Introduction, widget, The Emacs Widget Library}, for details. @node Simple Types @subsection Simple Types - This section describes all the simple customization types. + This section describes all the simple customization types. For +several of these customization types, the customization widget +provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}. @table @code @item sexp -The value may be any Lisp object that can be printed and read back. You -can use @code{sexp} as a fall-back for any option, if you don't want to -take the time to work out a more specific type to use. +The value may be any Lisp object that can be printed and read back. +You can use @code{sexp} as a fall-back for any option, if you don't +want to take the time to work out a more specific type to use. @item integer -The value must be an integer, and is represented textually -in the customization buffer. +The value must be an integer. @item number -The value must be a number (floating point or integer), and is -represented textually in the customization buffer. +The value must be a number (floating point or integer). @item float -The value must be a floating point number, and is represented -textually in the customization buffer. +The value must be a floating point number. @item string -The value must be a string, and the customization buffer shows just the -contents, with no delimiting @samp{"} characters and no quoting with -@samp{\}. +The value must be a string. The customization buffer shows the string +without delimiting @samp{"} characters or @samp{\} quotes. @item regexp Like @code{string} except that the string must be a valid regular @@ -558,39 +552,35 @@ integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number. @item file -The value must be a file name, and you can do completion with -@kbd{M-@key{TAB}}. +The value must be a file name. The widget provides completion. @item (file :must-match t) -The value must be a file name for an existing file, and you can do -completion with @kbd{M-@key{TAB}}. +The value must be a file name for an existing file. The widget +provides completion. @item directory -The value must be a directory name, and you can do completion with -@kbd{M-@key{TAB}}. +The value must be a directory name. The widget provides completion. @item hook -The value must be a list of functions (or a single function, but that is -obsolete usage). This customization type is used for hook variables. -You can use the @code{:options} keyword in a hook variable's -@code{defcustom} to specify a list of functions recommended for use in -the hook; see @ref{Variable Definitions}. +The value must be a list of functions. This customization type is +used for hook variables. You can use the @code{:options} keyword in a +hook variable's @code{defcustom} to specify a list of functions +recommended for use in the hook; @xref{Variable Definitions}. @item symbol The value must be a symbol. It appears in the customization buffer as -the name of the symbol. +the symbol name. The widget provides completion. @item function -The value must be either a lambda expression or a function name. When -it is a function name, you can do completion with @kbd{M-@key{TAB}}. +The value must be either a lambda expression or a function name. The +widget provides completion for function names. @item variable -The value must be a variable name, and you can do completion with -@kbd{M-@key{TAB}}. +The value must be a variable name. The widget provides completion. @item face -The value must be a symbol which is a face name, and you can do -completion with @kbd{M-@key{TAB}}. +The value must be a symbol which is a face name. The widget provides +completion. @item boolean The value is boolean---either @code{nil} or @code{t}. Note that by @@ -604,8 +594,10 @@ The value must be a coding-system name, and you can do completion with @kbd{M-@key{TAB}}. @item color -The value must be a valid color name, and you can do completion with -@kbd{M-@key{TAB}}. A sample is provided. +The value must be a valid color name. The widget provides completion +for color names, as well as a sample and a button for selecting a +color name from a list of color names shown in a @samp{*Colors*} +buffer. @end table @node Composite Types @@ -639,9 +631,8 @@ its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string symbol)} is a customization type which matches values such as @code{("foo" . foo)}. -In the customization buffer, the @sc{car} and the @sc{cdr} are -displayed and edited separately, each according to the type -that you specify for it. +In the customization buffer, the @sc{car} and @sc{cdr} are displayed +and edited separately, each according to their specified type. @item (list @var{element-types}@dots{}) The value must be a list with exactly as many elements as the @@ -684,7 +675,7 @@ specified by the @code{:options} keyword argument. The argument to the @code{:options} keywords should be a list of specifications for reasonable keys in the alist. Ordinarily, they are -simply atoms, which stand for themselves as. For example: +simply atoms, which stand for themselves. For example: @smallexample :options '("foo" "bar" "baz") @@ -757,14 +748,6 @@ key, using variations of this trick: "Alist of basic info about people. Each element has the form (NAME AGE MALE-FLAG)." :type '(alist :value-type (group integer boolean))) - -(defcustom pets '(("brian") - ("dorith" "dog" "guppy") - ("ken" "cat")) - "Alist of people's pets. -In an element (KEY . VALUE), KEY is the person's name, -and the VALUE is a list of that person's pets." - :type '(alist :value-type (repeat string))) @end smallexample @item (plist :key-type @var{key-type} :value-type @var{value-type}) @@ -774,9 +757,8 @@ that (i) the information is stored as a property list, defaults to @code{symbol} rather than @code{sexp}. @item (choice @var{alternative-types}@dots{}) -The value must fit at least one of @var{alternative-types}. -For example, @code{(choice integer string)} allows either an -integer or a string. +The value must fit one of @var{alternative-types}. For example, +@code{(choice integer string)} allows either an integer or a string. In the customization buffer, the user selects an alternative using a menu, and can then edit the value in the usual way for that @@ -968,20 +950,18 @@ whatever follows the last keyword-value pair. @subsection Splicing into Lists The @code{:inline} feature lets you splice a variable number of -elements into the middle of a list or vector. You use it in a -@code{set}, @code{choice} or @code{repeat} type which appears among the -element-types of a @code{list} or @code{vector}. - - Normally, each of the element-types in a @code{list} or @code{vector} -describes one and only one element of the list or vector. Thus, if an -element-type is a @code{repeat}, that specifies a list of unspecified -length which appears as one element. - - But when the element-type uses @code{:inline}, the value it matches is -merged directly into the containing sequence. For example, if it -matches a list with three elements, those become three elements of the -overall sequence. This is analogous to using @samp{,@@} in the backquote -construct. +elements into the middle of a @code{list} or @code{vector} +customization type. You use it by adding @code{:inline t} to a type +specification which is contained in a @code{list} or @code{vector} +specification. + + Normally, each entry in a @code{list} or @code{vector} type +specification describes a single element type. But when an entry +contains @code{:inline t}, the value it matches is merged directly +into the containing sequence. For example, if the entry matches a +list with three elements, those become three elements of the overall +sequence. This is analogous to @samp{,@@} in a backquote construct +(@pxref{Backquote}). For example, to specify a list whose first element must be @code{baz} and whose remaining arguments should be zero or more of @code{foo} and diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 9466f21a563..cc92fc225f9 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -148,6 +148,15 @@ enter the debugger. @code{debug-on-error} is @code{nil}. @end defopt +@defopt debug-on-event +If you set @code{debug-on-event} to a special event (@pxref{Special +Events}), Emacs will try to enter the debugger as soon as it receives +this event, bypassing @code{special-event-map}. At present, the only +supported values correspond to the signals @code{SIGUSR1} and +@code{SIGUSR2} (this is the default). This can be helpful when +@code{inhibit-quit} is set and Emacs is not otherwise responding. +@end defopt + To debug an error that happens during loading of the init file, use the option @samp{--debug-init}. This binds @code{debug-on-error} to @code{t} while loading the init file, and diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 381eaf66c12..d5870fd3abb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -3367,54 +3367,48 @@ fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. @defvar fringe-indicator-alist This buffer-local variable specifies the mapping from logical fringe -indicators to the actual bitmaps displayed in the window fringes. +indicators to the actual bitmaps displayed in the window fringes. The +value is an alist of elements @code{(@var{indicator} +. @var{bitmaps})}, where @var{indicator} specifies a logical indicator +type and @var{bitmaps} specifies the fringe bitmaps to use for that +indicator. -These symbols identify the logical fringe indicators: + Each @var{indicator} should be one of the following symbols: @table @asis -@item Truncation and continuation line indicators: -@code{truncation}, @code{continuation}. - -@item Buffer position indicators: -@code{up}, @code{down}, -@code{top}, @code{bottom}, -@code{top-bottom}. - -@item Empty line indicator: -@code{empty-line}. - -@item Overlay arrow indicator: -@code{overlay-arrow}. - -@item Unknown bitmap indicator: -@code{unknown}. +@item @code{truncation}, @code{continuation}. +Used for truncation and continuation lines. + +@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom} +Used to indicate buffer boundaries when +@code{indicate-buffer-boundaries} is non-@code{nil}: @code{up} and +@code{down} indicate a buffer boundary lying above or below the window +edge; @code{top} and @code{bottom} indicate the topmost and bottommost +buffer text line; and @code{top-bottom} indicates where there is just +one line of text in the buffer. + +@item @code{empty-line} +Used to indicate empty lines when @code{indicate-empty-lines} is +non-@code{nil}. + +@item @code{overlay-arrow} +Used for overlay arrows (@pxref{Overlay Arrow}). +@c Is this used anywhere? +@c @item Unknown bitmap indicator: +@c @code{unknown}. @end table - The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})} -specifies the fringe bitmaps used to display a specific logical -fringe indicator. - -Here, @var{indicator} specifies the logical indicator type, and -@var{bitmaps} is list of symbols @code{(@var{left} @var{right} -[@var{left1} @var{right1}])} which specifies the actual bitmap shown -in the left or right fringe for the logical indicator. - -The @var{left} and @var{right} symbols specify the bitmaps shown in -the left and/or right fringe for the specific indicator. The -@var{left1} or @var{right1} bitmaps are used only for the `bottom' and -`top-bottom indicators when the last (only) line in has no final -newline. Alternatively, @var{bitmaps} may be a single symbol which is -used in both left and right fringes. - -When @code{fringe-indicator-alist} has a buffer-local value, and there -is no bitmap defined for a logical indicator, or the bitmap is -@code{t}, the corresponding value from the default value of -@code{fringe-indicator-alist} is used. + Each @var{bitmaps} value may be a list of symbols @code{(@var{left} +@var{right} [@var{left1} @var{right1}])}. The @var{left} and +@var{right} symbols specify the bitmaps shown in the left and/or right +fringe, for the specific indicator. @var{left1} and @var{right1} are +specific to the @code{bottom} and @code{top-bottom} indicators, and +are used to indicate that the last text line has no final newline. +Alternatively, @var{bitmaps} may be a single symbol which is used in +both left and right fringes. -To completely hide a specific indicator, set the bitmap to @code{nil}. -@end defvar + The standard symbols for fringe bitmaps are: -Standard fringe bitmaps for indicators: @example left-arrow right-arrow up-arrow down-arrow left-curly-arrow right-curly-arrow @@ -3428,6 +3422,16 @@ vertical-bar horizontal-bar empty-line question-mark @end example +@noindent +In addition, @code{nil} represents the empty bitmap (i.e.@: an +indicator that is not shown). + + When @code{fringe-indicator-alist} has a buffer-local value, and +there is no bitmap defined for a logical indicator, or the bitmap is +@code{t}, the corresponding value from the default value of +@code{fringe-indicator-alist} is used. +@end defvar + @node Fringe Cursors @subsection Fringe Cursors @cindex fringe cursors @@ -4130,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}). * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. @end menu @@ -4147,12 +4152,10 @@ names for these dynamic libraries (though it is not possible to add new image formats). Note that image types @code{pbm} and @code{xbm} do not depend on external libraries and are always available in Emacs. - The supported image formats include XBM, XPM (this requires the -libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring -@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the -@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff} -v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring -@code{librsvg} 2.0.0). + The supported image formats (and the necessary library files) +include XBM, XPM (@code{libXpm} and @code{libz}), GIF (@code{libgif} +or @code{libungif}), PostScript, PBM, JPEG (@code{libjpeg}), TIFF +(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). You specify one of these formats with an image type symbol. The image type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, @@ -4467,33 +4470,13 @@ specifies the actual color to use for displaying that name. @table @code @item :index @var{index} -You can use @code{:index} to specify one image from a GIF file that -contains more than one image. This property specifies use of image -number @var{index} from the file. If the GIF file doesn't contain an -image with index @var{index}, the image displays as a hollow box. +You can use @code{:index} to specify image number @var{index} from a +GIF file that contains more than one image. If the GIF file doesn't +contain an image with the specified index, the image displays as a +hollow box. GIF files with more than one image can be animated, +@pxref{Animated Images}. @end table -@ignore -This could be used to implement limited support for animated GIFs. -For example, the following function displays a multi-image GIF file -at point-min in the current buffer, switching between sub-images -every 0.1 seconds. - -(defun show-anim (file max) - "Display multi-image GIF file FILE which contains MAX subimages." - (display-anim (current-buffer) file 0 max t)) - -(defun display-anim (buffer file idx max first-time) - (when (= idx max) - (setq idx 0)) - (let ((img (create-image file nil :image idx))) - (with-current-buffer buffer - (goto-char (point-min)) - (unless first-time (delete-char 1)) - (insert-image img)) - (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) -@end ignore - @node TIFF Images @subsection TIFF Images @cindex TIFF @@ -4502,10 +4485,10 @@ every 0.1 seconds. @table @code @item :index @var{index} -You can use @code{:index} to specify one image from a TIFF file that -contains more than one image. This property specifies use of image -number @var{index} from the file. If the TIFF file doesn't contain an -image with index @var{index}, the image displays as a hollow box. +You can use @code{:index} to specify image number @var{index} from a +TIFF file that contains more than one image. If the TIFF file doesn't +contain an image with the specified index, the image displays as a +hollow box. @end table @node PostScript Images @@ -4544,30 +4527,51 @@ specifying the bounding box of the PostScript image, analogous to the support, you can use the ImageMagick library to load many image formats. @findex imagemagick-types +@findex imagemagick-register-types The function @code{imagemagick-types} returns a list of image file extensions that your installation of ImageMagick supports. To enable support, you must call the function @code{imagemagick-register-types}. +This enables Emacs to visit these file types in @code{image-mode} +(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}). +If your Emacs was not compiled with ImageMagick support, then +@code{imagemagick-types} will be undefined and +@code{imagemagick-register-types} will do nothing. @vindex imagemagick-types-inhibit The variable @code{imagemagick-types-inhibit} specifies a list of -image types that you do @emph{not} want ImageMagick to handle. There -may be overlap between image loaders in your Emacs installation, and -you may prefer to use a different one for a given image type (which -@c FIXME how is this priority determined? -loader will be used in practice depends on the priority of the loaders). -@c FIXME why are these uppercase when image-types is lower-case? -@c FIXME what are the possible options? Are these actually file extensions? -For example, if you never want to use the ImageMagick loader to use +image types that you do @emph{not} want ImageMagick to handle. It is +a list of symbols, each of which has the same name as one of the +format tags used internally by ImageMagick (i.e., as +@code{imagemagick-types} returns). ImageMagick has a very broad +definition of what an image is, for example it includes such file +types as C files and HTML files. It is not appropriate to treat these +as images in Emacs. You can add any other ImageMagick type that you +wish to this list. +@ignore +@c I don't know what this means. I suspect it means eg loading jpg +@c images via libjpeg or ImageMagick. But it doesn't work. +@c If you don't have libjpeg support compiled in, you cannot +@c view jpeg images, even if you have imagemagick support: +@c http://debbugs.gnu.org/9045 +@c And if you have both compiled in, then you always get +@c the libjpeg version: +@c http://debbugs.gnu.org/10746 +There may be overlap between image loaders in your Emacs installation, +and you may prefer to use a different one for a given image type +(which loader will be used in practice depends on the priority of the +loaders). +For example, if you never want to use the ImageMagick loader to view JPEG files, add @code{JPG} to this list. +@end ignore +Note that ImageMagick often distinguishes between several different +types of a particular format (e.g., @code{JPG}, @code{JPEG}, +@code{PJPEG}, etc.), and you may need to add all versions to this +list. +@c Not sure this should even be in the manual at all. @vindex imagemagick-render-type -You can set the variable @code{imagemagick-render-type} to choose -between screen render methods for the ImageMagick loader. The options -are: @code{0}, a conservative method which works with older -@c FIXME details of this "newer method"? -@c Presumably it is faster but may be less "robust"? -ImageMagick versions (it is a bit slow, but robust); and @code{1}, -a newer ImageMagick method. +If you wish to experiment with the performance of the ImageMagick +loader, see the variable @code{imagemagick-render-type}. Images loaded with ImageMagick support a few new display specifications: @@ -4582,10 +4586,11 @@ aspect ratio may not be preserved. Specifies a rotation angle in degrees. @item :index -Specifies which image to view inside an image bundle file format, such -as TIFF or DJVM. You can use the @code{image-metadata} function to -retrieve the total number of images in an image bundle (this is -similar to how GIF files work). +@c Doesn't work: http://debbugs.gnu.org/7978 +This has the same meaning as it does for GIF images (@pxref{GIF Images}), +i.e. it specifies which image to view inside an image bundle file format +such as DJVM. You can use the @code{image-metadata} function to +retrieve the total number of images in an image bundle. @end table @@ -4853,6 +4858,39 @@ cache, it can always be displayed, even if the value of @var{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@node Animated Images +@subsection Animated Images + +@cindex animation +@cindex image animation +Some image files can contain more than one image. This can be used to +create animation. Currently, Emacs only supports animated GIF files. +The following functions related to animated images are available. + +@defun image-animated-p image +This function returns non-nil if @var{image} can be animated. +The actual return value is a cons @code{(@var{nimages} . @var{delay})}, +where @var{nimages} is the number of frames and @var{delay} is the +delay in seconds between them. +@end defun + +@defun image-animate image &optional index limit +This function animates @var{image}. The optional integer @var{index} +specifies the frame from which to start (default 0). The optional +argument @var{limit} controls the length of the animation. If omitted +or @code{nil}, the image animates once only; if @code{t} it loops +forever; if a number animation stops after that many seconds. +@end defun + +@noindent Animation operates by means of a timer. Note that Emacs imposes a +minimum frame delay of 0.01 seconds. + +@defun image-animate-timer image +This function returns the timer responsible for animating @var{image}, +if there is one. +@end defun + + @node Image Cache @subsection Image Cache @cindex image cache diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 0b8d972c1d5..a925f3865a4 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -326,7 +326,6 @@ Lists * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. Modifying Existing List Structure @@ -344,6 +343,7 @@ Sequences, Arrays, and Vectors * Vector Functions:: Functions specifically for vectors. * Char-Tables:: How to work with char-tables. * Bool-Vectors:: How to work with bool-vectors. +* Rings:: Managing a fixed-size ring of objects. Hash Tables @@ -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 @@ -436,12 +437,10 @@ Variables Scoping Rules for Variable Bindings -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. +* Dynamic Binding:: The default for binding local variables in Emacs. +* Dynamic Binding Tips:: Avoiding problems with dynamic binding. +* Lexical Binding:: A different type of local variable binding. +* Using Lexical Binding:: How to enable lexical binding. Buffer-Local Variables @@ -461,6 +460,7 @@ Functions * Anonymous Functions:: Lambda expressions are functions with no names. * Function Cells:: Accessing or setting the function definition of a symbol. +* Closures:: Functions that enclose a lexical environment. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Defining functions that the compiler will open code. @@ -483,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. @@ -549,7 +548,6 @@ Advising Emacs Lisp Functions * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. Debugging Lisp Programs @@ -1062,7 +1060,7 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Checksum/Hash:: Computing "message digests"/"checksums"/"hashes". * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. @@ -1353,6 +1351,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index adb4841a82d..cb3a4c54fac 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -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 @@ -39,12 +40,15 @@ interpreter. @cindex form @cindex expression - A Lisp object that is intended for evaluation is called an -@dfn{expression} or a @dfn{form}. The fact that forms are data -objects and not merely text is one of the fundamental differences -between Lisp-like languages and typical programming languages. Any -object can be evaluated, but in practice only numbers, symbols, lists -and strings are evaluated very often. +@cindex S-expression + A Lisp object that is intended for evaluation is called a @dfn{form} +or @dfn{expression}@footnote{It is sometimes also referred to as an +@dfn{S-expression} or @dfn{sexp}, but we generally do not use this +terminology in this manual.}. The fact that forms are data objects +and not merely text is one of the fundamental differences between +Lisp-like languages and typical programming languages. Any object can +be evaluated, but in practice only numbers, symbols, lists and strings +are evaluated very often. In subsequent sections, we will describe the details of what evaluation means for each kind of form. @@ -64,8 +68,8 @@ evaluate a @dfn{function call} form such as @code{(car x)}, Emacs first evaluates the argument (the subform @code{x}). After evaluating the argument, Emacs @dfn{executes} the function (@code{car}), and if the function is written in Lisp, execution works by evaluating the -@dfn{body} of the function. (In this example, however, @code{car} is -not a Lisp function; it is a primitive function implemented in C.) +@dfn{body} of the function (in this example, however, @code{car} is +not a Lisp function; it is a primitive function implemented in C). @xref{Functions}, for more information about functions and function calls. @@ -77,9 +81,8 @@ variables (@pxref{Variables}).@footnote{This definition of that can affect the result of a program.} Whenever a form refers to a variable without creating a new binding for it, the variable evaluates to the value given by the current environment. Evaluating a form may -create a new environment for recursive evaluation, by binding -variables (@pxref{Local Variables}). Such environments are temporary, -and vanish when the evaluation of the form is complete. +also temporarily alter the environment by binding variables +(@pxref{Local Variables}). @cindex side effect Evaluating a form may also make changes that persist; these changes @@ -97,12 +100,12 @@ interpretation. @xref{Command Loop}. @node Forms @section Kinds of Forms - A Lisp object that is intended to be evaluated is called a @dfn{form}. -How Emacs evaluates a form depends on its data type. Emacs has three -different kinds of form that are evaluated differently: symbols, lists, -and ``all other types.'' This section describes all three kinds, one by -one, starting with the ``all other types'' which are self-evaluating -forms. + A Lisp object that is intended to be evaluated is called a +@dfn{form} (or an @dfn{expression}). How Emacs evaluates a form +depends on its data type. Emacs has three different kinds of form +that are evaluated differently: symbols, lists, and ``all other +types.'' This section describes all three kinds, one by one, starting +with the ``all other types'' which are self-evaluating forms. @menu * Self-Evaluating Forms:: Forms that evaluate to themselves. @@ -177,9 +180,9 @@ program. Here is an example: @cindex symbol evaluation When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If it has none (if its value -cell is void), an error is signaled. For more information on the use of -variables, see @ref{Variables}. +is the variable's value, if it has one. If the symbol has no value as +a variable, the Lisp interpreter signals an error. For more +information on the use of variables, see @ref{Variables}. In the following example, we set the value of a symbol with @code{setq}. Then we evaluate the symbol, and get back the value that @@ -577,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 @@ -602,12 +695,13 @@ functions provides the ability to pass information to them as arguments. @defun eval form &optional lexical -This is the basic function evaluating an expression. It evaluates +This is the basic function for evaluating an expression. It evaluates @var{form} in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (@pxref{Forms}). -@var{lexical} if non-nil means to evaluate @var{form} using lexical scoping -rules (@pxref{Lexical Binding}) instead of the default dynamic scoping used -historically in Emacs Lisp. + +The argument @var{lexical}, if non-@code{nil}, means to evaluate +@var{form} using lexical scoping rules for variables, instead of the +default dynamic scoping rules. @xref{Lexical Binding}. Since @code{eval} is a function, the argument expression that appears in a call to @code{eval} is evaluated twice: once as preparation before diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 614bd827489..cf093ba36cb 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1480,7 +1480,7 @@ with @code{add-name-to-file} and then deleting @var{filename} has the same effect as renaming, aside from momentary intermediate states. @end deffn -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid +@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux This command copies the file @var{oldname} to @var{newname}. An error is signaled if @var{oldname} does not exist. If @var{newname} names a directory, it copies @var{oldname} into that directory, @@ -1501,6 +1501,16 @@ usually set to the user running Emacs). If @var{preserve-uid-gid} is non-@code{nil}, we attempt to copy the user and group ownership of the file. This works only on some operating systems, and only if you have the correct permissions to do so. + +@cindex SELinux +If the optional argument @var{preserve-selinux} is non-@code{nil}, we +attempt to copy the SELinux@footnote{@samp{Security-Enhanced Linux} +is a kernel feature that allows for finer access controls to be set on +files, and a system security policy to define who can access what. +The functions @code{file-selinux-context} and @code{set-file-selinux-context} +get and set, respectively, the SELinux properties of a file.} +context of the file. For this to work, Emacs must have been built +with libselinux support. @end deffn @deffn Command make-symbolic-link filename newname &optional ok-if-exists @@ -2852,24 +2862,21 @@ is a good way to come up with one. @end defun @defopt remote-file-name-inhibit-cache -Whether to use the remote file-name cache for read access. - -File attributes of remote files are cached for better performance. If -they are changed out of Emacs' control, the cached values become +The attributes of remote files can be cached for better performance. If +they are changed outside of Emacs's control, the cached values become invalid, and must be reread. -When set to @code{nil}, cached values are always used. This shall be -set with care. When set to @code{t}, cached values are never used. -ALthough this is the safest value, it could result in performance -degradation. +When this variable is set to @code{nil}, cached values are never +expired. Use this setting with caution, only if you are sure nothing +other than Emacs ever changes the remote files. If it is set to +@code{t}, cached values are never used. This is the safest value, but +could result in performance degradation. A compromise is to set it to a positive number. This means that cached values are used for that amount of seconds since they were -cached. - -In case a remote file is checked regularly, it might be reasonable to -let-bind this variable to a value less then the time period between -two checks. Example: +cached. If a remote file is checked regularly, it might be a good +idea to let-bind this variable to a value less than the time period +between consecutive checks. For example: @example (defun display-time-file-nonempty-p (file) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 4835a5b3da2..27303637e42 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1377,15 +1377,15 @@ remains selected until a subsequent call to @code{select-frame}. Each terminal frame has a number which appears in the mode line before the buffer name (@pxref{Mode Line Variables}). -@defun select-frame-set-input-focus frame +@defun select-frame-set-input-focus frame &optional norecord This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. On -a text-only terminal, the next redisplay displays the new frame on the -entire terminal screen. The return value of this function is not -significant. +obscured by other frames) and tries to give it the X server's focus. +On a text-only terminal, the next redisplay displays the new frame on +the entire terminal screen. The optional argument @var{norecord} has +the same meaning as for @code{select-frame} (see below). The return +value of this function is not significant. @end defun -@c ??? This is not yet implemented properly. @defun select-frame frame &optional norecord This function selects frame @var{frame}, temporarily disregarding the focus of the X server if any. The selection of @var{frame} lasts until @@ -1395,18 +1395,20 @@ window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may have the window system's input focus.) -The specified @var{frame} becomes the selected frame, as explained -above, and the terminal that @var{frame} is on becomes the selected -terminal. The window selected within @var{frame} becomes the selected -window. This function returns @var{frame}, or @code{nil} if @var{frame} -has been deleted. +The specified @var{frame} becomes the selected frame, and its terminal +becomes the selected terminal. This function then calls +@code{select-window} as a subroutine, passing the window selected +within @var{frame} as its first argument and @var{norecord} as its +second argument (hence, if @var{norecord} is non-@code{nil}, this +avoids changing the order of recently selected windows nor the buffer +list). @xref{Selecting Windows}. -Optional argument @var{norecord} non-@code{nil} means to neither change -the order of recently selected windows nor the buffer list. @xref{The -Buffer List}. +This function returns @var{frame}, or @code{nil} if @var{frame} has +been deleted. -In general, you should never use @code{select-frame} in a way that could -switch to a different terminal without switching back when you're done. +In general, you should never use @code{select-frame} in a way that +could switch to a different terminal without switching back when +you're done. @end defun Emacs cooperates with the window system by arranging to select frames as diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index ada00867bd0..9ee94557066 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -21,8 +21,9 @@ define them. * Anonymous Functions:: Lambda expressions are functions with no names. * Function Cells:: Accessing or setting the function definition of a symbol. +* Closures:: Functions that enclose a lexical environment. * Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler will open code. +* Inline Functions:: Functions that the compiler will expand inline. * Declaring Functions:: Telling the compiler that a function is defined. * Function Safety:: Determining whether a function is safe to call. * Related Topics:: Cross-references to specific Lisp primitives @@ -32,104 +33,117 @@ define them. @node What Is a Function @section What Is a Function? - In a general sense, a function is a rule for carrying on a computation -given several values called @dfn{arguments}. The result of the -computation is called the value of the function. The computation can -also have side effects: lasting changes in the values of variables or -the contents of data structures. - - Here are important terms for functions in Emacs Lisp and for other -function-like objects. +@cindex return value +@cindex value of function +@cindex argument + In a general sense, a function is a rule for carrying out a +computation given input values called @dfn{arguments}. The result of +the computation is called the @dfn{value} or @dfn{return value} of the +function. The computation can also have side effects, such as lasting +changes in the values of variables or the contents of data structures. + + In most computer languages, every function has a name. But in Lisp, +a function in the strictest sense has no name: it is an object which +can @emph{optionally} be associated with a symbol (e.g.@: @code{car}) +that serves as the function name. @xref{Function Names}. When a +function has been given a name, we usually also refer to that symbol +as a ``function'' (e.g.@: we refer to ``the function @code{car}''). +In this manual, the distinction between a function name and the +function object itself is usually unimportant, but we will take note +wherever it is relevant. + + Certain function-like objects, called @dfn{special forms} and +@dfn{macros}, also accept arguments to carry out computations. +However, as explained below, these are not considered functions in +Emacs Lisp. + + Here are important terms for functions and function-like objects: @table @dfn -@item function -@cindex function -In Emacs Lisp, a @dfn{function} is anything that can be applied to -arguments in a Lisp program. In some cases, we use it more -specifically to mean a function written in Lisp. Special forms and -macros are not functions. +@item lambda expression +A function (in the strict sense, i.e.@: a function object) which is +written in Lisp. These are described in the following section. +@ifnottex +@xref{Lambda Expressions}. +@end ifnottex @item primitive @cindex primitive @cindex subr @cindex built-in function -A @dfn{primitive} is a function callable from Lisp that is written in C, -such as @code{car} or @code{append}. These functions are also called -@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also -considered primitives.) - -Usually the reason we implement a function as a primitive is either -because it is fundamental, because it provides a low-level interface -to operating system services, or because it needs to run fast. -Primitives can be modified or added only by changing the C sources and -recompiling the editor. See @ref{Writing Emacs Primitives}. - -@item lambda expression -A @dfn{lambda expression} is a function written in Lisp. -These are described in the following section. -@ifnottex -@xref{Lambda Expressions}. -@end ifnottex +A function which is callable from Lisp but is actually written in C. +Primitives are also called @dfn{built-in functions}, or @dfn{subrs}. +Examples include functions like @code{car} and @code{append}. In +addition, all special forms (see below) are also considered +primitives. + +Usually, a function is implemented as a primitive because it is a +fundamental part of Lisp (e.g.@: @code{car}), or because it provides a +low-level interface to operating system services, or because it needs +to run fast. Unlike functions defined in Lisp, primitives can be +modified or added only by changing the C sources and recompiling +Emacs. See @ref{Writing Emacs Primitives}. @item special form -A @dfn{special form} is a primitive that is like a function but does not -evaluate all of its arguments in the usual way. It may evaluate only -some of the arguments, or may evaluate them in an unusual order, or -several times. Many special forms are described in @ref{Control -Structures}. +A primitive that is like a function but does not evaluate all of its +arguments in the usual way. It may evaluate only some of the +arguments, or may evaluate them in an unusual order, or several times. +Examples include @code{if}, @code{and}, and @code{while}. +@xref{Special Forms}. @item macro @cindex macro -A @dfn{macro} is a construct defined in Lisp by the programmer. It -differs from a function in that it translates a Lisp expression that you -write into an equivalent expression to be evaluated instead of the -original expression. Macros enable Lisp programmers to do the sorts of -things that special forms can do. @xref{Macros}, for how to define and -use macros. +A construct defined in Lisp, which differs from a function in that it +translates a Lisp expression into another expression which is to be +evaluated instead of the original expression. Macros enable Lisp +programmers to do the sorts of things that special forms can do. +@xref{Macros}. @item command @cindex command -A @dfn{command} is an object that @code{command-execute} can invoke; it -is a possible definition for a key sequence. Some functions are -commands; a function written in Lisp is a command if it contains an -interactive declaration (@pxref{Defining Commands}). Such a function -can be called from Lisp expressions like other functions; in this case, -the fact that the function is a command makes no difference. +An object which can be invoked via the @code{command-execute} +primitive, usually due to the user typing in a key sequence +@dfn{bound} to that command. @xref{Interactive Call}. A command is +usually a function; if the function is written in Lisp, it is made +into a command by an @code{interactive} form in the function +definition (@pxref{Defining Commands}). Commands that are functions +can also be called from Lisp expressions, just like other functions. Keyboard macros (strings and vectors) are commands also, even though -they are not functions. A symbol is a command if its function -definition is a command; such symbols can be invoked with @kbd{M-x}. -The symbol is a function as well if the definition is a function. -@xref{Interactive Call}. - -@item keystroke command -@cindex keystroke command -A @dfn{keystroke command} is a command that is bound to a key sequence -(typically one to three keystrokes). The distinction is made here -merely to avoid confusion with the meaning of ``command'' in non-Emacs -editors; for Lisp programs, the distinction is normally unimportant. +they are not functions. @xref{Keyboard Macros}. We say that a symbol +is a command if its function cell contains a command (@pxref{Symbol +Components}); such a @dfn{named command} can be invoked with +@kbd{M-x}. + +@item closure +A function object that is much like a lambda expression, except that +it also encloses an ``environment'' of lexical variable bindings. +@xref{Closures}. @item byte-code function -A @dfn{byte-code function} is a function that has been compiled by the -byte compiler. @xref{Byte-Code Type}. +A function that has been compiled by the byte compiler. +@xref{Byte-Code Type}. @item autoload object @cindex autoload object -An @dfn{autoload object} is a place-holder for a real function. If -the autoload object is called, it will make Emacs load the file -containing the definition of the real function, and then call the real -function instead. +A place-holder for a real function. If the autoload object is called, +Emacs loads the file containing the definition of the real function, +and then calls the real function. @xref{Autoload}. @end table + You can use the function @code{functionp} to test if an object is a +function: + @defun functionp object This function returns @code{t} if @var{object} is any kind of function, i.e.@: can be passed to @code{funcall}. Note that -@code{functionp} returns @code{nil} for special forms (@pxref{Special -Forms}). +@code{functionp} returns @code{t} for symbols that are function names, +and returns @code{nil} for special forms. @end defun -Unlike @code{functionp}, the next three functions do @emph{not} -treat a symbol as its function definition. +@noindent +Unlike @code{functionp}, the next three functions do @emph{not} treat +a symbol as its function definition. @defun subrp object This function returns @code{t} if @var{object} is a built-in function @@ -172,21 +186,26 @@ function with @code{&rest} arguments, or the symbol @code{unevalled} if @section Lambda Expressions @cindex lambda expression - A function written in Lisp is a list that looks like this: + A lambda expression is a function object written in Lisp. Here is +an example: @example -(lambda (@var{arg-variables}@dots{}) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-declaration}@r{]} - @var{body-forms}@dots{}) +(lambda (x) + "Return the hyperbolic cosine of X." + (* 0.5 (+ (exp x) (exp (- x))))) @end example @noindent -Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it -actually is valid as an expression---it evaluates to itself. In some -other Lisp dialects, a lambda expression is not a valid expression at -all. In either case, its main use is not to be evaluated as an -expression, but to be called as a function. +In Emacs Lisp, such a list is valid as an expression---it evaluates to +itself. But its main use is not to be evaluated as an expression, but +to be called as a function. + + A lambda expression, by itself, has no name; it is an @dfn{anonymous +function}. Although lambda expressions can be used this way +(@pxref{Anonymous Functions}), they are more commonly associated with +symbols to make @dfn{named functions} (@pxref{Function Names}). +Before going into these details, the following subsections describe +the components of a lambda expression and what they do. @menu * Lambda Components:: The parts of a lambda expression. @@ -198,10 +217,7 @@ expression, but to be called as a function. @node Lambda Components @subsection Components of a Lambda Expression -@ifnottex - - A function written in Lisp (a ``lambda expression'') is a list that -looks like this: + A lambda expression is a list that looks like this: @example (lambda (@var{arg-variables}@dots{}) @@ -209,7 +225,6 @@ looks like this: [@var{interactive-declaration}] @var{body-forms}@dots{}) @end example -@end ifnottex @cindex lambda list The first element of a lambda expression is always the symbol @@ -243,9 +258,9 @@ code to do the work of the function (or, as a Lisp programmer would say, function is the value returned by the last element of the body. @node Simple Lambda -@subsection A Simple Lambda-Expression Example +@subsection A Simple Lambda Expression Example - Consider for example the following function: + Consider the following example: @example (lambda (a b c) (+ a b c)) @@ -283,18 +298,15 @@ This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 4)} from left to right. Then it applies the lambda expression to the argument values 1, 6 and 1 to produce the value 8. - It is not often useful to write a lambda expression as the @sc{car} of -a form in this way. You can get the same result, of making local -variables and giving them values, using the special form @code{let} -(@pxref{Local Variables}). And @code{let} is clearer and easier to use. -In practice, lambda expressions are either stored as the function -definitions of symbols, to produce named functions, or passed as -arguments to other functions (@pxref{Anonymous Functions}). - - However, calls to explicit lambda expressions were very useful in the -old days of Lisp, before the special form @code{let} was invented. At -that time, they were the only way to bind and initialize local -variables. + As these examples show, you can use a form with a lambda expression +as its @sc{car} to make local variables and give them values. In the +old days of Lisp, this technique was the only way to bind and +initialize local variables. But nowadays, it is clearer to use the +special form @code{let} for this purpose (@pxref{Local Variables}). +Lambda expressions are mainly used as anonymous functions for passing +as arguments to other functions (@pxref{Anonymous Functions}), or +stored as symbol function definitions to produce named functions +(@pxref{Function Names}). @node Argument List @subsection Other Features of Argument Lists @@ -405,12 +417,12 @@ after a @code{&rest} argument. @subsection Documentation Strings of Functions @cindex documentation of function - A lambda expression may optionally have a @dfn{documentation string} just -after the lambda list. This string does not affect execution of the -function; it is a kind of comment, but a systematized comment which -actually appears inside the Lisp world and can be used by the Emacs help -facilities. @xref{Documentation}, for how the @var{documentation-string} is -accessed. + A lambda expression may optionally have a @dfn{documentation string} +just after the lambda list. This string does not affect execution of +the function; it is a kind of comment, but a systematized comment +which actually appears inside the Lisp world and can be used by the +Emacs help facilities. @xref{Documentation}, for how the +documentation string is accessed. It is a good idea to provide documentation strings for all the functions in your program, even those that are called only from within @@ -463,55 +475,45 @@ way users think of the parts of the macro call. @cindex named function @cindex function name - In most computer languages, every function has a name; the idea of a -function without a name is nonsensical. In Lisp, a function in the -strictest sense has no name. It is simply a list whose first element is -@code{lambda}, a byte-code function object, or a primitive subr-object. - - However, a symbol can serve as the name of a function. This happens -when you put the function in the symbol's @dfn{function cell} -(@pxref{Symbol Components}). Then the symbol itself becomes a valid, -callable function, equivalent to the list or subr-object that its -function cell refers to. The contents of the function cell are also -called the symbol's @dfn{function definition}. The procedure of using a -symbol's function definition in place of the symbol is called -@dfn{symbol function indirection}; see @ref{Function Indirection}. - - In practice, nearly all functions are given names in this way and -referred to through their names. For example, the symbol @code{car} works -as a function and does what it does because the primitive subr-object -@code{#<subr car>} is stored in its function cell. + A symbol can serve as the name of a function. This happens when the +symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a +function object (e.g.@: a lambda expression). Then the symbol itself +becomes a valid, callable function, equivalent to the function object +in its function cell. + + The contents of the function cell are also called the symbol's +@dfn{function definition}. The procedure of using a symbol's function +definition in place of the symbol is called @dfn{symbol function +indirection}; see @ref{Function Indirection}. If you have not given a +symbol a function definition, its function cell is said to be +@dfn{void}, and it cannot be used as a function. + + In practice, nearly all functions have names, and are referred to by +their names. You can create a named Lisp function by defining a +lambda expression and putting it in a function cell (@pxref{Function +Cells}). However, it is more common to use the @code{defun} special +form, described in the next section. +@ifnottex +@xref{Defining Functions}. +@end ifnottex We give functions names because it is convenient to refer to them by -their names in Lisp expressions. For primitive subr-objects such as -@code{#<subr car>}, names are the only way you can refer to them: there -is no read syntax for such objects. For functions written in Lisp, the -name is more convenient to use in a call than an explicit lambda -expression. Also, a function with a name can refer to itself---it can -be recursive. Writing the function's name in its own definition is much -more convenient than making the function definition point to itself -(something that is not impossible but that has various disadvantages in -practice). - - We often identify functions with the symbols used to name them. For -example, we often speak of ``the function @code{car},'' not -distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, the -distinction is not important. - - Even so, keep in mind that a function need not have a unique name. While -a given function object @emph{usually} appears in the function cell of only -one symbol, this is just a matter of convenience. It is easy to store -it in several symbols using @code{fset}; then each of the symbols is -equally well a name for the same function. - - A symbol used as a function name may also be used as a variable; these -two uses of a symbol are independent and do not conflict. (Some Lisp -dialects, such as Scheme, do not distinguish between a symbol's value -and its function definition; a symbol's value as a variable is also its -function definition.) If you have not given a symbol a function -definition, you cannot use it as a function; whether the symbol has a -value as a variable makes no difference to this. +their names in Lisp expressions. Also, a named Lisp function can +easily refer to itself---it can be recursive. Furthermore, primitives +can only be referred to textually by their names, since primitive +function objects (@pxref{Primitive Function Type}) have no read +syntax. + + A function need not have a unique name. A given function object +@emph{usually} appears in the function cell of only one symbol, but +this is just a convention. It is easy to store it in several symbols +using @code{fset}; then each of the symbols is a valid name for the +same function. + + Note that a symbol used as a function name may also be used as a +variable; these two uses of a symbol are independent and do not +conflict. (This is not the case in some dialects of Lisp, like +Scheme.) @node Defining Functions @section Defining Functions @@ -521,7 +523,7 @@ value as a variable makes no difference to this. is called @dfn{defining a function}, and it is done with the @code{defun} special form. -@defspec defun name argument-list body-forms +@defspec defun name argument-list body-forms... @code{defun} is the usual way to define new Lisp functions. It defines the symbol @var{name} as a function that looks like this: @@ -534,14 +536,9 @@ defines the symbol @var{name} as a function that looks like this: value. As described previously, @var{argument-list} is a list of argument -names and may include the keywords @code{&optional} and @code{&rest} -(@pxref{Lambda Expressions}). Also, the first two of the -@var{body-forms} may be a documentation string and an interactive -declaration. - -There is no conflict if the same symbol @var{name} is also used as a -variable, since the symbol's value cell is independent of the function -cell. @xref{Symbol Components}. +names and may include the keywords @code{&optional} and @code{&rest}. +Also, the first two of the @var{body-forms} may be a documentation +string and an interactive declaration. @xref{Lambda Components}. Here are some examples: @@ -575,7 +572,7 @@ Here are some examples: @group (defun capitalize-backwards () - "Upcase the last letter of a word." + "Upcase the last letter of the word at point." (interactive) (backward-word 1) (forward-word 1) @@ -587,9 +584,10 @@ Here are some examples: Be careful not to redefine existing functions unintentionally. @code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Redefining a function already -defined is often done deliberately, and there is no way to distinguish -deliberate redefinition from unintentional redefinition. +without any hesitation or notification. Emacs does not prevent you +from doing this, because redefining a function is sometimes done +deliberately, and there is no way to distinguish deliberate +redefinition from unintentional redefinition. @end defspec @cindex function aliases @@ -626,7 +624,8 @@ call the primitive's C definition directly, so changing the symbol's definition will have no effect on them. See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to open-code it. @xref{Inline Functions}. +and tells the Lisp compiler to perform inline expansion on it. +@xref{Inline Functions}. @node Calling Functions @section Calling Functions @@ -790,11 +789,10 @@ This function returns @var{arg} and has no side effects. This function ignores any arguments and returns @code{nil}. @end defun - Emacs Lisp functions can also be user-visible @dfn{commands}. A -command is a function that has an @dfn{interactive} specification. -You may want to call these functions as if they were called -interactively. See @ref{Interactive Call} for details on how to do -that. + Some functions are user-visible @dfn{commands}, which can be called +interactively (usually by a key sequence). It is possible to invoke +such a command exactly as though it was called interactively, by using +the @code{call-interactively} function. @xref{Interactive Call}. @node Mapping Functions @section Mapping Functions @@ -802,12 +800,12 @@ that. A @dfn{mapping function} applies a given function (@emph{not} a special form or macro) to each element of a list or other collection. -Emacs Lisp has several such functions; @code{mapcar} and -@code{mapconcat}, which scan a list, are described here. -@xref{Definition of mapatoms}, for the function @code{mapatoms} which -maps over the symbols in an obarray. @xref{Definition of maphash}, -for the function @code{maphash} which maps over key/value associations -in a hash table. +Emacs Lisp has several such functions; this section describes +@code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a +list. @xref{Definition of mapatoms}, for the function @code{mapatoms} +which maps over the symbols in an obarray. @xref{Definition of +maphash}, for the function @code{maphash} which maps over key/value +associations in a hash table. These mapping functions do not allow char-tables because a char-table is a sparse array whose nominal range of indices is very large. To map @@ -898,48 +896,67 @@ bool-vector, or a string. @section Anonymous Functions @cindex anonymous function - In Lisp, a function is a list that starts with @code{lambda}, a -byte-code function compiled from such a list, or alternatively a -primitive subr-object; names are ``extra.'' Although functions are -usually defined with @code{defun} and given names at the same time, it -is occasionally more concise to use an explicit lambda expression---an -anonymous function. Such a list is valid wherever a function name is. + Although functions are usually defined with @code{defun} and given +names at the same time, it is sometimes convenient to use an explicit +lambda expression---an @dfn{anonymous function}. Anonymous functions +are valid wherever function names are. They are often assigned as +variable values, or as arguments to functions; for instance, you might +pass one as the @var{function} argument to @code{mapcar}, which +applies that function to each element of a list (@pxref{Mapping +Functions}). @xref{describe-symbols example}, for a realistic example +of this. + + When defining a lambda expression that is to be used as an anonymous +function, you can in principle use any method to construct the list. +But typically you should use the @code{lambda} macro, or the +@code{function} special form, or the @code{#'} read syntax: + +@defmac lambda args body... +This macro returns an anonymous function with argument list @var{args} +and body forms given by @var{body}. In effect, this macro makes +@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car} +is @code{lambda} yields the form itself: + +@example +(lambda (x) (* x x)) + @result{} (lambda (x) (* x x)) +@end example + +The @code{lambda} form has one other effect: it tells the Emacs +evaluator and byte-compiler that its argument is a function, by using +@code{function} as a subroutine (see below). +@end defmac - Any method of creating such a list makes a valid function. Even this: +@defspec function function-object +@cindex function quoting +This special form returns @var{function-object} without evaluating it. +In this, it is similar to @code{quote} (@pxref{Quoting}). But unlike +@code{quote}, it also serves as a note to the Emacs evaluator and +byte-compiler that @var{function-object} is intended to be used as a +function. Assuming @var{function-object} is a valid lambda +expression, this has two effects: -@smallexample -@group -(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) -@result{} (lambda (x) (+ 12 x)) -@end group -@end smallexample +@itemize +@item +When the code is byte-compiled, @var{function-object} is compiled into +a byte-code function object (@pxref{Byte Compilation}). -@noindent -This computes a list that looks like @code{(lambda (x) (+ 12 x))} and -makes it the value (@emph{not} the function definition!) of -@code{silly}. +@item +When lexical binding is enabled, @var{function-object} is converted +into a closure. @xref{Closures}. +@end itemize +@end defspec - Here is how we might call this function: +@cindex @samp{#'} syntax +The read syntax @code{#'} is a short-hand for using @code{function}. +The following forms are all equivalent: @example -@group -(funcall silly 1) -@result{} 13 -@end group +(lambda (x) (* x x)) +(function (lambda (x) (* x x))) +#'(lambda (x) (* x x)) @end example -@noindent -It does @emph{not} work to write @code{(silly 1)}, because this -function is not the @emph{function definition} of @code{silly}. We -have not given @code{silly} any function definition, just a value as a -variable. - - Most of the time, anonymous functions are constants that appear in -your program. For instance, you might want to pass one as an argument -to the function @code{mapcar}, which applies any given function to -each element of a list (@pxref{Mapping Functions}). -@xref{describe-symbols example}, for a realistic example of this. - In the following example, we define a @code{change-property} function that takes a function as its third argument, followed by a @code{double-property} function that makes use of @@ -959,15 +976,11 @@ function that takes a function as its third argument, followed by a @end example @noindent -In the @code{double-property} function, we did not quote the -@code{lambda} form. This is permissible, because a @code{lambda} form -is @dfn{self-quoting}: evaluating the form yields the form itself. +Note that we do not quote the @code{lambda} form. -Whether or not you quote a @code{lambda} form makes a difference if -you compile the code (@pxref{Byte Compilation}). If the @code{lambda} -form is unquoted, as in the above example, the anonymous function is -also compiled. Suppose, however, that we quoted the @code{lambda} -form: + If you compile the above code, the anonymous function is also +compiled. This would not happen if, say, you had constructed the +anonymous function by quoting it as a list: @example @group @@ -977,52 +990,10 @@ form: @end example @noindent -If you compile this, the argument passed to @code{change-property} is -the precise list shown: - -@example -(lambda (x) (* x 2)) -@end example - -@noindent -The Lisp compiler cannot assume this list is a function, even though -it looks like one, since it does not know what @code{change-property} -will do with the list. Perhaps it will check whether the @sc{car} of -the third element is the symbol @code{*}! - -@findex function -The @code{function} special form explicitly tells the byte-compiler -that its argument is a function: - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is equivalent to @code{quote}. However, it serves as a -note to the Emacs Lisp compiler that @var{function-object} is intended -to be used only as a function, and therefore can safely be compiled. -Contrast this with @code{quote}, in @ref{Quoting}. -@end defspec - -@cindex @samp{#'} syntax -The read syntax @code{#'} is a short-hand for using @code{function}. -Generally, it is not necessary to use either @code{#'} or -@code{function}; just use an unquoted @code{lambda} form instead. -(Actually, @code{lambda} is a macro defined using @code{function}.) -The following forms are all equivalent: - -@example -#'(lambda (x) (* x x)) -(function (lambda (x) (* x x))) -(lambda (x) (* x x)) -@end example - - We sometimes write @code{function} instead of @code{quote} when -quoting the name of a function, but this usage is just a sort of -comment: - -@example -(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} -@end example +In that case, the anonymous function is kept as a lambda expression in +the compiled code. The byte-compiler cannot assume this list is a +function, even though it looks like one, since it does not know that +@code{change-property} intends to use it as a function. @node Function Cells @section Accessing Function Cell Contents @@ -1118,77 +1089,60 @@ This function stores @var{definition} in the function cell of this is not checked. The argument @var{symbol} is an ordinary evaluated argument. -There are three normal uses of this function: +The primary use of this function is as a subroutine by constructs that +define or alter functions, like @code{defadvice} (@pxref{Advising +Functions}). (If @code{defun} were not a primitive, it could be +written as a Lisp macro using @code{fset}.) You can also use it to +give a symbol a function definition that is not a list, e.g.@: a +keyboard macro (@pxref{Keyboard Macros}): -@itemize @bullet -@item -Copying one symbol's function definition to another---in other words, -making an alternate name for a function. (If you think of this as the -definition of the new name, you should use @code{defalias} instead of -@code{fset}; see @ref{Definition of defalias}.) +@example +;; @r{Define a named keyboard macro.} +(fset 'kill-two-lines "\^u2\^k") + @result{} "\^u2\^k" +@end example -@item -Giving a symbol a function definition that is not a list and therefore -cannot be made with @code{defun}. For example, you can use @code{fset} -to give a symbol @code{s1} a function definition which is another symbol -@code{s2}; then @code{s1} serves as an alias for whatever definition -@code{s2} presently has. (Once again use @code{defalias} instead of -@code{fset} if you think of this as the definition of @code{s1}.) +It you wish to use @code{fset} to make an alternate name for a +function, consider using @code{defalias} instead. @xref{Definition of +defalias}. +@end defun -@item -In constructs for defining or altering functions. If @code{defun} -were not a primitive, it could be written in Lisp (as a macro) using -@code{fset}. -@end itemize +@node Closures +@section Closures -Here are examples of these uses: + As explained in @ref{Variable Scoping}, Emacs can optionally enable +lexical binding of variables. When lexical binding is enabled, any +named function that you create (e.g.@: with @code{defun}), as well as +any anonymous function that you create using the @code{lambda} macro +or the @code{function} special form or the @code{#'} syntax +(@pxref{Anonymous Functions}), is automatically converted into a +closure. -@example -@group -;; @r{Save @code{foo}'s definition in @code{old-foo}.} -(fset 'old-foo (symbol-function 'foo)) -@end group + A closure is a function that also carries a record of the lexical +environment that existed when the function was defined. When it is +invoked, any lexical variable references within its definition use the +retained lexical environment. In all other respects, closures behave +much like ordinary functions; in particular, they can be called in the +same way as ordinary functions. -@group -;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} -;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)} -(fset 'xfirst 'car) - @result{} car -@end group -@group -(xfirst '(1 2 3)) - @result{} 1 -@end group -@group -(symbol-function 'xfirst) - @result{} car -@end group -@group -(symbol-function (symbol-function 'xfirst)) - @result{} #<subr car> -@end group + @xref{Lexical Binding}, for an example of using a closure. -@group -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end group + Currently, an Emacs Lisp closure object is represented by a list +with the symbol @code{closure} as the first element, a list +representing the lexical environment as the second element, and the +argument list and body forms as the remaining elements: -@group -;; @r{Here is a function that alters other functions.} -(defun copy-function-definition (new old) - "Define NEW with the same function definition as OLD." - (fset new (symbol-function old))) -@end group +@example +;; @r{lexical binding is enabled.} +(lambda (x) (* x x)) + @result{} (closure (t) (x) (* x x)) @end example -@end defun - @code{fset} is sometimes used to save the old definition of a -function before redefining it. That permits the new definition to -invoke the old definition. But it is unmodular and unclean for a Lisp -file to redefine a function defined elsewhere. If you want to modify -a function defined by another package, it is cleaner to use -@code{defadvice} (@pxref{Advising Functions}). +@noindent +However, the fact that the internal structure of a closure is +``exposed'' to the rest of the Lisp world is considered an internal +implementation detail. For this reason, we recommend against directly +examining or altering the structure of closure objects. @node Obsolete Functions @section Declaring Functions Obsolete @@ -1254,41 +1208,46 @@ this: @section Inline Functions @cindex inline functions -@findex defsubst -You can define an @dfn{inline function} by using @code{defsubst} instead -of @code{defun}. An inline function works just like an ordinary -function except for one thing: when you compile a call to the function, -the function's definition is open-coded into the caller. +@defmac defsubst name argument-list body-forms... +Define an inline function. The syntax is exactly the same as +@code{defun} (@pxref{Defining Functions}). +@end defmac + + You can define an @dfn{inline function} by using @code{defsubst} +instead of @code{defun}. An inline function works just like an +ordinary function except for one thing: when you byte-compile a call +to the function (@pxref{Byte Compilation}), the function's definition +is expanded into the caller. -Making a function inline makes explicit calls run faster. But it also -has disadvantages. For one thing, it reduces flexibility; if you -change the definition of the function, calls already inlined still use -the old definition until you recompile them. + Making a function inline often makes its function calls run faster. +But it also has disadvantages. For one thing, it reduces flexibility; +if you change the definition of the function, calls already inlined +still use the old definition until you recompile them. -Another disadvantage is that making a large function inline can increase -the size of compiled code both in files and in memory. Since the speed -advantage of inline functions is greatest for small functions, you -generally should not make large functions inline. + Another disadvantage is that making a large function inline can +increase the size of compiled code both in files and in memory. Since +the speed advantage of inline functions is greatest for small +functions, you generally should not make large functions inline. -Also, inline functions do not behave well with respect to debugging, + Also, inline functions do not behave well with respect to debugging, tracing, and advising (@pxref{Advising Functions}). Since ease of debugging and the flexibility of redefining functions are important features of Emacs, you should not make a function inline, even if it's small, unless its speed is really crucial, and you've timed the code to verify that using @code{defun} actually has performance problems. -It's possible to define a macro to expand into the same code that an -inline function would execute. (@xref{Macros}.) But the macro would be -limited to direct use in expressions---a macro cannot be called with -@code{apply}, @code{mapcar} and so on. Also, it takes some work to -convert an ordinary function into a macro. To convert it into an inline -function is very easy; simply replace @code{defun} with @code{defsubst}. -Since each argument of an inline function is evaluated exactly once, you -needn't worry about how many times the body uses the arguments, as you -do for macros. (@xref{Argument Evaluation}.) + It's possible to define a macro to expand into the same code that an +inline function would execute (@pxref{Macros}). But the macro would +be limited to direct use in expressions---a macro cannot be called +with @code{apply}, @code{mapcar} and so on. Also, it takes some work +to convert an ordinary function into a macro. To convert it into an +inline function is easy; just replace @code{defun} with +@code{defsubst}. Since each argument of an inline function is +evaluated exactly once, you needn't worry about how many times the +body uses the arguments, as you do for macros. -Inline functions can be used and open-coded later on in the same file, -following the definition, just like macros. + After an inline function is defined, its inline expansion can be +performed later on in the same file, just like macros. @node Declaring Functions @section Telling the Compiler that a Function is Defined @@ -1352,12 +1311,10 @@ definition using @code{locate-library}; if that finds no file, they expand the definition file name relative to the directory of the file that contains the @code{declare-function} call. - You can also say that a function is defined by C code by specifying a -file name ending in @samp{.c} or @samp{.m}. @code{check-declare-file} -looks for these files in the C source code directory. This is useful -only when you call a function that is defined only on certain systems. -Most of the primitive functions of Emacs are always defined so they will -never give you a warning. + You can also say that a function is a primitive by specifying a file +name ending in @samp{.c} or @samp{.m}. This is useful only when you +call a primitive that is defined only on certain systems. Most +primitives are always defined, so they will never give you a warning. Sometimes a file will optionally use functions from an external package. If you prefix the filename in the @code{declare-function} statement with diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 678ea83465f..f6556639e98 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -582,11 +582,12 @@ If this variable is non-@code{nil}, its value is a form to evaluate whenever the character @code{help-char} is read. If evaluating the form produces a string, that string is displayed. -A command that calls @code{read-event} or @code{read-char} probably -should bind @code{help-form} to a non-@code{nil} expression while it -does input. (The time when you should not do this is when @kbd{C-h} has -some other meaning.) Evaluating this expression should result in a -string that explains what the input is for and how to enter it properly. +A command that calls @code{read-event}, @code{read-char-choice}, or +@code{read-char} probably should bind @code{help-form} to a +non-@code{nil} expression while it does input. (The time when you +should not do this is when @kbd{C-h} has some other meaning.) +Evaluating this expression should result in a string that explains +what the input is for and how to enter it properly. Entry to the minibuffer binds this variable to the value of @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 95655324ab4..ef3ebc4be35 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -127,6 +127,9 @@ not exactly a hook, but does a similar job. @xref{Calendar Customizing,,, emacs}. @end ifnottex +@item change-major-mode-after-body-hook +@xref{Mode Hooks}. + @item change-major-mode-hook @xref{Creating Buffer-Local}. @@ -292,9 +295,15 @@ Manual}. @item post-command-hook @xref{Command Overview}. +@item post-self-insert-hook +@xref{Keymaps and Minor Modes}. + @item pre-command-hook @xref{Command Overview}. +@item prog-mode-hook +@xref{Basic Major Modes}. + @item resume-tty-functions @xref{Suspending Emacs}. diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 64c856d3ed4..a68bcfa0fe7 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -162,7 +162,7 @@ being described, are formatted like this: @var{first-number}. @cindex @code{nil} @cindex false - In Lisp, the symbol @code{nil} has three separate meanings: it + In Emacs Lisp, the symbol @code{nil} has three separate meanings: it is a symbol with the name @samp{nil}; it is the logical truth value @var{false}; and it is the empty list---the list of zero elements. When used as a variable, @code{nil} always has the value @code{nil}. @@ -396,13 +396,14 @@ Form', respectively. Commands are simply functions that may be called interactively; macros process their arguments differently from functions (the arguments are not evaluated), but are presented the same way. - Special form descriptions use a more complex notation to specify -optional and repeated arguments because they can break the argument -list down into separate arguments in more complicated ways. -@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is -optional and @samp{@var{repeated-args}@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped into -additional levels of list structure. Here is an example: + The descriptions of macros and special forms use a more complex +notation to specify optional and repeated arguments, because they can +break the argument list down into separate arguments in more +complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that +@var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}} +stands for zero or more arguments. Parentheses are used when several +arguments are grouped into additional levels of list structure. Here +is an example: @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} This imaginary special form implements a loop that executes the @@ -485,9 +486,9 @@ giving a prefix argument makes @var{here} non-@code{nil}. @end deffn @defvar emacs-build-time -The value of this variable indicates the time at which Emacs was built -at the local site. It is a list of three integers, like the value -of @code{current-time} (@pxref{Time of Day}). +The value of this variable indicates the time at which Emacs was +built. It is a list of three integers, like the value of +@code{current-time} (@pxref{Time of Day}). @example @group diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 8e03ade285f..a8528a548fc 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -432,6 +432,34 @@ for every numeric character code without modifier bits, even if it is @code{nil}, so these character's bindings are never inherited from the parent keymap. +@cindex keymap inheritance from multiple maps + Sometimes you want to make a keymap that inherits from more than one +map. You can use the function @code{make-composed-keymap} for this. + +@defun make-composed-keymap maps &optional parent +This function returns a new keymap composed of the existing keymap(s) +@var{maps}, and optionally inheriting from a parent keymap +@var{parent}. @var{maps} can be a single keymap or a list of more +than one. When looking up a key in the resulting new map, Emacs +searches in each of the @var{maps}, and then in @var{parent}, stopping +at the first match. A @code{nil} binding in any one of @var{maps} +overrides any binding in @var{parent}, but not a non-@code{nil} binding +in any other of the @var{maps}. +@end defun + +@noindent For example, here is how Emacs sets the parent of +@code{help-mode-map}, such that it inherits from both +@code{button-buffer-map} and @code{special-mode-map}: + +@example +(defvar help-mode-map + (let ((map (make-sparse-keymap))) + (set-keymap-parent map (make-composed-keymap button-buffer-map + special-mode-map)) + ... map) ... ) +@end example + + @node Prefix Keys @section Prefix Keys @cindex prefix key @@ -2318,7 +2346,7 @@ The various toolkits with which you can build Emacs do not all support the same set of features for menus. Some code works as expected with one toolkit, but not under another. -One example is menu actions or buttons in a top-level menu-bar. The +One example is menu actions or buttons in a top-level menu bar. The following works with the Lucid toolkit or on MS Windows, but not with GTK or Nextstep, where clicking on the item has no effect. @@ -2658,6 +2686,15 @@ The @code{:rtl} property specifies an alternative image to use for right-to-left languages. Only the Gtk+ version of Emacs supports this at present. +Like the menu bar, the tool bar can display separators (@pxref{Menu +Separators}). Tool bar separators are vertical rather than +horizontal, though, and only a single style is supported. Separators +are represented in the tool bar keymap in the same way as for the +menu bar, i.e. using a @code{(menu-item "--"}) entry. The Gtk+ and +Nextstep tool bars render separators natively, otherwise Emacs selects +a separator image that is appropriate for the display. Note that tool +bar separators do not support any properties, such as @code{:visible}. + The default tool bar is defined so that items specific to editing do not appear for major modes whose command symbol has a @code{mode-class} property of @code{special} (@pxref{Major Mode Conventions}). Major diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index eb9ddf58603..c8433c79b54 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -23,7 +23,6 @@ the whole list. * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. @end menu @node Cons Cells @@ -31,61 +30,56 @@ the whole list. @cindex lists and cons cells Lists in Lisp are not a primitive data type; they are built up from -@dfn{cons cells}. A cons cell is a data object that represents an -ordered pair. That is, it has two slots, and each slot @dfn{holds}, or -@dfn{refers to}, some Lisp object. One slot is known as the @sc{car}, -and the other is known as the @sc{cdr}. (These names are traditional; -see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.'' +@dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data +object that represents an ordered pair. That is, it has two slots, +and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One +slot is known as the @sc{car}, and the other is known as the @sc{cdr}. +(These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is +pronounced ``could-er.'' We say that ``the @sc{car} of this cons cell is'' whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. A list is a series of cons cells ``chained together,'' so that each -cell refers to the next one. There is one cons cell for each element of -the list. By convention, the @sc{car}s of the cons cells hold the -elements of the list, and the @sc{cdr}s are used to chain the list: the -@sc{cdr} slot of each cons cell refers to the following cons cell. The -@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between -the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the -level of cons cells, the @sc{car} and @sc{cdr} slots have the same -characteristics. +cell refers to the next one. There is one cons cell for each element +of the list. By convention, the @sc{car}s of the cons cells hold the +elements of the list, and the @sc{cdr}s are used to chain the list +(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of +convention; at the level of cons cells, the @sc{car} and @sc{cdr} +slots have similar properties). Hence, the @sc{cdr} slot of each cons +cell in a list refers to the following cons cell. @cindex true list - Since @code{nil} is the conventional value to put in the @sc{cdr} of -the last cons cell in the list, we call that case a @dfn{true list}. - - In Lisp, we consider the symbol @code{nil} a list as well as a -symbol; it is the list with no elements. For convenience, the symbol + Also by convention, the @sc{cdr} of the last cons cell in a list is +@code{nil}. We call such a @code{nil}-terminated structure a +@dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a +symbol and a list with no elements. For convenience, the symbol @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a -true list. +as its @sc{car}). + + Hence, the @sc{cdr} of a true list is always a true list. The +@sc{cdr} of a nonempty true list is a true list containing all the +elements except the first. @cindex dotted list @cindex circular list - If the @sc{cdr} of a list's last cons cell is some other value, -neither @code{nil} nor another cons cell, we call the structure a -@dfn{dotted list}, since its printed representation would use -@samp{.}. There is one other possibility: some cons cell's @sc{cdr} -could point to one of the previous cons cells in the list. We call -that structure a @dfn{circular list}. + If the @sc{cdr} of a list's last cons cell is some value other than +@code{nil}, we call the structure a @dfn{dotted list}, since its +printed representation would use dotted pair notation (@pxref{Dotted +Pair Notation}). There is one other possibility: some cons cell's +@sc{cdr} could point to one of the previous cons cells in the list. +We call that structure a @dfn{circular list}. For some purposes, it does not matter whether a list is true, -circular or dotted. If the program doesn't look far enough down the +circular or dotted. If a program doesn't look far enough down the list to see the @sc{cdr} of the final cons cell, it won't care. However, some functions that operate on lists demand true lists and signal errors if given a dotted list. Most functions that try to find the end of a list enter infinite loops if given a circular list. @cindex list structure - Because most cons cells are used as part of lists, the phrase -@dfn{list structure} has come to mean any structure made out of cons -cells. - - The @sc{cdr} of any nonempty true list @var{l} is a list containing all the -elements of @var{l} except the first. - - @xref{Cons Cell Type}, for the read and print syntax of cons cells and -lists, and for ``box and arrow'' illustrations of lists. + Because most cons cells are used as part of lists, we refer to any +structure made out of cons cells as a @dfn{list structure}. @node List-related Predicates @section Predicates on Lists @@ -257,6 +251,10 @@ x x @result{} (b c) @end example + +@noindent +For the @code{pop} macro, which removes an element from a list, +@xref{List Variables}. @end defmac @defun nth n list @@ -695,6 +693,10 @@ This macro provides an alternative way to write l @result{} (c a b) @end example + +@noindent +For the @code{pop} macro, which removes the first element from a list, +@xref{List Elements}. @end defmac Two functions modify lists that are the values of variables. @@ -1800,90 +1802,3 @@ often modifies the original list structure of @var{alist}. compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. @end defun - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - This section describes functions for operating on rings. A -@dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 8d8fec62e2c..3c2fa60248e 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -10,9 +10,10 @@ @cindex library @cindex Lisp library - Loading a file of Lisp code means bringing its contents into the Lisp -environment in the form of Lisp objects. Emacs finds and opens the -file, reads the text, evaluates each form, and then closes the file. + Loading a file of Lisp code means bringing its contents into the +Lisp environment in the form of Lisp objects. Emacs finds and opens +the file, reads the text, evaluates each form, and then closes the +file. Such a file is also called a @dfn{Lisp library}. The load functions evaluate all the expressions in a file just as the @code{eval-buffer} function evaluates all the @@ -29,11 +30,6 @@ into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. - A file containing Lisp code is often called a @dfn{library}. Thus, -the ``Rmail library'' is a file containing code for Rmail mode. -Similarly, a ``Lisp library directory'' is a directory of files -containing Lisp code. - @menu * How Programs Do Loading:: The @code{load} function and others. * Load Suffixes:: Details about the suffixes that @code{load} tries. @@ -88,8 +84,8 @@ this case, you must specify the precise file name you want, except that, if Auto Compression mode is enabled, @code{load} will still use @code{jka-compr-load-suffixes} to find compressed versions. By specifying the precise file name and using @code{t} for -@var{nosuffix}, you can prevent perverse file names such as -@file{foo.el.el} from being tried. +@var{nosuffix}, you can prevent file names like @file{foo.el.el} from +being tried. If the optional argument @var{must-suffix} is non-@code{nil}, then @code{load} insists that the file name used must end in either @@ -238,73 +234,37 @@ it skips the latter group. When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable @code{load-path}. -@defopt load-path +@defvar load-path @cindex @code{EMACSLOADPATH} environment variable The value of this variable is a list of directories to search when loading files with @code{load}. Each element is a string (which must be a directory name) or @code{nil} (which stands for the current working directory). -@end defopt - - The value of @code{load-path} is initialized from the environment -variable @code{EMACSLOADPATH}, if that exists; otherwise its default -value is specified in @file{emacs/src/epaths.h} when Emacs is built. -Then the list is expanded by adding subdirectories of the directories -in the list. - - The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; -@samp{:} (or @samp{;}, according to the operating system) separates -directory names, and @samp{.} is used for the current default directory. -Here is an example of how to set your @code{EMACSLOADPATH} variable from -a @code{csh} @file{.login} file: - -@smallexample -setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp -@end smallexample +@end defvar - Here is how to set it using @code{sh}: + Each time Emacs starts up, it sets up the value of @code{load-path} +in several steps. First, it initializes @code{load-path} to the +directories specified by the environment variable @env{EMACSLOADPATH}, +if that exists. The syntax of @env{EMACSLOADPATH} is the same as used +for @code{PATH}; directory names are separated by @samp{:} (or +@samp{;}, on some operating systems), and @samp{.} stands for the +current default directory. Here is an example of how to set +@env{EMACSLOADPATH} variable from @command{sh}: @smallexample export EMACSLOADPATH -EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp +EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp @end smallexample - Here is an example of code you can place in your init file (@pxref{Init -File}) to add several directories to the front of your default -@code{load-path}: +@noindent +Here is how to set it from @code{csh}: @smallexample -@group -(setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) -@end group +setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp @end smallexample -@c Wordy to rid us of an overfull hbox. --rjc 15mar92 -@noindent -In this example, the path searches the current working directory first, -followed then by the @file{/user/bil/emacs} directory, the -@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory, -which are then followed by the standard directories for Lisp code. - - Dumping Emacs uses a special value of @code{load-path}. If the value of -@code{load-path} at the end of dumping is unchanged (that is, still the -same special value), the dumped Emacs switches to the ordinary -@code{load-path} value when it starts up, as described above. But if -@code{load-path} has any other value at the end of dumping, that value -is used for execution of the dumped Emacs also. - - Therefore, if you want to change @code{load-path} temporarily for -loading a few libraries in @file{site-init.el} or @file{site-load.el}, -you should bind @code{load-path} locally with @code{let} around the -calls to @code{load}. - - The default value of @code{load-path}, when running an Emacs which has -been installed on the system, includes two special directories (and -their subdirectories as well): + If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs +initializes @code{load-path} with the following two directories: @smallexample "/usr/local/share/emacs/@var{version}/site-lisp" @@ -319,33 +279,42 @@ and @noindent The first one is for locally installed packages for a particular Emacs -version; the second is for locally installed packages meant for use with -all installed Emacs versions. - - There are several reasons why a Lisp package that works well in one -Emacs version can cause trouble in another. Sometimes packages need -updating for incompatible changes in Emacs; sometimes they depend on -undocumented internal Emacs data that can change without notice; -sometimes a newer Emacs version incorporates a version of the package, -and should be used only with that version. - - Emacs finds these directories' subdirectories and adds them to -@code{load-path} when it starts up. Both immediate subdirectories and -subdirectories multiple levels down are added to @code{load-path}. - - Not all subdirectories are included, though. Subdirectories whose -names do not start with a letter or digit are excluded. Subdirectories -named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which -contains a file named @file{.nosearch} is excluded. You can use these -methods to prevent certain subdirectories of the @file{site-lisp} -directories from being searched. +version; the second is for locally installed packages meant for use +with all installed Emacs versions. If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---then @code{load-path} -normally contains two additional directories. These are the @code{lisp} -and @code{site-lisp} subdirectories of the main build directory. (Both +executable that has not been formally installed---Emacs puts two more +directories in @code{load-path}. These are the @code{lisp} and +@code{site-lisp} subdirectories of the main build directory. (Both are represented as absolute file names.) + Next, Emacs ``expands'' the initial list of directories in +@code{load-path} by adding the subdirectories of those directories. +Both immediate subdirectories and subdirectories multiple levels down +are added. But it excludes subdirectories whose names do not start +with a letter or digit, and subdirectories named @file{RCS} or +@file{CVS}, and subdirectories containing a file named +@file{.nosearch}. + + Next, Emacs adds any extra load directory that you specify using the +@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The +GNU Emacs Manual}). It also adds the directories where optional +packages are installed, if any (@pxref{Packaging Basics}). + + It is common to add code to one's init file (@pxref{Init File}) to +add one or more directories to @code{load-path}. For example: + +@smallexample +(push "~/.emacs.d/lisp" load-path) +@end smallexample + + Dumping Emacs uses a special value of @code{load-path}. If the +value of @code{load-path} at the end of dumping is unchanged (that is, +still the same special value), the dumped Emacs switches to the +ordinary @code{load-path} value when it starts up, as described above. +But if @code{load-path} has any other value at the end of dumping, +that value is used for execution of the dumped Emacs also. + @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It searches for the library in the same way @code{load} does, and the @@ -401,30 +370,26 @@ example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. @xref{Coding Systems}. - The reason Emacs is designed this way is so that Lisp programs give -predictable results, regardless of how Emacs was started. In addition, -this enables programs that depend on using multibyte text to work even -in a unibyte Emacs. - - In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are -multibyte strings should not be noticeable, since inserting them in -unibyte buffers converts them to unibyte automatically. However, if -this does make a difference, you can force a particular Lisp file to be -interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a -comment on the file's first line. With that designator, the file will -unconditionally be interpreted as unibyte, even in an ordinary -multibyte Emacs session. This can matter when making keybindings to -non-@acronym{ASCII} characters written as @code{?v@var{literal}}. + In most Emacs Lisp programs, the fact that non-@acronym{ASCII} +strings are multibyte strings should not be noticeable, since +inserting them in unibyte buffers converts them to unibyte +automatically. However, if this does make a difference, you can force +a particular Lisp file to be interpreted as unibyte by writing +@samp{-*-unibyte: t;-*-} in a comment on the file's first line. With +that designator, the file will unconditionally be interpreted as +unibyte, even in an ordinary multibyte Emacs session. This can matter +when making keybindings to non-@acronym{ASCII} characters written as +@code{?v@var{literal}}. @node Autoload @section Autoload @cindex autoload - The @dfn{autoload} facility allows you to make a function or macro -known in Lisp, but put off loading the file that defines it. The first -call to the function automatically reads the proper file to install the -real definition and other associated code, then runs the real definition -as if it had been loaded all along. + The @dfn{autoload} facility allows you to register the existence of +a function or macro, but put off loading the file that defines it. +The first call to the function automatically reads the proper file, in +order to install the real definition and other associated code, then +runs the real definition as if it had been loaded all along. There are two ways to set up an autoloaded function: by calling @code{autoload}, and by writing a special ``magic'' comment in the @@ -696,23 +661,29 @@ already. If not, it loads the feature from the appropriate file. This file should call @code{provide} at the top level to add the feature to @code{features}; if it fails to do so, @code{require} signals an error. - For example, in @file{emacs/lisp/prolog.el}, -the definition for @code{run-prolog} includes the following code: + For example, in @file{idlwave.el}, the definition for +@code{idlwave-complete-filename} includes the following code: @smallexample -(defun run-prolog () - "Run an inferior Prolog process, with I/O via buffer *prolog*." - (interactive) - (require 'comint) - (switch-to-buffer (make-comint "prolog" prolog-program-name)) - (inferior-prolog-mode)) +(defun idlwave-complete-filename () + "Use the comint stuff to complete a file name." + (require 'comint) + (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-") + (comint-completion-addsuffix nil) + ...) + (comint-dynamic-complete-filename))) @end smallexample @noindent The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded. This ensures that @code{make-comint} is -defined. Features are normally named after the files that provide them, -so that @code{require} need not be given the file name. +if it has not yet been loaded, ensuring that +@code{comint-dynamic-complete-filename} is defined. Features are +normally named after the files that provide them, so that +@code{require} need not be given the file name. (Note that it is +important that the @code{require} statement be outside the body of the +@code{let}. Loading a library while its variables are let-bound can +have unintended consequences, namely the variables becoming unbound +after the let exits.) The @file{comint.el} file contains the following top-level expression: diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index a8b941bba89..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,14 +219,33 @@ 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. @defmac declare @var{specs}@dots{} @anchor{Definition of declare} A @code{declare} form is used in a macro definition to specify various -additional information about it. Two kinds of specification are +additional information about it. The following specifications are currently supported: @table @code @@ -257,109 +274,13 @@ without evaluating any @var{specs}. No macro absolutely needs a @code{declare} form, because that form has no effect on how the macro expands, on what the macro means in the -program. It only affects secondary features: indentation and Edebug. - -@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 +program. It only affects the secondary features listed above. @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 diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in index 08b176b7593..11b6beab84d 100644 --- a/doc/lispref/makefile.w32-in +++ b/doc/lispref/makefile.w32-in @@ -38,14 +38,9 @@ MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -I$(emacsdir) # The environment variable and its value to add $(srcdir) to the path # searched for TeX input files. texinputdir = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinputdir);$(TEXINPUTS)" \ + "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C -# The name of the manual: -VERSION=2.9 -## FIXME can this be set by configure, as per Makefile.in? -manual = elisp-manual-23-$(VERSION) - # List of all the texinfo files in the manual: srcs = \ diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index e3008470233..a71138f5268 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1335,19 +1335,19 @@ but uses the predicate @code{user-variable-p} instead of @deffn Command read-color &optional prompt convert allow-empty display This function reads a string that is a color specification, either the color's name or an RGB hex value such as @code{#RRRGGGBBB}. It -prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"}) +prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"}) and provides completion for color names, but not for hex RGB values. In addition to names of standard colors, completion candidates include the foreground and background colors at point. Valid RGB values are described in @ref{Color Names}. -The function's return value is the color name typed by the user in the +The function's return value is the string typed by the user in the minibuffer. However, when called interactively or if the optional -argument @var{convert} is non-@code{nil}, it converts the name into -the color's RGB value and returns that value as a string. If an -invalid color name was specified, this function signals an error, -except that empty color names are allowed when @code{allow-empty} is +argument @var{convert} is non-@code{nil}, it converts any input color +name into the corresponding RGB value string and instead returns that. +This function requires a valid color specification to be input. +Empty color names are allowed when @code{allow-empty} is non-@code{nil} and the user enters null input. Interactively, or when @var{display} is non-@code{nil}, the return diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 5d09b79748e..0b020bee0b0 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -135,23 +135,42 @@ This macro runs the abnormal hook @code{hook} as a series of nested ``wrapper functions'' around the @var{body} forms. The effect is similar to nested @code{around} advices (@pxref{Around-Advice}). -Each hook function must accept an argument list consisting of a function +Each hook function should accept an argument list consisting of a function @var{fun}, followed by the additional arguments listed in @var{args}. -The function @var{fun} passed to the very first hook function in -@var{hook} does the same as @var{body}, if it is called with arguments -@var{args}. The @var{fun} passed to each successive hook function is +The first hook function is passed a function @var{fun} that, if it is +called with arguments @var{args}, performs @var{body} (i.e., the default +operation). The @var{fun} passed to each successive hook function is constructed from all the preceding hook functions (and @var{body}); if this @var{fun} is called with arguments @var{args}, it does what the @code{with-wrapper-hook} call would if the preceding hook functions were the only ones in @var{hook}. -In the function definition of the hook function, @var{fun} can be called -any number of times (including not calling it at all). This function -definition is then used to construct the @var{fun} passed to the next -hook function in @var{hook}, if any. The last or ``outermost'' -@var{fun} is called once to produce the effect. +Each hook function may call its @var{fun} argument as many times as it +wishes, including never. In that case, such a hook function acts to +replace the default definition altogether, and any preceding hook +functions. Of course, a subsequent hook function may do the same thing. + +Each hook function definition is used to construct the @var{fun} passed +to the next hook function in @var{hook}, if any. The last or +``outermost'' @var{fun} is called once to produce the overall effect. + +When might you want to use a wrapper hook? The function +@code{filter-buffer-substring} illustrates a common case. There is a +basic functionality, performed by @var{body}---in this case, to extract +a buffer-substring. Then any number of hook functions can act in +sequence to modify that string, before returning the final result. +A wrapper-hook also allows for a hook function to completely replace the +default definition (by not calling @var{fun}). @end defmac +@defun run-hook-wrapped hook wrap-function &rest args +This function is similar to @code{run-hook-with-args-until-success}. +Like that function, it runs the functions on the abnormal hook +@code{hook}, stopping at the first one that returns non-@code{nil}. +Instead of calling the hook functions directly, though, it actually +calls @code{wrap-function} with arguments @code{fun} and @code{args}. +@end defun + @node Setting Hooks @subsection Setting Hooks @@ -468,8 +487,9 @@ other packages would interfere with them. @cindex major mode hook Each major mode should have a normal @dfn{mode hook} named @code{@var{modename}-mode-hook}. The very last thing the major mode command -should do is to call @code{run-mode-hooks}. This runs the mode hook, -and then runs the normal hook @code{after-change-major-mode-hook}. +should do is to call @code{run-mode-hooks}. This runs the normal +hook @code{change-major-mode-after-body-hook}, the mode hook, +and then the normal hook @code{after-change-major-mode-hook}. @xref{Mode Hooks}. @item @@ -588,6 +608,18 @@ Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}} line, or near the end of the file, for any mode tag. +@vindex inhibit-local-variables-regexps +There are some file types where it is not appropriate to scan the file +contents for a mode specifier. For example, a tar archive may happen to +contain, near the end of the file, a member file that has a local +variables section specifying a mode for that particular file. This +should not be applied to the containing tar file. Similarly, a tiff +image file might just happen to contain a first line that seems to +match the @w{@samp{-*-}} pattern. For these reasons, both these file +extensions are members of the list @var{inhibit-local-variables-regexps}. +Add patterns to this list to prevent Emacs searching them for local +variables of any kind (not just mode specifiers). + If @var{keep-mode-if-same} is non-@code{nil}, this function does not call the mode command if the buffer is already in the proper major mode. For instance, @code{set-visited-file-name} sets this to @@ -883,6 +915,20 @@ mode, which is used by the @samp{*Buffer List*} buffer. @xref{List Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}. @end deffn +@cindex tables of data +@deffn Command tabulated-list-mode +Tabulated List mode is another mode that derives from Special mode. It +displays tabulated data, i.e. a series of rows and columns, where each +row represents a particular entry, whose properties are displayed in the +various columns. It provides a general mechanism for sorting on +columns. You can use Tabulated List mode as the basis for other modes +that need to display lists. For example, the @samp{*Packages*} buffer +uses this (@pxref{Packages,,, emacs, The GNU Emacs Manual}). The +documentation of the @code{tabulated-list-mode} function explains what +you need to do to use it. At a minimum, specify the column format via +the @code{tabulated-list-format} variable. +@end deffn + @node Generic Modes @subsection Generic Modes @cindex generic mode @@ -927,8 +973,9 @@ before it runs the mode hook variable @code{@var{mode}-hook}. @node Mode Hooks @subsection Mode Hooks - Every major mode command should finish by running its mode hook and -the mode-independent normal hook @code{after-change-major-mode-hook}. + Every major mode command should finish by running the mode-independent +normal hook @code{change-major-mode-after-body-hook}, its mode hook, +and the normal hook @code{after-change-major-mode-hook}. It does this by calling @code{run-mode-hooks}. If the major mode is a derived mode, that is if it calls another major mode (the parent mode) in its body, it should do this inside @code{delay-mode-hooks} so that @@ -937,11 +984,12 @@ call to @code{run-mode-hooks} runs the parent's mode hook too. @xref{Major Mode Conventions}. Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. -When user-implemented major modes have not been updated to use it, -they won't entirely follow these conventions: they may run the -parent's mode hook too early, or fail to run -@code{after-change-major-mode-hook}. If you encounter such a major -mode, please correct it to follow these conventions. +Versions before 24 did not have @code{change-major-mode-after-body-hook}. +When user-implemented major modes do not use @code{run-mode-hooks} and +have not been updated to use these newer features, they won't entirely +follow these conventions: they may run the parent's mode hook too early, +or fail to run @code{after-change-major-mode-hook}. If you encounter +such a major mode, please correct it to follow these conventions. When you defined a major mode using @code{define-derived-mode}, it automatically makes sure these conventions are followed. If you @@ -951,6 +999,7 @@ use the following functions to handle these conventions automatically. @defun run-mode-hooks &rest hookvars Major modes should run their mode hook using this function. It is similar to @code{run-hooks} (@pxref{Hooks}), but it also runs +@code{change-major-mode-after-body-hook} and @code{after-change-major-mode-hook}. When this function is called during the execution of a @@ -970,6 +1019,11 @@ The hooks will actually run during the next call to construct. @end defmac +@defvar change-major-mode-after-body-hook +This is a normal hook run by @code{run-mode-hooks}. It is run before +the mode hooks. +@end defvar + @defvar after-change-major-mode-hook This is a normal hook run by @code{run-mode-hooks}. It is run at the very end of every properly-written major mode command. @@ -1000,13 +1054,10 @@ the conventions listed above: (defvar text-mode-map (let ((map (make-sparse-keymap))) (define-key map "\e\t" 'ispell-complete-word) - (define-key map "\es" 'center-line) - (define-key map "\eS" 'center-paragraph) map) "Keymap for `text-mode'. -Many other modes, such as Mail mode, Outline mode -and Indented Text mode, inherit all the commands -defined in this map.") +Many other modes, such as `mail-mode', `outline-mode' and +`indented-text-mode', inherit all the commands defined in this map.") @end group @end smallexample @@ -1024,7 +1075,6 @@ Turning on Text mode runs the normal hook `text-mode-hook'." @end group @group (set (make-local-variable 'text-mode-variant) t) - ;; @r{These two lines are a feature added recently.} (set (make-local-variable 'require-final-newline) mode-require-final-newline) (set (make-local-variable 'indent-line-function) 'indent-relative)) @@ -1035,103 +1085,29 @@ Turning on Text mode runs the normal hook `text-mode-hook'." (The last line is redundant nowadays, since @code{indent-relative} is the default value, and we'll delete it in a future version.) - Here is how it was defined formerly, before -@code{define-derived-mode} existed: - -@smallexample -@group -;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} -(define-abbrev-table 'text-mode-abbrev-table () - "Abbrev table used while in text mode.") -@end group - -@group -(defun text-mode () - "Major mode for editing text intended for humans to read... - Special commands: \\@{text-mode-map@} -@end group -@group -Turning on text-mode runs the hook `text-mode-hook'." - (interactive) - (kill-all-local-variables) - (use-local-map text-mode-map) -@end group -@group - (setq local-abbrev-table text-mode-abbrev-table) - (set-syntax-table text-mode-syntax-table) -@end group -@group - ;; @r{These four lines are absent from the current version} - ;; @r{not because this is done some other way, but because} - ;; @r{nowadays Text mode uses the normal definition of paragraphs.} - (set (make-local-variable 'paragraph-start) - (concat "[ \t]*$\\|" page-delimiter)) - (set (make-local-variable 'paragraph-separate) paragraph-start) - (set (make-local-variable 'indent-line-function) 'indent-relative-maybe) -@end group -@group - (setq mode-name "Text") - (setq major-mode 'text-mode) - (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} - ; @r{customize the mode with a hook.} -@end group -@end smallexample - @cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp -Interaction mode) have more features than Text mode and the code is -correspondingly more complicated. Here are excerpts from -@file{lisp-mode.el} that illustrate how these modes are written. + The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction +mode) have more features than Text mode and the code is correspondingly +more complicated. Here are excerpts from @file{lisp-mode.el} that +illustrate how these modes are written. + + Here is how the Lisp mode syntax and abbrev tables are defined: @cindex syntax table example @smallexample @group ;; @r{Create mode-specific table variables.} -(defvar lisp-mode-syntax-table nil "") -(defvar lisp-mode-abbrev-table nil "") -@end group - -@group -(defvar emacs-lisp-mode-syntax-table - (let ((table (make-syntax-table))) - (let ((i 0)) -@end group - -@group - ;; @r{Set syntax of chars up to @samp{0} to say they are} - ;; @r{part of symbol names but not words.} - ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} - (while (< i ?0) - (modify-syntax-entry i "_ " table) - (setq i (1+ i))) - ;; @r{@dots{} similar code follows for other character ranges.} -@end group -@group - ;; @r{Then set the syntax codes for characters that are special in Lisp.} - (modify-syntax-entry ? " " table) - (modify-syntax-entry ?\t " " table) - (modify-syntax-entry ?\f " " table) - (modify-syntax-entry ?\n "> " table) -@end group -@group - ;; @r{Give CR the same syntax as newline, for selective-display.} - (modify-syntax-entry ?\^m "> " table) - (modify-syntax-entry ?\; "< " table) - (modify-syntax-entry ?` "' " table) - (modify-syntax-entry ?' "' " table) - (modify-syntax-entry ?, "' " table) -@end group -@group - ;; @r{@dots{}likewise for many other characters@dots{}} - (modify-syntax-entry ?\( "() " table) - (modify-syntax-entry ?\) ")( " table) - (modify-syntax-entry ?\[ "(] " table) - (modify-syntax-entry ?\] ")[ " table)) - table)) -@end group -@group -;; @r{Create an abbrev table for lisp-mode.} +(defvar lisp-mode-abbrev-table nil) (define-abbrev-table 'lisp-mode-abbrev-table ()) + +(defvar lisp-mode-syntax-table + (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table))) + (modify-syntax-entry ?\[ "_ " table) + (modify-syntax-entry ?\] "_ " table) + (modify-syntax-entry ?# "' 14" table) + (modify-syntax-entry ?| "\" 23bn" table) + table) + "Syntax table used in `lisp-mode'.") @end group @end smallexample @@ -1140,7 +1116,7 @@ each calls the following function to set various variables: @smallexample @group -(defun lisp-mode-variables (lisp-syntax) +(defun lisp-mode-variables (&optional lisp-syntax keywords-case-insensitive) (when lisp-syntax (set-syntax-table lisp-mode-syntax-table)) (setq local-abbrev-table lisp-mode-abbrev-table) @@ -1148,22 +1124,14 @@ each calls the following function to set various variables: @end group @end smallexample - In Lisp and most programming languages, we want the paragraph -commands to treat only blank lines as paragraph separators. And the -modes should understand the Lisp conventions for comments. The rest of -@code{lisp-mode-variables} sets this up: +@noindent +Amongst other things, this function sets up the @code{comment-start} +variable to handle Lisp comments: @smallexample @group - (set (make-local-variable 'paragraph-start) - (concat page-delimiter "\\|$" )) - (set (make-local-variable 'paragraph-separate) - paragraph-start) - @dots{} -@end group -@group - (set (make-local-variable 'comment-indent-function) - 'lisp-comment-indent)) + (make-local-variable 'comment-start) + (setq comment-start ";") @dots{} @end group @end smallexample @@ -1175,11 +1143,10 @@ common. The following code sets up the common commands: @smallexample @group -(defvar shared-lisp-mode-map +(defvar lisp-mode-shared-map (let ((map (make-sparse-keymap))) - (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) - (define-key shared-lisp-mode-map "\177" - 'backward-delete-char-untabify) + (define-key map "\e\C-q" 'indent-sexp) + (define-key map "\177" 'backward-delete-char-untabify) map) "Keymap for commands shared by all sorts of Lisp modes.") @end group @@ -1191,25 +1158,29 @@ And here is the code to set up the keymap for Lisp mode: @smallexample @group (defvar lisp-mode-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map shared-lisp-mode-map) + (let ((map (make-sparse-keymap)) + (menu-map (make-sparse-keymap "Lisp"))) + (set-keymap-parent map lisp-mode-shared-map) (define-key map "\e\C-x" 'lisp-eval-defun) (define-key map "\C-c\C-z" 'run-lisp) + @dots{} map) - "Keymap for ordinary Lisp mode...") + "Keymap for ordinary Lisp mode. +All commands in `lisp-mode-shared-map' are inherited by this map.") @end group @end smallexample - Finally, here is the complete major mode command definition for Lisp -mode. +@noindent +Finally, here is the major mode command for Lisp mode: @smallexample @group -(defun lisp-mode () +(define-derived-mode lisp-mode prog-mode "Lisp" "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. Commands: Delete converts tabs to spaces as it moves back. Blank lines separate paragraphs. Semicolons start comments. + \\@{lisp-mode-map@} Note that `run-lisp' may be used either to start an inferior Lisp job or to switch back to an existing one. @@ -1218,24 +1189,12 @@ or to switch back to an existing one. @group Entry to this mode calls the value of `lisp-mode-hook' if that value is non-nil." - (interactive) - (kill-all-local-variables) -@end group -@group - (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} - (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds out what to describe.} - (setq mode-name "Lisp") ; @r{This goes into the mode line.} - (lisp-mode-variables t) ; @r{This defines various variables.} - (set (make-local-variable 'comment-start-skip) + (lisp-mode-variables nil t) + (set (make-local-variable 'find-tag-default-function) 'lisp-find-tag-default) + (make-local-variable 'comment-start-skip) + (setq comment-start-skip "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") - (set (make-local-variable 'font-lock-keywords-case-fold-search) t) -@end group -@group - (setq imenu-case-fold-search t) - (set-syntax-table lisp-mode-syntax-table) - (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} - ; @r{hook to customize the mode.} + (setq imenu-case-fold-search t)) @end group @end smallexample @@ -1415,11 +1374,12 @@ alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. @cindex @code{self-insert-command}, minor modes One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing @code{self-insert-command} are limited to -special cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of @code{self-insert-command} for the -standard one. The editor command loop handles this function specially.) +self-insert. (Another way to customize @code{self-insert-command} is +through @code{post-self-insert-hook}. Apart from this, the facilities +for customizing @code{self-insert-command} are limited to special cases, +designed for abbrevs and Auto Fill mode. Do not try substituting your +own definition of @code{self-insert-command} for the standard one. The +editor command loop handles this function specially.) The key sequences bound in a minor mode should consist of @kbd{C-c} followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other @@ -1434,11 +1394,21 @@ implementing a mode in one self-contained definition. @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} This macro defines a new minor mode whose name is @var{mode} (a symbol). It defines a command named @var{mode} to toggle the minor -mode, with @var{doc} as its documentation string. It also defines a -variable named @var{mode}, which is set to @code{t} or @code{nil} by -enabling or disabling the mode. The variable is initialized to -@var{init-value}. Except in unusual circumstances (see below), this -value must be @code{nil}. +mode, with @var{doc} as its documentation string. + +The toggle command takes one optional (prefix) argument. +If called interactively with no argument it toggles the mode on or off. +A positive prefix argument enables the mode, any other prefix argument +disables it. From Lisp, an argument of @code{toggle} toggles the mode, +whereas an omitted or @code{nil} argument enables the mode. +This makes it easy to enable the minor mode in a major mode hook, for example. +If @var{doc} is nil, the macro supplies a default documentation string +explaining the above. + +By default, it also defines a variable named @var{mode}, which is set to +@code{t} or @code{nil} by enabling or disabling the mode. The variable +is initialized to @var{init-value}. Except in unusual circumstances +(see below), this value must be @code{nil}. The string @var{lighter} says what to display in the mode line when the mode is enabled; if it is @code{nil}, the mode is not displayed @@ -1493,6 +1463,17 @@ This is equivalent to specifying @var{lighter} positionally. @item :keymap @var{keymap} This is equivalent to specifying @var{keymap} positionally. + +@item :variable @var{place} +This replaces the default variable @var{mode}, used to store the state +of the mode. If you specify this, the @var{mode} variable is not +defined, and any @var{init-value} argument is unused. @var{place} +can be a different named variable (which you must define yourself), or +anything that can be used with the @code{setf} function +(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}). +@var{place} can also be a cons @code{(@var{get} . @var{set})}, +where @var{get} is an expression that returns the current state, +and @var{set} is a function of one argument (a state) that sets it. @end table Any other keyword arguments are passed directly to the @@ -1521,9 +1502,10 @@ for this macro. @smallexample (define-minor-mode hungry-mode "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. +Interactively with no argument, this command toggles the mode. +A positive prefix argument enables the mode, any other prefix +argument disables it. From Lisp, argument omitted or nil enables +the mode, `toggle' toggles the state. When Hungry mode is enabled, the control delete key gobbles all preceding whitespace except the last. @@ -1552,13 +1534,7 @@ minor modes don't need any. @smallexample (define-minor-mode hungry-mode "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." +...rest of documentation as before..." ;; The initial value. :init-value nil ;; The indicator for the mode line. @@ -1593,8 +1569,15 @@ starts, for example by providing a @code{:require} keyword. Use @code{:group @var{group}} in @var{keyword-args} to specify the custom group for the mode variable of the global minor mode. + +Generally speaking, when you define a globalized minor mode, you should +also define a non-globalized version, so that people can use (or +disable) it in individual buffers. This also allows them to disable a +globally enabled minor mode in a specific major mode, by using that +mode's hook. @end defmac + @node Mode Line Format @section Mode-Line Format @cindex mode line diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 6768ecece9c..82336aa537f 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -168,34 +168,37 @@ character codepoint. @node Float Basics @section Floating Point Basics +@cindex @acronym{IEEE} floating point Floating point numbers are useful for representing numbers that are not integral. The precise range of floating point numbers is machine-specific; it is the same as the range of the C data type -@code{double} on the machine you are using. +@code{double} on the machine you are using. Emacs uses the +@acronym{IEEE} floating point standard where possible (the standard is +supported by most modern computers). - The read-syntax for floating point numbers requires either a decimal + The read syntax for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point number whose -value is 1500. They are all equivalent. You can also use a minus sign -to write negative floating point numbers, as in @samp{-1.0}. +value is 1500. They are all equivalent. You can also use a minus +sign to write negative floating point numbers, as in @samp{-1.0}. + + Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with +respect to @code{equal} and @code{=}), even though the two are +distinguishable in the @acronym{IEEE} floating point standard. -@cindex @acronym{IEEE} floating point @cindex positive infinity @cindex negative infinity @cindex infinity @cindex NaN - Most modern computers support the @acronym{IEEE} floating point standard, -which provides for positive infinity and negative infinity as floating point -values. It also provides for a class of values called NaN or -``not-a-number''; numerical functions return such values in cases where -there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a -NaN. For practical purposes, there's no significant difference between -different NaN values in Emacs Lisp, and there's no rule for precisely -which NaN value should be used in a particular case, so Emacs Lisp -doesn't try to distinguish them (but it does report the sign, if you -print it). Here are the read syntaxes for these special floating -point values: + The @acronym{IEEE} floating point standard supports positive +infinity and negative infinity as floating point values. It also +provides for a class of values called NaN or ``not-a-number''; +numerical functions return such values in cases where there is no +correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN +values can also carry a sign, but for practical purposes there's no +significant difference between different NaN values in Emacs Lisp.) +Here are the read syntaxes for these special floating point values: @table @asis @item positive infinity @@ -206,16 +209,37 @@ point values: @samp{0.0e+NaN} or @samp{-0.0e+NaN}. @end table - To test whether a floating point value is a NaN, compare it with -itself using @code{=}. That returns @code{nil} for a NaN, and -@code{t} for any other floating point value. +@defun isnan number +This predicate tests whether its argument is NaN, and returns @code{t} +if so, @code{nil} otherwise. The argument must be a number. +@end defun + + The following functions are specialized for handling floating point +numbers: + +@defun frexp x +This function returns a cons cell @code{(@var{sig} . @var{exp})}, +where @var{sig} and @var{exp} are respectively the significand and +exponent of the floating point number @var{x}: + +@smallexample +@var{x} = @var{sig} * 2^@var{exp} +@end smallexample + +@var{sig} is a floating point number between 0.5 (inclusive) and 1.0 +(exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}. +@end defun - The value @code{-0.0} is distinguishable from ordinary zero in -@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and -@code{=} consider them equal values. +@defun ldexp sig &optional exp +This function returns a floating point number corresponding to the +significand @var{sig} and exponent @var{exp}. +@end defun - You can use @code{logb} to extract the binary exponent of a floating -point number (or estimate the logarithm of an integer): +@defun copysign x1 x2 +This function copies the sign of @var{x2} to the value of @var{x1}, +and returns the result. @var{x1} and @var{x2} must be floating point +numbers. +@end defun @defun logb number This function returns the binary exponent of @var{number}. More @@ -230,14 +254,6 @@ down to an integer. @end example @end defun -@defvar float-e -The mathematical constant @math{e} (2.71828@dots{}). -@end defvar - -@defvar float-pi -The mathematical constant @math{pi} (3.14159@dots{}). -@end defvar - @node Predicates on Numbers @section Type Predicates for Numbers @cindex predicates for numbers @@ -266,15 +282,15 @@ This predicate tests whether its argument is a number (either integer or floating point), and returns @code{t} if so, @code{nil} otherwise. @end defun -@defun wholenump object +@defun natnump object @cindex natural numbers -The @code{wholenump} predicate (whose name comes from the phrase -``whole-number-p'') tests to see whether its argument is a nonnegative -integer, and returns @code{t} if so, @code{nil} otherwise. 0 is -considered non-negative. +This predicate (whose name comes from the phrase ``natural number'') +tests to see whether its argument is a nonnegative integer, and +returns @code{t} if so, @code{nil} otherwise. 0 is considered +non-negative. -@findex natnump -@code{natnump} is an obsolete synonym for @code{wholenump}. +@findex wholenump number +This is a synonym for @code{natnump}. @end defun @defun zerop number @@ -1122,35 +1138,15 @@ angle in radians between the vector @code{[@var{x}, @var{y}]} and the @end defun @defun exp arg -This is the exponential function; it returns -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -to the power @var{arg}. -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is a fundamental mathematical constant also called the base of natural -logarithms. +This is the exponential function; it returns @math{e} to the power +@var{arg}. @end defun @defun log arg &optional base -This function returns the logarithm of @var{arg}, with base @var{base}. -If you don't specify @var{base}, the base -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is used. If @var{arg} is negative, it signals a @code{domain-error} -error. +This function returns the logarithm of @var{arg}, with base +@var{base}. If you don't specify @var{base}, the natural base +@math{e} is used. If @var{arg} is negative, it signals a +@code{domain-error} error. @end defun @ignore @@ -1185,6 +1181,17 @@ This returns the square root of @var{arg}. If @var{arg} is negative, it signals a @code{domain-error} error. @end defun +In addition, Emacs defines the following common mathematical +constants: + +@defvar float-e +The mathematical constant @math{e} (2.71828@dots{}). +@end defvar + +@defvar float-pi +The mathematical constant @math{pi} (3.14159@dots{}). +@end defvar + @node Random Numbers @section Random Numbers @cindex random numbers @@ -1218,7 +1225,6 @@ nonnegative and less than @var{limit}. If @var{limit} is @code{t}, it means to choose a new seed based on the current time of day and on Emacs's process @acronym{ID} number. -@c "Emacs'" is incorrect usage! On some machines, any integer representable in Lisp may be the result of @code{random}. On other machines, the result can never be larger diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 3fb676edcd4..995a4d89352 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -427,10 +427,10 @@ codes for these non-@acronym{ASCII} control characters include the @ifnottex 2**26 @end ifnottex -bit as well as the code for the corresponding non-control -character. Ordinary terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using X -and other window systems. +bit as well as the code for the corresponding non-control character. +Ordinary text terminals have no way of generating non-@acronym{ASCII} +control characters, but you can generate them straightforwardly using +X and other window systems. For historical reasons, Emacs treats the @key{DEL} character as the control equivalent of @kbd{?}: @@ -501,10 +501,10 @@ character is upper case or lower case. Emacs uses the @end ifnottex bit to indicate that the shift key was used in typing a control character. This distinction is possible only when you use X terminals -or other special terminals; ordinary terminals do not report the -distinction to the computer in any way. The Lisp syntax for -the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} -represents the shifted-control-o character. +or other special terminals; ordinary text terminals do not report the +distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus, +@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o +character. @cindex hyper characters @cindex super characters @@ -541,9 +541,9 @@ intended. But you can use one symbol in all of these ways, independently. A symbol whose name starts with a colon (@samp{:}) is called a -@dfn{keyword symbol}. These symbols automatically act as constants, and -are normally used only by comparing an unknown symbol with a few -specific alternatives. +@dfn{keyword symbol}. These symbols automatically act as constants, +and are normally used only by comparing an unknown symbol with a few +specific alternatives. @xref{Constant Variables}. @cindex @samp{\} in symbols @cindex backslash in symbols @@ -617,26 +617,28 @@ all symbols; @pxref{Creating Symbols}.) @subsection Sequence Types A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp, lists and -arrays. Thus, an object of type list or of type array is also -considered a sequence. - - Arrays are further subdivided into strings, vectors, char-tables and -bool-vectors. Vectors can hold elements of any type, but string -elements must be characters, and bool-vector elements must be @code{t} -or @code{nil}. Char-tables are like vectors except that they are -indexed by any valid character code. The characters in a string can -have text properties like characters in a buffer (@pxref{Text -Properties}), but vectors do not support text properties, even when -their elements happen to be characters. - - Lists, strings and the other array types are different, but they have -important similarities. For example, all have a length @var{l}, and all -have elements which can be indexed from zero to @var{l} minus one. -Several functions, called sequence functions, accept any kind of -sequence. For example, the function @code{elt} can be used to extract -an element of a sequence, given its index. @xref{Sequences Arrays -Vectors}. +elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists} +and @dfn{arrays}. + + Lists are the most commonly-used sequences. A list can hold +elements of any type, and its length can be easily changed by adding +or removing elements. See the next subsection for more about lists. + + Arrays are fixed-length sequences. They are further subdivided into +strings, vectors, char-tables and bool-vectors. Vectors can hold +elements of any type, whereas string elements must be characters, and +bool-vector elements must be @code{t} or @code{nil}. Char-tables are +like vectors except that they are indexed by any valid character code. +The characters in a string can have text properties like characters in +a buffer (@pxref{Text Properties}), but vectors do not support text +properties, even when their elements happen to be characters. + + Lists, strings and the other array types also share important +similarities. For example, all have a length @var{l}, and all have +elements which can be indexed from zero to @var{l} minus one. Several +functions, called sequence functions, accept any kind of sequence. +For example, the function @code{length} reports the length of any kind +of sequence. @xref{Sequences Arrays Vectors}. It is generally impossible to read the same sequence twice, since sequences are always created anew upon reading. If you read the read @@ -650,24 +652,27 @@ same object, @code{nil}. @cindex decrement field of register @cindex pointers - A @dfn{cons cell} is an object that consists of two slots, called the -@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or -@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of -this cons cell is'' whatever object its @sc{car} slot currently holds, -and likewise for the @sc{cdr}. - -@quotation -A note to C programmers: in Lisp, we do not distinguish between -``holding'' a value and ``pointing to'' the value, because pointers in -Lisp are implicit. -@end quotation + A @dfn{cons cell} is an object that consists of two slots, called +the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any +Lisp object. We also say that ``the @sc{car} of this cons cell is'' +whatever object its @sc{car} slot currently holds, and likewise for +the @sc{cdr}. +@cindex list structure A @dfn{list} is a series of cons cells, linked together so that the @sc{cdr} slot of each cons cell holds either the next cons cell or the empty list. The empty list is actually the symbol @code{nil}. -@xref{Lists}, for functions that work on lists. Because most cons -cells are used as part of lists, the phrase @dfn{list structure} has -come to refer to any structure made out of cons cells. +@xref{Lists}, for details. Because most cons cells are used as part +of lists, we refer to any structure made out of cons cells as a +@dfn{list structure}. + +@cindex linked list +@quotation +A note to C programmers: a Lisp list thus works as a @dfn{linked list} +built up of cons cells. Because pointers in Lisp are implicit, we do +not distinguish between a cons cell slot ``holding'' a value versus +``pointing to'' the value. +@end quotation @cindex atoms Because cons cells are so central to Lisp, we also have a word for @@ -1025,40 +1030,40 @@ but the newline is ignored if escaped." @node Non-ASCII in Strings @subsubsection Non-@acronym{ASCII} Characters in Strings - You can include a non-@acronym{ASCII} international character in a string -constant by writing it literally. There are two text representations -for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte -and multibyte. If the string constant is read from a multibyte source, -such as a multibyte buffer or string, or a file that would be visited as -multibyte, then the character is read as a multibyte character, and that -makes the string multibyte. If the string constant is read from a -unibyte source, then the character is read as unibyte and that makes the -string unibyte. - - You can also represent a multibyte non-@acronym{ASCII} character with its -character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many -digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all -greater than 256.) Any character which is not a valid hex digit -terminates this construct. If the next character in the string could be -interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to -terminate the hex escape---for example, @w{@samp{\xe0\ }} represents -one character, @samp{a} with grave accent. @w{@samp{\ }} in a string -constant is just like backslash-newline; it does not contribute any -character to the string, but it does terminate the preceding hex escape. + You can include a non-@acronym{ASCII} international character in a +string constant by writing it literally. There are two text +representations for non-@acronym{ASCII} characters in Emacs strings +(and in buffers): unibyte and multibyte (@pxref{Text +Representations}). If the string constant is read from a multibyte +source, such as a multibyte buffer or string, or a file that would be +visited as multibyte, then Emacs reads the non-@acronym{ASCII} +character as a multibyte character and automatically makes the string +a multibyte string. If the string constant is read from a unibyte +source, then Emacs reads the non-@acronym{ASCII} character as unibyte, +and makes the string unibyte. + + Instead of writing a non-@acronym{ASCII} character literally into a +multibyte string, you can write it as its character code using a hex +escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary. +(Multibyte non-@acronym{ASCII} character codes are all greater than +256.) You can also specify a character in a multibyte string using +the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General +Escape Syntax}). In either case, any character which is not a valid +hex digit terminates the construct. If the next character in the +string could be interpreted as a hex digit, write @w{@samp{\ }} +(backslash and space) to terminate the hex escape---for example, +@w{@samp{\xe0\ }} represents one character, @samp{a} with grave +accent. @w{@samp{\ }} in a string constant is just like +backslash-newline; it does not contribute any character to the string, +but it does terminate the preceding hex escape. Using any hex escape +in a string (even for an @acronym{ASCII} character) automatically +forces the string to be multibyte. You can represent a unibyte non-@acronym{ASCII} character with its character code, which must be in the range from 128 (0200 octal) to 255 (0377 octal). If you write all such character codes in octal and the string contains no other characters forcing it to be multibyte, -this produces a unibyte string. However, using any hex escape in a -string (even for an @acronym{ASCII} character) forces the string to be -multibyte. - - You can also specify characters in a string by their numeric values -in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}). - - @xref{Text Representations}, for more information about the two -text representations. +this produces a unibyte string. @node Nonprinting Characters @subsubsection Nonprinting Characters in Strings @@ -1318,11 +1323,11 @@ with the name of the subroutine. @node Byte-Code Type @subsection Byte-Code Function Type -The byte compiler produces @dfn{byte-code function objects}. -Internally, a byte-code function object is much like a vector; however, -the evaluator handles this data type specially when it appears as a -function to be called. @xref{Byte Compilation}, for information about -the byte compiler. +@dfn{Byte-code function objects} are produced by byte-compiling Lisp +code (@pxref{Byte Compilation}). Internally, a byte-code function +object is much like a vector; however, the evaluator handles this data +type specially when it appears in a function call. @xref{Byte-Code +Objects}. The printed representation and read syntax for a byte-code function object is like that for a vector, with an additional @samp{#} before the @@ -1790,6 +1795,9 @@ with references to further information. @item consp @xref{List-related Predicates, consp}. +@item custom-variable-p +@xref{Variable Definitions, custom-variable-p}. + @item display-table-p @xref{Display Tables, display-table-p}. @@ -1865,9 +1873,6 @@ with references to further information. @item syntax-table-p @xref{Syntax Tables, syntax-table-p}. -@item user-variable-p -@xref{Defining Variables, user-variable-p}. - @item vectorp @xref{Vectors, vectorp}. @@ -1922,23 +1927,24 @@ This function returns a symbol naming the primitive type of @section Equality Predicates @cindex equality - Here we describe functions that test for equality between any two -objects. Other functions test equality of contents between objects of specific -types, e.g., strings. For these predicates, see the appropriate chapter -describing the data type. + Here we describe functions that test for equality between two +objects. Other functions test equality of contents between objects of +specific types, e.g.@: strings. For these predicates, see the +appropriate chapter describing the data type. @defun eq object1 object2 This function returns @code{t} if @var{object1} and @var{object2} are -the same object, @code{nil} otherwise. - -@code{eq} returns @code{t} if @var{object1} and @var{object2} are -integers with the same value. Also, since symbol names are normally -unique, if the arguments are symbols with the same name, they are -@code{eq}. For other types (e.g., lists, vectors, strings), two -arguments with the same contents or elements are not necessarily -@code{eq} to each other: they are @code{eq} only if they are the same -object, meaning that a change in the contents of one will be reflected -by the same change in the contents of the other. +the same object, and @code{nil} otherwise. + +If @var{object1} and @var{object2} are integers with the same value, +they are considered to be the same object (i.e.@: @code{eq} returns +@code{t}). If @var{object1} and @var{object2} are symbols with the +same name, they are normally the same object---but see @ref{Creating +Symbols} for exceptions. For other types (e.g.@: lists, vectors, +strings), two arguments with the same contents or elements are not +necessarily @code{eq} to each other: they are @code{eq} only if they +are the same object, meaning that a change in the contents of one will +be reflected by the same change in the contents of the other. @example @group @@ -1988,6 +1994,7 @@ by the same change in the contents of the other. @end group @end example +@noindent The @code{make-symbol} function returns an uninterned symbol, distinct from the symbol that is used if you write the name in a Lisp expression. Distinct symbols with the same name are not @code{eq}. @xref{Creating @@ -2003,11 +2010,11 @@ Symbols}. @defun equal object1 object2 This function returns @code{t} if @var{object1} and @var{object2} have -equal components, @code{nil} otherwise. Whereas @code{eq} tests if its -arguments are the same object, @code{equal} looks inside nonidentical -arguments to see if their elements or contents are the same. So, if two -objects are @code{eq}, they are @code{equal}, but the converse is not -always true. +equal components, and @code{nil} otherwise. Whereas @code{eq} tests +if its arguments are the same object, @code{equal} looks inside +nonidentical arguments to see if their elements or contents are the +same. So, if two objects are @code{eq}, they are @code{equal}, but +the converse is not always true. @example @group @@ -2059,13 +2066,13 @@ always true. @end example Comparison of strings is case-sensitive, but does not take account of -text properties---it compares only the characters in the strings. Use -@code{equal-including-properties} to also compare text properties. For -technical reasons, a unibyte string and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -(@pxref{Text Representations}). +text properties---it compares only the characters in the strings. +@xref{Text Properties}. Use @code{equal-including-properties} to also +compare text properties. For technical reasons, a unibyte string and +a multibyte string are @code{equal} if and only if they contain the +same sequence of character codes and all these codes are either in the +range 0 through 127 (@acronym{ASCII}) or 160 through 255 +(@code{eight-bit-graphic}). (@pxref{Text Representations}). @example @group diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 38eb5a86471..4cfc954cd1f 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -300,7 +300,8 @@ MS-DOS doesn't support asynchronous subprocesses, so this option doesn't work there. @item @code{(:file @var{file-name})} -Send the output to the file name specified. +Send the output to the file name specified, overwriting it if it +already exists. @item @code{(@var{real-destination} @var{error-destination})} Keep the standard output stream separate from the standard error stream; diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 21481568276..3dc777897c1 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -49,7 +49,6 @@ This function searches forward from point for an exact match for @var{string}. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on @var{noerror} (see below). -@c Emacs 19 feature In the following example, point is initially at the beginning of the line. Then @code{(search-forward "fox")} moves point after the last @@ -91,18 +90,21 @@ The argument @var{noerror} only affects valid searches which fail to find a match. Invalid arguments cause errors regardless of @var{noerror}. -If @var{repeat} is supplied (it must be a positive number), then the -search is repeated that many times (each time starting at the end of the -previous time's match). If these successive searches succeed, the -function succeeds, moving point and returning its new value. Otherwise -the search fails, with results depending on the value of -@var{noerror}, as described above. +If @var{repeat} is a positive number @var{n}, it serves as a repeat +count: the search is repeated @var{n} times, each time starting at the +end of the previous time's match. If these successive searches +succeed, the function succeeds, moving point and returning its new +value. Otherwise the search fails, with results depending on the +value of @var{noerror}, as described above. If @var{repeat} is a +negative number -@var{n}, it serves as a repeat count of @var{n} for a +search in the opposite (backward) direction. @end deffn @deffn Command search-backward string &optional limit noerror repeat This function searches backward from point for @var{string}. It is -just like @code{search-forward} except that it searches backwards and -leaves point at the beginning of the match. +like @code{search-forward}, except that it searches backwards rather +than forwards. Backward searches leave point at the beginning of the +match. @end deffn @deffn Command word-search-forward string &optional limit noerror repeat diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 0ea32f99e12..94f1bf666d2 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -8,10 +8,10 @@ @chapter Sequences, Arrays, and Vectors @cindex sequence - Recall that the @dfn{sequence} type is the union of two other Lisp -types: lists and arrays. In other words, any list is a sequence, and -any array is a sequence. The common property that all sequences have is -that each is an ordered collection of elements. + The @dfn{sequence} type is the union of two other Lisp types: lists +and arrays. In other words, any list is a sequence, and any array is +a sequence. The common property that all sequences have is that each +is an ordered collection of elements. An @dfn{array} is a fixed-length object with a slot for each of its elements. All the elements are accessible in constant time. The four @@ -54,19 +54,17 @@ But it is possible to add elements to the list, or remove elements. * Vector Functions:: Functions specifically for vectors. * Char-Tables:: How to work with char-tables. * Bool-Vectors:: How to work with bool-vectors. +* Rings:: Managing a fixed-size ring of objects. @end menu @node Sequence Functions @section Sequences - In Emacs Lisp, a @dfn{sequence} is either a list or an array. The -common property of all sequences is that they are ordered collections of -elements. This section describes functions that accept any kind of -sequence. + This section describes functions that accept any kind of sequence. @defun sequencep object -Returns @code{t} if @var{object} is a list, vector, string, -bool-vector, or char-table, @code{nil} otherwise. +This function returns @code{t} if @var{object} is a list, vector, +string, bool-vector, or char-table, @code{nil} otherwise. @end defun @defun length sequence @@ -149,8 +147,9 @@ This function generalizes @code{aref} (@pxref{Array Functions}) and @defun copy-sequence sequence @cindex copying sequences -Returns a copy of @var{sequence}. The copy is the same type of object -as the original sequence, and it has the same elements in the same order. +This function returns a copy of @var{sequence}. The copy is the same +type of object as the original sequence, and it has the same elements +in the same order. Storing a new element into the copy does not affect the original @var{sequence}, and vice versa. However, the elements of the new @@ -394,8 +393,8 @@ symbol-lookup tables (@pxref{Creating Symbols}), as part of the representation of a byte-compiled function (@pxref{Byte Compilation}), and more. - In Emacs Lisp, the indices of the elements of a vector start from zero -and count up from there. + Like other arrays, vectors use zero-origin indexing: the first +element has index 0. Vectors are printed with square brackets surrounding the elements. Thus, a vector whose elements are the symbols @code{a}, @code{b} and @@ -728,3 +727,96 @@ bv @noindent These results make sense because the binary codes for control-_ and control-W are 11111 and 10111, respectively. + +@node Rings +@section Managing a Fixed-Size Ring of Objects + +@cindex ring data structure + A @dfn{ring} is a fixed-size data structure that supports insertion, +deletion, rotation, and modulo-indexed reference and traversal. An +efficient ring data structure is implemented by the @code{ring} +package. It provides the functions listed in this section. + + Note that several ``rings'' in Emacs, like the kill ring and the +mark ring, are actually implemented as simple lists, @emph{not} using +the @code{ring} package; thus the following functions won't work on +them. + +@defun make-ring size +This returns a new ring capable of holding @var{size} objects. +@var{size} should be an integer. +@end defun + +@defun ring-p object +This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. +@end defun + +@defun ring-size ring +This returns the maximum capacity of the @var{ring}. +@end defun + +@defun ring-length ring +This returns the number of objects that @var{ring} currently contains. +The value will never exceed that returned by @code{ring-size}. +@end defun + +@defun ring-elements ring +This returns a list of the objects in @var{ring}, in order, newest first. +@end defun + +@defun ring-copy ring +This returns a new ring which is a copy of @var{ring}. +The new ring contains the same (@code{eq}) objects as @var{ring}. +@end defun + +@defun ring-empty-p ring +This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. +@end defun + + The newest element in the ring always has index 0. Higher indices +correspond to older elements. Indices are computed modulo the ring +length. Index @minus{}1 corresponds to the oldest element, @minus{}2 +to the next-oldest, and so forth. + +@defun ring-ref ring index +This returns the object in @var{ring} found at index @var{index}. +@var{index} may be negative or greater than the ring length. If +@var{ring} is empty, @code{ring-ref} signals an error. +@end defun + +@defun ring-insert ring object +This inserts @var{object} into @var{ring}, making it the newest +element, and returns @var{object}. + +If the ring is full, insertion removes the oldest element to +make room for the new element. +@end defun + +@defun ring-remove ring &optional index +Remove an object from @var{ring}, and return that object. The +argument @var{index} specifies which item to remove; if it is +@code{nil}, that means to remove the oldest item. If @var{ring} is +empty, @code{ring-remove} signals an error. +@end defun + +@defun ring-insert-at-beginning ring object +This inserts @var{object} into @var{ring}, treating it as the oldest +element. The return value is not significant. + +If the ring is full, this function removes the newest element to make +room for the inserted element. +@end defun + +@cindex fifo data structure + If you are careful not to exceed the ring size, you can +use the ring as a first-in-first-out queue. For example: + +@lisp +(let ((fifo (make-ring 5))) + (mapc (lambda (obj) (ring-insert fifo obj)) + '(0 one "two")) + (list (ring-remove fifo) t + (ring-remove fifo) t + (ring-remove fifo))) + @result{} (0 t one t "two") +@end lisp diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 49199d3e32f..bbb75f1474d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -410,8 +410,13 @@ in case if @code{case-fold-search} is non-@code{nil}. @defun string= string1 string2 This function returns @code{t} if the characters of the two strings match exactly. Symbols are also allowed as arguments, in which case -their print names are used. -Case is always significant, regardless of @code{case-fold-search}. +the symbol names are used. Case is always significant, regardless of +@code{case-fold-search}. + +This function is equivalent to @code{equal} for comparing two strings +(@pxref{Equality Predicates}). In particular, the text properties of +the two strings are ignored. But if either argument is not a string +or symbol, an error is signaled. @example (string= "abc" "abc") @@ -422,10 +427,6 @@ Case is always significant, regardless of @code{case-fold-search}. @result{} nil @end example -The function @code{string=} ignores the text properties of the two -strings. When @code{equal} (@pxref{Equality Predicates}) compares two -strings, it uses @code{string=}. - For technical reasons, a unibyte and a multibyte string are @code{equal} if and only if they contain the same sequence of character codes and all these codes are either in the range 0 through diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 866a63c4cd9..0ee22b905b6 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -41,62 +41,58 @@ references another object: @table @asis @item Print name @cindex print name cell -The @dfn{print name cell} holds a string that names the symbol for -reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. +The symbol's name. @item Value @cindex value cell -The @dfn{value cell} holds the current value of the symbol as a -variable. When a symbol is used as a form, the value of the form is the -contents of the symbol's value cell. See @code{symbol-value} in -@ref{Accessing Variables}. +The symbol's current value as a variable. @item Function @cindex function cell -The @dfn{function cell} holds the function definition of the symbol. -When a symbol is used as a function, its function definition is used in -its place. This cell is also used to make a symbol stand for a keymap -or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables names and function names do -not conflict. See @code{symbol-function} in @ref{Function Cells}. +The symbol's function definition. It can also hold a symbol, a +keymap, or a keyboard macro. @item Property list @cindex property list cell -The @dfn{property list cell} holds the property list of the symbol. See -@code{symbol-plist} in @ref{Property Lists}. +The symbol's property list. @end table - The print name cell always holds a string, and cannot be changed. The -other three cells can be set individually to any specified Lisp object. - - The print name cell holds the string that is the name of the symbol. -Since symbols are represented textually by their names, it is important -not to have two symbols with the same name. The Lisp reader ensures -this: every time it reads a symbol, it looks for an existing symbol with -the specified name before it creates a new one. (In GNU Emacs Lisp, -this lookup uses a hashing algorithm and an obarray; see @ref{Creating -Symbols}.) - - The value cell holds the symbol's value as a variable -(@pxref{Variables}). That is what you get if you evaluate the symbol as -a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate -value. Certain symbols have values that cannot be changed; these -include @code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. - - We often refer to ``the function @code{foo}'' when we really mean -the function stored in the function cell of the symbol @code{foo}. We -make the distinction explicit only when necessary. In normal -usage, the function cell usually contains a function -(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the -Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard -macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and -autoload objects (@pxref{Autoloading}) are also sometimes stored in -the function cells of symbols. +@noindent +The print name cell always holds a string, and cannot be changed. +Each of the other three cells can be set to any Lisp object. + + The print name cell holds the string that is the name of a symbol. +Since symbols are represented textually by their names, it is +important not to have two symbols with the same name. The Lisp reader +ensures this: every time it reads a symbol, it looks for an existing +symbol with the specified name before it creates a new one. To get a +symbol's name, use the function @code{symbol-name} (@pxref{Creating +Symbols}). + + The value cell holds a symbol's value as a variable, which is what +you get if the symbol itself is evaluated as a Lisp expression. +@xref{Variables}, for details about how values are set and retrieved, +including complications such as @dfn{local bindings} and @dfn{scoping +rules}. Most symbols can have any Lisp object as a value, but certain +special symbols have values that cannot be changed; these include +@code{nil} and @code{t}, and any symbol whose name starts with +@samp{:} (those are called @dfn{keywords}). @xref{Constant +Variables}. + + The function cell holds a symbol's function definition. Often, we +refer to ``the function @code{foo}'' when we really mean the function +stored in the function cell of @code{foo}; we make the distinction +explicit only when necessary. Typically, the function cell is used to +hold a function (@pxref{Functions}) or a macro (@pxref{Macros}). +However, it can also be used to hold a symbol (@pxref{Function +Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap +(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get +the contents of a symbol's function cell, use the function +@code{symbol-function} (@pxref{Function Cells}). The property list cell normally should hold a correctly formatted -property list (@pxref{Property Lists}), as a number of functions expect -to see a property list there. +property list. To get a symbol's function cell, use the function +@code{symbol-plist}. @xref{Property Lists}. The function cell or the value cell may be @dfn{void}, which means that the cell does not reference any object. (This is not the same @@ -104,57 +100,43 @@ thing as holding the symbol @code{void}, nor the same as holding the symbol @code{nil}.) Examining a function or value cell that is void results in an error, such as @samp{Symbol's value as variable is void}. - The four functions @code{symbol-name}, @code{symbol-value}, -@code{symbol-plist}, and @code{symbol-function} return the contents of -the four cells of a symbol. Here as an example we show the contents of -the four cells of the symbol @code{buffer-file-name}: + Because each symbol has separate value and function cells, variables +names and function names do not conflict. For example, the symbol +@code{buffer-file-name} has a value (the name of the file being +visited in the current buffer) as well as a function definition (a +primitive function that returns the name of the file): @example -(symbol-name 'buffer-file-name) - @result{} "buffer-file-name" -(symbol-value 'buffer-file-name) +buffer-file-name @result{} "/gnu/elisp/symbols.texi" (symbol-function 'buffer-file-name) @result{} #<subr buffer-file-name> -(symbol-plist 'buffer-file-name) - @result{} (variable-documentation 29529) @end example -@noindent -Because this symbol is the variable which holds the name of the file -being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the Emacs Lisp Manual. -The property list cell contains the list @code{(variable-documentation -29529)} which tells the documentation functions where to find the -documentation string for the variable @code{buffer-file-name} in the -@file{DOC-@var{version}} file. (29529 is the offset from the beginning -of the @file{DOC-@var{version}} file to where that documentation string -begins---see @ref{Documentation Basics}.) The function cell contains -the function for returning the name of the file. -@code{buffer-file-name} names a primitive function, which has no read -syntax and prints in hash notation (@pxref{Primitive Function Type}). A -symbol naming a function written in Lisp would have a lambda expression -(or a byte-code object) in this cell. - @node Definitions, Creating Symbols, Symbol Components, Symbols @section Defining Symbols @cindex definitions of symbols - A @dfn{definition} in Lisp is a special form that announces your -intention to use a certain symbol in a particular way. In Emacs Lisp, -you can define a symbol as a variable, or define it as a function (or -macro), or both independently. - - A definition construct typically specifies a value or meaning for the -symbol for one kind of use, plus documentation for its meaning when used -in this way. Thus, when you define a symbol as a variable, you can -supply an initial value for the variable, plus documentation for the -variable. + A @dfn{definition} is a special kind of Lisp expression that +announces your intention to use a symbol in a particular way. It +typically specifies a value or meaning for the symbol for one kind of +use, plus documentation for its meaning when used in this way. Thus, +when you define a symbol as a variable, you can supply an initial +value for the variable, plus documentation for the variable. @code{defvar} and @code{defconst} are special forms that define a -symbol as a global variable. They are documented in detail in -@ref{Defining Variables}. For defining user option variables that can -be customized, use @code{defcustom} (@pxref{Customization}). +symbol as a @dfn{global variable}---a variable that can be accessed at +any point in a Lisp program. @xref{Variables}, for details about +variables. To define a customizable variable, use the +@code{defcustom} macro, which also calls @code{defvar} as a subroutine +(@pxref{Customization}). + + In principle, you can assign a variable value to any symbol with +@code{setq}, whether not it has first been defined as a variable. +However, you ought to write a variable definition for each global +variable that you want to use; otherwise, your Lisp program may not +act correctly if it is evaluated with lexical scoping enabled +(@pxref{Variable Scoping}). @code{defun} defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This @@ -171,15 +153,14 @@ both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. @xref{Macros}. - In Emacs Lisp, a definition is not required in order to use a symbol -as a variable or function. Thus, you can make a symbol a global -variable with @code{setq}, whether you define it first or not. The real -purpose of definitions is to guide programmers and programming tools. -They inform programmers who read the code that certain symbols are -@emph{intended} to be used as variables, or as functions. In addition, -utilities such as @file{etags} and @file{make-docfile} recognize -definitions, and add appropriate information to tag tables and the -@file{DOC-@var{version}} file. @xref{Accessing Documentation}. + As previously noted, Emacs Lisp allows the same symbol to be defined +both as a variable (e.g.@: with @code{defvar}) and as a function or +macro (e.g.@: with @code{defun}). Such definitions do not conflict. + + These definition also act as guides for programming tools. For +example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers +containing links to the relevant variable, function, or macro +definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. @node Creating Symbols, Property Lists, Definitions, Symbols @section Creating and Interning Symbols @@ -254,8 +235,8 @@ not work---only @code{intern} can enter a symbol in an obarray properly. @cindex CL note---symbol in obarrays @quotation -@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in -several obarrays. +@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide +for interning a single symbol in several obarrays. @end quotation Most of the functions below take a name and sometimes an obarray as @@ -448,12 +429,13 @@ must be distinct. Property lists are better than association lists for attaching information to various Lisp function names or variables. If your -program keeps all of its associations in one association list, it will +program keeps all such information in one association list, it will typically need to search that entire list each time it checks for an -association. This could be slow. By contrast, if you keep the same -information in the property lists of the function names or variables -themselves, each search will scan only the length of one property list, -which is usually short. This is why the documentation for a variable is +association for a particular Lisp function name or variable, which +could be slow. By contrast, if you keep the same information in the +property lists of the function names or variables themselves, each +search will scan only the length of one property list, which is +usually short. This is why the documentation for a variable is recorded in a property named @code{variable-documentation}. The byte compiler likewise uses properties to record those functions needing special treatment. diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index dc215b1e0e6..3d153e43b2d 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -128,10 +128,10 @@ their meanings, and examples of their use. @deffn {Syntax class} @w{whitespace character} @dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-}) separate symbols and words from each other. Typically, whitespace -characters have no other syntactic significance, and multiple whitespace -characters are syntactically equivalent to a single one. Space, tab, -newline and formfeed are classified as whitespace in almost all major -modes. +characters have no other syntactic significance, and multiple +whitespace characters are syntactically equivalent to a single one. +Space, tab, and formfeed are classified as whitespace in almost all +major modes. @end deffn @deffn {Syntax class} @w{word constituent} @@ -606,11 +606,13 @@ expression prefix syntax class, and characters with the @samp{p} flag. @section Parsing Expressions This section describes functions for parsing and scanning balanced -expressions, also known as @dfn{sexps}. Basically, a sexp is either a -balanced parenthetical grouping, a string, or a symbol name (a -sequence of characters whose syntax is either word constituent or -symbol constituent). However, characters whose syntax is expression -prefix are treated as part of the sexp if they appear next to it. +expressions. We will refer to such expressions as @dfn{sexps}, +following the terminology of Lisp, even though these functions can act +on languages other than Lisp. Basically, a sexp is either a balanced +parenthetical grouping, a string, or a ``symbol'' (i.e.@: a sequence +of characters whose syntax is either word constituent or symbol +constituent). However, characters whose syntax is expression prefix +are treated as part of the sexp if they appear next to it. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C @@ -830,10 +832,6 @@ The value is @code{nil} if @var{state} represents a parse which has arrived at a top level position. @end defun - We have provided this access function rather than document how the -data is represented in the state, because we plan to change the -representation in the future. - @node Low-Level Parsing @subsection Low-Level Parsing diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index b75c013298f..416bfef4a60 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -56,7 +56,7 @@ the character after point. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Checksum/Hash:: Computing "message digests"/"checksums"/"hashes". * Parsing HTML:: Parsing HTML and XML. * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. @@ -218,44 +218,46 @@ This is like @code{buffer-substring}, except that it does not copy text properties, just the characters themselves. @xref{Text Properties}. @end defun -@defun filter-buffer-substring start end &optional delete noprops +@defun filter-buffer-substring start end &optional delete This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the variable -@code{buffer-substring-filters}, and returns the value from the last -filter function. If @code{buffer-substring-filters} is @code{nil}, -the value is the unaltered text from the buffer, what -@code{buffer-substring} would return. +through the filter functions specified by the wrapper hook +@code{filter-buffer-substring-functions}, and returns the final +result of applying all filters. The obsolete variable +@code{buffer-substring-filters} is also consulted. If both of these +variables are @code{nil}, the value is the unaltered text from the +buffer, as @code{buffer-substring} would return. If @var{delete} is non-@code{nil}, this function deletes the text between @var{start} and @var{end} after copying it, like @code{delete-and-extract-region}. -If @var{noprops} is non-@code{nil}, the final string returned does not -include text properties, while the string passed through the filters -still includes text properties from the buffer text. - Lisp code should use this function instead of @code{buffer-substring}, @code{buffer-substring-no-properties}, or @code{delete-and-extract-region} when copying into user-accessible data structures such as the kill-ring, X clipboard, and registers. Major and minor modes can add functions to -@code{buffer-substring-filters} to alter such text as it is copied out -of the buffer. +@code{filter-buffer-substring-functions} to alter such text as it is +copied out of the buffer. @end defun -@defvar buffer-substring-filters -This variable should be a list of functions that accept a single -argument, a string, and return a string. -@code{filter-buffer-substring} passes the buffer substring to the -first function in this list, and the return value of each function is -passed to the next function. The return value of the last function is -used as the return value of @code{filter-buffer-substring}. - -As a special convention, point is set to the start of the buffer text -being operated on (i.e., the @var{start} argument for -@code{filter-buffer-substring}) before these functions are called. - -If this variable is @code{nil}, no filtering is performed. +@defvar filter-buffer-substring-functions +This variable is a wrapper hook (@pxref{Running Hooks}), whose members +should be functions that accept four arguments: @var{fun}, +@var{start}, @var{end}, and @var{delete}. @var{fun} is a function +that takes three arguments (@var{start}, @var{end}, and @var{delete}), +and returns a string. In both cases, the @var{start}, @var{end}, and +@var{delete} arguments are the same as those of +@code{filter-buffer-substring}. + +The first hook function is passed a @var{fun} that is equivalent to +the default operation of @code{filter-buffer-substring}, i.e. it +returns the buffer-substring between @var{start} and @var{end} +(processed by any @code{buffer-substring-filters}) and optionally +deletes the original text from the buffer. In most cases, the hook +function will call @var{fun} once, and then do its own processing of +the result. The next hook function receives a @var{fun} equivalent to +this, and so on. The actual return value is the result of all the +hook functions acting in sequence. @end defvar @defun buffer-string @@ -500,6 +502,11 @@ syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also responsible for calling @code{blink-paren-function} when the inserted character has close parenthesis syntax (@pxref{Blinking}). +@vindex post-self-insert-hook +The final thing this command does is to run the hook +@code{post-self-insert-hook}. You could use this to automatically +reindent text as it is typed, for example. + Do not try substituting your own definition of @code{self-insert-command} for the standard one. The editor command loop handles this function specially. @@ -3991,7 +3998,7 @@ changed in the future. @node Transposition @section Transposition of Text - This subroutine is used by the transposition commands. + This function can be used to transpose stretches of text: @defun transpose-regions start1 end1 start2 end2 &optional leave-markers This function exchanges two nonoverlapping portions of the buffer. @@ -4064,9 +4071,11 @@ decoded text. The decoding functions ignore newline characters in the encoded text. @end defun -@node MD5 Checksum -@section MD5 Checksum +@node Checksum/Hash +@section Checksum/Hash @cindex MD5 checksum +@cindex hashing, secure +@cindex SHA-1 @cindex message digest computation MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit @@ -4077,7 +4086,7 @@ RFC@footnote{ For an explanation of what is an RFC, see the footnote in @ref{Base 64}. }1321. This section describes the Emacs facilities for computing -message digests. +message digests and other forms of ``secure hash''. @defun md5 object &optional start end coding-system noerror This function returns the MD5 message digest of @var{object}, which @@ -4112,6 +4121,16 @@ using the specified or chosen coding system. However, if coding instead. @end defun +@defun secure-hash algorithm object &optional start end binary +This function provides a general interface to a variety of secure +hashing algorithms. As well as the MD5 algorithm, it supports SHA-1, +SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. The argument +@var{algorithm} is a symbol stating which hash to compute. The +arguments @var{object}, @var{start}, and @var{end} are as for the +@code{md5} function. If the optional argument @var{binary} is +non-@code{nil}, returns a string in binary form. +@end defun + @node Parsing HTML @section Parsing HTML @cindex parsing html diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index b0a6795021b..ab3a4edc0ac 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -8,20 +8,20 @@ @cindex variable A @dfn{variable} is a name used in a program to stand for a value. -Nearly all programming languages have variables of some sort. In the -text of a Lisp program, variables are written using the syntax for -symbols. - - In Lisp, unlike most programming languages, programs are represented -primarily as Lisp objects and only secondarily as text. The Lisp -objects used for variables are symbols: the symbol name is the -variable name, and the variable's value is stored in the value cell of -the symbol. The use of a symbol as a variable is independent of its -use as a function name. @xref{Symbol Components}. - - The textual form of a Lisp program is given by the read syntax of -the Lisp objects that constitute the program. Hence, a variable in a -textual Lisp program is written using the read syntax for the symbol +In Lisp, each variable is represented by a Lisp symbol +(@pxref{Symbols}). The variable name is simply the symbol's name, and +the variable's value is stored in the symbol's value cell@footnote{To +be precise, under the default @dfn{dynamic binding} rules the value +cell always holds the variable's current value, but this is not the +case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for +details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a +symbol as a variable is independent of its use as a function name. + + As previously noted in this manual, a Lisp program is represented +primarily by Lisp objects, and only secondarily as text. The textual +form of a Lisp program is given by the read syntax of the Lisp objects +that constitute the program. Hence, the textual form of a variable in +a Lisp program is written using the read syntax for the symbol representing the variable. @menu @@ -145,63 +145,63 @@ does not raise an error if you actually change it. @cindex global binding Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to create variable values that -exist temporarily---only until a certain part of the program finishes. -These values are called @dfn{local}, and the variables so used are -called @dfn{local variables}. - - For example, when a function is called, its argument variables receive -new local values that last until the function exits. The @code{let} -special form explicitly establishes new local values for specified -variables; these last until exit from the @code{let} form. - -@cindex shadowing of variables - Establishing a local value saves away the variable's previous value -(or lack of one). We say that the previous value is @dfn{shadowed} -and @dfn{not visible}. Both global and local values may be shadowed -(@pxref{Scope}). After the life span of the local value is over, the -previous value (or lack of one) is restored. - - If you set a variable (such as with @code{setq}) while it is local, -this replaces the local value; it does not alter the global value, or -previous local values, that are shadowed. To model this behavior, we -speak of a @dfn{local binding} of the variable as well as a local value. - - The local binding is a conceptual place that holds a local value. -Entering a function, or a special form such as @code{let}, creates the -local binding; exiting the function or the @code{let} removes the -local binding. While the local binding lasts, the variable's value is -stored within it. Using @code{setq} or @code{set} while there is a -local binding stores a different value into the local binding; it does -not create a new binding. +with new values. Sometimes it is useful to give a variable a +@dfn{local value}---a value that takes effect only within a certain +part of a Lisp program. When a variable has a local value, we say +that it is @dfn{locally bound} to that value, and that it is a +@dfn{local variable}. + + For example, when a function is called, its argument variables +receive local values, which are the actual arguments supplied to the +function call; these local bindings take effect within the body of the +function. To take another example, the @code{let} special form +explicitly establishes local bindings for specific variables, which +take effect within the body of the @code{let} form. We also speak of the @dfn{global binding}, which is where (conceptually) the global value is kept. +@cindex shadowing of variables + Establishing a local binding saves away the variable's previous +value (or lack of one). We say that the previous value is +@dfn{shadowed}. Both global and local values may be shadowed. If a +local binding is in effect, using @code{setq} on the local variable +stores the specified value in the local binding. When that local +binding is no longer in effect, the previously shadowed value (or lack +of one) comes back. + @cindex current binding - A variable can have more than one local binding at a time (for -example, if there are nested @code{let} forms that bind it). In such a -case, the most recently created local binding that still exists is the -@dfn{current binding} of the variable. (This rule is called -@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no -local bindings, the variable's global binding is its current binding. -We sometimes call the current binding the @dfn{most-local existing -binding}, for emphasis. Ordinary evaluation of a symbol always returns -the value of its current binding. - - The special forms @code{let} and @code{let*} exist to create -local bindings. + A variable can have more than one local binding at a time (e.g.@: if +there are nested @code{let} forms that bind the variable). The +@dfn{current binding} is the local binding that is actually in effect. +It determines the value returned by evaluating the variable symbol, +and it is the binding acted on by @code{setq}. + + For most purposes, you can think of the current binding as the +``innermost'' local binding, or the global binding if there is no +local binding. To be more precise, a rule called the @dfn{scoping +rule} determines where in a program a local binding takes effect. The +default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, +which simply states that the current binding at any given point in the +execution of a program is the most recently-created binding for that +variable that still exists. For details about dynamic scoping, and an +alternative scoping rule called @dfn{lexical scoping}, @xref{Variable +Scoping}. + + The special forms @code{let} and @code{let*} exist to create local +bindings: @defspec let (bindings@dots{}) forms@dots{} -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}. +This special form sets up local bindings for a certain set of +variables, as specified by @var{bindings}, and then evaluates all of +the @var{forms} in textual order. Its return value is the value of +the last form in @var{forms}. Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is bound to @code{nil}; or @w{(ii) a} list of the form -@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is -bound to the result of evaluating @var{value-form}. If @var{value-form} -is omitted, @code{nil} is used. +that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the +form @code{(@var{symbol} @var{value-form})}, in which case +@var{symbol} is locally bound to the result of evaluating +@var{value-form}. If @var{value-form} is omitted, @code{nil} is used. All of the @var{value-form}s in @var{bindings} are evaluated in the order they appear and @emph{before} binding any of the symbols to them. @@ -213,6 +213,7 @@ Here is an example of this: @code{z} is bound to the old value of (setq y 2) @result{} 2 @end group + @group (let ((y 1) (z y)) @@ -226,15 +227,15 @@ Here is an example of this: @code{z} is bound to the old value of This special form is like @code{let}, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in @var{bindings} can -reasonably refer to the preceding symbols bound in this @code{let*} -form. Compare the following example with the example above for -@code{let}. +refer to the preceding symbols bound in this @code{let*} form. +Compare the following example with the example above for @code{let}. @example @group (setq y 2) @result{} 2 @end group + @group (let* ((y 1) (z y)) ; @r{Use the just-established value of @code{y}.} @@ -262,7 +263,7 @@ Macro calls (@pxref{Macros}). Variables}); a few variables have terminal-local bindings (@pxref{Multiple Terminals}). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs, rather than localized in time. +``where'' you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -280,7 +281,7 @@ that Lisp avoids infinite recursion on an ill-defined function. @code{max-lisp-eval-depth} provides another limit on depth of nesting. @xref{Definition of max-lisp-eval-depth,, Eval}. -The default value is 1000. Entry to the Lisp debugger increases the +The default value is 1300. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. @end defopt @@ -290,46 +291,33 @@ has room to execute. @cindex @code{void-variable} error @cindex void variable - If you have never given a symbol any value as a global variable, we -say that that symbol's global value is @dfn{void}. In other words, the -symbol's value cell does not have any Lisp object in it. If you try to -evaluate the symbol, you get a @code{void-variable} error rather than -a value. - - Note that a value of @code{nil} is not the same as void. The symbol -@code{nil} is a Lisp object and can be the value of a variable just as any -other object can be; but it is @emph{a value}. A void variable does not -have any value. - - After you have given a variable a value, you can make it void once more -using @code{makunbound}. + We say that a variable is void if its symbol has an unassigned value +cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic +binding rules (@pxref{Variable Scoping}), the value cell stores the +variable's current (local or global) value. Note that an unassigned +value cell is @emph{not} the same as having @code{nil} in the value +cell. The symbol @code{nil} is a Lisp object and can be the value of +a variable, just as any other object can be; but it is still a value. +If a variable is void, trying to evaluate the variable signals a +@code{void-variable} error rather than a value. + + Under lexical binding rules, the value cell only holds the +variable's global value, i.e.@: the value outside of any lexical +binding contruct. When a variable is lexically bound, the local value +is determined by the lexical environment; the variable may have a +local value if its symbol's value cell is unassigned. @defun makunbound symbol -This function makes the current variable binding of @var{symbol} void. -Subsequent attempts to use this symbol's value as a variable will signal -the error @code{void-variable}, unless and until you set it again. +This function empties out the value cell of @var{symbol}, making the +variable void. It returns @var{symbol}. -@code{makunbound} returns @var{symbol}. +If @var{symbol} has a dynamic local binding, @code{makunbound} voids +the current binding, and this voidness lasts only as long as the local +binding is in effect. Afterwards, the previously shadowed local or +global binding is reexposed; then the variable will no longer be void, +unless the reexposed binding is void too. -@example -@group -(makunbound 'x) ; @r{Make the global value of @code{x} void.} - @result{} x -@end group -@group -x -@error{} Symbol's value as variable is void: x -@end group -@end example - -If @var{symbol} is locally bound, @code{makunbound} affects the most -local existing binding. This is the only way a symbol can have a void -local binding, since all the constructs that create local bindings -create them with values. In this case, the voidness lasts at most as -long as the binding does; when the binding is removed due to exit from -the construct that made it, the previous local or global binding is -reexposed as usual, and the variable is no longer void unless the newly -reexposed binding was void all along. +Here are some examples (assuming dynamic binding is in effect): @smallexample @group @@ -361,17 +349,11 @@ x ; @r{The global binding is unchanged.} @end smallexample @end defun - A variable that has been made void with @code{makunbound} is -indistinguishable from one that has never received a value and has -always been void. - - You can use the function @code{boundp} to test whether a variable is -currently void. - @defun boundp variable -@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; -more precisely, if its current binding is not void. It returns -@code{nil} otherwise. +This function returns @code{t} if @var{variable} (a symbol) is not +void, and @code{nil} if it is void. + +Here are some examples (assuming dynamic binding is in effect): @smallexample @group @@ -402,52 +384,41 @@ more precisely, if its current binding is not void. It returns @section Defining Global Variables @cindex variable definition - You may announce your intention to use a symbol as a global variable -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 -used a certain way (as variables). Second, they inform the Lisp system -of these things, supplying a value and documentation. Third, they -provide information to utilities such as @code{etags} and -@code{make-docfile}, which create data bases of the functions and -variables in a program. - - The difference between @code{defconst} and @code{defvar} is primarily -a matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not restrict the ways in which a -variable can be used based on @code{defconst} or @code{defvar} -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. - -@ignore - One would expect user option variables to be defined with -@code{defconst}, since programs do not change them. Unfortunately, this -has bad results if the definition is in a library that is not preloaded: -@code{defconst} would override any prior value when the library is -loaded. Users would like to be able to set user options in their init -files, and override the default values given in the definitions. For -this reason, user options must be defined with @code{defvar}. -@end ignore + A @dfn{variable definition} is a construct that announces your +intention to use a symbol as a global variable. It uses the special +forms @code{defvar} or @code{defconst}, which are documented below. + + A variable definition serves three purposes. First, it informs +people who read the code that the symbol is @emph{intended} to be used +a certain way (as a variable). Second, it informs the Lisp system of +this, optionally supplying an initial value and a documentation +string. Third, it provides information to programming tools such as +@command{etags}, allowing them to find where the variable was defined. + + The difference between @code{defconst} and @code{defvar} is mainly a +matter of intent, serving to inform human readers of whether the value +should ever change. Emacs Lisp does not actually prevent you from +changing the value of a variable defined with @code{defconst}. One +notable difference between the two forms is that @code{defconst} +unconditionally initializes the variable, whereas @code{defvar} +initializes it only if it is originally void. + + To define a customizable variable, you should use @code{defcustom} +(which calls @code{defvar} as a subroutine). @xref{Customization}. @defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable and can also -initialize and document it. The definition informs a person reading -your code that @var{symbol} is used as a variable that might be set or -changed. It also declares this variable as @dfn{special}, meaning that it -should always use dynamic scoping rules. Note that @var{symbol} is not -evaluated; the symbol to be defined must appear explicitly in the -@code{defvar}. +This special form defines @var{symbol} as a variable. Note that +@var{symbol} is not evaluated; the symbol to be defined should appear +explicitly in the @code{defvar} form. The variable is marked as +@dfn{special}, meaning that it should always be dynamically bound +(@pxref{Variable Scoping}). If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates it and sets @var{symbol} to the result. But if @var{symbol} -already has a value (i.e., it is not void), @var{value} is not even -evaluated, and @var{symbol}'s value remains unchanged. -If @var{value} is omitted, the value of @var{symbol} is not changed in any -case; instead, the only effect of @code{defvar} is to declare locally that this -variable exists elsewhere and should hence always use dynamic scoping rules. +evaluates @var{value} and sets @var{symbol} to the result. But if +@var{symbol} already has a value (i.e.@: it is not void), @var{value} +is not even evaluated, and @var{symbol}'s value remains unchanged. If +@var{value} is omitted, the value of @var{symbol} is not changed in +any case. If @var{symbol} has a buffer-local binding in the current buffer, @code{defvar} operates on the default value, which is buffer-independent, @@ -459,19 +430,9 @@ 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. -If the @var{doc-string} argument appears, it specifies the documentation -for the variable. (This opportunity to specify documentation is one of -the main benefits of defining the variable.) The documentation is -stored in the symbol's @code{variable-documentation} property. The -Emacs help functions (@pxref{Documentation}) look for this property. - -If the documentation string begins with the character @samp{*}, Emacs -allows users to set it interactively using the @code{set-variable} -command. However, you should nearly always use @code{defcustom} -instead of @code{defvar} to define such variables, so that users can -use @kbd{M-x customize} and related commands to set them. In that -case, it is not necessary to begin the documentation string with -@samp{*}. @xref{Customization}. +If the @var{doc-string} argument is supplied, it specifies the +documentation string for the variable (stored in the symbol's +@code{variable-documentation} property). @xref{Documentation}. Here are some examples. This form defines @code{foo} but does not initialize it: @@ -494,38 +455,6 @@ it a documentation string: @end group @end example -The following form changes the documentation string for @code{bar}, -making it a user option, but does not change the value, since @code{bar} -already has a value. (The addition @code{(1+ nil)} would get an error -if it were evaluated, but since it is not evaluated, there is no error.) - -@example -@group -(defvar bar (1+ nil) - "*The normal weight of a bar.") - @result{} bar -@end group -@group -bar - @result{} 23 -@end group -@end example - -Here is an equivalent expression for the @code{defvar} special form: - -@example -@group -(defvar @var{symbol} @var{value} @var{doc-string}) -@equiv{} -(progn - (if (not (boundp '@var{symbol})) - (setq @var{symbol} @var{value})) - (if '@var{doc-string} - (put '@var{symbol} 'variable-documentation '@var{doc-string})) - '@var{symbol}) -@end group -@end example - The @code{defvar} form returns @var{symbol}, but it is normally used at top level in a file where its value does not matter. @end defspec @@ -538,6 +467,11 @@ global value, established here, that should not be changed by the user or by other programs. Note that @var{symbol} is not evaluated; the symbol to be defined must appear explicitly in the @code{defconst}. +The @code{defconst} form, like @code{defvar}, marks the variable as +@dfn{special}, meaning that it should always be dynamically bound +(@pxref{Variable Scoping}). In addition, it marks the variable as +risky (@pxref{File Local Variables}). + @code{defconst} always evaluates @var{value}, and sets the value of @var{symbol} to the result. If @var{symbol} does have a buffer-local binding in the current buffer, @code{defconst} sets the default value, @@ -567,37 +501,13 @@ float-pi @end example @end defspec -@defun user-variable-p variable -@cindex user option -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.) - -User option variables are distinguished from other variables either -though being declared using @code{defcustom}@footnote{They may also be -declared equivalently in @file{cus-start.el}.} or by the first character -of their @code{variable-documentation} property. If the property exists -and is a string, and its first character is @samp{*}, then the variable -is a user option. Aliases of user options are also user options. -@end defun - -@cindex @code{variable-interactive} property -@findex set-variable - If a user option variable has a @code{variable-interactive} property, -the @code{set-variable} command uses that value to control reading the -new value for the variable. The property's value is used as if it were -specified in @code{interactive} (@pxref{Using Interactive}). However, -this feature is largely obsoleted by @code{defcustom} -(@pxref{Customization}). - - @strong{Warning:} If the @code{defconst} and @code{defvar} special -forms are used while the variable has a local binding (made with -@code{let}, or a function argument), they set the local-binding's -value; the top-level binding is not changed. This is not what you -usually want. To prevent it, use these special forms at top level in -a file, where normally no local binding is in effect, and make sure to -load the file before making a local binding for the variable. + @strong{Warning:} If you use a @code{defconst} or @code{defvar} +special form while the variable has a local binding (made with +@code{let}, or a function argument), it sets the local binding rather +than the global binding. This is not what you usually want. To +prevent this, use these special forms at top level in a file, where +normally no local binding is in effect, and make sure to load the file +before making a local binding for the variable. @node Tips for Defining @section Tips for Defining Variables Robustly @@ -667,9 +577,9 @@ loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents (such -as, to rebind keys). Third, evaluating the @code{defvar} form with -@kbd{C-M-x} @emph{will} reinitialize the map completely. +important if the user has run hooks to alter part of the contents +(such as, to rebind keys). Third, evaluating the @code{defvar} form +with @kbd{C-M-x} will reinitialize the map completely. Putting so much code in the @code{defvar} form has one disadvantage: it puts the documentation string far away from the line which names the @@ -690,37 +600,27 @@ This has all the same advantages as putting the initialization inside the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on each form, if you do want to reinitialize the variable. - But be careful not to write the code like this: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (setq my-mode-map (make-sparse-keymap)) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{}) -@end example - -@noindent -This code sets the variable, then alters it, but it does so in more than -one step. If the user quits just after the @code{setq}, that leaves the -variable neither correctly initialized nor void nor @code{nil}. Once -that happens, reloading the file will not initialize the variable; it -will remain incomplete. - @node Accessing Variables @section Accessing Variable Values The usual way to reference a variable is to write the symbol which -names it (@pxref{Symbol Forms}). This requires you to specify the -variable name when you write the program. Usually that is exactly what -you want to do. Occasionally you need to choose at run time which -variable to reference; then you can use @code{symbol-value}. +names it. @xref{Symbol Forms}. + + Occasionally, you may want to reference a variable which is only +determined at run time. In that case, you cannot specify the variable +name in the text of the program. You can use the @code{symbol-value} +function to extract the value. @defun symbol-value symbol -This function returns the value of @var{symbol}. This is the value in -the innermost local binding of the symbol, or its global value if it -has no local bindings. +This function returns the value stored in @var{symbol}'s value cell. +This is where the variable's current (dynamic) value is stored. If +the variable has no local binding, this is simply its global value. +If the variable is void, a @code{void-variable} error is signaled. + +If the variable is lexically bound, the value reported by +@code{symbol-value} is not necessarily the same as the variable's +lexical value, which is determined by the lexical environment rather +than the symbol's value cell. @xref{Variable Scoping}. @example @group @@ -754,13 +654,10 @@ has no local bindings. @result{} 5 @end group @end example - -A @code{void-variable} error is signaled if the current binding of -@var{symbol} is void. @end defun @node Setting Variables -@section How to Alter a Variable Value +@section Setting Variable Values The usual way to change the value of a variable is with the special form @code{setq}. When you need to compute the choice of variable at @@ -769,8 +666,8 @@ run time, use the function @code{set}. @defspec setq [symbol form]@dots{} This special form is the most common method of changing a variable's value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The most-local existing -binding of the symbol is changed. +evaluating the corresponding @var{form}. The current binding of the +symbol is changed. @code{setq} does not evaluate @var{symbol}; it sets the symbol that you write. We say that this argument is @dfn{automatically quoted}. The @@ -809,12 +706,17 @@ second @var{symbol} is set, and so on: @end defspec @defun set symbol value -This function sets @var{symbol}'s value to @var{value}, then returns -@var{value}. Since @code{set} is a function, the expression written for -@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. +This function puts @var{value} in the value cell of @var{symbol}. +Since it is a function rather than a special form, the expression +written for @var{symbol} is evaluated to obtain the symbol to set. +The return value is @var{value}. + +When dynamic variable binding is in effect (the default), @code{set} +has the same effect as @code{setq}, apart from the fact that +@code{set} evaluates its @var{symbol} argument whereas @code{setq} +does not. But when a variable is lexically bound, @code{set} affects +its @emph{dynamic} value, whereas @code{setq} affects its current +(lexical) value. @xref{Variable Scoping}. @example @group @@ -854,327 +756,337 @@ error is signaled. (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 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 -symbol's ``special'' or dynamic value, ignoring any lexical bindings. -In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} -always affects the most local existing binding. -@end quotation @end defun @node Variable Scoping @section Scoping Rules for Variable Bindings - A given symbol @code{foo} can have several local variable bindings, -established at different places in the Lisp program, as well as a global -binding. The most recently established binding takes precedence over -the others. + When you create a local binding for a variable, that binding takes +effect only within a limited portion of the program (@pxref{Local +Variables}). This section describes exactly what this means. @cindex scope @cindex extent -@cindex dynamic scoping -@cindex lexical scoping - By default, local bindings in Emacs Lisp have @dfn{indefinite scope} and -@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. ``Indefinite scope'' means -that any part of the program can potentially access the variable -binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. ``Dynamic extent'' means that the binding -lasts as long as the activation of the construct that established it. - - The combination of dynamic extent and indefinite scope is called -@dfn{dynamic scoping}. By contrast, most programming languages use -@dfn{lexical scoping}, in which references to a local variable must be -located textually within the function or block that binds the variable. -Emacs can also support lexical scoping, upon request (@pxref{Lexical -Binding}). - -@cindex CL note---special variables -@quotation -@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are -dynamically scoped, like all variables in Emacs Lisp. -@end quotation + Each local binding has a certain @dfn{scope} and @dfn{extent}. +@dfn{Scope} refers to @emph{where} in the textual source code the +binding can be accessed. @dfn{Extent} refers to @emph{when}, as the +program is executing, the binding exists. + +@cindex dynamic binding +@cindex indefinite scope +@cindex dynamic extent + By default, the local bindings that Emacs creates are @dfn{dynamic +bindings}. Such a binding has @dfn{indefinite scope}, meaning that +any part of the program can potentially access the variable binding. +It also has @dfn{dynamic extent}, meaning that the binding lasts only +while the binding construct (such as the body of a @code{let} form) is +being executed. + +@cindex lexical binding +@cindex lexical scope +@cindex indefinite extent + Emacs can optionally create @dfn{lexical bindings}. A lexical +binding has @dfn{lexical scope}, meaning that any reference to the +variable must be located textually within the binding construct. It +also has @dfn{indefinite extent}, meaning that under some +circumstances the binding can live on even after the binding construct +has finished executing, by means of special objects called +@dfn{closures}. + + The following subsections describe dynamic binding and lexical +binding in greater detail, and how to enable lexical binding in Emacs +Lisp programs. @menu -* Scope:: Scope means where in the program a value is visible. - Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and avoid problems. -* Lexical Binding:: Use of lexical scoping. +* Dynamic Binding:: The default for binding local variables in Emacs. +* Dynamic Binding Tips:: Avoiding problems with dynamic binding. +* Lexical Binding:: A different type of local variable binding. +* Using Lexical Binding:: How to enable lexical binding. @end menu -@node Scope -@subsection Scope +@node Dynamic Binding +@subsection Dynamic Binding - Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. -This means that any function anywhere in the program text might access a -given binding of a variable. Consider the following function -definitions: + By default, the local variable bindings made by Emacs are dynamic +bindings. When a variable is dynamically bound, its current binding +at any point in the execution of the Lisp program is simply the most +recently-created dynamic local binding for that symbol, or the global +binding if there is no such local binding. + + Dynamic bindings have indefinite scope and dynamic extent, as shown +by the following example: @example @group -(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} - (foo 5)) ; @r{@code{foo} is some other function.} -@end group +(defvar x -99) ; @r{@code{x} receives an initial value of -99.} -@group -(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} - (list x)) +(defun getx () + x) ; @r{@code{x} is used ``free'' in this function.} + +(let ((x 1)) ; @r{@code{x} is dynamically bound.} + (getx)) + @result{} 1 + +;; @r{After the @code{let} form finishes, @code{x} reverts to its} +;; @r{previous value, which is -99.} + +(getx) + @result{} -99 @end group @end example - In a lexically scoped language, the binding of @code{x} in -@code{binder} would never be accessible in @code{user}, because -@code{user} is not textually contained within the function -@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} -may or may not refer to the binding of @code{x} established in -@code{binder}, depending on the circumstances: - -@itemize @bullet -@item -If we call @code{user} directly without calling @code{binder} at all, -then whatever binding of @code{x} is found, it cannot come from -@code{binder}. +@noindent +The function @code{getx} refers to @code{x}. This is a ``free'' +reference, in the sense that there is no binding for @code{x} within +that @code{defun} construct itself. When we call @code{getx} from +within a @code{let} form in which @code{x} is (dynamically) bound, it +retrieves the local value of @code{x} (i.e.@: 1). But when we call +@code{getx} outside the @code{let} form, it retrieves the global value +of @code{x} (i.e.@: -99). -@item -If we define @code{foo} as follows and then call @code{binder}, then the -binding made in @code{binder} will be seen in @code{user}: + Here is another example, which illustrates setting a dynamically +bound variable using @code{setq}: @example @group -(defun foo (lose) - (user)) +(defvar x -99) ; @r{@code{x} receives an initial value of -99.} + +(defun addx () + (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} + +(let ((x 1)) + (addx) + (addx)) + @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} + +;; @r{After the @code{let} form finishes, @code{x} reverts to its} +;; @r{previous value, which is -99.} + +(addx) + @result{} -98 @end group @end example -@item -However, if we define @code{foo} as follows and then call @code{binder}, -then the binding made in @code{binder} @emph{will not} be seen in -@code{user}: + Dynamic binding is implemented in Emacs Lisp in a simple way. Each +symbol has a value cell, which specifies its current dynamic value (or +absence of value). @xref{Symbol Components}. When a symbol is given +a dynamic local binding, Emacs records the contents of the value cell +(or absence thereof) in a stack, and stores the new local value in the +value cell. When the binding construct finishes executing, Emacs pops +the old value off the stack, and puts it in the value cell. -@example -(defun foo (x) - (user)) -@end example +@node Dynamic Binding Tips +@subsection Proper Use of Dynamic Binding -@noindent -Here, when @code{foo} is called by @code{binder}, it binds @code{x}. -(The binding in @code{foo} is said to @dfn{shadow} the one made in -@code{binder}.) Therefore, @code{user} will access the @code{x} bound -by @code{foo} instead of the one bound by @code{binder}. -@end itemize + Dynamic binding is a powerful feature, as it allows programs to +refer to variables that are not defined within their local textual +scope. However, if used without restraint, this can also make +programs hard to understand. There are two clean ways to use this +technique: -Emacs Lisp used dynamic scoping by default because simple implementations of -lexical scoping are slow. In addition, every Lisp system needs to offer -dynamic scoping at least as an option; if lexical scoping is the norm, there -must be a way to specify dynamic scoping instead for a particular variable. -Nowadays, Emacs offers both, but the default is still to use exclusively -dynamic scoping. - -@node Extent -@subsection Extent - - @dfn{Extent} refers to the time during program execution that a -variable name is valid. In Emacs Lisp, a variable is valid only while -the form that bound it is executing. This is called @dfn{dynamic -extent}. ``Local'' or ``automatic'' variables in most languages, -including C and Pascal, have dynamic extent. - - One alternative to dynamic extent is @dfn{indefinite extent}. This -means that a variable binding can live on past the exit from the form -that made the binding. Common Lisp and Scheme, for example, support -this, but Emacs Lisp does not. - - To illustrate this, the function below, @code{make-add}, returns a -function that purports to add @var{n} to its own argument @var{m}. This -would work in Common Lisp, but it does not do the job in Emacs Lisp, -because after the call to @code{make-add} exits, the variable @code{n} -is no longer bound to the actual argument 2. +@itemize @bullet +@item +If a variable has no global definition, use it as a local variable +only within a binding construct, e.g.@: the body of the @code{let} +form where the variable was bound, or the body of the function for an +argument variable. If this convention is followed consistently +throughout a program, the value of the variable will not affect, nor +be affected by, any uses of the same variable symbol elsewhere in the +program. + +@item +Otherwise, define the variable with @code{defvar}, @code{defconst}, or +@code{defcustom}. @xref{Defining Variables}. Usually, the definition +should be at top-level in an Emacs Lisp file. As far as possible, it +should include a documentation string which explains the meaning and +purpose of the variable. You should also choose the variable's name +to avoid name conflicts (@pxref{Coding Conventions}). + +Then you can bind the variable anywhere in a program, knowing reliably +what the effect will be. Wherever you encounter the variable, it will +be easy to refer back to the definition, e.g.@: via the @kbd{C-h v} +command (provided the variable definition has been loaded into Emacs). +@xref{Name Help,,, emacs, The GNU Emacs Manual}. + +For example, it is common to use local bindings for customizable +variables like @code{case-fold-search}: @example -(defun make-add (n) - (function (lambda (m) (+ n m)))) ; @r{Return a function.} - @result{} make-add -(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} - ; @r{with @code{(make-add 2)}.} - @result{} (lambda (m) (+ n m)) -(add2 4) ; @r{Try to add 2 to 4.} -@error{} Symbol's value as variable is void: n +@group +(defun search-for-abc () + "Search for the string \"abc\", ignoring case differences." + (let ((case-fold-search nil)) + (re-search-forward "abc"))) +@end group @end example +@end itemize -@cindex closures not available - Some Lisp dialects have ``closures,'' objects that are like functions -but record additional variable bindings. Emacs Lisp does not have -closures. +@node Lexical Binding +@subsection Lexical Binding -@node Impl of Scope -@subsection Implementation of Dynamic Scoping -@cindex deep binding +Optionally, you can create lexical bindings in Emacs Lisp. A +lexically bound variable has @dfn{lexical scope}, meaning that any +reference to the variable must be located textually within the binding +construct. - A simple sample implementation (which is not how Emacs Lisp actually -works) may help you understand dynamic binding. This technique is -called @dfn{deep binding} and was used in early Lisp systems. + Here is an example +@iftex +(see the next subsection, for how to actually enable lexical binding): +@end iftex +@ifnottex +(@pxref{Using Lexical Binding}, for how to actually enable lexical binding): +@end ifnottex - Suppose there is a stack of bindings, which are variable-value pairs. -At entry to a function or to a @code{let} form, we can push bindings -onto the stack for the arguments or local variables created there. We -can pop those bindings from the stack at exit from the binding -construct. +@example +@group +(let ((x 1)) ; @r{@code{x} is lexically bound.} + (+ x 3)) + @result{} 4 - We can find the value of a variable by searching the stack from top to -bottom for a binding for that variable; the value from that binding is -the value of the variable. To set the variable, we search for the -current binding, then store the new value into that binding. - - As you can see, a function's bindings remain in effect as long as it -continues execution, even during its calls to other functions. That is -why we say the extent of the binding is dynamic. And any other function -can refer to the bindings, if it uses the same variables while the -bindings are in effect. That is why we say the scope is indefinite. - -@cindex shallow binding - The actual implementation of variable scoping in GNU Emacs Lisp uses a -technique called @dfn{shallow binding}. Each variable has a standard -place in which its current value is always found---the value cell of the -symbol. - - In shallow binding, setting the variable works by storing a value in -the value cell. Creating a new binding works by pushing the old value -(belonging to a previous binding) onto a stack, and storing the new -local value in the value cell. Eliminating a binding works by popping -the old value off the stack, into the value cell. - - We use shallow binding because it has the same results as deep -binding, but runs faster, since there is never a need to search for a -binding. +(defun getx () + x) ; @r{@code{x} is used ``free'' in this function.} -@node Using Scoping -@subsection Proper Use of Dynamic Scoping +(let ((x 1)) ; @r{@code{x} is lexically bound.} + (getx)) +@error{} Symbol's value as variable is void: x +@end group +@end example - Binding a variable in one function and using it in another is a -powerful technique, but if used without restraint, it can make programs -hard to understand. There are two clean ways to use this technique: +@noindent +Here, the variable @code{x} has no global value. When it is lexically +bound within a @code{let} form, it can be used in the textual confines +of that @code{let} form. But it can @emph{not} be used from within a +@code{getx} function called from the @code{let} form, since the +function definition of @code{getx} occurs outside the @code{let} form +itself. + +@cindex lexical environment + Here is how lexical binding works. Each binding construct defines a +@dfn{lexical environment}, specifying the symbols that are bound +within the construct and their local values. When the Lisp evaluator +wants the current value of a variable, it looks first in the lexical +environment; if the variable is not specified in there, it looks in +the symbol's value cell, where the dynamic value is stored. + +@cindex closures + Lexical bindings have indefinite extent. Even after a binding +construct has finished executing, its lexical environment can be +``kept around'' in Lisp objects called @dfn{closures}. A closure is +created when you create a named or anonymous function with lexical +binding enabled. @xref{Closures}, for details. + + When a closure is called as a function, any lexical variable +references within its definition use the retained lexical environment. +Here is an example: -@itemize @bullet -@item -Use or bind the variable only in a few related functions, written close -together in one file. Such a variable is used for communication within -one program. +@example +(defvar my-ticker nil) ; @r{We will use this dynamically bound} + ; @r{variable to store a closure.} -You should write comments to inform other programmers that they can see -all uses of the variable before them, and to advise them not to add uses -elsewhere. +(let ((x 0)) ; @r{@code{x} is lexically bound.} + (setq my-ticker (lambda () + (setq x (1+ x))))) + @result{} (closure ((x . 0) t) () + (1+ x)) -@item -Give the variable a well-defined, documented meaning, and make all -appropriate functions refer to it (but not bind it or set it) wherever -that meaning is relevant. For example, the variable -@code{case-fold-search} is defined as ``non-@code{nil} means ignore case -when searching''; various search and replace functions refer to it -directly or through their subroutines, but do not bind or set it. - -Then you can bind the variable in other programs, knowing reliably what -the effect will be. -@end itemize +(funcall my-ticker) + @result{} 1 - In either case, you should define the variable with @code{defvar}. -This helps other people understand your program by telling them to look -for inter-function usage. It also avoids a warning from the byte -compiler. Choose the variable's name to avoid name conflicts---don't -use short names like @code{x}. +(funcall my-ticker) + @result{} 2 +(funcall my-ticker) + @result{} 3 -@node Lexical Binding -@subsection Use of Lexical Scoping +x ; @r{Note that @code{x} has no global value.} +@error{} Symbol's value as variable is void: x +@end example -Emacs Lisp can be evaluated in two different modes: in dynamic binding -mode or lexical binding mode. In dynamic binding mode, all local -variables use dynamic scoping, whereas in lexical binding mode -variables that have been declared @dfn{special} (i.e., declared with -@code{defvar}, @code{defcustom} or @code{defconst}) use dynamic -scoping and all others use lexical scoping. +@noindent +The @code{let} binding defines a lexical environment in which the +variable @code{x} is locally bound to 0. Within this binding +construct, we define a lambda expression which increments @code{x} by +one and returns the incremented value. This lambda expression is +automatically turned into a closure, in which the lexical environment +lives on even after the @code{let} binding construct has exited. Each +time we evaluate the closure, it increments @code{x}, using the +binding of @code{x} in that lexical environment. + + Note that functions like @code{symbol-value}, @code{boundp}, and +@code{set} only retrieve or modify a variable's dynamic binding +(i.e.@: the contents of its symbol's value cell). Also, the code in +the body of a @code{defun} or @code{defmacro} cannot refer to +surrounding lexical variables. + + Currently, lexical binding is not much used within the Emacs +sources. However, we expect its importance to increase in the future. +Lexical binding opens up a lot more opportunities for optimization, so +Emacs Lisp code that makes use of lexical binding is likely to run +faster in future Emacs versions. Such code is also much more friendly +to concurrency, which we want to add to Emacs in the near future. + +@node Using Lexical Binding +@subsection Using Lexical Binding + + When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical +binding is enabled if the buffer-local variable @code{lexical-binding} +is non-@code{nil}: @defvar lexical-binding -When non-nil, evaluation of Lisp code uses lexical scoping for non-special -local variables instead of dynamic scoping. If nil, dynamic scoping is used -for all local variables. This variable is typically set for a whole Elisp file -via file local variables (@pxref{File Local Variables}). +If this buffer-local variable is non-@code{nil}, Emacs Lisp files and +buffers are evaluated using lexical binding instead of dynamic +binding. (However, special variables are still dynamically bound; see +below.) If @code{nil}, dynamic binding is used for all local +variables. This variable is typically set for a whole Emacs Lisp +file, as a file local variable (@pxref{File Local Variables}). +Note that unlike other such variables, this one must be set in the +first line of a file. @end defvar +@noindent +When evaluating Emacs Lisp code directly using an @code{eval} call, +lexical binding is enabled if the @var{lexical} argument to +@code{eval} is non-@code{nil}. @xref{Eval}. + +@cindex special variables + Even when lexical binding is enabled, certain variables will +continue to be dynamically bound. These are called @dfn{special +variables}. Every variable that has been defined with @code{defvar}, +@code{defcustom} or @code{defconst} is a special variable +(@pxref{Defining Variables}). All other variables are subject to +lexical binding. + @defun special-variable-p SYMBOL -Return whether SYMBOL has been declared as a special variable, via -@code{defvar} or @code{defconst}. +This function returns non-@code{nil} if @var{symbol} is a special +variable (i.e.@: it has a @code{defvar}, @code{defcustom}, or +@code{defconst} variable definition). Otherwise, the return value is +@code{nil}. @end defun -The use of a special variable as a formal argument in a function is generally -discouraged and its behavior in lexical binding mode is unspecified (it may use -lexical scoping sometimes and dynamic scoping other times). - -Functions like @code{symbol-value}, @code{boundp}, or @code{set} only know -about dynamically scoped variables, so you cannot get the value of a lexical -variable via @code{symbol-value} and neither can you change it via @code{set}. -Another particularity is that code in the body of a @code{defun} or -@code{defmacro} cannot refer to surrounding lexical variables. - -Evaluation of a @code{lambda} expression in lexical binding mode will not just -return that lambda expression unchanged, as in the dynamic binding case, but -will instead construct a new object that remembers the current lexical -environment in which that lambda expression was defined, so that the function -body can later be evaluated in the proper context. Those objects are called -@dfn{closures}. They are also functions, in the sense that they are accepted -by @code{funcall}, and they are represented by a cons cell whose @code{car} is -the symbol @code{closure}. - -@menu -* Converting to Lexical Binding:: How to start using lexical scoping -@end menu - -@node Converting to Lexical Binding -@subsubsection Converting a package to use lexical scoping - -Lexical scoping, as currently implemented, does not bring many significant -benefits, unless you are a seasoned functional programmer addicted to -higher-order functions. But its importance will increase in the future: -lexical scoping opens up a lot more opportunities for optimization, so -lexically scoped code is likely to run faster in future Emacs versions, and it -is much more friendly to concurrency, which we want to add in the near future. - -Converting a package to lexical binding is usually pretty easy and should not -break backward compatibility: just add a file-local variable setting -@code{lexical-binding} to @code{t} and add declarations of the form -@code{(defvar @var{VAR})} for every variable which still needs to use -dynamic scoping. - -To find which variables need this declaration, the simplest solution is to -check the byte-compiler's warnings. The byte-compiler will usually find those -variables either because they are used outside of a let-binding (leading to -warnings about reference or assignment to ``free variable @var{VAR}'') or -because they are let-bound but not used within the let-binding (leading to -warnings about ``unused lexical variable @var{VAR}''). - -In cases where a dynamically scoped variable was bound as a function argument, -you will also need to move this binding to a @code{let}. These cases are also -flagged by the byte-compiler. - -To silence byte-compiler warnings about unused variables, just use a variable -name that start with an underscore, which the byte-compiler interpret as an -indication that this is a variable known not to be used. - -In most cases, the resulting code will then work with either setting of -@code{lexical-binding}, so it can still be used with older Emacsen (which will -simply ignore the @code{lexical-binding} variable setting). + The use of a special variable as a formal argument in a function is +discouraged. Doing so gives rise to unspecified behavior when lexical +binding mode is enabled (it may use lexical binding sometimes, and +dynamic binding other times). + + Converting an Emacs Lisp program to lexical binding is pretty easy. +First, add a file-local variable setting of @code{lexical-binding} to +@code{t} in the Emacs Lisp source file. Second, check that every +variable in the program which needs to be dynamically bound has a +variable definition, so that it is not inadvertently bound lexically. + + A simple way to find out which variables need a variable definition +is to byte-compile the source file. @xref{Byte Compilation}. If a +non-special variable is used outside of a @code{let} form, the +byte-compiler will warn about reference or assignment to a ``free +variable''. If a non-special variable is bound but not used within a +@code{let} form, the byte-compiler will warn about an ``unused lexical +variable''. The byte-compiler will also issue a warning if you use a +special variable as a function argument. + + (To silence byte-compiler warnings about unused variables, just use +a variable name that start with an underscore. The byte-compiler +interprets this as an indication that this is a variable known not to +be used.) @node Buffer-Local Variables @section Buffer-Local Variables @@ -1279,7 +1191,8 @@ foo @result{} 'a @end group @end example - Note that references to @code{foo} in @var{body} access the +@noindent +Note that references to @code{foo} in @var{body} access the buffer-local binding of buffer @samp{b}. When a file specifies local variable values, these become buffer-local @@ -1404,11 +1317,12 @@ value (@pxref{Default Value}) of @var{variable} instead. @defun buffer-local-variables &optional buffer This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is -used.) It returns an association list (@pxref{Association Lists}) in -which each element contains one buffer-local variable and its value. -However, when a variable's buffer-local binding in @var{buffer} is void, -then the variable appears directly in the resulting list. +buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer +is used.) Normally, each list element has the form +@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local +variable (a symbol) and @var{val} is its buffer-local value. But when +a variable's buffer-local binding in @var{buffer} is void, its list +element is just @var{sym}. @example @group @@ -1660,6 +1574,13 @@ Query (once) about all the variables. @end table @end defopt +@defvar inhibit-local-variables-regexps +This is a list of regular expressions. If a file has a name +matching an element of this list, then it is not scanned for +any form of file-local variable. For examples of why you might want +to use this, @pxref{Auto Major Mode}. +@end defvar + @defun hack-local-variables &optional mode-only This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @@ -1715,6 +1636,11 @@ For boolean-valued variables that are safe, use @code{booleanp} as the property value. Lambda expressions should be quoted so that @code{describe-variable} can display the predicate. + When defining a user option using @code{defcustom}, you can set its +@code{safe-local-variable} property by adding the arguments +@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable +Definitions}). + @defopt safe-local-variable-values This variable provides another way to mark some variable values as safe. It is a list of cons cells @code{(@var{var} . @var{val})}, @@ -1734,28 +1660,31 @@ the value @var{val}, based on the above criteria. @end defun @c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. A variable whose name -ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, + Some variables are considered @dfn{risky}. If a variable is risky, +it is never entered automatically into +@code{safe-local-variable-values}; Emacs always queries before setting +a risky variable, unless the user explicitly allows a value by +customizing @code{safe-local-variable-values} directly. + + Any variable whose name has a non-@code{nil} +@code{risky-local-variable} property is considered risky. When you +define a user option using @code{defcustom}, you can set its +@code{risky-local-variable} property by adding the arguments +@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable +Definitions}). In addition, any variable whose name ends in any of +@samp{-command}, @samp{-frame-alist}, @samp{-function}, @samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is considered risky. The -variables @samp{font-lock-keywords}, @samp{font-lock-keywords} -followed by a digit, and @samp{font-lock-syntactic-keywords} are also -considered risky. Finally, any variable whose name has a -non-@code{nil} @code{risky-local-variable} property is considered -risky. +@samp{-program}, or @samp{-predicate} is automatically considered +risky. The variables @samp{font-lock-keywords}, +@samp{font-lock-keywords} followed by a digit, and +@samp{font-lock-syntactic-keywords} are also considered risky. @defun risky-local-variable-p sym This function returns non-@code{nil} if @var{sym} is a risky variable, based on the above criteria. @end defun - If a variable is risky, it will not be entered automatically into -@code{safe-local-variable-values} as described above. Therefore, -Emacs will always query before setting a risky variable, unless the -user explicitly allows the setting by customizing -@code{safe-local-variable-values} directly. - @defvar ignored-local-variables This variable holds a list of variables that should not be given local values by files. Any value specified for one of these variables is diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 95f9f7f4d29..31055bd03fe 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -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 @@ -478,6 +479,7 @@ Functions * Anonymous Functions:: Lambda expressions are functions with no names. * Function Cells:: Accessing or setting the function definition of a symbol. +* Closures:: Functions that enclose a lexical environment. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Defining functions that the compiler will open code. @@ -500,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. @@ -567,7 +568,6 @@ Advising Emacs Lisp Functions * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. Debugging Lisp Programs @@ -1081,7 +1081,7 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Checksum/Hash:: Computing "message digests"/"checksums"/"hashes". * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. @@ -1372,6 +1372,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 08ea022f6a7..92f049135a1 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -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 @@ -477,6 +478,7 @@ Functions * Anonymous Functions:: Lambda expressions are functions with no names. * Function Cells:: Accessing or setting the function definition of a symbol. +* Closures:: Functions that enclose a lexical environment. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Defining functions that the compiler will open code. @@ -499,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. @@ -566,7 +567,6 @@ Advising Emacs Lisp Functions * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. Debugging Lisp Programs @@ -1080,7 +1080,7 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Checksum/Hash:: Computing "message digests"/"checksums"/"hashes". * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. @@ -1371,6 +1371,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 1bff30e45e1..98263f4093c 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -479,7 +479,7 @@ partially-visible line at the bottom of the text area is not counted. @end defun For compatibility with previous versions of Emacs, -@code{window-height} is an alias for @code{window-body-height}, and +@code{window-height} is an alias for @code{window-total-height}, and @code{window-width} is an alias for @code{window-body-width}. These aliases are considered obsolete and will be removed in the future. @@ -3104,9 +3104,9 @@ window configuration; see @ref{Frame Configurations}. @defun current-window-configuration &optional frame This function returns a new object representing @var{frame}'s current window configuration. The default for @var{frame} is the selected -frame. This function saves copies of window parameters listed by the -variable @code{window-persistent-parameters}, see @ref{Window -Parameters} for details. +frame. The variable @code{window-persistent-parameters} specifies +whether and which window parameters are saved by this function, see +@ref{Window Parameters} for details. @end defun @defun set-window-configuration configuration @@ -3214,27 +3214,25 @@ to clone the state of a frame into an arbitrary live window (@code{set-window-configuration} effectively clones the windows of a frame into the root window of that very frame only). -@defun window-state-get &optional window ignore +@defun window-state-get &optional window writable This function returns the state of @var{window} as a Lisp object. The argument @var{window} can be any window and defaults to the root window of the selected frame. -If the optional argument @var{ignore} is non-@code{nil}, this means to +If the optional argument @var{writable} is non-@code{nil}, this means to not use markers for sampling positions like @code{window-point} or @code{window-start}. This argument should be non-@code{nil} when the -state shall be written on disk and read back in another session. +state shall be written to disk and read back in another session. -The variable @code{window-persistent-parameters} specifies whether and -which window parameters are saved by this function, see @ref{Window -Parameters} for details. +Together, the argument @var{writable} and the variable +@code{window-persistent-parameters} specify which window parameters are +saved by this function, see @ref{Window Parameters} for details. @end defun -The value returned by @code{window-state-get} can be converted, using -one of the functions defined by Desktop Save Mode (@pxref{Desktop Save -Mode}), to an object that can be written to a file. Such objects can be -read back and converted to a Lisp object representing the state of the -window. That Lisp object can be used as argument for the following -function in order to restore the state window in another window. +The value returned by @code{window-state-get} can be used in the same +session to make a clone of a window in another window. It can be also +written to disk and read back in another session. In either case, use +the function described next to restore the state of the window. @defun window-state-put state &optional window ignore This function puts the window state @var{state} into @var{window}. The @@ -3281,10 +3279,10 @@ states of windows (@pxref{Window Configurations}) do not care about window parameters. This means, that when you change the value of a parameter within the body of a @code{save-window-excursion}, the previous value is not restored upon exit of that macro. It also means -that when you clone via @code{window-state-put} a window state saved -earlier by @code{window-state-get}, the cloned windows come up with no -parameters at all. The following variable allows to override the -standard behavior. +that when you restore via @code{window-state-put} a window state saved +earlier by @code{window-state-get}, all cloned windows have their +parameters reset to @code{nil}. The following variable allows to +override the standard behavior. @defvar window-persistent-parameters This variable is an alist specifying which parameters get saved by @@ -3293,32 +3291,25 @@ subsequently restored by @code{set-window-configuration} and @code{window-state-put}, see @ref{Window Configurations}. The @sc{car} of each entry of this alist is the symbol specifying the -parameter. The @sc{cdr} must be one of the following: +parameter. The @sc{cdr} should be one of the following: @table @asis -@item @code{state} -This value means the parameter is saved by @code{window-state-get} -provided its @var{ignore} argument is @code{nil}. The function -@code{current-window-configuration} does not save this parameter. - @item @code{nil} +This value means the parameter is neither saved by +@code{window-state-get} nor by @code{current-window-configuration}. + +@item @code{t} This value specifies that the parameter is saved by -@code{current-window-configuration} and, provided its @var{ignore} +@code{current-window-configuration} and, provided its @var{writable} argument is @code{nil}, by @code{window-state-get}. -@item @code{t} +@item @code{writable} This means that the parameter is saved unconditionally by both @code{current-window-configuration} and @code{window-state-get}. This value should not be used for parameters whose values do not have a read syntax. Otherwise, invoking @code{window-state-put} in another session may fail with an @code{invalid-read-syntax} error. @end table - -Parameters that have been saved are restored to their previous values by -@code{set-window-configuration} respectively are installed by -@code{window-state-put}. Parameters that have not been saved are left -alone by @code{set-window-configuration} respectively are not installed -by @code{window-state-put}. @end defvar Some functions, notably @code{delete-window}, |