diff options
Diffstat (limited to 'modules/ansi_c/lua_api')
| -rw-r--r-- | modules/ansi_c/lua_api | 29 |
1 files changed, 15 insertions, 14 deletions
diff --git a/modules/ansi_c/lua_api b/modules/ansi_c/lua_api index f8bc0be6..b3586d8e 100644 --- a/modules/ansi_c/lua_api +++ b/modules/ansi_c/lua_api @@ -1,6 +1,6 @@ lua_absindex lua_absindex(lua_State *L, int idx) [int]\nConverts the acceptable index `idx` into an absolute index (that is, one that\ndoes not depend on the stack top).\n lua_Alloc (*lua_Alloc)(void *ud, void *ptr, size_t osize, size_t nsize) [void*]\nThe type of the memory-allocation function used by Lua states. The allocator\nfunction must provide a functionality similar to `realloc`, but not exactly\nthe same. Its arguments are `ud`, an opaque pointer passed to `lua_newstate`;\n`ptr`, a pointer to the block being allocated/reallocated/freed; `osize`,\nthe original size of the block or some code about what is being allocated;\nand `nsize`, the new size of the block.\n\nWhen `ptr` is not `NULL`, `osize` is the size of the block pointed by `ptr`,\nthat is, the size given when it was allocated or reallocated.\n\nWhen `ptr` is `NULL`, `osize` encodes the kind of object that Lua is allocating.\n`osize` is any of `LUA_TSTRING`, `LUA_TTABLE`, `LUA_TFUNCTION`, `LUA_TUSERDATA`,\nor `LUA_TTHREAD` when (and only when) Lua is creating a new object of that type.\nWhen `osize` is some other value, Lua is allocating memory for something else.\n\nLua assumes the following behavior from the allocator function:\n\nWhen `nsize` is zero, the allocator must behave like `free` and return `NULL`.\n\nWhen `nsize` is not zero, the allocator must behave like `realloc`. The\nallocator returns `NULL` if and only if it cannot fulfill the request. Lua\nassumes that the allocator never fails when `osize >= nsize`.\n\nHere is a simple implementation for the allocator function. It is used in\nthe auxiliary library by `luaL_newstate`.\n\n static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {\n (void)ud; (void)osize; /* not used */\n if (nsize == 0) {\n free(ptr);\n return NULL;\n }\n else\n return realloc(ptr, nsize);\n }\n\nNote that Standard C ensures that `free(NULL)` has no effect and that\n`realloc(NULL, size)` is equivalent to `malloc(size)`. This code assumes that\n`realloc` does not fail when shrinking a block. (Although Standard C does not\nensure this behavior, it seems to be a safe assumption.)\n -lua_arith lua_arith(lua_State *L, int op) [void]\nPerforms an arithmetic or bitwise operation over the two values (or one, in the\ncase of negations) at the top of the stack, with the value at the top being the\nsecond operand, pops these values, and pushes the result of the operation. The\nfunction follows the semantics of the corresponding Lua operator (that is, it\nmay call metamethods).\n\nThe value of `op` must be one of the following constants:\n * LUA_OPADD: performs addition (`+`)\n * LUA_OPSUB: performs subtraction (`-`)\n * LUA_OPMUL: performs multiplication (`*`)\n * LUA_OPDIV: performs float division (`/`)\n * LUA_OPIDIV: performs floor division (`//`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\n * LUA_OPBNOT: performs bitwise negation (`~`)\n * LUA_OPBAND: performs bitwise and (`&`)\n * LUA_OPBOR: performs bitwise or (`|`)\n * LUA_OPBXOR: performs bitwise exclusive or (`~`)\n * LUA_OPBSHL: performs left shift (`<<`)\n * LUA_OPBSHR: performs right shift (`>>`)\n +lua_arith lua_arith(lua_State *L, int op) [void]\nPerforms an arithmetic or bitwise operation over the two values (or one, in the\ncase of negations) at the top of the stack, with the value at the top being the\nsecond operand, pops these values, and pushes the result of the operation. The\nfunction follows the semantics of the corresponding Lua operator (that is, it\nmay call metamethods).\n\nThe value of `op` must be one of the following constants:\n * LUA_OPADD: performs addition (`+`)\n * LUA_OPSUB: performs subtraction (`-`)\n * LUA_OPMUL: performs multiplication (`*`)\n * LUA_OPDIV: performs float division (`/`)\n * LUA_OPIDIV: performs floor division (`//`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\n * LUA_OPBNOT: performs bitwise NOT (`~`)\n * LUA_OPBAND: performs bitwise AND (`&`)\n * LUA_OPBOR: performs bitwise OR (`|`)\n * LUA_OPBXOR: performs bitwise exclusive OR (`~`)\n * LUA_OPBSHL: performs left shift (`<<`)\n * LUA_OPBSHR: performs right shift (`>>`)\n lua_atpanic lua_atpanic(lua_State *L, lua_CFunction panicf) [lua_CFunction]\nSets a new panic function and returns the old one (see §4.6).\n\nIf an error happens outside any protected environment, Lua calls a _panic\nfunction_ and then calls `abort`, thus exiting the host application. Your panic\nfunction can avoid this exit by never returning (e.g., doing a long jump).\n\nThe panic function runs as if it were a message handler (see §2.3); in\nparticular, the error message is at the top of the stack. However, there is no\nguarantees about stack space. To push anything on the stack, the panic function\nshould first check the available space (see §4.2).\n lua_call lua_call(lua_State *L, int nargs, int nresults) [void]\nCalls a function.\n\nTo call a function you must use the following protocol: first, the function\nto be called is pushed onto the stack; then, the arguments to the function\nare pushed in direct order; that is, the first argument is pushed first.\nFinally you call `lua_call`; `nargs` is the number of arguments that you\npushed onto the stack. All arguments and the function value are popped from\nthe stack when the function is called. The function results are pushed onto\nthe stack when the function returns. The number of results is adjusted to\n`nresults`, unless `nresults` is `LUA_MULTRET`. In this case, all results from\nthe function are pushed. Lua takes care that the returned values fit into the\nstack space, but it does not ensure any extra space on the stack. The function\nresults are pushed onto the stack in direct order (the first result is pushed\nfirst), so that after the call the last result is on the top of the stack.\n\nAny error inside the called function is propagated upwards (with a `longjmp`).\n\nThe following example shows how the host program can do the equivalent to\nthis Lua code:\n\n a = f("how", t.x, 14)\n\nHere it is in C:\n\n lua_getglobal(L, "f"); /* function to be called */\n lua_pushliteral(L, "how"); /* 1st argument */\n lua_getglobal(L, "t"); /* table to be indexed */\n lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */\n lua_remove(L, -2); /* remove 't' from the stack */\n lua_pushinteger(L, 14); /* 3rd argument */\n lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */\n lua_setglobal(L, "a"); /* set global 'a' */\n\nNote that the code above is _balanced_: at its end, the stack is back to\nits original configuration. This is considered good programming practice.\n lua_callk lua_callk(lua_State *L, int nargs, int nresults, lua_KContext ctx, lua_KFunction k) [void]\nThis function behaves exactly like `lua_call`, but allows the called function to\nyield (see §4.7).\n @@ -42,7 +42,7 @@ lua_isyieldable lua_isyieldable(lua_State *L) [int]\nReturns 1 if the given coro lua_KContext lua_KContext [typedef ... lua_KContext]\nThe type for continuation-function contexts. It must be a numerical type. This\ntype is defined as `intptr_t` when `intptr_t` is available, so that it can store\npointers too. Otherwise, it is defined as `ptrdiff_t`.\n lua_KFunction lua_KFunction [int (*)(lua_State *L, int status, lua_KContext ctx)]\nType for continuation functions (see §4.7).\n lua_len lua_len(lua_State *L, int index) [void]\nReturns the length of the value at the given index. It is equivalent to the\n'`#`' operator in Lua (see §3.4.7) and may trigger a metamethod for the "length"\nevent (see §2.4). The result is pushed on the stack.\n -lua_load lua_load(lua_State *L, lua_Reader reader, void *data, const char *chunkname, const char *mode) [int]\nLoads a Lua chunk without running it. If there are no errors, `lua_load`\npushes the compiled chunk as a Lua function on top of the stack. Otherwise, it\npushes an error message.\n\nThe return values of `lua_load` are:\n * LUA_OK: no errors;\n * LUA_ERRSYNTAX: syntax error during pre-compilation;\n * LUA_ERRMEM: memory allocation error.\n * LUA_ERRGCMM: error while running a `__gc` metamethod. (This error has no\n relation with the chunk being loaded. It is generated by the garbage\n collector.)\n\nThe `lua_load` function uses a user-supplied `reader` function to read the chunk\n(see `lua_Reader`). The `data` argument is an opaque value passed to the reader\nfunction.\n\nThe `chunkname` argument gives a name to the chunk, which is used for error\nmessages and in debug information (see §4.9).\n\n`lua_load` automatically detects whether the chunk is text or binary and loads\nit accordingly (see program `luac`). The string `mode` works as in function\n`load`, with the addition that a `NULL` value is equivalent to the string\n"`bt`".\n\n`lua_load` uses the stack internally, so the reader function must always\nleave the stack unmodified when returning.\n\nIf the resulting function has upvalues, its first upvalue is set to the value of\nthe global environment stored at index `LUA_RIDX_GLOBALS` in the registry\n(see §4.5). When loading main chunks, this upvalue will be the `_ENV` variable\n(see §2.2). Other upvalues are initialized with `nil`.\n +lua_load lua_load(lua_State *L, lua_Reader reader, void *data, const char *chunkname, const char *mode) [int]\nLoads a Lua chunk without running it. If there are no errors, `lua_load`\npushes the compiled chunk as a Lua function on top of the stack. Otherwise, it\npushes an error message.\n\nThe return values of `lua_load` are:\n * LUA_OK: no errors;\n * LUA_ERRSYNTAX: syntax error during pre-compilation;\n * LUA_ERRMEM: memory allocation (out-of-memory) error.\n * LUA_ERRGCMM: error while running a `__gc` metamethod. (This error has no\n relation with the chunk being loaded. It is generated by the garbage\n collector.)\n\nThe `lua_load` function uses a user-supplied `reader` function to read the chunk\n(see `lua_Reader`). The `data` argument is an opaque value passed to the reader\nfunction.\n\nThe `chunkname` argument gives a name to the chunk, which is used for error\nmessages and in debug information (see §4.9).\n\n`lua_load` automatically detects whether the chunk is text or binary and loads\nit accordingly (see program `luac`). The string `mode` works as in function\n`load`, with the addition that a `NULL` value is equivalent to the string\n"`bt`".\n\n`lua_load` uses the stack internally, so the reader function must always\nleave the stack unmodified when returning.\n\nIf the resulting function has upvalues, its first upvalue is set to the value of\nthe global environment stored at index `LUA_RIDX_GLOBALS` in the registry\n(see §4.5). When loading main chunks, this upvalue will be the `_ENV` variable\n(see §2.2). Other upvalues are initialized with `nil`.\n lua_newstate lua_newstate(lua_Alloc f, void *ud) [lua_State*]\nCreates a new thread running in a new, independent state. Returns `NULL` if it\ncannot create the thread or the state (due to lack of memory). The argument `f`\nis the allocator function; Lua does all memory allocation for this state through\nthis function. The second argument, `ud`, is an opaque pointer that Lua passes\nto the allocator in every call.\n lua_newtable lua_newtable(lua_State *L) [void]\nCreates a new empty table and pushes it onto the stack. It is equivalent to\n`lua_createtable(L, 0, 0)`.\n lua_newthread lua_newthread(lua_State *L) [lua_State*]\nCreates a new thread, pushes it on the stack, and returns a pointer to a\n`lua_State` that represents this new thread. The new thread returned by this\nfunction shares with the original thread its global environment, but has an\nindependent execution stack.\n\nThere is no explicit function to close or to destroy a thread. Threads are\nsubject to garbage collection, like any Lua object.\n @@ -50,13 +50,13 @@ lua_newuserdata lua_newuserdata(lua_State *L, size_t size) [void*]\nThis functio lua_next lua_next(lua_State *L, int index) [int]\n\nPops a key from the stack, and pushes a key-value pair from the table at\nthe given index (the "next" pair after the given key). If there are no more\nelements in the table, then `lua_next` returns 0 (and pushes nothing).\n\nA typical traversal looks like this:\n\n /* table is in the stack at index 't' */\n lua_pushnil(L); /* first key */\n while (lua_next(L, t) != 0) {\n /* uses 'key' (at index -2) and 'value' (at index -1) */\n printf("%s - %s\n",\n lua_typename(L, lua_type(L, -2)),\n lua_typename(L, lua_type(L, -1)));\n /* removes 'value'; keeps 'key' for next iteration */\n lua_pop(L, 1);\n }\n\nWhile traversing a table, do not call `lua_tolstring` directly on a key, unless\nyou know that the key is actually a string. Recall that `lua_tolstring` may\nchange the value at the given index; this confuses the next call to `lua_next`.\n\nSee function `next` for the caveats of modifying the table during its traversal.\n lua_Number lua_Number [double]\nThe type of floats in Lua. By default this type is double, but that can be\nchanged to a single float. (See `LUA_REAL` in `luaconf.h`.)\n lua_numbertointeger lua_numbertointeger(lua_Number n, lua_Integer *p) [int]\nConverts a Lua float to a Lua integer. This macro assumes that `n` has an\nintegral value. If that value is within the range of Lua integers, it is\nconverted to an integer and assigned to `*p`. The macro results in a boolean\nindicating whether the conversion was successful. (Note that this range test\ncan be tricky to do correctly without this macro, due to roundings.)\n\nThis macro may evaluate its arguments more than once.\n -lua_pcall lua_pcall(lua_State *L, int nargs, int nresults, int msgh) [int]\nCalls a function in protected mode.\n\nBoth `nargs` and `nresults` have the same meaning as in `lua_call`. If there\nare no errors during the call, `lua_pcall` behaves exactly like `lua_call`.\nHowever, if there is any error,\n\n`lua_pcall` catches it, pushes a single value on the stack (the error message),\nand returns an error code. Like `lua_call`, `lua_pcall` always removes the\nfunction and its arguments from the stack.\n\nIf `msgh` is 0, then the error message returned on the stack is exactly the\noriginal error message. Otherwise, `msgh` is the stack index of a _message\nhandler_. (In the current implementation, this index cannot be a pseudo-index.)\nIn case of runtime errors, this function will be called with the error message\nand its return value will be the message returned on the stack by `lua_pcall`.\n\nTypically, the message handler is used to add more debug information to the\nerror message, such as a stack traceback. Such information cannot be gathered\nafter the return of `lua_pcall`, since by then the stack has unwound.\n\nThe `lua_pcall` function returns one of the following constants (defined in\n`lua.h`):\n * LUA_OK (0): success.\n * LUA_ERRRUN: a runtime error.\n * LUA_ERRMEM: memory allocation error. For such errors, Lua does not call the\n message handler.\n * LUA_ERRERR: error while running the message handler.\n * LUA_ERRGCMM: error while running a `__gc` metamethod. (This error typically\n has no relation with the function being called.)\n +lua_pcall lua_pcall(lua_State *L, int nargs, int nresults, int msgh) [int]\nCalls a function in protected mode.\n\nBoth `nargs` and `nresults` have the same meaning as in `lua_call`. If there\nare no errors during the call, `lua_pcall` behaves exactly like `lua_call`.\nHowever, if there is any error,\n\n`lua_pcall` catches it, pushes a single value on the stack (the error object),\nand returns an error code. Like `lua_call`, `lua_pcall` always removes the\nfunction and its arguments from the stack.\n\nIf `msgh` is 0, then the error object returned on the stack is exactly the\noriginal error object. Otherwise, `msgh` is the stack index of a _message\nhandler_. (In the current implementation, this index cannot be a pseudo-index.)\nIn case of runtime errors, this function will be called with the error object\nand its return value will be the object returned on the stack by `lua_pcall`.\n\nTypically, the message handler is used to add more debug information to the\nerror object, such as a stack traceback. Such information cannot be gathered\nafter the return of `lua_pcall`, since by then the stack has unwound.\n\nThe `lua_pcall` function returns one of the following constants (defined in\n`lua.h`):\n * LUA_OK (0): success.\n * LUA_ERRRUN: a runtime error.\n * LUA_ERRMEM: memory allocation error. For such errors, Lua does not call the\n message handler.\n * LUA_ERRERR: error while running the message handler.\n * LUA_ERRGCMM: error while running a `__gc` metamethod. (This error typically\n has no relation with the function being called.)\n lua_pcallk lua_pcallk(lua_State *L, int nargs, int nresults, int msgh, lua_KContext ctx, lua_KFunction k) [int]\nThis function behaves exactly like `lua_pcall`, but allows the called function\nto yield (see §4.7).\n lua_pop lua_pop(lua_State *L, int n) [void]\nPops `n` elements from the stack.\n lua_pushboolean lua_pushboolean(lua_State *L, int b) [void]\nPushes a boolean value with value `b` onto the stack.\n lua_pushcclosure lua_pushcclosure(lua_State *L, lua_CFunction fn, int n) [void]\nPushes a new C closure onto the stack.\n\nWhen a C function is created, it is possible to associate some values with it,\nthus creating a C closure (see §4.4); these values are then accessible to\nthe function whenever it is called. To associate values with a C function,\nfirst these values must be pushed onto the stack (when there are multiple\nvalues, the first value is pushed first). Then `lua_pushcclosure` is called to\ncreate and push the C function onto the stack, with the argument `n` telling\nhow many values will be associated with the function. `lua_pushcclosure`\nalso pops these values from the stack.\n\nThe maximum value for `n` is 255.\n\nWhen `n` is zero, this function creates a _light C function_, which is just a\npointer to the C function. In that case, it never raises a memory error.\n lua_pushcfunction lua_pushcfunction(lua_State *L, lua_CFunction f) [void]\nPushes a C function onto the stack. This function receives a pointer to a\nC function and pushes onto the stack a Lua value of type `function` that,\nwhen called, invokes the corresponding C function.\n\nAny function to be registered in Lua must follow the correct protocol to\nreceive its parameters and return its results (see `lua_CFunction`).\n\n`lua_pushcfunction` is defined as a macro:\n\n #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)\n -lua_pushfstring lua_pushfstring(lua_State *L, const char *fmt, ...) [const char*]\nPushes onto the stack a formatted string and returns a pointer to this string.\nIt is similar to the ISO C function `sprintf`, but has some important\ndifferences:\n * You do not have to allocate space for the result: the result is a\n Lua string and Lua takes care of memory allocation (and deallocation,\n through garbage collection).\n * The conversion specifiers are quite restricted. There are no flags,\n widths, or precisions. The conversion specifiers can only be '%%'\n (inserts the character '%' in the string), '%s' (inserts a zero-terminated\n string, with no size restrictions), '%f' (inserts a `lua_Number`), '%L'\n (inserts a `lua_Integer`), '%p' (inserts a pointer as a hexadecimal\n numeral), '%d' (inserts an `int`), '%c' (inserts an `int` as a one-byte\n character), and '%U' (inserts a `long int` as a UTF-8 byte sequence).\n +lua_pushfstring lua_pushfstring(lua_State *L, const char *fmt, ...) [const char*]\nPushes onto the stack a formatted string and returns a pointer to this string.\nIt is similar to the ISO C function `sprintf`, but has some important\ndifferences:\n * You do not have to allocate space for the result: the result is a\n Lua string and Lua takes care of memory allocation (and deallocation,\n through garbage collection).\n * The conversion specifiers are quite restricted. There are no flags,\n widths, or precisions. The conversion specifiers can only be '%%'\n (inserts the character '%' in the string), '%s' (inserts a zero-terminated\n string, with no size restrictions), '%f' (inserts a `lua_Number`), '%L'\n (inserts a `lua_Integer`), '%p' (inserts a pointer as a hexadecimal\n numeral), '%d' (inserts an `int`), '%c' (inserts an `int` as a one-byte\n character), and '%U' (inserts a `long int` as a UTF-8 byte sequence).\n \nUnlike other push functions, this function checks for the stack space it needs,\nincluding the slot for its result.\n lua_pushglobaltable lua_pushglobaltable(lua_State *L) [void]\nPushes the global environment onto the stack.\n lua_pushinteger lua_pushinteger(lua_State *L, lua_Integer n) [void]\nPushes an integer with value `n` onto the stack.\n lua_pushlightuserdata lua_pushlightuserdata(lua_State *L, void *p) [void]\nPushes a light userdata onto the stack.\n\nUserdata represent C values in Lua. A _light userdata_ represents a pointer, a\n`void*`. It is a value (like a number): you do not create it, it has no\nindividual metatable, and it is not collected (as it was never created). A\nlight userdata is equal to "any" light userdata with the same C address.\n @@ -68,19 +68,19 @@ lua_pushstring lua_pushstring(lua_State *L, const char *s) [const char*]\nPushes lua_pushthread lua_pushthread(lua_State *L) [int]\nPushes the thread represented by `L` onto the stack. Returns 1 if this\nthread is the main thread of its state.\n lua_pushvalue lua_pushvalue(lua_State *L, int index) [void]\nPushes a copy of the element at the given index onto the stack.\n lua_pushvfstring lua_pushvfstring(lua_State *L, const char *fmt, va_list argp) [const char*]\nEquivalent to `lua_pushfstring`, except that it receives a `va_list` instead\nof a variable number of arguments.\n -lua_rawequal lua_rawequal(lua_State *L, int index1, int index2) [int]\nReturns 1 if the two values in indices `index1` and `index2` are primitively\nequal (that is, without calling metamethods). Otherwise returns 0. Also\nreturns 0 if any of the indices are not valid.\n +lua_rawequal lua_rawequal(lua_State *L, int index1, int index2) [int]\nReturns 1 if the two values in indices `index1` and `index2` are primitively\nequal (that is, without calling the `__eq` metamethod). Otherwise returns 0.\nAlso returns 0 if any of the indices are not valid.\n lua_rawget lua_rawget(lua_State *L, int index) [int]\nSimilar to `lua_gettable`, but does a raw access (i.e., without metamethods).\n -lua_rawgeti lua_rawgeti(lua_State *L, int index, lua_Integer n) [int]\nPushes onto the stack the value `t[n]`, where `t` is the table at the given\nindex. The access is raw; that is, it does not invoke metamethods.\n\nReturns the type of the pushed value.\n -lua_rawgetp lua_rawgetp(lua_State *L, int index, const void *p) [int]\nPushes onto the stack the value `t[k]`, where `t` is the table at the given\nindex and `k` is the pointer `p` represented as a light userdata. The access\nis raw; that is, it does not invoke metamethods.\n\nReturns the type of the pushed value.\n +lua_rawgeti lua_rawgeti(lua_State *L, int index, lua_Integer n) [int]\nPushes onto the stack the value `t[n]`, where `t` is the table at the given\nindex. The access is raw, that is, it does not invoke the `__index` metamethod.\n\nReturns the type of the pushed value.\n +lua_rawgetp lua_rawgetp(lua_State *L, int index, const void *p) [int]\nPushes onto the stack the value `t[k]`, where `t` is the table at the given\nindex and `k` is the pointer `p` represented as a light userdata. The access\nis raw, that is, it does not invoke the `__index` metamethod.\n\nReturns the type of the pushed value.\n lua_rawlen lua_rawlen(lua_State *L, int index) [size_t]\nReturns the raw "length" of the value at the given index: for strings, this\nis the string length; for tables, this is the result of the length operator\n('`#`') with no metamethods; for userdata, this is the size of the block of\nmemory allocated for the userdata; for other values, it is 0.\n lua_rawset lua_rawset(lua_State *L, int index) [void]\nSimilar to `lua_settable`, but does a raw assignment (i.e., without\nmetamethods).\n -lua_rawseti lua_rawseti(lua_State *L, int index, lua_Integer i) [void]\nDoes the equivalent of `t[i] = v`, where `t` is the table at the given index\nand `v` is the value at the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw; that is, it\ndoes not invoke metamethods.\n -lua_rawsetp lua_rawsetp(lua_State *L, int index, const void *p) [void]\nDoes the equivalent of `t[k] = v`, where `t` is the table at the given index,\n`k` is the pointer `p` represented as a light userdata, and `v` is the value at\nthe top of the stack.\n\nThis function pops the value from the stack. The assignment is raw; that is, it\ndoes not invoke metamethods.\n +lua_rawseti lua_rawseti(lua_State *L, int index, lua_Integer i) [void]\nDoes the equivalent of `t[i] = v`, where `t` is the table at the given index\nand `v` is the value at the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it\ndoes not invoke the `__newindex` metamethod.\n +lua_rawsetp lua_rawsetp(lua_State *L, int index, const void *p) [void]\nDoes the equivalent of `t[k] = v`, where `t` is the table at the given index,\n`k` is the pointer `p` represented as a light userdata, and `v` is the value at\nthe top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it\ndoes not invoke the `__newindex` metamethod.\n lua_Reader (*lua_Reader)(lua_State *L, void *data, size_t *size) [const char*]\nThe reader function used by `lua_load`. Every time it needs another piece of\nthe chunk, `lua_load` calls the reader, passing along its `data` parameter.\nThe reader must return a pointer to a block of memory with a new piece of\nthe chunk and set `size` to the block size. The block must exist until the\nreader function is called again. To signal the end of the chunk, the reader\nmust return `NULL` or set `size` to zero. The reader function may return\npieces of any size greater than zero.\n lua_register lua_register(lua_State *L, const char *name, lua_CFunction f) [void]\nSets the C function `f` as the new value of global `name`. It is defined\nas a macro:\n\n #define lua_register(L,n,f) (lua_pushcfunction(L, f), lua_setglobal(L, n))\n lua_remove lua_remove(lua_State *L, int index) [void]\nRemoves the element at the given valid index, shifting down the elements\nabove this index to fill the gap. This function cannot be called with a\npseudo-index, because a pseudo-index is not an actual stack position.\n lua_replace lua_replace(lua_State *L, int index) [void]\nMoves the top element into the given valid index, without shifting any element\n(therefore replacing the value at the given index), and then pops the top\nelement.\n -lua_resume lua_resume(lua_State *L, lua_State *from, int nargs) [int]\nStarts and resumes a coroutine in a given thread.\n\nTo start a coroutine, you push onto the thread stack the main function plus any\narguments; then you call `lua_resume`, with `nargs` being the number of\narguments. This call returns when the coroutine suspends or finishes its\nexecution. When it returns, the stack contains all values passed to\n`lua_yield`, or all values returned by the body function. `lua_resume` returns\n`LUA_YIELD` if the coroutine yields, `LUA_OK` if the coroutine finishes its\nexecution without errors, or an error code in case of errors (see `lua_pcall`).\n\nIn case of errors, the stack is not unwound, so you can use the debug API over\nit. The error message is on the top of the stack.\n\nTo resume a coroutine, you remove any results from the last `lua_yield`, put on\nits stack only the values to be passed as results from `yield`, and then call\n`lua_resume`.\n\nThe parameter `from` represents the coroutine that is resuming `L`. If there\nis no such coroutine, this parameter can be `NULL`.\n +lua_resume lua_resume(lua_State *L, lua_State *from, int nargs) [int]\nStarts and resumes a coroutine in a given thread.\n\nTo start a coroutine, you push onto the thread stack the main function plus any\narguments; then you call `lua_resume`, with `nargs` being the number of\narguments. This call returns when the coroutine suspends or finishes its\nexecution. When it returns, the stack contains all values passed to\n`lua_yield`, or all values returned by the body function. `lua_resume` returns\n`LUA_YIELD` if the coroutine yields, `LUA_OK` if the coroutine finishes its\nexecution without errors, or an error code in case of errors (see `lua_pcall`).\n\nIn case of errors, the stack is not unwound, so you can use the debug API over\nit. The error object is on the top of the stack.\n\nTo resume a coroutine, you remove any results from the last `lua_yield`, put on\nits stack only the values to be passed as results from `yield`, and then call\n`lua_resume`.\n\nThe parameter `from` represents the coroutine that is resuming `L`. If there\nis no such coroutine, this parameter can be `NULL`.\n lua_rotate lua_rotate(lua_State *L, int index, int n) [void]\nRotates the stack elements from `index` to the top `n` positions in the\ndirection of the top, for a positive `n`, or `-n` positions in the direction of\nthe bottom, for a negative `n`. The absolute value of `n` must not be greater\nthan the size of the slice being rotated.\n lua_setallocf lua_setallocf(lua_State *L, lua_Alloc f, void *ud) [void]\nChanges the allocator function of a given state to `f` with user data `ud`.\n lua_setfield lua_setfield(lua_State *L, int index, const char *k) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given index\nand `v` is the value at the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may\ntrigger a metamethod for the "newindex" event (see §2.4).\n @@ -108,11 +108,11 @@ lua_type lua_type(lua_State *L, int index) [int]\nReturns the type of the value lua_typename lua_typename(lua_State *L, int tp) [const char*]\nReturns the name of the type encoded by the value `tp`, which must be one\nthe values returned by `lua_type`.\n lua_Unsigned lua_Unsigned [typedef ... lua_Unsigned]\nThe unsigned version of `lua_Integer`.\n lua_upvalueindex lua_upvalueindex(lua_State *L, int i) [int]\nReturns the pseudo-index that represents the `i`-th upvalue of the running\nfunction (see §4.4).\n -lua_version lua_version(lua_State *L) [const lua_Number]\nReturns the address of the version number stored in the Lua core. When called\nwith a valid `lua_State`, returns the address of the version used to create that\nstate. When called with `NULL`, returns the address of the version running the\ncall.\n +lua_version lua_version(lua_State *L) [const lua_Number]\nReturns the address of the version number (a C static variable) stored in the\nLua core. When called with a valid `lua_State`, returns the address of the\nversion used to create that state. When called with `NULL`, returns the address\nof the version running the call.\n lua_Writer (*lua_Writer)(lua_State *L, const void* p, size_t sz, void* ud) [int]\nThe type of the writer function used by `lua_dump`. Every time it produces\nanother piece of chunk, `lua_dump` calls the writer, passing along the buffer\nto be written (`p`), its size (`sz`), and the `data` parameter supplied to\n`lua_dump`.\n\nThe writer returns an error code: 0 means no errors; any other value means\nan error and stops `lua_dump` from calling the writer again.\n lua_xmove lua_xmove(lua_State *from, lua_State *to, int n) [void]\nExchange values between different threads of the same state.\n\nThis function pops `n` values from the stack `from`, and pushes them onto\nthe stack `to`.\n lua_yield lua_yield(lua_State *L, int nresults) [int]\nThis function is equivalent to `lua_yieldk`, but it has no continuation\n(see §4.7). Therefore, when the thread resumes, it continues the function that\ncalled the function calling `lua_yield`.\n -lua_yieldk lua_yieldk(lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k) [int]\nYields a coroutine (thread).\n\nWhen a C function calls `lua_yieldk`, the running coroutine suspends its\nexecution, and the call to `lua_resume` that started this coroutine returns.\nThe parameter `nresults` is the number of values from the stack that will be\npassed as results to `lua_resume`.\n\nWhen the coroutine is resumed again, Lua calls the given continuation function\n`k` to continue the execution of the C function that yielded (see §4.7). This\ncontinuation function receives the same stack from the previous function, with\nthe `n` results removed and replaced by the arguments passed to `lua_resume`.\nMoreover, the continuation function receives the value `ctx` that was passed to `lua_yield`.\n\nUsually, this function does not return; when the coroutine eventually resumes,\nit continues executing the continuation function. However, there is one special\ncase, which is when this function is called from inside a line hook (see §4.9).\nIn that case, `lua_yieldk` should be called with no continuation (probably in\nthe form of `lua_yield`), and the hook should return immediately after the call.\nLua will yield and, when the coroutine resumes again, it will continue the\nnormal execution of the (Lua) function that triggered the hook.\n\nThis function can raise an error if it is called from a thread with a pending C\ncall with no continuation function, or it is called from a thread that is not\nrunning inside a resume (e.g., the main thread).\n +lua_yieldk lua_yieldk(lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k) [int]\nYields a coroutine (thread).\n\nWhen a C function calls `lua_yieldk`, the running coroutine suspends its\nexecution, and the call to `lua_resume` that started this coroutine returns.\nThe parameter `nresults` is the number of values from the stack that will be\npassed as results to `lua_resume`.\n\nWhen the coroutine is resumed again, Lua calls the given continuation function\n`k` to continue the execution of the C function that yielded (see §4.7). This\ncontinuation function receives the same stack from the previous function, with\nthe `n` results removed and replaced by the arguments passed to `lua_resume`.\nMoreover, the continuation function receives the value `ctx` that was passed to\n`lua_yield`.\n\nUsually, this function does not return; when the coroutine eventually resumes,\nit continues executing the continuation function. However, there is one special\ncase, which is when this function is called from inside a line or a count hook\n(see §4.9). In that case, `lua_yieldk` should be called with no continuation\n(probably in the form of `lua_yield` and no results), and the hook should return\nimmediately after the call. Lua will yield and, when the coroutine resumes\nagain, it will continue the normal execution of the (Lua) function that\ntriggered the hook.\n\nThis function can raise an error if it is called from a thread with a pending C\ncall with no continuation function, or it is called from a thread that is not\nrunning inside a resume (e.g., the main thread).\n lua_Debug lua_Debug [struct]\ntypedef struct lua_Debug {\n int event;\n const char *name; /* (n) */\n const char *namewhat; /* (n) */\n const char *what; /* (S) */\n const char *source; /* (S) */\n int currentline; /* (l) */\n int linedefined; /* (S) */\n int lastlinedefined; /* (S) */\n unsigned char nups; /* (u) number of upvalues */\n unsigned char nparams; /* (u) number of parameters */\n char isvararg; /* (u) */\n char istailcall; /* (t) */\n char short_src[LUA_IDSIZE]; /* (S) */\n /* private part */\n _other fields_\n} lua_Debug;\n\nA structure used to carry different pieces of information about a function or an\nactivation record. `lua_getstack` fills only the private part of this\nstructure, for later use. To fill the other fields of `lua_Debug` with useful\ninformation, call `lua_getinfo`.\n\nThe fields of `lua_Debug` have the following meaning:\n * source: the name of the chunk that created the function. If `source`\n starts with a '`@`', it means that the function was defined in a file where\n the file name follows the '`@`'. If `source` starts with a '`=`', the\n remainder of its contents describe the source in a user-dependent manner.\n Otherwise, the function was defined in a string where `source` is that\n string.\n * short_src: a "printable" version of `source`, to be used in error messages.\n * linedefined: the line number where the definition of the function starts.\n * lastlinedefined: the line number where the definition of the function ends.\n * what: the string "Lua" if the function is a Lua function, "C" if it is a\n C function, "main" if it is the main part of a chunk.\n * currentline: the current line where the given function is executing.\n When no line information is available, `currentline` is set to -1.\n * name: a reasonable name for the given function. Because functions in Lua\n are first-class values, they do not have a fixed name: some functions\n can be the value of multiple global variables, while others can be\n stored only in a table field. The `lua_getinfo` function checks how the\n function was called to find a suitable name. If it cannot find a name,\n then `name` is set to `NULL`.\n * namewhat: explains the `name` field. The value of `namewhat` can be\n "global", "local", "method", "field", "upvalue", or "" (the empty string),\n according to how the function was called. (Lua uses the empty string\n when no other option seems to apply.)\n * istailcall: true if this function invocation was called by a tail call. In\n this case, the caller of this level is not in the stack.\n * nups: the number of upvalues of the function.\n * nparams: the number of fixed parameters of the function (always 0 for C\n functions).\n * isvararg: true if the function is a vararg function (always true for C\n functions).\n lua_gethook lua_gethook(lua_State *L) [lua_Hook]\nReturns the current hook function.\n lua_gethookcount lua_gethookcount(lua_State *L) [int]\nReturns the current hook count.\n @@ -122,7 +122,7 @@ lua_getlocal lua_getlocal(lua_State *L, const lua_Debug *ar, int n) [const char* lua_getstack lua_getstack(lua_State *L, int level, lua_Debug *ar) [int]\nGets information about the interpreter runtime stack.\n\nThis function fills parts of a `lua_Debug` structure with an identification of\nthe _activation record_ of the function executing at a given level. Level 0\nis the current running function, whereas level _n+1_ is the function that\nhas called level _n_ (except for tail calls, which do not count on the stack).\nWhen there are no errors, `lua_getstack` returns 1; when called with a level\ngreater than the stack depth, it returns 0.\n lua_getupvalue lua_getupvalue(lua_State *L, int funcindex, int n) [const char*]\nGets information about a closure's upvalue. (For Lua functions, upvalues are\nthe external local variables that the function uses, and that are consequently\nincluded in its closure.) `lua_getupvalue` gets the index `n` of an upvalue,\npushes the upvalue's value onto the stack, and returns its name.`funcindex`\npoints to the closure in the stack. (Upvalues have no particular order,\nas they are active through the whole function. So, they are numbered in an\narbitrary order.)\n\nReturns `NULL` (and pushes nothing) when the index is greater than the\nnumber of upvalues. For C functions, this function uses the empty string\n"" as a name for all upvalues.\n lua_Hook (*lua_Hook)(lua_State *L, lua_Debug *ar) [void]\nType for debugging hook functions.\n\nWhenever a hook is called, its `ar` argument has its field `event` set to the\nspecific event that triggered the hook. Lua identifies these events with\nthe following constants: `LUA_HOOKCALL`, `LUA_HOOKRET`, `LUA_HOOKTAILCALL`,\n`LUA_HOOKLINE`, and `LUA_HOOKCOUNT`. Moreover, for line events, the\nfield `currentline` is also set. To get the value of any other field in\n`ar`, the hook must call `lua_getinfo`.\n\nFor call events, `event` can be `LUA_HOOKCALL`, the normal value, or\n`LUA_HOOKTAILCALL`, for a tail call; in this case, there will be no\ncorresponding return event.\n\nWhile Lua is running a hook, it disables other calls to hooks. Therefore,\nif a hook calls back Lua to execute a function or a chunk, this execution\noccurs without any calls to hooks.\n\nHook functions cannot have continuations, that is, they cannot call\n`lua_yieldk`, `lua_pcallk`, or `lua_callk` with a non-null `k`.\n\nHook functions can yield under the following conditions: Only count and line\nevents can yield and they cannot yield any value; to yield a hook function must\nfinish its execution calling `lua_yield` with `nresults` equal to zero.\n -lua_sethook lua_sethook(lua_State *L, lua_Hook f, int mask, int count) [void]\nSets the debugging hook function.\n\nArgument `f` is the hook function.\n\n`mask` specifies on which events the hook will be called: it is formed by a\nbitwise or of the constants `LUA_MASKCALL`, `LUA_MASKRET`, `LUA_MASKLINE`,\nand `LUA_MASKCOUNT`. The `count` argument is only meaningful when the mask\nincludes `LUA_MASKCOUNT`. For each event, the hook is called as explained\nbelow:\n * The call hook: is called when the interpreter calls a function. The hook is\n called just after Lua enters the new function, before the function gets\n its arguments.\n * The return hook: is called when the interpreter returns from a function.\n The hook is called just before Lua leaves the function. There is no\n standard way to access the values to be returned by the function.\n * The line hook: is called when the interpreter is about to start the\n execution of a new line of code, or when it jumps back in the code (even\n to the same line). (This event only happens while Lua is executing a\n Lua function.)\n * The count hook: is called after the interpreter executes every `count`\n instructions. (This event only happens while Lua is executing a Lua\n function.)\n\nA hook is disabled by setting `mask` to zero.\n +lua_sethook lua_sethook(lua_State *L, lua_Hook f, int mask, int count) [void]\nSets the debugging hook function.\n\nArgument `f` is the hook function.\n\n`mask` specifies on which events the hook will be called: it is formed by a\nbitwise OR of the constants `LUA_MASKCALL`, `LUA_MASKRET`, `LUA_MASKLINE`,\nand `LUA_MASKCOUNT`. The `count` argument is only meaningful when the mask\nincludes `LUA_MASKCOUNT`. For each event, the hook is called as explained\nbelow:\n * The call hook: is called when the interpreter calls a function. The hook is\n called just after Lua enters the new function, before the function gets\n its arguments.\n * The return hook: is called when the interpreter returns from a function.\n The hook is called just before Lua leaves the function. There is no\n standard way to access the values to be returned by the function.\n * The line hook: is called when the interpreter is about to start the\n execution of a new line of code, or when it jumps back in the code (even\n to the same line). (This event only happens while Lua is executing a\n Lua function.)\n * The count hook: is called after the interpreter executes every `count`\n instructions. (This event only happens while Lua is executing a Lua\n function.)\n\nA hook is disabled by setting `mask` to zero.\n lua_setlocal lua_setlocal(lua_State *L, const lua_Debug *ar, int n) [const char*]\nSets the value of a local variable of a given activation record. Parameters\n`ar` and `n` are as in `lua_getlocal` (see `lua_getlocal`). `lua_setlocal`\nassigns the value at the top of the stack to the variable and returns its name.\nIt also pops the value from the stack.\n\nReturns `NULL` (and pops nothing) when the index is greater than the number\nof active local variables.\n lua_setupvalue lua_setupvalue(lua_State *L, int funcindex, int n) [const char*]\nSets the value of a closure's upvalue. It assigns the value at the top of\nthe stack to the upvalue and returns its name. It also pops the value from\nthe stack. Parameters `funcindex` and `n` are as in the `lua_getupvalue`\n(see `lua_getupvalue`).\n\nReturns `NULL` (and pops nothing) when the index is greater than the number\nof upvalues.\n lua_upvalueid lua_upvalueid(lua_State *L, int funcindex, int n) [void*]\nReturns a unique identifier for the upvalue numbered `n` from the closure at\nindex `funcindex`. Parameters `funcindex` and `n` are as in the\n`lua_getupvalue` (see `lua_getupvalue`) (but `n` cannot be greater than the\nnumber of upvalues).\n\nThese unique identifiers allow a program to check whether different closures\nshare upvalues. Lua closures that share an upvalue (that is, that access a same\nexternal local variable) will return identical ids for those upvalue indices.\n @@ -168,6 +168,7 @@ luaL_newlibtable luaL_newlibtable(lua_State *L, const luaL_Reg l[]) [void]\nCrea luaL_newmetatable luaL_newmetatable(lua_State *L, const char *tname) [int]\nIf the registry already has the key `tname`, returns 0. Otherwise, creates a\nnew table to be used as a metatable for userdata, adds to this new table the\npair `__name = tname`, adds to the registry the pair `[tname] = new table`, and\nreturns 1. (The entry `__name` is used by some error-reporting functions.)\n\nIn both cases pushes onto the stack the final value associated with `tname`\nin the registry.\n luaL_newstate luaL_newstate(void) [lua_State*]\nCreates a new Lua state. It calls `lua_newstate` with an allocator based\non the standard C `realloc` function and then sets a panic function (see\n`lua_atpanic`) that prints an error message to the standard error output in\ncase of fatal errors.\n\nReturns the new state, or `NULL` if there is a memory allocation error.\n luaL_openlibs luaL_openlibs(lua_State *L) [void]\nOpens all standard Lua libraries into the given state.\n +luaL_opt luaL_opt(L, func, arg, dflt);\nThis macro is defined as follows:\n (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))\nIn words, if the argument `arg` is nil or absent, the macro results in the\ndefault `dflt`. Otherwise, it results in the result of calling `func` with the\nstate `L` and the argument index `arg` as parameters. Note that it evaluates the\nexpression `dflt` only if needed. \n luaL_optinteger luaL_optinteger(lua_State *L, int arg, lua_Integer d) [lua_Integer]\nIf the function argument `arg` is an integer (or convertable to an integer),\nreturns this integer. If this argument is absent or is nil, returns `d`.\nOtherwise, raises an error.\n luaL_optlstring luaL_optlstring(lua_State *L, int arg, const char *d, size_t *l) [const char*]\nIf the function argument `arg` is a string, returns this string. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n\nIf `l` is not `NULL`, fills the position `*l` with the result's length. If the\nresult is `NULL` (only possible when returning `d` and `d == NULL`), its length\nis considered zero.\n luaL_optnumber luaL_optnumber(lua_State *L, int arg, lua_Number d) [lua_Number]\nIf the function argument `arg` is a number, returns this number. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n @@ -183,7 +184,7 @@ luaL_setfuncs luaL_setfuncs(lua_State *L, const luaL_Reg *l, int nup) [void]\nRe luaL_setmetatable luaL_setmetatable(lua_State *L, const char *tname) [void]\nSets the metatable of the object at the top of the stack as the metatable\nassociated with name `tname` in the registry (see `luaL_newmetatable`).\n luaL_Stream luaL_Stream [typedef struct luaL_Stream {FILE *f; lua_CFunction closef;}]\nThe standard representation for file handles, which is used by the standard I/O\nlibrary.\n\nA file handle is implemented as a full userdata, with a metatable called\n`LUA_FILEHANDLE` (where `LUA_FILEHANDLE` is a macro with the actual metatable's\nname). The metatable is created by the I/O library (see `luaL_newmetatable`).\n\nThis userdata must start with the structure `luaL_Stream`; it can contain other\ndata after this initial structure. Field `f` points to the corresponding C\nstream (or it can be `NULL` to indicate an incompletely created handle). Field\n`closef` points to a Lua function that will be called to close the stream when\nthe handle is closed or collected; this function receives the file handle as its\nsole argument and must return either **true** (in case of success) or **nil**\nplus an error message (in case of error). Once Lua calls this field, it changes\nthe field value to `NULL` to signal that the handle is closed.\n luaL_testudata luaL_testudata(lua_State *L, int arg, const char *tname) [void]\nThis function works like `luaL_checkudata`, except that, when the test fails,\nit returns `NULL` instead of raising an error.\n -luaL_tolstring luaL_tolstring(lua_State *L, int idx, size_t *len) [const char*]\nConverts any Lua value at the given index to a C string in a reasonable format.\nThe resulting string is pushed onto the stack and also returned by the function.\nIf `len` is not `NULL`, the function also sets `*len` with the string length.\n\nIf the value has a metatable with a `"__tostring"` field, then `luaL_tolstring`\ncalls the corresponding metamethod with the value as argument, and uses the\nresult of the call as its result.\n +luaL_tolstring luaL_tolstring(lua_State *L, int idx, size_t *len) [const char*]\nConverts any Lua value at the given index to a C string in a reasonable format.\nThe resulting string is pushed onto the stack and also returned by the function.\nIf `len` is not `NULL`, the function also sets `*len` with the string length.\n\nIf the value has a metatable with a `__tostring` field, then `luaL_tolstring`\ncalls the corresponding metamethod with the value as argument, and uses the\nresult of the call as its result.\n luaL_traceback luaL_traceback(lua_State *L, lua_State *L1, const char *msg, int level) [void]\nCreates and pushes a traceback of the stack `L1`. If `msg` is not `NULL` it is\nappended at the beginning of the traceback. The `level` parameter tells at\nwhich level to start the traceback.\n luaL_typename luaL_typename(lua_State *L, int index) [const char*]\nReturns the name of the type of the value at the given index.\n luaL_unref luaL_unref(lua_State *L, int t, int ref) [void]\nReleases reference `ref` from the table at index `t` (see `luaL_ref`).\nThe entry is removed from the table, so that the referred object can be\ncollected. The reference `ref` is also freed to be used again.\n\nIf `ref` is `LUA_NOREF` or `LUA_REFNIL`, `luaL_unref` does nothing.\n |