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