src/emacs-module.h

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