diff options
Diffstat (limited to '3rdparty/lua/doc/manual.html')
-rw-r--r-- | 3rdparty/lua/doc/manual.html | 355 |
1 files changed, 228 insertions, 127 deletions
diff --git a/3rdparty/lua/doc/manual.html b/3rdparty/lua/doc/manual.html index 61a8220d7fd..574c7432c0f 100644 --- a/3rdparty/lua/doc/manual.html +++ b/3rdparty/lua/doc/manual.html @@ -10,7 +10,7 @@ <BODY> <H1> -<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> +<A HREF="https://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> Lua 5.4 Reference Manual </H1> @@ -19,9 +19,9 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes <P> <SMALL> -Copyright © 2020–2022 Lua.org, PUC-Rio. +Copyright © 2020–2024 Lua.org, PUC-Rio. Freely available under the terms of the -<a href="http://www.lua.org/license.html">Lua license</a>. +<a href="https://www.lua.org/license.html">Lua license</a>. </SMALL> <DIV CLASS="menubar"> @@ -29,7 +29,7 @@ Freely available under the terms of the · <A HREF="contents.html#index">index</A> · -<A HREF="http://www.lua.org/manual/">other versions</A> +<A HREF="https://www.lua.org/manual/">other versions</A> </DIV> <!-- ====================================================================== --> @@ -63,7 +63,7 @@ and rapid prototyping. <p> Lua is implemented as a library, written in <em>clean C</em>, -the common subset of Standard C and C++. +the common subset of standard C and C++. The Lua distribution includes a host program called <code>lua</code>, which uses the Lua library to offer a complete, standalone Lua interpreter, @@ -391,7 +391,7 @@ Whenever there is an error, an <em>error object</em> is propagated with information about the error. Lua itself only generates errors whose error object is a string, -but programs may generate errors with +but programs can generate errors with any value as the error object. It is up to the Lua program or its host to handle such error objects. For historical reasons, @@ -401,7 +401,7 @@ even though it does not have to be a string. <p> When you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C) -you may give a <em>message handler</em> +you can give a <em>message handler</em> to be called in case of errors. This function is called with the original error object and returns a new error object. @@ -453,7 +453,7 @@ which is then called a <em>metamethod</em>. In the previous example, the key is the string "<code>__add</code>" and the metamethod is the function that performs the addition. Unless stated otherwise, -a metamethod may in fact be any callable value, +a metamethod can in fact be any callable value, which is either a function or a value with a <code>__call</code> metamethod. @@ -1379,7 +1379,9 @@ Lua also accepts hexadecimal constants, which start with <code>0x</code> or <code>0X</code>. Hexadecimal constants also accept an optional fractional part plus an optional binary exponent, -marked by a letter '<code>p</code>' or '<code>P</code>'. +marked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal. +(For instance, <code>0x1.fp10</code> denotes 1984, +which is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.) <p> @@ -1621,21 +1623,13 @@ Expressions are discussed in <a href="#3.4">§3.4</a>. <p> Before the assignment, the list of values is <em>adjusted</em> to the length of -the list of variables. -If there are more values than needed, -the excess values are thrown away. -If there are fewer values than needed, -the list is extended with <b>nil</b>'s. -If the list of expressions ends with a function call, -then all values returned by that call enter the list of values, -before the adjustment -(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). +the list of variables (see <a href="#3.4.12">§3.4.12</a>). <p> If a variable is both assigned and read inside a multiple assignment, -Lua ensures all reads get the value of the variable +Lua ensures that all reads get the value of the variable before the assignment. Thus the code @@ -1731,7 +1725,7 @@ labels in Lua are considered statements too: <p> A label is visible in the entire block where it is defined, except inside nested functions. -A goto may jump to any visible label as long as it does not +A goto can jump to any visible label as long as it does not enter into the scope of a local variable. A label should not be declared where a label with the same name is visible, @@ -1739,11 +1733,6 @@ even if this other label has been declared in an enclosing block. <p> -Labels and empty statements are called <em>void statements</em>, -as they perform no actions. - - -<p> The <b>break</b> statement terminates the execution of a <b>while</b>, <b>repeat</b>, or <b>for</b> loop, skipping to the next statement after the loop: @@ -2059,7 +2048,7 @@ function calls are explained in <a href="#3.4.10">§3.4.10</a>; table constructors are explained in <a href="#3.4.9">§3.4.9</a>. Vararg expressions, denoted by three dots ('<code>...</code>'), can only be used when -directly inside a vararg function; +directly inside a variadic function; they are explained in <a href="#3.4.11">§3.4.11</a>. @@ -2074,52 +2063,6 @@ the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). -<p> -Both function calls and vararg expressions can result in multiple values. -If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), -then its return list is adjusted to zero elements, -thus discarding all returned values. -If an expression is used as the last (or the only) element -of a list of expressions, -then no adjustment is made -(unless the expression is enclosed in parentheses). -In all other contexts, -Lua adjusts the result list to one element, -either discarding all values except the first one -or adding a single <b>nil</b> if there are no values. - - -<p> -Here are some examples: - -<pre> - f() -- adjusted to 0 results - g(f(), x) -- f() is adjusted to 1 result - g(x, f()) -- g gets x plus all results from f() - a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) - a,b = ... -- a gets the first vararg argument, b gets - -- the second (both a and b can get nil if there - -- is no corresponding vararg argument) - - a,b,c = x, f() -- f() is adjusted to 2 results - a,b,c = f() -- f() is adjusted to 3 results - return f() -- returns all results from f() - return ... -- returns all received vararg arguments - return x,y,f() -- returns x, y, and all results from f() - {f()} -- creates a list with all results from f() - {...} -- creates a list with all vararg arguments - {f(), nil} -- f() is adjusted to 1 result -</pre> - -<p> -Any expression enclosed in parentheses always results in only one value. -Thus, -<code>(f(x,y,z))</code> is always a single value, -even if <code>f</code> returns several values. -(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> -or <b>nil</b> if <code>f</code> does not return any values.) - - @@ -2252,8 +2195,9 @@ Note that bitwise operators do not do this coercion. <p> -Nonetheless, it is always a good practice not to rely on these -implicit coercions, as they are not always applied; +It is always a good practice not to rely on the +implicit coercions from strings to numbers, +as they are not always applied; in particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error (see <a href="#3.4.4">§3.4.4</a>). These coercions exist mainly for compatibility and may be removed @@ -2558,9 +2502,9 @@ The order of the assignments in a constructor is undefined. <p> If the last field in the list has the form <code>exp</code> -and the expression is a function call or a vararg expression, +and the expression is a multires expression, then all values returned by this expression enter the list consecutively -(see <a href="#3.4.10">§3.4.10</a>). +(see <a href="#3.4.12">§3.4.12</a>). <p> @@ -2624,7 +2568,7 @@ A call of the form <code>return <em>functioncall</em></code> not in the scope of a to-be-closed variable is called a <em>tail call</em>. Lua implements <em>proper tail calls</em> (or <em>proper tail recursion</em>): -in a tail call, +In a tail call, the called function reuses the stack entry of the calling function. Therefore, there is no limit on the number of nested tail calls that a program can execute. @@ -2727,22 +2671,16 @@ initialized with the argument values: </pre><p> When a Lua function is called, it adjusts its list of arguments to -the length of its list of parameters, -unless the function is a <em>vararg function</em>, +the length of its list of parameters (see <a href="#3.4.12">§3.4.12</a>), +unless the function is a <em>variadic function</em>, which is indicated by three dots ('<code>...</code>') at the end of its parameter list. -A vararg function does not adjust its argument list; +A variadic function does not adjust its argument list; instead, it collects all extra arguments and supplies them to the function through a <em>vararg expression</em>, which is also written as three dots. The value of this expression is a list of all actual extra arguments, -similar to a function with multiple results. -If a vararg expression is used inside another expression -or in the middle of a list of expressions, -then its return list is adjusted to one element. -If the expression is used as the last element of a list of expressions, -then no adjustment is made -(unless that last expression is enclosed in parentheses). +similar to a function with multiple results (see <a href="#3.4.12">§3.4.12</a>). <p> @@ -2803,6 +2741,122 @@ is syntactic sugar for +<h3>3.4.12 – <a name="3.4.12">Lists of expressions, multiple results, +and adjustment</a></h3> + +<p> +Both function calls and vararg expressions can result in multiple values. +These expressions are called <em>multires expressions</em>. + + +<p> +When a multires expression is used as the last element +of a list of expressions, +all results from the expression are added to the +list of values produced by the list of expressions. +Note that a single expression +in a place that expects a list of expressions +is the last expression in that (singleton) list. + + +<p> +These are the places where Lua expects a list of expressions: + +<ul> + +<li>A <b>return</b> statement, +for instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">§3.3.4</a>).</li> + +<li>A table constructor, +for instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">§3.4.9</a>).</li> + +<li>The arguments of a function call, +for instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">§3.4.10</a>).</li> + +<li>A multiple assignment, +for instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">§3.3.3</a>).</li> + +<li>A local declaration, +for instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">§3.3.7</a>).</li> + +<li>The initial values in a generic <b>for</b> loop, +for instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">§3.3.5</a>).</li> + +</ul><p> +In the last four cases, +the list of values from the list of expressions +must be <em>adjusted</em> to a specific length: +the number of parameters in a call to a non-variadic function +(see <a href="#3.4.11">§3.4.11</a>), +the number of variables in a multiple assignment or +a local declaration, +and exactly four values for a generic <b>for</b> loop. +The <em>adjustment</em> follows these rules: +If there are more values than needed, +the extra values are thrown away; +if there are fewer values than needed, +the list is extended with <b>nil</b>'s. +When the list of expressions ends with a multires expression, +all results from that expression enter the list of values +before the adjustment. + + +<p> +When a multires expression is used +in a list of expressions without being the last element, +or in a place where the syntax expects a single expression, +Lua adjusts the result list of that expression to one element. +As a particular case, +the syntax expects a single expression inside a parenthesized expression; +therefore, adding parentheses around a multires expression +forces it to produce exactly one result. + + +<p> +We seldom need to use a vararg expression in a place +where the syntax expects a single expression. +(Usually it is simpler to add a regular parameter before +the variadic part and use that parameter.) +When there is such a need, +we recommend assigning the vararg expression +to a single variable and using that variable +in its place. + + +<p> +Here are some examples of uses of mutlres expressions. +In all cases, when the construction needs +"the n-th result" and there is no such result, +it uses a <b>nil</b>. + +<pre> + print(x, f()) -- prints x and all results from f(). + print(x, (f())) -- prints x and the first result from f(). + print(f(), x) -- prints the first result from f() and x. + print(1 + f()) -- prints 1 added to the first result from f(). + local x = ... -- x gets the first vararg argument. + x,y = ... -- x gets the first vararg argument, + -- y gets the second vararg argument. + x,y,z = w, f() -- x gets w, y gets the first result from f(), + -- z gets the second result from f(). + x,y,z = f() -- x gets the first result from f(), + -- y gets the second result from f(), + -- z gets the third result from f(). + x,y,z = f(), g() -- x gets the first result from f(), + -- y gets the first result from g(), + -- z gets the second result from g(). + x,y,z = (f()) -- x gets the first result from f(), y and z get nil. + return f() -- returns all results from f(). + return x, ... -- returns x and all received vararg arguments. + return x,y,f() -- returns x, y, and all results from f(). + {f()} -- creates a list with all results from f(). + {...} -- creates a list with all vararg arguments. + {f(), 5} -- creates a list with the first result from f() and 5. +</pre> + + + + <h2>3.5 – <a name="3.5">Visibility Rules</a></h2> @@ -2813,6 +2867,7 @@ Lua is a lexically scoped language. The scope of a local variable begins at the first statement after its declaration and lasts until the last non-void statement of the innermost block that includes the declaration. +(<em>Void statements</em> are labels and empty statements.) Consider the following example: <pre> @@ -3071,7 +3126,7 @@ In general, Lua's garbage collection can free or move internal memory and then invalidate pointers to internal strings. To allow a safe use of these pointers, -The API guarantees that any pointer to a string in a stack index +the API guarantees that any pointer to a string in a stack index is valid while the string value at that index is not removed from the stack. (It can be moved to another index, though.) When the index is a pseudo-index (referring to an upvalue), @@ -3537,7 +3592,7 @@ It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newst return realloc(ptr, nsize); } </pre><p> -Note that Standard C ensures +Note that ISO C ensures that <code>free(NULL)</code> has no effect and that <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. @@ -3785,8 +3840,36 @@ when called through this function. <p> -(Exceptionally, this function was introduced in release 5.4.3. -It is not present in previous 5.4 releases.) +(This function was introduced in release 5.4.3.) + + + + + +<hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p> +<span class="apii">[-0, +?, –]</span> +<pre>int lua_closethread (lua_State *L, lua_State *from);</pre> + +<p> +Resets a thread, cleaning its call stack and closing all pending +to-be-closed variables. +Returns a status code: +<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread +(either the original error that stopped the thread or +errors in closing methods), +or an error status otherwise. +In case of error, +leaves the error object on the top of the stack. + + +<p> +The parameter <code>from</code> represents the coroutine that is resetting <code>L</code>. +If there is no such coroutine, +this parameter can be <code>NULL</code>. + + +<p> +(This function was introduced in release 5.4.6.) @@ -4542,7 +4625,7 @@ Pops a key from the stack, and pushes a key–value pair from the table at the given index, the "next" pair after the given key. If there are no more elements in the table, -then <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. +then <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. <p> @@ -4985,6 +5068,7 @@ Also returns 0 if any of the indices are not valid. <p> Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access (i.e., without metamethods). +The value at <code>index</code> must be a table. @@ -5051,6 +5135,7 @@ For other values, this call returns 0. <p> Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment (i.e., without metamethods). +The value at <code>index</code> must be a table. @@ -5166,15 +5251,9 @@ and then pops the top element. <pre>int lua_resetthread (lua_State *L);</pre> <p> -Resets a thread, cleaning its call stack and closing all pending -to-be-closed variables. -Returns a status code: -<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread -(either the original error that stopped the thread or -errors in closing methods), -or an error status otherwise. -In case of error, -leaves the error object on the top of the stack. +This function is deprecated; +it is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with +<code>from</code> being <code>NULL</code>. @@ -5492,7 +5571,7 @@ otherwise, returns <code>NULL</code>. <hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> +<span class="apii">[-0, +0, <em>v</em>]</span> <pre>void lua_toclose (lua_State *L, int index);</pre> <p> @@ -5513,6 +5592,11 @@ unless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</c <p> +This function raises an error if the value at the given slot +neither has a <code>__close</code> metamethod nor is a false value. + + +<p> This function should not be called for an index that is equal to or below an active to-be-closed slot. @@ -5585,6 +5669,12 @@ after its last character (as in C), but can contain other zeros in its body. +<p> +This function can raise memory errors only +when converting a number to a string +(as then it may create a new string). + + @@ -6033,7 +6123,7 @@ the number of parameters of the function </li> <li><b><code>isvararg</code>: </b> -true if the function is a vararg function +true if the function is a variadic function (always true for C functions). </li> @@ -6773,7 +6863,7 @@ Equivalent to the sequence <pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> <p> -Removes <code>n</code> bytes from the the buffer <code>B</code> +Removes <code>n</code> bytes from the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). The buffer must have at least that many bytes. @@ -6968,8 +7058,8 @@ It is defined as the following macro: <pre> (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) </pre><p> -It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, -or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). +It returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, +or 1 in case of errors. @@ -6986,8 +7076,8 @@ It is defined as the following macro: <pre> (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) </pre><p> -It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, -or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). +It returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, +or 1 in case of errors. @@ -7294,7 +7384,7 @@ with <code>tname</code> in the registry. <p> Creates a new Lua state. It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an -allocator based on the standard C allocation functions +allocator based on the ISO C allocation functions and then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) that print messages to the standard error output. @@ -7685,9 +7775,7 @@ to start the traceback. <hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> <span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_typeerror (lua_State *L, - int arg, - const char *tname);</pre> +<pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre> <p> Raises a type error for the argument <code>arg</code> @@ -8708,6 +8796,8 @@ When you require a module <code>modname</code> and This variable is only a reference to the real table; assignments to this variable do not change the table used by <a href="#pdf-require"><code>require</code></a>. +The real table is stored in the C registry (see <a href="#4.3">§4.3</a>), +indexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string. @@ -8745,7 +8835,7 @@ including if necessary a path and an extension. <p> -This function is not supported by Standard C. +This functionality is not supported by ISO C. As such, it is only available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the <code>dlfcn</code> standard). @@ -8799,6 +8889,8 @@ A table to store loaders for specific modules This variable is only a reference to the real table; assignments to this variable do not change the table used by <a href="#pdf-require"><code>require</code></a>. +The real table is stored in the C registry (see <a href="#4.3">§4.3</a>), +indexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string. @@ -9311,7 +9403,7 @@ according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4. <p> -Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> +Returns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> with the given format. The format string cannot have the variable-length options '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). @@ -10091,9 +10183,9 @@ Returns the arc sine of <code>x</code> (in radians). <p> - + Returns the arc tangent of <code>y/x</code> (in radians), -but uses the signs of both arguments to find the +using the signs of both arguments to find the quadrant of the result. It also handles correctly the case of <code>x</code> being zero. @@ -10953,7 +11045,7 @@ The default value for <code>code</code> is <b>true</b>. <p> If the optional second argument <code>close</code> is true, -closes the Lua state before exiting. +the function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>). @@ -11195,13 +11287,13 @@ The returned table can contain all the fields returned by <a href="#lua_getinfo" with the string <code>what</code> describing which fields to fill in. The default for <code>what</code> is to get all information available, except the table of valid lines. -If present, -the option '<code>f</code>' +The option '<code>f</code>' adds a field named <code>func</code> with the function itself. -If present, -the option '<code>L</code>' -adds a field named <code>activelines</code> with the table of -valid lines. +The option '<code>L</code>' adds a field named <code>activelines</code> +with the table of valid lines, +provided the function is a Lua function. +If the function has no debug information, +the table is empty. <p> @@ -11503,12 +11595,18 @@ The options are: <li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> <li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the result to global <em>mod</em>;</li> +<li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the + result to global <em>g</em>;</li> <li><b><code>-v</code>: </b> print version information;</li> <li><b><code>-E</code>: </b> ignore environment variables;</li> <li><b><code>-W</code>: </b> turn warnings on;</li> <li><b><code>--</code>: </b> stop handling options;</li> <li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> </ul><p> +(The form <code>-l <em>g=mod</em></code> was introduced in release 5.4.4.) + + +<p> After handling its options, <code>lua</code> runs the given <em>script</em>. When called without arguments, <code>lua</code> behaves as <code>lua -v -i</code> @@ -11532,6 +11630,10 @@ Lua does not consult any environment variables. In particular, the values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> are set with the default paths defined in <code>luaconf.h</code>. +To signal to the libraries that this option is on, +the stand-alone interpreter sets the field +<code>"LUA_NOENV"</code> in the registry to a true value. +Other libraries may consult this field for the same purpose. <p> @@ -11582,7 +11684,7 @@ If there is a script, the script is called with arguments <code>arg[1]</code>, ···, <code>arg[#arg]</code>. Like all chunks in Lua, -the script is compiled as a vararg function. +the script is compiled as a variadic function. <p> @@ -11946,13 +12048,12 @@ and LiteralString, see <a href="#3.1">§3.1</a>.) - <P CLASS="footer"> Last update: -Thu Jan 13 11:33:16 UTC 2022 +Thu Jun 13 22:15:52 UTC 2024 </P> <!-- -Last change: revised for Lua 5.4.4 +Last change: revised for Lua 5.4.7 --> </body></html> |