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
  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 #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
  30 /* Function prototype for module user-pointer finalizers.
  31
  32    NOTE: C++11 15.4: An exception-specification shall not appear in a
  33                      typedef declaration or alias-declaration.
  34
  35 */
  36 void emacs_dummy_finalizer_function (void *) noexcept;
  37 typedef decltype(emacs_dummy_finalizer_function) *emacs_finalizer_function;
  38
  39 #else
  40 # define EMACS_NOEXCEPT
  41 typedef void (*emacs_finalizer_function) (void *);
  42 #endif
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 /* Current environment.  */
  49 typedef struct emacs_env_25 emacs_env;
  50
  51 /* Opaque pointer representing an Emacs Lisp value.
  52    BEWARE: Do not assume NULL is a valid value!  */
  53 typedef struct emacs_value_tag *emacs_value;
  54
  55 enum emacs_arity { emacs_variadic_function = -2 };
  56
  57 /* Struct passed to a module init function (emacs_module_init).  */
  58 struct emacs_runtime
  59 {
  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 };
  69
  70
  71 /* Function prototype for the module init function.  */
  72 typedef int (*emacs_init_function) (struct emacs_runtime *ert);
  73
  74 /* Function prototype for the module Lisp functions.  */
  75 typedef emacs_value (*emacs_subr) (emacs_env *env, ptrdiff_t nargs,
  76                                    emacs_value args[], void *data);
  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
 104   void (*free_global_ref) (emacs_env *env,
 105                            emacs_value global_reference);
 106
 107   /* Non-local exit handling.  */
 108
 109   enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env);
 110
 111   void (*non_local_exit_clear) (emacs_env *env);
 112
 113   enum emacs_funcall_exit (*non_local_exit_get)
 114     (emacs_env *env,
 115      emacs_value *non_local_exit_symbol_out,
 116      emacs_value *non_local_exit_data_out);
 117
 118   void (*non_local_exit_signal) (emacs_env *env,
 119                                  emacs_value non_local_exit_symbol,
 120                                  emacs_value non_local_exit_data);
 121
 122   void (*non_local_exit_throw) (emacs_env *env,
 123                                 emacs_value tag,
 124                                 emacs_value value);
 125
 126   /* Function registration.  */
 127
 128   emacs_value (*make_function) (emacs_env *env,
 129                                 ptrdiff_t min_arity,
 130                                 ptrdiff_t max_arity,
 131                                 emacs_value (*function) (emacs_env *env,
 132                                                          ptrdiff_t nargs,
 133                                                          emacs_value args[],
 134                                                          void *)
 135                                   EMACS_NOEXCEPT,
 136                                 const char *documentation,
 137                                 void *data);
 138
 139   emacs_value (*funcall) (emacs_env *env,
 140                           emacs_value function,
 141                           ptrdiff_t nargs,
 142                           emacs_value args[]);
 143
 144   emacs_value (*intern) (emacs_env *env,
 145                          const char *symbol_name);
 146
 147   /* Type conversion.  */
 148
 149   emacs_value (*type_of) (emacs_env *env,
 150                           emacs_value value);
 151
 152   bool (*is_not_nil) (emacs_env *env, emacs_value value);
 153
 154   bool (*eq) (emacs_env *env, emacs_value a, emacs_value b);
 155
 156   intmax_t (*extract_integer) (emacs_env *env, emacs_value value);
 157
 158   emacs_value (*make_integer) (emacs_env *env, intmax_t value);
 159
 160   double (*extract_float) (emacs_env *env, emacs_value value);
 161
 162   emacs_value (*make_float) (emacs_env *env, double value);
 163
 164   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
 165      null-terminated string.
 166
 167      SIZE must point to the total size of the buffer.  If BUFFER is
 168      NULL or if SIZE is not big enough, write the required buffer size
 169      to SIZE and return false.
 170
 171      Note that SIZE must include the last null byte (e.g. "abc" needs
 172      a buffer of size 4).
 173
 174      Return true if the string was successfully copied.  */
 175
 176   bool (*copy_string_contents) (emacs_env *env,
 177                                 emacs_value value,
 178                                 char *buffer,
 179                                 ptrdiff_t *size_inout);
 180
 181   /* Create a Lisp string from a utf8 encoded string.  */
 182   emacs_value (*make_string) (emacs_env *env,
 183                               const char *contents, ptrdiff_t length);
 184
 185   /* Embedded pointer type.  */
 186   emacs_value (*make_user_ptr) (emacs_env *env,
 187                                 emacs_finalizer_function fin,
 188                                 void *ptr);
 189
 190   void *(*get_user_ptr) (emacs_env *env, emacs_value uptr);
 191   void (*set_user_ptr) (emacs_env *env, emacs_value uptr, void *ptr);
 192
 193   emacs_finalizer_function (*get_user_finalizer) (emacs_env *env,
 194                                                   emacs_value uptr);
 195   void (*set_user_finalizer) (emacs_env *env,
 196                               emacs_value uptr,
 197                               emacs_finalizer_function fin);
 198
 199   /* Vector functions.  */
 200   emacs_value (*vec_get) (emacs_env *env, emacs_value vec, ptrdiff_t i);
 201
 202   void (*vec_set) (emacs_env *env, emacs_value vec, ptrdiff_t i,
 203                    emacs_value val);
 204
 205   ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vec);
 206 };
 207
 208 /* Every module should define a function as follows.  */
 209 extern int emacs_module_init (struct emacs_runtime *ert);
 210
 211 #ifdef __cplusplus
 212 }
 213 #endif
 214
 215 #endif /* EMACS_MODULE_H */