1/* emacs-module.h - GNU Emacs module API.
2
3Copyright (C) 2015-2021 Free Software Foundation, Inc.
4
5This file is part of GNU Emacs.
6
7GNU Emacs is free software: you can redistribute it and/or modify
8it under the terms of the GNU General Public License as published by
9the Free Software Foundation, either version 3 of the License, or (at
10your option) any later version.
11
12GNU Emacs is distributed in the hope that it will be useful,
13but WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15GNU General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
19
20/*
21This file defines the Emacs module API.  Please see the chapter
22`Dynamic Modules' in the GNU Emacs Lisp Reference Manual for
23information how to write modules and use this header file.
24*/
25
26#ifndef EMACS_MODULE_H
27#define EMACS_MODULE_H
28
29#include <stddef.h>
30#include <stdint.h>
31#include <time.h>
32
33#ifndef __cplusplus
34#include <stdbool.h>
35#endif
36
37#define EMACS_MAJOR_VERSION @emacs_major_version@
38
39#if defined __cplusplus && __cplusplus >= 201103L
40# define EMACS_NOEXCEPT noexcept
41#else
42# define EMACS_NOEXCEPT
43#endif
44
45#ifdef __has_attribute
46#if __has_attribute(__nonnull__)
47# define EMACS_ATTRIBUTE_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
48#endif
49#endif
50#ifndef EMACS_ATTRIBUTE_NONNULL
51# define EMACS_ATTRIBUTE_NONNULL(...)
52#endif
53
54#ifdef __cplusplus
55extern "C" {
56#endif
57
58/* Current environment.  */
59typedef struct emacs_env_27 emacs_env;
60
61/* Opaque pointer representing an Emacs Lisp value.
62   BEWARE: Do not assume NULL is a valid value!  */
63typedef struct emacs_value_tag *emacs_value;
64
65enum { emacs_variadic_function = -2 };
66
67/* Struct passed to a module init function (emacs_module_init).  */
68struct emacs_runtime
69{
70  /* Structure size (for version checking).  */
71  ptrdiff_t size;
72
73  /* Private data; users should not touch this.  */
74  struct emacs_runtime_private *private_members;
75
76  /* Return an environment pointer.  */
77  emacs_env *(*get_environment) (struct emacs_runtime *ert)
78    EMACS_ATTRIBUTE_NONNULL(1);
79};
80
81
82/* Possible Emacs function call outcomes.  */
83enum emacs_funcall_exit
84{
85  /* Function has returned normally.  */
86  emacs_funcall_exit_return = 0,
87
88  /* Function has signaled an error using `signal'.  */
89  emacs_funcall_exit_signal = 1,
90
91  /* Function has exit using `throw'.  */
92  emacs_funcall_exit_throw = 2
93};
94
95/* Possible return values for emacs_env.process_input.  */
96enum emacs_process_input_result
97{
98  /* Module code may continue  */
99  emacs_process_input_continue = 0,
100
101  /* Module code should return control to Emacs as soon as possible.  */
102  emacs_process_input_quit = 1
103};
104
105/* Define emacs_limb_t so that it is likely to match GMP's mp_limb_t.
106   This micro-optimization can help modules that use mpz_export and
107   mpz_import, which operate more efficiently on mp_limb_t.  It's OK
108   (if perhaps a bit slower) if the two types do not match, and
109   modules shouldn't rely on the two types matching.  */
110typedef size_t emacs_limb_t;
111#define EMACS_LIMB_MAX SIZE_MAX
112
113struct emacs_env_25
114{
115@module_env_snippet_25@
116};
117
118struct emacs_env_26
119{
120@module_env_snippet_25@
121
122@module_env_snippet_26@
123};
124
125struct emacs_env_27
126{
127@module_env_snippet_25@
128
129@module_env_snippet_26@
130
131@module_env_snippet_27@
132};
133
134/* Every module should define a function as follows.  */
135extern int emacs_module_init (struct emacs_runtime *ert)
136  EMACS_NOEXCEPT
137  EMACS_ATTRIBUTE_NONNULL(1);
138
139#ifdef __cplusplus
140}
141#endif
142
143#endif /* EMACS_MODULE_H */
144