emacs-module.h.in 3.06 KB
Newer Older
1 2
/* emacs-module.h - GNU Emacs module API.

Paul Eggert's avatar
Paul Eggert committed
3
Copyright (C) 2015-2019 Free Software Foundation, Inc.
4 5 6 7 8 9 10 11 12 13 14 15 16 17

This file is part of GNU Emacs.

GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

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 21 22 23 24

#ifndef EMACS_MODULE_H
#define EMACS_MODULE_H

#include <stdint.h>
#include <stddef.h>
25
#include <time.h>
26 27 28 29 30

#ifndef __cplusplus
#include <stdbool.h>
#endif

31 32 33 34
#ifdef EMACS_MODULE_GMP
#include <gmp.h>
#endif

35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
#if defined __cplusplus && __cplusplus >= 201103L
# define EMACS_NOEXCEPT noexcept
#else
# define EMACS_NOEXCEPT
#endif

#ifdef __has_attribute
#if __has_attribute(__nonnull__)
# define EMACS_ATTRIBUTE_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
#endif
#endif
#ifndef EMACS_ATTRIBUTE_NONNULL
# define EMACS_ATTRIBUTE_NONNULL(...)
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* Current environment.  */
55
typedef struct emacs_env_27 emacs_env;
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

/* Opaque pointer representing an Emacs Lisp value.
   BEWARE: Do not assume NULL is a valid value!  */
typedef struct emacs_value_tag *emacs_value;

enum { emacs_variadic_function = -2 };

/* Struct passed to a module init function (emacs_module_init).  */
struct emacs_runtime
{
  /* Structure size (for version checking).  */
  ptrdiff_t size;

  /* Private data; users should not touch this.  */
  struct emacs_runtime_private *private_members;

  /* Return an environment pointer.  */
  emacs_env *(*get_environment) (struct emacs_runtime *ert)
    EMACS_ATTRIBUTE_NONNULL(1);
};


/* Possible Emacs function call outcomes.  */
enum emacs_funcall_exit
{
  /* Function has returned normally.  */
  emacs_funcall_exit_return = 0,

  /* Function has signaled an error using `signal'.  */
  emacs_funcall_exit_signal = 1,

  /* Function has exit using `throw'.  */
Philipp Stephani's avatar
Philipp Stephani committed
88
  emacs_funcall_exit_throw = 2
89 90
};

91 92 93 94 95 96 97 98 99 100
/* Possible return values for emacs_env.process_input.  */
enum emacs_process_input_result
{
  /* Module code may continue  */
  emacs_process_input_continue = 0,

  /* Module code should return control to Emacs as soon as possible.  */
  emacs_process_input_quit = 1
};

101 102 103 104 105 106
#ifdef EMACS_MODULE_GMP
struct emacs_mpz { mpz_t value; };
#else
struct emacs_mpz;  /* no definition */
#endif

107 108 109 110 111 112 113 114 115 116 117 118
struct emacs_env_25
{
@module_env_snippet_25@
};

struct emacs_env_26
{
@module_env_snippet_25@

@module_env_snippet_26@
};

119 120 121 122 123 124 125 126 127
struct emacs_env_27
{
@module_env_snippet_25@

@module_env_snippet_26@

@module_env_snippet_27@
};

128 129
/* Every module should define a function as follows.  */
extern int emacs_module_init (struct emacs_runtime *ert)
130
  EMACS_NOEXCEPT
131 132 133 134 135 136 137
  EMACS_ATTRIBUTE_NONNULL(1);

#ifdef __cplusplus
}
#endif

#endif /* EMACS_MODULE_H */