diff options
| -rw-r--r-- | modules/cpp/lua_api | 62 | ||||
| -rw-r--r-- | modules/lua/lua.luadoc | 15 |
2 files changed, 39 insertions, 38 deletions
diff --git a/modules/cpp/lua_api b/modules/cpp/lua_api index 719846a5..3bdc24de 100644 --- a/modules/cpp/lua_api +++ b/modules/cpp/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;\n`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 should behave like `free` and return `NULL`.\n\nWhen `nsize` is not zero, the allocator should 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) [int]\nPerforms an arithmetic operation over the two values (or one, in the case of\nnegation) at the top of the stack, with the value at the top being the second\noperand, 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 division (`/`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\n +lua_arith lua_arith(lua_State *L, int op) [void]\nPerforms an arithmetic operation over the two values (or one, in the case of\nnegation) at the top of the stack, with the value at the top being the second\noperand, 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 division (`/`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\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. The function results are pushed onto the stack in direct order\n(the first result is pushed first), so that after the call the last result is on\nthe 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_pushstring(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, int ctx, lua_CFunction k) [void]\nThis function behaves exactly like `lua_call`, but allows the called function to\nyield (see §4.7).\n @@ -73,7 +73,7 @@ lua_Reader (*lua_Reader)(lua_State *L, void *data, size_t *size) [const char*]\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. Cannot be called with a pseudo-index,\nbecause 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 position, without shifting any element\n(therefore replacing the value at the given position), and then pops the top\nelement.\n -lua_resume lua_resume(lua_State *L, lua_State *from, int narg) [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 `narg` 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 put on its stack only the values to be passed as\nresults from `yield`, and then call `lua_resume`.\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 put on its stack only the values to be passed as\nresults from `yield`, and then call `lua_resume`.\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 valid\nindex and `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 lua_setglobal lua_setglobal(lua_State *L, const char *name) [void]\nPops a value from the stack and sets it as the new value of global `name`.\n @@ -81,7 +81,7 @@ lua_setmetatable lua_setmetatable(lua_State *L, int index) [void]\nPops a table lua_settable lua_settable(lua_State *L, int index) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given\nvalid index,\n\n`v` is the value at the top of the stack, and `k` is the value just below\nthe top.\n\nThis function pops both the key and the value from the stack. As in Lua,\nthis function may trigger a metamethod for the "newindex" event (see §2.4).\n lua_settop lua_settop(lua_State *L, int index) [void]\nAccepts any acceptable index, or 0, and sets the stack top to this index.\nIf the new top is larger than the old one, then the new elements are filled\nwith <b>nil</b>. If `index` is 0, then all stack elements are removed.\n lua_setuservalue lua_setuservalue(lua_State *L, int index) [void]\nPops a table or nil from the stack and sets it as the new value associated to\nthe userdata at the given index.\n -lua_State lua_State [struct lua_State]\nAn opaque structure that keeps the whole state of a Lua interpreter. The Lua\nlibrary is fully reentrant: it has no global variables. All information\nabout a state is kept in this structure.\n\nA pointer to this state must be passed as the first argument to every\nfunction in the library, except to `lua_newstate`, which creates a Lua state\nfrom scratch.\n +lua_State lua_State [struct lua_State]\nAn opaque structure that points to a thread and indirectly (through the thread)\nto the whole state of a Lua interpreter. The Lua library is fully reentrant: it\nhas no global variables. All information about a state is accessible through\nthis structure.\n\nA pointer to this structure must be passed as the first argument to every\nfunction in the library, except to `lua_newstate`, which creates a Lua state\nfrom scratch.\n lua_status lua_status(lua_State *L) [int]\nReturns the status of the thread `L`.\n\nThe status can be 0 (`LUA_OK`) for a normal thread, an error code if the thread\nfinished the execution of a `lua_resume` with an error, or `LUA_YIELD` if the\nthread is suspended.\n\nYou can only call functions in threads with status `LUA_OK`. You can resume\nthreads with status `LUA_OK` (to start a new coroutine) or `LUA_YIELD` (to\nresume a coroutine).\n lua_toboolean lua_toboolean(lua_State *L, int index) [int]\nConverts the Lua value at the given acceptable index to a C boolean value\n(0 or 1). Like all tests in Lua, `lua_toboolean` returns true for any Lua value\ndifferent from false and nil; otherwise it returns false. It also returns false\nwhen called with a non-valid index. (If you want to accept only actual boolean\nvalues, use `lua_isboolean` to test the value's type.)\n lua_tocfunction lua_tocfunction(lua_State *L, int index) [lua_CFunction]\nConverts a value at the given acceptable index to a C function. That value\nmust be a C function; otherwise, returns `NULL`.\n @@ -108,39 +108,39 @@ lua_Debug lua_Debug [struct]\ntypedef struct lua_Debug {\n int event;\n const 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 lua_gethookmask lua_gethookmask(lua_State *L) [int]\nReturns the current hook mask.\n -lua_getinfo lua_getinfo(lua_State *L, const char *what, lua_Debug *ar) [int]\nReturns information about a specific function or function invocation.\n\nTo get information about a function invocation, the parameter `ar` must be a\nvalid activation record that was filled by a previous call to `lua_getstack`\nor given as argument to a hook (see `lua_Hook`).\n\nTo get information about a function you push it onto the stack and start the\n`what` string with the character '>'. (In that case, `lua_getinfo` pops the\nfunction from the top of the stack.) For instance, to know in which line a\nfunction `f` was defined, you can write the following code:\n\n lua_Debug ar;\n lua_getglobal(L, "f"); /* get global 'f' */\n lua_getinfo(L, ">S", &ar);\n printf("%d\n", ar.linedefined);\n\nEach character in the string `what` selects some fields of the structure\n`ar` to be filled or a value to be pushed on the stack:\n * 'n': fills in the field `name` and `namewhat`;\n * 'S': fills in the fields `source`, `short_src`, `linedefined`,\n `lastlinedefined`, and `what`;\n * 'l': fills in the field `currentline`;\n * 't': fills in the field `istailcall`;\n * 'u': fills in the fields `nups`, `nparams`, and `isvararg`;\n * 'f': pushes onto the stack the function that is running at the given level;\n * 'L': pushes onto the stack a table whose indices are the numbers of the\n lines that are valid on the function. (A _valid line_ is a line with\n some associated code, that is, a line where you can put a break point.\n Non-valid lines include empty lines and comments.)\n\nThis function returns 0 on error (for instance, an invalid option in `what`).\n +lua_getinfo lua_getinfo(lua_State *L, const char *what, lua_Debug *ar) [int]\nGets information about a specific function or function invocation.\n\nTo get information about a function invocation, the parameter `ar` must be a\nvalid activation record that was filled by a previous call to `lua_getstack`\nor given as argument to a hook (see `lua_Hook`).\n\nTo get information about a function you push it onto the stack and start the\n`what` string with the character '>'. (In that case, `lua_getinfo` pops the\nfunction from the top of the stack.) For instance, to know in which line a\nfunction `f` was defined, you can write the following code:\n\n lua_Debug ar;\n lua_getglobal(L, "f"); /* get global 'f' */\n lua_getinfo(L, ">S", &ar);\n printf("%d\n", ar.linedefined);\n\nEach character in the string `what` selects some fields of the structure\n`ar` to be filled or a value to be pushed on the stack:\n * 'n': fills in the field `name` and `namewhat`;\n * 'S': fills in the fields `source`, `short_src`, `linedefined`,\n `lastlinedefined`, and `what`;\n * 'l': fills in the field `currentline`;\n * 't': fills in the field `istailcall`;\n * 'u': fills in the fields `nups`, `nparams`, and `isvararg`;\n * 'f': pushes onto the stack the function that is running at the given level;\n * 'L': pushes onto the stack a table whose indices are the numbers of the\n lines that are valid on the function. (A _valid line_ is a line with\n some associated code, that is, a line where you can put a break point.\n Non-valid lines include empty lines and comments.)\n\nThis function returns 0 on error (for instance, an invalid option in `what`).\n lua_getlocal lua_getlocal(lua_State *L, lua_Debug *ar, int n) [const char*]\nGets information about a local variable of a given activation record or a given\nfunction.\n\nIn the first case, the parameter `ar` must be a valid activation record that was\nfilled by a previous call to `lua_getstack` or given as argument to a hook (see\n`lua_Hook`). The index `n` selects which local variable to inspect; see\n`debug.getlocal` for details about variable indices and names.\n\n`lua_getlocal` pushes the variable's value onto the stack and returns its name.\n\nIn the second case, `ar` should be `NULL` and the function to be inspected must\nbe at the top of the stack. In this case, only parameters of Lua functions are\nvisible (as there is no information about what variables are active) and no\nvalues are pushed onto the stack.\n\nReturns `NULL` (and pushes nothing) when the index is greater than the number of\nactive local variables.\n -lua_getstack lua_getstack(lua_State *L, int level, lua_Debug *ar) [int]\nGet 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_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 +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) [int]\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, 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 an unique identifier for the upvalue numbered `n` from the closure at\nindex `fidx`. Parameters `funcindex` and `n` are as in the `lua_getupvalue`\n(see `lua_getupvalue`) (but `n` cannot be greater than the number 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 -lua_upvaluejoin lua_upvaluejoin(lua_State *L, int fidx1, int n1, int fidx2, int n2) [void]\nMake the `n1`-th upvalue of the Lua closure at index `fidx1` refer to the\n`n2`-th upvalue of the Lua closure at index `fidx2`.\n +lua_upvalueid lua_upvalueid(lua_State *L, int funcindex, int n) [void*]\nReturns an 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 +lua_upvaluejoin lua_upvaluejoin(lua_State *L, int funcindex1, int n1, int funcindex2, int n2) [void]\nMake the `n1`-th upvalue of the Lua closure at index `funcindex1` refer to the\n`n2`-th upvalue of the Lua closure at index `funcindex2`.\n luaL_addchar luaL_addchar(luaL_Buffer *B, char c) [void]\nAdds the byte `c` to the buffer `B` (see `luaL_Buffer`).\n luaL_addlstring luaL_addlstring(luaL_Buffer *B, const char *s, size_t l) [void]\nAdds the string pointed to by `s` with length `l` to the buffer `B` (see\n`luaL_Buffer`). The string can contain embedded zeros.\n luaL_addsize luaL_addsize(luaL_Buffer *B, size_t n) [void]\nAdds to the buffer `B` (see `luaL_Buffer`) a string of length `n` previously\ncopied to the buffer area (see `luaL_prepbuffer`).\n luaL_addstring luaL_addstring(luaL_Buffer *B, const char *s) [void]\nAdds the zero-terminated string pointed to by `s` to the buffer `B` (see\n`luaL_Buffer`). The string cannot contain embedded zeros.\n luaL_addvalue luaL_addvalue(luaL_Buffer *B) [void]\nAdds the value at the top of the stack to the buffer `B` (see `luaL_Buffer`).\nPops the value.\n\nThis is the only function on string buffers that can (and must) be called with\nan extra element on the stack, which is the value to be added to the buffer.\n -luaL_argcheck luaL_argcheck(lua_State *L, int cond, int narg, const char *extramsg) [void]\nChecks whether `cond` is true. If not, raises an error with a standard message.\n -luaL_argerror luaL_argerror(lua_State *L, int narg, const char *extramsg) [int]\nRaises an error with a standard message that includes `extramsg` as a comment.\n\nThis function never returns, but it is an idiom to use it in C functions as\n`return luaL_argerror(args)`.\n -luaL_Buffer luaL_Buffer [struct]\nType for a _string buffer_.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern\nof use is as follows:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it with a call `luaL_buffinit(L, &b)`.\n * Then add string pieces to the buffer calling any of the `luaL_add*`\n functions.\n * Finish by calling `luaL_pushresult(&b)`. This call leaves the final string\n on the top of the stack.\n\nIf you know beforehand the total size of the resulting string, you can use the\nbuffer like this:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it and preallocate a space of size `sz` with a call\n `luaL_buffinitsize(L, &b, sz)`.\n * Then copy the string into that space.\n * Finish by calling `luaL_pushresult(&b, sz)`, where `sz` is the total size of\n the resulting string copied into that space.\n\nDuring its normal operation, a string buffer uses a variable number of\nstack slots. So, while using a buffer, you cannot assume that you know\nwhere the top of the stack is. You can use the stack between successive\ncalls to buffer operations as long as that use is balanced; that is, when you\ncall a buffer operation, the stack is at the same level it was immediately\nafter the previous buffer operation. (The only exception to this rule is\n`luaL_addvalue`.) After calling `luaL_pushresult` the stack is back to its\nlevel when the buffer was initialized, plus the final string on its top.\n +luaL_argcheck luaL_argcheck(lua_State *L, int cond, int arg, const char *extramsg) [void]\nChecks whether `cond` is true. If not, raises an error with a standard message.\n +luaL_argerror luaL_argerror(lua_State *L, int arg, const char *extramsg) [int]\nRaises an error with a standard message that includes `extramsg` as a comment.\n\nThis function never returns, but it is an idiom to use it in C functions as\n`return luaL_argerror(args)`.\n +luaL_Buffer luaL_Buffer [struct]\nType for a _string buffer_.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern\nof use is as follows:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it with a call `luaL_buffinit(L, &b)`.\n * Then add string pieces to the buffer calling any of the `luaL_add*`\n functions.\n * Finish by calling `luaL_pushresult(&b)`. This call leaves the final string\n on the top of the stack.\n\nIf you know beforehand the total size of the resulting string, you can use the\nbuffer like this:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it and preallocate a space of size `sz` with a call\n `luaL_buffinitsize(L, &b, sz)`.\n * Then copy the string into that space.\n * Finish by calling `luaL_pushresultsize(&b, sz)`, where `sz` is the total\n size of the resulting string copied into that space.\n\nDuring its normal operation, a string buffer uses a variable number of\nstack slots. So, while using a buffer, you cannot assume that you know\nwhere the top of the stack is. You can use the stack between successive\ncalls to buffer operations as long as that use is balanced; that is, when you\ncall a buffer operation, the stack is at the same level it was immediately\nafter the previous buffer operation. (The only exception to this rule is\n`luaL_addvalue`.) After calling `luaL_pushresult` the stack is back to its\nlevel when the buffer was initialized, plus the final string on its top.\n luaL_buffinit luaL_buffinit(lua_State *L, luaL_Buffer *B) [void]\nInitializes a buffer `B`. This function does not allocate any space; the\nbuffer must be declared as a variable (see `luaL_Buffer`).\n luaL_buffinitsize luaL_buffinitsize(lua_State *L, luaL_Buffer *B, size_t sz) [char*]\nEquivalent to the sequence `luaL_buffinit`, `luaL_prepbuffsize`.\n luaL_callmeta luaL_callmeta(lua_State *L, int obj, const char *e) [int]\nCalls a metamethod.\n\nIf the object at index `obj` has a metatable and this metatable has a field\n`e`, this function calls this field passing the object as its only argument.\nIn this case this function returns true and pushes onto the stack the value\nreturned by the call. If there is no metatable or no metamethod, this function\nreturns false (without pushing any value on the stack).\n -luaL_checkany luaL_checkany(lua_State *L, int narg) [void]\nChecks whether the function has an argument of any type (including nil)\nat position `narg`.\n -luaL_checkint luaL_checkint(lua_State *L, int narg) [int]\nChecks whether the function argument `narg` is a number and returns this\nnumber cast to an `int`.\n -luaL_checkinteger luaL_checkinteger(lua_State *L, int narg) [lua_Integer]\nChecks whether the function argument `narg` is a number and returns this\nnumber cast to a `lua_Integer`.\n -luaL_checklong luaL_checklong(lua_State *L, int narg) [long]\nChecks whether the function argument `narg` is a number and returns this\nnumber cast to a `long`.\n -luaL_checklstring luaL_checklstring(lua_State *L, int narg, size_t *l) [const char*]\nChecks whether the function argument `narg` is a string and returns this\nstring; if `l` is not `NULL` fills `*l` with the string's length.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n -luaL_checknumber luaL_checknumber(lua_State *L, int narg) [lua_Number]\nChecks whether the function argument `narg` is a number and returns this\nnumber.\n -luaL_checkoption luaL_checkoption(lua_State *L, int narg, const char *def, const char *const lst[]) [int]\nChecks whether the function argument `narg` is a string and searches for this\nstring in the array `lst` (which must be NULL-terminated). Returns the index\nin the array where the string was found. Raises an error if the argument\nis not a string or if the string cannot be found.\n\nIf `def` is not `NULL`, the function uses `def` as a default value when\nthere is no argument `narg` or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual\nconvention in Lua libraries is to use strings instead of numbers to select\noptions.)\n +luaL_checkany luaL_checkany(lua_State *L, int arg) [void]\nChecks whether the function has an argument of any type (including nil)\nat position `arg`.\n +luaL_checkint luaL_checkint(lua_State *L, int arg) [int]\nChecks whether the function argument `arg` is a number and returns this number\ncast to an `int`.\n +luaL_checkinteger luaL_checkinteger(lua_State *L, int arg) [lua_Integer]\nChecks whether the function argument `arg` is a number and returns this number\ncast to a `lua_Integer`.\n +luaL_checklong luaL_checklong(lua_State *L, int arg) [long]\nChecks whether the function argument `arg` is a number and returns this number\ncast to a `long`.\n +luaL_checklstring luaL_checklstring(lua_State *L, int arg, size_t *l) [const char*]\nChecks whether the function argument `arg` is a string and returns this string;\nif `l` is not `NULL` fills `*l` with the string's length.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n +luaL_checknumber luaL_checknumber(lua_State *L, int arg) [lua_Number]\nChecks whether the function argument `arg` is a number and returns this number.\n +luaL_checkoption luaL_checkoption(lua_State *L, int arg, const char *def, const char *const lst[]) [int]\nChecks whether the function argument `arg` is a string and searches for this\nstring in the array `lst` (which must be NULL-terminated). Returns the index\nin the array where the string was found. Raises an error if the argument\nis not a string or if the string cannot be found.\n\nIf `def` is not `NULL`, the function uses `def` as a default value when\nthere is no argument `arg` or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual\nconvention in Lua libraries is to use strings instead of numbers to select\noptions.)\n luaL_checkstack luaL_checkstack(lua_State *L, int sz, const char *msg) [void]\nGrows the stack size to `top + sz` elements, raising an error if the stack\ncannot grow to that size. `msg` is an additional text to go into the error\nmessage (or `NULL` for no additional text).\n -luaL_checkstring luaL_checkstring(lua_State *L, int narg) [const char*]\nChecks whether the function argument `narg` is a string and returns this\nstring.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n -luaL_checktype luaL_checktype(lua_State *L, int narg, int t) [void]\nChecks whether the function argument `narg` has type `t`. See `lua_type`\nfor the encoding of types for `t`.\n -luaL_checkudata luaL_checkudata(lua_State *L, int narg, const char *tname) [void*]\nChecks whether the function argument `narg` is a userdata of the type `tname`\n(see `luaL_newmetatable`) and returns the userdata address (see\n`lua_touserdata`).\n -luaL_checkunsigned luaL_checkunsigned(lua_State *L, int narg) [lua_Unsigned]\nChecks whether the function argument `narg` is a number and returns this number\ncast to a `lua_Unsigned`.\n +luaL_checkstring luaL_checkstring(lua_State *L, int arg) [const char*]\nChecks whether the function argument `arg` is a string and returns this string.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n +luaL_checktype luaL_checktype(lua_State *L, int arg, int t) [void]\nChecks whether the function argument `arg` has type `t`. See `lua_type` for\nthe encoding of types for `t`.\n +luaL_checkudata luaL_checkudata(lua_State *L, int arg, const char *tname) [void*]\nChecks whether the function argument `arg` is a userdata of the type `tname`\n(see `luaL_newmetatable`) and returns the userdata address (see\n`lua_touserdata`).\n +luaL_checkunsigned luaL_checkunsigned(lua_State *L, int arg) [lua_Unsigned]\nChecks whether the function argument `arg` is a number and returns this number\ncast to a `lua_Unsigned`.\n luaL_checkversion luaL_checkversion(lua_State *L) [void]\nChecks whether the core running the call, the core that created the Lua state,\nand the code making the call are all using the same version of Lua. Also checks\nwhether the core running the call and the core that created the Lua state are\nusing the same address space.\n luaL_dofile luaL_dofile(lua_State *L, const char *filename) [int]\nLoads and runs the given file. It is defined as the following macro:\n\n (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns false if there are no errors or true in case of errors.\n luaL_dostring luaL_dostring(lua_State *L, const char *str) [int]\nLoads and runs the given string. It is defined as the following macro:\n\n (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns false if there are no errors or true in case of errors.\n @@ -151,7 +151,7 @@ luaL_getmetafield luaL_getmetafield(lua_State *L, int obj, const char *e) [int]\ luaL_getmetatable luaL_getmetatable(lua_State *L, const char *tname) [void]\nPushes onto the stack the metatable associated with name `tname` in the\nregistry (see `luaL_newmetatable`).\n luaL_getsubtable luaL_getsubtable(lua_State *L, int idx, const char *fname) [int]\nEnsures that the value `t[fname]`, where `t` is the value at the valid index\n`idx`, is a table, and pushes that table onto the stack. Returns true if it\nfinds a previous table there and false if it creates a new table.\n luaL_gsub luaL_gsub(lua_State *L, const char *s, const char *p, const char *r) [const char*]\nCreates a copy of string `s` by replacing any occurrence of the string `p`\nwith the string `r`. Pushes the resulting string on the stack and returns it.\n -luaL_len luaL_len(lua_State *L, int index) [int]\nReturns the "length" of the value at the given acceptable index as a number; it\nis equivalent to the '`#`' operator in Lua (see §3.4.6). Raises an error if the\nresult of the operation is not a number. (This only can happen through\nmetamethods.)\n +luaL_len luaL_len(lua_State *L, int index) [int]\nReturns the "length" of the value at the given acceptable index as a number; it\nis equivalent to the '`#`' operator in Lua (see §3.4.6). Raises an error if the\nresult of the operation is not a number. (This case only can happen through\nmetamethods.)\n luaL_loadbuffer luaL_loadbuffer(lua_State *L, const char *buff, size_t sz, const char *name) [int]\nEquivalent to `luaL_loadbufferx` with `mode` equal to `NULL`.\n luaL_loadbufferx luaL_loadbufferx(lua_State *L, const char *buff, size_t sz, const char *name, const char *mode) [int]\nLoads a buffer as a Lua chunk. This function uses `lua_load` to load the\nchunk in the buffer pointed to by `buff` with size `sz`.\n\nThis function returns the same results as `lua_load`. `name` is the chunk\nname, used for debug information and error messages. The string `mode` works as\nin function `lua_load`.\n luaL_loadfile luaL_loadfile(lua_State *L, const char *filename) [int]\nEquivalent to `luaL_loadfilex` with `mode` equal to `NULL`.\n @@ -162,13 +162,13 @@ luaL_newlibtable luaL_newlibtable(lua_State *L, const luaL_Reg l[]) [int]\nCreat luaL_newmetatable luaL_newmetatable(lua_State *L, const char *tname) [int]\nIf the registry already has the key `tname`, returns 0. Otherwise, creates\na new table to be used as a metatable for userdata, adds it to the registry\nwith key `tname`, and returns 1.\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_optint luaL_optint(lua_State *L, int narg, int d) [int]\nIf the function argument `narg` is a number, returns this number cast to\nan `int`. If this argument is absent or is nil, returns `d`. Otherwise,\nraises an error.\n -luaL_optinteger luaL_optinteger(lua_State *L, int narg, lua_Integer d) [lua_Integer]\nIf the function argument `narg` is a number, returns this number cast to a\n`lua_Integer`. If this argument is absent or is nil, returns `d`. Otherwise,\nraises an error.\n -luaL_optlong luaL_optlong(lua_State *L, int narg, long d) [long]\nIf the function argument `narg` is a number, returns this number cast to a\n`long`. If this argument is absent or is nil, returns `d`. Otherwise,\nraises an error.\n -luaL_optlstring luaL_optlstring(lua_State *L, int narg, const char *d, size_t *l) [const char*]\nIf the function argument `narg` 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.\n -luaL_optnumber luaL_optnumber(lua_State *L, int narg, lua_Number d) [lua_Number]\nIf the function argument `narg` is a number, returns this number. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n -luaL_optstring luaL_optstring(lua_State *L, int narg, const char *d) [const char*]\nIf the function argument `narg` is a string, returns this string. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n -luaL_optunsigned luaL_optunsigned(lua_State *L, int narg, lua_Unsigned u) [lua_Unsigned]\nIf the function argument `narg` is a number, returns this number cast to a\n`lua_Unsigned`. If this argument is absent or is nil, returns `u`. Otherwise,\nraises an error.\n +luaL_optint luaL_optint(lua_State *L, int arg, int d) [int]\nIf the function argument `arg` is a number, returns this number cast to an\n`int`. If this argument is absent or is nil, returns `d`. Otherwise, raises\nan error.\n +luaL_optinteger luaL_optinteger(lua_State *L, int arg, lua_Integer d) [lua_Integer]\nIf the function argument `arg` is a number, returns this number cast to a\n`lua_Integer`. If this argument is absent or is nil, returns `d`. Otherwise,\nraises an error.\n +luaL_optlong luaL_optlong(lua_State *L, int arg, long d) [long]\nIf the function argument `arg` is a number, returns this number cast to a\n`long`. If this argument is absent or is nil, returns `d`. Otherwise,\nraises 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.\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 +luaL_optstring luaL_optstring(lua_State *L, int arg, const char *d) [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 +luaL_optunsigned luaL_optunsigned(lua_State *L, int arg, lua_Unsigned u) [lua_Unsigned]\nIf the function argument `arg` is a number, returns this number cast to a\n`lua_Unsigned`. If this argument is absent or is nil, returns `u`. Otherwise,\nraises an error.\n luaL_prepbuffer luaL_prepbuffer(luaL_Buffer *B) [char*]\nEquivalent to `luaL_prepbuffsize` with the predefined size `LUAL_BUFFERSIZE`.\n luaL_prepbuffsize luaL_prepbuffsize(luaL_Buffer *B, size_t sz) [char*]\nReturns an address to a space of size `LUAL_BUFFERSIZE` where you can copy\na string to be added to buffer `B` (see `luaL_Buffer`). After copying the\nstring into this space you must call `luaL_addsize` with the size of the\nstring to actually add it to the buffer.\n luaL_pushresult luaL_pushresult(luaL_Buffer *B) [void]\nFinishes the use of buffer `B` leaving the final string on the top of\nthe stack.\n @@ -178,7 +178,7 @@ luaL_Reg luaL_Reg [struct]\ntypedef struct luaL_Reg {\n const char *name;\n lu luaL_requiref luaL_requiref(lua_State *L, const char *modname, lua_CFunction openf, int glb) [void]\nCalls function `openf` with string `modname` as an argument and sets the call\nresult in `package.loaded[modname]`, as if that function has been called through\n`require`.\n\nIf `glb` is true, also stores the result into global `modname`.\n\nLeaves a copy of that result on the stack.\n luaL_setfuncs luaL_setfuncs(lua_State *L, const luaL_Reg *l, int nup) [void]\nRegisters all functions in the array `l` (see `luaL_Reg`) into the table on the\ntop of the stack (below optional upvalues, see next).\n\nWhen `nup` is not zero, all functions are created sharing `nup` upvalues, which\nmust be previously pushed on the stack on top of the library table. These\nvalues are popped from the stack after the registration.\n 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_testudata luaL_testudata(lua_State *L, int narg, const char *tname) [void]\nThis function works like `luaL_checkudata`, except that, when the test fails,\nit returns `NULL` instead of throwing an error.\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 throwing an error.\n luaL_tolstring luaL_tolstring(lua_State *L, int idx, size_t *len) [const char*]\nConverts any Lua value at the given acceptable index to a C string in a\nreasonable format. The resulting string is pushed onto the stack and also\nreturned by the function. If `len` is not `NULL`, the function also sets `*len`\nwith 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 diff --git a/modules/lua/lua.luadoc b/modules/lua/lua.luadoc index a288c6c9..a3ed8b41 100644 --- a/modules/lua/lua.luadoc +++ b/modules/lua/lua.luadoc @@ -538,16 +538,17 @@ function string.gmatch(s, pattern) end -- If `repl` is a string, then its value is used for replacement. The character -- `%` works as an escape character: any sequence in `repl` of the form `%d`, -- with `d` between 1 and 9, stands for the value of the `d`-th captured --- substring (see below). The sequence `%0` stands for the whole match. The --- sequence `%%` stands for a single `%`. +-- substring. The sequence `%0` stands for the whole match. The sequence `%%` +-- stands for a single `%`. -- -- If `repl` is a table, then the table is queried for every match, using --- the first capture as the key; if the pattern specifies no captures, then --- the whole match is used as the key. +-- the first capture as the key. +-- -- If `repl` is a function, then this function is called every time a match --- occurs, with all captured substrings passed as arguments, in order; if --- the pattern specifies no captures, then the whole match is passed as a --- sole argument. +-- occurs, with all captured substrings passed as arguments, in order. +-- +-- In any case, if the pattern specifies no captures, then it behaves as if the +-- whole pattern was inside a capture. -- -- If the value returned by the table query or by the function call is a -- string or a number, then it is used as the replacement string; otherwise, |