code.delx.au - gnu-emacs/blob - src/module.h

   1 /*
   2   module.h - Module API
   3   Copyright (C) 2015 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
  10   (at 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 <http://www.gnu.org/licenses/>.
  19 */
  20
  21 #ifndef EMACS_MODULE_H
  22 #define EMACS_MODULE_H
  23
  24 #include <stdint.h>
  25 #include <stdlib.h>
  26 #include <stdbool.h>
  27
  28 #ifdef __cplusplus
  29 #define EMACS_EXTERN_C_BEGIN extern "C" {
  30 #define EMACS_EXTERN_C_END }
  31 #else
  32 #define EMACS_EXTERN_C_BEGIN
  33 #define EMACS_EXTERN_C_END
  34 #endif
  35
  36 #if defined(__cplusplus) && __cplusplus >= 201103L
  37 #define EMACS_NOEXCEPT noexcept
  38 #else
  39 #define EMACS_NOEXCEPT
  40 #endif
  41
  42 EMACS_EXTERN_C_BEGIN
  43
  44 /* Current environement */
  45 typedef struct emacs_env_25 emacs_env;
  46
  47 /* Opaque structure pointer representing an Emacs Lisp value */
  48 typedef struct emacs_value_tag* emacs_value;
  49
  50 enum emacs_arity {
  51   emacs_variadic_function = -2
  52 };
  53
  54 /* Struct passed to a module init function (emacs_module_init) */
  55 struct emacs_runtime {
  56   /* Structure size (for version checking) */
  57   size_t size;
  58
  59   /* Private data; users should not touch this */
  60   struct emacs_runtime_private *private_members;
  61
  62   /* Returns an environment pointer. */
  63   emacs_env* (*get_environment)(struct emacs_runtime *ert);
  64 };
  65
  66
  67 /* Function prototype for the module init function */
  68 typedef int (*emacs_init_function)(struct emacs_runtime *ert);
  69
  70 /* Function prototype for the module Lisp functions */
  71 typedef emacs_value (*emacs_subr)(emacs_env *env,
  72                                   int nargs,
  73                                   emacs_value args[],
  74                                   void *data);
  75
  76 /* Function prototype for module user-pointer finalizers */
  77 typedef void (*emacs_finalizer_function)(void*);
  78
  79 /* Possible Emacs function call outcomes. */
  80 enum emacs_funcall_exit {
  81   /* Function has returned normally. */
  82   emacs_funcall_exit_return = 0,
  83   /* Function has signaled an error using `signal'. */
  84   emacs_funcall_exit_signal = 1,
  85   /* Function has exit using `throw'. */
  86   emacs_funcall_exit_throw = 2,
  87 };
  88
  89 struct emacs_env_25 {
  90   /*
  91    * Structure size (for version checking)
  92    */
  93
  94   size_t size;
  95
  96   /* Private data; users should not touch this */
  97   struct emacs_env_private *private_members;
  98
  99   /*
 100    * Memory management
 101    */
 102
 103
 104   emacs_value (*make_global_ref)(emacs_env *env,
 105                                  emacs_value any_reference);
 106
 107   void (*free_global_ref)(emacs_env *env,
 108                           emacs_value global_reference);
 109
 110   /*
 111    * Non-local exit handling
 112    */
 113
 114   enum emacs_funcall_exit (*non_local_exit_check)(emacs_env *env);
 115
 116   void (*non_local_exit_clear)(emacs_env *env);
 117
 118   enum emacs_funcall_exit (*non_local_exit_get)(emacs_env *env,
 119                                        emacs_value *non_local_exit_symbol_out,
 120                                        emacs_value *non_local_exit_data_out);
 121
 122   void (*non_local_exit_signal)(emacs_env *env,
 123                        emacs_value non_local_exit_symbol,
 124                        emacs_value non_local_exit_data);
 125
 126   void (*non_local_exit_throw)(emacs_env *env,
 127                       emacs_value tag,
 128                       emacs_value value);
 129
 130   /*
 131    * Function registration
 132    */
 133
 134   emacs_value (*make_function)(emacs_env *env,
 135                                int min_arity,
 136                                int max_arity,
 137                                emacs_value (*function)(emacs_env*, int, emacs_value*, void*) EMACS_NOEXCEPT,
 138                                const char *documentation,
 139                                void *data);
 140
 141   emacs_value (*funcall)(emacs_env *env,
 142                          emacs_value function,
 143                          int nargs,
 144                          emacs_value args[]);
 145
 146   emacs_value (*intern)(emacs_env *env,
 147                         const char *symbol_name);
 148
 149   /*
 150    * Type conversion
 151    */
 152
 153   emacs_value (*type_of)(emacs_env *env,
 154                          emacs_value value);
 155
 156   bool (*is_not_nil)(emacs_env *env, emacs_value value);
 157
 158   bool (*eq)(emacs_env *env, emacs_value a, emacs_value b);
 159
 160   int64_t (*extract_integer)(emacs_env *env,
 161                              emacs_value value);
 162
 163   emacs_value (*make_integer)(emacs_env *env,
 164                               int64_t value);
 165
 166   double (*extract_float)(emacs_env *env,
 167                           emacs_value value);
 168
 169   emacs_value (*make_float)(emacs_env *env,
 170                             double value);
 171
 172   /*
 173    * Copy the content of the lisp string VALUE to BUFFER as an utf8
 174    * null-terminated string.
 175    *
 176    * SIZE must point to the total size of the buffer.  If BUFFER is
 177    * NULL or if SIZE is not big enough, write the required buffer size
 178    * to SIZE and return false.
 179    *
 180    * Note that SIZE must include the last null byte (e.g. "abc" needs
 181    * a buffer of size 4).
 182    *
 183    * Returns true if the string was successfully copied.
 184    */
 185
 186   bool (*copy_string_contents)(emacs_env *env,
 187                                emacs_value value,
 188                                char *buffer,
 189                                size_t *size_inout);
 190
 191   /*
 192    * Create a lisp string from a utf8 encoded string.
 193    */
 194   emacs_value (*make_string)(emacs_env *env,
 195                              const char *contents, size_t length);
 196
 197   /*
 198    * Embedded pointer type
 199    */
 200   emacs_value (*make_user_ptr)(emacs_env *env,
 201                                void (*fin)(void *) EMACS_NOEXCEPT,
 202                                void *ptr);
 203
 204   void* (*get_user_ptr)(emacs_env *env, emacs_value uptr);
 205   void (*set_user_ptr)(emacs_env *env, emacs_value uptr, void *ptr);
 206
 207   void (*(*get_user_finalizer)(emacs_env *env, emacs_value uptr))(void *) EMACS_NOEXCEPT;
 208   void (*set_user_finalizer)(emacs_env *env,
 209                              emacs_value uptr,
 210                              void (*fin)(void *) EMACS_NOEXCEPT);
 211
 212   /*
 213    * Vector functions
 214    */
 215   emacs_value (*vec_get) (emacs_env *env,
 216                           emacs_value vec,
 217                           size_t i);
 218
 219   void (*vec_set) (emacs_env *env,
 220                    emacs_value vec,
 221                    size_t i,
 222                    emacs_value val);
 223
 224   size_t (*vec_size) (emacs_env *env,
 225                       emacs_value vec);
 226 };
 227
 228 EMACS_EXTERN_C_END
 229
 230 #endif /* EMACS_MODULE_H */