1 /* emacs-module.h - GNU Emacs module API.
2 
3    Copyright (C) 2015-2020 Free Software Foundation, Inc.
4 
5    This file is part of GNU Emacs.
6 
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.
11 
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.
16 
17    You should have received a copy of the GNU General Public License
18    along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
19 
20 /*
21   This file defines the Emacs module API.  Please see the chapter
22   `Dynamic Modules' in the GNU Emacs Lisp Reference Manual for
23   information how to write modules and use this header file.
24 */
25 
26 module emacs_module.deimos;
27 
28 import core.stdc.config;
29 import core.stdc.stdint;
30 import core.sys.posix.time;
31 
32 extern(C):
33 
34 /* Current environment.  */
35 version (Emacs25) {
36   alias emacs_env = emacs_env_25;
37 } else version (Emacs26) {
38   alias emacs_env = emacs_env_26;
39 } else version (Emacs27) {
40   alias emacs_env = emacs_env_27;
41 } else {
42   // Default version.
43   alias emacs_env = emacs_env_27;
44 }
45 
46 /* Opaque pointer representing an Emacs Lisp value.
47    BEWARE: Do not assume NULL is a valid value!  */
48 alias emacs_value = emacs_value_tag*;
49 struct emacs_value_tag;
50 
51 enum emacs_variadic_function = -2;
52 
53 /* Struct passed to a module init function (emacs_module_init).  */
54 struct emacs_runtime {
55   @nogc nothrow:
56 
57   /* Structure size (for version checking).  */
58   c_long size;
59 
60   /* Private data; users should not touch this.  */
61   emacs_runtime_private* private_members;
62 
63   /* Return an environment pointer.  */
64   emacs_env* function(emacs_runtime*) get_environment;
65 }
66 
67 /* Possible Emacs function call outcomes.  */
68 enum emacs_funcall_exit {
69   /* Function has returned normally.  */
70   emacs_funcall_exit_return = 0,
71 
72   /* Function has signaled an error using `signal'.  */
73   emacs_funcall_exit_signal = 1,
74 
75   /* Function has exit using `throw'.  */
76   emacs_funcall_exit_throw = 2
77 }
78 enum emacs_funcall_exit_return = emacs_funcall_exit.emacs_funcall_exit_return;
79 enum emacs_funcall_exit_signal = emacs_funcall_exit.emacs_funcall_exit_signal;
80 enum emacs_funcall_exit_throw = emacs_funcall_exit.emacs_funcall_exit_throw;
81 
82 /* Possible return values for emacs_env.process_input.  */
83 enum emacs_process_input_result {
84   /* Module code may continue  */
85   emacs_process_input_continue = 0,
86 
87   /* Module code should return control to Emacs as soon as possible.  */
88   emacs_process_input_quit = 1
89 }
90 enum emacs_process_input_continue = emacs_process_input_result.emacs_process_input_continue;
91 enum emacs_process_input_quit = emacs_process_input_result.emacs_process_input_quit;
92 
93 /* Define emacs_limb_t so that it is likely to match GMP's mp_limb_t.
94    This micro-optimization can help modules that use mpz_export and
95    mpz_import, which operate more efficiently on mp_limb_t.  It's OK
96    (if perhaps a bit slower) if the two types do not match, and
97    modules shouldn't rely on the two types matching.  */
98 alias emacs_limb_t = c_ulong;
99 enum EMACS_LIMB_MAX = SIZE_MAX;
100 
101 struct emacs_env_25 {
102   @nogc nothrow:
103 
104   /* Structure size (for version checking).  */
105   c_long size;
106 
107   /* Private data; users should not touch this.  */
108   emacs_env_private* private_members;
109 
110   /* Memory management.  */
111 
112   emacs_value function(emacs_env*, emacs_value) make_global_ref;
113 
114   void function(emacs_env*, emacs_value) free_global_ref;
115 
116   /* Non-local exit handling.  */
117 
118   emacs_funcall_exit function(emacs_env*) non_local_exit_check;
119 
120   void function(emacs_env*) non_local_exit_clear;
121 
122   emacs_funcall_exit function(emacs_env*, emacs_value*, emacs_value*) non_local_exit_get;
123 
124   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_signal;
125 
126   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_throw;
127 
128   /* Function registration.  */
129 
130   emacs_value function(emacs_env*, c_long, c_long, emacs_value function(emacs_env*, c_long, emacs_value*, void*), const(char)*, void*) make_function;
131 
132   emacs_value function(emacs_env*, emacs_value, c_long, emacs_value*) funcall;
133 
134   emacs_value function(emacs_env*, const(char)*) intern;
135 
136   /* Type conversion.  */
137 
138   emacs_value function(emacs_env*, emacs_value) type_of;
139 
140   bool function(emacs_env*, emacs_value) is_not_nil;
141 
142   bool function(emacs_env*, emacs_value, emacs_value) eq;
143 
144   c_long function(emacs_env*, emacs_value) extract_integer;
145 
146   emacs_value function(emacs_env*, c_long) make_integer;
147 
148   double function(emacs_env*, emacs_value) extract_float;
149 
150   emacs_value function(emacs_env*, double) make_float;
151 
152   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
153      NUL-terminated string.
154 
155      SIZE must point to the total size of the buffer.  If BUFFER is
156      NULL or if SIZE is not big enough, write the required buffer size
157      to SIZE and return true.
158 
159      Note that SIZE must include the last NUL byte (e.g. "abc" needs
160      a buffer of size 4).
161 
162      Return true if the string was successfully copied.  */
163   bool function(emacs_env*, emacs_value, char*, c_long*) copy_string_contents;
164 
165   /* Create a Lisp string from a utf8 encoded string.  */
166   emacs_value function(emacs_env*, const(char)*, c_long) make_string;
167 
168   /* Embedded pointer type.  */
169   emacs_value function(emacs_env*, void function(void*), void*) make_user_ptr;
170 
171   void* function(emacs_env*, emacs_value) get_user_ptr;
172 
173   void function(emacs_env*, emacs_value, void*) set_user_ptr;
174 
175   void function(void*) function(emacs_env*, emacs_value) get_user_finalizer;
176 
177   void function(emacs_env*, emacs_value, void function(void*)) set_user_finalizer;
178 
179   /* Vector functions.  */
180 
181   emacs_value function(emacs_env*, emacs_value, c_long) vec_get;
182 
183   void function(emacs_env*, emacs_value, c_long, emacs_value) vec_set;
184 
185   c_long function(emacs_env*, emacs_value) vec_size;
186 }
187 
188 struct emacs_env_26 {
189   @nogc nothrow:
190 
191   /* Structure size (for version checking).  */
192   c_long size;
193 
194   /* Private data; users should not touch this.  */
195   emacs_env_private* private_members;
196 
197   /* Memory management.  */
198 
199   emacs_value function(emacs_env*, emacs_value) make_global_ref;
200 
201   void function(emacs_env*, emacs_value) free_global_ref;
202 
203   /* Non-local exit handling.  */
204 
205   emacs_funcall_exit function(emacs_env*) non_local_exit_check;
206 
207   void function(emacs_env*) non_local_exit_clear;
208 
209   emacs_funcall_exit function(emacs_env*, emacs_value*, emacs_value*) non_local_exit_get;
210 
211   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_signal;
212 
213   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_throw;
214 
215   /* Function registration.  */
216 
217   emacs_value function(emacs_env*, c_long, c_long, emacs_value function(emacs_env*, c_long, emacs_value*, void*), const(char)*, void*) make_function;
218 
219   emacs_value function(emacs_env*, emacs_value, c_long, emacs_value*) funcall;
220 
221   emacs_value function(emacs_env*, const(char)*) intern;
222 
223   /* Type conversion.  */
224 
225   emacs_value function(emacs_env*, emacs_value) type_of;
226 
227   bool function(emacs_env*, emacs_value) is_not_nil;
228 
229   bool function(emacs_env*, emacs_value, emacs_value) eq;
230 
231   c_long function(emacs_env*, emacs_value) extract_integer;
232 
233   emacs_value function(emacs_env*, c_long) make_integer;
234 
235   double function(emacs_env*, emacs_value) extract_float;
236 
237   emacs_value function(emacs_env*, double) make_float;
238 
239   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
240      NUL-terminated string.
241 
242      SIZE must point to the total size of the buffer.  If BUFFER is
243      NULL or if SIZE is not big enough, write the required buffer size
244      to SIZE and return true.
245 
246      Note that SIZE must include the last NUL byte (e.g. "abc" needs
247      a buffer of size 4).
248 
249      Return true if the string was successfully copied.  */
250   bool function(emacs_env*, emacs_value, char*, c_long*) copy_string_contents;
251 
252   /* Create a Lisp string from a utf8 encoded string.  */
253   emacs_value function(emacs_env*, const(char)*, c_long) make_string;
254 
255   /* Embedded pointer type.  */
256   emacs_value function(emacs_env*, void function(void*), void*) make_user_ptr;
257 
258   void* function(emacs_env*, emacs_value) get_user_ptr;
259 
260   void function(emacs_env*, emacs_value, void*) set_user_ptr;
261 
262   void function(void*) function(emacs_env*, emacs_value) get_user_finalizer;
263 
264   void function(emacs_env*, emacs_value, void function(void*)) set_user_finalizer;
265 
266   /* Vector functions.  */
267 
268   emacs_value function(emacs_env*, emacs_value, c_long) vec_get;
269 
270   void function(emacs_env*, emacs_value, c_long, emacs_value) vec_set;
271 
272   c_long function(emacs_env*, emacs_value) vec_size;
273 
274   /* Returns whether a quit is pending.  */
275   bool function(emacs_env*) should_quit;
276 }
277 
278 struct emacs_env_27 {
279   @nogc nothrow:
280 
281   /* Structure size (for version checking).  */
282   c_long size;
283 
284   /* Private data; users should not touch this.  */
285   emacs_env_private* private_members;
286 
287   /* Memory management.  */
288 
289   emacs_value function(emacs_env*, emacs_value) make_global_ref;
290 
291   void function(emacs_env*, emacs_value) free_global_ref;
292 
293   /* Non-local exit handling.  */
294 
295   emacs_funcall_exit function(emacs_env*) non_local_exit_check;
296 
297   void function(emacs_env*) non_local_exit_clear;
298 
299   emacs_funcall_exit function(emacs_env*, emacs_value*, emacs_value*) non_local_exit_get;
300 
301   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_signal;
302 
303   void function(emacs_env*, emacs_value, emacs_value) non_local_exit_throw;
304 
305   /* Function registration.  */
306 
307   emacs_value function(emacs_env*, c_long, c_long, emacs_value function(emacs_env*, c_long, emacs_value*, void*), const(char)*, void*) make_function;
308 
309   emacs_value function(emacs_env*, emacs_value, c_long, emacs_value*) funcall;
310 
311   emacs_value function(emacs_env*, const(char)*) intern;
312 
313   /* Type conversion.  */
314 
315   emacs_value function(emacs_env*, emacs_value) type_of;
316 
317   bool function(emacs_env*, emacs_value) is_not_nil;
318 
319   bool function(emacs_env*, emacs_value, emacs_value) eq;
320 
321   c_long function(emacs_env*, emacs_value) extract_integer;
322 
323   emacs_value function(emacs_env*, c_long) make_integer;
324 
325   double function(emacs_env*, emacs_value) extract_float;
326 
327   emacs_value function(emacs_env*, double) make_float;
328 
329   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
330      NUL-terminated string.
331 
332      SIZE must point to the total size of the buffer.  If BUFFER is
333      NULL or if SIZE is not big enough, write the required buffer size
334      to SIZE and return true.
335 
336      Note that SIZE must include the last NUL byte (e.g. "abc" needs
337      a buffer of size 4).
338 
339      Return true if the string was successfully copied.  */
340   bool function(emacs_env*, emacs_value, char*, c_long*) copy_string_contents;
341 
342   /* Create a Lisp string from a utf8 encoded string.  */
343   emacs_value function(emacs_env*, const(char)*, c_long) make_string;
344 
345   /* Embedded pointer type.  */
346   emacs_value function(emacs_env*, void function(void*), void*) make_user_ptr;
347 
348   void* function(emacs_env*, emacs_value) get_user_ptr;
349 
350   void function(emacs_env*, emacs_value, void*) set_user_ptr;
351 
352   void function(void*) function(emacs_env*, emacs_value) get_user_finalizer;
353 
354   void function(emacs_env*, emacs_value, void function(void*)) set_user_finalizer;
355 
356   /* Vector functions.  */
357 
358   emacs_value function(emacs_env*, emacs_value, c_long) vec_get;
359 
360   void function(emacs_env*, emacs_value, c_long, emacs_value) vec_set;
361 
362   c_long function(emacs_env*, emacs_value) vec_size;
363 
364   /* Returns whether a quit is pending.  */
365   bool function(emacs_env*) should_quit;
366 
367   /* Processes pending input events and returns whether the module
368      function should quit.  */
369   emacs_process_input_result function(emacs_env*) process_input;
370 
371   timespec function(emacs_env*, emacs_value) extract_time;
372 
373   emacs_value function(emacs_env*, timespec) make_time;
374 
375   bool function(emacs_env*, emacs_value, int*, c_long*, c_ulong*) extract_big_integer;
376 
377   emacs_value function(emacs_env*, int, c_long, const(c_ulong)*) make_big_integer;
378 }
379 
380 /* Every module should define a function as follows.  */
381 int emacs_module_init(emacs_runtime*) @nogc nothrow;
382 
383 struct emacs_env_private;
384 struct emacs_runtime_private;