src/script/common/c_internal.h

   1 /*
   2 Minetest
   3 Copyright (C) 2013 celeron55, Perttu Ahola <celeron55@gmail.com>
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation; either version 2.1 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License along
  16 with this program; if not, write to the Free Software Foundation, Inc.,
  17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 /******************************************************************************/
  21 /******************************************************************************/
  22 /* WARNING!!!! do NOT add this header in any include file or any code file    */
  23 /*             not being a modapi file!!!!!!!!                                */
  24 /******************************************************************************/
  25 /******************************************************************************/
  26
  27 #pragma once
  28
  29 extern "C" {
  30 #include <lua.h>
  31 #include <lauxlib.h>
  32 }
  33
  34 #include "config.h"
  35 #include "common/c_types.h"
  36
  37
  38 /*
  39         Define our custom indices into the Lua registry table.
  40
  41         Lua 5.2 and above define the LUA_RIDX_LAST macro. Only numbers above that
  42         may be used for custom indices, anything else is reserved.
  43
  44         Lua 5.1 / LuaJIT do not use any numeric indices (only string indices),
  45         so we can use numeric indices freely.
  46 */
  47 enum {
  48 #ifdef LUA_RIDX_LAST
  49         CUSTOM_RIDX_BEFORE_ = LUA_RIDX_LAST,
  50 #else
  51         CUSTOM_RIDX_BEFORE_ = 0,
  52 #endif
  53
  54         CUSTOM_RIDX_SCRIPTAPI,
  55         CUSTOM_RIDX_GLOBALS_BACKUP,
  56         CUSTOM_RIDX_CURRENT_MOD_NAME,
  57         CUSTOM_RIDX_ERROR_HANDLER,
  58         CUSTOM_RIDX_HTTP_API_LUA,
  59         CUSTOM_RIDX_METATABLE_MAP,
  60
  61         // The following four functions are implemented in Lua because LuaJIT can
  62         // trace them and optimize tables/string better than from the C API.
  63         CUSTOM_RIDX_READ_VECTOR,
  64         CUSTOM_RIDX_PUSH_VECTOR,
  65         CUSTOM_RIDX_READ_NODE,
  66         CUSTOM_RIDX_PUSH_NODE,
  67 };
  68
  69
  70 // Determine if CUSTOM_RIDX_SCRIPTAPI will hold a light or full userdata
  71 #if defined(__aarch64__) && USE_LUAJIT
  72 /* LuaJIT has a 47-bit limit for lightuserdata on this platform and we cannot
  73  * assume that the ScriptApi class was allocated at a fitting address. */
  74 #define INDIRECT_SCRIPTAPI_RIDX 1
  75 #else
  76 #define INDIRECT_SCRIPTAPI_RIDX 0
  77 #endif
  78
  79 // Pushes the error handler onto the stack and returns its index
  80 #define PUSH_ERROR_HANDLER(L) \
  81         (lua_rawgeti((L), LUA_REGISTRYINDEX, CUSTOM_RIDX_ERROR_HANDLER), lua_gettop((L)))
  82
  83 #define PCALL_RESL(L, RES) {                            \
  84         int result_ = (RES);                                \
  85         if (result_ != 0) {                                 \
  86                 script_error((L), result_, NULL, __FUNCTION__); \
  87         }                                                   \
  88 }
  89
  90 // What script_run_callbacks does with the return values of callbacks.
  91 // Regardless of the mode, if only one callback is defined,
  92 // its return value is the total return value.
  93 // Modes only affect the case where 0 or >= 2 callbacks are defined.
  94 enum RunCallbacksMode
  95 {
  96         // Returns the return value of the first callback
  97         // Returns nil if list of callbacks is empty
  98         RUN_CALLBACKS_MODE_FIRST,
  99         // Returns the return value of the last callback
 100         // Returns nil if list of callbacks is empty
 101         RUN_CALLBACKS_MODE_LAST,
 102         // If any callback returns a false value, the first such is returned
 103         // Otherwise, the first callback's return value (trueish) is returned
 104         // Returns true if list of callbacks is empty
 105         RUN_CALLBACKS_MODE_AND,
 106         // Like above, but stops calling callbacks (short circuit)
 107         // after seeing the first false value
 108         RUN_CALLBACKS_MODE_AND_SC,
 109         // If any callback returns a true value, the first such is returned
 110         // Otherwise, the first callback's return value (falseish) is returned
 111         // Returns false if list of callbacks is empty
 112         RUN_CALLBACKS_MODE_OR,
 113         // Like above, but stops calling callbacks (short circuit)
 114         // after seeing the first true value
 115         RUN_CALLBACKS_MODE_OR_SC,
 116         // Note: "a true value" and "a false value" refer to values that
 117         // are converted by readParam<bool> to true or false, respectively.
 118 };
 119
 120 // Gets a backtrace of the current execution point
 121 std::string script_get_backtrace(lua_State *L);
 122 // Wrapper for CFunction calls that converts C++ exceptions to Lua errors
 123 int script_exception_wrapper(lua_State *L, lua_CFunction f);
 124 // Acts as the error handler for lua_pcall
 125 int script_error_handler(lua_State *L);
 126 // Takes an error from lua_pcall and throws it as a LuaError
 127 void script_error(lua_State *L, int pcall_result, const char *mod, const char *fxn);
 128
 129 bool script_log_unique(lua_State *L, std::string message, std::ostream &log_to,
 130         int stack_depth = 1);
 131
 132 enum DeprecatedHandlingMode {
 133         Ignore,
 134         Log,
 135         Error
 136 };
 137
 138 /**
 139  * Reads `deprecated_lua_api_handling` in settings, returns cached value.
 140  *
 141  * @return DeprecatedHandlingMode
 142  */
 143 DeprecatedHandlingMode get_deprecated_handling_mode();
 144
 145 /**
 146  * Handles a deprecation warning based on user settings
 147  *
 148  * @param L Lua State
 149  * @param message The deprecation method
 150  * @param stack_depth How far on the stack to the first user function (ie: not builtin or core)
 151  */
 152 void log_deprecated(lua_State *L, std::string message, int stack_depth = 1);
 153
 154 // Safely call string.dump on a function value
 155 // (does not pop, leaves one value on stack)
 156 void call_string_dump(lua_State *L, int idx);