config

Personal configuration.
git clone git://code.dwrz.net/config
Log | Files | Refs

emacs-module.h (11343B)


      1 /* emacs-module.h - GNU Emacs module API.
      2 
      3 Copyright (C) 2015-2018 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 <https://www.gnu.org/licenses/>.  */
     19 
     20 #ifndef EMACS_MODULE_H
     21 #define EMACS_MODULE_H
     22 
     23 #include <stddef.h>
     24 #include <stdint.h>
     25 
     26 #ifndef __cplusplus
     27 #include <stdbool.h>
     28 #endif
     29 
     30 #if defined __cplusplus && __cplusplus >= 201103L
     31 #define EMACS_NOEXCEPT noexcept
     32 #else
     33 #define EMACS_NOEXCEPT
     34 #endif
     35 
     36 #ifdef __has_attribute
     37 #if __has_attribute(__nonnull__)
     38 #define EMACS_ATTRIBUTE_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
     39 #endif
     40 #endif
     41 #ifndef EMACS_ATTRIBUTE_NONNULL
     42 #define EMACS_ATTRIBUTE_NONNULL(...)
     43 #endif
     44 
     45 #ifdef __cplusplus
     46 extern "C" {
     47 #endif
     48 
     49 /* Current environment.  */
     50 typedef struct emacs_env_25 emacs_env;
     51 
     52 /* Opaque pointer representing an Emacs Lisp value.
     53    BEWARE: Do not assume NULL is a valid value!  */
     54 typedef struct emacs_value_tag *emacs_value;
     55 
     56 enum { emacs_variadic_function = -2 };
     57 
     58 /* Struct passed to a module init function (emacs_module_init).  */
     59 struct emacs_runtime {
     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       EMACS_ATTRIBUTE_NONNULL(1);
     69 };
     70 
     71 /* Possible Emacs function call outcomes.  */
     72 enum emacs_funcall_exit {
     73   /* Function has returned normally.  */
     74   emacs_funcall_exit_return = 0,
     75 
     76   /* Function has signaled an error using `signal'.  */
     77   emacs_funcall_exit_signal = 1,
     78 
     79   /* Function has exit using `throw'.  */
     80   emacs_funcall_exit_throw = 2
     81 };
     82 
     83 struct emacs_env_25 {
     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, emacs_value any_reference)
     93       EMACS_ATTRIBUTE_NONNULL(1);
     94 
     95   void (*free_global_ref)(emacs_env *env, emacs_value global_reference)
     96       EMACS_ATTRIBUTE_NONNULL(1);
     97 
     98   /* Non-local exit handling.  */
     99 
    100   enum emacs_funcall_exit (*non_local_exit_check)(emacs_env *env)
    101       EMACS_ATTRIBUTE_NONNULL(1);
    102 
    103   void (*non_local_exit_clear)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1);
    104 
    105   enum emacs_funcall_exit (*non_local_exit_get)(
    106       emacs_env *env, emacs_value *non_local_exit_symbol_out,
    107       emacs_value *non_local_exit_data_out) EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
    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       EMACS_ATTRIBUTE_NONNULL(1);
    113 
    114   void (*non_local_exit_throw)(emacs_env *env, emacs_value tag,
    115                                emacs_value value) EMACS_ATTRIBUTE_NONNULL(1);
    116 
    117   /* Function registration.  */
    118 
    119   emacs_value (*make_function)(
    120       emacs_env *env, ptrdiff_t min_arity, ptrdiff_t max_arity,
    121       emacs_value (*function)(emacs_env *env, ptrdiff_t nargs,
    122                               emacs_value args[], void *)
    123           EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1),
    124       const char *documentation, void *data) EMACS_ATTRIBUTE_NONNULL(1, 4);
    125 
    126   emacs_value (*funcall)(emacs_env *env, emacs_value function, ptrdiff_t nargs,
    127                          emacs_value args[]) EMACS_ATTRIBUTE_NONNULL(1);
    128 
    129   emacs_value (*intern)(emacs_env *env, const char *symbol_name)
    130       EMACS_ATTRIBUTE_NONNULL(1, 2);
    131 
    132   /* Type conversion.  */
    133 
    134   emacs_value (*type_of)(emacs_env *env, emacs_value value)
    135       EMACS_ATTRIBUTE_NONNULL(1);
    136 
    137   bool (*is_not_nil)(emacs_env *env, emacs_value value)
    138       EMACS_ATTRIBUTE_NONNULL(1);
    139 
    140   bool (*eq)(emacs_env *env, emacs_value a, emacs_value b)
    141       EMACS_ATTRIBUTE_NONNULL(1);
    142 
    143   intmax_t (*extract_integer)(emacs_env *env, emacs_value value)
    144       EMACS_ATTRIBUTE_NONNULL(1);
    145 
    146   emacs_value (*make_integer)(emacs_env *env, intmax_t value)
    147       EMACS_ATTRIBUTE_NONNULL(1);
    148 
    149   double (*extract_float)(emacs_env *env, emacs_value value)
    150       EMACS_ATTRIBUTE_NONNULL(1);
    151 
    152   emacs_value (*make_float)(emacs_env *env, double value)
    153       EMACS_ATTRIBUTE_NONNULL(1);
    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 true.
    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, emacs_value value, char *buffer,
    168                                ptrdiff_t *size_inout)
    169       EMACS_ATTRIBUTE_NONNULL(1, 4);
    170 
    171   /* Create a Lisp string from a utf8 encoded string.  */
    172   emacs_value (*make_string)(emacs_env *env, const char *contents,
    173                              ptrdiff_t length) EMACS_ATTRIBUTE_NONNULL(1, 2);
    174 
    175   /* Embedded pointer type.  */
    176   emacs_value (*make_user_ptr)(emacs_env *env,
    177                                void (*fin)(void *) EMACS_NOEXCEPT, void *ptr)
    178       EMACS_ATTRIBUTE_NONNULL(1);
    179 
    180   void *(*get_user_ptr)(emacs_env *env,
    181                         emacs_value uptr)EMACS_ATTRIBUTE_NONNULL(1);
    182   void (*set_user_ptr)(emacs_env *env, emacs_value uptr, void *ptr)
    183       EMACS_ATTRIBUTE_NONNULL(1);
    184 
    185   void (*(*get_user_finalizer)(emacs_env *env,
    186                                emacs_value uptr))(void *) EMACS_NOEXCEPT
    187       EMACS_ATTRIBUTE_NONNULL(1);
    188   void (*set_user_finalizer)(emacs_env *env, emacs_value uptr,
    189                              void (*fin)(void *) EMACS_NOEXCEPT)
    190       EMACS_ATTRIBUTE_NONNULL(1);
    191 
    192   /* Vector functions.  */
    193   emacs_value (*vec_get)(emacs_env *env, emacs_value vec, ptrdiff_t i)
    194       EMACS_ATTRIBUTE_NONNULL(1);
    195 
    196   void (*vec_set)(emacs_env *env, emacs_value vec, ptrdiff_t i, emacs_value val)
    197       EMACS_ATTRIBUTE_NONNULL(1);
    198 
    199   ptrdiff_t (*vec_size)(emacs_env *env, emacs_value vec)
    200       EMACS_ATTRIBUTE_NONNULL(1);
    201 };
    202 
    203 struct emacs_env_26 {
    204   /* Structure size (for version checking).  */
    205   ptrdiff_t size;
    206 
    207   /* Private data; users should not touch this.  */
    208   struct emacs_env_private *private_members;
    209 
    210   /* Memory management.  */
    211 
    212   emacs_value (*make_global_ref)(emacs_env *env, emacs_value any_reference)
    213       EMACS_ATTRIBUTE_NONNULL(1);
    214 
    215   void (*free_global_ref)(emacs_env *env, emacs_value global_reference)
    216       EMACS_ATTRIBUTE_NONNULL(1);
    217 
    218   /* Non-local exit handling.  */
    219 
    220   enum emacs_funcall_exit (*non_local_exit_check)(emacs_env *env)
    221       EMACS_ATTRIBUTE_NONNULL(1);
    222 
    223   void (*non_local_exit_clear)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1);
    224 
    225   enum emacs_funcall_exit (*non_local_exit_get)(
    226       emacs_env *env, emacs_value *non_local_exit_symbol_out,
    227       emacs_value *non_local_exit_data_out) EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
    228 
    229   void (*non_local_exit_signal)(emacs_env *env,
    230                                 emacs_value non_local_exit_symbol,
    231                                 emacs_value non_local_exit_data)
    232       EMACS_ATTRIBUTE_NONNULL(1);
    233 
    234   void (*non_local_exit_throw)(emacs_env *env, emacs_value tag,
    235                                emacs_value value) EMACS_ATTRIBUTE_NONNULL(1);
    236 
    237   /* Function registration.  */
    238 
    239   emacs_value (*make_function)(
    240       emacs_env *env, ptrdiff_t min_arity, ptrdiff_t max_arity,
    241       emacs_value (*function)(emacs_env *env, ptrdiff_t nargs,
    242                               emacs_value args[], void *)
    243           EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1),
    244       const char *documentation, void *data) EMACS_ATTRIBUTE_NONNULL(1, 4);
    245 
    246   emacs_value (*funcall)(emacs_env *env, emacs_value function, ptrdiff_t nargs,
    247                          emacs_value args[]) EMACS_ATTRIBUTE_NONNULL(1);
    248 
    249   emacs_value (*intern)(emacs_env *env, const char *symbol_name)
    250       EMACS_ATTRIBUTE_NONNULL(1, 2);
    251 
    252   /* Type conversion.  */
    253 
    254   emacs_value (*type_of)(emacs_env *env, emacs_value value)
    255       EMACS_ATTRIBUTE_NONNULL(1);
    256 
    257   bool (*is_not_nil)(emacs_env *env, emacs_value value)
    258       EMACS_ATTRIBUTE_NONNULL(1);
    259 
    260   bool (*eq)(emacs_env *env, emacs_value a, emacs_value b)
    261       EMACS_ATTRIBUTE_NONNULL(1);
    262 
    263   intmax_t (*extract_integer)(emacs_env *env, emacs_value value)
    264       EMACS_ATTRIBUTE_NONNULL(1);
    265 
    266   emacs_value (*make_integer)(emacs_env *env, intmax_t value)
    267       EMACS_ATTRIBUTE_NONNULL(1);
    268 
    269   double (*extract_float)(emacs_env *env, emacs_value value)
    270       EMACS_ATTRIBUTE_NONNULL(1);
    271 
    272   emacs_value (*make_float)(emacs_env *env, double value)
    273       EMACS_ATTRIBUTE_NONNULL(1);
    274 
    275   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
    276      null-terminated string.
    277 
    278      SIZE must point to the total size of the buffer.  If BUFFER is
    279      NULL or if SIZE is not big enough, write the required buffer size
    280      to SIZE and return true.
    281 
    282      Note that SIZE must include the last null byte (e.g. "abc" needs
    283      a buffer of size 4).
    284 
    285      Return true if the string was successfully copied.  */
    286 
    287   bool (*copy_string_contents)(emacs_env *env, emacs_value value, char *buffer,
    288                                ptrdiff_t *size_inout)
    289       EMACS_ATTRIBUTE_NONNULL(1, 4);
    290 
    291   /* Create a Lisp string from a utf8 encoded string.  */
    292   emacs_value (*make_string)(emacs_env *env, const char *contents,
    293                              ptrdiff_t length) EMACS_ATTRIBUTE_NONNULL(1, 2);
    294 
    295   /* Embedded pointer type.  */
    296   emacs_value (*make_user_ptr)(emacs_env *env,
    297                                void (*fin)(void *) EMACS_NOEXCEPT, void *ptr)
    298       EMACS_ATTRIBUTE_NONNULL(1);
    299 
    300   void *(*get_user_ptr)(emacs_env *env,
    301                         emacs_value uptr)EMACS_ATTRIBUTE_NONNULL(1);
    302   void (*set_user_ptr)(emacs_env *env, emacs_value uptr, void *ptr)
    303       EMACS_ATTRIBUTE_NONNULL(1);
    304 
    305   void (*(*get_user_finalizer)(emacs_env *env,
    306                                emacs_value uptr))(void *) EMACS_NOEXCEPT
    307       EMACS_ATTRIBUTE_NONNULL(1);
    308   void (*set_user_finalizer)(emacs_env *env, emacs_value uptr,
    309                              void (*fin)(void *) EMACS_NOEXCEPT)
    310       EMACS_ATTRIBUTE_NONNULL(1);
    311 
    312   /* Vector functions.  */
    313   emacs_value (*vec_get)(emacs_env *env, emacs_value vec, ptrdiff_t i)
    314       EMACS_ATTRIBUTE_NONNULL(1);
    315 
    316   void (*vec_set)(emacs_env *env, emacs_value vec, ptrdiff_t i, emacs_value val)
    317       EMACS_ATTRIBUTE_NONNULL(1);
    318 
    319   ptrdiff_t (*vec_size)(emacs_env *env, emacs_value vec)
    320       EMACS_ATTRIBUTE_NONNULL(1);
    321 
    322   /* Returns whether a quit is pending.  */
    323   bool (*should_quit)(emacs_env *env) EMACS_ATTRIBUTE_NONNULL(1);
    324 };
    325 
    326 /* Every module should define a function as follows.  */
    327 extern int emacs_module_init(struct emacs_runtime *ert) EMACS_NOEXCEPT
    328     EMACS_ATTRIBUTE_NONNULL(1);
    329 
    330 #ifdef __cplusplus
    331 }
    332 #endif
    333 
    334 #endif /* EMACS_MODULE_H */