vendor/lua/5.4.6

1 files changed, 199 insertions, 112 deletions

diff --git a/doc/manual.html b/doc/manual.html
index 61a8220d7fd1..0af688b343c7 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -19,7 +19,7 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
 
 <P>
 <SMALL>
-Copyright &copy; 2020&ndash;2022 Lua.org, PUC-Rio.
+Copyright &copy; 2020&ndash;2023 Lua.org, PUC-Rio.
 Freely available under the terms of the
 <a href="http://www.lua.org/license.html">Lua license</a>.
 </SMALL>
@@ -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&nbsp;C and C++.
+the common subset of standard&nbsp;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,
@@ -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">&sect;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">&sect;3.4</a>).
+the list of variables (see <a href="#3.4.12">&sect;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
 
@@ -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">&sect;3.4.10</a>;
 table constructors are explained in <a href="#3.4.9">&sect;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">&sect;3.4.11</a>.
 
 
@@ -2074,52 +2063,6 @@ the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
 and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;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">&sect;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"&lt;1</code> raises an error
 (see <a href="#3.4.4">&sect;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">&sect;3.4.10</a>).
+(see <a href="#3.4.12">&sect;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">&sect;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">&sect;3.4.12</a>).
 
 
 <p>
@@ -2803,6 +2741,122 @@ is syntactic sugar for
 
 
 
+<h3>3.4.12 &ndash; <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">&sect;3.3.4</a>).</li>
+
+<li>A table constructor,
+for instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">&sect;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">&sect;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">&sect;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">&sect;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">&sect;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">&sect;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 &ndash; <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&nbsp;C ensures
+Note that ISO&nbsp;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&nbsp;5.4.3.)
+
+
+
+
+
+<hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p>
+<span class="apii">[-0, +?, &ndash;]</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&nbsp;5.4.6.)
 
 
 
@@ -4542,7 +4625,7 @@ Pops a key from the stack,
 and pushes a key&ndash;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&nbsp;0 and pushes nothing.
 
 
 <p>
@@ -4985,6 +5068,7 @@ Also returns&nbsp;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&nbsp;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>.
 
 
 
@@ -6033,7 +6112,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&nbsp;functions).
 </li>
 
@@ -6773,7 +6852,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 +7047,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">&sect;4.4.1</a>).
+It returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
+or 1 in case of errors.
 
 
 
@@ -6986,8 +7065,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">&sect;4.4.1</a>).
+It returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
+or 1 in case of errors.
 
 
 
@@ -7294,7 +7373,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&nbsp;C allocation functions
+allocator based on the ISO&nbsp;C allocation functions
 and then sets a warning function and a panic function (see <a href="#4.4">&sect;4.4</a>)
 that print messages to the standard error output.
 
@@ -7685,9 +7764,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 +8785,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">&sect;4.3</a>),
+indexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string.
 
 
 
@@ -8745,7 +8824,7 @@ including if necessary a path and an extension.
 
 
 <p>
-This function is not supported by Standard&nbsp;C.
+This functionality is not supported by ISO&nbsp;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 +8878,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">&sect;4.3</a>),
+indexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string.
 
 
 
@@ -9311,7 +9392,7 @@ according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;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">&sect;6.4.2</a>).
@@ -10091,9 +10172,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 +11034,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>).
 
 
 
@@ -11503,12 +11584,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&nbsp;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>
@@ -11582,7 +11669,7 @@ If there is a script,
 the script is called with arguments
 <code>arg[1]</code>, &middot;&middot;&middot;, <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>
@@ -11949,10 +12036,10 @@ and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
 
 <P CLASS="footer">
 Last update:
-Thu Jan 13 11:33:16 UTC 2022
+Tue May  2 20:09:38 UTC 2023
 </P>
 <!--
-Last change: revised for Lua 5.4.4
+Last change: revised for Lua 5.4.6
 -->
 
 </body></html>