emacs-module.h (11343B)
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 <stddef.h> 24 #include <stdint.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_25 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 /* Structure size (for version checking). */ 61 ptrdiff_t size; 62 63 /* Private data; users should not touch this. */ 64 struct emacs_runtime_private *private_members; 65 66 /* Return an environment pointer. */ 67 emacs_env *(*get_environment)(struct emacs_runtime *ert) 68 EMACS_ATTRIBUTE_NONNULL(1); 69 }; 70 71 /* Possible Emacs function call outcomes. */ 72 enum emacs_funcall_exit { 73 /* Function has returned normally. */ 74 emacs_funcall_exit_return = 0, 75 76 /* Function has signaled an error using `signal'. */ 77 emacs_funcall_exit_signal = 1, 78 79 /* Function has exit using `throw'. */ 80 emacs_funcall_exit_throw = 2 81 }; 82 83 struct emacs_env_25 { 84 /* Structure size (for version checking). */ 85 ptrdiff_t size; 86 87 /* Private data; users should not touch this. */ 88 struct emacs_env_private *private_members; 89 90 /* Memory management. */ 91 92 emacs_value (*make_global_ref)(emacs_env *env, emacs_value any_reference) 93 EMACS_ATTRIBUTE_NONNULL(1); 94 95 void (*free_global_ref)(emacs_env *env, emacs_value global_reference) 96 EMACS_ATTRIBUTE_NONNULL(1); 97 98 /* Non-local exit handling. */ 99 100 enum emacs_funcall_exit (*non_local_exit_check)(emacs_env *env) 101 EMACS_ATTRIBUTE_NONNULL(1); 102 103 void (*non_local_exit_clear)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1); 104 105 enum emacs_funcall_exit (*non_local_exit_get)( 106 emacs_env *env, emacs_value *non_local_exit_symbol_out, 107 emacs_value *non_local_exit_data_out) EMACS_ATTRIBUTE_NONNULL(1, 2, 3); 108 109 void (*non_local_exit_signal)(emacs_env *env, 110 emacs_value non_local_exit_symbol, 111 emacs_value non_local_exit_data) 112 EMACS_ATTRIBUTE_NONNULL(1); 113 114 void (*non_local_exit_throw)(emacs_env *env, emacs_value tag, 115 emacs_value value) EMACS_ATTRIBUTE_NONNULL(1); 116 117 /* Function registration. */ 118 119 emacs_value (*make_function)( 120 emacs_env *env, ptrdiff_t min_arity, ptrdiff_t max_arity, 121 emacs_value (*function)(emacs_env *env, ptrdiff_t nargs, 122 emacs_value args[], void *) 123 EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1), 124 const char *documentation, void *data) EMACS_ATTRIBUTE_NONNULL(1, 4); 125 126 emacs_value (*funcall)(emacs_env *env, emacs_value function, ptrdiff_t nargs, 127 emacs_value args[]) EMACS_ATTRIBUTE_NONNULL(1); 128 129 emacs_value (*intern)(emacs_env *env, const char *symbol_name) 130 EMACS_ATTRIBUTE_NONNULL(1, 2); 131 132 /* Type conversion. */ 133 134 emacs_value (*type_of)(emacs_env *env, emacs_value value) 135 EMACS_ATTRIBUTE_NONNULL(1); 136 137 bool (*is_not_nil)(emacs_env *env, emacs_value value) 138 EMACS_ATTRIBUTE_NONNULL(1); 139 140 bool (*eq)(emacs_env *env, emacs_value a, emacs_value b) 141 EMACS_ATTRIBUTE_NONNULL(1); 142 143 intmax_t (*extract_integer)(emacs_env *env, emacs_value value) 144 EMACS_ATTRIBUTE_NONNULL(1); 145 146 emacs_value (*make_integer)(emacs_env *env, intmax_t value) 147 EMACS_ATTRIBUTE_NONNULL(1); 148 149 double (*extract_float)(emacs_env *env, emacs_value value) 150 EMACS_ATTRIBUTE_NONNULL(1); 151 152 emacs_value (*make_float)(emacs_env *env, double value) 153 EMACS_ATTRIBUTE_NONNULL(1); 154 155 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8 156 null-terminated string. 157 158 SIZE must point to the total size of the buffer. If BUFFER is 159 NULL or if SIZE is not big enough, write the required buffer size 160 to SIZE and return true. 161 162 Note that SIZE must include the last null byte (e.g. "abc" needs 163 a buffer of size 4). 164 165 Return true if the string was successfully copied. */ 166 167 bool (*copy_string_contents)(emacs_env *env, emacs_value value, char *buffer, 168 ptrdiff_t *size_inout) 169 EMACS_ATTRIBUTE_NONNULL(1, 4); 170 171 /* Create a Lisp string from a utf8 encoded string. */ 172 emacs_value (*make_string)(emacs_env *env, const char *contents, 173 ptrdiff_t length) EMACS_ATTRIBUTE_NONNULL(1, 2); 174 175 /* Embedded pointer type. */ 176 emacs_value (*make_user_ptr)(emacs_env *env, 177 void (*fin)(void *) EMACS_NOEXCEPT, void *ptr) 178 EMACS_ATTRIBUTE_NONNULL(1); 179 180 void *(*get_user_ptr)(emacs_env *env, 181 emacs_value uptr)EMACS_ATTRIBUTE_NONNULL(1); 182 void (*set_user_ptr)(emacs_env *env, emacs_value uptr, void *ptr) 183 EMACS_ATTRIBUTE_NONNULL(1); 184 185 void (*(*get_user_finalizer)(emacs_env *env, 186 emacs_value uptr))(void *) EMACS_NOEXCEPT 187 EMACS_ATTRIBUTE_NONNULL(1); 188 void (*set_user_finalizer)(emacs_env *env, emacs_value uptr, 189 void (*fin)(void *) EMACS_NOEXCEPT) 190 EMACS_ATTRIBUTE_NONNULL(1); 191 192 /* Vector functions. */ 193 emacs_value (*vec_get)(emacs_env *env, emacs_value vec, ptrdiff_t i) 194 EMACS_ATTRIBUTE_NONNULL(1); 195 196 void (*vec_set)(emacs_env *env, emacs_value vec, ptrdiff_t i, emacs_value val) 197 EMACS_ATTRIBUTE_NONNULL(1); 198 199 ptrdiff_t (*vec_size)(emacs_env *env, emacs_value vec) 200 EMACS_ATTRIBUTE_NONNULL(1); 201 }; 202 203 struct emacs_env_26 { 204 /* Structure size (for version checking). */ 205 ptrdiff_t size; 206 207 /* Private data; users should not touch this. */ 208 struct emacs_env_private *private_members; 209 210 /* Memory management. */ 211 212 emacs_value (*make_global_ref)(emacs_env *env, emacs_value any_reference) 213 EMACS_ATTRIBUTE_NONNULL(1); 214 215 void (*free_global_ref)(emacs_env *env, emacs_value global_reference) 216 EMACS_ATTRIBUTE_NONNULL(1); 217 218 /* Non-local exit handling. */ 219 220 enum emacs_funcall_exit (*non_local_exit_check)(emacs_env *env) 221 EMACS_ATTRIBUTE_NONNULL(1); 222 223 void (*non_local_exit_clear)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1); 224 225 enum emacs_funcall_exit (*non_local_exit_get)( 226 emacs_env *env, emacs_value *non_local_exit_symbol_out, 227 emacs_value *non_local_exit_data_out) EMACS_ATTRIBUTE_NONNULL(1, 2, 3); 228 229 void (*non_local_exit_signal)(emacs_env *env, 230 emacs_value non_local_exit_symbol, 231 emacs_value non_local_exit_data) 232 EMACS_ATTRIBUTE_NONNULL(1); 233 234 void (*non_local_exit_throw)(emacs_env *env, emacs_value tag, 235 emacs_value value) EMACS_ATTRIBUTE_NONNULL(1); 236 237 /* Function registration. */ 238 239 emacs_value (*make_function)( 240 emacs_env *env, ptrdiff_t min_arity, ptrdiff_t max_arity, 241 emacs_value (*function)(emacs_env *env, ptrdiff_t nargs, 242 emacs_value args[], void *) 243 EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1), 244 const char *documentation, void *data) EMACS_ATTRIBUTE_NONNULL(1, 4); 245 246 emacs_value (*funcall)(emacs_env *env, emacs_value function, ptrdiff_t nargs, 247 emacs_value args[]) EMACS_ATTRIBUTE_NONNULL(1); 248 249 emacs_value (*intern)(emacs_env *env, const char *symbol_name) 250 EMACS_ATTRIBUTE_NONNULL(1, 2); 251 252 /* Type conversion. */ 253 254 emacs_value (*type_of)(emacs_env *env, emacs_value value) 255 EMACS_ATTRIBUTE_NONNULL(1); 256 257 bool (*is_not_nil)(emacs_env *env, emacs_value value) 258 EMACS_ATTRIBUTE_NONNULL(1); 259 260 bool (*eq)(emacs_env *env, emacs_value a, emacs_value b) 261 EMACS_ATTRIBUTE_NONNULL(1); 262 263 intmax_t (*extract_integer)(emacs_env *env, emacs_value value) 264 EMACS_ATTRIBUTE_NONNULL(1); 265 266 emacs_value (*make_integer)(emacs_env *env, intmax_t value) 267 EMACS_ATTRIBUTE_NONNULL(1); 268 269 double (*extract_float)(emacs_env *env, emacs_value value) 270 EMACS_ATTRIBUTE_NONNULL(1); 271 272 emacs_value (*make_float)(emacs_env *env, double value) 273 EMACS_ATTRIBUTE_NONNULL(1); 274 275 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8 276 null-terminated string. 277 278 SIZE must point to the total size of the buffer. If BUFFER is 279 NULL or if SIZE is not big enough, write the required buffer size 280 to SIZE and return true. 281 282 Note that SIZE must include the last null byte (e.g. "abc" needs 283 a buffer of size 4). 284 285 Return true if the string was successfully copied. */ 286 287 bool (*copy_string_contents)(emacs_env *env, emacs_value value, char *buffer, 288 ptrdiff_t *size_inout) 289 EMACS_ATTRIBUTE_NONNULL(1, 4); 290 291 /* Create a Lisp string from a utf8 encoded string. */ 292 emacs_value (*make_string)(emacs_env *env, const char *contents, 293 ptrdiff_t length) EMACS_ATTRIBUTE_NONNULL(1, 2); 294 295 /* Embedded pointer type. */ 296 emacs_value (*make_user_ptr)(emacs_env *env, 297 void (*fin)(void *) EMACS_NOEXCEPT, void *ptr) 298 EMACS_ATTRIBUTE_NONNULL(1); 299 300 void *(*get_user_ptr)(emacs_env *env, 301 emacs_value uptr)EMACS_ATTRIBUTE_NONNULL(1); 302 void (*set_user_ptr)(emacs_env *env, emacs_value uptr, void *ptr) 303 EMACS_ATTRIBUTE_NONNULL(1); 304 305 void (*(*get_user_finalizer)(emacs_env *env, 306 emacs_value uptr))(void *) EMACS_NOEXCEPT 307 EMACS_ATTRIBUTE_NONNULL(1); 308 void (*set_user_finalizer)(emacs_env *env, emacs_value uptr, 309 void (*fin)(void *) EMACS_NOEXCEPT) 310 EMACS_ATTRIBUTE_NONNULL(1); 311 312 /* Vector functions. */ 313 emacs_value (*vec_get)(emacs_env *env, emacs_value vec, ptrdiff_t i) 314 EMACS_ATTRIBUTE_NONNULL(1); 315 316 void (*vec_set)(emacs_env *env, emacs_value vec, ptrdiff_t i, emacs_value val) 317 EMACS_ATTRIBUTE_NONNULL(1); 318 319 ptrdiff_t (*vec_size)(emacs_env *env, emacs_value vec) 320 EMACS_ATTRIBUTE_NONNULL(1); 321 322 /* Returns whether a quit is pending. */ 323 bool (*should_quit)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1); 324 }; 325 326 /* Every module should define a function as follows. */ 327 extern int emacs_module_init(struct emacs_runtime *ert) EMACS_NOEXCEPT 328 EMACS_ATTRIBUTE_NONNULL(1); 329 330 #ifdef __cplusplus 331 } 332 #endif 333 334 #endif /* EMACS_MODULE_H */