1 /* emacs-module.h - GNU Emacs module API.
3 Copyright (C) 2015-2016 Free Software Foundation, Inc.
5 This file is part of GNU Emacs.
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.
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.
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/>. */
20 #ifndef EMACS_MODULE_H
21 #define EMACS_MODULE_H
27 #if defined __cplusplus && __cplusplus >= 201103L
28 # define EMACS_NOEXCEPT noexcept
30 /* Function prototype for module user-pointer finalizers.
32 NOTE: C++11 15.4: An exception-specification shall not appear in a
33 typedef declaration or alias-declaration.
36 void emacs_dummy_finalizer_function (void *) noexcept
;
37 typedef decltype(emacs_dummy_finalizer_function
) *emacs_finalizer_function
;
40 # define EMACS_NOEXCEPT
41 typedef void (*emacs_finalizer_function
) (void *);
48 /* Current environment. */
49 typedef struct emacs_env_25 emacs_env
;
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
;
55 enum emacs_arity
{ emacs_variadic_function
= -2 };
57 /* Struct passed to a module init function (emacs_module_init). */
60 /* Structure size (for version checking). */
63 /* Private data; users should not touch this. */
64 struct emacs_runtime_private
*private_members
;
66 /* Return an environment pointer. */
67 emacs_env
*(*get_environment
) (struct emacs_runtime
*ert
);
71 /* Function prototype for the module init function. */
72 typedef int (*emacs_init_function
) (struct emacs_runtime
*ert
);
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
);
78 /* Possible Emacs function call outcomes. */
79 enum emacs_funcall_exit
81 /* Function has returned normally. */
82 emacs_funcall_exit_return
= 0,
84 /* Function has signaled an error using `signal'. */
85 emacs_funcall_exit_signal
= 1,
87 /* Function has exit using `throw'. */
88 emacs_funcall_exit_throw
= 2,
93 /* Structure size (for version checking). */
96 /* Private data; users should not touch this. */
97 struct emacs_env_private
*private_members
;
99 /* Memory management. */
101 emacs_value (*make_global_ref
) (emacs_env
*env
,
102 emacs_value any_reference
);
104 void (*free_global_ref
) (emacs_env
*env
,
105 emacs_value global_reference
);
107 /* Non-local exit handling. */
109 enum emacs_funcall_exit (*non_local_exit_check
) (emacs_env
*env
);
111 void (*non_local_exit_clear
) (emacs_env
*env
);
113 enum emacs_funcall_exit (*non_local_exit_get
)
115 emacs_value
*non_local_exit_symbol_out
,
116 emacs_value
*non_local_exit_data_out
);
118 void (*non_local_exit_signal
) (emacs_env
*env
,
119 emacs_value non_local_exit_symbol
,
120 emacs_value non_local_exit_data
);
122 void (*non_local_exit_throw
) (emacs_env
*env
,
126 /* Function registration. */
128 emacs_value (*make_function
) (emacs_env
*env
,
131 emacs_value (*function
) (emacs_env
*env
,
136 const char *documentation
,
139 emacs_value (*funcall
) (emacs_env
*env
,
140 emacs_value function
,
144 emacs_value (*intern
) (emacs_env
*env
,
145 const char *symbol_name
);
147 /* Type conversion. */
149 emacs_value (*type_of
) (emacs_env
*env
,
152 bool (*is_not_nil
) (emacs_env
*env
, emacs_value value
);
154 bool (*eq
) (emacs_env
*env
, emacs_value a
, emacs_value b
);
156 intmax_t (*extract_integer
) (emacs_env
*env
, emacs_value value
);
158 emacs_value (*make_integer
) (emacs_env
*env
, intmax_t value
);
160 double (*extract_float
) (emacs_env
*env
, emacs_value value
);
162 emacs_value (*make_float
) (emacs_env
*env
, double value
);
164 /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
165 null-terminated string.
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.
171 Note that SIZE must include the last null byte (e.g. "abc" needs
174 Return true if the string was successfully copied. */
176 bool (*copy_string_contents
) (emacs_env
*env
,
179 ptrdiff_t *size_inout
);
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
);
185 /* Embedded pointer type. */
186 emacs_value (*make_user_ptr
) (emacs_env
*env
,
187 emacs_finalizer_function fin
,
190 void *(*get_user_ptr
) (emacs_env
*env
, emacs_value uptr
);
191 void (*set_user_ptr
) (emacs_env
*env
, emacs_value uptr
, void *ptr
);
193 emacs_finalizer_function (*get_user_finalizer
) (emacs_env
*env
,
195 void (*set_user_finalizer
) (emacs_env
*env
,
197 emacs_finalizer_function fin
);
199 /* Vector functions. */
200 emacs_value (*vec_get
) (emacs_env
*env
, emacs_value vec
, ptrdiff_t i
);
202 void (*vec_set
) (emacs_env
*env
, emacs_value vec
, ptrdiff_t i
,
205 ptrdiff_t (*vec_size
) (emacs_env
*env
, emacs_value vec
);
208 /* Every module should define a function as follows. */
209 extern int emacs_module_init (struct emacs_runtime
*ert
);
215 #endif /* EMACS_MODULE_H */