diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 266 |
1 files changed, 147 insertions, 119 deletions
diff --git a/doc/manual.html b/doc/manual.html index 360d316..4ba084d 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -19,9 +19,9 @@ Lua 5.2 Reference Manual by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes <p> <small> -Copyright © 2011 Lua.org, PUC-Rio. +Copyright © 2011–2012 Lua.org, PUC-Rio. Freely available under the terms of the -<a href="http://www.lua.org/license.html#5">Lua license</a>. +<a href="http://www.lua.org/license.html">Lua license</a>. </small> <hr> <p> @@ -33,7 +33,7 @@ Freely available under the terms of the <!-- ====================================================================== --> <p> -<!-- $Id: manual.of,v 1.94 2011/12/12 15:26:26 roberto Exp $ --> +<!-- $Id: manual.of,v 1.99 2012/06/08 15:30:20 roberto Exp $ --> @@ -913,6 +913,14 @@ the object memory is freed only when it becomes completely inaccessible; its finalizer will never be called twice. +<p> +When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), +Lua calls the finalizers of all objects marked for collection, +following the reverse order that they were marked. +If any finalizer marks new objects for collection during that phase, +these new objects will not be finalized. + + @@ -1206,7 +1214,7 @@ results in a newline in the string. The escape sequence '<code>\z</code>' skips the following span of white-space characters, including line breaks; -it is particularly useful to break and indent a long string +it is particularly useful to break and indent a long literal string into multiple lines without adding the newlines and spaces into the string contents. @@ -1234,7 +1242,7 @@ an opening long bracket of level 1 is written as <code>[=[</code>, and so on. A <em>closing long bracket</em> is defined similarly; for instance, a closing long bracket of level 4 is written as <code>]====]</code>. -A long string starts with an opening long bracket of any level and +A <em>long literal</em> starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. It can contain any text except a closing bracket of the proper level. Literals in this bracketed form can run for several lines, @@ -2820,8 +2828,7 @@ by looking only at its arguments The third field, <code>x</code>, tells whether the function may throw errors: '<code>-</code>' means the function never throws any error; -'<code>m</code>' means the function may throw only memory allocation errors; -'<code>e</code>' means the function may throw other kinds of errors; +'<code>e</code>' means the function may throw errors; '<code>v</code>' means the function may throw an error on purpose. @@ -2922,7 +2929,7 @@ it seems to be a safe assumption.) <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> <span class="apii">[-(2|1), +1, <em>e</em>]</span> -<pre>int lua_arith (lua_State *L, int op);</pre> +<pre>void lua_arith (lua_State *L, int op);</pre> <p> Performs an arithmetic operation over the two values @@ -3183,7 +3190,7 @@ without shifting any element <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> <p> @@ -3202,7 +3209,7 @@ Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</c <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> +<span class="apii">[-0, +0, <em>e</em>]</span> <pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre> <p> @@ -3343,7 +3350,7 @@ opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. <hr><h3><a name="lua_getctx"><code>lua_getctx</code></a></h3><p> <span class="apii">[-0, +0, –]</span> -<pre>int lua_getctx (lua_State *L, int *ctx);</pre> +<pre>int lua_getctx (lua_State *L, int *ctx);</pre> <p> This function is called by a continuation function (see <a href="#4.7">§4.7</a>) @@ -3740,7 +3747,7 @@ passes to the allocator in every call. <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>void lua_newtable (lua_State *L);</pre> <p> @@ -3752,7 +3759,7 @@ It is equivalent to <code>lua_createtable(L, 0, 0)</code>. <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>lua_State *lua_newthread (lua_State *L);</pre> <p> @@ -3773,7 +3780,7 @@ like any Lua object. <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> <p> @@ -3959,7 +3966,7 @@ Pushes a boolean value with value <code>b</code> onto the stack. <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> -<span class="apii">[-n, +1, <em>m</em>]</span> +<span class="apii">[-n, +1, <em>e</em>]</span> <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> <p> @@ -4025,7 +4032,7 @@ Note that <code>f</code> is used twice. <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> <p> @@ -4092,7 +4099,7 @@ light userdata with the same C address. <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> <p> @@ -4105,7 +4112,7 @@ It automatically provides the string length. <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> <p> @@ -4148,7 +4155,7 @@ Pushes a number with value <code>n</code> onto the stack. <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> <p> @@ -4195,7 +4202,7 @@ onto the stack. <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp);</pre> @@ -4282,7 +4289,7 @@ for other values, it is 0. <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> -<span class="apii">[-2, +0, <em>m</em>]</span> +<span class="apii">[-2, +0, <em>e</em>]</span> <pre>void lua_rawset (lua_State *L, int index);</pre> <p> @@ -4294,7 +4301,7 @@ Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> +<span class="apii">[-1, +0, <em>e</em>]</span> <pre>void lua_rawseti (lua_State *L, int index, int n);</pre> <p> @@ -4313,7 +4320,7 @@ that is, it does not invoke metamethods. <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> +<span class="apii">[-1, +0, <em>e</em>]</span> <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> <p> @@ -4400,7 +4407,7 @@ and then pops the top element. <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> <span class="apii">[-?, +?, –]</span> -<pre>int lua_resume (lua_State *L, lua_State *from, int narg);</pre> +<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> <p> Starts and resumes a coroutine in a given thread. @@ -4410,7 +4417,7 @@ Starts and resumes a coroutine in a given thread. To start a coroutine, you push onto the thread stack the main function plus any arguments; then you call <a href="#lua_resume"><code>lua_resume</code></a>, -with <code>narg</code> being the number of arguments. +with <code>nargs</code> being the number of arguments. This call returns when the coroutine suspends or finishes its execution. When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, or all values returned by the body function. @@ -4550,14 +4557,15 @@ the new value associated to the userdata at the given index. <pre>typedef struct lua_State lua_State;</pre> <p> -An opaque structure that keeps the whole state of a Lua interpreter. +An opaque structure that points to a thread and indirectly +(through the thread) to the whole state of a Lua interpreter. The Lua library is fully reentrant: it has no global variables. -All information about a state is kept in this structure. +All information about a state is accessible through this structure. <p> -A pointer to this state must be passed as the first argument to +A pointer to this structure must be passed as the first argument to every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, which creates a Lua state from scratch. @@ -4660,7 +4668,7 @@ indicates whether the operation succeeded. <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> +<span class="apii">[-0, +0, <em>e</em>]</span> <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> <p> @@ -4743,7 +4751,7 @@ Typically this function is used only for debug information. <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> +<span class="apii">[-0, +0, <em>e</em>]</span> <pre>const char *lua_tostring (lua_State *L, int index);</pre> <p> @@ -4848,7 +4856,7 @@ and <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> <span class="apii">[-0, +0, –]</span> -<pre>const char *lua_typename (lua_State *L, int tp);</pre> +<pre>const char *lua_typename (lua_State *L, int tp);</pre> <p> Returns the name of the type encoded by the value <code>tp</code>, @@ -4932,7 +4940,7 @@ and pushes them onto the stack <code>to</code>. <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> <span class="apii">[-?, +?, –]</span> -<pre>int lua_yield (lua_State *L, int nresults);</pre> +<pre>int lua_yield (lua_State *L, int nresults);</pre> <p> This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, @@ -4947,7 +4955,7 @@ the function calling <code>lua_yield</code>. <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> <span class="apii">[-?, +?, –]</span> -<pre>int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);</pre> +<pre>int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);</pre> <p> Yields a coroutine. @@ -5145,11 +5153,11 @@ Returns the current hook mask. <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> -<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> +<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> <p> -Returns information about a specific function or function invocation. +Gets information about a specific function or function invocation. <p> @@ -5268,7 +5276,7 @@ the number of active local variables. <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> <p> -Get information about the interpreter runtime stack. +Gets information about the interpreter runtime stack. <p> @@ -5345,6 +5353,20 @@ Therefore, if a hook calls back Lua to execute a function or a chunk, this execution occurs without any calls to hooks. +<p> +Hook functions cannot have continuations, +that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, +<a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>. + + +<p> +Hook functions can yield under the following conditions: +Only count and line events can yield +and they cannot yield any value; +to yield a hook function must finish its execution +calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero. + + @@ -5450,7 +5472,7 @@ when the index is greater than the number of upvalues. <p> Returns an unique identifier for the upvalue numbered <code>n</code> -from the closure at index <code>fidx</code>. +from the closure at index <code>funcindex</code>. Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>) (but <code>n</code> cannot be greater than the number of upvalues). @@ -5467,13 +5489,14 @@ will return identical ids for those upvalue indices. -<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3> -<pre>void lua_upvaluejoin (lua_State *L, int fidx1, int n1, - int fidx2, int n2);</pre> +<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> +<span class="apii">[-0, +0, –]</span> +<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, + int funcindex2, int n2);</pre> <p> -Make the <code>n1</code>-th upvalue of the Lua closure at index <code>fidx1</code> -refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>fidx2</code>. +Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> +refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. @@ -5538,7 +5561,7 @@ in alphabetical order. <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> <p> @@ -5550,7 +5573,7 @@ Adds the byte <code>c</code> to the buffer <code>B</code> <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> <p> @@ -5564,7 +5587,7 @@ The string can contain embedded zeros. <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> <p> @@ -5577,7 +5600,7 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> <p> @@ -5591,7 +5614,7 @@ The string cannot contain embedded zeros. <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> -<span class="apii">[-1, +?, <em>m</em>]</span> +<span class="apii">[-1, +?, <em>e</em>]</span> <pre>void luaL_addvalue (luaL_Buffer *B);</pre> <p> @@ -5614,7 +5637,7 @@ which is the value to be added to the buffer. <span class="apii">[-0, +0, <em>v</em>]</span> <pre>void luaL_argcheck (lua_State *L, int cond, - int narg, + int arg, const char *extramsg);</pre> <p> @@ -5627,7 +5650,7 @@ If not, raises an error with a standard message. <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> +<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> <p> Raises an error with a standard message @@ -5686,7 +5709,7 @@ size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.< <li>Then copy the string into that space.</li> <li> -Finish by calling <code>luaL_pushresult(&b, sz)</code>, +Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, where <code>sz</code> is the total size of the resulting string copied into that space. </li> @@ -5728,7 +5751,7 @@ the buffer must be declared as a variable <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> <p> @@ -5762,11 +5785,11 @@ this function returns false (without pushing any value on the stack). <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checkany (lua_State *L, int narg);</pre> +<pre>void luaL_checkany (lua_State *L, int arg);</pre> <p> Checks whether the function has an argument -of any type (including <b>nil</b>) at position <code>narg</code>. +of any type (including <b>nil</b>) at position <code>arg</code>. @@ -5774,10 +5797,10 @@ of any type (including <b>nil</b>) at position <code>narg</code>. <hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_checkint (lua_State *L, int narg);</pre> +<pre>int luaL_checkint (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a number +Checks whether the function argument <code>arg</code> is a number and returns this number cast to an <code>int</code>. @@ -5786,10 +5809,10 @@ and returns this number cast to an <code>int</code>. <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre> +<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a number +Checks whether the function argument <code>arg</code> is a number and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. @@ -5798,10 +5821,10 @@ and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code <hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>long luaL_checklong (lua_State *L, int narg);</pre> +<pre>long luaL_checklong (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a number +Checks whether the function argument <code>arg</code> is a number and returns this number cast to a <code>long</code>. @@ -5810,10 +5833,10 @@ and returns this number cast to a <code>long</code>. <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre> +<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> <p> -Checks whether the function argument <code>narg</code> is a string +Checks whether the function argument <code>arg</code> is a string and returns this string; if <code>l</code> is not <code>NULL</code> fills <code>*l</code> with the string's length. @@ -5829,10 +5852,10 @@ so all conversions and caveats of that function apply here. <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre> +<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a number +Checks whether the function argument <code>arg</code> is a number and returns this number. @@ -5842,12 +5865,12 @@ and returns this number. <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> <pre>int luaL_checkoption (lua_State *L, - int narg, + int arg, const char *def, const char *const lst[]);</pre> <p> -Checks whether the function argument <code>narg</code> is a string and +Checks whether the function argument <code>arg</code> is a string and searches for this string in the array <code>lst</code> (which must be NULL-terminated). Returns the index in the array where the string was found. @@ -5858,7 +5881,7 @@ if the string cannot be found. <p> If <code>def</code> is not <code>NULL</code>, the function uses <code>def</code> as a default value when -there is no argument <code>narg</code> or when this argument is <b>nil</b>. +there is no argument <code>arg</code> or when this argument is <b>nil</b>. <p> @@ -5886,10 +5909,10 @@ raising an error if the stack cannot grow to that size. <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_checkstring (lua_State *L, int narg);</pre> +<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a string +Checks whether the function argument <code>arg</code> is a string and returns this string. @@ -5903,10 +5926,10 @@ so all conversions and caveats of that function apply here. <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre> +<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> <p> -Checks whether the function argument <code>narg</code> has type <code>t</code>. +Checks whether the function argument <code>arg</code> has type <code>t</code>. See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. @@ -5915,10 +5938,10 @@ See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre> +<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> <p> -Checks whether the function argument <code>narg</code> is a userdata +Checks whether the function argument <code>arg</code> is a userdata of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). @@ -5928,10 +5951,10 @@ returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata <hr><h3><a name="luaL_checkunsigned"><code>luaL_checkunsigned</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Unsigned luaL_checkunsigned (lua_State *L, int narg);</pre> +<pre>lua_Unsigned luaL_checkunsigned (lua_State *L, int arg);</pre> <p> -Checks whether the function argument <code>narg</code> is a number +Checks whether the function argument <code>arg</code> is a number and returns this number cast to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>. @@ -5955,7 +5978,7 @@ are using the same address space. <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> -<span class="apii">[-0, +?, <em>m</em>]</span> +<span class="apii">[-0, +?, <em>e</em>]</span> <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> <p> @@ -6014,7 +6037,7 @@ as <code>return luaL_error(<em>args</em>)</code>. <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> -<span class="apii">[-0, +3, <em>m</em>]</span> +<span class="apii">[-0, +3, <em>e</em>]</span> <pre>int luaL_execresult (lua_State *L, int stat);</pre> <p> @@ -6027,7 +6050,7 @@ process-related functions in the standard library <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> -<span class="apii">[-0, +(1|3), <em>m</em>]</span> +<span class="apii">[-0, +(1|3), <em>e</em>]</span> <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> <p> @@ -6040,7 +6063,7 @@ file-related functions in the standard library <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>m</em>]</span> +<span class="apii">[-0, +(0|1), <em>e</em>]</span> <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> <p> @@ -6067,7 +6090,7 @@ in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code> <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> <p> @@ -6083,7 +6106,7 @@ and false if it creates a new table. <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>const char *luaL_gsub (lua_State *L, const char *s, const char *p, @@ -6100,7 +6123,7 @@ Pushes the resulting string on the stack and returns it. <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> +<span class="apii">[-0, +0, <em>e</em>]</span> <pre>int luaL_len (lua_State *L, int index);</pre> <p> @@ -6108,7 +6131,7 @@ Returns the "length" of the value at the given acceptable index as a number; it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.6">§3.4.6</a>). Raises an error if the result of the operation is not a number. -(This only can happen through metamethods.) +(This case only can happen through metamethods.) @@ -6153,7 +6176,7 @@ The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_ <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> <p> @@ -6164,7 +6187,7 @@ Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <co <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_loadfilex (lua_State *L, const char *filename, const char *mode);</pre> @@ -6218,7 +6241,7 @@ it does not run it. <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_newlib (lua_State *L, const luaL_Reg *l);</pre> <p> @@ -6234,7 +6257,7 @@ It is implemented as the following macro: <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> <p> @@ -6255,7 +6278,7 @@ not a pointer to it. <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> <p> @@ -6309,10 +6332,10 @@ Opens all standard Lua libraries into the given state. <hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_optint (lua_State *L, int narg, int d);</pre> +<pre>int luaL_optint (lua_State *L, int arg, int d);</pre> <p> -If the function argument <code>narg</code> is a number, +If the function argument <code>arg</code> is a number, returns this number cast to an <code>int</code>. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6325,11 +6348,11 @@ Otherwise, raises an error. <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> <pre>lua_Integer luaL_optinteger (lua_State *L, - int narg, + int arg, lua_Integer d);</pre> <p> -If the function argument <code>narg</code> is a number, +If the function argument <code>arg</code> is a number, returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6341,10 +6364,10 @@ Otherwise, raises an error. <hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre> +<pre>long luaL_optlong (lua_State *L, int arg, long d);</pre> <p> -If the function argument <code>narg</code> is a number, +If the function argument <code>arg</code> is a number, returns this number cast to a <code>long</code>. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6357,12 +6380,12 @@ Otherwise, raises an error. <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> <pre>const char *luaL_optlstring (lua_State *L, - int narg, + int arg, const char *d, size_t *l);</pre> <p> -If the function argument <code>narg</code> is a string, +If the function argument <code>arg</code> is a string, returns this string. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6379,10 +6402,10 @@ fills the position <code>*l</code> with the result's length. <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre> +<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> <p> -If the function argument <code>narg</code> is a number, +If the function argument <code>arg</code> is a number, returns this number. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6395,11 +6418,11 @@ Otherwise, raises an error. <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> <pre>const char *luaL_optstring (lua_State *L, - int narg, + int arg, const char *d);</pre> <p> -If the function argument <code>narg</code> is a string, +If the function argument <code>arg</code> is a string, returns this string. If this argument is absent or is <b>nil</b>, returns <code>d</code>. @@ -6412,11 +6435,11 @@ Otherwise, raises an error. <hr><h3><a name="luaL_optunsigned"><code>luaL_optunsigned</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> <pre>lua_Unsigned luaL_optunsigned (lua_State *L, - int narg, + int arg, lua_Unsigned u);</pre> <p> -If the function argument <code>narg</code> is a number, +If the function argument <code>arg</code> is a number, returns this number cast to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>. If this argument is absent or is <b>nil</b>, returns <code>u</code>. @@ -6427,7 +6450,7 @@ Otherwise, raises an error. <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> <p> @@ -6439,7 +6462,7 @@ with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</co <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> +<span class="apii">[-?, +?, <em>e</em>]</span> <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> <p> @@ -6455,7 +6478,7 @@ it to the buffer. <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> -<span class="apii">[-?, +1, <em>m</em>]</span> +<span class="apii">[-?, +1, <em>e</em>]</span> <pre>void luaL_pushresult (luaL_Buffer *B);</pre> <p> @@ -6467,7 +6490,7 @@ the top of the stack. <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> -<span class="apii">[-?, +1, <em>m</em>]</span> +<span class="apii">[-?, +1, <em>e</em>]</span> <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> <p> @@ -6478,7 +6501,7 @@ Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a> <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> +<span class="apii">[-1, +0, <em>e</em>]</span> <pre>int luaL_ref (lua_State *L, int t);</pre> <p> @@ -6582,8 +6605,8 @@ in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code> <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> -<pre>void *luaL_testudata (lua_State *L, int narg, const char *tname);</pre> +<span class="apii">[-0, +0, <em>e</em>]</span> +<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> <p> This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, @@ -6618,7 +6641,7 @@ and uses the result of the call as its result. <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, int level);</pre> @@ -6665,7 +6688,7 @@ If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> +<span class="apii">[-0, +1, <em>e</em>]</span> <pre>void luaL_where (lua_State *L, int lvl);</pre> <p> @@ -6749,7 +6772,7 @@ the host program can open them individually by using <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), -<a name="pdf-luaopen_bitlib"><code>luaopen_bitlib</code></a> (for the bit library), +<a name="pdf-luaopen_bit32"><code>luaopen_bit32</code></a> (for the bit library), <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). @@ -7914,24 +7937,26 @@ If <code>repl</code> is a string, then its value is used for replacement. The character <code>%</code> works as an escape character: any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, with <em>d</em> between 1 and 9, -stands for the value of the <em>d</em>-th captured substring (see below). +stands for the value of the <em>d</em>-th captured substring. The sequence <code>%0</code> stands for the whole match. The sequence <code>%%</code> stands for a single <code>%</code>. <p> If <code>repl</code> 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. +using the first capture as the key. <p> If <code>repl</code> is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, -in order; +in order. + + +<p> +In any case, if the pattern specifies no captures, -then the whole match is passed as a sole argument. +then it behaves as if the whole pattern was inside a capture. <p> @@ -10091,6 +10116,9 @@ You can avoid some incompatibilities by compiling Lua with appropriate options (see file <code>luaconf.h</code>). However, all these compatibility options will be removed in the next version of Lua. +Similarly, +all features marked as deprecated in Lua 5.1 +have been removed in Lua 5.2. @@ -10387,10 +10415,10 @@ Here is the complete syntax of Lua in extended BNF. <HR> <SMALL CLASS="footer"> Last update: -Mon Dec 12 15:21:08 BRST 2011 +Fri Jun 8 16:13:40 BRT 2012 </SMALL> <!-- -Last change: revised for Lua 5.2.0 +Last change: revised for Lua 5.2.1 --> </body></html> |