src/emacs-module.h

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