lua 5.3 英文手册 自己收集整理版

 
/*
** state manipulation 
*/
LUA_API lua_State *(lua_newstate) (lua_Alloc f, void *ud);//创建lua虚拟机
LUA_API void       (lua_close) (lua_State *L); //销毁指定 Lua 状态机中的所有对象
/**
lua_newthread
创建一个新线程，并将其压入堆栈，并返回维护这个线程的 lua_State 指针。这个函数返回的新状态机共享原有状态机中的所有对象（比如一些 table），但是它有独立的执行堆栈。
没有显式的函数可以用来关闭或销毁掉一个线程。线程跟其它 Lua 对象一样是垃圾收集的条目之一。
*/
LUA_API lua_State *(lua_newthread) (lua_State *L);
/**
lua_tocfunction
lua_CFunction lua_tocfunction (lua_State *L, int index);
把给定索引处的 Lua 值转换为一个 C 函数。这个值必须是一个 C 函数；如果不是就返回 NULL 。
*/
LUA_API lua_CFunction (lua_atpanic) (lua_State *L, lua_CFunction panicf);

/**
lua_Number
typedef double lua_Number;
Lua 中数字的类型。确省是 double ，但是你可以在 luaconf.h 中修改它。

通过修改配置文件你可以改变 Lua 让它操作其它数字类型（例如：float 或是 long ）。
*/
LUA_API const lua_Number *(lua_version) (lua_State *L);
/*
** basic stack manipulation 虚拟栈基本操作
*/
LUA_API int   (lua_absindex) (lua_State *L, int idx); 
LUA_API int   (lua_gettop) (lua_State *L); //获取栈中元素个数
LUA_API void  (lua_settop) (lua_State *L, int idx); //重置栈顶指针指向idx的位置
LUA_API void  (lua_pushvalue) (lua_State *L, int idx);//复制idx位置元素并压入到栈顶
LUA_API void  (lua_rotate) (lua_State *L, int idx, int n); 
LUA_API void  (lua_copy) (lua_State *L, int fromidx, int toidx); 
LUA_API int   (lua_checkstack) (lua_State *L, int n);//
LUA_API void  (lua_xmove) (lua_State *from, lua_State *to, int n);
/***
** access functions (stack -> C)  虚拟栈数据传递到C++中
*/ 
/**
int lua_is... (lua_State *L, int index)：检查一个元素能否被转换成指定的类型。
*/
LUA_API int             (lua_isnumber) (lua_State *L, int idx);
LUA_API int             (lua_isstring) (lua_State *L, int idx);
LUA_API int             (lua_iscfunction) (lua_State *L, int idx);
LUA_API int             (lua_isinteger) (lua_State *L, int idx);
LUA_API int             (lua_isuserdata) (lua_State *L, int idx);
LUA_API int             (lua_type) (lua_State *L, int idx); //返回栈中元素的类型；

LUA_API const char     *(lua_typename) (lua_State *L, int tp);//返回type对应的名字字符串，第二个参数为lua_type返回的类型
/**
int lua_to... (lua_State *L, int index)：类型转换函数
*/
LUA_API lua_Number      (lua_tonumberx) (lua_State *L, int idx, int *isnum);//将给定索引处的Lua值转换为C类型lua_Number(参见lua_Number)。Lua值必须是数字或可转换为数字的字符串(参见§3.4.3);否则，lua_tonumberx返回0。
LUA_API lua_Integer     (lua_tointegerx) (lua_State *L, int idx, int *isnum);
LUA_API int             (lua_toboolean) (lua_State *L, int idx);
LUA_API const char     *(lua_tolstring) (lua_State *L, int idx, size_t *len);
/***
lua_rawlen
/返回给定索引处值的固有“长度”: 对于字符串,它指字符串的长度;
//对于表: 它指不触发元方法的情况下取长度操作'#'应得到的值;
//对于用户数据: 它指为该用户数据分配的内存块的大小;
//对于其它值: 它为0.
*/
LUA_API size_t          (lua_rawlen) (lua_State *L, int idx);
LUA_API lua_CFunction   (lua_tocfunction) (lua_State *L, int idx);
LUA_API void           *(lua_touserdata) (lua_State *L, int idx);
LUA_API lua_State      *(lua_tothread) (lua_State *L, int idx);
LUA_API const void     *(lua_topointer) (lua_State *L, int idx);
LUA_API void  (lua_arith) (lua_State *L, int op); //对堆栈顶部的两个值(如果是负数，则为一个)执行算术或逐位操作，其中顶部的值是第二个操作数，弹出这些值，并推送操作的结果。该函数遵循相应的Lua操作符的语义(即，它可以调用元方法)。
LUA_API int   (lua_rawequal) (lua_State *L, int idx1, int idx2);//如果在索引的两个值，则返回1 index1和 index2是原始地等于（即，不调用__eq元方法）。否则返回0.如果任何索引无效，则返回0
LUA_API int   (lua_compare) (lua_State *L, int idx1, int idx2, int op); //比较两个Lua值。如果索引处的值index1满足op 与索引处的值进行比较时返回1 index2，则遵循相应Lua运算符的语义（即，它可以调用metamethods）。否则返回0.如果任何索引无效，则返回0。
/***
** push functions (C -> stack)   C++数据传递到虚拟栈中
*/
LUA_API void        (lua_pushnil) (lua_State *L); //将nil值推入堆栈。
LUA_API void        (lua_pushnumber) (lua_State *L, lua_Number n);
LUA_API void        (lua_pushinteger) (lua_State *L, lua_Integer n);
LUA_API const char *(lua_pushlstring) (lua_State *L, const char *s, size_t len);
LUA_API const char *(lua_pushstring) (lua_State *L, const char *s);
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数据传递到虚拟栈中
*/
LUA_API int (lua_getglobal) (lua_State *L, const char *name);
LUA_API int (lua_gettable) (lua_State *L, int idx);
/** int t = lua_getfield(L, 2/*index*/, "type"/*key*/); //取出t.type 的值，并放到栈顶!!*/
LUA_API int (lua_getfield) (lua_State *L, int idx, const char *k);
LUA_API int (lua_geti) (lua_State *L, int idx, lua_Integer n);
LUA_API int (lua_rawget) (lua_State *L, int idx);
LUA_API int (lua_rawgeti) (lua_State *L, int idx, lua_Integer n);
LUA_API int (lua_rawgetp) (lua_State *L, int idx, const void *p);
LUA_API void  (lua_createtable) (lua_State *L, int narr, int nrec);
LUA_API void *(lua_newuserdata) (lua_State *L, size_t sz);
LUA_API int   (lua_getmetatable) (lua_State *L, int objindex);
LUA_API int  (lua_getuservalue) (lua_State *L, int idx); 
/*
** set functions (stack -> Lua 虚拟栈数据传递到Lua空间中
*/
LUA_API void  (lua_setglobal) (lua_State *L, const char *name);
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_seti) (lua_State *L, int idx, lua_Integer n);
LUA_API void  (lua_rawset) (lua_State *L, int idx);
LUA_API void  (lua_rawseti) (lua_State *L, int idx, lua_Integer n);
LUA_API void  (lua_rawsetp) (lua_State *L, int idx, const void *p);
LUA_API int   (lua_setmetatable) (lua_State *L, int objindex);
LUA_API void  (lua_setuservalue) (lua_State *L, int idx); 

/*
** 'load' and 'call' functions (load and run Lua code)
*/
/*** 
void lua_call (lua_State *L, int nargs, int nresults);
要调用一个函数，必须使用以下协议:首先，要调用的函数被推入堆栈;然后，按直接顺序推送函数的参数;也就是说，首先推第一个参数。最后调用lua_call;nargs是您推入堆栈的参数的数量。当函数被调用时，所有参数和函数值都会从堆栈中弹出。函数返回时，将函数结果推入堆栈。结果的数量调整为nresults，除非nresults是LUA_MULTRET。在这种情况下，函数的所有结果都被推送;Lua负责将返回的值放入堆栈空间，但它并不确保堆栈中有任何额外的空间。函数结果按直接顺序推入堆栈(首先推入第一个结果)，这样在调用之后，最后一个结果就位于堆栈的顶部。
lua_callk 与 lua_call相同 lua_callk允许  yield
*/
LUA_API void  (lua_callk) (lua_State *L, int nargs, int nresults,lua_KContext ctx, lua_KFunction k); 
LUA_API int   (lua_pcallk) (lua_State *L, int nargs, int nresults, int errfunc,lua_KContext ctx, lua_KFunction k);  //与上面相同 多了一个错误处理
/**** lua_load 在不运行Lua块的情况下加载Lua块。如果没有错误，lua_load将编译后的块作为Lua函数推送到堆栈的顶部。否则，它将推送一条错误消息。*/
LUA_API int   (lua_load) (lua_State *L, lua_Reader reader, void *dt, const char *chunkname, const char *mode); 
/**
lua_dump 将函数转储为二进制块。接收堆栈顶部的Lua函数，并生成一个二进制块，如果再次加载该块，将生成一个与转储的函数等价的函数。当生成块的一部分时，lua_dump使用给定的数据调用函数writer(参见lua_Writer)来编写它们。
如果strip为真，则二进制表示可能不包含关于函数的所有调试信息，以节省空间。返回的值是上次调用写入器返回的错误代码;0表示没有错误。
此函数不会从堆栈中弹出Lua函数。*/
LUA_API int (lua_dump) (lua_State *L, lua_Writer writer, void *data, int strip);


/*  coroutine functions 协同程序*/ 
/**
当C函数调用lua_yieldk时，正在运行的协同程序暂停执行，对启动该协同程序的lua_resume的调用返回。参数nresults是将作为结果传递给lua_resume的堆栈中的值的数量。
当再次恢复协调程序时，Lua调用给定的延续函数k来继续执行生成的C函数(参见§4.7)。这个延续函数从前一个函数接收相同的堆栈，删除n个结果并由传递给lua_resume的参数替换。此外，延续函数接收传递给lua_yield dk的值ctx。
通常，这个函数不会返回;当协程最终恢复时，它将继续执行continuation函数。但是，有一种特殊的情况，就是从行或count钩子中调用这个函数(参见§4.9)。在这种情况下，应该调用lua_yield dk，而不使用延续(可能以lua_yield的形式)，也不使用结果，并且钩子应该在调用之后立即返回。Lua将让步，当协程再次恢复时，它将继续执行触发钩子的(Lua)函数的正常执行。
如果这个函数是从一个没有延续函数的挂起C调用的线程中调用的，或者是从一个没有在resume中运行的线程(例如，主线程)中调用的，那么它可能会引发一个错误。*/
LUA_API int  (lua_yieldk)     (lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k);
LUA_API int  (lua_resume)     (lua_State *L, lua_State *from, int narg);
LUA_API int  (lua_status)     (lua_State *L);
LUA_API int (lua_isyieldable) (lua_State *L); 
LUA_API int (lua_gc) (lua_State *L, int what, int data);


/*
** miscellaneous functions 杂项
*/ 
LUA_API int   (lua_error) (lua_State *L);//生成Lua错误。错误消息(实际上可以是任何类型的Lua值)必须位于堆栈顶部。这个函数执行跳远，因此永远不会返回。
LUA_API int   (lua_next) (lua_State *L, int idx);//pairs遍历table时用来取下一个内容的函数.
LUA_API void  (lua_concat) (lua_State *L, int n); // 将堆栈顶部的n个值连接起来，弹出它们，并将结果留在顶部
LUA_API void  (lua_len)    (lua_State *L, int idx);
LUA_API size_t   (lua_stringtonumber) (lua_State *L, const char *s);
LUA_API lua_Alloc (lua_getallocf) (lua_State *L, void **ud);
LUA_API void      (lua_setallocf) (lua_State *L, lua_Alloc f, void *ud); 

 
 /****

debug hook功能
Lua5.1开始 提供了较为完善的debug库函数，其中的sethook可以让用户自己设置hook函数来监控程序的某些运行行为，这包括：调用 函数，从函数返回和将要运行新的一行代码，每当这些事件(event)发生时hook函数都会被调用。
*/

typedef struct lua_Debug lua_Debug;  /* activation record */ 
/* Functions to be called by the debugger 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 void *(lua_upvalueid) (lua_State *L, int fidx, int n);
LUA_API void  (lua_upvaluejoin) (lua_State *L, int fidx1, int n1,
                                               int fidx2, int n2);

LUA_API void (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); 
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 linedefined;    /* (S) */
  int lastlinedefined;    /* (S) */
  unsigned char nups;    /* (u) number of upvalues */
  unsigned char nparams;/* (u) number of parameters */
  char isvararg;        /* (u) */
  char istailcall;    /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* private part */
  struct CallInfo *i_ci;  /* active function */
}; 

 简单的总结一下

     lua 提供的函数分为几类

          1) 虚拟机对象管理类

          2）lua脚本 C++ 虚拟机中  数据传递 转换 比较类 

          3）虚拟机视角集合维护 及 处理方法

          4）线程维护函数

          5）钩子 及监控 函数