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