+ rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \

+ ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs

+define the same abbrevs. Tables that do not have any abbrevs to save

+are omitted. If @var{filename} is @code{nil} or omitted,

+modification time, as a Lisp timestamp (@pxref{Time of Day}).

+@code{visited-file-modtime} returns a timestamp for some non-file buffers

+by @code{visited-file-modtime}, it should be a Lisp time value

+(@pxref{Time of Day}).

+(mapcar #'buffer-name (buffer-list))

+Note that any non-@code{nil} symbol might be used as an event or an

+event type; @code{eventp} cannot distinguish whether a symbol is

+intended by Lisp code to be used as an event.

+

+@cindex not recording input events

+@cindex input events, prevent recording

+Elements read from this list are normally recorded by the

+record-keeping features (@pxref{Recording Input}) and while defining a

+keyboard macro (@pxref{Keyboard Macros}). However, an element of the

+form @w{@code{(no-record . @var{event})}} causes @var{event} to be

+processed normally without recording it.

+ You can also suppress compiler warnings within a certain expression

+using the @code{with-suppressed-warnings} macro:

+

+@defspec with-suppressed-warnings warnings body@dots{}

+In execution, this is equivalent to @code{(progn @var{body}...)}, but

+the compiler does not issue warnings for the specified conditions in

+@var{body}. @var{warnings} is an associative list of warning symbols

+and function/variable symbols they apply to. For instance, if you

+wish to call an obsolete function called @code{foo}, but want to

+suppress the compilation warning, say:

+

+@lisp

+(with-suppressed-warnings ((obsolete foo))

+ (foo ...))

+@end lisp

+@end defspec

+

+For more coarse-grained suppression of compiler warnings, you can use

+the @code{with-no-warnings} construct:

+We recommend that you use @code{with-suppressed-warnings} instead, but

+if you do use this construct, that you use it around the smallest

+possible piece of code to avoid missing possible warnings other than

+

+@ifnottex

+@anchor{rx in pcase}

+@item (rx @var{rx-expr}@dots{})

+Matches strings against the regexp @var{rx-expr}@dots{}, using the

+@code{rx} regexp notation (@pxref{Rx Notation}), as if by

+@code{string-match}.

+

+In addition to the usual @code{rx} syntax, @var{rx-expr}@dots{} can

+contain the following constructs:

+

+@table @code

+@item (let @var{ref} @var{rx-expr}@dots{})

+Bind the symbol @var{ref} to a submatch that matches

+@var{rx-expr}@enddots{}. @var{ref} is bound in @var{body-forms} to

+the string of the submatch or nil, but can also be used in

+@code{backref}.

+

+@item (backref @var{ref})

+Like the standard @code{backref} construct, but @var{ref} can here

+also be a name introduced by a previous @code{(let @var{ref} @dots{})}

+construct.

+@end table

+@end ifnottex

+

+@itemx @var{number}

+Use of @var{result} is deprecated. Here is an example of using

+@code{dotimes} to do something 100 times:

+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:

+@defmac ignore-error condition body@dots{}

+This macro is like @code{ignore-errors}, but will only ignore the

+specific error condition specified.

+

+@example

+ (ignore-error end-of-file

+ (read ""))

+@end example

+

+@var{condition} can also be a list of error conditions.

+@end defmac

+

+* Using Debugger:: What the debugger does.

+* Backtraces:: What you see while in the debugger.

+ 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.

+

+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:

+@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

+addition to the usual Emacs commands and to the Backtrace mode commands

+described in the previous section. The most important use of

+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.

+

+The trace is identical to the one that @code{debug} would show in the

+@file{*Backtrace*} buffer. The return value is always nil.

+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.

+ (list 'testing (backtrace))

+ eval((progn (1+ var) (list 'testing (backtrace))))

+ (list 'testing (backtrace))

+ (eval (progn (1+ var) (list 'testing (backtrace))))

+@defun progress-reporter-update reporter &optional value suffix

+Optional argument @var{suffix} is a string to be displayed after

+@var{reporter}'s main message and progress text. If @var{reporter} is

+a non-numerical reporter, then @var{value} should be @code{nil}, or a

+string to use instead of @var{suffix}.

+

+@defun progress-reporter-force-update reporter &optional value new-message suffix

+@var{reporter}, @var{value}, and @var{suffix} have the same meaning as for

+@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{}

+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 subsection using

+this macro as follows:

+@group

+@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

+@defvar warning-fill-column

+The column at which to fill warnings.

+@end defvar

+

+hiding is now obsolete and deprecated; instead you should use the

+@code{invisible} property (@pxref{Invisible Text}) to get the same effect.

+When these functions are called, @code{inhibit-modification-hooks} is

+bound to non-@code{nil}. If the functions modify the buffer, you

+might want to bind @code{inhibit-modification-hooks} to @code{nil}, so

+as to cause the change hooks to run for these modifications. However,

+doing this may call your own change hook recursively, so be sure to

+prepare for that. @xref{Change Hooks}.

+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.

+@defun set-window-fringes window left &optional right outside-margins persistent

+with its @var{keep-margins} argument @code{nil} or omitted. However,

+if the optional fifth argument @var{persistent} is non-@code{nil} and

+the other arguments are processed successfully, the values specified

+here unconditionally survive subsequent invocations of

+@code{set-window-buffer}.

+@var{right-width} @var{outside-margins} @var{persistent})}.

+@item @code{up-arrow}, @code{down-arrow}

+@itemx @code{top-left-angle}, @code{top-right-angle}

+@itemx @code{left-bracket}, @code{right-bracket}

+@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}

+@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type persistent

+@var{height} specifies the height of the horizontal scroll bar in

+pixels (@code{nil} means use the height specified for the frame).

+@var{horizontal-type} specifies whether to have a horizontal scroll

+bar. The possible values are @code{bottom}, @code{t}, which means to

+use the frame's default, and @code{nil} for no horizontal scroll bar.

+Note that for a mini window the value @code{t} has the same meaning as

+@code{nil}, namely to not show a horizontal scroll bar. You have to

+explicitly specify @code{bottom} in order to show a horizontal scroll

+bar in a mini window.

+with its @var{keep-margins} argument @code{nil} or omitted. However,

+if the optional fifth argument @var{persistent} is non-@code{nil} and

+the other arguments are processed successfully, the values specified

+here unconditionally survive subsequent invocations of

+@code{set-window-buffer}.

+@var{horizontal-type} @var{persistent})}.

+

+The value of @var{persistent} is the value specified for @var{window}

+with the last successful invocation of @code{set-window-scroll-bars},

+@code{nil} if there never was one.

+If you do not specify a window's scroll bar settings via

+@item :width @var{width}, :height @var{height}

+The @code{:width} and @code{:height} keywords are used for scaling the

+image. If only one of them is specified, the other one will be

+calculated so as to preserve the aspect ratio. If both are specified,

+aspect ratio may not be preserved.

+

+@item :max-width @var{max-width}, :max-height @var{max-height}

+The @code{:max-width} and @code{:max-height} keywords are used for

+scaling if the size of the image exceeds these values. If

+@code{:width} is set, it will have precedence over @code{max-width},

+and if @code{:height} is set, it will have precedence over

+@code{max-height}, but you can otherwise mix these keywords as you

+wish.

+

+If both @code{:max-width} and @code{:height} are specified, but

+@code{:width} is not, preserving the aspect ratio might require that

+width exceeds @code{:max-width}. If this happens, scaling will use a

+smaller value for the height so as to preserve the aspect ratio while

+not exceeding @code{:max-width}. Similarly when both

+@code{:max-height} and @code{:width} are specified, but @code{:height}

+is not. For example, if you have a 200x100 image and specify that

+@code{:width} should be 400 and @code{:max-height} should be 150,

+you'll end up with an image that is 300x150: Preserving the aspect

+ratio and not exceeding the ``max'' setting. This combination of

+parameters is a useful way of saying ``display this image as large as

+possible, but no larger than the available display area''.

+

+@item :scale @var{scale}

+This should be a number, where values higher than 1 means to increase

+the size, and lower means to decrease the size, by multiplying both

+the width and height. For instance, a value of 0.25 will make the

+image a quarter size of what it originally was. If the scaling makes

+the image larger than specified by @code{:max-width} or

+@code{:max-height}, the resulting size will not exceed those two

+values. If both @code{:scale} and @code{:height}/@code{:width} are

+specified, the height/width will be adjusted by the specified scaling

+factor.

+

+@item :rotation @var{angle}

+Specifies a rotation angle in degrees. Only multiples of 90 degrees

+are supported, unless the image type is @code{imagemagick}. Positive

+values rotate clockwise, negative values counter-clockwise. Rotation

+is performed after scaling and cropping.

+

+@item :index @var{frame}

+@xref{Multi-Frame Images}.

+

+@defun image-transforms-p &optional frame

+This function returns non-@code{nil} if @var{frame} supports image

+scaling and rotation. @var{frame} @code{nil} or omitted means to use

+the selected frame (@pxref{Input Focus}). The returned list includes

+symbols that indicate which image transform operations are supported:

+

+@table @code

+@item scale

+Image scaling is supported by @var{frame} via the @code{:scale},

+@code{:width}, @code{:height}, @code{:max-width}, and

+@code{:max-height} properties.

+@item rotate90

+Image rotation is supported by @var{frame} if the rotation angle is an

+integral multiple of 90 degrees.

+@end table

+

+If image transforms are not supported, @code{:rotation}, @code{:crop},

+@code{:width}, @code{:height}, @code{:scale}, @code{:max-width} and

+@code{:max-height} will only be usable through ImageMagick, if

+available (@pxref{ImageMagick Images}).

+@end defun

+@item :crop @var{geometry}

+The value of @var{geometry} should be a list of the form

+@code{(@var{width} @var{height} @var{x} @var{y})}. @var{width} and

+@var{height} specify the width and height of the cropped image. If

+@var{x} is a positive number it specifies the offset of the cropped

+area from the left of the original image, and if negative the offset

+from the right. If @var{y} is a positive number it specifies the

+offset from the top of the original image, and if negative from the

+bottom. If @var{x} or @var{y} are @code{nil} or unspecified the crop

+area will be centred on the original image.

+

+If the crop area is outside or overlaps the edge of the image it will

+be reduced to exclude any areas outside of the image. This means it

+is not possible to use @code{:crop} to increase the size of the image

+by entering large @var{width} or @var{height} values.

+

+Cropping is performed after scaling but before rotation.

+Rotate the image by 90 degrees clockwise (@code{image-rotate}).

+A prefix means to rotate by 90 degrees counter-clockwise instead.

+@code{action} as normal. If the @code{button-data} property is

+present in @var{button}, use that as the argument for the

+@code{action} function instead of @var{button}.

+@deffn Command forward-button n &optional wrap display-message no-error

+is skipped over. Returns the button found, and signals an error if no

+buttons can be found. If @var{no-error} in non-@code{nil}, return nil

+instead of signalling the error.

+is skipped over. Returns the button found, and signals an error if no

+buttons can be found. If @var{no-error} in non-@code{nil}, return nil

+instead of signalling the error.

+@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.

+

+@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

+* Deferred Eval:: Deferred and lazy evaluation of forms.

+* Using Debugger:: What the debugger does.

+* Backtraces:: What you see while in the debugger.

+@ifnottex

+* Rx Notation:: An alternative, structured regexp notation.

+@end ifnottex

+* The Thread List:: Show the active threads.

+@item range-error

+The message is @code{Arithmetic range error}.

+This can happen with integers exceeding the @code{integer-width} limit.

+@xref{Integer Basics}.

+

+* 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.

+ @result{} 'foo

+ @result{} 'foo

+ @result{} ['foo]

+

+@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.

+@xref{Lisp and Coding Systems, inhibit-nul-byte-detection}.

+to a named user, the value is an integer.

+The time of last access as a Lisp timestamp

+(@code{file-attribute-access-time}). The timestamp is in the

+style of @code{current-time} (@pxref{Time of Day}) and is truncated

+The time of last modification as a Lisp timestamp

+The time of last status change as a Lisp timestamp

+The size of the file in bytes (@code{file-attribute-size}).

+The file's inode number (@code{file-attribute-inode-number}),

+a nonnegative integer.

+@code{file-attribute-device-number}), an integer.

+This element and the file's inode number

+ t 6473924464520138

+ 1014478468)

+@item 6473924464520138

+@item 1014478468

+@defun executable-find program &optional remote

+the file is not found. The function searches in all the directories

+

+If @var{remote} is non-@code{nil}, and @code{default-directory} is a

+remote directory, @var{program} is searched on the respective remote host.

+@defun file-name-base filename

+file name, @code{nil} otherwise. A file name is considered to be

+absolute if its first component is @samp{~}, or is @samp{~@var{user}}

+where @var{user} is a valid login name. In the following examples,

+assume that there is a user named @samp{rms} but no user named

+@samp{nosuchuser}.

+(file-name-absolute-p "~nosuchuser/foo")

+ @result{} nil

+@end group

+@group

+@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

+@defun directory-files-recursively directory regexp &optional include-directories predicate follow-symlinks

+

+By default, all subdirectories are descended into. If @var{predicate}

+is @code{t}, errors when trying to descend into a subdirectory (for

+instance, if it's not readable by this user) are ignored. If it's

+neither @code{nil} nor @code{t}, it should be a function that takes

+one parameter (the subdirectory name) and should return non-@code{nil}

+if the directory is to be descended into.

+

+Symbolic links to subdirectories are not followed by default, but if

+@var{follow-symlinks} is non-@code{nil}, they are followed.

+list @code{(@var{filename} . @var{attributes})}, where @var{attributes}

+@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

+

+@cindex file name handler

+@code{dired-compress-file}, @code{dired-uncache},

+@code{exec-path}, @code{expand-file-name},@*

+@code{file-symlink-p}, @code{file-system-info},

+@code{file-truename}, @code{file-writable-p},

+@code{make-process},

+@code{exec-path}, @code{expand-file-name},

+@code{file-symlink-p}, @code{file-system-info},

+@code{file-truename}, @code{file-writable-p},

+@code{make-process},

+files at the same time. Implementers of file name handlers need to

+ensure this principle is valid.

+ (< 0 (file-attribute-size

+ (file-attributes

+ (file-chase-links file)))))))

+@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

+

+On multi-monitor displays it is possible to use the command

+@code{make-frame-on-monitor} to make frames on the specified monitor.

+

+@deffn Command make-frame-on-monitor monitor &optional display parameters

+This function creates and returns a new frame on @var{monitor} located

+on @var{display}, taking the other frame parameters from the alist

+@var{parameters}. @var{monitor} should be the name of the physical

+monitor, the same string as returned by the function

+@code{display-monitor-attributes-list} in the attribute @code{name}.

+@var{display} should be the name of an X display (a string).

+@end deffn

+The special value @code{child-frame} means to make a minibuffer-only

+child frame (@pxref{Child Frames}) whose parent becomes the frame

+created. As if specified as @code{nil}, Emacs will set this parameter

+to the minibuffer window of the child frame but will not select the

+child frame after its creation.

+

+drawing characters on the frame, in order of priority. In Emacs built

+without Cairo drawing on X, there are currently three available font

+backends: @code{x} (the X core font driver), @code{xft} (the Xft font

+driver), and @code{xfthb} (the Xft font driver with HarfBuzz text

+shaping). If built with the Cairo drawing, there are also three

+available font backends on X: @code{x}, @code{ftcr} (the FreeType font

+driver on Cairo), and @code{ftcrhb} (the FreeType font driver on Cairo

+with HarfBuzz text shaping). On MS-Windows, there are currently three

+available font backends: @code{gdi} (the core MS-Windows font driver),

+@code{uniscribe} (font driver for OTF and TTF fonts with text shaping

+by the Uniscribe engine), and @code{harfbuzz} (font driver for OTF and

+TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs,

+The GNU Emacs Manual}). On other systems, there is only one available

+font backend, so it does not make sense to modify this frame

+parameter.

+@vindex after-delete-frame-functions

+@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}.

+way, Emacs automatically keeps track of which frames have focus. To

+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.

+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.

+@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

+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.

+@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 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.

+child frames are made visible.

+

+ When a parent frame is about to be deleted (@pxref{Deleting

+Frames}), its child frames are recursively deleted before it. There

+is one exception to this rule: When the child frame serves as a

+surrogate minibuffer frame (@pxref{Minibuffers and Frames}) for

+another frame, it is retained until the parent frame has been deleted.

+If, at this time, no remaining frame uses the child frame as its

+minibuffer frame, Emacs will try to delete the child frame too. If

+that deletion fails for whatever reason, the child frame is made a

+top-level frame.

+ @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]}

+ @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]})

+

+When @var{function-object} is a symbol and the code is byte compiled,

+the byte-compiler will warn if that function is not defined or might

+not be known at run time.

+@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body

+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.

+As a trivial example, here's how to add advice that'll modify the

+return value of a function every time it's called:

+

+@example

+(defun my-double (x)

+ (* x 2))

+(defun my-increase (x)

+ (+ x 1))

+(advice-add 'my-double :filter-return #'my-increase)

+@end example

+

+After adding this advice, if you call @code{my-double} with @samp{3},

+the return value will be @samp{7}. To remove this advice, say

+

+@example

+(advice-remove 'my-double #'my-increase)

+@end example

+

+A more advanced example would be to trace the calls to the process

+filter of a process @var{proc}:

+It can reduce this integer modulo the length of the array, to produce an

+two keys directly. The two functions should be consistent with each

+other: that is, two keys' hash codes should be the same if the keys

+compare as equal. Also, since the two functions can be called at any

+time (such as by the garbage collector), the functions should be free

+of side effects and should return quickly, and their behavior should

+depend on only on properties of the keys that do not change.

+function should use the whole range of fixnums for hash codes,

+including negative fixnums.

+This is an integer that reflects the contents of @var{obj}

+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.

+Lisp programs should @emph{not} rely on hash codes being preserved

+between Emacs sessions, as the implementation of the hash functions

+uses some details of the object storage that can change between

+sessions and between different architectures.

+

+@itemx server-after-make-frame-hook

+@itemx after-delete-frame-functions

+after-set-visited-file-name-hook

+@cindex @option{--temacs} option, and dumping method

+Instead, one of the last steps of building Emacs runs the command

+@w{@samp{temacs -batch -l loadup --temacs=@var{dump-method}}}. The

+special option @option{--temacs} tells @command{temacs} how to record

+all the standard preloaded Lisp functions and variables, so that when

+you subsequently run Emacs, it will start much faster. The

+@option{--temacs} option requires an argument @var{dump-method}, which

+can be one of the following:

+

+@table @samp

+@item pdump

+@cindex dump file

+Record the preloaded Lisp data in a @dfn{dump file}. This

+method produces an additional data file which Emacs will load at

+startup. The produced dump file is usually called @file{emacs.pdmp},

+and is installed in the Emacs @code{exec-directory} (@pxref{Help

+Functions}). This method is the most preferred one, as it does not

+require Emacs to employ any special techniques of memory allocation,

+which might get in the way of various memory-layout techniques used by

+modern systems to enhance security and privacy.

+

+@item pbootstrap

+@cindex bootstrapping Emacs

+Like @samp{pdump}, but used while @dfn{bootstrapping} Emacs, when no

+previous Emacs binary and no @file{*.elc} byte-compiled Lisp files are

+available. The produced dump file is usually named

+@file{bootstrap-emacs.pdmp} in this case.

+

+@item dump

+@cindex unexec

+This method causes @command{temacs} to dump out an executable program,

+called @file{emacs}, which has all the standard Lisp files already

+preloaded into it. (The @samp{-batch} argument prevents

+@command{temacs} from trying to initialize any of its data on the

+terminal, so that the tables of terminal information are empty in the

+dumped Emacs.) This method is also known as @dfn{unexec}, because it

+produces a program file from a running process, and thus is in some

+sense the opposite of executing a program to start a process.

+Although this method was the way that Emacs traditionally saved its

+state, it is now deprecated.

+

+@item bootstrap

+Like @samp{dump}, but used when bootstrapping Emacs with the

+@code{unexec} method.

+@end table

+is the one which is installed. If the portable dumper was used to

+build Emacs, the @file{emacs} executable is actually an exact copy of

+@file{temacs}, and the corresponding @file{emacs.pdmp} file is

+installed as well. The variable @code{preloaded-file-list} stores a

+list of the preloaded Lisp files recorded in the dump file or

+in the dumped Emacs executable. If you port Emacs to a new operating

+system, and are not able to implement dumping of any kind, then Emacs

+must load @file{loadup.el} each time it starts.

+@defun dump-emacs-portable to-file &optional track-referrers

+This function dumps the current state of Emacs into a dump

+file @var{to-file}, using the @code{pdump} method. Normally, the

+dump file is called @file{@var{emacs-name}.dmp}, where

+@var{emacs-name} is the name of the Emacs executable file. The

+optional argument @var{track-referrers}, if non-@code{nil}, causes the

+portable dumper to keep additional information to help track

+down the provenance of object types that are not yet supported by the

+@code{pdump} method.

+

+Although the portable dumper code can run on many platforms, the dump

+files that it produces are not portable---they can be loaded only by

+the Emacs executable that dumped them.

+

+If you want to use this function in an Emacs that was already dumped,

+you must run Emacs with the @samp{-batch} option.

+@end defun

+

+@var{to-file}, using the @code{unexec} method. It takes symbols from

+@var{from-file} (this is normally the executable file @file{temacs}).

+This function cannot be used in an Emacs that was already dumped.

+This function is deprecated, and by default Emacs is built without

+@code{unexec} support so this function is not available.

+@end defun

+

+@defun pdumper-stats

+If the current Emacs session restored its state from a dump

+file, this function returns information about the dump file and the

+time it took to restore the Emacs state. The value is an alist

+@w{@code{((dumped-with-pdumper . t) (load-time . @var{time})

+(dump-file-name . @var{file}))}},

+where @var{file} is the name of the dump file, and @var{time} is the

+time in seconds it took to restore the state from the dump file.

+If the current session was not restored from a dump file, the

+value is nil.

+ Beyond the basic vector, a lot of objects like markers, overlays and

+buffers are managed as if they were vectors. The corresponding C data

+ (strings 32 2942 2607)

+Size in bytes of a vector of length 1, including its header.

+Slot counts might include some or all overhead from vector headers,

+depending on the platform.

+This function returns an estimate of the total amount of bytes of

+virtual memory that Emacs is currently using, divided by 1024.

+This includes vector-like objects such as markers and overlays, plus

+certain objects not visible to users.

+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.

+

+@file{emacs-module.h} defines a preprocessor macro

+@code{EMACS_MAJOR_VERSION}. It expands to an integer literal which is

+the latest major version of Emacs supported by the header.

+@xref{Version Info}. Note that the value of

+@code{EMACS_MAJOR_VERSION} is a compile-time constant and does not

+represent the version of Emacs that is currently running and has

+loaded your module. If you want your module to be compatible with

+various versions of @file{emacs-module.h} as well as various versions

+of Emacs, you can use conditional compilation based on

+@code{EMACS_MAJOR_VERSION}.

+

+@w{@code{long long}}. If the value of @var{arg} doesn't fit into an

+@code{intmax_t}, the function signals an error using the error symbol

+@code{overflow-error}.

+@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{time})

+This function, which is available since Emacs 27, interprets

+@var{time} as an Emacs Lisp time value and returns the corresponding

+@code{struct timespec}. @xref{Time of Day}. @code{struct timespec}

+represents a timestamp with nanosecond precision. It has the

+following members:

+

+@table @code

+@item time_t tv_sec

+Whole number of seconds.

+@item long tv_nsec

+Fractional seconds as number of nanoseconds, always less than one

+billion.

+@end table

+

+@noindent

+@xref{Elapsed Time,,,libc}.

+

+If @var{time} has higher precision than nanoseconds, then this

+function truncates it to nanosecond precision towards negative

+infinity. This function signals an error if @var{time} (truncated to

+nanoseconds) cannot be represented by @code{struct timespec}. For

+example, if @code{time_t} is a 32-bit integral type, then a @var{time}

+value of ten billion seconds would signal an error, but a @var{time}

+value of 600 picoseconds would get truncated to zero.

+

+If you need to deal with time values that are not representable by

+@code{struct timespec}, or if you want higher precision, call the Lisp

+function @code{encode-time} and work with its return value.

+@xref{Time Conversion}.

+@end deftypefn

+

+corresponding @code{emacs_value} object. It returns either a fixnum

+or a bignum depending on whether the value of @var{n} is inside the

+limits set by @code{most-negative-fixnum} and

+@code{most-positive-fixnum} (@pxref{Integer Basics}).

+@deftypefn Function emacs_value make_time (emacs_env *@var{env}, struct timespec @var{time})

+This function, which is available since Emacs 27, takes a @code{struct

+timespec} argument @var{time} and returns the corresponding Emacs

+timestamp as a pair @code{(@var{ticks} . @var{hz})}. @xref{Time of

+Day}. The return value represents exactly the same timestamp as

+@var{time}: all input values are representable, and there is never a

+loss of precision. @code{@var{time}.tv_sec} and

+@code{@var{time}.tv_nsec} can be arbitrary values. In particular,

+there's no requirement that @var{time} be normalized. This means that

+@code{@var{time}.tv_nsec} can be negative or larger than 999,999,999.

+@end deftypefn

+

+If you define the preprocessor macro @code{EMACS_MODULE_GMP} before

+including the header @file{emacs-module.h}, you can also convert

+between Emacs integers and GMP @code{mpz_t} values. @xref{GMP

+Basics,,,gmp}. If @code{EMACS_MODULE_GMP} is defined,

+@file{emacs-module.h} wraps @code{mpz_t} in the following structure:

+

+@deftp struct emacs_mpz value

+struct emacs_mpz @{ mpz_t value; @};

+@end deftp

+

+@noindent

+Then you can use the following additional functions:

+

+@deftypefn Function bool extract_big_integer (emacs_env *@var{env}, emacs_value @var{arg}, struct emacs_mpz *@var{result})

+This function, which is available since Emacs 27, extracts the

+integral value of @var{arg} into @var{result}. @var{result} must not

+be @code{NULL}. @code{@var{result}->value} must be an initialized

+@code{mpz_t} object. @xref{Initializing Integers,,,gmp}. If

+@var{arg} is an integer, Emacs will store its value into

+@code{@var{result}->value}. After you have finished using

+@code{@var{result}->value}, you should free it using @code{mpz_clear}

+or similar.

+@end deftypefn

+

+@deftypefn Function emacs_value make_big_integer (emacs_env *@var{env}, const struct emacs_mpz *@var{value})

+This function, which is available since Emacs 27, takes an

+arbitrary-sized integer argument and returns a corresponding

+@code{emacs_value} object. @var{value} must not be @code{NULL}.

+@code{@var{value}->value} must be an initialized @code{mpz_t} object.

+@xref{Initializing Integers,,,gmp}. Emacs will return a corresponding

+integral object. After you have finished using

+@code{@var{value}->value}, you should free it using @code{mpz_clear}

+or similar.

+@end deftypefn

+

+The following example uses GMP to calculate the next probable prime

+after a given integer:

+

+@example

+#include <assert.h>

+#include <gmp.h>

+

+#define EMACS_MODULE_GMP

+#include <emacs-module.h>

+

+static emacs_value

+next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args,

+ void *data)

+@{

+ assert (nargs == 1);

+ emacs_mpz p;

+ mpz_init (p.value);

+ env->extract_big_integer (env, args[0], &p);

+ mpz_nextprime (p.value, p.value);

+ emacs_value result = env->make_big_integer (env, &p);

+ mpz_clear (p.value);

+ return result;

+@}

+@end example

+

+processing and returns as soon as possible. In most cases, use

+@code{process_input} instead.

+@end deftypefn

+

+To process input events in addition to checking whether the user wants

+to quit, use the following function, which is available since Emacs

+27.1.

+

+@anchor{process_input}

+@deftypefn Function enum emacs_process_input_result process_input (emacs_env *@var{env})

+This function processes pending input events. It returns

+@code{emacs_process_input_quit} if the user wants to quit or an error

+occurred while processing signals. In that case, we recommend that

+your module function aborts any on-going processing and returns as

+soon as possible. If the module code may continue running,

+@code{process_input} returns @code{emacs_process_input_continue}. The

+return value is @code{emacs_process_input_continue} if and only if

+there is no pending nonlocal exit in @code{env}. If the module

+continues after calling @code{process_input}, global state such as

+variable values and buffer content may have been modified in arbitrary

+ways.

+@deftypefn Function enum emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})

+or vectorlike object. Each of these data types has the

+Since the tag space is limited, all other types are the subtypes of

+@code{Lisp_Vectorlike}. Vector subtypes are enumerated

+frames, and processes fall into this category.

+A @code{printf}-family function can print such a value

+via a format like @code{"%"PRIdMAX}.

+built. It uses the style of

+@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

+

+@code{local-function-key-map} inherits from @code{function-key-map}.

+The latter should only be altered if you want the binding to apply in

+all terminals, so using the former is almost always preferred.

+ (logior (ash 1 24) e)

+ '(menu-item "Continue Replace" multifile-continue

+@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

+@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

+

+This function returns a list of numbers starting with @var{from} and

+ @result{} (lambda (x) (nconc '(foo) x))

+ @result{} (lambda (x) (nconc '(foo 1 2 3 4) x))

+@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}.

+(autoload 'doctor "doctor" "\

+@findex read-variable@r{, history list}

+@defvar custom-variable-history

+A history list for variable-name arguments read by

+@code{read-variable}.

+@end defvar

+

+@samp{*} for each character in the password. If you want to apply

+The option @code{resize-mini-windows} does not affect the behavior of

+minibuffer-only frames (@pxref{Frame Layout}). The following option

+allows to automatically resize such frames as well.

+

+@defopt resize-mini-frames

+If this is @code{nil}, minibuffer-only frames are never resized

+automatically.

+

+If this is a function, that function is called with the

+minibuffer-only frame to be resized as sole argument. At the time

+this function is called, the buffer of the minibuffer window of that

+frame is the buffer whose contents will be shown the next time that

+window is redisplayed. The function is expected to fit the frame to

+the buffer in some appropriate way.

+

+Any other non-@code{nil} value means to resize minibuffer-only frames

+by calling @code{fit-frame-to-buffer} (@pxref{Resizing Windows}).

+@end defopt

+

+minibuffer, it scrolls this window (@pxref{Textual Scrolling}).

+@defun add-hook hook function &optional depth local

+first (barring another @code{add-hook} call).

+

+In some cases, it is important to control the relative ordering of functions

+on the hook. The optional argument @var{depth} lets you indicate where the

+function should be inserted in the list: it should then be a number

+between -100 and 100 where the higher the value, the closer to the end of the

+list the function should go. The @var{depth} defaults to 0 and for backward

+compatibility when @var{depth} is a non-nil symbol it is interpreted as a depth

+of 90. Furthermore, when @var{depth} is strictly greater than 0 the function

+is added @emph{after} rather than before functions of the same depth.

+One should never use a depth of 100 (or -100), because one can never be

+sure that no other function will ever need to come before (or after) us.

+@cindex suspend major mode temporarily

+one. However, you can temporarily @dfn{suspend} a major mode and later

+@dfn{restore} the suspended mode, see below.

+@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

+

+@defopt tabulated-list-gui-sort-indicator-asc

+This variable specifies the character to be used on GUI frames as an

+indication that the column is sorted in the ascending order.

+

+Whenever you change the sort direction in Tabulated List buffers, this

+indicator toggles between ascending (``asc'') and descending (``desc'').

+@end defopt

+

+@defopt tabulated-list-gui-sort-indicator-desc

+Like @code{tabulated-list-gui-sort-indicator-asc}, but used when the

+column is sorted in the descending order.

+@end defopt

+

+@defopt tabulated-list-tty-sort-indicator-asc

+Like @code{tabulated-list-gui-sort-indicator-asc}, but used for

+text-mode frames.

+@end defopt

+

+@defopt tabulated-list-tty-sort-indicator-desc

+Like @code{tabulated-list-tty-sort-indicator-asc}, but used when the

+column is sorted in the descending order.

+@end defopt

+

+ (setq-local text-mode-variant t)

+ (setq-local require-final-newline mode-require-final-newline))

+ '(([C-backspace] . hungry-electric-delete)))

+@kbd{C-@key{DEL}}. There are no @var{body} forms---many minor modes

+don't need any.

+ (hungry-electric-delete t)))))

+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

+high 16 bits. This usage is obsolescent.

+@var{char} in @var{charset}. If

+@defvar inhibit-nul-byte-detection

+Return a list @w{@code{(@var{width} @var{height})}} of 2 integers, for

+the default paper size measured in millimeters (locale items

+@code{_NL_PAPER_WIDTH} and @code{_NL_PAPER_HEIGHT}).

+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.

+ 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

+but many machines provide a wider range.

+ The Lisp reader reads an integer as a nonempty sequence

+of decimal digits with optional initial sign and optional

+final period.

+ 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

+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:

+ In binary, the decimal integer 5 looks like this:

+@dots{}000101

+(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.)

+@dots{}111111

+@minus{}1 is represented as all ones. (This is called @dfn{two's

+@dots{}111011

+@cindex largest fixnum

+@cindex maximum fixnum

+The value of this variable is the greatest ``small'' integer that Emacs

+Lisp can handle. Typical values are

+@cindex smallest fixnum

+@cindex minimum fixnum

+The value of this variable is the numerically least ``small'' integer

+that Emacs Lisp can handle. It is negative. Typical values are

+@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 controls

+whether Emacs signals a range error when a large integer would be

+calculated. Integers with absolute values less than

+@ifnottex

+2**@var{n},

+@end ifnottex

+@tex

+@math{2^{n}},

+@end tex

+where @var{n} is this variable's value, do not signal a range error.

+Attempts to create larger integers typically signal a range error,

+although there might be no signal if a larger integer can be created cheaply.

+Setting this variable to a large number can be costly if a computation

+creates huge integers.

+@end defvar

+

+with respect to numeric comparisons like @code{=}. This follows the

+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}.

+precisely, if @var{x} is finite and nonzero, the value is the

+logarithm base 2 of @math{|x|}, rounded down to an integer.

+If @var{x} is zero, infinite, or a NaN, the value is minus infinity,

+plus infinity, or a NaN respectively.

+(logb 0)

+ @result{} -1.0e+INF

+@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

+

+@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

+ 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

+@code{(eql 1 1)} both return @code{t}. This can be used to compare

+large integers as well as small ones.

+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

+@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 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.

+(ash 7 1) @result{} 14

+@dots{}000111

+ @result{}

+@dots{}001110

+(ash 7 -1) @result{} 3

+@dots{}000111

+ @result{}

+@dots{}000011

+(ash -7 1) @result{} -14

+@dots{}111001

+ @result{}

+@dots{}110010

+(ash -7 -1) @result{} -4

+@dots{}111001

+ @result{}

+@dots{}111100

+Here are examples of shifting left or right by two bits:

+@smallexample

+ ; @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}

+(ash 5 -2)

+ @result{} 1 ; = @r{@dots{}000001}

+(ash -5 -2)

+ @result{} -2 ; = @r{@dots{}111110}

+@end smallexample

+@end defun

+@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.

+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.

+ ; @r{ binary values}

+(ash -7 -1) ; -7 = @r{@dots{}111111111111111111111111111001}

+ @result{} -4 ; = @r{@dots{}111111111111111111111111111100}

+(lsh -7 -1)

+ @result{} 536870908 ; = @r{@dots{}011111111111111111111111111100}

+(ash -5 -2) ; -5 = @r{@dots{}111111111111111111111111111011}

+ @result{} -2 ; = @r{@dots{}111111111111111111111111111110}

+(lsh -5 -2)

+ @result{} 268435454 ; = @r{@dots{}001111111111111111111111111110}

+ ; @r{ binary values}

+(logand 14 13) ; 14 = @r{@dots{}001110}

+ ; 13 = @r{@dots{}001101}

+ @result{} 12 ; 12 = @r{@dots{}001100}

+(logand 14 13 4) ; 14 = @r{@dots{}001110}

+ ; 13 = @r{@dots{}001101}

+ ; 4 = @r{@dots{}000100}

+ @result{} 4 ; 4 = @r{@dots{}000100}

+ @result{} -1 ; -1 = @r{@dots{}111111}

+ ; @r{ binary values}

+(logior 12 5) ; 12 = @r{@dots{}001100}

+ ; 5 = @r{@dots{}000101}

+ @result{} 13 ; 13 = @r{@dots{}001101}

+(logior 12 5 7) ; 12 = @r{@dots{}001100}

+ ; 5 = @r{@dots{}000101}

+ ; 7 = @r{@dots{}000111}

+ @result{} 15 ; 15 = @r{@dots{}001111}

+ ; @r{ binary values}

+(logxor 12 5) ; 12 = @r{@dots{}001100}

+ ; 5 = @r{@dots{}000101}

+ @result{} 9 ; 9 = @r{@dots{}001001}

+(logxor 12 5 7) ; 12 = @r{@dots{}001100}

+ ; 5 = @r{@dots{}000101}

+ ; 7 = @r{@dots{}000111}

+ @result{} 14 ; 14 = @r{@dots{}001110}

+;; 5 = @r{@dots{}000101}

+;; -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

+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{limit} is a positive fixnum, the value is chosen to be

+any fixnum, i.e., any integer from @code{most-negative-fixnum} through

+@code{most-positive-fixnum} (@pxref{Integer Basics}).

+ 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

+

+ 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.

+These kinds of array may have any length up to the largest fixnum,

+subject to system architecture limits and available memory.

+@item bignump

+@xref{Predicates on Numbers, floatp}.

+

+@item fixnump

+@xref{Predicates on Numbers, floatp}.

+

+If @var{object1} and @var{object2} are fixnums with the same value,

+For other types of objects whose contents cannot be changed (e.g.,

+bignums and 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.

+(eq 3.0 3.0)

+ @result{} t @r{or} nil

+;; @r{The result is implementation-dependent.}

+@end group

+

+@group

+ For @code{equal}, equality is defined recursively; for example, given

+Comparing circular lists may therefore cause deep recursion that leads

+to an error, and this may result in counterintuitive behavior such as

+@code{(equal a b)} returning @code{t} whereas @code{(equal b a)}

+signals an error.

+@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).

+

+@cindex @file{early-init.el}

+@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}.

+

+@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

+

+@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}.

+

+ 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:

+In some cases, functions may default to returning two- or

+On all current machines @var{picosec} is a multiple of 1000, but this

+may change as higher-resolution clocks become available.

+@end itemize

+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

+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},

+This function returns the current time as a Lisp timestamp.

+@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.

+

+To access (or alter) the elements in the time value, the

+@code{decoded-time-second}, @code{decoded-time-minute},

+@code{decoded-time-hour}, @code{decoded-time-day},

+@code{decoded-time-month}, @code{decoded-time-year},

+@code{decoded-time-weekday}, @code{decoded-time-dst} and

+@code{decoded-time-zone} accessors can be used.

+

+For instance, to increase the year in a decoded time, you could say:

+

+@lisp

+(setf (decoded-time-year decoded-time)

+ (+ (decoded-time-year decoded-time) 4))

+@end lisp

+

+Also see the following function.

+

+@end defun

+

+@defun decoded-time-add time delta

+This function takes a decoded time structure and adds @var{delta}

+(also a decoded time structure) to it. Elements in @var{delta} that

+are @code{nil} are ignored.

+

+For instance, if you want ``same time next month'', you

+could say:

+

+@lisp

+(let ((time (decode-time))

+ (delta (make-decoded-time :month 2)))

+ (encode-time (decoded-time-add time delta)))

+@end lisp

+

+If this date doesn't exist (if you're running this on January 31st,

+for instance), then the date will be shifted back until you get a

+valid date (which will be February 28th or 29th, depending).

+

+Fields are added in a most to least significant order, so if the

+adjustment described above happens, it happens before adding days,

+hours, minutes or seconds.

+

+The values in @var{delta} can be negative to subtract values instead.

+

+The return value is a decoded time structure.

+@defun make-decoded-time &key second minute hour day month year dst zone

+Return a decoded time structure with only the given keywords filled

+out, leaving the rest @code{nil}. For instance, to get a structure

+that represents ``two months'', you could say:

+

+@lisp

+(make-decoded-time :month 2)

+@end lisp

+@end defun

+

+@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.

+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:

+(encode-time (decode-time @dots{}))

+@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month};

+for example, day 0 means the day preceding the given month.

+Time values include @code{nil}, numbers, and Lisp timestamps

+(@pxref{Time of Day}).

+corresponding Lisp timestamp. The argument @var{string} should represent

+@vindex ISO 8601 date/time strings

+@defun iso8601-parse string

+For a more strict function (that will error out upon invalid input),

+this function can be used instead. It's able to parse all variants of

+the ISO 8601 standard, so in addition to the formats mentioned above,

+it also parses things like ``1998W45-3'' (week number) and

+``1998-245'' (ordinal day number). To parse durations, there's

+@code{iso8601-parse-duration}, and to parse intervals, there's

+@code{iso8601-parse-interval}. All these functions return decoded

+time structures, except the final one, which returns three of them

+(the start, the end, and the duration).

+@end defun

+

+This stands for the ISO 8601 date format, which is like

+@samp{%+4Y-%m-%d} except that any flags or field width override the

+@samp{+} and (after subtracting 6) the @samp{4}.

+@samp{0} pads with zeros, @samp{+} pads with zeros and also puts

+@samp{+} before nonnegative year numbers with more than four digits,

+@samp{_} pads with blanks, @samp{-}

+This function returns the processor run time used by Emacs, as a Lisp

+timestamp (@pxref{Time of Day}).

+(@pxref{Time of Day}). As with any time value, a value of

+@code{nil} for any of their

+number stands for the number of seconds since the epoch.

+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.

+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

+However, the result is a float if either argument is a float infinity or NaN@.

+as a time value that is often just a single number of elapsed seconds.

+@defun date-days-in-month year month

+Return the number of days in @var{month} in @var{year}. For instance,

+there's 29 days in February 2004.

+@end defun

+

+@defun date-ordinal-to-time year ordinal

+Return the date of @var{ordinal} in @var{year} as a decoded time

+structure. For instance, the 120th day in 2004 is April 29th.

+@end defun

+

+been idle, using the same format as

+@defun recent-keys &optional include-cmds

+If @var{include-cmds} is non-@code{nil}, complete key sequences in the

+result vector are interleaved with pseudo-events of the form

+@code{(nil . @var{COMMAND})}, where @var{COMMAND} is the binding of

+the key sequence (@pxref{Command Overview}).

+

+* Archive Web Server:: Interfacing to an archive web server.

+@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

+installed, and then calls @code{package-activate-all}.

+making them available.

+file is used as the long description (overriding any @samp{;;;

+Commentary:} section).

+reachable via HTTP, this directory must be accessible to a web server;

+@xref{Archive Web Server}.

+

+@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

+@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

+

+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.

+Some file name handlers may not support all combinations and forms of the

+some file name handlers might behave as if @var{display} were @code{nil},

+file name handlers might not support separating standard output and error

+If a file name handler is invoked, it determines the program to run based

+The second argument @var{infile} may invoke a file name handler. The file

+name handler could be different from the handler chosen for the

+remote host. When set to @code{nil}, a file name handler could optimize

+If provided, @var{stopped} must be @code{nil}; it is an error to use

+any non-@code{nil} value. The @code{:stop} key is ignored otherwise

+and is retained for compatibility with other process types such as

+pipe processes. Asynchronous subprocesses never start in the stopped

+state.

+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}.

+

+@cindex standard error process

+If @var{stderr} is a buffer, Emacs will create a pipe process, the

+@dfn{standard error process}. This process will have the default

+filter (@pxref{Filter Functions}), sentinel (@pxref{Sentinels}), and

+coding systems (@pxref{Default Coding Systems}). On the other hand,

+it will use @var{query-flag} as its query-on-exit flag (@pxref{Query

+Before Exit}). It will be associated with the @var{stderr} buffer

+(@pxref{Process Buffers}) and send its output (which is the standard

+error of the main process) there.

+

+If @var{stderr} is a pipe process, Emacs will use it as standard error

+process for the new process.

+

+@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}.

+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. The @code{:stderr} argument cannot be a pipe process,

+file name handlers do not support pipe processes for this. A buffer

+as @code{:stderr} argument is accepted, its contents is shown without

+the use of pipe processes. @xref{Filter Functions}, @ref{Sentinels},

+and @ref{Accepting Output}.

+

+Some file name handlers may not support @code{make-process}. In such

+cases, this function does nothing and returns @code{nil}.

+invoke a file name handler based on the value of @code{default-directory}.

+Depending on the implementation of the file name handler, it might not be

+Some file name handlers may not support @code{start-file-process} (for

+@ref{Lisp and Coding Systems, inhibit-nul-byte-detection}, for how to

+If you have passed a non-@code{nil} @var{stderr} to

+@code{make-process}, it will have a standard error process.

+@xref{Asynchronous Processes}. In that case, waiting for process

+output from the main process doesn't wait for output from the standard

+error process. To make sure you have received both all of standard

+output and all of standard error from a process, use the following

+code:

+

+@example

+(while (accept-process-output process))

+(while (accept-process-output stderr-process))

+@end example

+

+Reading pending standard error from a process running on a remote host

+is not possible this way.

+

+application's code. The corresponding @var{value} is a Lisp

+timestamp (@pxref{Time of Day}).

+processing system calls. The corresponding @var{value} is a Lisp

+timestamp.

+@var{value} is a Lisp timestamp.

+The time when the process was started, as a Lisp timestamp.

+The time elapsed since the process started, as a Lisp timestamp.

+connecting to that address will be accepted. When using @code{local},

+by default IPv4 will be used, specify a @var{family} of @code{ipv6} to

+override this.

+filter are multibyte, otherwise they are unibyte. The default is @code{t}.

+@deffn Command serial-term port speed &optional line-mode

+If @var{line-mode} is non-@code{nil}, @code{term-line-mode} is used;

+otherwise @code{term-raw-mode} is used.

+@ifnottex

+* Rx Notation:: An alternative, structured regexp notation.

+@end ifnottex

+@anchor{Non-greedy repetition}

+A character alternative can also specify named character classes

+(@pxref{Char Classes}). This is a POSIX feature. For example,

+@samp{[[:ascii:]]} matches any @acronym{ASCII} character.

+Using a character class is equivalent to mentioning each of the

+characters in that class; but the latter is not feasible in practice,

+since some classes include thousands of different characters.

+A character class should not appear as the lower or upper bound

+of a range.

+

+special: @samp{]}, @samp{-} and @samp{^}.

+To include @samp{]} in a character alternative, put it at the

+beginning. To include @samp{^}, put it anywhere but at the beginning.

+To include @samp{-}, put it at the end. Thus, @samp{[]^-]} matches

+all three of these special characters. You cannot use @samp{\} to

+escape these three characters, since @samp{\} is not special here.

+range is empty and represents no characters. Thus, @samp{[z-a]}

+always fails to match, and @samp{[^z-a]} matches any character,

+including newline. However, a reversed range should always be from

+the letter @samp{z} to the letter @samp{a} to make it clear that it is

+not a typo; for example, @samp{[+-*/]} should be avoided, because it

+matches only @samp{/} rather than the likely-intended four characters.

+Some kinds of character alternatives are not the best style even

+though they have a well-defined meaning in Emacs. They include:

+

+@enumerate

+@item

+Although a range's bound can be almost any character, it is better

+style to stay within natural sequences of ASCII letters and digits

+because most people have not memorized character code tables.

+For example, @samp{[.-9]} is less clear than @samp{[./0-9]},

+and @samp{[`-~]} is less clear than @samp{[`a-z@{|@}~]}.

+Unicode character escapes can help here; for example, for most programmers

+@samp{[ก-ฺ฿-๛]} is less clear than @samp{[\u0E01-\u0E3A\u0E3F-\u0E5B]}.

+

+@item

+Although a character alternative can include duplicates, it is better

+style to avoid them. For example, @samp{[XYa-yYb-zX]} is less clear

+than @samp{[XYa-z]}.

+

+@item

+Although a range can denote just one, two, or three characters, it

+is simpler to list the characters. For example,

+@samp{[a-a0]} is less clear than @samp{[a0]}, @samp{[i-j]} is less clear

+than @samp{[ij]}, and @samp{[i-k]} is less clear than @samp{[ijk]}.

+

+@item

+Although a @samp{-} can appear at the beginning of a character

+alternative or as the upper bound of a range, it is better style to

+put @samp{-} by itself at the end of a character alternative. For

+example, although @samp{[-a-z]} is valid, @samp{[a-z-]} is better

+style; and although @samp{[*--]} is valid, @samp{[*+,-]} is clearer.

+@end enumerate

+@samp{[^a-z0-9A-Z]} matches all characters @emph{except} ASCII letters and

+@cindex ascii character class, regexp

+@cindex alnum character class, regexp

+@cindex alpha character class, regexp

+@cindex xdigit character class, regexp

+This matches any character whose code is in the range 0--31.

+2**16 @minus{} 1

+@math{2^{16}-1}

+@ifnottex

+In the @code{rx} notation (@pxref{Rx Notation}), the regexp could be written

+

+@example

+@group

+(rx (any ".?!") ; Punctuation ending sentence.

+ (zero-or-more (any "\"')]@}")) ; Closing quotes or brackets.

+ (or line-end

+ (seq " " line-end)

+ "\t"

+ " ") ; Two spaces.

+ (zero-or-more (any "\t\n "))) ; Optional extra whitespace.

+@end group

+@end example

+

+Since @code{rx} regexps are just S-expressions, they can be formatted

+and commented as such.

+@end ifnottex

+

+@ifnottex

+@node Rx Notation

+@subsection The @code{rx} Structured Regexp Notation

+@cindex rx

+@cindex regexp syntax

+

+ As an alternative to the string-based syntax, Emacs provides the

+structured @code{rx} notation based on Lisp S-expressions. This

+notation is usually easier to read, write and maintain than regexp

+strings, and can be indented and commented freely. It requires a

+conversion into string form since that is what regexp functions

+expect, but that conversion typically takes place during

+byte-compilation rather than when the Lisp code using the regexp is

+run.

+

+ Here is an @code{rx} regexp@footnote{It could be written much

+simpler with non-greedy operators (how?), but that would make the

+example less interesting.} that matches a block comment in the C

+programming language:

+

+@example

+@group

+(rx "/*" ; Initial /*

+ (zero-or-more

+ (or (not (any "*")) ; Either non-*,

+ (seq "*" ; or * followed by

+ (not (any "/"))))) ; non-/

+ (one-or-more "*") ; At least one star,

+ "/") ; and the final /

+@end group

+@end example

+

+@noindent

+or, using shorter synonyms and written more compactly,

+

+@example

+@group

+(rx "/*"

+ (* (| (not (any "*"))

+ (: "*" (not (any "/")))))

+ (+ "*") "/")

+@end group

+@end example

+

+@noindent

+In conventional string syntax, it would be written

+

+@example

+"/\\*\\(?:[^*]\\|\\*[^/]\\)*\\*+/"

+@end example

+

+The @code{rx} notation is mainly useful in Lisp code; it cannot be

+used in most interactive situations where a regexp is requested, such

+as when running @code{query-replace-regexp} or in variable

+customisation.

+

+@menu

+* Rx Constructs:: Constructs valid in rx forms.

+* Rx Functions:: Functions and macros that use rx forms.

+@end menu

+

+@node Rx Constructs

+@subsubsection Constructs in @code{rx} regexps

+

+The various forms in @code{rx} regexps are described below. The

+shorthand @var{rx} represents any @code{rx} form, and @var{rx}@dots{}

+means one or more @code{rx} forms. Where the corresponding string

+regexp syntax is given, @var{A}, @var{B}, @dots{} are string regexp

+subexpressions.

+@c With the new implementation of rx, this can be changed from

+@c 'one or more' to 'zero or more'.

+

+@subsubheading Literals

+

+@table @asis

+@item @code{"some-string"}

+Match the string @samp{some-string} literally. There are no

+characters with special meaning, unlike in string regexps.

+

+@item @code{?C}

+Match the character @samp{C} literally.

+@end table

+

+@subsubheading Sequence and alternative

+

+@table @asis

+@item @code{(seq @var{rx}@dots{})}

+@cindex @code{seq} in rx

+@itemx @code{(sequence @var{rx}@dots{})}

+@cindex @code{sequence} in rx

+@itemx @code{(: @var{rx}@dots{})}

+@cindex @code{:} in rx

+@itemx @code{(and @var{rx}@dots{})}

+@cindex @code{and} in rx

+Match the @var{rx}s in sequence. Without arguments, the expression

+matches the empty string.@*

+Corresponding string regexp: @samp{@var{A}@var{B}@dots{}}

+(subexpressions in sequence).

+

+@item @code{(or @var{rx}@dots{})}

+@cindex @code{or} in rx

+@itemx @code{(| @var{rx}@dots{})}

+@cindex @code{|} in rx

+Match exactly one of the @var{rx}s, trying from left to right.

+Without arguments, the expression will not match anything at all.@*

+Corresponding string regexp: @samp{@var{A}\|@var{B}\|@dots{}}.

+@end table

+

+@subsubheading Repetition

+

+Normally, repetition forms are greedy, in that they attempt to match

+as many times as possible. Some forms are non-greedy; they try to

+match as few times as possible (@pxref{Non-greedy repetition}).

+

+@table @code

+@item (zero-or-more @var{rx}@dots{})

+@cindex @code{zero-or-more} in rx

+@itemx (0+ @var{rx}@dots{})

+@cindex @code{0+} in rx

+Match the @var{rx}s zero or more times. Greedy by default.@*

+Corresponding string regexp: @samp{@var{A}*} (greedy),

+@samp{@var{A}*?} (non-greedy)

+

+@item (one-or-more @var{rx}@dots{})

+@cindex @code{one-or-more} in rx

+@itemx (1+ @var{rx}@dots{})

+@cindex @code{1+} in rx

+Match the @var{rx}s one or more times. Greedy by default.@*

+Corresponding string regexp: @samp{@var{A}+} (greedy),

+@samp{@var{A}+?} (non-greedy)

+

+@item (zero-or-one @var{rx}@dots{})

+@cindex @code{zero-or-one} in rx

+@itemx (optional @var{rx}@dots{})

+@cindex @code{optional} in rx

+@itemx (opt @var{rx}@dots{})

+@cindex @code{opt} in rx

+Match the @var{rx}s once or an empty string. Greedy by default.@*

+Corresponding string regexp: @samp{@var{A}?} (greedy),

+@samp{@var{A}??} (non-greedy).

+

+@item (* @var{rx}@dots{})

+@cindex @code{*} in rx

+Match the @var{rx}s zero or more times. Greedy.@*

+Corresponding string regexp: @samp{@var{A}*}

+

+@item (+ @var{rx}@dots{})

+@cindex @code{+} in rx

+Match the @var{rx}s one or more times. Greedy.@*

+Corresponding string regexp: @samp{@var{A}+}

+

+@item (? @var{rx}@dots{})

+@cindex @code{?} in rx

+Match the @var{rx}s once or an empty string. Greedy.@*

+Corresponding string regexp: @samp{@var{A}?}

+

+@item (*? @var{rx}@dots{})

+@cindex @code{*?} in rx

+Match the @var{rx}s zero or more times. Non-greedy.@*

+Corresponding string regexp: @samp{@var{A}*?}

+

+@item (+? @var{rx}@dots{})

+@cindex @code{+?} in rx

+Match the @var{rx}s one or more times. Non-greedy.@*

+Corresponding string regexp: @samp{@var{A}+?}

+

+@item (?? @var{rx}@dots{})

+@cindex @code{??} in rx

+Match the @var{rx}s or an empty string. Non-greedy.@*

+Corresponding string regexp: @samp{@var{A}??}

+

+@item (= @var{n} @var{rx}@dots{})

+@cindex @code{=} in rx

+@itemx (repeat @var{n} @var{rx})

+Match the @var{rx}s exactly @var{n} times.@*

+Corresponding string regexp: @samp{@var{A}\@{@var{n}\@}}

+

+@item (>= @var{n} @var{rx}@dots{})

+@cindex @code{>=} in rx

+Match the @var{rx}s @var{n} or more times. Greedy.@*

+Corresponding string regexp: @samp{@var{A}\@{@var{n},\@}}

+

+@item (** @var{n} @var{m} @var{rx}@dots{})

+@cindex @code{**} in rx

+@itemx (repeat @var{n} @var{m} @var{rx}@dots{})

+@cindex @code{repeat} in rx

+Match the @var{rx}s at least @var{n} but no more than @var{m} times. Greedy.@*

+Corresponding string regexp: @samp{@var{A}\@{@var{n},@var{m}\@}}

+@end table

+

+The greediness of some repetition forms can be controlled using the

+following constructs. However, it is usually better to use the

+explicit non-greedy forms above when such matching is required.

+

+@table @code

+@item (minimal-match @var{rx})

+@cindex @code{minimal-match} in rx

+Match @var{rx}, with @code{zero-or-more}, @code{0+},

+@code{one-or-more}, @code{1+}, @code{zero-or-one}, @code{opt} and

+@code{option} using non-greedy matching.

+

+@item (maximal-match @var{rx})

+@cindex @code{maximal-match} in rx

+Match @var{rx}, with @code{zero-or-more}, @code{0+},

+@code{one-or-more}, @code{1+}, @code{zero-or-one}, @code{opt} and

+@code{option} using non-greedy matching. This is the default.

+@end table

+

+@subsubheading Matching single characters

+

+@table @asis

+@item @code{(any @var{set}@dots{})}

+@cindex @code{any} in rx

+@itemx @code{(char @var{set}@dots{})}

+@cindex @code{char} in rx

+@itemx @code{(in @var{set}@dots{})}

+@cindex @code{in} in rx

+@cindex character class in rx

+Match a single character from one of the @var{set}s. Each @var{set}

+is a character, a string representing the set of its characters, a

+range or a character class (see below). A range is either a

+hyphen-separated string like @code{"A-Z"}, or a cons of characters

+like @code{(?A . ?Z)}.

+

+Note that hyphen (@code{-}) is special in strings in this construct,

+since it acts as a range separator. To include a hyphen, add it as a

+separate character or single-character string.@*

+Corresponding string regexp: @samp{[@dots{}]}

+

+@item @code{(not @var{charspec})}

+@cindex @code{not} in rx

+Match a character not included in @var{charspec}. @var{charspec} can

+be an @code{any}, @code{syntax} or @code{category} form, or a

+character class.@*

+Corresponding string regexp: @samp{[^@dots{}]}, @samp{\S@var{code}},

+@samp{\C@var{code}}

+

+@item @code{not-newline}, @code{nonl}

+@cindex @code{not-newline} in rx

+@cindex @code{nonl} in rx

+Match any character except a newline.@*

+Corresponding string regexp: @samp{.} (dot)

+

+@item @code{anything}

+@cindex @code{anything} in rx

+Match any character.@*

+Corresponding string regexp: @samp{.\|\n} (for example)

+

+@item character class

+@cindex character class in rx

+Match a character from a named character class:

+

+@table @asis

+@item @code{alpha}, @code{alphabetic}, @code{letter}

+Match alphabetic characters. More precisely, match characters whose

+Unicode @samp{general-category} property indicates that they are

+alphabetic.

+

+@item @code{alnum}, @code{alphanumeric}

+Match alphabetic characters and digits. More precisely, match

+characters whose Unicode @samp{general-category} property indicates

+that they are alphabetic or decimal digits.

+

+@item @code{digit}, @code{numeric}, @code{num}

+Match the digits @samp{0}--@samp{9}.

+

+@item @code{xdigit}, @code{hex-digit}, @code{hex}

+Match the hexadecimal digits @samp{0}--@samp{9}, @samp{A}--@samp{F}

+and @samp{a}--@samp{f}.

+

+@item @code{cntrl}, @code{control}

+Match any character whose code is in the range 0--31.

+

+@item @code{blank}

+Match horizontal whitespace. More precisely, match characters whose

+Unicode @samp{general-category} property indicates that they are

+spacing separators.

+

+@item @code{space}, @code{whitespace}, @code{white}

+Match any character that has whitespace syntax

+(@pxref{Syntax Class Table}).

+

+@item @code{lower}, @code{lower-case}

+Match anything lower-case, as determined by the current case table.

+If @code{case-fold-search} is non-nil, this also matches any

+upper-case letter.

+

+@item @code{upper}, @code{upper-case}

+Match anything upper-case, as determined by the current case table.

+If @code{case-fold-search} is non-nil, this also matches any

+lower-case letter.

+

+@item @code{graph}, @code{graphic}

+Match any character except whitespace, @acronym{ASCII} and

+non-@acronym{ASCII} control characters, surrogates, and codepoints

+unassigned by Unicode, as indicated by the Unicode

+@samp{general-category} property.

+

+@item @code{print}, @code{printing}

+Match whitespace or a character matched by @code{graph}.

+

+@item @code{punct}, @code{punctuation}

+Match any punctuation character. (At present, for multibyte

+characters, anything that has non-word syntax.)

+

+@item @code{word}, @code{wordchar}

+Match any character that has word syntax (@pxref{Syntax Class Table}).

+

+@item @code{ascii}

+Match any @acronym{ASCII} character (codes 0--127).

+

+@item @code{nonascii}

+Match any non-@acronym{ASCII} character (but not raw bytes).

+@end table

+

+Corresponding string regexp: @samp{[[:@var{class}:]]}

+

+@item @code{(syntax @var{syntax})}

+@cindex @code{syntax} in rx

+Match a character with syntax @var{syntax}, being one of the following

+names:

+

+@multitable {@code{close-parenthesis}} {Syntax character}

+@headitem Syntax name @tab Syntax character

+@item @code{whitespace} @tab @code{-}

+@item @code{punctuation} @tab @code{.}

+@item @code{word} @tab @code{w}

+@item @code{symbol} @tab @code{_}

+@item @code{open-parenthesis} @tab @code{(}

+@item @code{close-parenthesis} @tab @code{)}

+@item @code{expression-prefix} @tab @code{'}

+@item @code{string-quote} @tab @code{"}

+@item @code{paired-delimiter} @tab @code{$}

+@item @code{escape} @tab @code{\}

+@item @code{character-quote} @tab @code{/}

+@item @code{comment-start} @tab @code{<}

+@item @code{comment-end} @tab @code{>}

+@item @code{string-delimiter} @tab @code{|}

+@item @code{comment-delimiter} @tab @code{!}

+@end multitable

+

+For details, @pxref{Syntax Class Table}. Please note that

+@code{(syntax punctuation)} is @emph{not} equivalent to the character class

+@code{punctuation}.@*

+Corresponding string regexp: @samp{\s@var{code}}

+

+@item @code{(category @var{category})}

+@cindex @code{category} in rx

+Match a character in category @var{category}, which is either one of

+the names below or its category character.

+

+@multitable {@code{vowel-modifying-diacritical-mark}} {Category character}

+@headitem Category name @tab Category character

+@item @code{space-for-indent} @tab space

+@item @code{base} @tab @code{.}

+@item @code{consonant} @tab @code{0}

+@item @code{base-vowel} @tab @code{1}

+@item @code{upper-diacritical-mark} @tab @code{2}

+@item @code{lower-diacritical-mark} @tab @code{3}

+@item @code{tone-mark} @tab @code{4}

+@item @code{symbol} @tab @code{5}

+@item @code{digit} @tab @code{6}

+@item @code{vowel-modifying-diacritical-mark} @tab @code{7}

+@item @code{vowel-sign} @tab @code{8}

+@item @code{semivowel-lower} @tab @code{9}

+@item @code{not-at-end-of-line} @tab @code{<}

+@item @code{not-at-beginning-of-line} @tab @code{>}

+@item @code{alpha-numeric-two-byte} @tab @code{A}

+@item @code{chinese-two-byte} @tab @code{C}

+@item @code{greek-two-byte} @tab @code{G}

+@item @code{japanese-hiragana-two-byte} @tab @code{H}

+@item @code{indian-two-byte} @tab @code{I}

+@item @code{japanese-katakana-two-byte} @tab @code{K}

+@item @code{strong-left-to-right} @tab @code{L}

+@item @code{korean-hangul-two-byte} @tab @code{N}

+@item @code{strong-right-to-left} @tab @code{R}

+@item @code{cyrillic-two-byte} @tab @code{Y}

+@item @code{combining-diacritic} @tab @code{^}

+@item @code{ascii} @tab @code{a}

+@item @code{arabic} @tab @code{b}

+@item @code{chinese} @tab @code{c}

+@item @code{ethiopic} @tab @code{e}

+@item @code{greek} @tab @code{g}

+@item @code{korean} @tab @code{h}

+@item @code{indian} @tab @code{i}

+@item @code{japanese} @tab @code{j}

+@item @code{japanese-katakana} @tab @code{k}

+@item @code{latin} @tab @code{l}

+@item @code{lao} @tab @code{o}

+@item @code{tibetan} @tab @code{q}

+@item @code{japanese-roman} @tab @code{r}

+@item @code{thai} @tab @code{t}

+@item @code{vietnamese} @tab @code{v}

+@item @code{hebrew} @tab @code{w}

+@item @code{cyrillic} @tab @code{y}

+@item @code{can-break} @tab @code{|}

+@end multitable

+

+For more information about currently defined categories, run the

+command @kbd{M-x describe-categories @key{RET}}. For how to define

+new categories, @pxref{Categories}.@*

+Corresponding string regexp: @samp{\c@var{code}}

+@end table

+

+@subsubheading Zero-width assertions

+

+These all match the empty string, but only in specific places.

+

+@table @asis

+@item @code{line-start}, @code{bol}

+@cindex @code{line-start} in rx

+@cindex @code{bol} in rx

+Match at the beginning of a line.@*

+Corresponding string regexp: @samp{^}

+

+@item @code{line-end}, @code{eol}

+@cindex @code{line-end} in rx

+@cindex @code{eol} in rx

+Match at the end of a line.@*

+Corresponding string regexp: @samp{$}

+

+@item @code{string-start}, @code{bos}, @code{buffer-start}, @code{bot}

+@cindex @code{string-start} in rx

+@cindex @code{bos} in rx

+@cindex @code{buffer-start} in rx

+@cindex @code{bot} in rx

+Match at the start of the string or buffer being matched against.@*

+Corresponding string regexp: @samp{\`}

+

+@item @code{string-end}, @code{eos}, @code{buffer-end}, @code{eot}

+@cindex @code{string-end} in rx

+@cindex @code{eos} in rx

+@cindex @code{buffer-end} in rx

+@cindex @code{eot} in rx

+Match at the end of the string or buffer being matched against.@*

+Corresponding string regexp: @samp{\'}

+

+@item @code{point}

+@cindex @code{point} in rx

+Match at point.@*

+Corresponding string regexp: @samp{\=}

+

+@item @code{word-start}

+@cindex @code{word-start} in rx

+Match at the beginning of a word.@*

+Corresponding string regexp: @samp{\<}

+

+@item @code{word-end}

+@cindex @code{word-end} in rx

+Match at the end of a word.@*

+Corresponding string regexp: @samp{\>}

+

+@item @code{word-boundary}

+@cindex @code{word-boundary} in rx

+Match at the beginning or end of a word.@*

+Corresponding string regexp: @samp{\b}

+

+@item @code{not-word-boundary}

+@cindex @code{not-word-boundary} in rx

+Match anywhere but at the beginning or end of a word.@*

+Corresponding string regexp: @samp{\B}

+

+@item @code{symbol-start}

+@cindex @code{symbol-start} in rx

+Match at the beginning of a symbol.@*

+Corresponding string regexp: @samp{\_<}

+

+@item @code{symbol-end}

+@cindex @code{symbol-end} in rx

+Match at the end of a symbol.@*

+Corresponding string regexp: @samp{\_>}

+@end table

+

+@subsubheading Capture groups

+

+@table @code

+@item (group @var{rx}@dots{})

+@cindex @code{group} in rx

+@itemx (submatch @var{rx}@dots{})

+@cindex @code{submatch} in rx

+Match the @var{rx}s, making the matched text and position accessible

+in the match data. The first group in a regexp is numbered 1;

+subsequent groups will be numbered one higher than the previous

+group.@*

+Corresponding string regexp: @samp{\(@dots{}\)}

+

+@item (group-n @var{n} @var{rx}@dots{})

+@cindex @code{group-n} in rx

+@itemx (submatch-n @var{n} @var{rx}@dots{})

+@cindex @code{submatch-n} in rx

+Like @code{group}, but explicitly assign the group number @var{n}.

+@var{n} must be positive.@*

+Corresponding string regexp: @samp{\(?@var{n}:@dots{}\)}

+

+@item (backref @var{n})

+@cindex @code{backref} in rx

+Match the text previously matched by group number @var{n}.

+@var{n} must be in the range 1--9.@*

+Corresponding string regexp: @samp{\@var{n}}

+@end table

+

+@subsubheading Dynamic inclusion

+

+@table @code

+@item (literal @var{expr})

+@cindex @code{literal} in rx

+Match the literal string that is the result from evaluating the Lisp

+expression @var{expr}. The evaluation takes place at call time, in

+the current lexical environment.

+

+@item (regexp @var{expr})

+@cindex @code{regexp} in rx

+@itemx (regex @var{expr})

+@cindex @code{regex} in rx

+Match the string regexp that is the result from evaluating the Lisp

+expression @var{expr}. The evaluation takes place at call time, in

+the current lexical environment.

+

+@item (eval @var{expr})

+@cindex @code{eval} in rx

+Match the rx form that is the result from evaluating the Lisp

+expression @var{expr}. The evaluation takes place at macro-expansion

+time for @code{rx}, at call time for @code{rx-to-string},

+in the current global environment.

+@end table

+

+@node Rx Functions

+@subsubsection Functions and macros using @code{rx} regexps

+

+@defmac rx rx-expr@dots{}

+Translate the @var{rx-expr}s to a string regexp, as if they were the

+body of a @code{(seq @dots{})} form. The @code{rx} macro expands to a

+string constant, or, if @code{literal} or @code{regexp} forms are

+used, a Lisp expression that evaluates to a string.

+@end defmac

+

+@defun rx-to-string rx-expr &optional no-group

+Translate @var{rx-expr} to a string regexp which is returned.

+If @var{no-group} is absent or nil, bracket the result in a

+non-capturing group, @samp{\(?:@dots{}\)}, if necessary to ensure that

+a postfix operator appended to it will apply to the whole expression.

+

+Arguments to @code{literal} and @code{regexp} forms in @var{rx-expr}

+must be string literals.

+@end defun

+

+The @code{pcase} macro can use @code{rx} expressions as patterns

+directly; @pxref{rx in pcase}.

+@end ifnottex

+

+@defun regexp-opt strings &optional paren keep-order

+If @var{strings} is the empty list, the return value is a regexp that

+never matches anything.

+

+The optional argument @var{keep-order}, if @code{nil} or omitted,

+allows the returned regexp to match the strings in any order. If

+non-@code{nil}, the match is guaranteed to be performed in the order

+given, as if the strings were made into a regexp by joining them with

+the @samp{\|} operator.

+

+Up to reordering, the resulting regexp of @code{regexp-opt} is

+equivalent to but usually more efficient than that of a simplified

+version:

+@defvar regexp-unmatchable

+This variable contains a regexp that is guaranteed not to match any

+string at all. It is particularly useful as default value for

+variables that may be set to a pattern that actually matches

+something.

+@end defvar

+

+matches starts at that index in @var{string}, and the returned value

+does not include the first @var{start} characters of @var{string}.

+To get the whole transformed string, concatenate the first

+@var{start} characters of @var{string} with the return value.

+@defun seq-contains-p sequence elt &optional function

+ This function returns non-@code{nil} if at least one element in

+@var{sequence} is equal to @var{elt}. If the optional argument

+@var{function} is non-@code{nil}, it is a function of two arguments to

+use instead of the default @code{equal}.

+ @result{} [1 two '(three) "four" [five]]

+ @result{} [1 two '(three) "four" [five]]

+ @result{} [1 two '(three) "four" [five]]

+ @result{} (1 two '(three) "four" [five])

+@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

+

+@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

+

+@defun make-string count character &optional multibyte

+ 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.

+

+@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

+

+integer. Negative integers are formatted in a platform-dependent

+way. The object can also be a floating-point number that is formatted

+as an integer, dropping any fraction.

+integer. The object can also be a floating-point number that is

+formatted as an integer, dropping any fraction.

+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 floating-point number that is

+formatted as an integer, dropping any fraction.

+ The flag @samp{+} inserts a plus sign before a nonnegative number, so

+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

+with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes nonzero results

+@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}.

+

+@defun syntax-ppss-context state

+Return @code{string} if @var{state} is a string and @code{comment} if

+it's a comment.

+@end defun

+

+@samp{1} @tab @code{(ash 1 16)} @tab @samp{p} @tab @code{(ash 1 20)}

+@samp{2} @tab @code{(ash 1 17)} @tab @samp{b} @tab @code{(ash 1 21)}

+@samp{3} @tab @code{(ash 1 18)} @tab @samp{n} @tab @code{(ash 1 22)}

+@samp{4} @tab @code{(ash 1 19)} @tab @samp{c} @tab @code{(ash 1 23)}

+* Interpolated Strings:: Formatting Customizable Strings.

+* Parsing JSON:: Parsing and generating JSON values.

+* JSONRPC:: JSON Remote Procedure Call protocol

+@deffn Command self-insert-command count &optional char

+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.

+@deffn Command delete-indentation &optional join-following-p beg end

+instead. Otherwise, if @var{beg} and @var{end} are non-@code{nil},

+this function joins all lines in the region they define.

+

+In an interactive call, @var{join-following-p} is the prefix argument,

+and @var{beg} and @var{end} are, respectively, the start and end of

+the region if it is active, else @code{nil}. The function returns

+@code{nil}.

+modified. A @var{time-flag} that is a non-integer Lisp timestamp

+represents the visited file's modification time as of

+

+This function can be called before an amalgamating command. It

+removes the previous @code{undo-boundary} if a series of such calls

+have been made.

+from 1. Passing a buffer other than the current buffer may be slow.

+@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

+

+

+

+@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.

+Unlike with other similar hooks, when Emacs calls these functions,

+@code{inhibit-modification-hooks} does @emph{not} get bound to

+non-@code{nil}. If the functions modify the buffer, you should

+consider binding this variable to non-@code{nil} to prevent any buffer

+changes running the change hooks. Otherwise, you must be prepared for

+recursive calls. @xref{Change Hooks}.

+When these functions are called, @code{inhibit-modification-hooks} is

+bound to non-@code{nil}. If the functions modify the buffer, you

+might want to bind @code{inhibit-modification-hooks} to @code{nil}, so

+as to cause the change hooks to run for these modifications. However,

+doing this may call your own change hook recursively, so be sure to

+prepare for that.

+

+@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

+

+@deffn Command replace-buffer-contents source &optional max-secs max-costs

+accessible portion of the @var{source} buffer.

+

+This function attempts to keep point, markers, text properties, and

+overlays in the current buffer intact. One potential case where this

+behavior is useful is external code formatting programs: they

+typically write the reformatted text into a temporary buffer or file,

+and using @code{delete-region} and @code{insert-buffer-substring}

+would destroy these properties. However, the latter combination is

+typically faster (@xref{Deletion}, and @ref{Insertion}).

+

+For its working, @code{replace-buffer-contents} needs to compare the

+contents of the original buffer with that of @code{source} which is a

+costly operation if the buffers are huge and there is a high number of

+differences between them. In order to keep

+@code{replace-buffer-contents}'s runtime in bounds, it has two

+optional arguments.

+

+@code{max-secs} defines a hard boundary in terms of seconds. If given

+and exceeded, it will fall back to @code{delete-region} and

+@code{insert-buffer-substring}.

+

+@code{max-costs} defines the quality of the difference computation.

+If the actual costs exceed this limit, heuristics are used to provide

+a faster but suboptimal solution. The default value is 1000000.

+

+@code{replace-buffer-contents} returns t if a non-destructive

+replacement could be performed. Otherwise, i.e., if @code{max-secs}

+was exceeded, it returns nil.

+@defun replace-region-contents beg end replace-fn &optional max-secs max-costs

+This function replaces the region between @code{beg} and @code{end}

+using the given @code{replace-fn}. The function @code{replace-fn} is

+run in the current buffer narrowed to the specified region and it

+should return either a string or a buffer replacing the region.

+

+The replacement is performed using @code{replace-buffer-contents} (see

+above) which also describes the @code{max-secs} and @code{max-costs}

+arguments and the return value.

+

+Note: If the replacement is a string, it will be placed in a temporary

+buffer so that @code{replace-buffer-contents} can operate on it.

+Therefore, if you already have the replacement in a buffer, it makes

+no sense to convert it to a string using @code{buffer-substring} or

+similar.

+@end defun

+

+@defun zlib-decompress-region start end &optional allow-partial

+data. If @var{allow-partial} is @code{nil} or omitted, then on

+failure, the function leaves the region unchanged and returns

+@code{nil}. Otherwise, it returns the number of bytes that were not

+decompressed and replaces the region text by whatever data was

+successfully decompressed. This function can be called only in

+unibyte buffers.

+}2045 and also in RFC 4648. This section describes the functions for

+@deffn Command base64url-encode-region beg end &optional no-pad

+This function is like @code{base64-encode-region}, but it implements

+the URL variant of base 64 encoding, per RFC 4648, and it doesn't

+insert newline characters into the encoded text, so the output is

+just one long line.

+

+If the optional argument @var{no-pad} is non-@code{nil} then this

+function doesn't generate the padding (@code{=}).

+@end deffn

+

+@defun base64url-encode-string string &optional no-pad

+Like @code{base64-encode-string}, but generates the URL variant of

+base 64, and doesn't insert newline characters into the encoded text,

+so the result is just one long line.

+

+If the optional argument @var{no-pad} is non-@code{nil} then this

+function doesn't generate the padding.

+@end defun

+

+@deffn Command base64-decode-region beg end &optional base64url

+

+If optional argument @var{base64url} is is non-@code{nil}, then padding

+is optional, and the URL variant of base 64 encoding is used.

+@defun base64-decode-string string &optional base64url

+

+

+If optional argument @var{base64url} is is non-@code{nil}, then padding

+is optional, and the URL variant of base 64 encoding is used.

+@end defun

+

+

+@node Interpolated Strings

+@section Formatting Customizable Strings

+

+It is, in some circumstances, useful to present users with a string to

+be customized that can then be expanded programmatically. For

+instance, @code{erc-header-line-format} is @code{"%n on %t (%m,%l)

+%o"}, and each of those characters after the percent signs are

+expanded when the header line is computed. To do this, the

+@code{format-spec} function is used:

+

+@defun format-spec format specification &optional only-present

+@var{format} is the format specification string as in the example

+above. @var{specification} is an alist that has elements where the

+@code{car} is a character and the @code{cdr} is the substitution.

+

+If @code{ONLY-PRESENT} is @code{nil}, errors will be signalled if a

+format character has been used that's not present in

+@var{specification}. If it's non-@code{nil}, that format

+specification is left verbatim in the result.

+Here's a trivial example:

+

+@example

+(format-spec "su - %u %l"

+ `((?u . ,(user-login-name))

+ (?l . "ls")))

+ @result{} "su - foo ls"

+@end example

+

+In addition to allowing padding/limiting to a certain length, the

+following modifiers can be used:

+

+@table @asis

+@item @samp{0}

+Use zero padding.

+

+@item @samp{@ }

+User space padding.

+

+@item @samp{-}

+Pad to the right.

+

+@item @samp{^}

+Use upper case.

+

+@item @samp{_}

+Use lower case.

+

+@item @samp{<}

+If the length needs to limited, remove characters from the left.

+

+@item @samp{>}

+Same as previous, but remove characters from the right.

+@end table

+

+If contradictory modifiers are used (for instance, both upper and

+lower case), then what happens is undefined.

+

+As an example, @samp{"%<010b"} means ``insert the @samp{b} expansion,

+but pad with leading zeroes if it's less than ten characters, and if

+it's more than ten characters, shorten by removing characters from the

+left''.

+

+

+ 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 inputs to GnuTLS cryptographic functions can be specified in

+ 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.

+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.)

+ 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

+@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. If @var{string} doesn't contain a valid JSON object,

+this function signals the @code{json-parse-error} error.

+

+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 :array-type

+The value decides which Lisp object to use for representing a JSON

+array. It can be either @code{array}, the default, to use Lisp

+arrays; or @code{list} to use lists.

+

+@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 contains a valid JSON object; otherwise it signals the

+@code{json-parse-error} error and 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

+@cindex JSONRPC

+

+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 @dfn{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."

+

+@findex jsonrpc-connection

+To model this agnosticism, the @code{jsonrpc} library uses objects of

+a @code{jsonrpc-connection} class, which represent a connection to a

+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 is always a subclass of @code{jsonrpc-connection}.

+Nevertheless, we can define two distinct APIs around the

+@code{jsonrpc-connection} class:

+

+@cindex JSONRPC application interfaces

+@enumerate

+

+@item A user interface for building JSONRPC applications

+

+@findex :request-dispatcher

+@findex :notification-dispatcher

+@findex jsonrpc-notify

+@findex jsonrpc-request

+@findex jsonrpc-async-request

+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/or

+@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 @code{params} object.

+

+@findex jsonrpc-error

+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 (a normal return) or

+non-locally (an error return). A local return value must be a Lisp

+object that can be serialized as JSON (@pxref{Parsing JSON}). This

+determines a success response, and the object is forwarded to the

+server as the JSONRPC @code{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 @code{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 calls

+the Lisp 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