diff options
Diffstat (limited to 'doc/lispref')
36 files changed, 1805 insertions, 786 deletions
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 74e3878a37e..5de04a7784c 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -167,8 +167,8 @@ elisp.ps: elisp.dvi ## [12] stuff is from two-volume.make. mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs rm -f elisp[12]* vol[12].tmp clean: mostlyclean diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index ce1ab693672..b92d3701ec9 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -232,7 +232,8 @@ Emacs commands to offer to save your abbrevs. Save all abbrev definitions (except system abbrevs), for all abbrev tables listed in @code{abbrev-table-name-list}, in the file @var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, +define the same abbrevs. Tables that do not have any abbrevs to save +are omitted. If @var{filename} is @code{nil} or omitted, @code{abbrev-file-name} is used. This function returns @code{nil}. @end deffn diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 8d8fc97a60f..29f542b685b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -648,16 +648,13 @@ file should not be done. @defun visited-file-modtime This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. (This is the same format that -@code{file-attributes} uses to return time values; @pxref{File -Attributes}.) +modification time, as a Lisp timestamp (@pxref{Time of Day}). If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not visiting a file or if the time has been explicitly cleared by @code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers +@code{visited-file-modtime} returns a timestamp for some non-file buffers too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. @@ -671,9 +668,8 @@ is not @code{nil}, and otherwise to the last modification time of the visited file. If @var{time} is neither @code{nil} nor an integer flag returned -by @code{visited-file-modtime}, it should have the form -@code{(@var{high} @var{low} @var{microsec} @var{picosec})}, -the format used by @code{current-time} (@pxref{Time of Day}). +by @code{visited-file-modtime}, it should be a Lisp time value +(@pxref{Time of Day}). This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign @@ -830,7 +826,7 @@ regardless of which frames they were displayed on. @group ;; @r{Note that the name of the minibuffer} ;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) +(mapcar #'buffer-name (buffer-list)) @result{} ("buffers.texi" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS") @end group diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 3ffe8f7fb9d..5d4184e3fb4 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1095,12 +1095,10 @@ Matches if @var{expval} is a vector of length @var{m} whose @item @var{symbol} @itemx @var{keyword} -@itemx @var{integer} +@itemx @var{number} @itemx @var{string} Matches if the corresponding element of @var{expval} is @code{equal} to the specified literal object. -Note that, aside from @var{symbol}, this is the same set of -self-quoting literal objects that are acceptable as a core pattern. @item ,@var{pattern} Matches if the corresponding element of @var{expval} @@ -1355,7 +1353,8 @@ This construct executes @var{body} once for each integer from 0 (inclusive) to @var{count} (exclusive), binding the variable @var{var} to the integer for the current iteration. Then it returns the value of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: +Use of @var{result} is deprecated. Here is an example of using +@code{dotimes} to do something 100 times: @example (dotimes (i 100) @@ -1986,9 +1985,10 @@ error occurs during @var{protected-form}. Each of the @var{handlers} is a list of the form @code{(@var{conditions} @var{body}@dots{})}. Here @var{conditions} is an error condition name to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: +to allow the debugger to run before the handler). A condition name of +@code{t} matches any condition. @var{body} is one or more Lisp +expressions to be executed when this handler handles an error. Here +are examples of handlers: @example @group diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 2576fbe39d7..9e433433107 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -81,7 +81,8 @@ debugger recursively. @xref{Recursive Editing}. * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -392,32 +393,82 @@ this is not what you want, you can either set @code{eval-expression-debug-on-error} to @code{nil}, or set @code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. + The debugger itself must be run byte-compiled, since it makes +assumptions about the state of the Lisp interpreter. These +assumptions are false if the debugger is running interpreted. + +@node Backtraces +@subsection Backtraces +@cindex backtrace buffer + +Debugger mode is derived from Backtrace mode, which is also used to +show backtraces by Edebug and ERT. (@pxref{Edebug}, and @ref{Top,the +ERT manual,, ert, ERT: Emacs Lisp Regression Testing}.) + +@cindex stack frame +The backtrace buffer shows you the functions that are executing and +their argument values. When a backtrace buffer is created, it shows +each stack frame on one, possibly very long, line. (A stack frame is +the place where the Lisp interpreter records information about a +particular invocation of a function.) The most recently called +function will be at the top. + @cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click with the mouse on -that name, or move to it and type @key{RET}, to visit the source code. +In a backtrace you can specify a stack frame by moving point to a line +describing that frame. The frame whose line point is on is considered +the @dfn{current frame}. + +If a function name is underlined, that means Emacs knows where its +source code is located. You can click with the mouse on that name, or +move to it and type @key{RET}, to visit the source code. You can also +type @key{RET} while point is on any name of a function or variable +which is not underlined, to see help information for that symbol in a +help buffer, if any exists. The @code{xref-find-definitions} command, +bound to @key{M-.}, can also be used on any identifier in a backtrace +(@pxref{Looking Up Identifiers,,,emacs, The GNU Emacs Manual}). + +In backtraces, the tails of long lists and the ends of long strings, +vectors or structures, as well as objects which are deeply nested, +will be printed as underlined ``...''. You can click with the mouse +on a ``...'', or type @key{RET} while point is on it, to show the part +of the object that was hidden. To control how much abbreviation is +done, customize @code{backtrace-line-length}. + +Here is a list of commands for navigating and viewing backtraces: - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. +@table @kbd +@item v +Toggle the display of local variables of the current stack frame. + +@item p +Move to the beginning of the frame, or to the beginning +of the previous frame. + +@item n +Move to the beginning of the next frame. + +@item + +Add line breaks and indentation to the top-level Lisp form at point to +make it more readable. + +@item - +Collapse the top-level Lisp form at point back to a single line. + +@item # +Toggle @code{print-circle} for the frame at point. + +@item . +Expand all the forms abbreviated with ``...'' in the frame at point. + +@end table @node Debugger Commands @subsection Debugger Commands @cindex debugger command list The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of +addition to the usual Emacs commands and to the Backtrace mode commands +described in the previous section. The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a @@ -427,6 +478,11 @@ the same function. (To do this, visit the source for the function and type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger to step through a primitive function. +Some of the debugger commands operate on the current frame. If a +frame starts with a star, that means that exiting that frame will call the +debugger again. This is useful for examining the return value of a +function. + @c FIXME: Add @findex for the following commands? --xfq Here is a list of Debugger mode commands: @@ -502,8 +558,6 @@ Display a list of functions that will invoke the debugger when called. This is a list of functions that are set to break on entry by means of @code{debug-on-entry}. -@item v -Toggle the display of local variables of the current stack frame. @end table @node Invoking the Debugger @@ -624,20 +678,19 @@ of @code{debug} (@pxref{Invoking the Debugger}). @cindex run time stack @cindex call stack This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@file{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. +The trace is identical to the one that @code{debug} would show in the +@file{*Backtrace*} buffer. The return value is always nil. In the following example, a Lisp expression calls @code{backtrace} explicitly. This prints the backtrace to the stream @code{standard-output}, which, in this case, is the buffer @samp{backtrace-output}. -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. +Each line of the backtrace represents one function call. The line +shows the function followed by a list of the values of the function's +arguments if they are all known; if they are still being computed, the +line consists of a list containing the function and its unevaluated +arguments. Long lists or deeply nested structures may be elided. @smallexample @group @@ -654,10 +707,10 @@ forms are elided. @group ----------- Buffer: backtrace-output ------------ backtrace() - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) + eval((progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) @@ -685,10 +738,10 @@ example would look as follows: @group ----------- Buffer: backtrace-output ------------ (backtrace) - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (eval (progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b3ce7fbf6af..19424ecc7e6 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -469,19 +469,54 @@ never print it, there are many good reasons for this not to happen. Secondly, @samp{done} is more explicit. @end defun -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} +@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{} This is a convenience macro that works the same way as @code{dotimes} does, but also reports loop progress using the functions described -above. It allows you to save some typing. +above. It allows you to save some typing. The argument +@var{reporter-or-message} can be either a string or a progress +reporter object. -You can rewrite the example in the beginning of this node using -this macro this way: +You can rewrite the example in the beginning of this subsection using +this macro as follows: @example +@group (dotimes-with-progress-reporter (k 500) "Collecting some mana for Emacs..." (sit-for 0.01)) +@end group +@end example + +Using a reporter object as the @var{reporter-or-message} argument is +useful if you want to specify the optional arguments in +@var{make-progress-reporter}. For instance, you can write the +previous example as follows: + +@example +@group +(dotimes-with-progress-reporter + (k 500) + (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5) + (sit-for 0.01)) +@end group +@end example +@end defmac + +@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{} +This is another convenience macro that works the same way as @code{dolist} +does, but also reports loop progress using the functions described +above. As in @code{dotimes-with-progress-reporter}, +@code{reporter-or-message} can be a progress reporter or a string. +You can rewrite the previous example with this macro as follows: + +@example +@group +(dolist-with-progress-reporter + (k (number-sequence 0 500)) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +@end group @end example @end defmac @@ -2939,7 +2974,13 @@ the remapped face---it replaces the normal definition of @var{face}, instead of modifying it. If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. +effect only within that buffer. If @code{face-remapping-alist} +includes faces applicable only to certain windows, by using the +@w{@code{(:filtered (:window @var{param} @var{val}) @var{spec})}}, +that face takes effect only in windows that match the filter +conditions (@pxref{Special Properties}). To turn off face filtering +temporarily, bind @code{face-filters-always-match} to a non-@code{nil} +value, then all face filters will match any window. Note: face remapping is non-recursive. If @var{remapping} references the same face name @var{face}, either directly or via the @@ -4129,10 +4170,10 @@ Used to indicate continued lines. @item @code{right-triangle}, @code{left-triangle} The former is used by overlay arrows. The latter is unused. -@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle} +@item @code{up-arrow}, @code{down-arrow} @itemx @code{bottom-left-angle}, @code{bottom-right-angle} -@itemx @code{top-right-angle}, @code{top-left-angle} -@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle} +@itemx @code{top-left-angle}, @code{top-right-angle} +@itemx @code{left-bracket}, @code{right-bracket} Used to indicate buffer boundaries. @item @code{filled-rectangle}, @code{hollow-rectangle} @@ -4140,7 +4181,7 @@ Used to indicate buffer boundaries. @itemx @code{vertical-bar}, @code{horizontal-bar} Used for different types of fringe cursors. -@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark} +@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark} Not used by core Emacs features. @end table diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index e674280a83d..2c0ee3969b9 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -442,8 +442,18 @@ Redisplay the most recently known expression result in the echo area Display a backtrace, excluding Edebug's own functions for clarity (@code{edebug-backtrace}). -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. +@xref{Backtraces}, for a description of backtraces +and the commands which work on them. + +@findex edebug-backtrace-show-instrumentation +@findex edebug-backtrace-hide-instrumentation +If you would like to see Edebug's functions in the backtrace, +use @kbd{M-x edebug-backtrace-show-instrumentation}. To hide them +again use @kbd{M-x edebug-backtrace-hide-instrumentation}. + +If a backtrace frame starts with @samp{>} that means that Edebug knows +where the source code for the frame is located. Use @kbd{s} to jump +to the source code for the current frame. The backtrace buffer is killed automatically when you continue execution. @@ -1711,3 +1721,33 @@ Whether or not to pause for @code{edebug-sit-for-seconds} on reaching a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil} to allow it. @end defopt + +@defopt edebug-behavior-alist +By default, this alist contains one entry with the key @code{edebug} +and a list of three functions, which are the default implementations +of the functions inserted in instrumented code: @code{edebug-enter}, +@code{edebug-before} and @code{edebug-after}. To change Edebug's +behavior globally, modify the default entry. + +Edebug's behavior may also be changed on a per-definition basis by +adding an entry to this alist, with a key of your choice and three +functions. Then set the @code{edebug-behavior} symbol property of an +instrumented definition to the key of the new entry, and Edebug will +call the new functions in place of its own for that definition. +@end defopt + +@defopt edebug-new-definition-function +A function run by Edebug after it wraps the body of a definition +or closure. After Edebug has initialized its own data, this function +is called with one argument, the symbol associated with the +definition, which may be the actual symbol defined or one generated by +Edebug. This function may be used to set the @code{edebug-behavior} +symbol property of each definition instrumented by Edebug. +@end defopt + +@defopt edebug-after-instrumentation-function +To inspect or modify Edebug's instrumentation before it is used, set +this variable to a function which takes one argument, an instrumented +top-level form, and returns either the same or a replacement form, +which Edebug will then use as the final result of instrumentation. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a2b03da5abc..e18759654d9 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -455,6 +455,7 @@ Evaluation the program). * Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. Kinds of Forms @@ -654,7 +655,8 @@ The Lisp Debugger * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -1354,6 +1356,7 @@ Threads * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. Processes @@ -1398,7 +1401,6 @@ Packing and Unpacking Byte Arrays * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! Emacs Display diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index c794028b5e6..aa99b2b1a98 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -159,6 +159,11 @@ The message is @samp{No catch for tag}. @xref{Catch and Throw}. The message is @samp{Attempt to modify a protected file}. @end ignore +@item range-error +The message is @code{Arithmetic range error}. +This can happen with integers exceeding the @code{integer-width} limit. +@xref{Integer Basics}. + @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched @@ -223,9 +228,6 @@ The message is @samp{Arithmetic domain error}. The message is @samp{Arithmetic overflow error}. This is a subcategory of @code{domain-error}. -@item range-error -The message is @code{Arithmetic range error}. - @item singularity-error The message is @samp{Arithmetic singularity error}. This is a subcategory of @code{domain-error}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 4bf70d247b6..db42dfb6373 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -20,11 +20,12 @@ function @code{eval}. @ifnottex @menu -* 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. +* 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. +* Deferred Eval:: Deferred and lazy evaluation of forms. @end menu @node Intro Eval @@ -584,15 +585,15 @@ Here are some examples of expressions that use @code{quote}: @end group @group ''foo - @result{} (quote foo) + @result{} 'foo @end group @group '(quote foo) - @result{} (quote foo) + @result{} 'foo @end group @group ['foo] - @result{} [(quote foo)] + @result{} ['foo] @end group @end example @@ -883,3 +884,115 @@ particular elements, like this: @end group @end example @end defvar + +@node Deferred Eval +@section Deferred and Lazy Evaluation + +@cindex deferred evaluation +@cindex lazy evaluation + + + Sometimes it is useful to delay the evaluation of an expression, for +example if you want to avoid performing a time-consuming calculation +if it turns out that the result is not needed in the future of the +program. The @file{thunk} library provides the following functions +and macros to support such @dfn{deferred evaluation}: + +@cindex thunk +@defmac thunk-delay forms@dots{} +Return a @dfn{thunk} for evaluating the @var{forms}. A thunk is a +closure (@pxref{Closures}) that inherits the lexical environment of the +@code{thunk-delay} call. Using this macro requires +@code{lexical-binding}. +@end defmac + +@defun thunk-force thunk +Force @var{thunk} to perform the evaluation of the forms specified in +the @code{thunk-delay} that created the thunk. The result of the +evaluation of the last form is returned. The @var{thunk} also +``remembers'' that it has been forced: Any further calls of +@code{thunk-force} with the same @var{thunk} will just return the same +result without evaluating the forms again. +@end defun + +@defmac thunk-let (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let} but creates ``lazy'' variable +bindings. Any binding has the form @w{@code{(@var{symbol} +@var{value-form})}}. Unlike @code{let}, the evaluation of any +@var{value-form} is deferred until the binding of the according +@var{symbol} is used for the first time when evaluating the +@var{forms}. Any @var{value-form} is evaluated at most once. Using +this macro requires @code{lexical-binding}. +@end defmac + +Example: + +@example +@group +(defun f (number) + (thunk-let ((derived-number + (progn (message "Calculating 1 plus 2 times %d" number) + (1+ (* 2 number))))) + (if (> number 10) + derived-number + number))) +@end group + +@group +(f 5) +@result{} 5 +@end group + +@group +(f 12) +@print{} Calculating 1 plus 2 times 12 +@result{} 25 +@end group + +@end example + +Because of the special nature of lazily bound variables, it is an error +to set them (e.g.@: with @code{setq}). + + +@defmac thunk-let* (bindings@dots{}) forms@dots{} +This is like @code{thunk-let} but any expression in @var{bindings} is allowed +to refer to preceding bindings in this @code{thunk-let*} form. Using +this macro requires @code{lexical-binding}. +@end defmac + +@example +@group +(thunk-let* ((x (prog2 (message "Calculating x...") + (+ 1 1) + (message "Finished calculating x"))) + (y (prog2 (message "Calculating y...") + (+ x 1) + (message "Finished calculating y"))) + (z (prog2 (message "Calculating z...") + (+ y 1) + (message "Finished calculating z"))) + (a (prog2 (message "Calculating a...") + (+ z 1) + (message "Finished calculating a")))) + (* z x)) + +@print{} Calculating z... +@print{} Calculating y... +@print{} Calculating x... +@print{} Finished calculating x +@print{} Finished calculating y +@print{} Finished calculating z +@result{} 8 + +@end group +@end example + +@code{thunk-let} and @code{thunk-let*} use thunks implicitly: their +expansion creates helper symbols and binds them to thunks wrapping the +binding expressions. All references to the original variables in the +body @var{forms} are then replaced by an expression that calls +@code{thunk-force} with the according helper variable as the argument. +So, any code using @code{thunk-let} or @code{thunk-let*} could be +rewritten to use thunks, but in many cases using these macros results +in nicer code than using thunks explicitly. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 403a21b3365..5c99ea2781c 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1299,36 +1299,34 @@ Alternate names, also known as hard links, can be created by using the @item The file's @acronym{UID}, normally as a string (@code{file-attribute-user-id}). However, if it does not correspond -to a named user, the value is a number. +to a named user, the value is an integer. @item The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} -(@code{file-attribute-access-time}). (This is similar to the value of -@code{current-time}; see @ref{Time of Day}.) The value is truncated +The time of last access as a Lisp timestamp +(@code{file-attribute-status-change-time}). The timestamp is in the +style of @code{current-time} (@pxref{Time of Day}) and is truncated to that of the filesystem's timestamp resolution; for example, on some FAT-based filesystems, only the date of last access is recorded, so this time will always hold the midnight of the day of the last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above) +The time of last modification as a Lisp timestamp (@code{file-attribute-modification-time}). This is the last time when the file's contents were modified. @item -The time of last status change as a list of four integers (as above) +The time of last status change as a Lisp timestamp (@code{file-attribute-status-change-time}). This is the time of the last change to the file's access mode bits, its owner and group, and other information recorded in the filesystem for the file, beyond the file's contents. @item -The size of the file in bytes (@code{file-attribute-size}). This is -floating point if the size is too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). @item The file's modes, as a string of ten letters or dashes, as in @@ -1338,21 +1336,13 @@ The file's modes, as a string of ten letters or dashes, as in An unspecified value, present for backward compatibility. @item -The file's inode number (@code{file-attribute-inode-number}). If -possible, this is an integer. If the inode number is too large to be -represented as an integer in Emacs Lisp but dividing it by -@math{2^{16}} yields a representable integer, then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of -the form @code{(@var{high} @var{middle} . @var{low})}, where -@code{high} holds the high bits, @var{middle} the middle 24 bits, and -@var{low} the low 16 bits. +The file's inode number (@code{file-attribute-inode-number}), +a nonnegative integer. @item The filesystem number of the device that the file is on -@code{file-attribute-device-number}). Depending on the magnitude of -the value, this can be either an integer or a cons cell, in the same -manner as the inode number. This element and the file's inode number +@code{file-attribute-device-number}), an integer. +This element and the file's inode number together give enough information to distinguish any two files on the system---no two files can have the same values for both of these numbers. @@ -1368,8 +1358,8 @@ For example, here are the file attributes for @file{files.texi}: (20000 23 0 0) (20614 64555 902289 872000) 122295 "-rw-rw-rw-" - t (5888 2 . 43978) - (15479 . 46724)) + t 6473924464520138 + 1014478468) @end group @end example @@ -1410,10 +1400,10 @@ has a mode of read and write access for the owner, group, and world. @item t is merely a placeholder; it carries no information. -@item (5888 2 . 43978) +@item 6473924464520138 has an inode number of 6473924464520138. -@item (15479 . 46724) +@item 1014478468 is on the file-system device whose number is 1014478468. @end table @end defun @@ -1567,13 +1557,16 @@ For compatibility, @var{predicate} can also be one of the symbols a list of one or more of these symbols. @end defun -@defun executable-find program +@defun executable-find program &optional remote This function searches for the executable file of the named @var{program} and returns the absolute file name of the executable, including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories +the file is not found. The function searches in all the directories in @code{exec-path}, and tries all the file-name extensions in @code{exec-suffixes} (@pxref{Subprocess Creation}). + +If @var{remote} is non-@code{nil}, and @code{default-directory} is a +remote directory, @var{program} is searched on the respective remote host. @end defun @node Changing Files @@ -2131,7 +2124,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part, not an extension. @end defun -@defun file-name-base &optional filename +@defun file-name-base filename This function is the composition of @code{file-name-sans-extension} and @code{file-name-nondirectory}. For example, @@ -2139,8 +2132,6 @@ and @code{file-name-nondirectory}. For example, (file-name-base "/my/home/foo.c") @result{} "foo" @end example - -The @var{filename} argument defaults to @code{buffer-file-name}. @end defun @node Relative File Names @@ -2376,8 +2367,10 @@ start with @samp{~}.) Otherwise, the current buffer's value of @end example If the part of @var{filename} before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first +@samp{~}, it expands to your home directory, which is typically +specified by the value of the @env{HOME} environment variable +(@pxref{General Variables,,, emacs, The GNU Emacs Manual}). +If the part before the first slash is @samp{~@var{user}} and if @var{user} is a valid login name, it expands to @var{user}'s home directory. If you do not want this expansion for a relative @var{filename} that @@ -2927,7 +2920,7 @@ are included. This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead of returning a list of file names, it returns for each file a -list @code{(@var{filename} @var{attributes})}, where @var{attributes} +list @code{(@var{filename} . @var{attributes})}, where @var{attributes} is what @code{file-attributes} returns for that file. The optional argument @var{id-format} has the same meaning as the corresponding argument to @code{file-attributes} (@pxref{Definition @@ -3004,10 +2997,16 @@ This command creates a directory named @var{dirname}. If @var{parents} is non-@code{nil}, as is always the case in an interactive call, that means to create the parent directories first, if they don't already exist. - @code{mkdir} is an alias for this. @end deffn +@deffn Command make-empty-file filename &optional parents +This command creates an empty file named @var{filename}. +As @code{make-directory}, this command creates parent directories +if @var{parents} is non-@code{nil}. +If @var{filename} already exists, this command signals an error. +@end deffn + @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents This command copies the directory named @var{dirname} to @var{newname}. If @var{newname} is a directory name, @@ -3068,7 +3067,7 @@ expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that match. -@cindex file handler +@cindex file name handler @vindex file-name-handler-alist The variable @code{file-name-handler-alist} holds a list of handlers, together with regular expressions that determine when to apply each @@ -3139,8 +3138,8 @@ first, before handlers for jobs such as remote file access. @code{directory-file-name}, @code{directory-files}, @code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, +@code{dired-compress-file}, @code{dired-uncache}, +@code{exec-path}, @code{expand-file-name},@* @code{file-accessible-directory-p}, @code{file-acl}, @code{file-attributes}, @@ -3161,7 +3160,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @@ -3171,6 +3171,7 @@ first, before handlers for jobs such as remote file access. @code{make-directory}, @code{make-directory-internal}, @code{make-nearby-temp-file}, +@code{make-process}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3196,7 +3197,7 @@ first, before handlers for jobs such as remote file access. @code{directory-files}, @code{directory-files-and-at@discretionary{}{}{}tributes}, @code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, +@code{exec-path}, @code{expand-file-name}, @code{file-accessible-direc@discretionary{}{}{}tory-p}, @code{file-acl}, @code{file-attributes}, @@ -3217,7 +3218,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, @code{get-file-buffer}, @code{insert-directory}, @@ -3226,6 +3228,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @code{make-direc@discretionary{}{}{}tory-internal}, +@code{make-process}, @code{make-symbolic-link}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3353,8 +3356,8 @@ If @code{file-remote-p} returns the same identifier for two different filenames, that means they are stored on the same file system and can be accessed locally with respect to each other. This means, for example, that it is possible to start a remote process accessing both -files at the same time. Implementers of file handlers need to ensure -this principle is valid. +files at the same time. Implementers of file name handlers need to +ensure this principle is valid. @var{identification} specifies which part of the identifier shall be returned as string. @var{identification} can be the symbol @@ -3424,8 +3427,9 @@ between consecutive checks. For example: (let ((remote-file-name-inhibit-cache (- display-time-interval 5))) (and (file-exists-p file) - (< 0 (nth 7 (file-attributes - (file-chase-links file))))))) + (< 0 (file-attribute-size + (file-attributes + (file-chase-links file))))))) @end example @end defopt diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b993f4932cd..8cb406cded3 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -181,6 +181,12 @@ the value of that parameter in the created frame to its value in the selected frame. @end defvar +@defopt server-after-make-frame-hook +A normal hook run when the Emacs server creates a client frame. When +this hook is called, the created frame is the selected one. +@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@end defopt + @node Multiple Terminals @section Multiple Terminals @@ -2524,6 +2530,7 @@ it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions +@vindex after-delete-frame-functions This function deletes the frame @var{frame}. The argument @var{frame} must specify a live frame (see below) and defaults to the selected frame. @@ -2535,7 +2542,9 @@ performed recursively; so this step makes sure that no other frames with @var{frame} as their ancestor will exist. Then, unless @var{frame} specifies a tooltip, this function runs the hook @code{delete-frame-functions} (each function getting one argument, -@var{frame}) before actually killing the frame. +@var{frame}) before actually killing the frame. After actually killing +the frame and removing the frame from the frame list, @code{delete-frame} +runs @code{after-delete-frame-functions}. Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -2696,14 +2705,22 @@ This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To +way, Emacs automatically keeps track of which frames have focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames temporarily by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. +The plural ``frames'' in the previous paragraph is deliberate: while +Emacs itself has only one selected frame, Emacs can have frames on +many different terminals (recall that a connection to a window system +counts as a terminal), and each terminal has its own idea of which +frame has input focus. When you set the input focus to a frame, you +set the focus for that frame's terminal, but frames on other terminals +may still remain focused. + +Lisp programs can switch frames temporarily by calling the function +@code{select-frame}. This does not alter the window system's concept +of focus; rather, it escapes from the window manager's control until +that control is somehow reasserted. When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to @code{select-frame}, the next @@ -2714,11 +2731,11 @@ before the buffer name (@pxref{Mode Line Variables}). @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 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. +obscured by other frames) and tries to give it the window system's +focus. On a text 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 Ideally, the function described next should focus a frame without also @@ -2766,17 +2783,35 @@ could switch to a different terminal without switching back when you're done. @end deffn -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. +@cindex text-terminal focus notification +Emacs cooperates with the window system by arranging to select frames +as the server and window manager request. When a window system +informs Emacs that one of its frames has been selected, Emacs +internally generates a @dfn{focus-in} event. When an Emacs frame is +displayed on a text-terminal emulator, such as @command{xterm}, which +supports reporting of focus-change notification, the focus-in and +focus-out events are available even for text-mode frames. Focus +events are normally handled by @code{handle-focus-in}. + +@deffn Command handle-focus-in event +This function handles focus-in events from window systems and +terminals that support explicit focus notifications. It updates the +per-frame focus flags that @code{frame-focus-state} queries and calls +@code{after-focus-change-function}. In addition, it generates a +@code{switch-frame} event in order to switch the Emacs notion of the +selected frame to the frame most recently focused in some terminal. +It's important to note that this switching of the Emacs selected frame +to the most recently focused frame does not mean that other frames do +not continue to have the focus in their respective terminals. Do not +invoke this function yourself: instead, attach logic to +@code{after-focus-change-function}. +@end deffn @deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. +This function handles a switch-frame event, which Emacs generates for +itself upon focus notification or under various other circumstances +involving an input event arriving at a different frame from the last +event. Do not invoke this function yourself. @end deffn @defun redirect-frame-focus frame &optional focus-frame @@ -2810,14 +2845,42 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun -@defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. The -frame gaining focus is selected when this hook is run. -@end defvar +@defun frame-focus-state frame +This function retrieves the last known focus state of @var{frame}. + +It returns @code{nil} if the frame is known not to be focused, +@code{t} if the frame is known to be focused, or @code{unknown} if +Emacs does not know the focus state of the frame. (You may see this +last state in TTY frames running on terminals that do not support +explicit focus notifications.) +@end defun -@defvar focus-out-hook -This is a normal hook run when an Emacs frame has lost input focus and -no other Emacs frame has gained input focus instead. +@defvar after-focus-change-function +This function is an extension point that code can use to receive a +notification that focus has changed. + +This function is called with no arguments when Emacs notices that the +set of focused frames may have changed. Code wanting to do something +when frame focus changes should use @code{add-function} to add a +function to this one, and in this added function, re-scan the set of +focused frames, calling @code{frame-focus-state} to retrieve the last +known focus state of each frame. Focus events are delivered +asynchronously, and frame input focus according to an external system +may not correspond to the notion of the Emacs selected frame. +Multiple frames may appear to have input focus simultaneously due to +focus event delivery differences, the presence of multiple Emacs +terminals, and other factors, and code should be robust in the face of +this situation. + +Depending on window system, focus events may also be delivered +repeatedly and with different focus states before settling to the +expected values. Code relying on focus notifications should +``debounce'' any user-visible updates arising from focus changes, +perhaps by deferring work until redisplay. + +This function may be called in arbitrary contexts, including from +inside @code{read-event}, so take the same care as you might when +writing a process filter. @end defvar @defopt focus-follows-mouse diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index d01804e4940..222f863c988 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -371,8 +371,8 @@ keyword @code{&rest} before one final argument. @example @group (@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) + @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]} + @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]}) @end group @end example @@ -1242,7 +1242,7 @@ This form defines a method like @code{cl-defmethod} does. @end table @end defmac -@defmac cl-defmethod name [qualifier] arguments &rest [docstring] body +@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body This macro defines a particular implementation for the generic function called @var{name}. The implementation code is given by @var{body}. If present, @var{docstring} is the documentation string @@ -1269,15 +1269,20 @@ defined with @code{cl-defstruct} (@pxref{Structures,,, cl, Common Lisp Extensions for GNU Emacs Lisp}), or of one of its child classes. @end table -Alternatively, the argument specializer can be of the form -@code{&context (@var{expr} @var{spec})}, in which case the value of -@var{expr} must be compatible with the specializer provided by -@var{spec}; @var{spec} can be any of the forms described above. In -other words, this form of specializer uses the value of @var{expr} -instead of arguments for the decision whether the method is -applicable. For example, @code{&context (overwrite-mode (eql t))} -will make the method compatible only when @code{overwrite-mode} is -turned on. +Method definitions can make use of a new argument-list keyword, +@code{&context}, which introduces extra specializers that test the +environment at the time the method is run. This keyword should appear +after the list of required arguments, but before any @code{&rest} or +@code{&optional} keywords. The @code{&context} specializers look much +like regular argument specializers---(@var{expr} @var{spec})---except +that @var{expr} is an expression to be evaluated in the current +context, and the @var{spec} is a value to compare against. For +example, @code{&context (overwrite-mode (eql t))} will make the method +applicable only when @code{overwrite-mode} is turned on. The +@code{&context} keyword can be followed by any number of context +specializers. Because the context specializers are not part of the +generic function's argument signature, they may be omitted in methods +that don't require them. The type specializer, @code{(@var{arg} @var{type})}, can specify one of the @dfn{system types} in the following list. When a parent type diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index d5c9948ca73..5aaf31247b4 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -300,8 +300,8 @@ the same integer. @defun sxhash-eql obj This function returns a hash code for Lisp object @var{obj} suitable for @code{eql} comparison. I.e. it reflects identity of @var{obj} -except for the case where the object is a float number, in which case -hash code is generated for the value. +except for the case where the object is a bignum or a float number, +in which case a hash code is generated for the value. If two objects @var{obj1} and @var{obj2} are @code{eql}, then @code{(sxhash-eql @var{obj1})} and @code{(sxhash-eql @var{obj2})} are diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 7c8748b5e48..71992464e09 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -66,6 +66,7 @@ not exactly a hook, but does a similar job. @item after-make-frame-functions @itemx before-make-frame-hook +@itemx server-after-make-frame-hook @xref{Creating Frames}. @c Not general enough? @@ -123,6 +124,7 @@ The command loop runs this soon after @code{post-command-hook} (q.v.). @xref{Input Focus}. @item delete-frame-functions +@itemx after-delete-frame-functions @xref{Deleting Frames}. @item delete-terminal-functions diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 38d84f149e0..d7c1fb7e422 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -247,8 +247,8 @@ of 8k bytes, and small vectors are packed into blocks of 4k bytes). @cindex vector-like objects, storage @cindex storage of vector-like Lisp objects - Beyond the basic vector, a lot of objects like window, buffer, and -frame are managed as if they were vectors. The corresponding C data + Beyond the basic vector, a lot of objects like markers, overlays and +buffers are managed as if they were vectors. The corresponding C data structures include the @code{union vectorlike_header} field whose @code{size} member contains the subtype enumerated by @code{enum pvec_type} and an information about how many @code{Lisp_Object} fields this structure @@ -319,7 +319,6 @@ future allocations. So an overall result is: @example ((@code{conses} @var{cons-size} @var{used-conses} @var{free-conses}) (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols}) - (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs}) (@code{strings} @var{string-size} @var{used-strings} @var{free-strings}) (@code{string-bytes} @var{byte-size} @var{used-bytes}) (@code{vectors} @var{vector-size} @var{used-vectors}) @@ -335,7 +334,7 @@ Here is an example: @example (garbage-collect) @result{} ((conses 16 49126 8058) (symbols 48 14607 0) - (miscs 40 34 56) (strings 32 2942 2607) + (strings 32 2942 2607) (string-bytes 1 78607) (vectors 16 7247) (vector-slots 8 341609 29474) (floats 8 71 102) (intervals 56 27 26) (buffers 944 8) @@ -367,19 +366,6 @@ The number of symbols in use. The number of symbols for which space has been obtained from the operating system, but that are not currently being used. -@item misc-size -Internal size of a miscellaneous entity, i.e., -@code{sizeof (union Lisp_Misc)}, which is a size of the -largest type enumerated in @code{enum Lisp_Misc_Type}. - -@item used-miscs -The number of miscellaneous objects in use. These include markers -and overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - @item string-size Internal size of a string header, i.e., @code{sizeof (struct Lisp_String)}. @@ -397,7 +383,7 @@ This is used for convenience and equals to @code{sizeof (char)}. The total size of all string data in bytes. @item vector-size -Internal size of a vector header, i.e., @code{sizeof (struct Lisp_Vector)}. +Size in bytes of a vector of length 1, including its header. @item used-vectors The number of vector headers allocated from the vector blocks. @@ -407,6 +393,8 @@ Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}. @item used-slots The number of slots in all used vectors. +Slot counts might include some or all overhead from vector headers, +depending on the platform. @item free-slots The number of free slots in all vector blocks. @@ -508,10 +496,8 @@ function @code{memory-limit} provides information on the total amount of memory Emacs is currently using. @defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - +This function returns an estimate of the total amount of bytes of +virtual memory that Emacs is currently using, divided by 1024. You can use this to get a general idea of how your actions affect the memory usage. @end defun @@ -596,6 +582,8 @@ in this Emacs session. @defvar vector-cells-consed The total number of vector cells that have been allocated so far in this Emacs session. +This includes vector-like objects such as markers and overlays, plus +certain objects not visible to users. @end defvar @defvar symbols-consed @@ -608,12 +596,6 @@ The total number of string characters that have been allocated so far in this session. @end defvar -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - @defvar intervals-consed The total number of intervals that have been allocated so far in this Emacs session. @@ -760,6 +742,13 @@ names in the documentation string from the ones used in the C code. @samp{usage:} is required if the function has an unlimited number of arguments. +Some primitives have multiple definitions, one per platform (e.g., +@code{x-create-frame}). In such cases, rather than writing the +same documentation string in each definition, only one definition has +the actual documentation. The others have placeholders beginning with +@samp{SKIP}, which are ignored by the function that parses the +@file{DOC} file. + All the usual rules for documentation strings in Lisp code (@pxref{Documentation Tips}) apply to C code documentation strings too. @@ -1699,7 +1688,7 @@ a special type to represent the pointers to all of them, which is known as In C, the tagged pointer is an object of type @code{Lisp_Object}. Any initialized variable of such a type always holds the value of one of the following basic data types: integer, symbol, string, cons cell, float, -vectorlike or miscellaneous object. Each of these data types has the +or vectorlike object. Each of these data types has the corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the bits is the value itself. Integers are immediate, i.e., directly @@ -1731,18 +1720,13 @@ Symbol, the unique-named entity commonly used as an identifier. @item struct Lisp_Float Floating-point value. - -@item union Lisp_Misc -Miscellaneous kinds of objects which don't fit into any of the above. @end table These types are the first-class citizens of an internal type system. -Since the tag space is limited, all other types are the subtypes of either -@code{Lisp_Vectorlike} or @code{Lisp_Misc}. Vector subtypes are enumerated +Since the tag space is limited, all other types are the subtypes of +@code{Lisp_Vectorlike}. Vector subtypes are enumerated by @code{enum pvec_type}, and nearly all complex objects like windows, buffers, -frames, and processes fall into this category. The rest of special types, -including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type} -and form the set of subtypes of @code{Lisp_Misc}. +frames, and processes fall into this category. Below there is a description of a few subtypes of @code{Lisp_Vectorlike}. Buffer object represents the text to display and edit. Window is the part diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 2b5f7905258..2596e87939b 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -493,7 +493,7 @@ giving a prefix argument makes @var{here} non-@code{nil}. @defvar emacs-build-time The value of this variable indicates the time at which Emacs was -built. It is a list of four integers, like the value of +built. It uses the style of @code{current-time} (@pxref{Time of Day}), or is @code{nil} if the information is not available. @@ -530,6 +530,18 @@ directory (without cleaning). This is only of relevance when developing Emacs. @end defvar +@defvar emacs-repository-version +A string that gives the repository revision from which Emacs was +built. If Emacs was built outside revision control, the value is +@code{nil}. +@end defvar + +@defvar emacs-repository-branch +A string that gives the repository branch from which Emacs was built. +In the most cases this is @code{"master"}. If Emacs was built outside +revision control, the value is @code{nil}. +@end defvar + @node Acknowledgments @section Acknowledgments diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ccc75a9c7af..cc0386c8fc7 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1660,7 +1660,7 @@ to turn the character that follows into a Hyper character: (defun hyperify (prompt) (let ((e (read-event))) (vector (if (numberp e) - (logior (lsh 1 24) e) + (logior (ash 1 24) e) (if (memq 'hyper (event-modifiers e)) e (add-event-modifier "H-" e)))))) @@ -2443,7 +2443,7 @@ Next we define the menu items: @smallexample (define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue + '(menu-item "Continue Replace" multifile-continue :help "Continue last tags replace operation")) (define-key menu-bar-replace-menu [tags-repl] '(menu-item "Replace in tagged files" tags-query-replace diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 615f21581aa..746b4643c18 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -156,6 +156,22 @@ considered a list and @code{not} when it is considered a truth value @end example @end defun +@defun proper-list-p object +This function returns the length of @var{object} if it is a proper +list, @code{nil} otherwise (@pxref{Cons Cells}). In addition to +satisfying @code{listp}, a proper list is neither circular nor dotted. + +@example +@group +(proper-list-p '(a b c)) + @result{} 3 +@end group +@group +(proper-list-p '(a b . c)) + @result{} nil +@end group +@end example +@end defun @node List Elements @section Accessing Elements of Lists @@ -651,8 +667,20 @@ non-@code{nil}, it copies vectors too (and operates recursively on their elements). @end defun +@defun flatten-tree tree +This function returns a ``flattened'' copy of @var{tree}, that is, +a list containing all the non-@code{nil} terminal nodes, or leaves, of +the tree of cons cells rooted at @var{tree}. Leaves in the returned +list are in the same order as in @var{tree}. +@end defun + +@example +(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) + @result{}(1 2 3 4 5 6 7) +@end example + @defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and +This function returns a list of numbers starting with @var{from} and incrementing by @var{separation}, and ending at or just before @var{to}. @var{separation} can be positive or negative and defaults to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, @@ -1144,7 +1172,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) + @result{} (lambda (x) (nconc '(foo) x)) @end group @group @@ -1162,7 +1190,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) + @result{} (lambda (x) (nconc '(foo 1 2 3 4) x)) @end group @end smallexample @end defun @@ -1736,11 +1764,12 @@ alist @end example @end defun -@defun assoc-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{equal} to @var{key}. It works like @code{assq-delete-all}, -except for the predicate used for comparing alist elements with -@var{key}. +@defun assoc-delete-all key alist &optional test +This function is like @code{assq-delete-all} except that it accepts +an optional argument @var{test}, a predicate function to compare the +keys in @var{alist}. If omitted or @code{nil}, @var{test} defaults to +@code{equal}. As @code{assq-delete-all}, this function often modifies +the original list structure of @var{alist}. @end defun @defun rassq-delete-all value alist diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index f0cc689d1f6..6f1213f097b 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -641,7 +641,7 @@ autoloading with a magic comment: Here's what that produces in @file{loaddefs.el}: @example -(autoload (quote doctor) "doctor" "\ +(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy. \(fn)" t nil) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 0c0862160bf..766079d7bcd 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -634,6 +634,12 @@ A history list for arguments that are Lisp expressions to evaluate. A history list for arguments that are faces. @end defvar +@findex read-variable@r{, history list} +@defvar custom-variable-history +A history list for variable-name arguments read by +@code{read-variable}. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. @@ -2240,7 +2246,7 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does not echo the password as the user types it; instead, it echoes -@samp{.} for each character in the password. If you want to apply +@samp{*} for each character in the password. If you want to apply another character to hide the password, let-bind the variable @code{read-hide-char} with that character. @@ -2503,7 +2509,7 @@ locally inside the minibuffer (@pxref{Help Functions}). @anchor{Definition of minibuffer-scroll-window} If the value of this variable is non-@code{nil}, it should be a window object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. +minibuffer, it scrolls this window (@pxref{Textual Scrolling}). @end defvar @defun minibuffer-selected-window diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 9df1a69e907..143cc7c5827 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -197,6 +197,7 @@ from the buffer-local hook list instead of from the global hook list. @cindex major mode @cindex major mode command +@cindex suspend major mode temporarily Major modes specialize Emacs for editing or interacting with particular kinds of text. Each buffer has exactly one major mode at a time. Every major mode is associated with a @dfn{major mode command}, @@ -205,7 +206,8 @@ switching to that mode in the current buffer, by setting various buffer-local variables such as a local keymap. @xref{Major Mode Conventions}. Note that unlike minor modes there is no way to ``turn off'' a major mode, instead the buffer must be switched to a different -one. +one. However, you can temporarily @dfn{suspend} a major mode and later +@dfn{restore} the suspended mode, see below. The least specialized major mode is called @dfn{Fundamental mode}, which has no mode-specific definitions or variable settings. @@ -216,6 +218,24 @@ commands, it does @emph{not} run any mode hooks (@pxref{Major Mode Conventions}), since you are not supposed to customize this mode. @end deffn +@defun major-mode-suspend +This function works like @code{fundamental-mode}, in that it kills all +buffer-local variables, but it also records the major mode in effect, +so that it could subsequently be restored. This function and +@code{major-mode-restore} (described next) are useful when you need to +put a buffer under some specialized mode other than the one Emacs +chooses for it automatically (@pxref{Auto Major Mode}), but would also +like to be able to switch back to the original mode later. +@end defun + +@defun major-mode-restore &optional avoided-modes +This function restores the major mode recorded by +@code{major-mode-suspend}. If no major mode was recorded, this +function calls @code{normal-mode} (@pxref{Auto Major Mode, +normal-mode}), but tries to force it not to choose any modes in +@var{avoided-modes}, if that argument is non-@code{nil}. +@end defun + The easiest way to write a major mode is to use the macro @code{define-derived-mode}, which sets up the new mode as a variant of an existing major mode. @xref{Derived Modes}. We recommend using diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index ab15ea7d9b2..c734a994a07 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -829,18 +829,18 @@ two functions support these conversions. This function decodes a character that is assigned a @var{code-point} in @var{charset}, to the corresponding Emacs character, and returns it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be +the value is @code{nil}. + +For backward compatibility, if @var{code-point} doesn't fit in a Lisp +fixnum (@pxref{Integer Basics, most-positive-fixnum}), it can be specified as a cons cell @code{(@var{high} . @var{low})}, where @var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. +high 16 bits. This usage is obsolescent. @end defun @defun encode-char char charset This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If +@var{char} in @var{charset}. If @var{charset} doesn't have a codepoint for @var{char}, the value is @code{nil}. @end defun diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index e7beed0073d..cffc634169f 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -14,9 +14,9 @@ fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can also be expressed in exponential notation: @samp{1.5e2} is the same as @samp{150.0}; here, @samp{e2} stands for ten to the second power, and -that is multiplied by 1.5. Integer computations are exact, though -they may overflow. Floating-point computations often involve rounding -errors, as the numbers have a fixed amount of precision. +that is multiplied by 1.5. Integer computations are exact. +Floating-point computations often involve rounding errors, as the +numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -34,7 +34,23 @@ errors, as the numbers have a fixed amount of precision. @node Integer Basics @section Integer Basics - The range of values for an integer depends on the machine. The + Integers in Emacs Lisp are not limited to the machine word size. + + Under the hood, though, there are two kinds of integers: smaller +ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}. +Some functions in Emacs accept only fixnums. Also, while fixnums can +always be compared for numeric equality with @code{eq}, bignums +require more-heavyweight equality predicates like @code{eql}. + + The range of values for bignums is limited by the amount of main +memory, by machine characteristics such as the size of the word used +to represent a bignum's exponent, and by the @code{integer-width} +variable. These limits are typically much more generous than the +limits for fixnums. A bignum is never numerically equal to a fixnum; +if Emacs computes an integer in fixnum range, it represents the +integer as a fixnum, not a bignum. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -49,21 +65,17 @@ to @tex @math{2^{29}-1}), @end tex -but many machines provide a wider range. Many examples in this -chapter assume the minimum integer width of 30 bits. -@cindex overflow +but many machines provide a wider range. - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. + The Lisp reader reads an integer as a nonempty sequence +of decimal digits with optional initial sign and optional +final period. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -74,14 +86,17 @@ Emacs range is treated as a floating-point number. @cindex hex numbers @cindex octal numbers @cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads + The syntax for integers in bases other than 10 consists of @samp{#} +followed by a radix indication followed by one or more digits. The +radix indications are @samp{b} for binary, @samp{o} for octal, +@samp{x} for hex, and @samp{@var{radix}r} for radix @var{radix}. +Thus, @samp{#b@var{integer}} reads @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads @var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: +from 2 to 36, and allowed digits are the first @var{radix} characters +taken from @samp{0}--@samp{9}, @samp{A}--@samp{Z}. +Letter case is ignored and there is no initial sign or final period. +For example: @example #b101100 @result{} 44 @@ -94,26 +109,26 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 30-bit binary, the decimal integer 5 looks like this: + In binary, the decimal integer 5 looks like this: @example -0000...000101 (30 bits total) +@dots{}000101 @end example @noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) +(The ellipsis @samp{@dots{}} stands for a conceptually infinite number +of bits that match the leading bit; here, an infinite number of 0 +bits. Later examples also use this @samp{@dots{}} notation.) The integer @minus{}1 looks like this: @example -1111...111111 (30 bits total) +@dots{}111111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's +@minus{}1 is represented as all ones. (This is called @dfn{two's complement} notation.) Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. @@ -121,24 +136,7 @@ In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) +@dots{}111011 @end example Many of the functions described in this chapter accept markers for @@ -147,11 +145,11 @@ arguments to such functions may be either numbers or markers, we often give these arguments the name @var{number-or-marker}. When the argument value is a marker, its position value is used and its buffer is ignored. -@cindex largest Lisp integer -@cindex maximum Lisp integer +@cindex largest fixnum +@cindex maximum fixnum @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp can -handle. Typical values are +The value of this variable is the greatest ``small'' integer that Emacs +Lisp can handle. Typical values are @ifnottex 2**29 @minus{} 1 @end ifnottex @@ -168,11 +166,11 @@ on 32-bit and on 64-bit platforms. @end defvar -@cindex smallest Lisp integer -@cindex minimum Lisp integer +@cindex smallest fixnum +@cindex minimum fixnum @defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. Typical values are +The value of this variable is the numerically least ``small'' integer +that Emacs Lisp can handle. It is negative. Typical values are @ifnottex @minus{}2**29 @end ifnottex @@ -189,6 +187,26 @@ on 32-bit and on 64-bit platforms. @end defvar +@cindex bignum range +@cindex integer range +@cindex number of bignum bits, limit on +@defvar integer-width +The value of this variable is a nonnegative integer that is an upper +bound on the number of bits in a bignum. Integers outside the fixnum +range are limited to absolute values less than +@ifnottex +2**@var{n}, +@end ifnottex +@tex +@math{2^{n}}, +@end tex +where @var{n} is this variable's value. Attempts to create bignums outside +this range signal a range error. Setting this variable +to zero disables creation of bignums; setting it to a large number can +cause Emacs to consume large quantities of memory if a computation +creates huge integers. +@end defvar + In Emacs Lisp, text characters are represented by integers. Any integer between zero and the value of @code{(max-char)}, inclusive, is considered to be valid as a character. @xref{Character Codes}. @@ -213,7 +231,7 @@ least one digit after any decimal point in a floating-point number; @samp{1500.} is an integer, not a floating-point number. Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero -with respect to @code{equal} and @code{=}. This follows the +with respect to numeric comparisons like @code{=}. This follows the @acronym{IEEE} floating-point standard, which says @code{-0.0} and @code{0.0} are numerically equal even though other operations can distinguish them. @@ -227,8 +245,20 @@ 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@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. +A NaN is never numerically equal to any value, not even to itself. +NaNs carry a sign and a significand, and non-numeric functions treat +two NaNs as equal when their +signs and significands agree. Significands of NaNs are +machine-dependent, as are the digits in their string representation. + + When NaNs and signed zeros are involved, non-numeric functions like +@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and +@code{gethash} determine whether values are indistinguishable, not +whether they are numerically equal. For example, when @var{x} and +@var{y} are the same NaN, @code{(equal x y)} returns @code{t} whereas +@code{(= x y)} uses numeric comparison and returns @code{nil}; +conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas +@code{(= 0.0 -0.0)} returns @code{t}. Here are read syntaxes for these special floating-point values: @@ -305,6 +335,18 @@ use otherwise), but the @code{zerop} predicate requires a number as its argument. See also @code{integer-or-marker-p} and @code{number-or-marker-p}, in @ref{Predicates on Markers}. +@defun bignump object +This predicate tests whether its argument is a large integer, and +returns @code{t} if so, @code{nil} otherwise. Unlike small integers, +large integers can be @code{=} or @code{eql} even if they are not @code{eq}. +@end defun + +@defun fixnump object +This predicate tests whether its argument is a small integer, and +returns @code{t} if so, @code{nil} otherwise. Small integers can be +compared with @code{eq}. +@end defun + @defun floatp object This predicate tests whether its argument is floating point and returns @code{t} if so, @code{nil} otherwise. @@ -344,23 +386,27 @@ if so, @code{nil} otherwise. The argument must be a number. @cindex comparing numbers To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating-point -objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - In Emacs Lisp, each integer is a unique Lisp object. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing -an unknown value with an integer, because @code{eq} does not report an +@code{=} instead of non-numeric comparison predicates like @code{eq}, +@code{eql} and @code{equal}. Distinct floating-point and large +integer objects can be numerically equal. If you use @code{eq} to +compare them, you test whether they are the same @emph{object}; if you +use @code{eql} or @code{equal}, you test whether their values are +@emph{indistinguishable}. In contrast, @code{=} uses numeric +comparison, and sometimes returns @code{t} when a non-numeric +comparison would return @code{nil} and vice versa. @xref{Float +Basics}. + + In Emacs Lisp, if two fixnums are numerically equal, they are the +same Lisp object. That is, @code{eq} is equivalent to @code{=} on +fixnums. It is sometimes convenient to use @code{eq} for comparing +an unknown value with a fixnum, because @code{eq} does not report an error if the unknown value is not a number---it accepts arguments of any type. By contrast, @code{=} signals an error if the arguments are not numbers or markers. However, it is better programming practice to use @code{=} if you can, even for comparing integers. - Sometimes it is useful to compare numbers with @code{equal}, which -treats two numbers as equal if they have the same data type (both + Sometimes it is useful to compare numbers with @code{eql} or @code{equal}, +which treat two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, @code{=} can treat an integer and a floating-point number as equal. @xref{Equality Predicates}. @@ -379,15 +425,6 @@ Here's a function to do this: fuzz-factor))) @end example -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integers. -@end quotation - @defun = number-or-marker &rest number-or-markers This function tests whether all its arguments are numerically equal, and returns @code{t} if so, @code{nil} otherwise. @@ -397,7 +434,8 @@ and returns @code{t} if so, @code{nil} otherwise. This function acts like @code{eq} except when both arguments are numbers. It compares numbers by type and numeric value, so that @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. +@code{(eql 1 1)} both return @code{t}. This can be used to compare +large integers as well as small ones. @end defun @defun /= number-or-marker1 number-or-marker2 @@ -557,10 +595,6 @@ Except for @code{%}, each of these functions accepts both integer and floating-point arguments, and returns a floating-point number if any argument is floating point. - Emacs Lisp arithmetic functions do not check for integer overflow. -Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. For example, @@ -814,181 +848,119 @@ Rounding a value equidistant between two integers returns the even integer. @cindex logical arithmetic In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise +sequence of @dfn{bits} (digits which are either zero or one). +Conceptually the bit sequence is infinite on the left, with the +most-significant bits being all zeros or all ones. A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} is +negative. Left shifts introduce zero bits on the right; right shifts +discard the rightmost bits. Considered as an integer operation, +@code{ash} multiplies @var{integer1} by +@ifnottex +2**@var{count}, +@end ifnottex +@tex +@math{2^{count}}, +@end tex +and then converts the result to an integer by rounding downward, toward +minus infinity. -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. +Here are examples of @code{ash}, shifting a pattern of bits one place +to the left and to the right. These examples show only the low-order +bits of the binary pattern; leading bits all agree with the +highest-order bit shown. As you can see, shifting left by one is +equivalent to multiplying by two, whereas shifting right by one is +equivalent to dividing by two and then rounding toward minus infinity. @example @group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 +(ash 7 1) @result{} 14 ;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 +@dots{}000111 + @result{} +@dots{}001110 @end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): -@example @group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 +(ash 7 -1) @result{} 3 +@dots{}000111 + @result{} +@dots{}000011 @end group -@end example -On the other hand, shifting one place to the right looks like this: - -@example @group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 +(ash -7 1) @result{} -14 +@dots{}111001 + @result{} +@dots{}110010 @end group @group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 +(ash -7 -1) @result{} -4 +@dots{}111001 + @result{} +@dots{}111100 @end group @end example -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. +Here are examples of shifting left or right by two bits: -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example +@smallexample @group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) + ; @r{ binary values} +(ash 5 2) ; 5 = @r{@dots{}000101} + @result{} 20 ; = @r{@dots{}010100} +(ash -5 2) ; -5 = @r{@dots{}111011} + @result{} -20 ; = @r{@dots{}101100} @end group -@end example - -@noindent -which becomes the following when left shifted: - -@example @group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) +(ash 5 -2) + @result{} 1 ; = @r{@dots{}000001} @end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example @group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) +(ash -5 -2) + @result{} -2 ; = @r{@dots{}111110} @end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: +@end smallexample +@end defun -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the right +if @var{count} is negative, bringing zeros into the vacated bits. If +@var{count} is negative, then @var{integer1} must be either a fixnum +or a positive bignum, and @code{lsh} treats a negative fixnum as if it +were unsigned by subtracting twice @code{most-negative-fixnum} before +shifting, producing a nonnegative result. This quirky behavior dates +back to when Emacs supported only fixnums; nowadays @code{ash} is a +better choice. -Here are other examples: +As @code{lsh} behaves like @code{ash} except when @var{integer1} and +@var{count1} are both negative, the following examples focus on these +exceptional cases. These examples assume 30-bit fixnums. -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} + ; @r{ binary values} +(ash -7 -1) ; -7 = @r{@dots{}111111111111111111111111111001} + @result{} -4 ; = @r{@dots{}111111111111111111111111111100} +(lsh -7 -1) + @result{} 536870908 ; = @r{@dots{}011111111111111111111111111100} @end group @group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} +(ash -5 -2) ; -5 = @r{@dots{}111111111111111111111111111011} + @result{} -2 ; = @r{@dots{}111111111111111111111111111110} +(lsh -5 -2) + @result{} 268435454 ; = @r{@dots{}001111111111111111111111111110} @end group @end smallexample @end defun @@ -1022,23 +994,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} +(logand 14 13) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + @result{} 12 ; 12 = @r{@dots{}001100} @end group @group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} +(logand 14 13 4) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + ; 4 = @r{@dots{}000100} + @result{} 4 ; 4 = @r{@dots{}000100} @end group @group (logand) - @result{} -1 ; -1 = @r{1111...111111} + @result{} -1 ; -1 = @r{@dots{}111111} @end group @end smallexample @end defun @@ -1052,18 +1024,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} +(logior 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 13 ; 13 = @r{@dots{}001101} @end group @group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} +(logior 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 15 ; 15 = @r{@dots{}001111} @end group @end smallexample @end defun @@ -1077,18 +1049,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} +(logxor 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 9 ; 9 = @r{@dots{}001001} @end group @group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} +(logxor 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 14 ; 14 = @r{@dots{}001110} @end group @end smallexample @end defun @@ -1101,9 +1073,27 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @example (lognot 5) @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) +;; 5 = @r{@dots{}000101} ;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) +;; -6 = @r{@dots{}111010} +@end example +@end defun + +@cindex popcount +@cindex Hamming weight +@cindex counting set bits +@defun logcount integer +This function returns the @dfn{Hamming weight} of @var{integer}: the +number of ones in the binary representation of @var{integer}. +If @var{integer} is negative, it returns the number of zero bits in +its two's complement binary representation. The result is always +nonnegative. + +@example +(logcount 43) ; 43 = @r{@dots{}000101011} + @result{} 4 +(logcount -43) ; -43 = @r{@dots{}111010101} + @result{} 3 @end example @end defun @@ -1189,8 +1179,8 @@ returns a NaN. @defun expt x y This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. +arguments are integers and @var{y} is nonnegative, the result is an +integer; in this case, overflow signals an error, so watch out. If @var{x} is a finite negative number and @var{y} is a finite non-integer, @code{expt} returns a NaN. @end defun @@ -1241,11 +1231,10 @@ other strings to choose various seed values. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is a positive integer, the value is chosen to be +If @var{limit} is a positive fixnum, the value is chosen to be nonnegative and less than @var{limit}. Otherwise, the value might be -any integer representable in Lisp, i.e., an integer between -@code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). +any fixnum, i.e., any integer from @code{most-negative-fixnum} through +@code{most-positive-fixnum} (@pxref{Integer Basics}). If @var{limit} is @code{t}, it means to choose a new seed as if Emacs were restarting, typically from the system entropy. On systems diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 69b6c859f65..745baacc297 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -166,7 +166,10 @@ latter are unique to Emacs Lisp. @node Integer Type @subsection Integer Type - The range of values for an integer depends on the machine. The + Under the hood, there are two kinds of integers---small integers, +called @dfn{fixnums}, and large integers, called @dfn{bignums}. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -182,8 +185,15 @@ to @math{2^{29}-1}) @end tex but many machines provide a wider range. -Emacs Lisp arithmetic functions do not check for integer overflow. Thus -@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. + + Bignums can have arbitrary precision. Operations that overflow a +fixnum will return a bignum instead. + + Fixnums can be compared with @code{eq}, but bignums require +@code{eql} or @code{=}. To test whether an integer is a fixnum or a +bignum, you can compare it to @code{most-negative-fixnum} and +@code{most-positive-fixnum}, or you can use the convenience predicates +@code{fixnump} and @code{bignump} on any object. The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The @@ -200,11 +210,6 @@ leading @samp{+} or a final @samp{.}. @end example @noindent -As a special exception, if a sequence of digits specifies an integer -too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating-Point Type}). -For instance, if Emacs integers are 30 bits, @code{536870912} is read -as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information. @@ -1895,6 +1900,9 @@ with references to further information. @item arrayp @xref{Array Functions, arrayp}. +@item bignump +@xref{Predicates on Numbers, floatp}. + @item bool-vector-p @xref{Bool-Vectors, bool-vector-p}. @@ -1928,6 +1936,9 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. +@item fixnump +@xref{Predicates on Numbers, floatp}. + @item floatp @xref{Predicates on Numbers, floatp}. @@ -2083,6 +2094,10 @@ 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. +For other types of objects whose contents cannot be changed (e.g., +floats), two arguments with the same contents might or might not be +the same object, and @code{eq} returns @code{t} or @code{nil} +depending on whether the Lisp interpreter created one object or two. @example @group @@ -2096,6 +2111,12 @@ be reflected by the same change in the contents of the other. @end group @group +(eq 3.0 3.0) + @result{} t @r{or} nil +;; @r{The result is implementation-dependent.} +@end group + +@group (eq "asdf" "asdf") @result{} nil @end group diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 65c57064a3d..6fae93717a2 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -95,6 +95,22 @@ if requested by environment variables such as @env{LANG}. @item It does some basic parsing of the command-line arguments. +@item +It loads your early init file (@pxref{Early Init File,,, emacs, The +GNU Emacs Manual}). This is not done if the options @samp{-q}, +@samp{-Q}, or @samp{--batch} were specified. If the @samp{-u} option +was specified, Emacs looks for the init file in that user's home +directory instead. + +@item +It calls the function @code{package-activate-all} to activate any +optional Emacs Lisp package that has been installed. @xref{Packaging +Basics}. However, Emacs doesn't activate the packages when +@code{package-enable-at-startup} is @code{nil} or when it's started +with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To +activate the packages in the latter case, @code{package-activate-all} +should be called explicitly (e.g., via the @samp{--funcall} option). + @vindex initial-window-system@r{, and startup} @findex window-system-initialization @item @@ -159,15 +175,6 @@ It loads your abbrevs from the file specified by (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the option @samp{--batch} was specified. -@item -It calls the function @code{package-initialize} to activate any -optional Emacs Lisp package that has been installed. @xref{Packaging -Basics}. However, Emacs doesn't initialize packages when -@code{package-enable-at-startup} is @code{nil} or when it's started -with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To -initialize packages in the latter case, @code{package-initialize} -should be called explicitly (e.g., via the @samp{--funcall} option). - @vindex after-init-time @item It sets the variable @code{after-init-time} to the value of @@ -366,6 +373,7 @@ Equivalent to @samp{-q --no-site-file --no-splash}. @cindex init file @cindex @file{.emacs} @cindex @file{init.el} +@cindex @file{early-init.el} When you start Emacs, it normally attempts to load your @dfn{init file}. This is either a file named @file{.emacs} or @file{.emacs.el} @@ -389,6 +397,19 @@ file; this way, even if you have su'd, Emacs still loads your own init file. If those environment variables are absent, though, Emacs uses your user-id to find your home directory. +@cindex early init file + Emacs also attempts to load a second init file, called the +@dfn{early init file}, if it exists. This is a file named +@file{early-init.el} in your @file{~/.emacs.d} directory. The +difference between the early init file and the regular init file is +that the early init file is loaded much earlier during the startup +process, so you can use it to customize some things that are +initialized before loading the regular init file. For example, you +can customize the process of initializing the package system, by +setting variables such as @var{package-load-list} or +@var{package-enable-at-startup}. @xref{Package Installation,,, +emacs,The GNU Emacs Manual}. + @cindex default init file An Emacs installation may have a @dfn{default init file}, which is a Lisp library named @file{default.el}. Emacs finds this file through @@ -1181,24 +1202,19 @@ Titles}). @cindex UID @defun user-real-uid This function returns the real @acronym{UID} of the user. -The value may be floating point, in the (unlikely) event that -the UID is too large to fit in a Lisp integer. @end defun @defun user-uid This function returns the effective @acronym{UID} of the user. -The value may be floating point. @end defun @cindex GID @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun group-real-gid This function returns the real @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun system-users @@ -1214,6 +1230,11 @@ groups on the system. If Emacs cannot retrieve this information, the return value is @code{nil}. @end defun +@defun group-name gid +This function returns the group name that corresponds to the numeric +group ID @var{gid}, or @code{nil} if there is no such group. +@end defun + @node Time of Day @section Time of Day @@ -1222,11 +1243,44 @@ return value is @code{nil}. This section explains how to determine the current time and time zone. +@cindex Lisp timestamp +@cindex timestamp, Lisp + Many functions like @code{current-time} and @code{file-attributes} +return @dfn{Lisp timestamp} values that count seconds, and that can +represent absolute time by counting seconds since the @dfn{epoch} of +1970-01-01 00:00:00 UTC. + + Although traditionally Lisp timestamps were integer pairs, their +form has evolved and programs ordinarily should not depend on the +current default form. If your program needs a particular timestamp +form, you can use the @code{encode-time} function to convert it to the +needed form. @xref{Time Conversion}. + @cindex epoch - Most of these functions represent time as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -This represents the number of seconds from the @dfn{epoch} (January -1, 1970 at 00:00 UTC), using the formula: + There are currently three forms of Lisp timestamps, each of +which represents a number of seconds: + +@itemize @bullet +@item +An integer. Although this is the simplest form, it cannot represent +subsecond timestamps. + +@item +A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is +positive. This represents @var{ticks}/@var{hz} seconds, which is the +same time as plain @var{ticks} if @var{hz} is 1. A common value for +@var{hz} is 1000000000, for a nanosecond-resolution +clock.@footnote{Currently @var{hz} should be at least 65536 to avoid +compatibility warnings when the timestamp is passed to standard +functions, as previous versions of Emacs would interpret such a +timestamps differently due to backward-compatibility concerns. These +warnings are intended to be removed in a future Emacs version.} + +@item +A list of four integers @code{(@var{high} @var{low} @var{micro} +@var{pico})}, where 0 @leq{} @var{low} < 65536, 0 @leq{} @var{micro} < +1000000, and 0 @leq{} @var{pico} < 1000000. +This represents the number of seconds using the formula: @ifnottex @var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + @var{pico} * 10**@minus{}12. @@ -1234,21 +1288,23 @@ This represents the number of seconds from the @dfn{epoch} (January @tex $high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -The return value of @code{current-time} represents time using this -form, as do the timestamps in the return values of other functions -such as @code{file-attributes} (@pxref{Definition of -file-attributes}). In some cases, functions may return two- or +In some cases, functions may default to returning two- or three-element lists, with omitted @var{microsec} and @var{picosec} components defaulting to zero. +On all current machines @var{picosec} is a multiple of 1000, but this +may change as higher-resolution clocks become available. +@end itemize @cindex time value Function arguments, e.g., the @var{time} argument to @code{current-time-string}, accept a more-general @dfn{time value} -format, which can be a list of integers as above, or a single number -for seconds since the epoch, or @code{nil} for the current time. You -can convert a time value into a human-readable string using -@code{current-time-string} and @code{format-time-string}, into a list -of integers using @code{seconds-to-time}, and into other forms using +format, which can be a Lisp timestamp, @code{nil} for the current +time, a single floating-point number for seconds, or a list +@code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} +@var{low})} that is a truncated list timestamp with missing elements +taken to be zero. You can convert a time value into +a human-readable string using @code{format-time-string}, into a Lisp +timestamp using @code{encode-time}, and into other forms using @code{decode-time} and @code{float-time}. These functions are described in the following sections. @@ -1257,9 +1313,10 @@ This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is -always the same, so you can reliably -use @code{substring} to extract them. You should count -characters from the beginning of the string rather than from the end, +always the same, although (unless you require English weekday or +month abbreviations regardless of locale) it is typically more +convenient to use @code{format-time-string} than to extract +fields from the output of @code{current-time-string}, as the year might not have exactly four digits, and additional information may some day be added at the end. @@ -1276,12 +1333,7 @@ defaults to the current time zone rule. @xref{Time Zone Rules}. @end defun @defun current-time -This function returns the current time, represented as a list of four -integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -These integers have trailing zeros on systems that return time with -lower resolutions. On all current machines @var{picosec} is a -multiple of 1000, but this may change as higher-resolution clocks -become available. +This function returns the current time as a Lisp timestamp. @end defun @defun float-time &optional time @@ -1295,13 +1347,6 @@ exact. Do not use this function if precise time stamps are required. @code{time-to-seconds} is an alias for this function. @end defun -@defun seconds-to-time time -This function converts a time value to list-of-integer form. -For example, if @var{time} is a number, @code{(time-to-seconds -(seconds-to-time @var{time}))} equals the number unless overflow -or rounding errors occur. -@end defun - @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1412,7 +1457,8 @@ The year, an integer typically greater than 1900. The day of week, as an integer between 0 and 6, where 0 stands for Sunday. @item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. +@code{t} if daylight saving time is effect, @code{nil} if it is not +in effect, and @minus{}1 if this information is not available. @item utcoff An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich. @@ -1422,32 +1468,63 @@ seconds east of Greenwich. @var{dow} and @var{utcoff}. @end defun -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a list-of-integer time value. For the -meanings of the arguments, see the table above under -@code{decode-time}. +@defun encode-time &optional time form &rest obsolescent-arguments +This function converts @var{time} to a Lisp timestamp. +It can act as the inverse of @code{decode-time}. + +The first argument can be a time value such as a number of seconds, a +pair @code{(@var{ticks} . @var{hz})}, a list @code{(@var{high} +@var{low} @var{micro} @var{pico})}, or @code{nil} (the default) for +the current time (@pxref{Time of Day}). It can also be a list +@code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} +@var{year} @var{ignored} @var{dst} @var{zone})} that specifies a +decoded time in the style of @code{decode-time}, so that +@code{(encode-time (decode-time ...))} works. For the meanings of +these list members, see the table under @code{decode-time}. + +The optional @var{form} argument specifies the desired timestamp form +to be returned. If @var{form} is the symbol @code{integer}, this +function returns an integer count of seconds. If @var{form} is a +positive integer, it specifies a clock frequency and this function +returns an integer-pair timestamp @code{(@var{ticks} +. @var{form})}.@footnote{Currently a positive integer @var{form} +should be at least 65536 if the returned value is intended to be given +to standard functions expecting Lisp timestamps.} If @var{form} is +@code{t}, this function treats it as a positive integer suitable for +representing the timestamp; for example, it is treated as 1000000000 +if the platform timestamp has nanosecond resolution. If @var{form} is +@code{list}, this function returns an integer list @code{(@var{high} +@var{low} @var{micro} @var{pico})}. Although an omitted or @code{nil} +@var{form} currently acts like @code{list}, this is planned to change +in a future Emacs version, so callers requiring list timestamps should +pass @code{list} explicitly. + +As an obsolescent calling convention, this function can be given six +or more arguments. The first six arguments @var{second}, +@var{minute}, @var{hour}, @var{day}, @var{month}, and @var{year} +specify most of the components of a decoded time. If there are more +than six arguments the @emph{last} argument is used as @var{zone} and +any other extra arguments are ignored, so that @code{(apply +#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults +to the current time zone rule (@pxref{Time Zone Rules}). The decoded +time's @var{dst} component is treated as if it was @minus{}1, and +@var{form} takes its default value. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. -The optional argument @var{zone} defaults to the current time zone rule. -@xref{Time Zone Rules}. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: +The @code{encode-time} function acts as a rough inverse to +@code{decode-time}. For example, you can pass the output of +the latter to the former as follows: @example -(apply 'encode-time (decode-time @dots{})) +(encode-time (decode-time @dots{})) @end example You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. +@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; +for example, day 0 means the day preceding the given month. The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results. @@ -1462,12 +1539,12 @@ on others, years as early as 1901 do work. @cindex formatting time values These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and lists of two to four -integers (@pxref{Time of Day}). +Time values include @code{nil}, numbers, and Lisp timestamps +(@pxref{Time of Day}). @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding time value. +corresponding Lisp timestamp. @end defun @defun format-time-string format-string &optional time zone @@ -1665,10 +1742,6 @@ You can also specify the field width by following the @samp{%} with a number; shorter numbers will be padded with blanks. An optional period before the width requests zero-padding instead. For example, @code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). @end defun @node Processor Run Time @@ -1693,10 +1766,8 @@ When called interactively, it prints the uptime in the echo area. @end deffn @defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, using the same format as @code{current-time} -(@pxref{Time of Day}). +This function returns the processor run time used by Emacs, as a Lisp +timestamp (@pxref{Time of Day}). Note that the time returned by this function excludes the time Emacs was not using the processor, and if the Emacs process has several @@ -1721,26 +1792,36 @@ interactively, it prints the duration in the echo area. @cindex calendrical computations These functions perform calendrical computations using time values -(@pxref{Time of Day}). A value of @code{nil} for any of their +(@pxref{Time of Day}). As with any time value, a value of +@code{nil} for any of their time-value arguments stands for the current system time, and a single -integer number stands for the number of seconds since the epoch. +number stands for the number of seconds since the epoch. @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @var{t2}. +The result is @code{nil} if either argument is a NaN. +@end defun + +@defun time-equal-p t1 t2 +This returns @code{t} if @var{t1} and @var{t2} are equal time values. +The result is @code{nil} if either argument is a NaN. @end defun @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, as a time value. If you need the difference in units +two time values, as a time value. However, the result is a float +if either argument is a float infinity or NaN@. +If you need the difference in units of elapsed seconds, use @code{float-time} (@pxref{Time of Day, float-time}) to convert the result into seconds. @end defun @defun time-add t1 t2 This returns the sum of two time values, as a time value. +However, the result is a float if either argument is a float infinity or NaN@. One argument should represent a time difference rather than a point in time, -either as a list or as a single number of elapsed seconds. +as a time value that is often just a single number of elapsed seconds. Here is how to add a number of seconds to a time value: @example @@ -1983,8 +2064,7 @@ the idleness time, as described below. @defun current-idle-time If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of four integers: @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}, using the same format as +been idle, using the same format as @code{current-time} (@pxref{Time of Day}). When Emacs is not idle, @code{current-idle-time} returns @code{nil}. diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 39bdc01a75c..7244efbd8f7 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -22,6 +22,7 @@ user-level features of the packaging system. * Simple Packages:: How to package a single .el file. * Multi-file Packages:: How to package multiple files. * Package Archives:: Maintaining package archives. +* Archive Web Server:: Interfacing to an archive web server. @end menu @node Packaging Basics @@ -105,24 +106,36 @@ adds the package's content directory to @code{load-path}, and evaluates the autoload definitions in @file{@var{name}-autoloads.el}. Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. +@code{package-activate-all} to make installed packages available to the +current session. This is done after loading the early init file, but +before loading the regular init file (@pxref{Startup Summary}). +Packages are not automatically made available if the user option +@code{package-enable-at-startup} is set to @code{nil} in the early +init file. + +@defun package-activate-all +This function makes the packages available to the current session. +The user option @code{package-load-list} specifies which packages to +make available; by default, all installed packages are made available. +If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +evaluating package autoloads more than once. @xref{Package +Installation,,, emacs, The GNU Emacs Manual}. + +In most cases, you should not need to call @code{package-activate-all}, +as this is done automatically during startup. Simply make sure to put +any code that should run before @code{package-activate-all} in the early +init file, and any code that should run after it in the primary init +file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). +@end defun @deffn Command package-initialize &optional no-activate This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. If called during startup, this function also sets -@code{package-enable-at-startup} to @code{nil}, to avoid accidentally -loading the packages twice. @xref{Package Installation,,, emacs, The -GNU Emacs Manual}. +installed, and then calls @code{package-activate-all}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually -loading them; it is for internal use only. +making them available. @end deffn @node Simple Packages @@ -237,7 +250,8 @@ dependency's version (a string). @end defun If the content directory contains a file named @file{README}, this -file is used as the long description. +file is used as the long description (overriding any @samp{;;; +Commentary:} section). If the content directory contains a file named @file{dir}, this is assumed to be an Info directory file made with @command{install-info}. @@ -299,8 +313,8 @@ access. Such local archives are mainly useful for testing. A package archive is simply a directory in which the package files, and associated files, are stored. If you want the archive to be -reachable via HTTP, this directory must be accessible to a web server. -How to accomplish this is beyond the scope of this manual. +reachable via HTTP, this directory must be accessible to a web server; +@xref{Archive Web Server}. A convenient way to set up and update a package archive is via the @code{package-x} library. This is included with Emacs, but not loaded @@ -381,3 +395,28 @@ manual. For more information on cryptographic keys and signing, @pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + +@node Archive Web Server +@section Interfacing to an archive web server +@cindex archive web server + +A web server providing access to a package archive must support the +following queries: + +@table @asis +@item archive-contents +Return a lisp form describing the archive contents. The form is a list +of 'package-desc' structures (see @file{package.el}), except the first +element of the list is the archive version. + +@item <package name>-readme.txt +Return the long description of the package. + +@item <file name>.sig +Return the signature for the file. + +@item <file name> +Return the file. This will be the tarball for a multi-file +package, or the single file for a simple package. + +@end table diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d2ab518e5eb..72b164c5d45 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -177,6 +177,14 @@ before starting Emacs. Trying to modify @code{exec-path} independently of @env{PATH} can lead to confusing results. @end defopt +@defun exec-path +This function is an extension of the variable @code{exec-path}. If +@code{default-directory} indicates a remote directory, this function +returns a list of directories used for searching programs on the +respective remote host. In case of a local @code{default-directory}, +the function returns just the value of the variable @code{exec-path}. +@end defun + @node Shell Arguments @section Shell Arguments @cindex arguments for shell commands @@ -415,27 +423,27 @@ be found in the definition of the @code{insert-directory} function: @defun process-file program &optional infile buffer display &rest args This function processes files synchronously in a separate process. It -is similar to @code{call-process}, but may invoke a file handler based -on the value of the variable @code{default-directory}, which specifies -the current working directory of the subprocess. +is similar to @code{call-process}, but may invoke a file name handler +based on the value of the variable @code{default-directory}, which +specifies the current working directory of the subprocess. The arguments are handled in almost the same way as for @code{call-process}, with the following differences: -Some file handlers may not support all combinations and forms of the +Some file name handlers may not support all combinations and forms of the arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, +some file name handlers might behave as if @var{display} were @code{nil}, regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error +file name handlers might not support separating standard output and error output by way of the @var{buffer} argument. -If a file handler is invoked, it determines the program to run based +If a file name handler is invoked, it determines the program to run based on the first argument @var{program}. For instance, suppose that a handler for remote files is invoked. Then the path that is used for searching for the program might be different from @code{exec-path}. -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the +The second argument @var{infile} may invoke a file name handler. The file +name handler could be different from the handler chosen for the @code{process-file} function itself. (For example, @code{default-directory} could be on one remote host, and @var{infile} on a different remote host. Or @code{default-directory} @@ -462,7 +470,7 @@ remote files. By default, this variable is always set to @code{t}, meaning that a call of @code{process-file} could potentially change any file on a -remote host. When set to @code{nil}, a file handler could optimize +remote host. When set to @code{nil}, a file name handler could optimize its behavior with respect to remote file attribute caching. You should only ever change this variable with a let-binding; never @@ -686,7 +694,15 @@ a default sentinel will be used, which can be overridden later. @item :stderr @var{stderr} Associate @var{stderr} with the standard error of the process. A non-@code{nil} value should be either a buffer or a pipe process -created with @code{make-pipe-process}, described below. +created with @code{make-pipe-process}, described below. If +@var{stderr} is @code{nil}, standard error is mixed with standard +output, and both are sent to @var{buffer} or @var{filter}. + +@item :file-handler @var{file-handler} +If @var{file-handler} is non-@code{nil}, then look for a file name +handler for the current buffer's @code{default-directory}, and invoke +that file name handler to make the process. If there is no such +handler, proceed as if @var{file-handler} were @code{nil}. @end table The original argument list, modified with the actual connection @@ -694,9 +710,18 @@ information, is available via the @code{process-contact} function. The current working directory of the subprocess is set to the current buffer's value of @code{default-directory} if that is local (as -determined by `unhandled-file-name-directory'), or "~" otherwise. If -you want to run a process in a remote directory use -@code{start-file-process}. +determined by @code{unhandled-file-name-directory}), or @file{~} +otherwise. If you want to run a process in a remote directory, pass +@code{:file-handler t} to @code{make-process}. In that case, the +current working directory is the local name component of +@code{default-directory} (as determined by @code{file-local-name}). + +Depending on the implementation of the file name handler, it might not +be possible to apply @var{filter} or @var{sentinel} to the resulting +process object. @xref{Filter Functions}, and @ref{Sentinels}. + +Some file name handlers may not support @code{make-process}. In such +cases, this function does nothing and returns @code{nil}. @end defun @defun make-pipe-process &rest args @@ -812,7 +837,7 @@ subprocess running @var{program} in it, and returns its process object. The difference from @code{start-process} is that this function may -invoke a file handler based on the value of @code{default-directory}. +invoke a file name handler based on the value of @code{default-directory}. This handler ought to run @var{program}, perhaps on the local host, perhaps on a remote host that corresponds to @code{default-directory}. In the latter case, the local part of @code{default-directory} becomes @@ -826,13 +851,13 @@ names relative to @code{default-directory}, or to names that identify the files locally on the remote host, by running them through @code{file-local-name}. -Depending on the implementation of the file handler, it might not be +Depending on the implementation of the file name handler, it might not be possible to apply @code{process-filter} or @code{process-sentinel} to the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}. @c FIXME Can we find a better example (i.e., a more modern function @c that is actually documented). -Some file handlers may not support @code{start-file-process} (for +Some file name handlers may not support @code{start-file-process} (for example the function @code{ange-ftp-hook-function}). In such cases, this function does nothing and returns @code{nil}. @end defun @@ -2079,8 +2104,6 @@ attribute and @var{value} is the value of that attribute. The various attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating point, -depending on the magnitude of the value. @table @code @item euid @@ -2164,19 +2187,17 @@ faults for all the child processes of the given process. @item utime Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). +application's code. The corresponding @var{value} is a Lisp +timestamp (@pxref{Time of Day}). @item stime Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. +processing system calls. The corresponding @var{value} is a Lisp +timestamp. @item time The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. +@var{value} is a Lisp timestamp. @item cutime @itemx cstime @@ -2195,13 +2216,10 @@ nice values get scheduled more favorably.) The number of threads in the process. @item start -The time when the process was started, in the same -@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by -@code{file-attributes} and @code{current-time}. +The time when the process was started, as a Lisp timestamp. @item etime -The time elapsed since the process started, in the format @code{(@var{high} -@var{low} @var{microsec} @var{picosec})}. +The time elapsed since the process started, as a Lisp timestamp. @item vsize The virtual memory size of the process, measured in kilobytes. @@ -2729,8 +2747,7 @@ Initialize the process filter to @var{filter}. @item :filter-multibyte @var{multibyte} If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. +filter are multibyte, otherwise they are unibyte. The default is @code{t}. @item :sentinel @var{sentinel} Initialize the process sentinel to @var{sentinel}. @@ -3133,7 +3150,6 @@ direction is also known as @dfn{serializing} or @dfn{packing}. @menu * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! @end menu @node Bindat Spec @@ -3376,132 +3392,3 @@ dotted notation. @result{} "127.0.0.1" @end example @end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 25.2, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here are two complete examples that use bindat.el. -The first shows simple byte packing: - -@lisp -(require 'bindat) - -(defun rfc868-payload () - (bindat-pack - '((now-hi u16) - (now-lo u16)) - ;; Emacs uses Unix epoch, while RFC868 epoch - ;; is 1900-01-01 00:00:00, which is 2208988800 - ;; (or #x83aa7e80) seconds more. - (let ((now (time-add nil '(#x83aa #x7e80)))) - `((now-hi . ,(car now)) - (now-lo . ,(cadr now)))))) - -(let ((s (rfc868-payload))) - (list (multibyte-string-p s) - (mapconcat (lambda (byte) - (format "%02x" byte)) - s " ") - (current-time-string))) - @result{} (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017") -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 7546863dde2..05fc3282053 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -642,10 +642,10 @@ is omitted, the minimum is 0; if @var{n} is omitted, there is no maximum. For both forms, @var{m} and @var{n}, if specified, may be no larger than @ifnottex -2**15 @minus{} 1 +2**16 @minus{} 1 @end ifnottex @tex -@math{2^{15}-1} +@math{2^{16}-1} @end tex . diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 5cf2e89644d..0c3c4e3b282 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1308,9 +1308,9 @@ not evaluate or even examine the elements of the vector. @example @group (setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eval avector) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eq avector (eval avector)) @result{} t @end group @@ -1400,9 +1400,9 @@ list with the same elements: @example @group (setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (append avector nil) - @result{} (1 two (quote (three)) "four" [five]) + @result{} (1 two '(three) "four" [five]) @end group @end example @@ -1777,6 +1777,11 @@ If the ring is full, this function removes the newest element to make room for the inserted element. @end defun +@defun ring-resize ring size +Set the size of @var{ring} to @var{size}. If the new size is smaller, +then the oldest items in the ring are discarded. +@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: diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 5aa49c2e954..600639f244f 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -809,6 +809,21 @@ when the output stream is a unibyte buffer or a marker pointing into one. @end defvar +@defvar print-charset-text-property +This variable controls printing of `charset' text property on printing +a string. The value should be @code{nil}, @code{t}, or +@code{default}. + +If the value is @code{nil}, @code{charset} text properties are never +printed. If @code{t}, they are always printed. + +If the value is @code{default}, only print @code{charset} text +properties if there is an ``unexpected'' @code{charset} property. For +ascii characters, all charsets are considered ``expected''. +Otherwise, the expected @code{charset} property of a character is +given by @code{char-charset}. +@end defvar + @defvar print-length @cindex printing limits The value of this variable is the maximum number of elements to print in diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 8420527f858..521f163663d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -121,7 +121,7 @@ character (i.e., an integer), @code{nil} otherwise. The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. -@defun make-string count character +@defun make-string count character &optional multibyte This function returns a string made up of @var{count} repetitions of @var{character}. If @var{count} is negative, an error is signaled. @@ -132,6 +132,13 @@ This function returns a string made up of @var{count} repetitions of @result{} "" @end example + Normally, if @var{character} is an @acronym{ASCII} character, the +result is a unibyte string. But if the optional argument +@var{multibyte} is non-@code{nil}, the function will produce a +multibyte string instead. This is useful when you later need to +concatenate the result with non-@acronym{ASCII} strings or replace +some of its characters with non-@acronym{ASCII} characters. + Other functions to compare with this one include @code{make-vector} (@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). @end defun @@ -666,6 +673,28 @@ of the two strings. The sign is negative if @var{string1} (or its specified portion) is less. @end defun +@cindex Levenshtein distance +@cindex distance between strings +@cindex edit distance between strings +@defun string-distance string1 string2 &optional bytecompare +This function returns the @dfn{Levenshtein distance} between the +source string @var{string1} and the target string @var{string2}. The +Levenshtein distance is the number of single-character +changes---deletions, insertions, or replacements---required to +transform the source string into the target string; it is one possible +definition of the @dfn{edit distance} between strings. + +Letter-case of the strings is significant for the computed distance, +but their text properties are ignored. If the optional argument +@var{bytecompare} is non-@code{nil}, the function calculates the +distance in terms of bytes instead of characters. The byte-wise +comparison uses the internal Emacs representation of characters, so it +will produce inaccurate results for multibyte strings that include raw +bytes (@pxref{Text Representations}); make the strings unibyte by +encoding them (@pxref{Explicit Encoding}) if you need accurate results +with raw bytes. +@end defun + @defun assoc-string key alist &optional case-fold This function works like @code{assoc}, except that @var{key} must be a string or symbol, and comparison is done using @code{compare-strings}. @@ -893,18 +922,25 @@ Functions}). Thus, strings are enclosed in @samp{"} characters, and @item %o @cindex integer to octal Replace the specification with the base-eight representation of an -unsigned integer. +integer. Negative integers are formatted in a platform-dependent +way. The object can also be a nonnegative floating-point +number that is formatted as an integer, dropping any fraction, if the +integer does not exceed machine limits. @item %d Replace the specification with the base-ten representation of a signed -integer. +integer. The object can also be a floating-point number that is +formatted as an integer, dropping any fraction. @item %x @itemx %X @cindex integer to hexadecimal Replace the specification with the base-sixteen representation of an -unsigned integer. @samp{%x} uses lower case and @samp{%X} uses upper -case. +integer. Negative integers are formatted in a platform-dependent +way. @samp{%x} uses lower case and @samp{%X} uses upper +case. The object can also be a nonnegative floating-point number that +is formatted as an integer, dropping any fraction, if the integer does +not exceed machine limits. @item %c Replace the specification with the character which is the value given. @@ -981,17 +1017,17 @@ numbered or unnumbered format specifications but not both, except that After the @samp{%} and any field number, you can put certain @dfn{flag characters}. - The flag @samp{+} inserts a plus sign before a positive number, so + The flag @samp{+} inserts a plus sign before a nonnegative number, so that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are +before a nonnegative number. (Otherwise, nonnegative numbers start with the +first digit.) These flags are useful for ensuring that nonnegative +and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. The flag @samp{#} specifies an alternate form which depends on the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result +with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes nonzero results with @samp{0x} or @samp{0X}. For @samp{%e} and @samp{%f}, the @samp{#} flag means include a decimal point even if the precision is zero. For @samp{%g}, it always includes a decimal point, and also @@ -1074,6 +1110,17 @@ shows only the first three characters of the representation for precision is what the local library functions of the @code{printf} family produce. +@cindex formatting numbers for rereading later + If you plan to use @code{read} later on the formatted string to +retrieve a copy of the formatted value, use a specification that lets +@code{read} reconstruct the value. To format numbers in this +reversible way you can use @samp{%s} and @samp{%S}, to format just +integers you can also use @samp{%d}, and to format just nonnegative +integers you can also use @samp{#x%x} and @samp{#o%o}. Other formats +may be problematic; for example, @samp{%d} and @samp{%g} can mishandle +NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o} +can mishandle negative integers. @xref{Input Functions}. + @node Case Conversion @section Case Conversion in Lisp @cindex upper case diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 90d380f5b84..a960eeac7e8 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1014,13 +1014,13 @@ corresponds to each syntax flag. @item @i{Prefix} @tab @i{Flag} @tab @i{Prefix} @tab @i{Flag} @item -@samp{1} @tab @code{(lsh 1 16)} @tab @samp{p} @tab @code{(lsh 1 20)} +@samp{1} @tab @code{(ash 1 16)} @tab @samp{p} @tab @code{(ash 1 20)} @item -@samp{2} @tab @code{(lsh 1 17)} @tab @samp{b} @tab @code{(lsh 1 21)} +@samp{2} @tab @code{(ash 1 17)} @tab @samp{b} @tab @code{(ash 1 21)} @item -@samp{3} @tab @code{(lsh 1 18)} @tab @samp{n} @tab @code{(lsh 1 22)} +@samp{3} @tab @code{(ash 1 18)} @tab @samp{n} @tab @code{(ash 1 22)} @item -@samp{4} @tab @code{(lsh 1 19)} @tab @samp{c} @tab @code{(lsh 1 23)} +@samp{4} @tab @code{(ash 1 19)} @tab @samp{c} @tab @code{(ash 1 23)} @end multitable @defun string-to-syntax desc diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index fb5f56e9ddd..6dfd211d1a0 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -61,6 +61,8 @@ the character after point. * Checksum/Hash:: Computing cryptographic hashes. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. * Parsing HTML/XML:: Parsing HTML and XML. +* Parsing JSON:: Parsing and generating JSON values. +* JSONRPC:: JSON Remote Procedure Call protocol * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -498,14 +500,14 @@ after point. It leaves the mark after the inserted text. The value is @code{nil}. @end deffn -@deffn Command self-insert-command count +@deffn Command self-insert-command count &optional char @cindex character insertion @cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. +This command inserts the character @var{char} (the last character typed); +it does so @var{count} times, before point, and returns @code{nil}. +Most printing characters are bound to this command. In routine use, +@code{self-insert-command} is the most frequently called function in Emacs, +but programs rarely use it except to install it on a keymap. In an interactive call, @var{count} is the numeric prefix argument. @@ -1325,9 +1327,8 @@ elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became -modified. A @var{time-flag} of the form -@code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})} represents the visited file's modification time as of +modified. A @var{time-flag} that is a non-integer Lisp timestamp +represents the visited file's modification time as of when it was previously visited or saved, using the same format as @code{current-time}; see @ref{Time of Day}. A @var{time-flag} of 0 means the buffer does not correspond to any file; @@ -3184,6 +3185,95 @@ buffer to scan. Positions are relative to @var{object}. The default for @var{object} is the current buffer. @end defun +@defun text-property-search-forward prop &optional value predicate not-current +Search for the next region that has text property @var{prop} set to +@var{value} according to @var{predicate}. + +This function is modelled after @code{search-forward} and friends in +that it moves point, but it returns a structure that describes the +match instead of returning it in @code{match-beginning} and friends. + +If the text property can't be found, the function returns @code{nil}. +If it's found, point is placed at the end of the region that has this +text property match, and a @code{prop-match} structure is returned. + +@var{predicate} can either be @code{t} (which is a synonym for +@code{equal}), @code{nil} (which means ``not equal''), or a predicate +that will be called with two parameters: The first is @var{value}, and +the second is the value of the text property we're inspecting. + +If @var{not-current}, if point is in a region where we have a match, +then skip past that and find the next instance instead. + +The @code{prop-match} structure has the following accessors: +@code{prop-match-beginning} (the start of the match), +@code{prop-match-end} (the end of the match), and +@code{prop-match-value} (the value of @var{property} at the start of +the match). + +In the examples below, imagine that you're in a buffer that looks like +this: + +@example +This is a bold and here's bolditalic and this is the end. +@end example + +That is, the ``bold'' words are the @code{bold} face, and the +``italic'' word is in the @code{italic} face. + +With point at the start: + +@lisp +(while (setq match (text-property-search-forward 'face 'bold t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the words that use the @code{bold} face. + +@lisp +(while (setq match (text-property-search-forward 'face nil t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the bits that have no face properties, which +will result in the list @samp{("This is a " "and here's " "and this is +the end")} (only reversed, since we used @code{push}). + +@lisp +(while (setq match (text-property-search-forward 'face nil nil)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the regions where @code{face} is set to +something, but this is split up into where the properties change, so +the result here will be @samp{("bold" "bold" "italic")}. + +For a more realistic example where you might use this, consider that +you have a buffer where certain sections represent URLs, and these are +tagged with @code{shr-url}. + +@lisp +(while (setq match (text-property-search-forward 'shr-url nil nil)) + (push (prop-match-value match) urls)) +@end lisp + +This will give you a list of all those URLs. + +@end defun + +@defun text-property-search-backward prop &optional value predicate not-current +This is just like @code{text-property-search-backward}, but searches +backward instead. Point is placed at the beginning of the matched +region instead of the end, though. +@end defun + + @node Special Properties @subsection Properties with Special Meanings @@ -3235,6 +3325,17 @@ foreground or background color, similar to @code{(:foreground @var{color-name})} or @code{(:background @var{color-name})}. This form is supported for backward compatibility only, and should be avoided. + +@item +A cons cell of the form @w{@code{(:filtered @var{filter} +@var{face-spec})}}, that specifies the face given by @var{face-spec}, +but only if @var{filter} matches when the face is used for display. +The @var{face-spec} can use any of the forms mentioned above. The +@var{filter} should be of the form @w{@code{(:window @var{param} +@var{value})}}, which matches for windows whose parameter @var{param} +is @code{eq} to @var{value}. If the variable +@code{face-filters-always-match} is non-@code{nil}, all face filters +are deemed to have matched. @end itemize Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by @@ -3617,6 +3718,12 @@ string to display, which is passed through The GNU Emacs Manual}) provides an example. @end defvar +@defvar face-filters-always-match +If this variable is non-@code{nil}, face filters that specify +attributes applied only when certain conditions are met will be deemed +to match always. +@end defvar + @node Format Properties @subsection Formatted Text Properties @@ -4529,9 +4636,9 @@ It should be somewhat more efficient on larger buffers than @cindex symmetric cipher @cindex cipher, symmetric -If compiled with GnuTLS, Emacs offers built-in cryptographic support. -Following the GnuTLS API terminology, the available tools are digests, -MACs, symmetric ciphers, and AEAD ciphers. + If compiled with GnuTLS, Emacs offers built-in cryptographic +support. Following the GnuTLS API terminology, the available tools +are digests, MACs, symmetric ciphers, and AEAD ciphers. The terms used herein, such as IV (Initialization Vector), require some familiarity with cryptography and will not be defined in detail. @@ -4549,7 +4656,7 @@ structure of the GnuTLS library. @cindex format of gnutls cryptography inputs @cindex gnutls cryptography inputs format -The inputs to GnuTLS cryptographic functions can be specified in + The inputs to GnuTLS cryptographic functions can be specified in several ways, both as primitive Emacs Lisp types or as lists. The list form is currently similar to how @code{md5} and @@ -4716,8 +4823,15 @@ IV used. @section Parsing HTML and XML @cindex parsing html -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. + Emacs can be compiled with built-in libxml2 support. + +@defun libxml-available-p +This function returns non-@code{nil} if built-in libxml2 support is +available in this Emacs session. +@end defun + +When libxml2 support is available, the following functions can be used +to parse HTML or XML text into Lisp object trees. @defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as @@ -4729,7 +4843,10 @@ The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. If the optional argument @var{discard-comments} is non-@code{nil}, -then the parse tree is created without any comments. +any top-level comment is discarded. (This argument is obsolete and +will be removed in future Emacs versions. To remove comments, use the +@code{xml-remove-comments} utility function on the data before you +call the parsing function.) In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second @@ -4784,9 +4901,9 @@ about syntax). @cindex DOM @cindex Document Object Model -The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the -other @acronym{XML} parsing functions) is a tree structure where each -node has a node name (called a @dfn{tag}), and optional key/value + The @acronym{DOM} returned by @code{libxml-parse-html-region} (and +the other @acronym{XML} parsing functions) is a tree structure where +each node has a node name (called a @dfn{tag}), and optional key/value @dfn{attribute} list, and then a list of @dfn{child nodes}. The child nodes are either strings or @acronym{DOM} objects. @@ -4904,6 +5021,319 @@ textual nodes that just contain white-space. @end table +@node Parsing JSON +@section Parsing and generating JSON values +@cindex JSON +@cindex JavaScript Object Notation + + When Emacs is compiled with @acronym{JSON} (@dfn{JavaScript Object +Notation}) support, it provides several functions to convert +between Lisp objects and JSON values. Any JSON value can be converted +to a Lisp object, but not vice versa. Specifically: + +@itemize +@item +JSON uses three keywords: @code{true}, @code{null}, @code{false}. +@code{true} is represented by the symbol @code{t}. By default, the +remaining two are represented, respectively, by the symbols +@code{:null} and @code{:false}. + +@item +JSON only has floating-point numbers. They can represent both Lisp +integers and Lisp floating-point numbers. + +@item +JSON strings are always Unicode strings encoded in UTF-8. Lisp +strings can contain non-Unicode characters. + +@item +JSON has only one sequence type, the array. JSON arrays are +represented using Lisp vectors. + +@item +JSON has only one map type, the object. JSON objects are represented +using Lisp hashtables, alists or plists. When an alist or plist +contains several elements with the same key, Emacs uses only the first +element for serialization, in accordance with the behavior of +@code{assq}. +@end itemize + +@noindent +Note that @code{nil}, being both a valid alist and a valid plist, +represents @code{@{@}}, the empty JSON object; not @code{null}, +@code{false}, or an empty array, all of which are different JSON +values. + + If some Lisp object can't be represented in JSON, the serialization +functions will signal an error of type @code{wrong-type-argument}. +The parsing functions can also signal the following errors: + +@table @code +@item json-end-of-file +Signaled when encountering a premature end of the input text. + +@item json-trailing-content +Signaled when encountering unexpected input after the first JSON +object parsed. + +@item json-parse-error +Signaled when encountering invalid JSON syntax. +@end table + + Only top-level values (arrays and objects) can be serialized to +JSON. The subobjects within these top-level values can be of any +type. Likewise, the parsing functions will only return vectors, +hashtables, alists, and plists. + +@defun json-serialize object &rest args +This function returns a new Lisp string which contains the JSON +representation of @var{object}. The argument @var{args} is a list of +keyword/argument pairs. The following keywords are accepted: + +@table @code +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-insert object &rest args +This function inserts the JSON representation of @var{object} into the +current buffer before point. The argument @var{args} are interpreted +as in @code{json-parse-string}. +@end defun + +@defun json-parse-string string &rest args +This function parses the JSON value in @var{string}, which must be a +Lisp string. The argument @var{args} is a list of keyword/argument +pairs. The following keywords are accepted: + +@table @code +@item :object-type +The value decides which Lisp object to use for representing the +key-value mappings of a JSON object. It can be either +@code{hash-table}, the default, to make hashtables with strings as +keys; @code{alist} to use alists with symbols as keys; or @code{plist} +to use plists with keyword symbols as keys. + +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-parse-buffer &rest args +This function reads the next JSON value from the current buffer, +starting at point. It moves point to the position immediately after +the value if a value could be read and converted to Lisp; otherwise it +doesn't move point. The arguments @var{args} are interpreted as in +@code{json-parse-string}. +@end defun + +@node JSONRPC +@section JSONRPC communication +@cindex JSON remote procedure call protocol + +The @code{jsonrpc} library implements the @acronym{JSONRPC} +specification, version 2.0, as it is described in +@uref{http://www.jsonrpc.org/}. As the name suggests, JSONRPC is a +generic @code{Remote Procedure Call} protocol designed around +@acronym{JSON} objects, which you can convert to and from Lisp objects +(@pxref{Parsing JSON}). + +@menu +* JSONRPC Overview:: +* Process-based JSONRPC connections:: +* JSONRPC JSON object format:: +* JSONRPC deferred requests:: +@end menu + +@node JSONRPC Overview +@subsection Overview + +Quoting from the @uref{http://www.jsonrpc.org/, spec}, JSONRPC "is +transport agnostic in that the concepts can be used within the same +process, over sockets, over http, or in many various message passing +environments." + +To model this agnosticism, the @code{jsonrpc} library uses objects of +a @code{jsonrpc-connection} class, which represent a connection the +remote JSON endpoint (for details on Emacs's object system, +@pxref{Top,EIEIO,,eieio,EIEIO}). In modern object-oriented parlance, +this class is ``abstract'', i.e. the actual class of a useful +connection object used is always a subclass of it. Nevertheless, we +can define two distinct API's around the @code{jsonrpc-connection} +class: + +@enumerate + +@item A user interface for building JSONRPC applications + +In this scenario, the JSONRPC application selects a concrete subclass +of @code{jsonrpc-connection}, and proceeds to create objects of that +subclass using @code{make-instance}. To initiate a contact to the +remote endpoint, the JSONRPC application passes this object to the +functions @code{jsonrpc-notify'}, @code{jsonrpc-request} and +@code{jsonrpc-async-request}. For handling remotely initiated +contacts, which generally come in asynchronously, the instantiation +should include @code{:request-dispatcher} and +@code{:notification-dispatcher} initargs, which are both functions of +3 arguments: the connection object; a symbol naming the JSONRPC method +invoked remotely; and a JSONRPC "params" object. + +The function passed as @code{:request-dispatcher} is responsible for +handling the remote endpoint's requests, which expect a reply from the +local endpoint (in this case, the program you're building). Inside +that function, you may either return locally (normally) or non-locally +(error). A local return value must be a Lisp object serializable as +JSON (@pxref{Parsing JSON}). This determines a success response, and +the object is forwarded to the server as the JSONRPC "result" object. +A non-local return, achieved by calling the function +@code{jsonrpc-error}, causes an error response to be sent to the +server. The details of the accompanying JSONRPC "error" are filled +out with whatever was passed to @code{jsonrpc-error}. A non-local +return triggered by an unexpected error of any other type also causes +an error response to be sent (unless you have set +@code{debug-on-error}, in which case this should land you in the +debugger, @pxref{Error Debugging}). + +@item A inheritance interface for building JSONRPC transport implementations + +In this scenario, @code{jsonrpc-connection} is subclassed to implement +a different underlying transport strategy (for details on how to +subclass, @pxref{Inheritance,Inheritance,,eieio}). Users of the +application-building interface can then instantiate objects of this +concrete class (using the @code{make-instance} function) and connect +to JSONRPC endpoints using that strategy. + +This API has mandatory and optional parts. + +To allow its users to initiate JSONRPC contacts (notifications or +requests) or reply to endpoint requests, the method +@code{jsonrpc-connection-send} must be implemented for the subclass. + +Likewise, for handling the three types of remote contacts (requests, +notifications and responses to local requests) the transport +implementation must arrange for the function +@code{jsonrpc-connection-receive} to be called after noticing a new +JSONRPC message on the wire (whatever that "wire" may be). + +Finally, and optionally, the @code{jsonrpc-connection} subclass should +implement @code{jsonrpc-shutdown} and @code{jsonrpc-running-p} if +these concepts apply to the transport. If they do, then any system +resources (e.g. processes, timers, etc..) used listen for messages on +the wire should be released in @code{jsonrpc-shutdown}, i.e. they +should only be needed while @code{jsonrpc-running-p} is non-nil. + +@end enumerate + +@node Process-based JSONRPC connections +@subsection Process-based JSONRPC connections + +For convenience, the @code{jsonrpc} library comes built-in with a +@code{jsonrpc-process-connection} transport implementation that can +talk to local subprocesses (using the standard input and standard +output); or TCP hosts (using sockets); or any other remote endpoint +that Emacs's process object can represent (@pxref{Processes}). + +Using this transport, the JSONRPC messages are encoded on the wire as +plain text and prefaced by some basic HTTP-style enveloping headers, +such as ``Content-Length''. + +For an example of an application using this transport scheme on top of +JSONRPC, see the +@uref{https://microsoft.github.io/language-server-protocol/specification, +Language Server Protocol}. + +Along with the mandatory @code{:request-dispatcher} and +@code{:notification-dispatcher} initargs, users of the +@code{jsonrpc-process-connection} class should pass the following +initargs as keyword-value pairs to @code{make-instance}: + +@table @code +@item :process +Value must be a live process object or a function of no arguments +producing one such object. If passed a process object, that is +expected to contain an pre-established connection; otherwise, the +function is called immediately after the object is made. + +@item :on-shutdown +Value must be a function of a single argument, the +@code{jsonrpc-process-connection} object. The function is called +after the underlying process object has been deleted (either +deliberately by @code{jsonrpc-shutdown} or unexpectedly, because of +some external cause). +@end table + +@node JSONRPC JSON object format +@subsection JSON object format + +JSON objects are exchanged as Lisp plists (@pxref{Parsing JSON}): +JSON-compatible plists are handed to the dispatcher functions and, +likewise, JSON-compatible plists should be given to +@code{jsonrpc-notify}, @code{jsonrpc-request} and +@code{jsonrpc-async-request}. + +To facilitate handling plists, this library make liberal use of +@code{cl-lib} library and suggests (but doesn't force) its clients to +do the same. A macro @code{jsonrpc-lambda} can be used to create a +lambda for destructuring a JSON-object like in this example: + +@example +(jsonrpc-async-request + myproc :frobnicate `(:foo "trix") + :success-fn (jsonrpc-lambda (&key bar baz &allow-other-keys) + (message "Server replied back with %s and %s!" + bar baz)) + :error-fn (jsonrpc-lambda (&key code message _data) + (message "Sadly, server reports %s: %s" + code message))) +@end example + +@node JSONRPC deferred requests +@subsection Deferred requests + +In many @acronym{RPC} situations, synchronization between the two +communicating endpoints is a matter of correctly designing the RPC +application: when synchronization is needed, requests (which are +blocking) should be used; when it isn't, notifications should suffice. +However, when Emacs acts as one of these endpoints, asynchronous +events (e.g. timer- or process-related) may be triggered while there +is still uncertainty about the state of the remote endpoint. +Furthermore, acting on these events may only sometimes demand +synchronization, depending on the event's specific nature. + +The @code{:deferred} keyword argument to @code{jsonrpc-request} and +@code{jsonrpc-async-request} is designed to let the caller indicate +that the specific request needs synchronization and its actual +issuance may be delayed to the future, until some condition is +satisfied. Specifying @code{:deferred} for a request doesn't mean it +@emph{will} be delayed, only that it @emph{can} be. If the request +isn't sent immediately, @code{jsonrpc} will make renewed efforts to +send it at certain key times during communication, such as when +receiving or sending other messages to the endpoint. + +Before any attempt to send the request, the application-specific +conditions are checked. Since the @code{jsonrpc} library can't known +what these conditions are, the programmer may use the +@code{jsonrpc-connection-ready-p} generic function (@pxref{Generic +Functions}) to specify them. The default method for this function +returns @code{t}, but you can add overriding methods that return +@code{nil} in some situations, based on the arguments passed to it, +which are the @code{jsonrpc-connection} object (@pxref{JSONRPC +Overview}) and whichever value you passed as the @code{:deferred} +keyword argument. + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -5049,8 +5479,8 @@ making. When that happens, the arguments to individual changes are made, but won't necessarily be the minimal such region, and the arguments to each successive call of @code{after-change-functions} will then delimit the part of text being -changed exactly. In general, we advise to use either before- or the -after-change hooks, but not both. +changed exactly. In general, we advise using either the before- or +the after-change hook, but not both. @defmac combine-after-change-calls body@dots{} The macro executes @var{body} normally, but arranges to call the @@ -5074,6 +5504,30 @@ because it may lead to inefficient behavior for some change hook functions. @end defmac +@defmac combine-change-calls beg end body@dots{} +This executes @var{body} normally, except any buffer changes it makes +do not trigger the calls to @code{before-change-functions} and +@code{after-change-functions}. Instead there is a single call of each +of these hooks for the region enclosed by @var{beg} and @var{end}, the +parameters supplied to @code{after-change-functions} reflecting the +changes made to the size of the region by @var{body}. + +The result of this macro is the result returned by @var{body}. + +This macro is useful when a function makes a possibly large number of +repetitive changes to the buffer, and the change hooks would otherwise +take a long time to run, were they to be run for each individual +buffer modification. Emacs itself uses this macro, for example, in +the commands @code{comment-region} and @code{uncomment-region}. + +@strong{Warning:} You must not alter the values of +@code{before-change-functions} or @code{after-change-function} within +@var{body}. + +@strong{Warning:} You must not make any buffer changes outside of the +region specified by @var{beg} and @var{end}. +@end defmac + @defvar first-change-hook This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi index 7b14ab5a730..db68f9192bd 100644 --- a/doc/lispref/threads.texi +++ b/doc/lispref/threads.texi @@ -45,6 +45,7 @@ closure are shared by any threads invoking the closure. * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. @end menu @node Basic Thread Functions @@ -75,8 +76,8 @@ thread, @code{nil} otherwise. @defun thread-join thread Block until @var{thread} exits, or until the current thread is -signaled. If @var{thread} has already exited, this returns -immediately. +signaled. It returns the result of the @var{thread} function. If +@var{thread} has already exited, this returns immediately. @end defun @defun thread-signal thread error-symbol data @@ -87,6 +88,9 @@ thread, then this just calls @code{signal} immediately. Otherwise, If @var{thread} was blocked by a call to @code{mutex-lock}, @code{condition-wait}, or @code{thread-join}; @code{thread-signal} will unblock it. + +If @var{thread} is the main thread, the signal is not propagated +there. Instead, it is shown as message in the main thread. @end defun @defun thread-yield @@ -127,15 +131,21 @@ Return a list of all the live thread objects. A new list is returned by each invocation. @end defun +@defvar main-thread +This variable keeps the main thread Emacs is running, or @code{nil} if +Emacs is compiled without thread support. +@end defvar + When code run by a thread signals an error that is unhandled, the thread exits. Other threads can access the error form which caused the thread to exit using the following function. -@defun thread-last-error +@defun thread-last-error &optional cleanup This function returns the last error form recorded when a thread exited due to an error. Each thread that exits abnormally overwrites the form stored by the previous thread's error with a new value, so -only the last one can be accessed. +only the last one can be accessed. If @var{cleanup} is +non-@code{nil}, the stored form is reset to @code{nil}. @end defun @node Mutexes @@ -262,3 +272,53 @@ Return the name of @var{cond}, as passed to Return the mutex associated with @var{cond}. Note that the associated mutex cannot be changed. @end defun + +@node The Thread List +@section The Thread List + +@cindex thread list +@cindex list of threads +@findex list-threads +The @code{list-threads} command lists all the currently alive threads. +In the resulting buffer, each thread is identified either by the name +passed to @code{make-thread} (@pxref{Basic Thread Functions}), or by +its unique internal identifier if it was not created with a name. The +status of each thread at the time of the creation or last update of +the buffer is shown, in addition to the object the thread was blocked +on at the time, if it was blocked. + +@defvar thread-list-refresh-seconds +The @file{*Threads*} buffer will automatically update twice per +second. You can make the refresh rate faster or slower by customizing +this variable. +@end defvar + +Here are the commands available in the thread list buffer: + +@table @kbd + +@cindex backtrace of thread +@cindex thread backtrace +@item b +Show a backtrace of the thread at point. This will show where in its +code the thread had yielded or was blocked at the moment you pressed +@kbd{b}. Be aware that the backtrace is a snapshot; the thread could +have meanwhile resumed execution, and be in a different state, or +could have exited. + +You may use @kbd{g} in the thread's backtrace buffer to get an updated +backtrace, as backtrace buffers do not automatically update. +@xref{Backtraces}, for a description of backtraces and the other +commands which work on them. + +@item s +Signal the thread at point. After @kbd{s}, type @kbd{q} to send a +quit signal or @kbd{e} to send an error signal. Threads may implement +handling of signals, but the default behavior is to exit on any +signal. Therefore you should only use this command if you understand +how to restart the target thread, because your Emacs session may +behave incorrectly if necessary threads are killed. + +@item g +Update the list of threads and their statuses. +@end table diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 7f0fcffaaf1..3940dd89246 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2263,6 +2263,12 @@ selected window or never appeared in it before, or if buffer. @end defopt +@defopt switch-to-buffer-obey-display-actions +If this variable is non-@code{nil}, @code{switch-to-buffer} respects +display actions specified by @code{display-buffer-overriding-action}, +@code{display-buffer-alist} and other display related variables. +@end defopt + The next two commands are similar to @code{switch-to-buffer}, except for the described features. @@ -2607,6 +2613,12 @@ suitable @code{window-height} or @code{window-width} entry, see above. If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing @var{buffer}. + +If @var{alist} contains a @code{window-min-height} entry, this +function ensures that the window used is or can become at least as +high as specified by that entry's value. Note that this is only a +guarantee. In order to actually resize the window used, @var{alist} +must also provide an appropriate @code{window-height} entry. @end defun @defun display-buffer-at-bottom buffer alist @@ -2790,6 +2802,22 @@ The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry. +@vindex window-min-height@r{, a buffer display action alist entry} +@item window-min-height +The value specifies a minimum height of the window used, in lines. If +a window is not or cannot be made as high as specified by this entry, +the window is not considered for use. The only client of this entry +is presently @code{display-buffer-below-selected}. + +Note that providing such an entry alone does not necessarily make the +window as tall as specified by its value. To actually resize an +existing window or make a new window as tall as specified by that +value, a @code{window-height} entry specifying that value should be +provided as well. Such a @code{window-height} entry can, however, +specify a completely different value or ask the window height to be +fit to that of its buffer in which case the @code{window-min-height} +entry provides the guaranteed minimum height of the window used. + @vindex window-height@r{, a buffer display action alist entry} @item window-height The value specifies whether and how to adjust the height of the chosen @@ -4850,6 +4878,13 @@ line reappears after the echo area momentarily displays the message @samp{End of buffer}. @end deffn +@deffn Command scroll-other-window-down &optional count +This function scrolls the text in another window downward @var{count} +lines. Negative values of @var{count}, or @code{nil}, are handled as +in @code{scroll-down}. In other respects, it behaves the same way as +@code{scroll-other-window} does. +@end deffn + @defvar other-window-scroll-buffer If this variable is non-@code{nil}, it tells @code{scroll-other-window} which buffer's window to scroll. @@ -4952,7 +4987,7 @@ beginning or end of the buffer (depending on scrolling direction); only if point is already on that position do they signal an error. @end defopt -@deffn Command recenter &optional count +@deffn Command recenter &optional count redisplay @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does @@ -4966,8 +5001,12 @@ line in the window. If @var{count} is @code{nil} (or a non-@code{nil} list), @code{recenter} puts the line containing point in the middle of the -window. If @var{count} is @code{nil}, this function may redraw the -frame, according to the value of @code{recenter-redisplay}. +window. If @var{count} is @code{nil} and @var{redisplay} is +non-@code{nil}, this function may redraw the frame, according to the +value of @code{recenter-redisplay}. Thus, omitting the second +argument can be used to countermand the effect of +@code{recenter-redisplay} being non-@code{nil}. Interactive calls +pass non-‘nil’ for @var{redisplay}. When @code{recenter} is called interactively, @var{count} is the raw prefix argument. Thus, typing @kbd{C-u} as the prefix sets the @@ -4995,8 +5034,9 @@ respect to the entire window group. @defopt recenter-redisplay If this variable is non-@code{nil}, calling @code{recenter} with a -@code{nil} argument redraws the frame. The default value is -@code{tty}, which means only redraw the frame if it is a tty frame. +@code{nil} @var{count} argument and non-@code{nil} @var{redisplay} +argument redraws the frame. The default value is @code{tty}, which +means only redraw the frame if it is a tty frame. @end defopt @deffn Command recenter-top-bottom &optional count @@ -5720,9 +5760,10 @@ This function puts the window state @var{state} into @var{window}. The argument @var{state} should be the state of a window returned by an earlier invocation of @code{window-state-get}, see above. The optional argument @var{window} can be either a live window or an -internal window (@pxref{Windows and Frames}) and defaults to the -selected one. If @var{window} is not live, it is replaced by a live -window before putting @var{state} into it. +internal window (@pxref{Windows and Frames}). If @var{window} is not +a live window, it is replaced by a new live window created on the same +frame before putting @var{state} into it. If @var{window} is @code{nil}, +it puts the window state into a new window. If the optional argument @var{ignore} is non-@code{nil}, it means to ignore minimum window sizes and fixed-size restrictions. If @var{ignore} @@ -6016,6 +6057,14 @@ whether a specific window has changed size, compare the return values of @code{window-pixel-height-before-size-change} and @code{window-pixel-height} for that window (@pxref{Window Sizes}). +The buffer-local value of this hook is run once for the buffer and the +frame in question, provided at least one window showing the buffer on +that frame has changed its size. As it still receives the frame as +its sole argument, any function called on a buffer-local basis will be +oblivious to which window(s) showing the buffer changed its (their) +size and has to check out these windows by using the method described +in the previous paragraph. + These function are usually only called when at least one window was added or has changed size since the last time this hook was run for the associated frame. In some rare cases this hook also runs when a |