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;