1 /* emacs-module.h - GNU Emacs module API. 2 3 Copyright (C) 2015-2018 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 #ifndef EMACS_MODULE_H 21 #define EMACS_MODULE_H 22 23 #include <stdint.h> 24 #include <stddef.h> 25 26 #ifndef __cplusplus 27 #include <stdbool.h> 28 #endif 29 30 #if defined __cplusplus && __cplusplus >= 201103L 31 # define EMACS_NOEXCEPT noexcept 32 #else 33 # define EMACS_NOEXCEPT 34 #endif 35 36 #ifdef __has_attribute 37 #if __has_attribute(__nonnull__) 38 # define EMACS_ATTRIBUTE_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__))) 39 #endif 40 #endif 41 #ifndef EMACS_ATTRIBUTE_NONNULL 42 # define EMACS_ATTRIBUTE_NONNULL(...) 43 #endif 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /* Current environment. */ 50 typedef struct emacs_env_26 emacs_env; 51 52 /* Opaque pointer representing an Emacs Lisp value. 53 BEWARE: Do not assume NULL is a valid value! */ 54 typedef struct emacs_value_tag *emacs_value; 55 56 enum { emacs_variadic_function = -2 }; 57 58 /* Struct passed to a module init function (emacs_module_init). */ 59 struct emacs_runtime 60 { 61 /* Structure size (for version checking). */ 62 ptrdiff_t size; 63 64 /* Private data; users should not touch this. */ 65 struct emacs_runtime_private *private_members; 66 67 /* Return an environment pointer. */ 68 emacs_env *(*get_environment) (struct emacs_runtime *ert) 69 EMACS_ATTRIBUTE_NONNULL(1); 70 }; 71 72 73 /* Possible Emacs function call outcomes. */ 74 enum emacs_funcall_exit 75 { 76 /* Function has returned normally. */ 77 emacs_funcall_exit_return = 0, 78 79 /* Function has signaled an error using `signal'. */ 80 emacs_funcall_exit_signal = 1, 81 82 /* Function has exit using `throw'. */ 83 emacs_funcall_exit_throw = 2 84 }; 85 86 struct emacs_env_25 87 { 88 /* Structure size (for version checking). */ 89 ptrdiff_t size; 90 91 /* Private data; users should not touch this. */ 92 struct emacs_env_private *private_members; 93 94 /* Memory management. */ 95 96 emacs_value (*make_global_ref) (emacs_env *env, 97 emacs_value any_reference) 98 EMACS_ATTRIBUTE_NONNULL(1); 99 100 void (*free_global_ref) (emacs_env *env, 101 emacs_value global_reference) 102 EMACS_ATTRIBUTE_NONNULL(1); 103 104 /* Non-local exit handling. */ 105 106 enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env) 107 EMACS_ATTRIBUTE_NONNULL(1); 108 109 void (*non_local_exit_clear) (emacs_env *env) 110 EMACS_ATTRIBUTE_NONNULL(1); 111 112 enum emacs_funcall_exit (*non_local_exit_get) 113 (emacs_env *env, 114 emacs_value *non_local_exit_symbol_out, 115 emacs_value *non_local_exit_data_out) 116 EMACS_ATTRIBUTE_NONNULL(1, 2, 3); 117 118 void (*non_local_exit_signal) (emacs_env *env, 119 emacs_value non_local_exit_symbol, 120 emacs_value non_local_exit_data) 121 EMACS_ATTRIBUTE_NONNULL(1); 122 123 void (*non_local_exit_throw) (emacs_env *env, 124 emacs_value tag, 125 emacs_value value) 126 EMACS_ATTRIBUTE_NONNULL(1); 127 128 /* Function registration. */ 129 130 emacs_value (*make_function) (emacs_env *env, 131 ptrdiff_t min_arity, 132 ptrdiff_t max_arity, 133 emacs_value (*function) (emacs_env *env, 134 ptrdiff_t nargs, 135 emacs_value args[], 136 void *) 137 EMACS_NOEXCEPT 138 EMACS_ATTRIBUTE_NONNULL(1), 139 const char *documentation, 140 void *data) 141 EMACS_ATTRIBUTE_NONNULL(1, 4); 142 143 emacs_value (*funcall) (emacs_env *env, 144 emacs_value function, 145 ptrdiff_t nargs, 146 emacs_value args[]) 147 EMACS_ATTRIBUTE_NONNULL(1); 148 149 emacs_value (*intern) (emacs_env *env, 150 const char *symbol_name) 151 EMACS_ATTRIBUTE_NONNULL(1, 2); 152 153 /* Type conversion. */ 154 155 emacs_value (*type_of) (emacs_env *env, 156 emacs_value value) 157 EMACS_ATTRIBUTE_NONNULL(1); 158 159 bool (*is_not_nil) (emacs_env *env, emacs_value value) 160 EMACS_ATTRIBUTE_NONNULL(1); 161 162 bool (*eq) (emacs_env *env, emacs_value a, emacs_value b) 163 EMACS_ATTRIBUTE_NONNULL(1); 164 165 intmax_t (*extract_integer) (emacs_env *env, emacs_value value) 166 EMACS_ATTRIBUTE_NONNULL(1); 167 168 emacs_value (*make_integer) (emacs_env *env, intmax_t value) 169 EMACS_ATTRIBUTE_NONNULL(1); 170 171 double (*extract_float) (emacs_env *env, emacs_value value) 172 EMACS_ATTRIBUTE_NONNULL(1); 173 174 emacs_value (*make_float) (emacs_env *env, double value) 175 EMACS_ATTRIBUTE_NONNULL(1); 176 177 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8 178 null-terminated string. 179 180 SIZE must point to the total size of the buffer. If BUFFER is 181 NULL or if SIZE is not big enough, write the required buffer size 182 to SIZE and return true. 183 184 Note that SIZE must include the last null byte (e.g. "abc" needs 185 a buffer of size 4). 186 187 Return true if the string was successfully copied. */ 188 189 bool (*copy_string_contents) (emacs_env *env, 190 emacs_value value, 191 char *buffer, 192 ptrdiff_t *size_inout) 193 EMACS_ATTRIBUTE_NONNULL(1, 4); 194 195 /* Create a Lisp string from a utf8 encoded string. */ 196 emacs_value (*make_string) (emacs_env *env, 197 const char *contents, ptrdiff_t length) 198 EMACS_ATTRIBUTE_NONNULL(1, 2); 199 200 /* Embedded pointer type. */ 201 emacs_value (*make_user_ptr) (emacs_env *env, 202 void (*fin) (void *) EMACS_NOEXCEPT, 203 void *ptr) 204 EMACS_ATTRIBUTE_NONNULL(1); 205 206 void *(*get_user_ptr) (emacs_env *env, emacs_value uptr) 207 EMACS_ATTRIBUTE_NONNULL(1); 208 void (*set_user_ptr) (emacs_env *env, emacs_value uptr, void *ptr) 209 EMACS_ATTRIBUTE_NONNULL(1); 210 211 void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr)) 212 (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1); 213 void (*set_user_finalizer) (emacs_env *env, 214 emacs_value uptr, 215 void (*fin) (void *) EMACS_NOEXCEPT) 216 EMACS_ATTRIBUTE_NONNULL(1); 217 218 /* Vector functions. */ 219 emacs_value (*vec_get) (emacs_env *env, emacs_value vec, ptrdiff_t i) 220 EMACS_ATTRIBUTE_NONNULL(1); 221 222 void (*vec_set) (emacs_env *env, emacs_value vec, ptrdiff_t i, 223 emacs_value val) 224 EMACS_ATTRIBUTE_NONNULL(1); 225 226 ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vec) 227 EMACS_ATTRIBUTE_NONNULL(1); 228 }; 229 230 struct emacs_env_26 231 { 232 /* Structure size (for version checking). */ 233 ptrdiff_t size; 234 235 /* Private data; users should not touch this. */ 236 struct emacs_env_private *private_members; 237 238 /* Memory management. */ 239 240 emacs_value (*make_global_ref) (emacs_env *env, 241 emacs_value any_reference) 242 EMACS_ATTRIBUTE_NONNULL(1); 243 244 void (*free_global_ref) (emacs_env *env, 245 emacs_value global_reference) 246 EMACS_ATTRIBUTE_NONNULL(1); 247 248 /* Non-local exit handling. */ 249 250 enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env) 251 EMACS_ATTRIBUTE_NONNULL(1); 252 253 void (*non_local_exit_clear) (emacs_env *env) 254 EMACS_ATTRIBUTE_NONNULL(1); 255 256 enum emacs_funcall_exit (*non_local_exit_get) 257 (emacs_env *env, 258 emacs_value *non_local_exit_symbol_out, 259 emacs_value *non_local_exit_data_out) 260 EMACS_ATTRIBUTE_NONNULL(1, 2, 3); 261 262 void (*non_local_exit_signal) (emacs_env *env, 263 emacs_value non_local_exit_symbol, 264 emacs_value non_local_exit_data) 265 EMACS_ATTRIBUTE_NONNULL(1); 266 267 void (*non_local_exit_throw) (emacs_env *env, 268 emacs_value tag, 269 emacs_value value) 270 EMACS_ATTRIBUTE_NONNULL(1); 271 272 /* Function registration. */ 273 274 emacs_value (*make_function) (emacs_env *env, 275 ptrdiff_t min_arity, 276 ptrdiff_t max_arity, 277 emacs_value (*function) (emacs_env *env, 278 ptrdiff_t nargs, 279 emacs_value args[], 280 void *) 281 EMACS_NOEXCEPT 282 EMACS_ATTRIBUTE_NONNULL(1), 283 const char *documentation, 284 void *data) 285 EMACS_ATTRIBUTE_NONNULL(1, 4); 286 287 emacs_value (*funcall) (emacs_env *env, 288 emacs_value function, 289 ptrdiff_t nargs, 290 emacs_value args[]) 291 EMACS_ATTRIBUTE_NONNULL(1); 292 293 emacs_value (*intern) (emacs_env *env, 294 const char *symbol_name) 295 EMACS_ATTRIBUTE_NONNULL(1, 2); 296 297 /* Type conversion. */ 298 299 emacs_value (*type_of) (emacs_env *env, 300 emacs_value value) 301 EMACS_ATTRIBUTE_NONNULL(1); 302 303 bool (*is_not_nil) (emacs_env *env, emacs_value value) 304 EMACS_ATTRIBUTE_NONNULL(1); 305 306 bool (*eq) (emacs_env *env, emacs_value a, emacs_value b) 307 EMACS_ATTRIBUTE_NONNULL(1); 308 309 intmax_t (*extract_integer) (emacs_env *env, emacs_value value) 310 EMACS_ATTRIBUTE_NONNULL(1); 311 312 emacs_value (*make_integer) (emacs_env *env, intmax_t value) 313 EMACS_ATTRIBUTE_NONNULL(1); 314 315 double (*extract_float) (emacs_env *env, emacs_value value) 316 EMACS_ATTRIBUTE_NONNULL(1); 317 318 emacs_value (*make_float) (emacs_env *env, double value) 319 EMACS_ATTRIBUTE_NONNULL(1); 320 321 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8 322 null-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 null byte (e.g. "abc" needs 329 a buffer of size 4). 330 331 Return true if the string was successfully copied. */ 332 333 bool (*copy_string_contents) (emacs_env *env, 334 emacs_value value, 335 char *buffer, 336 ptrdiff_t *size_inout) 337 EMACS_ATTRIBUTE_NONNULL(1, 4); 338 339 /* Create a Lisp string from a utf8 encoded string. */ 340 emacs_value (*make_string) (emacs_env *env, 341 const char *contents, ptrdiff_t length) 342 EMACS_ATTRIBUTE_NONNULL(1, 2); 343 344 /* Embedded pointer type. */ 345 emacs_value (*make_user_ptr) (emacs_env *env, 346 void (*fin) (void *) EMACS_NOEXCEPT, 347 void *ptr) 348 EMACS_ATTRIBUTE_NONNULL(1); 349 350 void *(*get_user_ptr) (emacs_env *env, emacs_value uptr) 351 EMACS_ATTRIBUTE_NONNULL(1); 352 void (*set_user_ptr) (emacs_env *env, emacs_value uptr, void *ptr) 353 EMACS_ATTRIBUTE_NONNULL(1); 354 355 void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr)) 356 (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1); 357 void (*set_user_finalizer) (emacs_env *env, 358 emacs_value uptr, 359 void (*fin) (void *) EMACS_NOEXCEPT) 360 EMACS_ATTRIBUTE_NONNULL(1); 361 362 /* Vector functions. */ 363 emacs_value (*vec_get) (emacs_env *env, emacs_value vec, ptrdiff_t i) 364 EMACS_ATTRIBUTE_NONNULL(1); 365 366 void (*vec_set) (emacs_env *env, emacs_value vec, ptrdiff_t i, 367 emacs_value val) 368 EMACS_ATTRIBUTE_NONNULL(1); 369 370 ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vec) 371 EMACS_ATTRIBUTE_NONNULL(1); 372 373 /* Returns whether a quit is pending. */ 374 bool (*should_quit) (emacs_env *env) 375 EMACS_ATTRIBUTE_NONNULL(1); 376 }; 377 378 /* Every module should define a function as follows. */ 379 extern int emacs_module_init (struct emacs_runtime *ert) 380 EMACS_NOEXCEPT 381 EMACS_ATTRIBUTE_NONNULL(1); 382 383 #ifdef __cplusplus 384 } 385 #endif 386 387 #endif /* EMACS_MODULE_H */ 388