procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge from origin/emacs-26

Browse source 
643df63 (origin/emacs-26) Avoid byte-compiler warning in em-rebind.el
d0eca49 ; * doc/emacs/mark.texi (Disabled Transient Mark): Fix last c...
af80b10 Improve indexing of 'C-SPC C-SPC'
89a7301 ; * doc/lispref/internals.texi (Writing Dynamic Modules): Fix...
a108eaa Fix bug with precious entries in Gnus registry
ce8b458 Document in the ELisp manual how to write loadable modules
a7ebc6b dired-do-shell-command: Notify users after abort the command

# Conflicts:
#	lisp/registry.el
This commit is contained in:
Glenn Morris 2018-10-12 10:31:22 -07:00
commit 6cf4dfe472
8 changed files with 750 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/emacs/mark.texi
View file

@ -444,12 +444,13 @@ from point to the end of the buffer. Commands that act this way are
identified in their own documentation.
@end itemize
@cindex enabling Transient Mark mode temporarily
While Transient Mark mode is off, you can activate it temporarily
using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}.
@table @kbd
@item C-@key{SPC} C-@key{SPC}
@kindex C-SPC C-SPC@r{, disabling Transient Mark}
@kindex C-SPC C-SPC@r{, enabling Transient Mark mode temporarily}
Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable
Transient Mark mode just once, until the mark is deactivated. (This
is not really a separate command; you are using the @kbd{C-@key{SPC}}

9
doc/lispref/elisp.texi
View file

@ -1590,9 +1590,18 @@ GNU Emacs Internals
* Memory Usage:: Info about total size of Lisp objects made so far.
* C Dialect:: What C variant Emacs is written in.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Writing Dynamic Modules:: Writing loadable modules for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
* C Integer Types:: How C integer types are used inside Emacs.
Writing Dynamic Modules
* Module Initialization::
* Module Functions::
* Module Values::
* Module Misc::
* Module Nonlocal::
Object Internals
* Buffer Internals:: Components of a buffer structure.

703
doc/lispref/internals.texi
View file

@ -18,6 +18,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
* Memory Usage:: Info about total size of Lisp objects made so far.
* C Dialect:: What C variant Emacs is written in.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Writing Dynamic Modules:: Writing loadable modules for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
* C Integer Types:: How C integer types are used inside Emacs.
@end menu
@ -969,6 +970,708 @@ in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
@code{side-effect-and-error-free-fns} so that the compiler optimizer
knows about it.
@node Writing Dynamic Modules
@section Writing Dynamically-Loaded Modules
@cindex writing emacs modules
@cindex dynamic modules, writing
@cindex module @acronym{API}
This section describes the Emacs module @acronym{API} and how to use
it as part of writing extension modules for Emacs. The module
@acronym{API} is defined in the C programming language, therefore the
description and the examples in this section assume the module is
written in C@. For other programming languages, you will need to use
the appropriate bindings, interfaces and facilities for calling C code.
Emacs C code requires a C99 or later compiler (@pxref{C Dialect}), and
so the code examples in this section also follow that standard.
Writing a module and integrating it into Emacs comprises the following
tasks:
@itemize @bullet
@item
Writing initialization code for the module.
@item
Writing one or more module functions.
@item
Communicating values and objects between Emacs and your module
functions.
@item
Handling of error conditions and nonlocal exits.
@end itemize
@noindent
The following subsections describe these tasks and the @acronym{API}
itself in more detail.
Once your module is written, compile it to produce a shared library,
according to the conventions of the underlying platform. Then place
the shared library in a directory mentioned in @code{load-path}
(@pxref{Library Search}), where Emacs will find it.
If you wish to verify the conformance of a module to the Emacs dynamic
module @acronym{API}, invoke Emacs with the @kbd{--module-assertions}
option. @xref{Initial Options,,,emacs, The GNU Emacs Manual}.
@menu
* Module Initialization::
* Module Functions::
* Module Values::
* Module Misc::
* Module Nonlocal::
@end menu
@node Module Initialization
@subsection Module Initialization Code
@cindex module initialization
Begin your module by including the header file @file{emacs-module.h}
and defining the GPL compatibility symbol:
@example
#include <emacs-module.h>
int plugin_is_GPL_compatible;
@end example
The @file{emacs-module.h} file is installed into your system's include
tree as part of the Emacs installation. Alternatively, you can find
it in the Emacs source tree.
@anchor{module initialization function}
Next, write an initialization function for the module.
@deftypefn Function int emacs_module_init (struct emacs_runtime *@var{runtime})
Emacs calls this function when it loads a module. If a module does
not export a function named @code{emacs_module_init}, trying to load
the module will signal an error. The initialization function should
return zero if the initialization succeeds, non-zero otherwise. In
the latter case, Emacs will signal an error, and the loading of the
module will fail. If the user presses @kbd{C-g} during the
initialization, Emacs ignores the return value of the initialization
function and quits (@pxref{Quitting}). (If needed, you can catch user
quitting inside the initialization function, @pxref{should_quit}.)
The argument @var{runtime} is a pointer to a C @code{struct} that
includes 2 public fields: @code{size}, which provides the size of the
structure in bytes; and @code{get_environment}, which provides a
pointer to a function that allows the module initialization function
access to the Emacs environment object and its interfaces.
The initialization function should perform whatever initialization is
required for the module. In addition, it can perform the following
tasks:
@table @asis
@cindex compatibility, between modules and Emacs
@item Compatibility verification
A module can verify that the Emacs executable which loads the module
is compatible with the module, by comparing the @code{size} member of
the @var{runtime} structure with the value compiled into the module:
@example
int
emacs_module_init (struct emacs_runtime *ert)
@{
if (ert->size < sizeof (*ert))
return 1;
@}
@end example
@noindent
If the size of the runtime object passed to the module is smaller than
what it expects, it means the module was compiled for an Emacs version
newer (later) than the one which attempts to load it, i.e.@: the
module might be incompatible with the Emacs binary.
In addition, a module can verify the compatibility of the module
@acronym{API} with what the module expects. The following sample code
assumes it is part of the @code{emacs_module_init} function shown
above:
@example
emacs_env *env = ert->get_environment (ert);
if (env->size < sizeof (*env))
return 2;
@end example
@noindent
@cindex module runtime environment
This calls the @code{get_environment} function using the pointer
provided in the @code{runtime} structure to retrieve a pointer to the
@acronym{API}'s @dfn{environment}, a C @code{struct} which also has a
@code{size} field holding the size of the structure in bytes.
Finally, you can write a module that will work with older versions of
Emacs, by comparing the size of the environment passed by Emacs with
known sizes, like this:
@example
emacs_env *env = ert->get_environment (ert);
if (env->size >= sizeof (struct emacs_env_26))
emacs_version = 26; /* Emacs 26 or later. */
else if (env->size >= sizeof (struct emacs_env_25))
emacs_version = 25;
else
return 2; /* Unknown or unsupported version. */
@end example
@noindent
This works because later Emacs versions always @emph{add} members to
the environment, never @emph{remove} any members, so the size can only
grow with new Emacs releases. Given the version of Emacs, the module
can use only the parts of the module @acronym{API} that existed in
that version, since those parts are identical in later versions.
We recommend that modules always perform the compatibility
verification, unless they do their job entirely in the initialization
function, and don't access any Lisp objects or use any Emacs functions
accessible through the environment structure.
@item Binding module functions to Lisp symbols
This gives the module functions names so that Lisp code could call it
by that name. We describe how to do this in @ref{Module Functions}
below.
@end table
@end deftypefn
@node Module Functions
@subsection Writing Module Functions
@cindex writing module functions
@cindex module functions
The main reason for writing an Emacs module is to make additional
functions available to Lisp programs that load the module. This
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})
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
zero (see @code{make_function} below for more flexible specification
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}.
Module functions use the type @code{emacs_value} to communicate Lisp
objects between Emacs and the module (@pxref{Module Values}). The
@acronym{API}, described below and in the following subsections,
provides facilities for conversion between basic C data types and the
corresponding @code{emacs_value} objects.
A module function always returns a value. If the function returns
normally, the Lisp code which called it will see the Lisp object
corresponding to the @code{emacs_value} value the function returned.
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.
@end deftypefn
After writing your C code for a module function, you should make a
Lisp function object from it using @code{make_function}. This is
normally done in the module initialization function (@pxref{module
initialization function}), after verifying the @acronym{API}
compatibility, and uses the pointer to @code{make_function} provided
in the environment (recall that the pointer to the environment is
returned by @code{get_environment}).
@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})
@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
@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},
which makes the function accept an unlimited number of arguments, like
the @code{&rest} keyword in Lisp (@pxref{Argument List}).
The argument @var{data} is a way to arrange for arbitrary additional
data to be passed to @var{func} when it is called. Whatever pointer
is passed to @code{make_function} will be passed unaltered to
@var{func}.
The argument @var{docstring} specifies the documentation string for
the function. It should be either an @acronym{ASCII} string, or a
UTF-8 encoded non-@acronym{ASCII} string, or a @code{NULL} pointer; in
the latter case the function will have no documentation. The
documentation string can end with a line that specifies the advertised
calling convention, see @ref{Function Documentation}.
Since every module function must accept the pointer to the environment
as its first argument, the call to @code{make_function} could be made
from any module function, but you will normally want to do that from
the module initialization function, so that all the module functions
are known to Emacs once the module is loaded.
@end deftypefn
Finally, you should bind the Lisp function to a symbol, so that Lisp
code could call your function by name. For that, use the module
@acronym{API} function @code{intern} (@pxref{intern}) whose pointer is
also provided in the environment that module functions can access.
Combining the above steps, code that arranges for a C function
@code{module_func} to be callable as @code{module-func} from Lisp will
look like this, as part of the module initialization function:
@example
emacs_env *env = ert->get_environment (ert);
emacs_value func = env->make_function (env, min_arity, max_arity,
module_func, docstring, data);
emacs_value symbol = env->intern (env, "module-func");
emacs_value args[] = @{symbol, func@};
env->funcall (env, env->intern (env, "defalias"), 2, args);
@end example
@noindent
This makes the symbol @code{module-func} known to Emacs by calling
@code{env->intern}, then invokes @code{defalias} from Emacs to bind
the function to that symbol. Note that it is possible to use
@code{fset} instead of @code{defalias}; the differences are described
in @ref{Defining Functions, defalias}.
Using the module @acronym{API}, it is possible to define more complex
function and data types: interactive functions, inline functions,
macros, etc. However, the resulting C code will be cumbersome and
hard to read. Therefore, we recommend that you limit the module code
which creates functions and data structures to the absolute minimum,
and leave the rest for a Lisp package that will accompany your module,
because doing these additional tasks in Lisp is much easier, and will
produce a much more readable code. For example, given a module
function @code{module-func} defined as above, one way of making an
interactive command @code{module-cmd} based on it is with the
following simple Lisp wrapper:
@lisp
(defun module-cmd (&rest args)
"Documentation string for the command."
(interactive @var{spec})
(apply 'module-func args))
@end lisp
The Lisp package which goes with your module could then load the
module using the @code{module-load} primitive (@pxref{Dynamic
Modules}) when the package is loaded into Emacs.
@node Module Values
@subsection Conversion Between Lisp and Module Values
@cindex module values, conversion
@cindex @code{emacs_value} data type
With very few exceptions, most modules need to exchange data with
Lisp programs that call them: accept arguments to module functions and
return values from module functions. For this purpose, the module
@acronym{API} provides the @code{emacs_value} type, which represents
Emacs Lisp objects communicated via the @acronym{API}; it is the
functional equivalent of the @code{Lisp_Object} type used in Emacs C
primitives (@pxref{Writing Emacs Primitives}). This section describes
the parts of the module @acronym{API} that allow to create
@code{emacs_value} objects corresponding to basic Lisp data types, and
how to access from C data in @code{emacs_value} objects that
correspond to Lisp objects.
All of the functions described below are actually @emph{function
pointers} provided via the pointer to the environment which every
module function accepts. Therefore, module code should call these
functions through the environment pointer, like this:
@example
emacs_env *env; /* the environment pointer */
env->some_function (arguments@dots{});
@end example
@noindent
The @code{emacs_env} pointer will usually come from the first argument
to the module function, or from the call to @code{get_environment} if
you need the environment in the module initialization function.
Most of the functions described below became available in Emacs 25,
the first Emacs release that supported dynamic modules. For the few
functions that became available in later Emacs releases, we mention
the first Emacs version that supported them.
The following @acronym{API} functions extract values of various C data
types from @code{emacs_value} objects. They all raise the
@code{wrong-type-argument} error condition (@pxref{Type Predicates})
if the argument @code{emacs_value} object is not of the type expected
by the function. @xref{Module Nonlocal}, for details of how signaling
errors works in Emacs modules, and how to catch error conditions
inside the module before they are reported to Emacs. The
@acronym{API} function @code{type_of} (@pxref{Module Misc, type_of})
can be used to obtain the type of a @code{emacs_value} object.
@deftypefn Function intmax_t extract_integer (emacs_env *@var{env}, emacs_value @var{arg})
This function returns the value of a Lisp integer specified by
@var{arg}. The C data type of the return value, @code{intmax_t}, is
the widest integral data type supported by the C compiler, typically
@w{@code{long long}}.
@end deftypefn
@deftypefn Function double extract_float (emacs_env *@var{env}, emacs_value @var{arg})
This function returns the value of a Lisp float specified by
@var{arg}, as a C @code{double} value.
@end deftypefn
@deftypefn Function bool copy_string_contents (emacs_env *@var{env}, emacs_value @var{arg}, char *@var{buf}, ptrdiff_t *@var{len})
This function stores the UTF-8 encoded text of a Lisp string specified
by @var{arg} in the array of @code{char} pointed by @var{buf}, which
should have enough space to hold at least @code{*@var{len}} bytes,
including the terminating null byte. The argument @var{len} must not
be a @code{NULL} pointer, and, when the function is called, it should
point to a value that specifies the size of @var{buf} in bytes.
If the buffer size specified by @code{*@var{len}} is large enough to
hold the string's text, the function stores in @code{*@var{len}} the
actual number of bytes copied to @var{buf}, including the terminating
null byte, and returns @code{true}. If the buffer is too small, the
function raises the @code{args-out-of-range} error condition, stores
the required number of bytes in @code{*@var{len}}, and returns
@code{false}. @xref{Module Nonlocal}, for how to handle pending error
conditions.
The argument @var{buf} can be a @code{NULL} pointer, in which case the
function stores in @code{*@var{len}} the number of bytes required for
storing the contents of @var{arg}, and returns @code{true}. This is
how you can determine the size of @var{buf} needed to store a
particular string: first call @code{copy_string_contents} with
@code{NULL} as @var{buf}, then allocate enough memory to hold the
number of bytes stored by the function in @code{*@var{len}}, and call
the function again with non-@code{NULL} @var{buf} to actually perform
the text copying.
@end deftypefn
@deftypefn Function emacs_value vec_get (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index})
This function returns the element of @var{vector} at @var{index}. The
@var{index} of the first vector element is zero. The function raises
the @code{args-out-of-range} error condition if the value of
@var{index} is invalid. To extract C data from the value the function
returns, use the other extraction functions described here, as
appropriate for the Lisp data type stored in that element of the
vector.
@end deftypefn
@deftypefn Function ptrdiff_t vec_size (emacs_env *@var{env}, emacs_value @var{vector})
This function returns the number of elements in @var{vector}.
@end deftypefn
@deftypefn Function void vec_set (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index}, emacs_value @var{value})
This function stores @var{value} in the element of @var{vector} whose
index is @var{index}. It raises the @code{args-out-of-range} error
condition if the value of @var{index} is invalid.
@end deftypefn
The following @acronym{API} functions create @code{emacs_value}
objects from basic C data types. They all return the created
@code{emacs_value} object.
@deftypefn Function emacs_value make_integer (emacs_env *@var{env}, intmax_t @var{n})
This function takes an integer argument @var{n} and returns the
corresponding @code{emacs_value} object. It raises the
@code{overflow-error} error condition if the value of @var{n} cannot
be represented as an Emacs integer, i.e.@: is not inside the limits
set by @code{most-negative-fixnum} and @code{most-positive-fixnum}
(@pxref{Integer Basics}).
@end deftypefn
@deftypefn Function emacs_value make_float (emacs_env *@var{env}, double @var{d})
This function takes a @code{double} argument @var{d} and returns the
corresponding Emacs floating-point value.
@end deftypefn
@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen})
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.
@end deftypefn
The @acronym{API} does not provide functions to manipulate Lisp data
structures, for example, create lists with @code{cons} and @code{list}
(@pxref{Building Lists}), extract list members with @code{car} and
@code{cdr} (@pxref{List Elements}), create vectors with @code{vector}
(@pxref{Vector Functions}), etc. For these, use @code{intern} and
@code{funcall}, described in the next subsection, to call the
corresponding Lisp functions.
Normally, @code{emacs_value} objects have a rather short lifetime: it
ends when the @code{emacs_env} pointer used for their creation goes
out of scope. Occasionally, you may need to create @dfn{global
references}: @code{emacs_value} objects that live as long as you
wish. Use the following two functions to manage such objects.
@deftypefn Function emacs_value make_global_ref (emacs_env *@var{env}, emacs_value @var{value})
This function returns a global reference for @var{value}.
@end deftypefn
@deftypefn Function void free_global_ref (emacs_env *@var{env}, emacs_value @var{global_value})
This function frees the @var{global_value} previously created by
@code{make_global_ref}. The @var{global_value} is no longer valid
after the call. Your module code should pair each call to
@code{make_global_ref} with the corresponding @code{free_global_ref}.
@end deftypefn
@cindex user pointer, using in module functions
An alternative to keeping around C data structures that need to be
passed to module functions later is to create @dfn{user pointer}
objects. A user pointer, or @code{user-ptr}, object is a Lisp object
that encapsulates a C pointer and can have an associated finalizer
function, which is called when the object is garbage-collected
(@pxref{Garbage Collection}). The module @acronym{API} provides
functions to create and access @code{user-ptr} objects. These
functions raise the @code{wrong-type-argument} error condition if they
are called on @code{emacs_value} that doesn't represent a
@code{user-ptr} object.
@deftypefn Function emacs_value make_user_ptr (emacs_env *@var{env}, emacs_finalizer @var{fin}, void *@var{ptr})
This function creates and returns a @code{user-ptr} object which wraps
the C pointer @var{ptr}. The finalizer function @var{fin} can be a
@code{NULL} pointer (meaning no finalizer), or it can be a function of
the following signature:
@example
typedef void (*emacs_finalizer) (void *@var{ptr});
@end example
@noindent
If @var{fin} is not a @code{NULL} pointer, it will be called with the
@var{ptr} as the argument when the @code{user-ptr} object is
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)
This function extracts the C pointer from the Lisp object represented
by @var{val}.
@end deftypefn
@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr})
This function sets the C pointer embedded in the @code{user-ptr}
object represented by @var{value} to @var{ptr}.
@end deftypefn
@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val)
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.
@end deftypefn
@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, 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.
@end deftypefn
@node Module Misc
@subsection Miscellaneous Convenience Functions for Modules
This subsection describes a few convenience functions provided by
the module @acronym{API}. Like the functions described in previous
subsections, all of them are actually function pointers, and need to
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})
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.
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}
is non-@code{nil}; it returns @code{true} or @code{false} accordingly.
Note that you could implement an equivalent test by using
@code{intern} to get an @code{emacs_value} representing @code{nil},
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.
@end deftypefn
@anchor{intern}
@deftypefn Function emacs_value intern (emacs_env *@var{env}, const char *name)
This function returns an interned Emacs symbol whose name is
@var{name}, which should be an @acronym{ASCII} null-terminated string.
It creates a new symbol if one does not already exist.
Together with @code{funcall}, described below, this function provides
a means for invoking any Lisp-callable Emacs function, provided that
its name is a pure @acronym{ASCII} string. For example, here's how to
intern a symbol whose name @code{name_str} is non-@acronym{ASCII}, by
calling the more powerful Emacs @code{intern} function
(@pxref{Creating Symbols}):
@example
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);
@end example
@end deftypefn
@deftypefn Function emacs_value funcall (emacs_env *@var{env}, emacs_value @var{func}, ptrdiff_t @var{nargs}, emacs_value *@var{args})
This function calls the specified @var{func} passing it @var{nargs}
arguments from the array pointed to by @var{args}. The argument
@var{func} can be a function symbol (e.g., returned by @code{intern}
described above), a module function returned by @code{make_function}
(@pxref{Module Functions}), a subroutine written in C, etc. If
@var{nargs} is zero, @var{args} can be a @code{NULL} pointer.
The function returns the value that @var{func} returned.
@end deftypefn
If your module includes potentially long-running code, it is a good
idea to check from time to time in that code whether the user wants to
quit, e.g., by typing @kbd{C-g} (@pxref{Quitting}). The following
function, which is available since Emacs 26.1, is provided for that
purpose.
@anchor{should_quit}
@deftypefn Function bool should_quit (emacs_env *@var{env})
This function returns @code{true} if the user wants to quit. In that
case, we recommend that your module function aborts any on-going
processing and returns as soon as possible.
@end deftypefn
@node Module Nonlocal
@subsection Nonlocal Exits in Modules
@cindex nonlocal exits, in modules
Emacs Lisp supports nonlocal exits, whereby program control is
transfered from one point in a program to another remote point.
@xref{Nonlocal Exits}. Thus, Lisp functions called by your module
might exit nonlocally by calling @code{signal} or @code{throw}, and
your module functions must handle such nonlocal exits properly. Such
handling is needed because C programs will not automatically release
resources and perform other cleanups in these cases; your module code
must itself do it. The module @acronym{API} provides facilities for
that, described in this subsection. They are generally available
since Emacs 25; those of them that became available in later releases
explicitly call out the first Emacs version where they became part of
the @acronym{API}.
When some Lisp code called by a module function signals an error or
throws, the nonlocal exit is trapped, and the pending exit and its
associated data are stored in the environment. Whenever a nonlocal
exit is pending in the environment, any module @acronym{API} function
called with a pointer to that environment will return immediately
without any processing (the functions @code{non_local_exit_check},
@code{non_local_exit_get}, and @code{non_local_exit_clear} are
exceptions from this rule). If your module function then does nothing
and returns to Emacs, a pending nonlocal exit will cause Emacs to act
on it: signal an error or throw to the corresponding @code{catch}.
So the simplest ``handling'' of nonlocal exits in module functions is
to do nothing special and let the rest of your code to run as if
nothing happened. However, this can cause two classes of problems:
@itemize @minus
@item
Your module function might use uninitialized or undefined values,
since @acronym{API} functions return immediately without producing the
expected results.
@item
Your module might leak resources, because it might not have the
opportunity to release them.
@end itemize
Therefore, we recommend that your module functions check for nonlocal
exit conditions and recover from them, using the functions described
below.
@deftypefn Function enum emacs_funcall_exit non_local_exit_check (emacs_env *@var{env})
This function returns the kind of nonlocal exit condition stored in
@var{env}. The possible values are:
@vindex emacs_funcall_exit@r{, enumeration}
@vtable @code
@item emacs_funcall_exit_return
The last @acronym{API} function exited normally.
@item emacs_funcall_exit_signal
The last @acronym{API} function signaled an error.
@item emacs_funcall_exit_throw
The last @acronym{API} function exited via @code{throw}.
@end vtable
@end deftypefn
@deftypefn Function emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})
This function returns the kind of nonlocal exit condition stored in
@var{env}, like @code{non_local_exit_check} does, but it also returns
the full information about the nonlocal exit, if any. If the return
value is @code{emacs_funcall_exit_signal}, the function stores the
error symbol in @code{*@var{symbol}} and the error data in
@code{*@var{data}} (@pxref{Signaling Errors}). If the return value is
@code{emacs_funcall_exit_throw}, the function stores the @code{catch}
tag symbol in @code{*@var{symbol}} and the @code{throw} value in
@code{*@var{data}}. The function doesn't store anything in memory
pointed by these arguments when the return value is
@code{emacs_funcall_exit_return}.
@end deftypefn
You should check nonlocal exit conditions where it matters: before you
allocated some resource or after you allocated a resource that might
need freeing, or where a failure means further processing is
impossible or infeasible.
Once your module function detected that a nonlocal exit is pending, it
can either return to Emacs (after performing the necessary local
cleanup), or it can attempt to recover from the nonlocal exit. The
following @acronym{API} functions will help with these tasks.
@deftypefn Function void non_local_exit_clear (emacs_env *@var{env})
This function clears the pending nonlocal exit conditions and data
from @var{env}. After calling it, the module @acronym{API} functions
will work normally. Use this function if your module function can
recover from nonlocal exits of the Lisp functions it calls and
continue, and also before calling any of the following two functions
(or any other @acronym{API} functions, if you want them to perform
their intended processing when a nonlocal exit is pending).
@end deftypefn
@deftypefn Function void non_local_exit_throw (emacs_env *@var{env}, emacs_value @var{tag}, emacs_value @var{value})
This function throws to the Lisp @code{catch} symbol represented by
@var{tag}, passing it @var{value} as the value to return. Your module
function should in general return soon after calling this function.
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.
@end deftypefn
@node Object Internals
@section Object Internals
@cindex object internals

33
doc/lispref/loading.texi
View file

@ -1139,8 +1139,6 @@ Features}).
@section Emacs Dynamic Modules
@cindex dynamic modules
@c FIXME: This is intentionally incomplete, as the module integration
@c is not yet finished. To be refined later.
A @dfn{dynamic Emacs module} is a shared library that provides
additional functionality for use in Emacs Lisp programs, just like a
package written in Emacs Lisp would.
@ -1162,30 +1160,43 @@ Every dynamic module should export a C-callable function named
@code{load} or @code{require} which loads the module. It should also
export a symbol named @code{plugin_is_GPL_compatible} to indicate that
its code is released under the GPL or compatible license; Emacs will
refuse to load modules that don't export such a symbol.
signal an error if your program tries to load modules that don't
export such a symbol.
If a module needs to call Emacs functions, it should do so through the
API defined and documented in the header file @file{emacs-module.h}
that is part of the Emacs distribution.
@acronym{API} (Application Programming Interface) defined and
documented in the header file @file{emacs-module.h} that is part of
the Emacs distribution. @xref{Writing Dynamic Modules}, for details
of using that API when writing your own modules.
@cindex user-ptr object
@cindex user pointer object
Modules can create @code{user-ptr} Lisp objects that embed pointers to
C struct's defined by the module. This is useful for keeping around
complex data structures created by a module, to be passed back to the
module's functions. User-ptr objects can also have associated
@dfn{finalizers} -- functions to be run when the object is GC'ed; this
is useful for freeing any resources allocated for the underlying data
structure, such as memory, open file descriptors, etc.
structure, such as memory, open file descriptors, etc. @xref{Module
Values}.
@defun user-ptrp object
This function returns @code{t} if its argument is a @code{user-ptr}
object.
@end defun
@defun module-load file
Emacs calls this low-level primitive to load a module from the
specified @var{file} and perform the necessary initialization of the
module. This is the primitive which makes sure the module exports the
@code{plugin_is_GPL_compatible} symbol, calls the module's
@code{emacs_module_init} function, and signals an error if that
function returns an error indication, or if the use typed @kbd{C-g}
during the initialization. If the initialization succeeds,
@code{module-load} returns @code{t}. Note that @var{file} must
already have the proper file-name extension, as this function doesn't
try looking for files with known extensions, unlike @code{load}.
@end defun
Loadable modules in Emacs are enabled by using the
@kbd{--with-modules} option at configure time.
If you write your own dynamic modules, you may wish to verify their
conformance to the Emacs dynamic module API. Invoking Emacs with the
@kbd{--module-assertions} option will help you in this matter.
@xref{Initial Options,,,emacs, The GNU Emacs Manual}.

2
doc/misc/gnus.texi
View file

@ -26194,7 +26194,7 @@ Get the data under @code{key} for message @code{id}.
If any extra entries are precious, their presence will make the
registry keep the whole entry forever, even if there are no groups for
the Message-ID and if the size limit of the registry is reached. By
default this is just @code{(marks)} so the custom registry marks are
default this is just @code{(mark)} so the custom registry marks are
precious.
@end defvar

21
lisp/dired-aux.el
View file

@ -763,16 +763,17 @@ can be produced by `dired-get-marked-files', for example."
(y-or-n-p (format-message
"Confirm--do you mean to use `?' as a wildcard? ")))
(t))))
(when ok
(if on-each
(dired-bunch-files (- 10000 (length command))
(lambda (&rest files)
(dired-run-shell-command
(dired-shell-stuff-it command files t arg)))
nil file-list)
;; execute the shell command
(dired-run-shell-command
(dired-shell-stuff-it command file-list nil arg)))))))
(cond ((not ok) (message "Command canceled"))
(t
(if on-each
(dired-bunch-files (- 10000 (length command))
(lambda (&rest files)
(dired-run-shell-command
(dired-shell-stuff-it command files t arg)))
nil file-list)
;; execute the shell command
(dired-run-shell-command
(dired-shell-stuff-it command file-list nil arg))))))))
;; Might use {,} for bash or csh:
(defvar dired-mark-prefix ""

2
lisp/eshell/em-rebind.el
View file

@ -223,7 +223,7 @@ lock it at that."
(interactive "P")
(let ((count (prefix-numeric-value n)))
(if (eshell-point-within-input-p (- (point) count))
(delete-backward-char count n)
(delete-char (- count) n)
(beep))))
(defun eshell-delchar-or-maybe-eof (arg)

2
lisp/registry.el
View file

@ -358,7 +358,7 @@ return LIMIT such candidates. If SORTFUNC is provided, sort
entries first and return candidates from beginning of list."
(let* ((precious (oref db precious))
(precious-p (lambda (entry-key)
(cdr (memq (car-safe entry-key) precious))))
(memq (car-safe entry-key) precious)))
(data (oref db data))
(candidates (cl-loop for k being the hash-keys of data
using (hash-values v)