src/emacs-module.h

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