diff options
Diffstat (limited to 'devdocs/elisp/module-misc.html')
| -rw-r--r-- | devdocs/elisp/module-misc.html | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/devdocs/elisp/module-misc.html b/devdocs/elisp/module-misc.html new file mode 100644 index 00000000..17516754 --- /dev/null +++ b/devdocs/elisp/module-misc.html @@ -0,0 +1,34 @@ + <h4 class="subsection"> Miscellaneous Convenience Functions for Modules</h4> <p>This subsection describes a few convenience functions provided by the module <acronym>API</acronym>. Like the functions described in previous subsections, all of them are actually function pointers, and need to be called via the <code>emacs_env</code> pointer. Description of functions that were introduced after Emacs 25 calls out the first version where they became available. </p> <dl> <dt id="eq">Function: <em>bool</em> <strong>eq</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>a</var>, emacs_value <var>b</var>)</em> +</dt> <dd> +<p>This function returns <code>true</code> if the Lisp objects represented by <var>a</var> and <var>b</var> are identical, <code>false</code> otherwise. This is the same as the Lisp function <code>eq</code> (see <a href="equality-predicates">Equality Predicates</a>), but avoids the need to intern the objects represented by the arguments. </p> <p>There are no <acronym>API</acronym> functions for other equality predicates, so you will need to use <code>intern</code> and <code>funcall</code>, described below, to perform more complex equality tests. </p> +</dd> +</dl> <dl> <dt id="is_not_nil">Function: <em>bool</em> <strong>is_not_nil</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>arg</var>)</em> +</dt> <dd> +<p>This function tests whether the Lisp object represented by <var>arg</var> is non-<code>nil</code>; it returns <code>true</code> or <code>false</code> accordingly. </p> <p>Note that you could implement an equivalent test by using <code>intern</code> to get an <code>emacs_value</code> representing <code>nil</code>, then use <code>eq</code>, described above, to test for equality. But using this function is more convenient. </p> +</dd> +</dl> <dl> <dt id="type_of">Function: <em>emacs_value</em> <strong>type_of</strong> <em>(emacs_env *<var>env</var>, emacs_value <code>arg</code>)</em> +</dt> <dd><p>This function returns the type of <var>arg</var> as a value that represents a symbol: <code>string</code> for a string, <code>integer</code> for an integer, <code>process</code> for a process, etc. See <a href="type-predicates">Type Predicates</a>. You can use <code>intern</code> and <code>eq</code> to compare against known type symbols, if your code needs to depend on the object type. </p></dd> +</dl> <dl> <dt id="intern">Function: <em>emacs_value</em> <strong>intern</strong> <em>(emacs_env *<var>env</var>, const char *name)</em> +</dt> <dd> +<p>This function returns an interned Emacs symbol whose name is <var>name</var>, which should be an <acronym>ASCII</acronym> null-terminated string. It creates a new symbol if one does not already exist. </p> <p>Together with <code>funcall</code>, described below, this function provides a means for invoking any Lisp-callable Emacs function, provided that its name is a pure <acronym>ASCII</acronym> string. For example, here’s how to intern a symbol whose name <code>name_str</code> is non-<acronym>ASCII</acronym>, by calling the more powerful Emacs <code>intern</code> function (see <a href="creating-symbols">Creating Symbols</a>): </p> <div class="example"> <pre class="example">emacs_value fintern = env->intern (env, "intern"); +emacs_value sym_name = + env->make_string (env, name_str, strlen (name_str)); +emacs_value symbol = env->funcall (env, fintern, 1, &sym_name); +</pre> +</div> </dd> +</dl> <dl> <dt id="funcall">Function: <em>emacs_value</em> <strong>funcall</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>func</var>, ptrdiff_t <var>nargs</var>, emacs_value *<var>args</var>)</em> +</dt> <dd> +<p>This function calls the specified <var>func</var> passing it <var>nargs</var> arguments from the array pointed to by <var>args</var>. The argument <var>func</var> can be a function symbol (e.g., returned by <code>intern</code> described above), a module function returned by <code>make_function</code> (see <a href="module-functions">Module Functions</a>), a subroutine written in C, etc. If <var>nargs</var> is zero, <var>args</var> can be a <code>NULL</code> pointer. </p> <p>The function returns the value that <var>func</var> returned. </p> +</dd> +</dl> <p>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</kbd> (see <a href="quitting">Quitting</a>). The following function, which is available since Emacs 26.1, is provided for that purpose. </p> <dl> <dt id="should_quit">Function: <em>bool</em> <strong>should_quit</strong> <em>(emacs_env *<var>env</var>)</em> +</dt> <dd><p>This function returns <code>true</code> 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. In most cases, use <code>process_input</code> instead. </p></dd> +</dl> <p>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. </p> <dl> <dt id="process_input">Function: <em>enum emacs_process_input_result</em> <strong>process_input</strong> <em>(emacs_env *<var>env</var>)</em> +</dt> <dd><p>This function processes pending input events. It returns <code>emacs_process_input_quit</code> 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</code> returns <code>emacs_process_input_continue</code>. The return value is <code>emacs_process_input_continue</code> if and only if there is no pending nonlocal exit in <code>env</code>. If the module continues after calling <code>process_input</code>, global state such as variable values and buffer content may have been modified in arbitrary ways. </p></dd> +</dl> <dl> <dt id="open_channel">Function: <em>int</em> <strong>open_channel</strong> <em>(emacs_env *<var>env</var>, emacs_value <var>pipe_process</var>)</em> +</dt> <dd><p>This function, which is available since Emacs 28, opens a channel to an existing pipe process. <var>pipe_process</var> must refer to an existing pipe process created by <code>make-pipe-process</code>. <a href="asynchronous-processes#Pipe-Processes">Pipe Processes</a>. 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</code> function to write to the file descriptor. Once done, close the file descriptor using <code>close</code>. <a href="https://www.gnu.org/software/libc/manual/html_node/Low_002dLevel-I_002fO.html#Low_002dLevel-I_002fO">(libc)Low-Level I/O</a>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Module-Misc.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Module-Misc.html</a> + </p> +</div> |