This is the public interface to the core Lua library.

L0001 /* L0002 ** $Id: lua.h,v 1.218.1.5 2008/08/06 13:30:12 roberto Exp $ L0003 ** Lua - An Extensible Extension Language L0004 ** Lua.org, PUC-Rio, Brazil (http://www.lua.org) L0005 ** See Copyright Notice at the end of this file L0006 */ L0007 L0008 L0009 #ifndef lua_h L0010 #define lua_h L0011 L0012 #include <stdarg.h> L0013 #include <stddef.h> L0014 L0015 L0016 #include "luaconf.h" L0017 L0018 L0019 #define LUA_VERSION "Lua 5.1" L0020 #define LUA_RELEASE "Lua 5.1.4" L0021 #define LUA_VERSION_NUM 501

This is the number exposed by lua_version(). Note: 502 mean "5.2". 501 means "5.1"

L0022 #define LUA_COPYRIGHT "Copyright (C) 1994-2008 Lua.org, PUC-Rio" L0023 #define LUA_AUTHORS "R. Ierusalimschy, L. H. de Figueiredo & W. Celes" L0024 L0025 L0026 /* mark for precompiled code (`<esc>Lua') */ L0027 #define LUA_SIGNATURE "\033Lua"

Lua bytecode always starts with a signature consisting of these bytes. Both Lua 5.1 and 5.2 start with this signature. Some functions like load() determine whether a file is Lua source code or Lua byte code by looking for this signature. The \033 (escape) character is not a valid first character in Lua source code.

L0028 L0029 /* option for multiple returns in `lua_pcall' and `lua_call' */ L0030 #define LUA_MULTRET (-1) L0031 L0032 L0033 /* L0034 ** pseudo-indices L0035 */ L0036 #define LUA_REGISTRYINDEX (-10000) L0037 #define LUA_ENVIRONINDEX (-10001) L0038 #define LUA_GLOBALSINDEX (-10002) L0039 #define lua_upvalueindex(i) (LUA_GLOBALSINDEX-(i)) L0040 L0041 L0042 /* thread status; 0 is OK */ L0043 #define LUA_YIELD 1 L0044 #define LUA_ERRRUN 2 L0045 #define LUA_ERRSYNTAX 3 L0046 #define LUA_ERRMEM 4 L0047 #define LUA_ERRERR 5

Note: see also LUA_ERRFILE in lauxlib.h.

L0048 L0049 L0050 typedef struct lua_State lua_State; L0051 L0052 typedef int (*lua_CFunction) (lua_State *L); L0053 L0054 L0055 /* L0056 ** functions that read/write blocks when loading/dumping Lua chunks L0057 */ L0058 typedef const char * (*lua_Reader) (lua_State *L, void *ud, size_t *sz); L0059 L0060 typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud); L0061 L0062 L0063 /* L0064 ** prototype for memory-allocation functions L0065 */ L0066 typedef void * (*lua_Alloc) (void *ud, void *ptr, size_t osize, size_t nsize); L0067 L0068 L0069 /* L0070 ** basic types L0071 */ L0072 #define LUA_TNONE (-1) L0073 L0074 #define LUA_TNIL 0 L0075 #define LUA_TBOOLEAN 1 L0076 #define LUA_TLIGHTUSERDATA 2 L0077 #define LUA_TNUMBER 3 L0078 #define LUA_TSTRING 4 L0079 #define LUA_TTABLE 5 L0080 #define LUA_TFUNCTION 6 L0081 #define LUA_TUSERDATA 7 L0082 #define LUA_TTHREAD 8 L0083 L0084 L0085 L0086 /* minimum Lua stack available to a C function */ L0087 #define LUA_MINSTACK 20

From the reference manual: Whenever Lua calls C, it ensures that at least LUA_MINSTACK stack positions are available. LUA_MINSTACK is defined as 20, so that usually you do not have to worry about stack space unless your code has loops pushing elements onto the stack.

L0088 L0089 L0090 /* L0091 ** generic extra include file L0092 */ L0093 #if defined(LUA_USER_H) L0094 #include LUA_USER_H L0095 #endif L0096 L0097 L0098 /* type of numbers in Lua */ L0099 typedef LUA_NUMBER lua_Number;

Typically set to double on PCs.

L0100 L0101 L0102 /* type for integer functions */ L0103 typedef LUA_INTEGER lua_Integer;

Typically set to int (32-bit) on PCs.

L0104 L0105 L0106 L0107 /* L0108 ** state manipulation L0109 */ L0110 LUA_API lua_State *(lua_newstate) (lua_Alloc f, void *ud); L0111 LUA_API void (lua_close) (lua_State *L); L0112 LUA_API lua_State *(lua_newthread) (lua_State *L); L0113 L0114 LUA_API lua_CFunction (lua_atpanic) (lua_State *L, lua_CFunction panicf); L0115 L0116 L0117 /* L0118 ** basic stack manipulation L0119 */ L0120 LUA_API int (lua_gettop) (lua_State *L); L0121 LUA_API void (lua_settop) (lua_State *L, int idx); L0122 LUA_API void (lua_pushvalue) (lua_State *L, int idx); L0123 LUA_API void (lua_remove) (lua_State *L, int idx); L0124 LUA_API void (lua_insert) (lua_State *L, int idx); L0125 LUA_API void (lua_replace) (lua_State *L, int idx); L0126 LUA_API int (lua_checkstack) (lua_State *L, int sz); L0127 L0128 LUA_API void (lua_xmove) (lua_State *from, lua_State *to, int n); L0129 L0130 L0131 /* L0132 ** access functions (stack -> C) L0133 */ L0134 L0135 LUA_API int (lua_isnumber) (lua_State *L, int idx); L0136 LUA_API int (lua_isstring) (lua_State *L, int idx); L0137 LUA_API int (lua_iscfunction) (lua_State *L, int idx); L0138 LUA_API int (lua_isuserdata) (lua_State *L, int idx); L0139 LUA_API int (lua_type) (lua_State *L, int idx); L0140 LUA_API const char *(lua_typename) (lua_State *L, int tp); L0141 L0142 LUA_API int (lua_equal) (lua_State *L, int idx1, int idx2); L0143 LUA_API int (lua_rawequal) (lua_State *L, int idx1, int idx2); L0144 LUA_API int (lua_lessthan) (lua_State *L, int idx1, int idx2); L0145 L0146 LUA_API lua_Number (lua_tonumber) (lua_State *L, int idx); L0147 LUA_API lua_Integer (lua_tointeger) (lua_State *L, int idx); L0148 LUA_API int (lua_toboolean) (lua_State *L, int idx); L0149 LUA_API const char *(lua_tolstring) (lua_State *L, int idx, size_t *len); L0150 LUA_API size_t (lua_objlen) (lua_State *L, int idx); L0151 LUA_API lua_CFunction (lua_tocfunction) (lua_State *L, int idx); L0152 LUA_API void *(lua_touserdata) (lua_State *L, int idx); L0153 LUA_API lua_State *(lua_tothread) (lua_State *L, int idx); L0154 LUA_API const void *(lua_topointer) (lua_State *L, int idx); L0155 L0156 L0157 /* L0158 ** push functions (C -> stack) L0159 */ L0160 LUA_API void (lua_pushnil) (lua_State *L); L0161 LUA_API void (lua_pushnumber) (lua_State *L, lua_Number n); L0162 LUA_API void (lua_pushinteger) (lua_State *L, lua_Integer n); L0163 LUA_API void (lua_pushlstring) (lua_State *L, const char *s, size_t l); L0164 LUA_API void (lua_pushstring) (lua_State *L, const char *s); L0165 LUA_API const char *(lua_pushvfstring) (lua_State *L, const char *fmt, L0166 va_list argp); L0167 LUA_API const char *(lua_pushfstring) (lua_State *L, const char *fmt, ...); L0168 LUA_API void (lua_pushcclosure) (lua_State *L, lua_CFunction fn, int n); L0169 LUA_API void (lua_pushboolean) (lua_State *L, int b); L0170 LUA_API void (lua_pushlightuserdata) (lua_State *L, void *p); L0171 LUA_API int (lua_pushthread) (lua_State *L); L0172 L0173 L0174 /* L0175 ** get functions (Lua -> stack) L0176 */ L0177 LUA_API void (lua_gettable) (lua_State *L, int idx); L0178 LUA_API void (lua_getfield) (lua_State *L, int idx, const char *k); L0179 LUA_API void (lua_rawget) (lua_State *L, int idx); L0180 LUA_API void (lua_rawgeti) (lua_State *L, int idx, int n); L0181 LUA_API void (lua_createtable) (lua_State *L, int narr, int nrec); L0182 LUA_API void *(lua_newuserdata) (lua_State *L, size_t sz); L0183 LUA_API int (lua_getmetatable) (lua_State *L, int objindex); L0184 LUA_API void (lua_getfenv) (lua_State *L, int idx); L0185 L0186 L0187 /* L0188 ** set functions (stack -> Lua) L0189 */ L0190 LUA_API void (lua_settable) (lua_State *L, int idx); L0191 LUA_API void (lua_setfield) (lua_State *L, int idx, const char *k); L0192 LUA_API void (lua_rawset) (lua_State *L, int idx); L0193 LUA_API void (lua_rawseti) (lua_State *L, int idx, int n); L0194 LUA_API int (lua_setmetatable) (lua_State *L, int objindex); L0195 LUA_API int (lua_setfenv) (lua_State *L, int idx); L0196 L0197 L0198 /* L0199 ** `load' and `call' functions (load and run Lua code) L0200 */ L0201 LUA_API void (lua_call) (lua_State *L, int nargs, int nresults); L0202 LUA_API int (lua_pcall) (lua_State *L, int nargs, int nresults, int errfunc); L0203 LUA_API int (lua_cpcall) (lua_State *L, lua_CFunction func, void *ud); L0204 LUA_API int (lua_load) (lua_State *L, lua_Reader reader, void *dt, L0205 const char *chunkname); L0206 L0207 LUA_API int (lua_dump) (lua_State *L, lua_Writer writer, void *data); L0208 L0209 L0210 /* L0211 ** coroutine functions L0212 */ L0213 LUA_API int (lua_yield) (lua_State *L, int nresults); L0214 LUA_API int (lua_resume) (lua_State *L, int narg); L0215 LUA_API int (lua_status) (lua_State *L); L0216 L0217 /* L0218 ** garbage-collection function and options L0219 */ L0220 L0221 #define LUA_GCSTOP 0 L0222 #define LUA_GCRESTART 1 L0223 #define LUA_GCCOLLECT 2 L0224 #define LUA_GCCOUNT 3 L0225 #define LUA_GCCOUNTB 4 L0226 #define LUA_GCSTEP 5 L0227 #define LUA_GCSETPAUSE 6 L0228 #define LUA_GCSETSTEPMUL 7 L0229 L0230 LUA_API int (lua_gc) (lua_State *L, int what, int data); L0231 L0232 L0233 /* L0234 ** miscellaneous functions L0235 */ L0236 L0237 LUA_API int (lua_error) (lua_State *L); L0238 L0239 LUA_API int (lua_next) (lua_State *L, int idx); L0240 L0241 LUA_API void (lua_concat) (lua_State *L, int n); L0242 L0243 LUA_API lua_Alloc (lua_getallocf) (lua_State *L, void **ud); L0244 LUA_API void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); L0245 L0246 L0247 L0248 /* L0249 ** =============================================================== L0250 ** some useful macros L0251 ** =============================================================== L0252 */ L0253 L0254 #define lua_pop(L,n) lua_settop(L, -(n)-1) L0255 L0256 #define lua_newtable(L) lua_createtable(L, 0, 0) L0257 L0258 #define lua_register(L,n,f) (lua_pushcfunction(L, (f)), lua_setglobal(L, (n))) L0259 L0260 #define lua_pushcfunction(L,f) lua_pushcclosure(L, (f), 0) L0261 L0262 #define lua_strlen(L,i) lua_objlen(L, (i)) L0263 L0264 #define lua_isfunction(L,n) (lua_type(L, (n)) == LUA_TFUNCTION) L0265 #define lua_istable(L,n) (lua_type(L, (n)) == LUA_TTABLE) L0266 #define lua_islightuserdata(L,n) (lua_type(L, (n)) == LUA_TLIGHTUSERDATA) L0267 #define lua_isnil(L,n) (lua_type(L, (n)) == LUA_TNIL) L0268 #define lua_isboolean(L,n) (lua_type(L, (n)) == LUA_TBOOLEAN) L0269 #define lua_isthread(L,n) (lua_type(L, (n)) == LUA_TTHREAD) L0270 #define lua_isnone(L,n) (lua_type(L, (n)) == LUA_TNONE) L0271 #define lua_isnoneornil(L, n) (lua_type(L, (n)) <= 0) L0272 L0273 #define lua_pushliteral(L, s) \ L0274 lua_pushlstring(L, "" s, (sizeof(s)/sizeof(char))-1) L0275 L0276 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, (s)) L0277 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, (s)) L0278 L0279 #define lua_tostring(L,i) lua_tolstring(L, (i), NULL) L0280 L0281 L0282 L0283 /* L0284 ** compatibility macros and functions L0285 */ L0286 L0287 #define lua_open() luaL_newstate() L0288 L0289 #define lua_getregistry(L) lua_pushvalue(L, LUA_REGISTRYINDEX) L0290 L0291 #define lua_getgccount(L) lua_gc(L, LUA_GCCOUNT, 0) L0292 L0293 #define lua_Chunkreader lua_Reader L0294 #define lua_Chunkwriter lua_Writer L0295 L0296 L0297 /* hack */ L0298 LUA_API void lua_setlevel (lua_State *from, lua_State *to); L0299 L0300 L0301 /* L0302 ** {====================================================================== L0303 ** Debug API L0304 ** ======================================================================= L0305 */ L0306 L0307 L0308 /* L0309 ** Event codes L0310 */ L0311 #define LUA_HOOKCALL 0 L0312 #define LUA_HOOKRET 1 L0313 #define LUA_HOOKLINE 2 L0314 #define LUA_HOOKCOUNT 3 L0315 #define LUA_HOOKTAILRET 4 L0316 L0317 L0318 /* L0319 ** Event masks L0320 */ L0321 #define LUA_MASKCALL (1 << LUA_HOOKCALL) L0322 #define LUA_MASKRET (1 << LUA_HOOKRET) L0323 #define LUA_MASKLINE (1 << LUA_HOOKLINE) L0324 #define LUA_MASKCOUNT (1 << LUA_HOOKCOUNT) L0325 L0326 typedef struct lua_Debug lua_Debug; /* activation record */ L0327 L0328 L0329 /* Functions to be called by the debuger in specific events */ L0330 typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); L0331 L0332 L0333 LUA_API int lua_getstack (lua_State *L, int level, lua_Debug *ar); L0334 LUA_API int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); L0335 LUA_API const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); L0336 LUA_API const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); L0337 LUA_API const char *lua_getupvalue (lua_State *L, int funcindex, int n); L0338 LUA_API const char *lua_setupvalue (lua_State *L, int funcindex, int n); L0339 L0340 LUA_API int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); L0341 LUA_API lua_Hook lua_gethook (lua_State *L); L0342 LUA_API int lua_gethookmask (lua_State *L); L0343 LUA_API int lua_gethookcount (lua_State *L); L0344 L0345 L0346 struct lua_Debug { L0347 int event; L0348 const char *name; /* (n) */ L0349 const char *namewhat; /* (n) `global', `local', `field', `method' */ L0350 const char *what; /* (S) `Lua', `C', `main', `tail' */ L0351 const char *source; /* (S) */ L0352 int currentline; /* (l) */ L0353 int nups; /* (u) number of upvalues */ L0354 int linedefined; /* (S) */ L0355 int lastlinedefined; /* (S) */ L0356 char short_src[LUA_IDSIZE]; /* (S) */ L0357 /* private part */ L0358 int i_ci; /* active function */ L0359 }; L0360 L0361 /* }====================================================================== */ L0362 L0363 L0364 /****************************************************************************** L0365 * Copyright (C) 1994-2008 Lua.org, PUC-Rio. All rights reserved. L0366 * L0367 * Permission is hereby granted, free of charge, to any person obtaining L0368 * a copy of this software and associated documentation files (the L0369 * "Software"), to deal in the Software without restriction, including L0370 * without limitation the rights to use, copy, modify, merge, publish, L0371 * distribute, sublicense, and/or sell copies of the Software, and to L0372 * permit persons to whom the Software is furnished to do so, subject to L0373 * the following conditions: L0374 * L0375 * The above copyright notice and this permission notice shall be L0376 * included in all copies or substantial portions of the Software. L0377 * L0378 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, L0379 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF L0380 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. L0381 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY L0382 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, L0383 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE L0384 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. L0385 ******************************************************************************/ L0386 L0387 L0388 #endif

Lua 5.1.4: lua.h