1 /** 2 * Copyright (c) 2006-2011 LOVE Development Team 3 * 4 * This software is provided 'as-is', without any express or implied 5 * warranty. In no event will the authors be held liable for any damages 6 * arising from the use of this software. 7 * 8 * Permission is granted to anyone to use this software for any purpose, 9 * including commercial applications, and to alter it and redistribute it 10 * freely, subject to the following restrictions: 11 * 12 * 1. The origin of this software must not be misrepresented; you must not 13 * claim that you wrote the original software. If you use this software 14 * in a product, an acknowledgment in the product documentation would be 15 * appreciated but is not required. 16 * 2. Altered source versions must be plainly marked as such, and must not be 17 * misrepresented as being the original software. 18 * 3. This notice may not be removed or altered from any source distribution. 19 **/ 20 21 #ifndef LOVE_RUNTIME_H 22 #define LOVE_RUNTIME_H 23 24 // LOVE 25 #include "types.h" 26 27 // Lua 28 extern "C" { 29 #include <lua.h> 30 #include <lualib.h> 31 #include <lauxlib.h> 32 } 33 34 namespace love 35 { 36 // Forward declarations. 37 class Module; 38 class Reference; 39 40 // Exposed mutex of the GC 41 extern void *_gcmutex; 42 extern unsigned int _gcthread; 43 44 /** 45 * Registries represent special tables which can be accessed with 46 * luax_getregistry. 47 **/ 48 enum Registry 49 { 50 REGISTRY_GC = 1, 51 REGISTRY_MODULES, 52 }; 53 54 /** 55 * This structure wraps all Lua-exposed objects. It exists in the 56 * Lua state as a full userdata (so we can catch __gc "events"), 57 * though the Object it refers to is light userdata in the sense 58 * that it is not allocated by the Lua VM. 59 **/ 60 struct Proxy 61 { 62 // Holds type information (see types.h). 63 bits flags; 64 65 // The light userdata. 66 void * data; 67 68 // True if Lua should delete on GC. 69 bool own; 70 }; 71 72 /** 73 * A Module with Lua wrapper functions and other data. 74 **/ 75 struct WrappedModule 76 { 77 // The module containing the functions. 78 Module * module; 79 80 // The name for the table to put the functions in, without the 'love'-prefix. 81 const char * name; 82 83 // The type flags of this module. 84 love::bits flags; 85 86 // The functions of the module (last element {0,0}). 87 const luaL_Reg * functions; 88 89 // A list of functions which expose the types of the modules (last element 0). 90 const lua_CFunction * types; 91 92 }; 93 94 /** 95 * Returns a reference to the top stack element (-1) if the value 96 * is of the specified type. If the value is incorrect, zero is returned. 97 * 98 * In any case, the top stack element is popped, regardless of its type. 99 **/ 100 Reference * luax_refif(lua_State * L, int type); 101 102 /** 103 * Prints the current contents of the stack. Only useful for debugging. 104 * @param L The Lua state. 105 **/ 106 void luax_printstack(lua_State * L); 107 108 /** 109 * Converts the value at idx to a bool. It follow the same rules 110 * as lua_toboolean, but returns a bool instead of an int. 111 * @param L The Lua state. 112 * @param idx The index on the Lua state. 113 * @return True if the value evaluates to true, false otherwise. 114 **/ 115 bool luax_toboolean(lua_State * L, int idx); 116 117 /** 118 * Pushes a bool onto the stack. It's the same as lua_pushboolean, 119 * but with bool instead of int. 120 * @param L The Lua state. 121 * @paarm b The bool to push. 122 **/ 123 void luax_pushboolean(lua_State * L, bool b); 124 125 /** 126 * Converts the value at idx to a bool, or if not present, b is returned. 127 * @param L The Lua state. 128 * @param idx The index of the Lua state. 129 * @param b The value to return if no value exist at the specified index. 130 * @return True if the value evaluates to true, false otherwise. 131 **/ 132 bool luax_optboolean(lua_State * L, int idx, bool b); 133 134 /** 135 * Require at least 'min' number of items on the stack. 136 * @param L The Lua state. 137 * @param min The minimum number of items on the stack. 138 * @return Zero if conditions are met, otherwise a Lua error (longjmp). 139 **/ 140 int luax_assert_argc(lua_State * L, int min); 141 142 /** 143 * Require at least 'min', but more than 'max' items on the stack. 144 * @param L The Lua state. 145 * @param min The minimum number of items on the stack. 146 * @param max The maximum number of items on the stack. 147 * @return Zero if conditions are met, otherwise a Lua error (longjmp). 148 **/ 149 int luax_assert_argc(lua_State * L, int min, int max); 150 151 /** 152 * Require that the value at idx is a function. 153 * @param L The Lua state. 154 *@param idx The index on the stack. 155 **/ 156 int luax_assert_function(lua_State * L, int idx); 157 158 /** 159 * Register a module in the love table. The love table will be created if it does not exist. 160 * @param L The Lua state. 161 **/ 162 int luax_register_module(lua_State * L, const WrappedModule & m); 163 164 /** 165 * Inserts a module with 'name' into the package.preloaded table. 166 * @param f The function to be called when the module is opened. 167 * @param name The name of the module, with 'love'-prefix, for instance 'love.graphics'. 168 **/ 169 int luax_preload(lua_State * L, lua_CFunction f, const char * name); 170 171 /** 172 * Register a new type. 173 * @param tname The name of the type. This must not conflict with other type names, 174 * even from other modules. 175 * @param f The list of member functions for the type. 176 **/ 177 int luax_register_type(lua_State * L, const char * tname, const luaL_Reg * f = 0); 178 179 /** 180 * Register a new searcher function for package.loaders. This can for instance enable 181 * loading of files through love.filesystem using standard require. 182 * @param L The Lua state. 183 * @param f The searcher function. 184 **/ 185 int luax_register_searcher(lua_State * L, lua_CFunction f); 186 187 /** 188 * Creates a new Lua-accessible object of the given type, and put it on the stack. 189 * @param L The Lua state. 190 * @param name The name of the type. This must match the used earlier with luax_register_type. 191 * @param flags The type information. 192 * @param data The pointer to the actual object. 193 * @own Set this to true (default) if the object should be released upon garbage collection. 194 **/ 195 void luax_newtype(lua_State * L, const char * name, bits flags, void * data, bool own = true); 196 197 /** 198 * Checks whether the value at idx is a certain type. 199 * @param L The Lua state. 200 * @param idx The index on the stack. 201 * @param type The type to check for. 202 * @return True if the value is Proxy of the specified type, false otherwise. 203 **/ 204 bool luax_istype(lua_State * L, int idx, love::bits type); 205 206 /** 207 * Gets the function love.module.function and puts it on top of the stack (alone). If the 208 * love table, the module, or the function does not exist, an error is returned. 209 * @return An error if nonexistent, or 1 if successful. 210 **/ 211 int luax_getfunction(lua_State * L, const char * module, const char * function); 212 213 /** 214 * Converts an object into another object by the specified function love.module.function. 215 * The conversion function must accept a single object of the relevant type as a parameter, 216 * and returnone value. If the function does not exist (see luax_getfunction), an error is returned. 217 * 218 * Note that the initial object at idx is replaced by the new object. 219 * 220 * @param L The Lua state. 221 * @param idx The index on the stack. 222 * @param module The module in the love table. 223 * @param function The function in the module. 224 **/ 225 int luax_convobj(lua_State * L, int idx, const char * module, const char * function); 226 227 /** 228 * Converts an object into another object by the specified function love.module.function. 229 * The conversion function must accept a single object of the relevant type as its first parameter, 230 * and return one value. If the function does not exist (see luax_getfunction), an error is returned. 231 * 232 * Note that the initial object at idx is replaced by the new object. 233 * 234 * @param L The Lua state. 235 * @param idxs An array of indices on the stack. 236 * @param n How many arguments are being passed. 237 * @param module The module in the love table. 238 * @param function The function in the module. 239 **/ 240 int luax_convobj(lua_State * L, int idxs[], int n, const char * module, const char * function); 241 242 /** 243 * 'Insist' that a table 'k' exists in the table at idx. Insistence involves that the 244 * table (k) is created if it does not exist in the table at idx. The table at idx must 245 * pre-exist, however. Also note that if the a non-table value exists at the specified 246 * location, it will be overwritten with a new table. The insisted table, and only the 247 * insisted table, will be placed on top of the stack. 248 * 249 * @param idx The index on the stack containing a table. 250 * @param k The name of the table we are insisting exist. 251 **/ 252 int luax_insist(lua_State * L, int idx, const char * k); 253 254 /** 255 * Insist that a global table 'k' exists. See luax_insist. 256 * @param k The name of the table we are insisting exist. 257 **/ 258 int luax_insistglobal(lua_State * L, const char * k); 259 260 /** 261 * Insists that a table 'k' exists inside the 'love' table. See luax_insist. 262 * @param k The name of the table we are insisting exist. 263 **/ 264 int luax_insistlove(lua_State * L, const char * k); 265 266 /** 267 * Gets (creates if needed) the specified Registry, and puts it on top 268 * of the stack. 269 * @param L The Lua state. 270 * @param r The Registry to get. 271 **/ 272 int luax_getregistry(lua_State * L, Registry r); 273 274 Type luax_type(lua_State * L, int idx); 275 276 /** 277 * Converts the value at idx to the specified type without checking that 278 * this conversion is valid. If the type has been previously verified with 279 * luax_istype, then this can be safely used. Otherwise, use luax_checktype. 280 * @param L The Lua state. 281 * @param idx The index on the stack. 282 * @param name The name of the type. 283 * @param type The type bit. 284 **/ 285 template <typename T> luax_totype(lua_State * L,int idx,const char *,love::bits)286 T * luax_totype(lua_State * L, int idx, const char *, love::bits) 287 { 288 return (T*)(((Proxy *)lua_touserdata(L, idx))->data); 289 } 290 291 /** 292 * Like luax_totype, but causes an error if the value at idx is not Proxy, 293 * or is not the specified type. 294 * @param L The Lua state. 295 * @param idx The index on the stack. 296 * @param name The name of the type. 297 * @param type The type bit. 298 **/ 299 template <typename T> luax_checktype(lua_State * L,int idx,const char * name,love::bits type)300 T * luax_checktype(lua_State * L, int idx, const char * name, love::bits type) 301 { 302 if(lua_isuserdata(L, idx) == 0) 303 luaL_error(L, "Incorrect parameter type: expected userdata."); 304 305 Proxy * u = (Proxy *)lua_touserdata(L, idx); 306 307 if((u->flags & type) != type) 308 luaL_error(L, "Incorrect parameter type: expected %s", name); 309 310 return (T *)u->data; 311 } 312 313 template <typename T> luax_getmodule(lua_State * L,const char * k,love::bits type)314 T * luax_getmodule(lua_State * L, const char * k, love::bits type) 315 { 316 luax_getregistry(L, REGISTRY_MODULES); 317 lua_getfield(L, -1, k); 318 319 if(!lua_isuserdata(L, -1)) 320 luaL_error(L, "Tried to get nonexisting module %s.", k); 321 322 Proxy * u = (Proxy *)lua_touserdata(L, -1); 323 324 if((u->flags & type) != type) 325 luaL_error(L, "Incorrect module %s", k); 326 327 lua_pop(L, 2); 328 329 return (T*)u->data; 330 } 331 332 } // love 333 334 #endif // LOVE_RUNTIME_H 335