Merge from origin/emacs-25
[emacs.git] / src / emacs-module.h
blobae7311b05a7d7a687b9056c1af8774996320d001
1 /* emacs-module.h - GNU Emacs module API.
3 Copyright (C) 2015-2016 Free Software Foundation, Inc.
5 This file is part of GNU Emacs.
7 GNU Emacs is free software: you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or (at
10 your option) any later version.
12 GNU Emacs is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
20 #ifndef EMACS_MODULE_H
21 #define EMACS_MODULE_H
23 #include <stdint.h>
24 #include <stddef.h>
25 #include <stdbool.h>
27 #if defined __cplusplus && __cplusplus >= 201103L
28 # define EMACS_NOEXCEPT noexcept
29 #else
30 # define EMACS_NOEXCEPT
31 #endif
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
37 /* Current environment. */
38 typedef struct emacs_env_25 emacs_env;
40 /* Opaque pointer representing an Emacs Lisp value.
41 BEWARE: Do not assume NULL is a valid value! */
42 typedef struct emacs_value_tag *emacs_value;
44 enum { emacs_variadic_function = -2 };
46 /* Struct passed to a module init function (emacs_module_init). */
47 struct emacs_runtime
49 /* Structure size (for version checking). */
50 ptrdiff_t size;
52 /* Private data; users should not touch this. */
53 struct emacs_runtime_private *private_members;
55 /* Return an environment pointer. */
56 emacs_env *(*get_environment) (struct emacs_runtime *ert);
60 /* Possible Emacs function call outcomes. */
61 enum emacs_funcall_exit
63 /* Function has returned normally. */
64 emacs_funcall_exit_return = 0,
66 /* Function has signaled an error using `signal'. */
67 emacs_funcall_exit_signal = 1,
69 /* Function has exit using `throw'. */
70 emacs_funcall_exit_throw = 2,
73 struct emacs_env_25
75 /* Structure size (for version checking). */
76 ptrdiff_t size;
78 /* Private data; users should not touch this. */
79 struct emacs_env_private *private_members;
81 /* Memory management. */
83 emacs_value (*make_global_ref) (emacs_env *env,
84 emacs_value any_reference);
86 void (*free_global_ref) (emacs_env *env,
87 emacs_value global_reference);
89 /* Non-local exit handling. */
91 enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env);
93 void (*non_local_exit_clear) (emacs_env *env);
95 enum emacs_funcall_exit (*non_local_exit_get)
96 (emacs_env *env,
97 emacs_value *non_local_exit_symbol_out,
98 emacs_value *non_local_exit_data_out);
100 void (*non_local_exit_signal) (emacs_env *env,
101 emacs_value non_local_exit_symbol,
102 emacs_value non_local_exit_data);
104 void (*non_local_exit_throw) (emacs_env *env,
105 emacs_value tag,
106 emacs_value value);
108 /* Function registration. */
110 emacs_value (*make_function) (emacs_env *env,
111 ptrdiff_t min_arity,
112 ptrdiff_t max_arity,
113 emacs_value (*function) (emacs_env *env,
114 ptrdiff_t nargs,
115 emacs_value args[],
116 void *)
117 EMACS_NOEXCEPT,
118 const char *documentation,
119 void *data);
121 emacs_value (*funcall) (emacs_env *env,
122 emacs_value function,
123 ptrdiff_t nargs,
124 emacs_value args[]);
126 emacs_value (*intern) (emacs_env *env,
127 const char *symbol_name);
129 /* Type conversion. */
131 emacs_value (*type_of) (emacs_env *env,
132 emacs_value value);
134 bool (*is_not_nil) (emacs_env *env, emacs_value value);
136 bool (*eq) (emacs_env *env, emacs_value a, emacs_value b);
138 intmax_t (*extract_integer) (emacs_env *env, emacs_value value);
140 emacs_value (*make_integer) (emacs_env *env, intmax_t value);
142 double (*extract_float) (emacs_env *env, emacs_value value);
144 emacs_value (*make_float) (emacs_env *env, double value);
146 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
147 null-terminated string.
149 SIZE must point to the total size of the buffer. If BUFFER is
150 NULL or if SIZE is not big enough, write the required buffer size
151 to SIZE and return false.
153 Note that SIZE must include the last null byte (e.g. "abc" needs
154 a buffer of size 4).
156 Return true if the string was successfully copied. */
158 bool (*copy_string_contents) (emacs_env *env,
159 emacs_value value,
160 char *buffer,
161 ptrdiff_t *size_inout);
163 /* Create a Lisp string from a utf8 encoded string. */
164 emacs_value (*make_string) (emacs_env *env,
165 const char *contents, ptrdiff_t length);
167 /* Embedded pointer type. */
168 emacs_value (*make_user_ptr) (emacs_env *env,
169 void (*fin) (void *) EMACS_NOEXCEPT,
170 void *ptr);
172 void *(*get_user_ptr) (emacs_env *env, emacs_value uptr);
173 void (*set_user_ptr) (emacs_env *env, emacs_value uptr, void *ptr);
175 void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr))
176 (void *) EMACS_NOEXCEPT;
177 void (*set_user_finalizer) (emacs_env *env,
178 emacs_value uptr,
179 void (*fin) (void *) EMACS_NOEXCEPT);
181 /* Vector functions. */
182 emacs_value (*vec_get) (emacs_env *env, emacs_value vec, ptrdiff_t i);
184 void (*vec_set) (emacs_env *env, emacs_value vec, ptrdiff_t i,
185 emacs_value val);
187 ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vec);
190 /* Every module should define a function as follows. */
191 extern int emacs_module_init (struct emacs_runtime *ert);
193 #ifdef __cplusplus
195 #endif
197 #endif /* EMACS_MODULE_H */