+
Lua 5.3 Reference Manual
+
Lua 5.3 Reference Manual
The reference manual is the official definition of the Lua language.
+
For a complete introduction to Lua programming, see the book
Programming in Lua.
-
+
+ +Copyright © 2015 Lua.org, PUC-Rio. Freely available under the terms of the @@ -39,7 +38,7 @@
Lua functions
basic environment
+ |
+
Lua 5.3 Reference Manual
-by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes -
- + +
+ Copyright © 2015 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. - -
+ -contents +
- + @@ -113,15 +115,15 @@ nil, boolean, number, string, function, userdata, thread, and table. -Nil is the type of the value nil, +The type nil has one single value, nil, whose main property is to be different from any other value; it usually represents the absence of a useful value. -Boolean is the type of the values false and true. +The type boolean has two values, false and true. Both nil and false make a condition false; any other value makes it true. -Number represents both +The type number represents both integer numbers and real (floating-point) numbers. -String represents immutable sequences of bytes. +The type string represents immutable sequences of bytes. Lua is 8-bit clean: strings can contain any 8-bit value, @@ -132,6 +134,7 @@
The type number uses two internal representations,
+or two subtypes,
one called integer and the other called float.
Lua has explicit rules about when each representation is used,
but it also converts between them automatically as needed (see §3.4.3).
@@ -142,7 +145,7 @@
Standard Lua uses 64-bit integers and double-precision (64-bit) floats,
but you can also compile Lua so that it
uses 32-bit integers and/or single-precision (32-bit) floats.
-The option with 32 bits for both integers and floats
+The option with 32 bits for both integers and floats
is particularly attractive
for small machines and embedded systems.
(See macro LUA_32BITS in file luaconf.h.)
@@ -185,8 +188,8 @@
The type table implements associative arrays,
that is, arrays that can be indexed not only with numbers,
but with any Lua value except nil and NaN.
-(Not a Number is a special numeric value used to represent
-undefined or unrepresentable results, such as 0/0.)
+(Not a Number is a special value used to represent
+undefined or unrepresentable numerical results, such as 0/0.)
Tables can be heterogeneous;
that is, they can contain values of all types (except nil).
Any key with value nil is not considered part of the table.
@@ -393,7 +396,7 @@
You can replace the metatable of tables
using the setmetatable function.
-You cannot change the metatable of other types from Lua
+You cannot change the metatable of other types from Lua code
(except by using the debug library (§6.10));
you must use the C API for that.
@@ -425,12 +428,7 @@
string "__add".
Note that queries for metamethods are always raw;
the access to a metamethod does not invoke other metamethods.
-You can emulate how Lua queries a metamethod for an object obj
-with the following code:
-
- rawget(getmetatable(obj) or {}, "__" .. event_name)
-
For the unary operators (negation, length, and bitwise not),
@@ -510,7 +508,7 @@
Behavior similar to the "add" operation,
except that Lua will try a metamethod
-if any operator is neither an integer
+if any operand is neither an integer
nor a value coercible to an integer (see §3.4.3).
@@ -549,7 +547,7 @@
Behavior similar to the "add" operation,
except that Lua will try a metamethod
-if any operator is neither a string nor a number
+if any operand is neither a string nor a number
(which is always coercible to a string).
@@ -599,6 +597,8 @@
assuming that a <= b is equivalent to not (b < a).
As with the other comparison operators,
the result is always a boolean.
+(This use of the "__lt" event can be removed in future versions;
+it is also slower than a real "__le" metamethod.)
+It is a good practice to add all needed metamethods to a table
+before setting it as a metatable of some object.
+In particular, the "__gc" metamethod works only when this order
+is followed (see §2.5.1).
+
+
@@ -752,8 +759,6 @@
Note that if you set a metatable without a __gc field
and later create that field in the metatable,
the object will not be marked for finalization.
-However, after an object has been marked,
-you can freely change the __gc field of its metatable.
@@ -794,7 +799,7 @@ its finalizer will be called again in the next cycle where the object is unreachable. In any case, -the object memory is freed only in the GC cycle where +the object memory is freed only in a GC cycle where the object is unreachable and not marked for finalization. @@ -822,8 +827,8 @@
A weak table can have weak keys, weak values, or both.
-A table with weak keys allows the collection of its keys,
-but prevents the collection of its values.
+A table with weak values allows the collection of its values,
+but prevents the collection of its keys.
A table with both weak keys and weak values allows the collection of
both keys and values.
In any case, if either the key or the value is collected,
@@ -913,10 +918,10 @@
When you first call coroutine.resume,
passing as its first argument
a thread returned by coroutine.create,
-the coroutine starts its execution,
-at the first line of its main function.
+the coroutine starts its execution by
+calling its main function.
Extra arguments passed to coroutine.resume are passed
-as arguments to the coroutine's main function.
+as arguments to that function.
After the coroutine starts running,
it runs until it terminates or yields.
@@ -1111,7 +1116,7 @@
Strings in Lua can contain any 8-bit value, including embedded zeros,
which can be specified as '\0'.
More generally,
-we can specify any byte in a literal string by its numerical value.
+we can specify any byte in a literal string by its numeric value.
This can be done
with the escape sequence \xXX,
where XX is a sequence of exactly two hexadecimal digits,
@@ -1186,7 +1191,7 @@
-A numerical constant (or numeral)
+A numeric constant (or numeral)
can be written with an optional fractional part
and an optional decimal exponent,
marked by a letter 'e' or 'E'.
@@ -1581,11 +1586,11 @@
The for statement has two forms: -one numeric and one generic. +one numerical and one generic.
-The numeric for loop repeats a block of code while a +The numerical for loop repeats a block of code while a control variable runs through an arithmetic progression. It has the following syntax: @@ -1879,13 +1884,13 @@
Floor division (//) is a division
-that rounds the quotient towards minus infinite,
+that rounds the quotient towards minus infinity,
that is, the floor of the division of its operands.
Modulo is defined as the remainder of a division -that rounds the quotient towards minus infinite (floor division). +that rounds the quotient towards minus infinity (floor division).
@@ -1972,8 +1977,9 @@ First, the string is converted to an integer or a float, following its syntax and the rules of the Lua lexer. (The string may have also leading and trailing spaces and a sign.) -Then, the resulting number is converted to the required type -(float or integer) according to the previous rules. +Then, the resulting number (float or integer) +is converted to the type (float or integer) required by the context +(e.g., the operation that forced the conversion).
@@ -2006,11 +2012,7 @@ If the types are different, then the result is false. Otherwise, the values of the operands are compared. Strings are compared in the obvious way. -Numbers follow the usual rule for binary operations: -if both operands are integers, -they are compared as integers; -otherwise, they are converted to floats -and compared as such. +Numbers are equal if they denote the same mathematical value.
@@ -2045,8 +2047,8 @@
The order operators work as follows.
If both arguments are numbers,
-then they are compared following
-the usual rule for binary operations.
+then they are compared according to their mathematical values
+(regardless of their subtypes).
Otherwise, if both arguments are strings,
then their values are compared according to the current locale.
Otherwise, Lua tries to call the "lt" or the "le"
@@ -2055,6 +2057,12 @@
and a >= b is translated to b <= a.
+
+Following the IEEE 754 standard, +NaN is considered neither smaller than, +nor equal to, nor greater than any value (including itself). + + @@ -2636,29 +2644,22 @@
A valid index is an index that refers to a
-real position within the stack, that is,
-its position lies between 1 and the stack top
-(1 ≤ abs(index) ≤ top).
-
-Usually, functions that can modify the value at an index
-require valid indices.
-
-
-
-Unless otherwise noted,
-any function that accepts valid indices also accepts pseudo-indices,
-which represent some Lua values that are accessible to C code
-but which are not in the stack.
-Pseudo-indices are used to access the registry
+position that stores a modifiable Lua value.
+It comprises stack indices between 1 and the stack top
+(1 ≤ abs(index) ≤ top)
+
+plus pseudo-indices,
+which represent some positions that are accessible to C code
+but that are not in the stack.
+Pseudo-indices are used to access the registry (see §4.5)
and the upvalues of a C function (see §4.4).
-Functions that do not need a specific stack position,
-but only a value in the stack (e.g., query functions),
+Functions that do not need a specific mutable position,
+but only a value (e.g., query functions),
can be called with acceptable indices.
An acceptable index can be any valid index,
-including the pseudo-indices,
but it also can be any positive index after the stack top
within the space allocated for the stack,
that is, indices up to the stack size.
@@ -2701,7 +2702,7 @@
its upvalues are located at specific pseudo-indices.
These pseudo-indices are produced by the macro
lua_upvalueindex.
-The first value associated with a function is at position
+The first upvalue associated with a function is at index
lua_upvalueindex(1), and so on.
Any access to lua_upvalueindex(n),
where n is greater than the number of upvalues of the
@@ -2719,8 +2720,7 @@
a predefined table that can be used by any C code to
store whatever Lua values it needs to store.
The registry table is always located at pseudo-index
-LUA_REGISTRYINDEX,
-which is a valid index.
+LUA_REGISTRYINDEX.
Any C library can store data into this table,
but it must take care to choose keys
that are different from those used
@@ -2981,7 +2981,8 @@
int lua_absindex (lua_State *L, int idx);
-Converts the acceptable index idx into an absolute index
+Converts the acceptable index idx
+into an equivalent absolute index
(that is, one that does not depend on the stack top).
@@ -3224,7 +3225,7 @@
As an example, the following function receives a variable number -of numerical arguments and returns their average and their sum: +of numeric arguments and returns their average and their sum:
static int foo (lua_State *L) {
@@ -3383,8 +3384,9 @@
If strip is true,
-the binary representation is created without debug information
-about the function.
+the binary representation may not include all debug information
+about the function,
+to save space.
@@ -3661,7 +3663,7 @@
(usually a 64-bit two-complement integer),
but that can be changed to long or int
(usually a 32-bit two-complement integer).
-(See LUA_INT in luaconf.h.)
+(See LUA_INT_TYPE in luaconf.h.)
@@ -3850,7 +3852,7 @@
The type for continuation-function contexts.
-It must be a numerical type.
+It must be a numeric type.
This type is defined as intptr_t
when intptr_t is available,
so that it can store pointers too.
@@ -4068,7 +4070,7 @@
lua_Number
-typedef double lua_Number;
+typedef ... lua_Number;
The type of floats in Lua.
@@ -4076,8 +4078,8 @@
By default this type is double,
-but that can be changed to a single float.
-(See LUA_REAL in luaconf.h.)
+but that can be changed to a single float or a long double.
+(See LUA_FLOAT_TYPE in luaconf.h.)
@@ -4133,7 +4135,7 @@
is exactly the original error message.
Otherwise, msgh is the stack index of a
message handler.
-(In the current implementation, this index cannot be a pseudo-index.)
+(This index cannot be a pseudo-index.)
In case of runtime errors,
this function will be called with the error message
and its return value will be the message
@@ -4267,20 +4269,11 @@
-Any function to be registered in Lua must
+Any function to be callable by Lua must
follow the correct protocol to receive its parameters
and return its results (see lua_CFunction).
-
-lua_pushcfunction is defined as a macro:
-
-
- #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
-
-Note that f is used twice.
-
-
@@ -4309,7 +4302,7 @@
'%%' (inserts the character '%'),
'%s' (inserts a zero-terminated string, with no size restrictions),
'%f' (inserts a lua_Number),
-'%L' (inserts a lua_Integer),
+'%I' (inserts a lua_Integer),
'%p' (inserts a pointer as a hexadecimal numeral),
'%d' (inserts an int),
'%c' (inserts an int as a one-byte character), and
@@ -4369,9 +4362,8 @@
const char *lua_pushliteral (lua_State *L, const char *s);
-This macro is equivalent to lua_pushlstring,
-but can be used only when s is a literal string.
-It automatically provides the string length.
+This macro is equivalent to lua_pushstring,
+but should be used only when s is a literal string.
@@ -4598,9 +4590,9 @@
void lua_rawsetp (lua_State *L, int index, const void *p);
-Does the equivalent of t[k] = v,
+Does the equivalent of t[p] = v,
where t is the table at the given index,
-k is the pointer p represented as a light userdata,
+p is encoded as a light userdata,
and v is the value at the top of the stack.
@@ -4672,7 +4664,7 @@
Moves the top element into the given valid index
without shifting any element
-(therefore replacing the value at the given index),
+(therefore replacing the value at that given index),
and then pops the top element.
@@ -4684,7 +4676,7 @@
int lua_resume (lua_State *L, lua_State *from, int nargs);
-Starts and resumes a coroutine in a given thread.
+Starts and resumes a coroutine in the given thread L.
@@ -4731,12 +4723,16 @@
void lua_rotate (lua_State *L, int idx, int n);
-Rotates the stack elements from idx to the top n positions
-in the direction of the top, for a positive n,
+Rotates the stack elements between the valid index idx
+and the top of the stack.
+The elements are rotated n positions in the direction of the top,
+for a positive n,
or -n positions in the direction of the bottom,
for a negative n.
The absolute value of n must not be greater than the size
of the slice being rotated.
+This function cannot be called with a pseudo-index,
+because a pseudo-index is not an actual stack position.
@@ -5072,7 +5068,7 @@
-Typically this function is used only for debug information.
+Typically this function is used only for hashing and debug information.
@@ -5127,7 +5123,7 @@
or LUA_TNONE for a non-valid (but acceptable) index.
The types returned by lua_type are coded by the following constants
defined in lua.h:
-LUA_TNIL,
+LUA_TNIL (0),
LUA_TNUMBER,
LUA_TBOOLEAN,
LUA_TSTRING,
@@ -5618,24 +5614,26 @@
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
-Gets information about a closure's upvalue.
-(For Lua functions,
-upvalues are the external local variables that the function uses,
-and that are consequently included in its closure.)
-lua_getupvalue gets the index n of an upvalue,
-pushes the upvalue's value onto the stack,
+Gets information about the n-th upvalue
+of the closure at index funcindex.
+It pushes the upvalue's value onto the stack
and returns its name.
-funcindex points to the closure in the stack.
-(Upvalues have no particular order,
-as they are active through the whole function.
-So, they are numbered in an arbitrary order.)
+Returns NULL (and pushes nothing)
+when the index n is greater than the number of upvalues.
-Returns NULL (and pushes nothing)
-when the index is greater than the number of upvalues.
For C functions, this function uses the empty string ""
as a name for all upvalues.
+(For Lua functions,
+upvalues are the external local variables that the function uses,
+and that are consequently included in its closure.)
+
+
+
+Upvalues have no particular order,
+as they are active through the whole function.
+They are numbered in an arbitrary order.
@@ -5680,10 +5678,10 @@
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 lua_yield with nresults equal to zero.
+Only count and line events can yield;
+to yield, a hook function must finish its execution
+calling lua_yield with nresults equal to zero
+(that is, with no values).
@@ -5748,9 +5746,7 @@
Sets the value of a local variable of a given activation record.
-Parameters ar and n are as in lua_getlocal
-(see lua_getlocal).
-lua_setlocal assigns the value at the top of the stack
+It assigns the value at the top of the stack
to the variable and returns its name.
It also pops the value from the stack.
@@ -5761,6 +5757,10 @@
the number of active local variables.
+
+Parameters ar and n are as in function lua_getlocal.
+
+
@@ -5773,13 +5773,15 @@
It assigns the value at the top of the stack
to the upvalue and returns its name.
It also pops the value from the stack.
-Parameters funcindex and n are as in the lua_getupvalue
-(see lua_getupvalue).
Returns NULL (and pops nothing)
-when the index is greater than the number of upvalues.
+when the index n is greater than the number of upvalues.
+
+
+
+Parameters funcindex and n are as in function lua_getupvalue.
@@ -5792,9 +5794,6 @@
Returns a unique identifier for the upvalue numbered n
from the closure at index funcindex.
-Parameters funcindex and n are as in the lua_getupvalue
-(see lua_getupvalue)
-(but n cannot be greater than the number of upvalues).
@@ -5805,6 +5804,11 @@
will return identical ids for those upvalue indices.
+
+Parameters funcindex and n are as in function lua_getupvalue,
+but n cannot be greater than the number of upvalues.
+
+
@@ -6367,9 +6371,9 @@
Pushes onto the stack the metatable associated with name tname
-in the registry (see luaL_newmetatable).
-If there is no metatable associated with tname,
-returns false and pushes nil.
+in the registry (see luaL_newmetatable)
+(nil if there is no metatable associated with that name).
+Returns the type of the pushed value.
@@ -7333,7 +7337,7 @@
The order in which the indices are enumerated is not specified,
even for numeric indices.
-(To traverse a table in numeric order,
+(To traverse a table in numerical order,
use a numerical for.)
@@ -7522,8 +7526,6 @@
tostring (v)
Receives a value of any type and
converts it to a string in a human-readable format.
-Floats always produce strings with some
-floating-point indication (either a decimal dot or an exponent).
(For complete control of how numbers are converted,
use string.format.)
@@ -7579,8 +7581,8 @@
6.2 – Coroutine Manipulation
-The operations related to coroutines comprise a sub-library of
-the basic library and come inside the table coroutine.
+This library comprises the operations to manipulate coroutines,
+which come inside the table coroutine.
See §2.6 for a general description of coroutines.
@@ -7590,7 +7592,7 @@
Creates a new coroutine, with body f.
-f must be a Lua function.
+f must be a function.
Returns this new coroutine,
an object with type "thread".
@@ -7674,7 +7676,7 @@
Creates a new coroutine, with body f.
-f must be a Lua function.
+f must be a function.
Returns a function that resumes the coroutine each time it is called.
Any arguments passed to the function behave as the
extra arguments to resume.
@@ -8073,7 +8075,7 @@
string.byte (s [, i [, j]])
-Returns the internal numerical codes of the characters s[i],
+Returns the internal numeric codes of the characters s[i],
s[i+1], ..., s[j].
The default value for i is 1;
the default value for j is i.
@@ -8082,7 +8084,7 @@
-Numerical codes are not necessarily portable across platforms.
+Numeric codes are not necessarily portable across platforms.
@@ -8091,12 +8093,12 @@
string.char (···)
Receives zero or more integers.
Returns a string with length equal to the number of arguments,
-in which each character has the internal numerical code equal
+in which each character has the internal numeric code equal
to its corresponding argument.
-Numerical codes are not necessarily portable across platforms.
+Numeric codes are not necessarily portable across platforms.
@@ -8112,9 +8114,9 @@
so that a later load on this string returns
a copy of the function (but with new upvalues).
If strip is a true value,
-the binary representation is created without debug information
-about the function
-(local variable names, lines, etc.).
+the binary representation may not include all debug information
+about the function,
+to save space.
@@ -8138,7 +8140,7 @@
If it finds a match, then find returns the indices of s
where this occurrence starts and ends;
otherwise, it returns nil.
-A third, optional numerical argument init specifies
+A third, optional numeric argument init specifies
where to start the search;
its default value is 1 and can be negative.
A value of true as a fourth, optional argument plain
@@ -8186,18 +8188,23 @@
Options
-A and a (when available),
-E, e, f,
+A, a, E, e, f,
G, and g all expect a number as argument.
Options c, d,
i, o, u, X, and x
expect an integer.
-Option q expects a string;
-option s expects a string without embedded zeros.
-If the argument to option s is not a string,
+Option q expects a string.
+Option s expects a string without embedded zeros;
+if its argument is not a string,
it is converted to one following the same rules of tostring.
+
+When Lua is compiled with a non-C99 compiler,
+options A and a (hexadecimal floats)
+do not support any modifier (flags, width, length).
+
+
@@ -8344,7 +8351,7 @@
otherwise it returns nil.
If pattern specifies no captures,
then the whole match is returned.
-A third, optional numerical argument init specifies
+A third, optional numeric argument init specifies
where to start the search;
its default value is 1 and can be negative.
@@ -8499,7 +8506,7 @@
represents the character x.
This is the standard way to escape the magic characters.
Any non-alphanumeric character
-(including all punctuations, even the non-magical)
+(including all punctuation characters, even the non-magical)
can be preceded by a '%'
when used to represent itself in a pattern.
a2[t],··· = a1[f],···,a1[e].
The default for a2 is a1.
The destination range can overlap with the source range.
-Index f must be positive.
+The number of elements to be moved must fit in a Lua integer.
@@ -9120,7 +9127,7 @@
The float value HUGE_VAL,
-a value larger than any other numerical value.
+a value larger than any other numeric value.
@@ -9602,16 +9609,12 @@
following the lexical conventions of Lua.
(The numeral may have leading spaces and a sign.)
This format always reads the longest input sequence that
-is a valid prefix for a number;
-if that prefix does not form a valid number
+is a valid prefix for a numeral;
+if that prefix does not form a valid numeral
(e.g., an empty string, "0x", or "3.4e-"),
it is discarded and the function returns nil.
-
i":
-reads an integral number and returns it as an integer.
-a":
reads the whole file, starting at the current position.
On end of file, it returns the empty string.
@@ -9946,17 +9949,26 @@
Returns the current time when called without arguments,
-or a time representing the date and time specified by the given table.
+or a time representing the local date and time specified by the given table.
This table must have fields year, month, and day,
and may have fields
hour (default is 12),
min (default is 0),
sec (default is 0),
and isdst (default is nil).
+Other fields are ignored.
For a description of these fields, see the os.date function.
+The values in these fields do not need to be inside their valid ranges.
+For instance, if sec is -10,
+it means -10 seconds from the time specified by the other fields;
+if hour is 1000,
+it means +1000 hours from the time specified by the other fields.
+
+
+
The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other systems, this number counts the number @@ -10093,7 +10105,7 @@
For instance, the expression debug.getinfo(1,"n").name returns
-a table with a name for the current function,
+a name for the current function,
if a reasonable name can be found,
and the expression debug.getinfo(print)
returns a table with all available information
@@ -10599,7 +10611,8 @@
It is easy to require a compatible external library or,
better yet, to replace its functions with appropriate bitwise operations.
(Keep in mind that bit32 operates on 32-bit integers,
-while the bitwise operators in standard Lua operate on 64-bit integers.)
+while the bitwise operators in Lua 5.3 operate on Lua integers,
+which by default have 64 bits.)
io.read do not have a starting '*' anymore.
-For compatibility, Lua will continue to ignore this character.
+For compatibility, Lua will continue to accept (and ignore) this character.
collectgarbage("count") now returns only one result.
+(You can compute that second result from the fractional part
+of the first result.)
+