lua.h源码详解

/*** $Id: lua.h,v 1.218.1.5 2008/08/06 13:30:12 roberto Exp $** Lua - An Extensible Extension Language** Lua.org, PUC-Rio, Brazil (http://www.lua.org)** See Copyright Notice at the end of this file*/#ifndef lua_h#define lua_h#include <stdarg.h>#include <stddef.h>#include "luaconf.h"#define LUA_VERSION"Lua 5.1"#define LUA_RELEASE"Lua 5.1.4"#define LUA_VERSION_NUM501#define LUA_COPYRIGHT"Copyright (C) 1994-2008 Lua.org, PUC-Rio"#define LUA_AUTHORS"R. Ierusalimschy, L. H. de Figueiredo & W. Celes"/* mark for precompiled code (`<esc>Lua') */#defineLUA_SIGNATURE"\033Lua"/* option for multiple returns in `lua_pcall' and `lua_call' */#define LUA_MULTRET(-1)/*** pseudo-indices*/#define LUA_REGISTRYINDEX(-10000)#define LUA_ENVIRONINDEX(-10001)#define LUA_GLOBALSINDEX(-10002)#define lua_upvalueindex(i)(LUA_GLOBALSINDEX-(i))/* thread status; 0 is OK */#define LUA_YIELD1#define LUA_ERRRUN2#define LUA_ERRSYNTAX3#define LUA_ERRMEM4#define LUA_ERRERR5typedef struct lua_State lua_State;typedef int (*lua_CFunction) (lua_State *L);/*** functions that read/write blocks when loading/dumping Lua chunks*/typedef const char * (*lua_Reader) (lua_State *L, void *ud, size_t *sz);typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud);/*** prototype for memory-allocation functions*/typedef void * (*lua_Alloc) (void *ud, void *ptr, size_t osize, size_t nsize);/*** basic types*/#define LUA_TNONE(-1)#define LUA_TNIL0#define LUA_TBOOLEAN1#define LUA_TLIGHTUSERDATA2#define LUA_TNUMBER3#define LUA_TSTRING4#define LUA_TTABLE5#define LUA_TFUNCTION6#define LUA_TUSERDATA7#define LUA_TTHREAD8//lua_type返回的类型常量/* minimum Lua stack available to a C function */#define LUA_MINSTACK20/*** generic extra include file*/#if defined(LUA_USER_H)#include LUA_USER_H#endif/* type of numbers in Lua */typedef LUA_NUMBER lua_Number;/* type for integer functions */typedef LUA_INTEGER lua_Integer;/*** state manipulation*/LUA_API lua_State *(lua_newstate) (lua_Alloc f, void *ud);//Lua脚本的编译执行是相互独立的，在不同的线程上执行。通过luaL_newstate()函数可以申请一个虚拟机，返回指针类型 lua_State。今后其他所有Lua Api函数的调用都需要此指针作为第一参数，用来指定某个虚拟机。LUA_API void       (lua_close) (lua_State *L);//销毁指定 Lua 状态机中的所有对象（如果有垃圾收集相关的元方法的话，会调用它们），并且释放状态机中使用的所有动态内存。LUA_API lua_State *(lua_newthread) (lua_State *L);//可以在一个状态中创建其它线程，这个函数会返回一个lua_State指针，表示新建的线程，它还会将新线程作为一个类型为thread的值压入栈中。LUA_API lua_CFunction (lua_atpanic) (lua_State *L, lua_CFunction panicf);/*** basic stack manipulation*/LUA_API int   (lua_gettop) (lua_State *L);//返回栈中元素的个数，也就是返回栈顶元素的索引LUA_API void  (lua_settop) (lua_State *L, int idx);//设置栈顶的位置，高了的话用nil补足，低了的话删除多余的LUA_API void  (lua_pushvalue) (lua_State *L, int idx);//会将指定索引的值的副本压入栈顶LUA_API void  (lua_remove) (lua_State *L, int idx);//移除指定索引上的值，并将之上的元素全部下移LUA_API void  (lua_insert) (lua_State *L, int idx);//会将指定位置之上的元素全部上移，然后把栈顶元素移到该位置LUA_API void  (lua_replace) (lua_State *L, int idx);//弹出栈顶的值，并将该值设置到指定索引上LUA_API int   (lua_checkstack) (lua_State *L, int sz);//用来检查栈中是否有足够的空间LUA_API void  (lua_xmove) (lua_State *from, lua_State *to, int n);//从from栈中弹出n个元素到to栈中/*** access functions (stack -> C)*/LUA_API int             (lua_isnumber) (lua_State *L, int idx);//检查栈中指定位置的元素是否可以转换为numberLUA_API int             (lua_isstring) (lua_State *L, int idx);//检查栈中指定位置的元素是否可以转换为stringLUA_API int             (lua_iscfunction) (lua_State *L, int idx);//检查栈中指定位置的元素是否可以转换为cfunctionLUA_API int             (lua_isuserdata) (lua_State *L, int idx);//检查栈中指定位置的元素是否可以转换为userdataLUA_API int             (lua_type) (lua_State *L, int idx);//返回指定位置元素的累心不过并且保存在idx中，它会返回很多类型常量，比如（LUA_TBOOLEAN），上面有定义LUA_API const char     *(lua_typename) (lua_State *L, int tp);//返回tp表示的类型名LUA_API int            (lua_equal) (lua_State *L, int idx1, int idx2);//索引 index1 和 index2 中的值相同的话，返回 1 。否则返回 0 。如果任何一个索引无效也会返回 0LUA_API int            (lua_rawequal) (lua_State *L, int idx1, int idx2);//检测idx1是否等于idx2，此函数不会调用任何元表的方法LUA_API int            (lua_lessthan) (lua_State *L, int idx1, int idx2);//如果索引 index1 处的值小于索引 index2 处的值时，返回 1 ；否则返回 0 。如果任何一个索引无效，也会返回 0 。 LUA_API lua_Number      (lua_tonumber) (lua_State *L, int idx);//检查这个元素是否为number类型（不用转换），成功的话返回该值，否则返回0LUA_API lua_Integer     (lua_tointeger) (lua_State *L, int idx);//检查这个元素是否为integer类型（不用转换），成功的话返回该值，否则返回0LUA_API int             (lua_toboolean) (lua_State *L, int idx);//检查这个元素是否为boolean类型（不用转换），成功的话返回该值，否则返回0LUA_API const char     *(lua_tolstring) (lua_State *L, int idx, size_t *len);//返回一个指向内部字符串副本的指针，并将该字符串的长度存入len中。返回的内部副本不能修改，前面有constLUA_API size_t          (lua_objlen) (lua_State *L, int idx);//返回一个对象的“长度”，对于字符串和table来说这个结果就是#的结果。LUA_API lua_CFunction   (lua_tocfunction) (lua_State *L, int idx);//检查这个元素是否为cfunction类型（不用转换），成功的话返回该值，否则返回NULLLUA_API void       *(lua_touserdata) (lua_State *L, int idx);//检查这个元素是否为userdata类型LUA_API lua_State      *(lua_tothread) (lua_State *L, int idx);//检查这个元素是否为thread类型LUA_API const void     *(lua_topointer) (lua_State *L, int idx);//检查这个元素是否为pointer类型/*** push functions (C -> stack)*/LUA_API void  (lua_pushnil) (lua_State *L);//向栈中压入nilLUA_API void  (lua_pushnumber) (lua_State *L, lua_Number n);//向栈中压入numberLUA_API void  (lua_pushinteger) (lua_State *L, lua_Integer n);//向栈中压入integerLUA_API void  (lua_pushlstring) (lua_State *L, const char *s, size_t l);//向栈中压入任意字符串（char* 以及长度）LUA_API void  (lua_pushstring) (lua_State *L, const char *s);//向栈中压入以0结尾的字符串LUA_API const char *(lua_pushvfstring) (lua_State *L, const char *fmt,//                                                      va_list argp);LUA_API const char *(lua_pushfstring) (lua_State *L, const char *fmt, ...);LUA_API void  (lua_pushcclosure) (lua_State *L, lua_CFunction fn, int n);LUA_API void  (lua_pushboolean) (lua_State *L, int b);LUA_API void  (lua_pushlightuserdata) (lua_State *L, void *p);LUA_API int   (lua_pushthread) (lua_State *L);/*** get functions (Lua -> stack)*/LUA_API void  (lua_gettable) (lua_State *L, int idx);//就是以栈顶的值作为key来访问idx位置上的table，这时table中的第1个元素的值就放到栈顶了LUA_API void  (lua_getfield) (lua_State *L, int idx, const char *k);//读取table中字段的值，将值压入栈中// background = {r = 0.3, g = 1, b = 0.5}// lua_getglobal(L, "background");// lua_getfield(L, -1, "r");// 这时r的值就到栈顶了LUA_API void  (lua_rawget) (lua_State *L, int idx);LUA_API void  (lua_rawgeti) (lua_State *L, int idx, int n);LUA_API void  (lua_createtable) (lua_State *L, int narr, int nrec);//创建一个新的空 table 压入堆栈。这个新 table 将被预分配 narr 个元素的数组空间以及 nrec 个元素的非数组空间。当你明确知道表中需要多少个元素时，预分配就非常有用。如果你不知道，可以使用函数 lua_newtable。 LUA_API void *(lua_newuserdata) (lua_State *L, size_t sz);LUA_API int   (lua_getmetatable) (lua_State *L, int objindex);LUA_API void  (lua_getfenv) (lua_State *L, int idx);/*** set functions (stack -> Lua)*/LUA_API void  (lua_settable) (lua_State *L, int idx);LUA_API void  (lua_setfield) (lua_State *L, int idx, const char *k);LUA_API void  (lua_rawset) (lua_State *L, int idx);LUA_API void  (lua_rawseti) (lua_State *L, int idx, int n);LUA_API int   (lua_setmetatable) (lua_State *L, int objindex);LUA_API int   (lua_setfenv) (lua_State *L, int idx);/*** `load' and `call' functions (load and run Lua code)*/LUA_API void  (lua_call) (lua_State *L, int nargs, int nresults);LUA_API int   (lua_pcall) (lua_State *L, int nargs, int nresults, int errfunc);LUA_API int   (lua_cpcall) (lua_State *L, lua_CFunction func, void *ud);LUA_API int   (lua_load) (lua_State *L, lua_Reader reader, void *dt,                                        const char *chunkname);LUA_API int (lua_dump) (lua_State *L, lua_Writer writer, void *data);/*** coroutine functions*/LUA_API int  (lua_yield) (lua_State *L, int nresults);//可以挂起lua的调用者LUA_API int  (lua_resume) (lua_State *L, int narg);//可以启动一个协同程序，它的用法就像lua_call一样。将待调用的函数压入栈中，并且压入参数，最后在lua_resume时传入参数的数量nargLUA_API int  (lua_status) (lua_State *L);//返回线程 L 的状态。正常的线程状态是 0 。 当线程执行完毕或发生一个错误时，状态值是错误码。 如果线程被挂起，状态为 LUA_YIELD 。/*** garbage-collection function and options*/#define LUA_GCSTOP0//停止收集器#define LUA_GCRESTART1//重启收集器#define LUA_GCCOLLECT2//执行一轮完整的垃圾收集周期，收集并释放所有不可到达的对象，这时默认选项#define LUA_GCCOUNT3//返回lua当前使用的内存数量，单位是KB#define LUA_GCCOUNTB4//返回lua当前使用的内存数量的千字节余数。#define LUA_GCSTEP5//执行一些垃圾收集工作#define LUA_GCSETPAUSE6//设置收集器的pause参数，其值由data参数指定，表示一个百分比。当data为100时，pause参数设为1（100%）。这个参数决定收集器在周期之间等待的时间#define LUA_GCSETSTEPMUL7//设置收集器的stepmul参数，其值也是由data参数指定，表示一个百分比。这个参数决定收集器的工作速度#define LUA_GCISRUNNING9//收集器是否在工作LUA_API int (lua_gc) (lua_State *L, int what, int data);//进行垃圾回收，what指定了要做的事，工作的总量由第二个参数data决定/*** miscellaneous functions*/LUA_API int   (lua_error) (lua_State *L);//产生一个 Lua 错误。错误信息（实际上可以是任何类型的 Lua 值）必须被置入栈顶。这个函数会做一次长跳转，因此它不会再返回。LUA_API int   (lua_next) (lua_State *L, int idx);//先把 表(lua栈 index所指的表), 的当前索引弹出，再把table 当前索引的值弹出，也就是先弹出 table的索引，再弹出table索引的值LUA_API void  (lua_concat) (lua_State *L, int n);//连接栈顶的 n 个值，然后将这些值出栈，并把结果放在栈顶。如果 n 为 1 ，结果就是一个字符串放在栈上（即，函数什么都不做）；如果 n 为 0 ，结果是一个空串。 连接依照 Lua 中创建语义完成，如果尝试把两个不能连接的类型连接，程序会给出错误提示。LUA_API lua_Alloc (lua_getallocf) (lua_State *L, void **ud);//返回给定状态机的内存分配器函数。LUA_API void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);/*** ===============================================================** some useful macros** ===============================================================*/#define lua_pop(L,n)lua_settop(L, -(n)-1)//设置栈顶位置#define lua_newtable(L)lua_createtable(L, 0, 0)#define lua_register(L,n,f) (lua_pushcfunction(L, (f)), lua_setglobal(L, (n)))#define lua_pushcfunction(L,f)lua_pushcclosure(L, (f), 0)#define lua_strlen(L,i)lua_objlen(L, (i))#define lua_isfunction(L,n)(lua_type(L, (n)) == LUA_TFUNCTION)#define lua_istable(L,n)(lua_type(L, (n)) == LUA_TTABLE)#define lua_islightuserdata(L,n)(lua_type(L, (n)) == LUA_TLIGHTUSERDATA)#define lua_isnil(L,n)(lua_type(L, (n)) == LUA_TNIL)#define lua_isboolean(L,n)(lua_type(L, (n)) == LUA_TBOOLEAN)#define lua_isthread(L,n)(lua_type(L, (n)) == LUA_TTHREAD)#define lua_isnone(L,n)(lua_type(L, (n)) == LUA_TNONE)#define lua_isnoneornil(L, n)(lua_type(L, (n)) <= 0)#define lua_pushliteral(L, s)\lua_pushlstring(L, "" s, (sizeof(s)/sizeof(char))-1)#define lua_setglobal(L,s)lua_setfield(L, LUA_GLOBALSINDEX, (s))#define lua_getglobal(L,s)lua_getfield(L, LUA_GLOBALSINDEX, (s))#define lua_tostring(L,i)lua_tolstring(L, (i), NULL)/*** compatibility macros and functions*/#define lua_open()luaL_newstate()#define lua_getregistry(L)lua_pushvalue(L, LUA_REGISTRYINDEX)#define lua_getgccount(L)lua_gc(L, LUA_GCCOUNT, 0)#define lua_Chunkreaderlua_Reader#define lua_Chunkwriterlua_Writer/* hack */LUA_API void lua_setlevel(lua_State *from, lua_State *to);/*** {======================================================================** Debug API** =======================================================================*//*** Event codes*/#define LUA_HOOKCALL0#define LUA_HOOKRET1#define LUA_HOOKLINE2#define LUA_HOOKCOUNT3#define LUA_HOOKTAILRET 4/*** Event masks*/#define LUA_MASKCALL(1 << LUA_HOOKCALL)#define LUA_MASKRET(1 << LUA_HOOKRET)#define LUA_MASKLINE(1 << LUA_HOOKLINE)#define LUA_MASKCOUNT(1 << LUA_HOOKCOUNT)typedef struct lua_Debug lua_Debug;  /* activation record *//* Functions to be called by the debuger in specific events */typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);LUA_API int lua_getstack (lua_State *L, int level, lua_Debug *ar);LUA_API int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);LUA_API const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);LUA_API const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);LUA_API const char *lua_getupvalue (lua_State *L, int funcindex, int n);LUA_API const char *lua_setupvalue (lua_State *L, int funcindex, int n);LUA_API int lua_sethook (lua_State *L, lua_Hook func, int mask, int count);LUA_API lua_Hook lua_gethook (lua_State *L);LUA_API int lua_gethookmask (lua_State *L);LUA_API int lua_gethookcount (lua_State *L);/* From Lua 5.2. */LUA_API void *lua_upvalueid (lua_State *L, int idx, int n);LUA_API void lua_upvaluejoin (lua_State *L, int idx1, int n1, int idx2, int n2);LUA_API int lua_loadx (lua_State *L, lua_Reader reader, void *dt,       const char *chunkname, const char *mode);struct lua_Debug {  int event;  const char *name;/* (n) */  const char *namewhat;/* (n) `global', `local', `field', `method' */  const char *what;/* (S) `Lua', `C', `main', `tail' */  const char *source;/* (S) */  int currentline;/* (l) */  int nups;/* (u) number of upvalues */  int linedefined;/* (S) */  int lastlinedefined;/* (S) */  char short_src[LUA_IDSIZE]; /* (S) */  /* private part */  int i_ci;  /* active function */};/* }====================================================================== *//******************************************************************************* Copyright (C) 1994-2008 Lua.org, PUC-Rio.  All rights reserved.** Permission is hereby granted, free of charge, to any person obtaining* a copy of this software and associated documentation files (the* "Software"), to deal in the Software without restriction, including* without limitation the rights to use, copy, modify, merge, publish,* distribute, sublicense, and/or sell copies of the Software, and to* permit persons to whom the Software is furnished to do so, subject to* the following conditions:** The above copyright notice and this permission notice shall be* included in all copies or substantial portions of the Software.** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.******************************************************************************/#endif