+
Lua 5.4 Reference Manual
+
Lua 5.4 Reference Manual
-Copyright © 2020–2022 Lua.org, PUC-Rio. +Copyright © 2020–2024 Lua.org, PUC-Rio. Freely available under the terms of the -Lua license. +Lua license.
+
Lua 5.4 Reference Manual
-Copyright © 2020–2022 Lua.org, PUC-Rio. +Copyright © 2020–2024 Lua.org, PUC-Rio. Freely available under the terms of the -Lua license. +Lua license.
@@ -63,7 +63,7 @@ and rapid prototyping.
Lua is implemented as a library, written in clean C,
-the common subset of Standard C and C++.
+the common subset of standard C and C++.
The Lua distribution includes a host program called lua,
which uses the Lua library to offer a complete,
standalone Lua interpreter,
@@ -391,7 +391,7 @@ Whenever there is an error,
an error object
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.
When you use xpcall (or lua_pcall, in C)
-you may give a message handler
+you can give a message handler
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 metamethod.
In the previous example, the key is the string "__add"
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 __call metamethod.
@@ -1379,7 +1379,9 @@ Lua also accepts hexadecimal constants,
which start with 0x or 0X.
Hexadecimal constants also accept an optional fractional part
plus an optional binary exponent,
-marked by a letter 'p' or 'P'.
+marked by a letter 'p' or 'P' and written in decimal.
+(For instance, 0x1.fp10 denotes 1984,
+which is 0x1f / 16 multiplied by 210.)
@@ -1621,21 +1623,13 @@ Expressions are discussed in §3.4.
Before the assignment, the list of values is adjusted 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 nil'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 §3.4). +the list of variables (see §3.4.12).
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,18 +1725,13 @@ labels in Lua are considered statements too:
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, even if this other label has been declared in an enclosing block. -
-Labels and empty statements are called void statements, -as they perform no actions. - -
The break statement terminates the execution of a
while, repeat, or for loop,
@@ -2059,7 +2048,7 @@ function calls are explained in §3.4.10;
table constructors are explained in §3.4.9.
Vararg expressions,
denoted by three dots ('...'), can only be used when
-directly inside a vararg function;
+directly inside a variadic function;
they are explained in §3.4.11.
@@ -2074,52 +2063,6 @@ the unary logical not (see §3.4.5),
and the unary length operator (see §3.4.7).
-
-Both function calls and vararg expressions can result in multiple values. -If a function call is used as a statement (see §3.3.6), -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 nil if there are no values. - - -
-Here are some examples: - -
- 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
-
-
-
-Any expression enclosed in parentheses always results in only one value.
-Thus,
-(f(x,y,z)) is always a single value,
-even if f returns several values.
-(The value of (f(x,y,z)) is the first value returned by f
-or nil if f does not return any values.)
-
-
@@ -2252,8 +2195,9 @@ Note that bitwise operators do not do this coercion.
-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, "1"==1 is false and "1"<1 raises an error
(see §3.4.4).
These coercions exist mainly for compatibility and may be removed
@@ -2558,9 +2502,9 @@ The order of the assignments in a constructor is undefined.
If the last field in the list has the form exp
-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 §3.4.10).
+(see §3.4.12).
@@ -2624,7 +2568,7 @@ A call of the form return functioncall not in the
scope of a to-be-closed variable is called a tail call.
Lua implements proper tail calls
(or proper tail recursion):
-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:
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 vararg function,
+the length of its list of parameters (see §3.4.12),
+unless the function is a variadic function,
which is indicated by three dots ('...')
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 vararg expression,
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 §3.4.12).
@@ -2803,6 +2741,122 @@ is syntactic sugar for +
+Both function calls and vararg expressions can result in multiple values. +These expressions are called multires expressions. + + +
+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. + + +
+These are the places where Lua expects a list of expressions: + +
return e1, e2, e3 (see §3.3.4).{e1, e2, e3} (see §3.4.9).foo(e1, e2, e3) (see §3.4.10).a , b, c = e1, e2, e3 (see §3.3.3).local a , b, c = e1, e2, e3 (see §3.3.7).for k in e1, e2, e3 do ... end (see §3.3.5).+In the last four cases, +the list of values from the list of expressions +must be adjusted to a specific length: +the number of parameters in a call to a non-variadic function +(see §3.4.11), +the number of variables in a multiple assignment or +a local declaration, +and exactly four values for a generic for loop. +The adjustment 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 nil's. +When the list of expressions ends with a multires expression, +all results from that expression enter the list of values +before the adjustment. + + +
+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. + + +
+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. + + +
+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 nil. + +
+ 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.
+
+
+
+
+
@@ -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 luaL_newst
return realloc(ptr, nsize);
}
-Note that Standard C ensures
+Note that ISO C ensures
that free(NULL) has no effect and that
realloc(NULL,size) is equivalent to malloc(size).
@@ -3785,8 +3840,36 @@ when called through this function.
-(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.) + + + + + +
lua_closethread+[-0, +?, –] +
int lua_closethread (lua_State *L, lua_State *from);+ +
+Resets a thread, cleaning its call stack and closing all pending
+to-be-closed variables.
+Returns a status code:
+LUA_OK 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.
+
+
+
+The parameter from represents the coroutine that is resetting L.
+If there is no such coroutine,
+this parameter can be NULL.
+
+
+
+(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 lua_next returns 0 and pushes nothing.
+then lua_next returns 0 and pushes nothing.
@@ -4985,6 +5068,7 @@ Also returns 0 if any of the indices are not valid.
Similar to lua_gettable, but does a raw access
(i.e., without metamethods).
+The value at index must be a table.
@@ -5051,6 +5135,7 @@ For other values, this call returns 0.
Similar to lua_settable, but does a raw assignment
(i.e., without metamethods).
+The value at index must be a table.
@@ -5166,15 +5251,9 @@ and then pops the top element.
int lua_resetthread (lua_State *L);
-Resets a thread, cleaning its call stack and closing all pending
-to-be-closed variables.
-Returns a status code:
-LUA_OK 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 lua_closethread with
+from being NULL.
@@ -5492,7 +5571,7 @@ otherwise, returns NULL.
lua_toclose-[-0, +0, m] +[-0, +0, v]
void lua_toclose (lua_State *L, int index);
@@ -5512,6 +5591,11 @@ by any other function in the API except lua_settop.
+lua_closeslot
+This function raises an error if the value at the given slot
+neither has a __close metamethod nor is a false value.
+
+
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. +
+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
isvararg:
-true if the function is a vararg function
+true if the function is a variadic function
(always true for C functions).
void luaL_buffsub (luaL_Buffer *B, int n);
-Removes n bytes from the the buffer B
+Removes n bytes from the buffer B
(see luaL_Buffer).
The buffer must have at least that many bytes.
@@ -6968,8 +7058,8 @@ It is defined as the following macro:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
-It returns LUA_OK if there are no errors,
-or an error code in case of errors (see §4.4.1).
+It returns 0 (LUA_OK) if there are no errors,
+or 1 in case of errors.
@@ -6986,8 +7076,8 @@ It is defined as the following macro:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
-It returns LUA_OK if there are no errors,
-or an error code in case of errors (see §4.4.1).
+It returns 0 (LUA_OK) if there are no errors,
+or 1 in case of errors.
@@ -7294,7 +7384,7 @@ with tname in the registry.
Creates a new Lua state.
It calls lua_newstate 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 §4.4)
that print messages to the standard error output.
@@ -7685,9 +7775,7 @@ to start the traceback.
luaL_typeerror[-0, +0, v] -
const char *luaL_typeerror (lua_State *L, - int arg, - const char *tname);+
int luaL_typeerror (lua_State *L, int arg, const char *tname);
Raises a type error for the argument arg
@@ -8708,6 +8796,8 @@ When you require a module modname and
This variable is only a reference to the real table;
assignments to this variable do not change the
table used by require.
+The real table is stored in the C registry (see §4.3),
+indexed by the key LUA_LOADED_TABLE, a string.
@@ -8745,7 +8835,7 @@ including if necessary a path and an extension.
-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
-Returns the size of a string resulting from
-
+
Returns the arc tangent of
If the optional second argument
@@ -11503,12 +11595,18 @@ The options are:
+(The form
After handling its options,
@@ -11582,7 +11684,7 @@ If there is a script,
the script is called with arguments
@@ -11946,13 +12048,12 @@ and LiteralString, see §3.1.)
-
dlfcn 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 require.
+The real table is stored in the C registry (see §4.3),
+indexed by the key LUA_PRELOAD_TABLE, a string.
@@ -9311,7 +9403,7 @@ according to the format string fmt (see §6.4.
string.pack
+Returns the length of a string resulting from string.pack
with the given format.
The format string cannot have the variable-length options
's' or 'z' (see §6.4.2).
@@ -10091,9 +10183,9 @@ Returns the arc sine of x (in radians).
y/x (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 x being zero.
@@ -10953,7 +11045,7 @@ The default value for code is true.
close is true,
-closes the Lua state before exiting.
+the function closes the Lua state before exiting (see lua_close).
@@ -11195,13 +11287,13 @@ The returned table can contain all the fields returned by what describing which fields to fill in.
The default for what is to get all information available,
except the table of valid lines.
-If present,
-the option 'f'
+The option 'f'
adds a field named func with the function itself.
-If present,
-the option 'L'
-adds a field named activelines with the table of
-valid lines.
+The option 'L' adds a field named activelines
+with the table of valid lines,
+provided the function is a Lua function.
+If the function has no debug information,
+the table is empty.
-i: enter interactive mode after running script;-l mod: "require" mod and assign the
result to global mod;-l g=mod: "require" mod and assign the
+ result to global g;-v: print version information;-E: ignore environment variables;-W: turn warnings on;--: stop handling options;-: execute stdin as a file and stop handling options.-l g=mod was introduced in release 5.4.4.)
+
+
+lua runs the given script.
When called without arguments,
lua behaves as lua -v -i
@@ -11532,6 +11630,10 @@ Lua does not consult any environment variables.
In particular,
the values of package.path and package.cpath
are set with the default paths defined in luaconf.h.
+To signal to the libraries that this option is on,
+the stand-alone interpreter sets the field
+"LUA_NOENV" in the registry to a true value.
+Other libraries may consult this field for the same purpose.
arg[1], ···, arg[#arg].
Like all chunks in Lua,
-the script is compiled as a vararg function.
+the script is compiled as a variadic function.