diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/display.texi | 21 | ||||
| -rw-r--r-- | doc/lispref/edebug.texi | 5 | ||||
| -rw-r--r-- | doc/lispref/files.texi | 42 | ||||
| -rw-r--r-- | doc/lispref/frames.texi | 28 | ||||
| -rw-r--r-- | doc/lispref/internals.texi | 180 | ||||
| -rw-r--r-- | doc/lispref/keymaps.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/loading.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/minibuf.texi | 9 | ||||
| -rw-r--r-- | doc/lispref/modes.texi | 27 | ||||
| -rw-r--r-- | doc/lispref/objects.texi | 8 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 11 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 41 | ||||
| -rw-r--r-- | doc/lispref/searching.texi | 10 | ||||
| -rw-r--r-- | doc/lispref/strings.texi | 35 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 11 | ||||
| -rw-r--r-- | doc/lispref/windows.texi | 14 |
16 files changed, 310 insertions, 146 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 2ef27c00b8e..25eabd6c3fc 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1318,12 +1318,6 @@ the buffer specified by @var{buffer-or-name} current for running @var{body}. @end defmac -@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body -This macro is like @code{with-current-buffer-window} but unlike that -displays the buffer specified by @var{buffer-or-name} @emph{before} -running @var{body}. -@end defmac - A window showing a temporary buffer can be fitted to the size of that buffer using the following mode: @@ -2459,12 +2453,15 @@ Draw a box with lines of width 1, in the foreground color. @item @var{color} Draw a box with lines of width 1, in color @var{color}. -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to -1. A negative width @minus{}@var{n} means to draw a line of width @var{n} -whose top and bottom parts occupy the space of the underlying text, -thus avoiding any increase in the character height. +@item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})} +This way you can explicitly specify all aspects of the box. The values +@var{vwidth} and @var{hwidth} specifies respectively the width of the +vertical and horizontal lines to draw; they default to (1 . 1). +A negative horizontal or vertical width @minus{}@var{n} means to draw a line +of width @var{n} that occupies the space of the underlying text, thus +avoiding any increase in the character height or width. For simplification +the width could be specified with only a single number @var{n} instead +of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}. The value @var{color} specifies the color to draw with. The default is the foreground color of the face for simple boxes, and the background diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index b5b5ea0a645..d879f3dcadf 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1362,6 +1362,11 @@ while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See @ref{Backtracking}, for more details. Also see the @code{let} example. +@item &error +@code{&error} should be followed by a string, an error message, in the +edebug-spec; it aborts the instrumentation, displaying the message in +the minibuffer. + @item @var{other-symbol} @cindex indirect specifications Any other symbol in a specification list may be a predicate or an diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 6ca2834fbd4..92cbc2a1c91 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -928,7 +928,7 @@ also checks that the file's group would be unchanged. This function does not follow symbolic links. @end defun -@defun file-modes filename +@defun file-modes filename &optional flag @cindex mode bits @cindex file permissions @cindex permissions, file @@ -946,12 +946,19 @@ The highest possible value is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, the @acronym{SUID} bit is set for both others and group, and the sticky bit is set. +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently obtaining the mode bits of a file +somewhere else, and is more consistent with @code{file-attributes} +(@pxref{File Attributes}). + @xref{Changing Files}, for the @code{set-file-modes} function, which can be used to set these permissions. @example @group -(file-modes "~/junk/diffs") +(file-modes "~/junk/diffs" 'nofollow) @result{} 492 ; @r{Decimal integer.} @end group @group @@ -960,7 +967,7 @@ can be used to set these permissions. @end group @group -(set-file-modes "~/junk/diffs" #o666) +(set-file-modes "~/junk/diffs" #o666 'nofollow) @result{} nil @end group @@ -1801,9 +1808,17 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}. @cindex file permissions, setting @cindex permissions, file @cindex file modes, setting -@deffn Command set-file-modes filename mode +@deffn Command set-file-modes filename mode &optional flag This function sets the @dfn{file mode} (or @dfn{permissions}) of -@var{filename} to @var{mode}. This function follows symbolic links. +@var{filename} to @var{mode}. + +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently changing the mode bits of a file +somewhere else. On platforms that do not support changing mode bits +on a symbolic link, this function signals an error when @var{filename} +is a symbolic link and @var{flag} is @code{nofollow}. If called non-interactively, @var{mode} must be an integer. Only the lowest 12 bits of the integer are used; on most systems, only the @@ -1811,7 +1826,7 @@ lowest 9 bits are meaningful. You can use the Lisp construct for octal numbers to enter @var{mode}. For example, @example -(set-file-modes #o644) +(set-file-modes "myfile" #o644 'nofollow) @end example @noindent @@ -1894,11 +1909,24 @@ omitted or @code{nil}, it defaults to 0, i.e., no access rights at all. @end defun -@defun set-file-times filename &optional time +@defun file-modes-number-to-symbolic modes +This function converts a numeric file mode specification in +@var{modes} into the equivalent symbolic form. +@end defun + +@defun set-file-times filename &optional time flag This function sets the access and modification times of @var{filename} to @var{time}. The return value is @code{t} if the times are successfully set, otherwise it is @code{nil}. @var{time} defaults to the current time and must be a time value (@pxref{Time of Day}). + +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently changing the times of a file +somewhere else. On platforms that do not support changing times +on a symbolic link, this function signals an error when @var{filename} +is a symbolic link and @var{flag} is @code{nofollow}. @end defun @defun set-file-extended-attributes filename attribute-alist diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ae61b269520..22d32c00d9b 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -2193,10 +2193,11 @@ it and see if it works.) @vindex ns-appearance@r{, a frame parameter} @item ns-appearance Only available on macOS, if set to @code{dark} draw this frame's -window-system window using the ``vibrant dark'' theme, otherwise use -the system default. The ``vibrant dark'' theme can be used to set the -toolbar and scrollbars to a dark appearance when using an Emacs theme -with a dark background. +window-system window using the ``vibrant dark'' theme, and if set to +@code{light} use the ``aqua'' theme, otherwise use the system default. +The ``vibrant dark'' theme can be used to set the toolbar and +scrollbars to a dark appearance when using an Emacs theme with a dark +background. @vindex ns-transparent-titlebar@r{, a frame parameter} @item ns-transparent-titlebar @@ -2220,6 +2221,9 @@ How to display the cursor. Legitimate values are: @table @code @item box Display a filled box. (This is the default.) +@item (box . @var{size}) +Display a filled box. However, display it as a hollow box if point is +under masked image larger than @var{size} pixels in either dimension. @item hollow Display a hollow box. @item nil @@ -3872,13 +3876,15 @@ detailed knowledge of what types other applications use for drag and drop. @vindex dnd-protocol-alist +@vindex browse-url-handlers +@vindex browse-url-default-handlers When an URL is dropped on Emacs it may be a file, but it may also be another URL type (https, etc.). Emacs first checks @code{dnd-protocol-alist} to determine what to do with the URL@. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. +there is no match there, Emacs looks for a match in +@code{browse-url-handlers} and @code{browse-url-default-handlers}. If +still no match has been found, the text for the URL is inserted. If +you want to alter Emacs behavior, you can customize these variables. @node Color Names @section Color Names @@ -3970,11 +3976,11 @@ If @var{color} is not defined, the value is @code{nil}. (color-values "black") @result{} (0 0 0) (color-values "white") - @result{} (65280 65280 65280) + @result{} (65535 65535 65535) (color-values "red") - @result{} (65280 0 0) + @result{} (65535 0 0) (color-values "pink") - @result{} (65280 49152 51968) + @result{} (65535 49344 52171) (color-values "hungry") @result{} nil @end example diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 325841d8f8a..d70c3543f2a 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1228,9 +1228,9 @@ the @var{runtime} structure with the value compiled into the module: @example int -emacs_module_init (struct emacs_runtime *ert) +emacs_module_init (struct emacs_runtime *runtime) @{ - if (ert->size < sizeof (*ert)) + if (runtime->size < sizeof (*runtime)) return 1; @} @end example @@ -1247,7 +1247,7 @@ assumes it is part of the @code{emacs_module_init} function shown above: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); if (env->size < sizeof (*env)) return 2; @end example @@ -1264,7 +1264,7 @@ Emacs, by comparing the size of the environment passed by Emacs with known sizes, like this: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); if (env->size >= sizeof (struct emacs_env_26)) emacs_version = 26; /* Emacs 26 or later. */ else if (env->size >= sizeof (struct emacs_env_25)) @@ -1314,7 +1314,8 @@ subsection describes how to write such @dfn{module functions}. A module function has the following general form and signature: -@deftypefn Function emacs_value module_func (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data}) +@deftypefn Function emacs_value emacs_function (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data}) +@tindex emacs_function The @var{env} argument provides a pointer to the @acronym{API} environment, needed to access Emacs objects and functions. The @var{nargs} argument is the required number of arguments, which can be @@ -1323,7 +1324,7 @@ of the argument number), and @var{args} is a pointer to the array of the function arguments. The argument @var{data} points to additional data required by the function, which was arranged when @code{make_function} (see below) was called to create an Emacs -function from @code{module_func}. +function from @code{emacs_function}. Module functions use the type @code{emacs_value} to communicate Lisp objects between Emacs and the module (@pxref{Module Values}). The @@ -1338,6 +1339,10 @@ However, if the user typed @kbd{C-g}, or if the module function or its callees signaled an error or exited nonlocally (@pxref{Module Nonlocal}), Emacs will ignore the returned value and quit or throw as it does when Lisp code encounters the same situations. + +The header @file{emacs-module.h} provides the type +@code{emacs_function} as an alias type for a function pointer to a +module function. @end deftypefn After writing your C code for a module function, you should make a @@ -1348,11 +1353,11 @@ normally done in the module initialization function (@pxref{module initialization function}), after verifying the @acronym{API} compatibility. -@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, subr @var{func}, const char *@var{docstring}, void *@var{data}) +@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, emacs_function @var{func}, const char *@var{docstring}, void *@var{data}) @vindex emacs_variadic_function This returns an Emacs function created from the C function @var{func}, -whose signature is as described for @code{module_func} above (assumed -here to be @code{typedef}'ed as @code{subr}). The arguments +whose signature is as described for @code{emacs_function} above. +The arguments @var{min_arity} and @var{max_arity} specify the minimum and maximum number of arguments that @var{func} can accept. The @var{max_arity} argument can have the special value @code{emacs_variadic_function}, @@ -1388,7 +1393,7 @@ Combining the above steps, code that arranges for a C function look like this, as part of the module initialization function: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); emacs_value func = env->make_function (env, min_arity, max_arity, module_func, docstring, data); emacs_value symbol = env->intern (env, "module-func"); @@ -1442,6 +1447,54 @@ The Lisp package which goes with your module could then load the module using the @code{load} primitive (@pxref{Dynamic Modules}) when the package is loaded into Emacs. +@anchor{Module Function Finalizers} +If you want to run some code when a module function object (i.e., an +object returned by @code{make_function}) is garbage-collected, you can +install a @dfn{function finalizer}. Function finalizers are available +since Emacs 28. For example, if you have passed some heap-allocated +structure to the @var{data} argument of @code{make_function}, you can +use the finalizer to deallocate the structure. @xref{Basic +Allocation,,,libc}, and @pxref{Freeing after Malloc,,,libc}. The +finalizer function has the following signature: + +@example +void finalizer (void *@var{data}) +@end example + +Here, @var{data} receives the value passed to @var{data} when calling +@code{make_function}. Note that the finalizer can't interact with +Emacs in any way. + +Directly after calling @code{make_function}, the newly-created +function doesn't have a finalizer. Use @code{set_function_finalizer} +to add one, if desired. + +@deftypefun void emacs_finalizer (void *@var{ptr}) +The header @file{emacs-module.h} provides the type +@code{emacs_finalizer} as a type alias for an Emacs finalizer +function. +@end deftypefun + +@deftypefun emacs_finalizer get_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}) +This function, which is available since Emacs 28, returns the function +finalizer associated with the module function represented by +@var{arg}. @var{arg} must refer to a module function, that is, an +object returned by @code{make_function}. If no finalizer is +associated with the function, @code{NULL} is returned. +@end deftypefun + +@deftypefun void set_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin}) +This function, which is available since Emacs 28, sets the function +finalizer associated with the module function represented by @var{arg} +to @var{fin}. @var{arg} must refer to a module function, that is, an +object returned by @code{make_function}. @var{fin} can either be +@code{NULL} to clear @var{arg}'s function finalizer, or a pointer to a +function to be called when the object represented by @var{arg} is +garbage-collected. At most one function finalizer can be set per +function; if @var{arg} already has a finalizer, it is replaced by +@var{fin}. +@end deftypefun + @node Module Values @subsection Conversion Between Lisp and Module Values @cindex module values, conversion @@ -1541,12 +1594,11 @@ This function returns the value of a Lisp float specified by @var{arg}, as a C @code{double} value. @end deftypefn -@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: +@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{arg}) +This function, which is available since Emacs 27, interprets @var{arg} +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 @@ -1744,9 +1796,9 @@ next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args, @} int -emacs_module_init (struct emacs_runtime *ert) +emacs_module_init (struct emacs_runtime *runtime) @{ - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); emacs_value symbol = env->intern (env, "next-prime"); emacs_value func = env->make_function (env, 1, 1, next_prime, NULL, NULL); @@ -1773,16 +1825,15 @@ 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 -@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen}) +@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{len}) This function creates an Emacs string from C text string pointed by @var{str} whose length in bytes, not including the terminating null -byte, is @var{strlen}. The original string in @var{str} can be either -an @acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} -string; it can include embedded null bytes, and doesn't have to end in -a terminating null byte at @code{@var{str}[@var{strlen}]}. The -function raises the @code{overflow-error} error condition if -@var{strlen} is negative or exceeds the maximum length of an Emacs -string. +byte, is @var{len}. The original string in @var{str} can be either an +@acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} string; +it can include embedded null bytes, and doesn't have to end in a +terminating null byte at @code{@var{str}[@var{len}]}. The function +raises the @code{overflow-error} error condition if @var{len} is +negative or exceeds the maximum length of an Emacs string. @end deftypefn The @acronym{API} does not provide functions to manipulate Lisp data @@ -1839,27 +1890,32 @@ garbage-collected. Don't run any expensive code in a finalizer, because GC must finish quickly to keep Emacs responsive. @end deftypefn -@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value val) +@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}) This function extracts the C pointer from the Lisp object represented -by @var{val}. +by @var{arg}. @end deftypefn -@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr}) +@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}, void *@var{ptr}) This function sets the C pointer embedded in the @code{user-ptr} -object represented by @var{value} to @var{ptr}. +object represented by @var{arg} to @var{ptr}. @end deftypefn -@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val) +@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}) This function returns the finalizer of the @code{user-ptr} object -represented by @var{val}, or @code{NULL} if it doesn't have a finalizer. +represented by @var{arg}, or @code{NULL} if it doesn't have a +finalizer. @end deftypefn -@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, emacs_finalizer @var{fin}) +@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin}) This function changes the finalizer of the @code{user-ptr} object -represented by @var{val} to be @var{fin}. If @var{fin} is a -@code{NULL} pointer, the @code{user-ptr} object will have no finalizer. +represented by @var{arg} to be @var{fin}. If @var{fin} is a +@code{NULL} pointer, the @code{user-ptr} object will have no +finalizer. @end deftypefn +Note that the @code{emacs_finalizer} type works for both user pointer +an module function finalizers. @xref{Module Function Finalizers}. + @node Module Misc @subsection Miscellaneous Convenience Functions for Modules @@ -1870,20 +1926,20 @@ be called via the @code{emacs_env} pointer. Description of functions that were introduced after Emacs 25 calls out the first version where they became available. -@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{val1}, emacs_value @var{val2}) +@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{a}, emacs_value @var{b}) This function returns @code{true} if the Lisp objects represented by -@var{val1} and @var{val2} are identical, @code{false} otherwise. This -is the same as the Lisp function @code{eq} (@pxref{Equality -Predicates}), but avoids the need to intern the objects represented by -the arguments. +@var{a} and @var{b} are identical, @code{false} otherwise. This is +the same as the Lisp function @code{eq} (@pxref{Equality Predicates}), +but avoids the need to intern the objects represented by the +arguments. There are no @acronym{API} functions for other equality predicates, so you will need to use @code{intern} and @code{funcall}, described below, to perform more complex equality tests. @end deftypefn -@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{val}) -This function tests whether the Lisp object represented by @var{val} +@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{arg}) +This function tests whether the Lisp object represented by @var{arg} is non-@code{nil}; it returns @code{true} or @code{false} accordingly. Note that you could implement an equivalent test by using @@ -1892,12 +1948,12 @@ then use @code{eq}, described above, to test for equality. But using this function is more convenient. @end deftypefn -@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{object}) -This function returns the type of @var{object} as a value that -represents a symbol: @code{string} for a string, @code{integer} for an -integer, @code{process} for a process, etc. @xref{Type Predicates}. -You can use @code{intern} and @code{eq} to compare against known type -symbols, if your code needs to depend on the object type. +@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{arg}) +This function returns the type of @var{arg} as a value that represents +a symbol: @code{string} for a string, @code{integer} for an integer, +@code{process} for a process, etc. @xref{Type Predicates}. You can +use @code{intern} and @code{eq} to compare against known type symbols, +if your code needs to depend on the object type. @end deftypefn @anchor{intern} @@ -1917,8 +1973,7 @@ calling the more powerful Emacs @code{intern} function emacs_value fintern = env->intern (env, "intern"); emacs_value sym_name = env->make_string (env, name_str, strlen (name_str)); -emacs_value intern_args[] = @{ sym_name, env->intern (env, "nil") @}; -emacs_value symbol = env->funcall (env, fintern, 2, intern_args); +emacs_value symbol = env->funcall (env, fintern, 1, &sym_name); @end example @end deftypefn @@ -1967,6 +2022,20 @@ variable values and buffer content may have been modified in arbitrary ways. @end deftypefn +@anchor{open_channel} +@deftypefun int open_channel (emacs_env *@var{env}, emacs_value @var{pipe_process}) +This function, which is available since Emacs 28, opens a channel to +an existing pipe process. @var{pipe_process} must refer to an +existing pipe process created by @code{make-pipe-process}. @ref{Pipe +Processes}. If successful, the return value will be a new file +descriptor that you can use to write to the pipe. Unlike all other +module functions, you can use the returned file descriptor from +arbitrary threads, even if no module environment is active. You can +use the @code{write} function to write to the file descriptor. Once +done, close the file descriptor using @code{close}. @ref{Low-Level +I/O,,,libc}. +@end deftypefun + @node Module Nonlocal @subsection Nonlocal Exits in Modules @cindex nonlocal exits, in modules @@ -2071,11 +2140,12 @@ One use of this function is when you want to re-throw a non-local exit from one of the called @acronym{API} or Lisp functions. @end deftypefn -@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{error}, emacs_value @var{data}) -This function signals the error represented by @var{error} with the -specified error data @var{data}. The module function should return -soon after calling this function. This function could be useful, -e.g., for signaling errors from module functions to Emacs. +@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{symbol}, emacs_value @var{data}) +This function signals the error represented by the error symbol +@var{symbol} with the specified error data @var{data}. The module +function should return soon after calling this function. This +function could be useful, e.g., for signaling errors from module +functions to Emacs. @end deftypefn diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 1e81fb1dc52..130ff0d8671 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1846,8 +1846,11 @@ local map. @cindex scanning keymaps @cindex keymaps, scanning - This section describes functions used to scan all the current keymaps -for the sake of printing help information. + This section describes functions used to scan all the current +keymaps for the sake of printing help information. To display the +bindings in a particular keymap, you can use the +@code{describe-keymap} command (@pxref{Misc Help, , Other Help +Commands, emacs, The GNU Emacs Manual}) @defun accessible-keymaps keymap &optional prefix This function returns a list of all the keymaps that can be reached (via diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 2739d10ece9..6833af9c262 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1170,10 +1170,13 @@ extension, a.k.a.@: ``suffix''. This suffix is platform-dependent. @defvar module-file-suffix This variable holds the system-dependent value of the file-name -extension of the module files. Its value is @file{.so} on POSIX hosts -and @file{.dll} on MS-Windows. +extension of the module files. Its value is @file{.so} on POSIX +hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows. @end defvar + On macOS, dynamic modules can also have the suffix @file{.so} in +addition to @file{.dylib}. + @findex emacs_module_init @vindex plugin_is_GPL_compatible Every dynamic module should export a C-callable function named diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index c1615993f5e..2488fb37529 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -646,6 +646,15 @@ A history list for variable-name arguments read by @code{read-variable}. @end defvar +@defvar read-number-history +A history list for numbers read by @code{read-number}. +@end defvar + +@defvar goto-line-history +A history list for arguments to @code{goto-line}. This variable is +buffer local. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index e685391c955..33a07c9fb4d 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -469,9 +469,10 @@ variable @code{imenu-generic-expression}, for the two variables @code{imenu-create-index-function} (@pxref{Imenu}). @item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. +The mode can tell ElDoc mode how to retrieve different types of +documentation for whatever is at point, by adding one or more +buffer-local entries to the special hook +@code{eldoc-documentation-functions}. @item The mode can specify how to complete various keywords by adding one or @@ -1352,19 +1353,11 @@ illustrate how these modes are written. @end smallexample The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (&optional syntax keywords-case-insensitive elisp) - (when syntax - (set-syntax-table lisp-mode-syntax-table)) - @dots{} -@end group -@end smallexample +Lisp mode and Emacs Lisp mode inherit from Lisp Data mode and Lisp +Interaction Mode inherits from Emacs Lisp mode. @noindent -Amongst other things, this function sets up the @code{comment-start} +Amongst other things, Lisp Data mode sets up the @code{comment-start} variable to handle Lisp comments: @smallexample @@ -1414,7 +1407,7 @@ Finally, here is the major mode command for Lisp mode: @smallexample @group -(define-derived-mode lisp-mode prog-mode "Lisp" +(define-derived-mode lisp-mode lisp-data-mode "Lisp" "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. Commands: Delete converts tabs to spaces as it moves back. @@ -1425,10 +1418,9 @@ Note that `run-lisp' may be used either to start an inferior Lisp job or to switch back to an existing one." @end group @group - (lisp-mode-variables nil t) (setq-local find-tag-default-function 'lisp-find-tag-default) (setq-local comment-start-skip - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") + "\\(\\(^\\|[^\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") (setq imenu-case-fold-search t)) @end group @end smallexample @@ -2673,6 +2665,7 @@ Setting this variable makes it buffer-local in the current buffer. @node Font Lock Mode @section Font Lock Mode @cindex Font Lock mode +@cindex syntax highlighting and coloring @dfn{Font Lock mode} is a buffer-local minor mode that automatically attaches @code{face} properties to certain parts of the buffer based on diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 5c5f89eb433..83066744121 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -2339,8 +2339,12 @@ same sequence of character codes and all these codes are in the range @end group @end example -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. +The @code{equal} function recursively compares the contents of objects +if they are integers, strings, markers, vectors, bool-vectors, +byte-code function objects, char-tables, records, or font objects. +Other objects are considered @code{equal} only if they are @code{eq}. +For example, two distinct buffers are never considered @code{equal}, +even if their textual contents are the same. @end defun For @code{equal}, equality is defined recursively; for example, given diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index b31ab87ff17..942bda105f7 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1701,7 +1701,8 @@ following form: @noindent The format of this list is the same as what @code{decode-time} accepts (@pxref{Time Conversion}), and is described in more detail there. Any -element that cannot be determined from the input will be set to +@code{dst} element that cannot be determined from the input is set to +@minus{}1, and any other unknown element is set to @code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this function will attempt to parse @@ -2193,9 +2194,9 @@ cause anything special to happen. @findex list-timers The @code{list-timers} command lists all the currently active timers. -There's only one command available in the buffer displayed: @kbd{c} -(@code{timer-list-cancel}) that will cancel the timer on the line -under point. +The command @kbd{c} (@code{timer-list-cancel}) will cancel the timer +on the line under point. You can sort the list by column using the +command @kbd{S} (@code{tabulated-list-sort}). @node Idle Timers @section Idle Timers @@ -3137,7 +3138,7 @@ being reported. For example: @end group @group -(set-file-modes "/tmp/foo" (default-file-modes)) +(set-file-modes "/tmp/foo" (default-file-modes) 'nofollow) @result{} Event (35025468 attribute-changed "/tmp/foo") @end group @end example diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 6970f718ee0..4002004cd6f 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -477,6 +477,22 @@ You should only ever change this variable with a let-binding; never with @code{setq}. @end defvar +@defopt process-file-return-signal-string +This user option indicates whether a call of @code{process-file} +returns a string describing the signal interrupting a remote process. + +When a process returns an exit code greater than 128, it is +interpreted as a signal. @code{process-file} requires to return a +string describing this signal. + +Since there are processes violating this rule, returning exit codes +greater than 128 which are not bound to a signal, @code{process-file} +returns always the exit code as natural number for remote processes. +Setting this user option to non-nil forces @code{process-file} to +interpret such exit codes as signals, and to return a corresponding +string. +@end defopt + @defun call-process-region start end program &optional delete destination display &rest args This function sends the text from @var{start} to @var{end} as standard input to a process running @var{program}. It deletes the text @@ -743,6 +759,7 @@ Some file name handlers may not support @code{make-process}. In such cases, this function does nothing and returns @code{nil}. @end defun +@anchor{Pipe Processes} @defun make-pipe-process &rest args This function creates a bidirectional pipe which can be attached to a child process. This is useful with the @code{:stderr} keyword of @@ -2426,18 +2443,15 @@ server is stopped; a non-@code{nil} value means yes. @cindex encrypted network connections @cindex @acronym{TLS} network connections @cindex @acronym{STARTTLS} network connections -Emacs can create encrypted network connections, using either built-in -or external support. The built-in support uses the GnuTLS -Transport Layer Security Library; see +Emacs can create encrypted network connections, using the built-in +support for the GnuTLS Transport Layer Security Library; see @uref{https://www.gnu.org/software/gnutls/, the GnuTLS project page}. If your Emacs was compiled with GnuTLS support, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. For more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}. -The external support uses the @file{starttls.el} library, which -requires a helper utility such as @command{gnutls-cli} to be installed -on the system. The @code{open-network-stream} function can -transparently handle the details of creating encrypted connections for -you, using whatever support is available. +The @code{open-network-stream} function can transparently handle the +details of creating encrypted connections for you, using whatever +support is available. @defun open-network-stream name buffer host service &rest parameters This function opens a TCP connection, with optional encryption, and @@ -2465,6 +2479,12 @@ that are mainly relevant to encrypted connections: @item :nowait @var{boolean} If non-@code{nil}, try to make an asynchronous connection. +@item :coding @var{coding} +Use this to set the coding systems used by the network process, in +preference to binding @code{coding-system-for-read} or +@code{coding-system-for-write}. @xref{Network Processes}, for +details. + @item :type @var{type} The type of connection. Options are: @@ -2491,7 +2511,10 @@ If non-@code{nil}, always ask for the server's capabilities, even when doing a @samp{plain} connection. @item :capability-command @var{capability-command} -Command string to query the host capabilities. +Command to query the host capabilities. This can either be a string +(which will then be sent verbatim to the server), or a function +(called with a single parameter; the "greeting" from the server when +connecting), and should return a string. @item :end-of-command @var{regexp} @itemx :end-of-capability @var{regexp} diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 83c154938cd..c8a12bdd66b 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -338,16 +338,14 @@ first tries to match all three @samp{a}s; but the rest of the pattern is The next alternative is for @samp{a*} to match only two @samp{a}s. With this choice, the rest of the regexp matches successfully. -@strong{Warning:} Nested repetition operators can run for an -indefinitely long time, if they lead to ambiguous matching. For +@strong{Warning:} Nested repetition operators can run for a very +long time, if they lead to ambiguous matching. For example, trying to match the regular expression @samp{\(x+y*\)*a} against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could take hours before it ultimately fails. Emacs must try each way of grouping the @samp{x}s before concluding that none of them can work. -Even worse, @samp{\(x*\)*} can match the null string in infinitely -many ways, so it causes an infinite loop. To avoid these problems, -check nested repetitions carefully, to make sure that they do not -cause combinatorial explosions in backtracking. +In general, avoid expressions that can match the same string in +multiple ways. @item @samp{+} @cindex @samp{+} in regexp diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 0dc47f30c43..8de6255478b 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1157,7 +1157,7 @@ The function @code{format-spec} described in this section performs a similar function to @code{format}, except it operates on format control strings that use arbitrary specification characters. -@defun format-spec template spec-alist &optional only-present +@defun format-spec template spec-alist &optional ignore-missing This function returns a string produced from the format string @var{template} according to conversions specified in @var{spec-alist}, which is an alist (@pxref{Association Lists}) of the form @@ -1190,12 +1190,15 @@ The order of specifications in @var{template} need not correspond to the order of associations in @var{spec-alist}. @end itemize -The optional argument @var{only-present} indicates how to handle +The optional argument @var{ignore-missing} indicates how to handle specification characters in @var{template} that are not found in @var{spec-alist}. If it is @code{nil} or omitted, the function -signals an error. Otherwise, those format specifications and any -occurrences of @samp{%%} in @var{template} are left verbatim in the -output, including their text properties, if any. +signals an error; if it is @code{ignore}, those format specifications +are left verbatim in the output, including their text properties, if +any; if it is @code{delete}, those format specifications are removed +from the output; any other non-@code{nil} value is handled like +@code{ignore}, but any occurrences of @samp{%%} are also left verbatim +in the output. @end defun The syntax of format specifications accepted by @code{format-spec} is @@ -1243,7 +1246,7 @@ the right rather than the left. @item < This flag causes the substitution to be truncated on the left to the -given width, if specified. +given width and precision, if specified. @item > This flag causes the substitution to be truncated on the right to the @@ -1262,9 +1265,12 @@ The result of using contradictory flags (for instance, both upper and lower case) is undefined. As is the case with @code{format}, a format specification can include -a width, which is a decimal number that appears after any flags. If a -substitution contains fewer characters than its specified width, it is -padded on the left: +a width, which is a decimal number that appears after any flags, and a +precision, which is a decimal-point @samp{.} followed by a decimal +number that appears after any flags and width. + +If a substitution contains fewer characters than its specified width, +it is padded on the left: @example @group @@ -1274,6 +1280,17 @@ padded on the left: @end group @end example +If a substitution contains more characters than its specified +precision, it is truncated on the right: + +@example +@group +(format-spec "%.2a is truncated on the right" + '((?a . "alpha"))) + @result{} "al is truncated on the right" +@end group +@end example + Here is a more complicated example that combines several aforementioned features: diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 5d83e7bd6cc..0c3813ff1d0 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4813,11 +4813,9 @@ When @var{noerror} is non-@code{nil}, this function silently uses @code{raw-text} coding instead. @item (@code{iv-auto} @var{length}) -This will generate an IV (Initialization Vector) of the specified -length using the GnuTLS @code{GNUTLS_RND_NONCE} generator and pass it -to the function. This ensures that the IV is unpredictable and -unlikely to be reused in the same session. The actual value of the IV -is returned by the function as described below. +This generates a random IV (Initialization Vector) of the specified +length and passes it to the function. This ensures that the IV is +unpredictable and unlikely to be reused in the same session. @end table @@ -5101,6 +5099,9 @@ The following are functions for altering the @acronym{DOM}. @item dom-set-attribute @var{node} @var{attribute} @var{value} Set the @var{attribute} of the node to @var{value}. +@item dom-remove-attribute @var{node} @var{attribute} +Remove @var{attribute} from @var{node}. + @item dom-append-child @var{node} @var{child} Append @var{child} as the last child of @var{node}. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index a19f123c658..5ec23a9c876 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -3048,6 +3048,16 @@ since there is no guarantee that an arbitrary caller of @code{display-buffer} will be able to handle the case that no window will display the buffer. @code{display-buffer-no-window} is the only action function that cares about this entry. + +@vindex body-function@r{, a buffer display action alist entry} +@item body-function +The value must be a function taking one argument (a displayed window). +This function can be used to fill the displayed window's body with +some contents that might depend on dimensions of the displayed window. +It is called @emph{after} the buffer is displayed, and @emph{before} +the entries @code{window-height}, @code{window-width} and +@code{preserve-size} are applied that could resize the window to fit +it to the inserted contents. @end table By convention, the entries @code{window-height}, @code{window-width} @@ -5916,10 +5926,6 @@ This function compares two window configurations as regards the structure of windows, but ignores the values of point and the saved scrolling positions---it can return @code{t} even if those aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point. @end defun @defun window-configuration-frame config |