-Lua 5.4 Reference Manual
+
+Lua 5.5 Reference Manual
-Lua 5.4 Reference Manual
+
+Lua 5.5 Reference Manual
@@ -32,7 +32,7 @@
-Copyright © 2020–2024 Lua.org, PUC-Rio. +Copyright © 2020–2025 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. @@ -44,7 +44,7 @@
-basic
+basic
_G
_VERSION
assert
@@ -180,7 +179,7 @@
-coroutine
+coroutine
coroutine.close
coroutine.create
coroutine.isyieldable
@@ -191,7 +190,7 @@
-debug
+debug
debug.debug
debug.gethook
debug.getinfo
@@ -210,7 +209,7 @@
-io
+io
io.close
io.flush
io.input
@@ -238,7 +237,7 @@
-math
+math
math.abs
math.acos
math.asin
@@ -249,7 +248,9 @@
-os
+os
os.clock
os.date
os.difftime
@@ -282,7 +283,7 @@
-package
+package
package.config
package.cpath
package.loaded
@@ -293,7 +294,7 @@
-string
+string
string.byte
string.char
string.dump
@@ -313,8 +314,9 @@
-table
+table
table.concat
+table.create
table.insert
table.move
table.pack
@@ -323,7 +325,7 @@
-utf8
+utf8
utf8.char
utf8.charpattern
utf8.codepoint
@@ -366,11 +368,11 @@
LUA_CPATH
-LUA_CPATH_5_4
+LUA_CPATH_5_5
LUA_INIT
-LUA_INIT_5_4
+LUA_INIT_5_5
LUA_PATH
-LUA_PATH_5_4
+LUA_PATH_5_5
-luaopen_base
-luaopen_coroutine
-luaopen_debug
-luaopen_io
-luaopen_math
-luaopen_os
-luaopen_package
-luaopen_string
-luaopen_table
-luaopen_utf8
+LUAL_BUFFERSIZE
@@ -610,6 +607,22 @@
+LUA_COLIBK
+LUA_DBLIBK
+LUA_GLIBK
+LUA_IOLIBK
+LUA_LOADLIBK
+LUA_MATHLIBK
+LUA_OSLIBK
+LUA_STRLIBK
+LUA_TABLIBK
+LUA_UTF8LIBK
+
+
+LUA_COLIBNAME
+LUA_DBLIBNAME
+LUA_IOLIBNAME
+LUA_LOADLIBNAME
+LUA_MATHLIBNAME
+LUA_OSLIBNAME
+LUA_STRLIBNAME
+LUA_TABLIBNAME
+LUA_UTF8LIBNAME
-Lua 5.4 Reference Manual
+
+Lua 5.5 Reference Manual
@@ -19,7 +19,7 @@
-Copyright © 2020–2024 Lua.org, PUC-Rio. +Copyright © 2020–2025 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. @@ -166,7 +166,7 @@
Unless stated otherwise, any overflow when manipulating integer values wrap around, -according to the usual rules of two-complement arithmetic. +according to the usual rules of two's complement arithmetic. (In other words, the actual result is the unique representable integer that is equal modulo 2n to the mathematical result, @@ -190,7 +190,8 @@
\0').
Lua is also encoding-agnostic;
it makes no assumptions about the contents of a string.
-The length of any string in Lua must fit in a Lua integer.
+The length of any string in Lua must fit in a Lua integer,
+and the string plus a small header must fit in size_t.
@@ -295,12 +296,105 @@
+A variable name refers to a global or a local variable according +to the declaration that is in context at that point of the code. +(For the purposes of this discussion, +a function's formal parameter is equivalent to a local variable.) + + +
+All chunks start with an implicit declaration global *,
+which declares all free names as global variables;
+this preambular declaration becomes void inside the scope of any other
+global declaration,
+as the following example illustrates:
+
+
+ X = 1 -- Ok, global by default + do + global Y -- voids the implicit initial declaration + Y = 1 -- Ok, Y declared as global + X = 1 -- ERROR, X not declared + end + X = 2 -- Ok, global by default again +
+So, outside any global declaration, +Lua works as global-by-default. +Inside any global declaration, +Lua works without a default: +All variables must be declared. + + +
+Lua is a lexically scoped language. +The scope of a variable declaration begins at the first statement after +the declaration and lasts until the last non-void statement +of the innermost block that includes the declaration. +(Void statements are labels and empty statements.) + + +
+A declaration shadows any declaration for the same name that +is in context at the point of the declaration. Inside this +shadow, any outer declaration for that name is void. +See the next example: + +
+ global print, x + x = 10 -- global variable + do -- new block + local x = x -- new 'x', with value 10 + print(x) --> 10 + x = x+1 + do -- another block + local x = x+1 -- another 'x' + print(x) --> 12 + end + print(x) --> 11 + end + print(x) --> 10 (the global one) ++ +
+Notice that, in a declaration like local x = x,
+the new x being declared is not in scope yet,
+and so the x on the right-hand side refers to the outside variable.
+
+
+
+Because of the lexical scoping rules, +local variables can be freely accessed by functions +defined inside their scope. +A local variable used by an inner function is called an upvalue +(or external local variable, or simply external variable) +inside the inner function. + + +
+Notice that each execution of a local statement +defines new local variables. +Consider the following example: + +
+ a = {}
+ local x = 20
+ for i = 1, 10 do
+ local y = 0
+ a[i] = function () y = y + 1; return x + y end
+ end
+
+The loop creates ten closures
+(that is, ten instances of the anonymous function).
+Each of these closures uses a different y variable,
+while all of them share the same x.
+
As we will discuss further in §3.2 and §3.3.3,
-any reference to a free name
-(that is, a name not bound to any declaration) var
+any reference to a global variable var
is syntactically translated to _ENV.var.
Moreover, every chunk is compiled in the scope of
an external local variable named _ENV (see §3.3.2),
@@ -310,12 +404,14 @@
Despite the existence of this external _ENV variable and
the translation of free names,
-_ENV is a completely regular name.
+_ENV is a regular name.
In particular,
you can define new variables and parameters with that name.
-Each reference to a free name uses the _ENV that is
-visible at that point in the program,
-following the usual visibility rules of Lua (see §3.5).
+(However, you should not define _ENV as a global variable,
+otherwise _ENV.var would translate to
+_ENV._ENV.var and so on, in an infinite loop.)
+Each reference to a global variable name uses the _ENV that is
+visible at that point in the program.
@@ -335,8 +431,8 @@
_ENV variable
is the global environment (see load).
Therefore, by default,
-free names in Lua code refer to entries in the global environment
-and, therefore, they are also called global variables.
+global variables in Lua code refer to entries in the global environment
+and, therefore, they act as conventional global variables.
Moreover, all standard libraries are loaded in the global environment
and some functions there operate on that environment.
You can use load (or loadfile)
@@ -392,7 +488,9 @@ setmetatable function.
You cannot change the metatable of other types from Lua code,
-except by using the debug library (§6.10).
+except by using the debug library (§6.11).
@@ -477,7 +575,7 @@
@@ -490,7 +588,7 @@
__add:
+__add:
the addition (+) operation.
If any operand for an addition is not a number,
Lua will try to call a metamethod.
@@ -506,42 +604,42 @@ __sub:
+__sub:
the subtraction (-) operation.
Behavior similar to the addition operation.
__mul:
+__mul:
the multiplication (*) operation.
Behavior similar to the addition operation.
__div:
+__div:
the division (/) operation.
Behavior similar to the addition operation.
__mod:
+__mod:
the modulo (%) operation.
Behavior similar to the addition operation.
__pow:
+__pow:
the exponentiation (^) operation.
Behavior similar to the addition operation.
__unm:
+__unm:
the negation (unary -) operation.
Behavior similar to the addition operation.
__idiv:
+__idiv:
the floor division (//) operation.
Behavior similar to the addition operation.
__band:
+__band:
the bitwise AND (&) operation.
Behavior similar to the addition operation,
except that Lua will try a metamethod
@@ -549,32 +647,32 @@ __bor:
+__bor:
the bitwise OR (|) operation.
Behavior similar to the bitwise AND operation.
__bxor:
+__bxor:
the bitwise exclusive OR (binary ~) operation.
Behavior similar to the bitwise AND operation.
__bnot:
+__bnot:
the bitwise NOT (unary ~) operation.
Behavior similar to the bitwise AND operation.
__shl:
+__shl:
the bitwise left shift (<<) operation.
Behavior similar to the bitwise AND operation.
__shr:
+__shr:
the bitwise right shift (>>) operation.
Behavior similar to the bitwise AND operation.
__concat:
+__concat:
the concatenation (..) operation.
Behavior similar to the addition operation,
except that Lua will try a metamethod
@@ -582,7 +680,7 @@ __len:
+__len:
the length (#) operation.
If the object is not a string,
Lua will try its metamethod.
@@ -596,7 +694,7 @@ __eq:
+__eq:
the equal (==) operation.
Behavior similar to the addition operation,
except that Lua will try a metamethod only when the values
@@ -605,7 +703,7 @@ __lt:
+__lt:
the less than (<) operation.
Behavior similar to the addition operation,
except that Lua will try a metamethod only when the values
@@ -613,12 +711,12 @@ __le:
+__le:
the less equal (<=) operation.
Behavior similar to the less than operation.
__index:
+__index:
The indexing access operation table[key].
This event happens when table is not a table or
when key is not present in table.
@@ -639,7 +737,7 @@ __index metavalue.
__newindex:
+__newindex:
The indexing assignment table[key] = value.
Like the index event,
this event happens when table is not a table or
@@ -668,7 +766,7 @@ __call:
+__call:
The call operation func(args).
This event happens when Lua tries to call a non-function value
(that is, func is not a function).
@@ -746,8 +844,8 @@ @@ -781,8 +880,8 @@
lua_gc in C
or collectgarbage in Lua.
-You can also use these functions to control
-the collector directly (e.g., to stop and restart it).
+You can also use these functions to control the collector directly,
+for instance to stop or restart it.
@@ -804,43 +903,36 @@ The garbage-collector pause controls how long the collector waits before starting a new cycle. -The collector starts a new cycle when the use of memory -hits n% of the use after the previous collection. +The collector starts a new cycle when the number of bytes +hits n% of the total after the previous collection. Larger values make the collector less aggressive. Values equal to or less than 100 mean the collector will not wait to start a new cycle. -A value of 200 means that the collector waits for the total memory in use -to double before starting a new cycle. -The default value is 200; the maximum value is 1000. - - -
-The garbage-collector step multiplier -controls the speed of the collector relative to -memory allocation, -that is, -how many elements it marks or sweeps for each -kilobyte of memory allocated. -Larger values make the collector more aggressive but also increase -the size of each incremental step. -You should not use values less than 100, -because they make the collector too slow and -can result in the collector never finishing a cycle. -The default value is 100; the maximum value is 1000. +A value of 200 means that the collector waits for +the total number of bytes to double before starting a new cycle.
The garbage-collector step size controls the size of each incremental step, specifically how many bytes the interpreter allocates -before performing a step. -This parameter is logarithmic: -A value of n means the interpreter will allocate 2n -bytes between steps and perform equivalent work during the step. -A large value (e.g., 60) makes the collector a stop-the-world -(non-incremental) collector. -The default value is 13, -which means steps of approximately 8 Kbytes. +before performing a step: +A value of n means the interpreter will allocate +approximately n bytes between steps. + + +
+The garbage-collector step multiplier +controls how much work each incremental step does. +A value of n means the interpreter will execute +n% units of work for each word allocated. +A unit of work corresponds roughly to traversing one slot +or sweeping one object. +Larger values make the collector more aggressive. +Beware that values too small can +make the collector too slow to ever finish a cycle. +As a special case, a zero value means unlimited work, +effectively producing a non-incremental, stop-the-world collector. @@ -852,35 +944,53 @@
+The generational mode uses three parameters: +the minor multiplier, the minor-major multiplier, +and the major-minor multiplier.
The minor multiplier controls the frequency of minor collections. For a minor multiplier x, -a new minor collection will be done when memory -grows x% larger than the memory in use after the previous major -collection. +a new minor collection will be done when the number of bytes +grows x% larger than the number in use just +after the last major collection. For instance, for a multiplier of 20, -the collector will do a minor collection when the use of memory -gets 20% larger than the use after the previous major collection. -The default value is 20; the maximum value is 200. +the collector will do a minor collection when the number of bytes +gets 20% larger than the total after the last major collection.
-The major multiplier controls the frequency of major collections. -For a major multiplier x, -a new major collection will be done when memory -grows x% larger than the memory in use after the previous major -collection. +The minor-major multiplier controls the shift to major collections. +For a multiplier x, +the collector will shift to a major collection +when the number of bytes from old objects grows x% larger +than the total after the previous major collection. For instance, for a multiplier of 100, -the collector will do a major collection when the use of memory -gets larger than twice the use after the previous collection. -The default value is 100; the maximum value is 1000. +the collector will do a major collection when the number of old bytes +gets larger than twice the total after the previous major collection. +As a special case, +a value of 0 stops the collector from doing major collections. + + +
+The major-minor multiplier controls the shift back to minor collections. +For a multiplier x, +the collector will shift back to minor collections +after a major collection collects at least x% +of the bytes allocated during the last cycle. +In particular, for a multiplier of 0, +the collector will immediately shift back to minor collections +after doing one major collection. @@ -1239,9 +1349,9 @@
and break do else elseif end
- false for function goto if in
- local nil not or repeat return
- then true until while
+ false for function global goto if
+ in local nil not or repeat
+ return then true until while
@@ -1435,7 +1545,7 @@
A single name can denote a global variable or a local variable (or a function's formal parameter, -which is a particular kind of local variable): +which is a particular kind of local variable) (see §2.2):
var ::= Name @@ -1444,11 +1554,9 @@3.2 – Variables
-Any variable name is assumed to be global unless explicitly declared -as a local (see §3.3.7). -Local variables are lexically scoped: +Because variables are lexically scoped, local variables can be freely accessed by functions -defined inside their scope (see §3.5). +defined inside their scope (see §2.2).
@@ -1476,8 +1584,6 @@
3.2 – Variables
An access to a global variable
xis equivalent to_ENV.x. -Due to the way that chunks are compiled, -the variable_ENVitself is never global (see §2.2). @@ -1598,6 +1704,8 @@3.3.2 – Chunks
see the programluacand the functionstring.dumpfor details. Programs in source and compiled forms are interchangeable; Lua automatically detects the file type and acts accordingly (seeload). +Be aware that, unlike source code, +maliciously crafted binary chunks can crash the interpreter. @@ -1726,9 +1834,9 @@3.3.4 – Control Structures
A label is visible in the entire block where it is defined, except inside nested functions. A goto can jump to any visible label as long as it does not -enter into the scope of a local variable. +enter into the scope of a variable declaration. A label should not be declared -where a label with the same name is visible, +where a previous label with the same name is visible, even if this other label has been declared in an enclosing block. @@ -1788,7 +1896,8 @@
The numerical for loop
stat ::= for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end
The given identifier (Name) defines the control variable,
-which is a new variable local to the loop body (block).
+which is a new read-only (const) variable local to the loop body
+(block).
@@ -1829,13 +1938,6 @@
-You should not change the value of the control variable -during the loop. -If you need its value after the loop, -assign it to another variable before exiting the loop. - - @@ -1862,7 +1964,8 @@
The names var_i declare loop variables local to the loop body.
-The first of these variables is the control variable.
+The first of these variables is the control variable,
+which is a read-only (const) variable.
@@ -1893,11 +1996,6 @@
-You should not change the value of the control variable -during the loop. - - @@ -1917,41 +2015,102 @@
-
-Local variables can be declared anywhere inside a block. +
+Local and global variables can be declared anywhere inside a block. The declaration can include an initialization:
stat ::= local attnamelist [‘=’ explist]
- attnamelist ::= Name attrib {‘,’ Name attrib}
+ stat ::= global attnamelist [‘=’ explist]
-If present, an initial assignment has the same semantics +If there is no initialization, +local variables are initialized with nil; +global variables are left unchanged. +Otherwise, the initialization gets the same adjustment of a multiple assignment (see §3.3.3). -Otherwise, all variables are initialized with nil. +Moreover, for global variables, +the initialization will raise a runtime error +if the variable is already defined, +that is, it has a non-nil value.
-Each variable name may be postfixed by an attribute -(a name between angle brackets): +The list of names may be prefixed by an attribute +(a name between angle brackets) +and each variable name may be postfixed by an attribute:
- attrib ::= [‘<’ Name ‘>’]
+ attnamelist ::= [attrib] Name [attrib] {‘,’ Name [attrib]}
+ attrib ::= ‘<’ Name ‘>’
+A prefixed attribute applies to all names in the list;
+a postfixed attribute applies to its particular name.
There are two possible attributes:
-const, which declares a constant variable,
-that is, a variable that cannot be assigned to
-after its initialization;
+const, which declares a constant or read-only variable,
+
+that is, a variable that cannot be used as the left-hand side of an
+assignment,
and close, which declares a to-be-closed variable (see §3.3.8).
+Only local variables can have the close attribute.
A list of variables can contain at most one to-be-closed variable.
+
+Lua offers also a collective declaration for global variables: + +
+ stat ::= global [attrib] ‘*’ +
+This special form implicitly declares
+as globals all names not explicitly declared previously.
+In particular,
+global<const> * implicitly declares
+as read-only globals all names not explicitly declared previously;
+see the following example:
+
+
+ global X + global<const> * + print(math.pi) -- Ok, 'print' and 'math' are read-only + X = 1 -- Ok, declared as read-write + Y = 1 -- Error, Y is read-only ++ +
+As noted in §2.2,
+all chunks start with an implicit declaration global *,
+but this preambular declaration becomes void inside
+the scope of any other global declaration.
+Therefore, a program that does not use global declarations
+or start with global *
+has free read-write access to any global;
+a program that starts with global<const> *
+has free read-only access to any global;
+and a program that starts with any other global declaration
+(e.g., global none) can only refer to declared variables.
+
+
+
+Note that, for global variables, +the effect of any declaration is only syntactical +(except for the optional assignment): + +
+ global X <const>, _G + X = 1 -- ERROR + _ENV.X = 1 -- Ok + _G.print(X) -- Ok + foo() -- 'foo' can freely change any global ++
A chunk is also a block (see §3.3.2), -and so local variables can be declared in a chunk outside any explicit block. +and so variables can be declared in a chunk outside any explicit block.
-The visibility rules for local variables are explained in §3.5. +The visibility rules for variable declarations +are explained in §2.2. @@ -1971,10 +2130,11 @@
__close metamethod.
When calling the metamethod,
-the value itself is passed as the first argument
-and the error object that caused the exit (if any)
+the value itself is passed as the first argument.
+If there was an error,
+the error object that caused the exit
is passed as a second argument;
-if there was no error, the second argument is nil.
+otherwise, there is no second argument.
@@ -2070,14 +2230,14 @@
Lua supports the following arithmetic operators:
+: addition-: subtraction*: multiplication/: float division//: floor division%: modulo^: exponentiation-: unary minus+: addition-: subtraction*: multiplication/: float division//: floor division%: modulo^: exponentiation-: unary minus@@ -2124,12 +2284,12 @@
Lua supports the following bitwise operators:
&: bitwise AND|: bitwise OR~: bitwise exclusive OR>>: right shift<<: left shift~: unary bitwise NOT&: bitwise AND|: bitwise OR~: bitwise exclusive OR>>: right shift<<: left shift~: unary bitwise NOT@@ -2233,12 +2393,12 @@
Lua supports the following relational operators:
==: equality~=: inequality<: less than>: greater than<=: less or equal>=: greater or equal==: equality~=: inequality<: less than>: greater than<=: less or equal>=: greater or equalThese operators always result in false or true. @@ -2386,12 +2546,12 @@
A table with exactly one border is called a sequence.
-For instance, the table {10, 20, 30, 40, 50} is a sequence,
+For instance, the table {10,20,30,40,50} is a sequence,
as it has only one border (5).
-The table {10, 20, 30, nil, 50} has two borders (3 and 5),
+The table {10,20,30,nil,50} has two borders (3 and 5),
and therefore it is not a sequence.
(The nil at index 4 is called a hole.)
-The table {nil, 20, 30, nil, nil, 60, nil}
+The table {nil,20,30,nil,nil,60,nil}
has three borders (0, 3, and 6),
so it is not a sequence, too.
The table {} is a sequence with border 0.
@@ -2541,7 +2701,7 @@
can be used to emulate methods.
A call v:name(args)
-is syntactic sugar for v.name(v,args),
+is syntactic sugar for v.name(v, args),
except that v is evaluated only once.
@@ -2596,7 +2756,7 @@
-The syntax for function definition is +The syntax for a function definition is
functiondef ::= function funcbody @@ -2609,6 +2769,7 @@+ +3.4.11 – Function Definitions
stat ::= function funcname funcbody stat ::= local function Name funcbody + stat ::= global function Name funcbody funcname ::= Name {‘.’ Name} [‘:’ Name]The statement @@ -2630,7 +2791,9 @@
3.4.11 – Function Definitions
t.a.b.c.f = function () body end -+
The statement
@@ -2647,9 +2810,36 @@3.4.11 – Function Definitions
local f = function () body end
(This only makes a difference when the body of the function
-contains references to f.)
+contains recursive references to f.)
+Similarly, the statement
+
+
+ global function f () body end +
+translates to + +
+ global f; global f = function () body end +
+The second global makes the assignment an initialization, +which will raise an error if that global is already defined. +
+The colon syntax
+is used to emulate methods,
+adding an implicit extra parameter self to the function.
+Thus, the statement
+
+
+ function t.a.b.c:f (params) body end +
+is syntactic sugar for + +
+ t.a.b.c.f = function (self, params) body end ++
A function definition is an executable expression, whose value has type function. @@ -2662,12 +2852,30 @@
+Results are returned using the return statement (see §3.3.4). +If control reaches the end of a function +without encountering a return statement, +then the function returns with no results. + + +
+ +There is a system-dependent limit on the number of values +that a function may return. +This limit is guaranteed to be at least 1000. + + + +
Parameters act as local variables that are initialized with the argument values:
- parlist ::= namelist [‘,’ ‘...’] | ‘...’ + parlist ::= namelist [‘,’ varargparam] | varargparam + varargparam ::= ‘...’ [Name]
When a Lua function is called, it adjusts its list of arguments to @@ -2677,10 +2885,10 @@
n" is the number of extra arguments.
@@ -2692,7 +2900,7 @@
Then, we have the following mapping from arguments to parameters and -to the vararg expression: +to the vararg table:
CALL PARAMETERS
@@ -2703,46 +2911,52 @@ 3.4.11 – Function Definitions
f(r(), 10) a=1, b=10
f(r()) a=1, b=2
- g(3) a=3, b=nil, ... --> (nothing)
- g(3, 4) a=3, b=4, ... --> (nothing)
- g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
- g(5, r()) a=5, b=1, ... --> 2 3
+ g(3) a=3, b=nil, va. table -> {n = 0}
+ g(3, 4) a=3, b=4, va. table -> {n = 0}
+ g(3, 4, 5, 8) a=3, b=4, va. table -> {5, 8, n = 2}
+ g(5, r()) a=5, b=1, va. table -> {2, 3, n = 2}
-Results are returned using the return statement (see §3.3.4). -If control reaches the end of a function -without encountering a return statement, -then the function returns with no results. +A vararg table in a variadic function can have an optional name, +given after the three dots. +When present, +that name denotes a read-only local variable that +refers to the vararg table. +If the vararg table does not have a name, +it can only be accessed through a vararg expression.
-
-There is a system-dependent limit on the number of values
-that a function may return.
-This limit is guaranteed to be greater than 1000.
+A vararg expression is also written as three dots,
+and its value is a list of the values in the vararg table,
+from 1 to the integer value at index "n".
+(Therefore, if the code does not modify the vararg table,
+this list corresponds to the extra arguments in the function call.)
+This list behaves like the results from a
+function with multiple results (see §3.4.12).
-The colon syntax
-is used to emulate methods,
-adding an implicit extra parameter self to the function.
-Thus, the statement
+As an optimization,
+if the vararg table satisfies some conditions,
+the code does not create an actual table and instead translates
+the indexing expressions and the vararg expressions
+into accesses to the internal vararg data.
+The conditions are as follows:
+If the vararg table has a name,
+that name is not an upvalue in a nested function
+and it is used only as the base table
+in the syntactic constructions t[exp] or t.id.
+Note that an anonymous vararg table always satisfy these conditions.
+
-
- function t.a.b.c:f (params) body end -
-is syntactic sugar for -
- t.a.b.c.f = function (self, params) body end --
Both function calls and vararg expressions can result in multiple values. @@ -2765,22 +2979,22 @@
{e1, e2, e3} (see §3.4.9).{e1,e2,e3} (see §3.4.9).foo(e1, e2, e3) (see §3.4.10).foo(e1,e2,e3) (see §3.4.10).a , b, c = e1, e2, e3 (see §3.3.3).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).for k in e1,e2,e3 do ... end (see §3.3.5).
In the last four cases, @@ -2788,8 +3002,7 @@
-Here are some examples of uses of mutlres expressions. +Here are some examples of uses of multires expressions. In all cases, when the construction needs "the n-th result" and there is no such result, it uses a nil. @@ -2859,69 +3072,6 @@
- -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. -(Void statements are labels and empty statements.) -Consider the following example: - -
- x = 10 -- global variable - do -- new block - local x = x -- new 'x', with value 10 - print(x) --> 10 - x = x+1 - do -- another block - local x = x+1 -- another 'x' - print(x) --> 12 - end - print(x) --> 11 - end - print(x) --> 10 (the global one) -- -
-Notice that, in a declaration like local x = x,
-the new x being declared is not in scope yet,
-and so the second x refers to the outside variable.
-
-
-
-Because of the lexical scoping rules, -local variables can be freely accessed by functions -defined inside their scope. -A local variable used by an inner function is called an upvalue -(or external local variable, or simply external variable) -inside the inner function. - - -
-Notice that each execution of a local statement -defines new local variables. -Consider the following example: - -
- a = {}
- local x = 20
- for i = 1, 10 do
- local y = 0
- a[i] = function () y = y + 1; return x + y end
- end
-
-The loop creates ten closures
-(that is, ten instances of the anonymous function).
-Each of these closures uses a different y variable,
-while all of them share the same x.
-
-
-
-
-
Several functions in the API return pointers (const char*)
@@ -3123,8 +3273,8 @@
In general, -Lua's garbage collection can free or move internal memory -and then invalidate pointers to internal strings. +Lua's garbage collection can free or move memory +and then invalidate pointers to strings handled by a Lua state. To allow a safe use of these pointers, 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. @@ -3211,8 +3361,8 @@
The integer keys in the registry are used
-by the reference mechanism (see luaL_ref)
-and by some predefined values.
+by the reference mechanism (see luaL_ref),
+with some predefined values.
Therefore, integer keys in the registry
must not be used for other purposes.
@@ -3225,12 +3375,12 @@
LUA_RIDX_MAINTHREAD: At this index the registry has
+LUA_RIDX_MAINTHREAD: At this index the registry has
the main thread of the state.
(The main thread is the one created together with the state.)
LUA_RIDX_GLOBALS: At this index the registry has
+LUA_RIDX_GLOBALS: At this index the registry has
the global environment.
LUA_OK (0): no errors.LUA_OK (0): no errors.LUA_ERRRUN: a runtime error.LUA_ERRRUN: a runtime error.LUA_ERRMEM:
+LUA_ERRMEM:
memory allocation error.
For such errors, Lua does not call the message handler.
LUA_ERRERR: error while running the message handler.LUA_ERRERR:
+stack overflow while running the message handler
+due to another stack overflow.
+More often than not,
+this error is the result of some other error while running
+a message handler.
+An error in a message handler will call the handler again,
+which will generate the error again, and so on,
+until this loop exhausts the stack and cause this error.
+LUA_ERRSYNTAX: syntax error during precompilation.LUA_ERRSYNTAX: syntax error during precompilation
+or format error in a binary chunk.LUA_YIELD: the thread (coroutine) yields.LUA_YIELD: the thread (coroutine) yields.LUA_ERRFILE: a file-related error;
+LUA_ERRFILE: a file-related error;
e.g., it cannot open or read the file.@@ -3530,7 +3690,7 @@
-The type of the memory-allocation function used by Lua states.
+The type of the memory-allocator function used by Lua states.
The allocator function must provide a
functionality similar to realloc,
but not exactly the same.
@@ -3577,12 +3737,13 @@
-Here is a simple implementation for the allocator function.
-It is used in the auxiliary library by luaL_newstate.
+Here is a simple implementation for the allocator function,
+corresponding to the function luaL_alloc from the
+auxiliary library.
- static void *l_alloc (void *ud, void *ptr, size_t osize,
- size_t nsize) {
+ void *luaL_alloc (void *ud, void *ptr, size_t osize,
+ size_t nsize) {
(void)ud; (void)osize; /* not used */
if (nsize == 0) {
free(ptr);
@@ -3619,20 +3780,20 @@ 4.6 – Functions and Types
LUA_OPADD: performs addition (+)LUA_OPSUB: performs subtraction (-)LUA_OPMUL: performs multiplication (*)LUA_OPDIV: performs float division (/)LUA_OPIDIV: performs floor division (//)LUA_OPMOD: performs modulo (%)LUA_OPPOW: performs exponentiation (^)LUA_OPUNM: performs mathematical negation (unary -)LUA_OPBNOT: performs bitwise NOT (~)LUA_OPBAND: performs bitwise AND (&)LUA_OPBOR: performs bitwise OR (|)LUA_OPBXOR: performs bitwise exclusive OR (~)LUA_OPSHL: performs left shift (<<)LUA_OPSHR: performs right shift (>>)LUA_OPADD: performs addition (+)LUA_OPSUB: performs subtraction (-)LUA_OPMUL: performs multiplication (*)LUA_OPDIV: performs float division (/)LUA_OPIDIV: performs floor division (//)LUA_OPMOD: performs modulo (%)LUA_OPPOW: performs exponentiation (^)LUA_OPUNM: performs mathematical negation (unary -)LUA_OPBNOT: performs bitwise NOT (~)LUA_OPBAND: performs bitwise AND (&)LUA_OPBOR: performs bitwise OR (|)LUA_OPBXOR: performs bitwise exclusive OR (~)LUA_OPSHL: performs left shift (<<)LUA_OPSHR: performs right shift (>>)nresults,
-unless nresults is LUA_MULTRET.
-In this case, all results from the function are pushed;
+unless nresults is LUA_MULTRET,
+which makes all results from the function to be pushed.
+In the first case, an explicit number of results,
+the caller must ensure that the stack has space for the
+returned values.
+In the second case, all results,
Lua takes care that the returned values fit into the stack space,
but it does not ensure any extra space in the stack.
The function results are pushed onto the stack in direct order
@@ -3683,6 +3848,10 @@
+The maximum value for nresults is 250.
+
+
Any error while calling and running the function is propagated upwards
(with a longjmp).
@@ -3839,10 +4008,6 @@
-(This function was introduced in release 5.4.3.) - - @@ -3853,23 +4018,29 @@
Resets a thread, cleaning its call stack and closing all pending
to-be-closed variables.
-Returns a status code:
+The parameter from represents the coroutine that is resetting L.
+If there is no such coroutine,
+this parameter can be NULL.
+
+
+
+Unless L is equal to from,
+the call 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 error object is put 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.)
+If L is equal to from,
+it corresponds to a thread closing itself.
+In that case,
+the call does not return;
+instead, the resume that (re)started the thread returns.
+The thread must be running inside a resume.
@@ -3894,9 +4065,9 @@
LUA_OPEQ: compares for equality (==)LUA_OPLT: compares for less than (<)LUA_OPLE: compares for less or equal (<=)LUA_OPEQ: compares for equality (==)LUA_OPLT: compares for less than (<)LUA_OPLE: compares for less or equal (<=)lua_createtable[-0, +1, m] -
void lua_createtable (lua_State *L, int narr, int nrec);+
void lua_createtable (lua_State *L, int nseq, int nrec);
Creates a new empty table and pushes it onto the stack.
-Parameter narr is a hint for how many elements the table
+Parameter nseq is a hint for how many elements the table
will have as a sequence;
parameter nrec is a hint for how many other elements
the table will have.
Lua may use these hints to preallocate memory for the new table.
This preallocation may help performance when you know in advance
how many elements the table will have.
-Otherwise you can use the function lua_newtable.
+Otherwise you should use the function lua_newtable.
@@ -3972,6 +4143,15 @@
+The function lua_dump fully preserves the Lua stack
+through the calls to the writer function,
+except that it may push some values for internal use
+before the first call,
+and it restores the stack size to its original size
+after the last call.
+
+
If strip is true,
the binary representation may not include all debug information
@@ -3985,10 +4165,6 @@
-This function does not pop the Lua function from the stack. - - @@ -4023,50 +4199,64 @@
LUA_GCCOLLECT:
+LUA_GCCOLLECT:
Performs a full garbage-collection cycle.
LUA_GCSTOP:
+LUA_GCSTOP:
Stops the garbage collector.
LUA_GCRESTART:
+LUA_GCRESTART:
Restarts the garbage collector.
LUA_GCCOUNT:
+LUA_GCCOUNT:
Returns the current amount of memory (in Kbytes) in use by Lua.
LUA_GCCOUNTB:
+LUA_GCCOUNTB:
Returns the remainder of dividing the current amount of bytes of
memory in use by Lua by 1024.
LUA_GCSTEP (int stepsize):
-Performs an incremental step of garbage collection,
-corresponding to the allocation of stepsize Kbytes.
+LUA_GCSTEP (size_t n):
+Performs a step of garbage collection.
LUA_GCISRUNNING:
+LUA_GCISRUNNING:
Returns a boolean that tells whether the collector is running
(i.e., not stopped).
LUA_GCINC (int pause, int stepmul, stepsize):
-Changes the collector to incremental mode
-with the given parameters (see §2.5.1).
+LUA_GCINC:
+Changes the collector to incremental mode.
Returns the previous mode (LUA_GCGEN or LUA_GCINC).
LUA_GCGEN (int minormul, int majormul):
-Changes the collector to generational mode
-with the given parameters (see §2.5.2).
+LUA_GCGEN:
+Changes the collector to generational mode.
Returns the previous mode (LUA_GCGEN or LUA_GCINC).
LUA_GCPARAM (int param, int val):
+Changes and/or returns the value of a parameter of the collector.
+If val is -1, the call only returns the current value.
+The argument param must have one of the following values:
+
+LUA_GCPMINORMUL: The minor multiplier. LUA_GCPMAJORMINOR: The major-minor multiplier. LUA_GCPMINORMAJOR: The minor-major multiplier. LUA_GCPPAUSE: The garbage-collector pause. LUA_GCPSTEPMUL: The step multiplier. LUA_GCPSTEPSIZE: The step size. +
For more details about these options,
see collectgarbage.
@@ -4083,7 +4273,7 @@
lua_Alloc lua_getallocf (lua_State *L, void **ud);
-Returns the memory-allocation function of a given state.
+Returns the memory-allocator function of a given state.
If ud is not NULL, Lua stores in *ud the
opaque pointer given when the memory-allocator function was set.
@@ -4257,9 +4447,9 @@
By default this type is long long,
-(usually a 64-bit two-complement integer),
+(usually a 64-bit two's complement integer),
but that can be changed to long or int
-(usually a 32-bit two-complement integer).
+(usually a 32-bit two's complement integer).
(See LUA_INT_TYPE in luaconf.h.)
@@ -4516,12 +4706,32 @@
mode works as in function load,
with the addition that
a NULL value is equivalent to the string "bt".
+Moreover, it may have a 'B' instead of a 'b',
+meaning a fixed buffer with the binary dump.
-lua_load uses the stack internally,
-so the reader function must always leave the stack
-unmodified when returning.
+A fixed buffer means that the address returned by the reader function
+will contain the chunk until everything created by the chunk has
+been collected;
+therefore, Lua can avoid copying to internal structures
+some parts of the chunk.
+(In general, a fixed buffer would keep its contents
+until the end of the program,
+for instance with the chunk in ROM.)
+Moreover, for a fixed buffer,
+the reader function should return the entire chunk in the first read.
+(As an example, luaL_loadbufferx does that,
+which means that you can use it to load fixed buffers.)
+
+
+
+The function lua_load fully preserves the Lua stack
+through the calls to the reader function,
+except that it may push some values for internal use
+before the first call,
+and it restores the stack size to its original size plus one
+(for the pushed result) after the last call.
@@ -4545,7 +4755,8 @@
lua_newstate[-0, +0, –] -
lua_State *lua_newstate (lua_Alloc f, void *ud);+
lua_State *lua_newstate (lua_Alloc f, void *ud, + unsigned int seed);
Creates a new independent state and returns its main thread. @@ -4556,6 +4767,8 @@
lua_Alloc).
The second argument, ud, is an opaque pointer that Lua
passes to the allocator in every call.
+The third argument, seed,
+is a seed for the hashing of strings.
@@ -4567,7 +4780,7 @@
Creates a new empty table and pushes it onto the stack.
-It is equivalent to lua_createtable(L, 0, 0).
+It is equivalent to lua_createtable(L,0,0).
@@ -4700,6 +4913,24 @@
lua_numbertocstring+[-0, +0, –] +
unsigned lua_numbertocstring (lua_State *L, int idx, + char *buff);+ +
+Converts the number at acceptable index idx to a string
+and puts the result in buff.
+The buffer must have a size of at least LUA_N2SBUFFSZ bytes.
+The conversion follows a non-specified format (see §3.4.3).
+The function returns the number of bytes written to the buffer
+(including the final zero),
+or zero if the value at idx is not a number.
+
+
+
+
+
lua_pcall[-(nargs + 1), +(nresults|1), –]
int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);@@ -4851,6 +5082,48 @@
lua_pushexternalstring+[-0, +1, m] +
const char *lua_pushexternalstring (lua_State *L, + const char *s, size_t len, lua_Alloc falloc, void *ud);+ +
+Creates an external string,
+that is, a string that uses memory not managed by Lua.
+The pointer s points to the external buffer
+holding the string content,
+and len is the length of the string.
+The string should have a zero at its end,
+that is, the condition s[len] == '\0' should hold.
+As with any string in Lua,
+the length must fit in a Lua integer.
+
+
+
+If falloc is different from NULL,
+that function will be called by Lua
+when the external buffer is no longer needed.
+The contents of the buffer should not change before this call.
+The function will be called with the given ud,
+the string s as the block,
+the length plus one (to account for the ending zero) as the old size,
+and 0 as the new size.
+
+
+
+Even when using an external buffer,
+Lua still has to allocate a header for the string.
+In case of a memory-allocation error,
+Lua will call falloc before raising the error.
+
+
+
+The function returns a pointer to the string (that is, s).
+
+
+
+
+
lua_pushfstring[-0, +1, v]
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);@@ -4858,29 +5131,28 @@
Pushes onto the stack a formatted string
and returns a pointer to this string (see §4.1.3).
-It is similar to the ISO C function sprintf,
-but has two important differences.
-First,
-you do not have to allocate space for the result;
-the result is a Lua string and Lua takes care of memory allocation
-(and deallocation, through garbage collection).
-Second,
-the conversion specifiers are quite restricted.
-There are no flags, widths, or precisions.
-The conversion specifiers can only be
+The result is a copy of fmt with
+each conversion specifier replaced by a string representation
+of its respective extra argument.
+A conversion specifier (and its corresponding extra argument) can be
'%%' (inserts the character '%'),
'%s' (inserts a zero-terminated string, with no size restrictions),
'%f' (inserts a lua_Number),
'%I' (inserts a lua_Integer),
-'%p' (inserts a pointer),
+'%p' (inserts a void pointer),
'%d' (inserts an int),
'%c' (inserts an int as a one-byte character), and
-'%U' (inserts a long int as a UTF-8 byte sequence).
+'%U' (inserts an unsigned long as a UTF-8 byte sequence).
+
+
+
+Every occurrence of '%' in the string fmt
+must form a valid conversion specifier.
-This function may raise errors due to memory overflow -or an invalid conversion specifier. +Besides memory allocation errors, +this function may raise an error if the resulting string is too large. @@ -4930,7 +5202,7 @@
lua_pushliteral-[-0, +1, m] +[-0, +1, v]
const char *lua_pushliteral (lua_State *L, const char *s);
@@ -4943,7 +5215,7 @@
lua_pushlstring-[-0, +1, m] +[-0, +1, v]
const char *lua_pushlstring (lua_State *L, const char *s, size_t len);
@@ -4960,6 +5232,11 @@
+Besides memory allocation errors, +this function may raise an error if the string is too large. + + @@ -5033,14 +5310,18 @@
lua_pushvfstring-[-0, +1, v] +[-0, +1, –]
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
-Equivalent to lua_pushfstring, except that it receives a va_list
-instead of a variable number of arguments.
+Equivalent to lua_pushfstring,
+except that it receives a va_list
+instead of a variable number of arguments,
+and it does not raise errors.
+Instead, in case of errors it pushes the error message
+and returns NULL.
@@ -5246,19 +5527,6 @@
lua_resetthread-[-0, +?, –] -
int lua_resetthread (lua_State *L);- -
-This function is deprecated;
-it is equivalent to lua_closethread with
-from being NULL.
-
-
-
-
-
lua_resume[-?, +?, –]
int lua_resume (lua_State *L, lua_State *from, int nargs, @@ -5274,8 +5542,9 @@4.6 – Functions and Types
onto the empty stack of the thread. then you calllua_resume, withnargsbeing the number of arguments. -This call returns when the coroutine suspends or finishes its execution. -When it returns, +The function returns when the coroutine suspends, +finishes its execution, or raises an unprotected error. +When it returns without errors,*nresultsis updated and the top of the stack contains the*nresultsvalues passed tolua_yield@@ -5286,11 +5555,13 @@4.6 – Functions and Types
without errors, or an error code in case of errors (see §4.4.1). In case of errors, -the error object is on the top of the stack. +the error object is pushed on the top of the stack. +(In that case,nresultsis not updated, +as its value would have to be 1 for the sole error object.)-To resume a coroutine, +To resume a suspended coroutine, you remove the
*nresultsyielded values from its stack, push the values to be passed as results fromyield, and then calllua_resume. @@ -5444,7 +5715,7 @@4.6 – Functions and Types
void lua_settop (lua_State *L, int index);-Accepts any index, or 0, +Receives any acceptable stack index, or 0, and sets the stack top to this index. If the new top is greater than the old one, then the new elements are filled with nil. @@ -5650,8 +5921,6 @@
4.6 – Functions and Types
Converts the Lua value at the given index to a C string. -If
lenis notNULL, -it sets*lenwith the string length. The Lua value must be a string or a number; otherwise, the function returnsNULL. If the value is a number, @@ -5662,13 +5931,19 @@4.6 – Functions and Types
-
lua_tolstringreturns a pointer -to a string inside the Lua state (see §4.1.3). -This string always has a zero ('\0') -after its last character (as in C), +Iflenis notNULL, +the function sets*lenwith the string length. +The returned C string always has a zero ('\0') +after its last character, but can contain other zeros in its body. ++The pointer returned by
lua_tolstring+may be invalidated by the garbage collector if the +corresponding Lua value is removed from the stack (see §4.1.3). + +This function can raise memory errors only when converting a number to a string @@ -5892,6 +6167,12 @@
4.6 – Functions and Types
and theudparameter supplied tolua_dump. ++After
lua_dumpwrites its last piece, +it will signal that by calling the writer function one more time, +with aNULLbuffer (and size 0). + +The writer returns an error code: 0 means no errors; @@ -6022,9 +6303,10 @@
4.7 – The Debug Interface
unsigned char nups; /* (u) number of upvalues */ unsigned char nparams; /* (u) number of parameters */ char isvararg; /* (u) */ + unsigned char extraargs; /* (t) number of extra arguments */ char istailcall; /* (t) */ - unsigned short ftransfer; /* (r) index of first value transferred */ - unsigned short ntransfer; /* (r) number of transferred values */ + int ftransfer; /* (r) index of first value transferred */ + int ntransfer; /* (r) number of transferred values */ char short_src[LUA_IDSIZE]; /* (S) */ /* private part */ other fields @@ -6047,7 +6329,7 @@4.7 – The Debug Interface
source:
+source:
the source of the chunk that created the function.
If source starts with a '@',
it means that the function was defined in a file where
@@ -6059,35 +6341,35 @@ source is that string.
srclen:
+srclen:
The length of the string source.
short_src:
+short_src:
a "printable" version of source, to be used in error messages.
linedefined:
+linedefined:
the line number where the definition of the function starts.
lastlinedefined:
+lastlinedefined:
the line number where the definition of the function ends.
what:
+what:
the string "Lua" if the function is a Lua function,
"C" if it is a C function,
"main" if it is the main part of a chunk.
currentline:
+currentline:
the current line where the given function is executing.
When no line information is available,
currentline is set to -1.
name:
+name:
a reasonable name for the given function.
Because functions in Lua are first-class values,
they do not have a fixed name:
@@ -6099,35 +6381,43 @@ name is set to NULL.
namewhat:
+namewhat:
explains the name field.
The value of namewhat can be
-"global", "local", "method",
-"field", "upvalue", or "" (the empty string),
+"global", "local", "upvalue",
+"field", "" (the empty string), plus some other options,
according to how the function was called.
(Lua uses the empty string when no other option seems to apply.)
istailcall:
+istailcall:
true if this function invocation was called by a tail call.
In this case, the caller of this level is not in the stack.
nups:
+extraargs:
+The number of extra arguments added by the call
+to functions called through __call metamethods.
+(Each __call metavalue adds a single extra argument,
+the object being called,
+but there may be a chain of __call metavalues.)
+nups:
the number of upvalues of the function.
nparams:
+nparams:
the number of parameters of the function
(always 0 for C functions).
isvararg:
+isvararg:
true if the function is a variadic function
(always true for C functions).
ftransfer:
+ftransfer:
the index in the stack of the first value being "transferred",
that is, parameters in a call or return values in a return.
(The other values are in consecutive indices.)
@@ -6139,7 +6429,7 @@ ntransfer:
+ntransfer:
The number of values being transferred (see previous item).
(For calls of Lua functions,
this value is always equal to nparams.)
@@ -6223,33 +6513,33 @@ f':
+f':
pushes onto the stack the function that is
running at the given level;
l': fills in the field currentline;
+l': fills in the field currentline;
n': fills in the fields name and namewhat;
+n': fills in the fields name and namewhat;
r': fills in the fields ftransfer and ntransfer;
+r': fills in the fields ftransfer and ntransfer;
S':
+S':
fills in the fields source, short_src,
linedefined, lastlinedefined, and what;
t': fills in the field istailcall;
+t': fills in the fields istailcall and extraargs;
u': fills in the fields
+u': fills in the fields
nups, nparams, and isvararg;
L':
+L':
pushes onto the stack a table whose indices are
the lines on the function with some associated code,
that is, the lines where you can put a break point.
@@ -6423,21 +6713,21 @@ count instructions.
This event only happens while Lua is executing a Lua function.
All functions and types from the auxiliary library
-are defined in header file lauxlib.h and
+are defined in the header file lauxlib.h and
have a prefix luaL_.
@@ -6751,7 +7041,7 @@
b of type luaL_Buffer.luaL_buffinit(L, &b).luaL_buffinit(L,&b).b of type luaL_Buffer.sz with a call luaL_buffinitsize(L, &b, sz).sz with a call luaL_buffinitsize(L,&b,sz).luaL_pushresultsize(&b, sz),
+Finish by calling luaL_pushresultsize(&b,sz),
where sz is the total size of the resulting string
copied into that space (which may be less than or
equal to the preallocated size).
@@ -7060,6 +7350,7 @@
It returns 0 (LUA_OK) if there are no errors,
or 1 in case of errors.
+(Except for out-of-memory errors, which are raised.)
@@ -7242,6 +7533,8 @@
name is the chunk name,
used for debug information and error messages.
The string mode works as in the function lua_load.
+In particular, this function supports mode 'B' for
+fixed buffers.
@@ -7277,7 +7570,7 @@
-This function returns the same results as lua_load
+This function returns the same results as lua_load,
or LUA_ERRFILE for file-related errors.
@@ -7311,6 +7604,19 @@
luaL_makeseed+[-0, +0, –] +
unsigned int luaL_makeseed (lua_State *L);+ +
+Returns a value with a weak attempt for randomness.
+The parameter L can be NULL
+if there is no Lua state available.
+
+
+
+
+
luaL_newlib[-0, +1, m]
void luaL_newlib (lua_State *L, const luaL_Reg l[]);@@ -7383,8 +7689,9 @@
Creates a new Lua state.
-It calls lua_newstate with an
-allocator based on the ISO C allocation functions
+It calls lua_newstate with luaL_alloc as
+the allocator function and the result of luaL_makeseed(NULL)
+as the seed,
and then sets a warning function and a panic function (see §4.4)
that print messages to the standard error output.
@@ -7397,17 +7704,6 @@
luaL_openlibs-[-0, +0, e] -
void luaL_openlibs (lua_State *L);- -
-Opens all standard Lua libraries into the given state. - - - - -
luaL_opt[-0, +0, –]
T luaL_opt (L, func, arg, dflt);@@ -7583,11 +7879,23 @@
-A reference is a unique integer key.
-As long as you do not manually add integer keys into the table t,
-luaL_ref ensures the uniqueness of the key it returns.
+The reference system uses the integer keys of the table.
+A reference is a unique integer key;
+luaL_ref ensures the uniqueness of the keys it returns.
+The entry 1 is reserved for internal use.
+Before the first use of luaL_ref,
+the integer keys of the table
+should form a proper sequence (no holes),
+and the value at entry 1 should be false:
+nil if the sequence is empty,
+false otherwise.
+You should not manually set integer keys in the table
+after the first use of luaL_ref.
+
+
+
You can retrieve an object referred by the reference r
-by calling lua_rawgeti(L, t, r).
+by calling lua_rawgeti(L,t,r) or lua_geti(L,t,r).
The function luaL_unref frees a reference.
@@ -7633,7 +7941,7 @@
If glb is true,
-also stores the module into the global modname.
+also stores the module into the global variable modname.
@@ -7683,6 +7991,17 @@
luaL_allocvoid *luaL_alloc (void *ud, void *ptr, size_t osize, size_t nsize);+ +
+A standard allocator function for Lua (see lua_Alloc),
+built on top of the C functions realloc and free.
+
+
+
+
+
luaL_Streamtypedef struct luaL_Stream {
FILE *f;
@@ -7705,8 +8024,8 @@ 5.1 – Functions and Types
This userdata must start with the structure luaL_Stream;
it can contain other data after this initial structure.
-The field f points to the corresponding C stream
-(or it can be NULL to indicate an incompletely created handle).
+The field f points to the corresponding C stream,
+or it is NULL to indicate an incompletely created handle.
The field closef points to a Lua function
that will be called to close the stream
when the handle is closed or collected;
@@ -7804,16 +8123,16 @@
5.1 – Functions and Types
void luaL_unref (lua_State *L, int t, int ref);
-Releases the reference ref from the table at index t
-(see luaL_ref).
-The entry is removed from the table,
-so that the referred object can be collected.
-The reference ref is also freed to be used again.
-
-
-
-If ref is LUA_NOREF or LUA_REFNIL,
-luaL_unref does nothing.
+Releases a reference (see luaL_ref).
+The integer ref must be either
+LUA_NOREF, LUA_REFNIL,
+or a reference previously returned by luaL_ref
+and not already released.
+If ref is either LUA_NOREF or LUA_REFNIL
+this function does nothing.
+Otherwise, the entry is removed from the table,
+so that the referred object can be collected and
+the reference ref can be used again by luaL_ref.
@@ -7884,25 +8203,25 @@
6 – The Standard Libraries
Except for the basic and the package libraries, @@ -7910,30 +8229,80 @@
-To have access to these libraries,
-the C host program should call the luaL_openlibs function,
-which opens all standard libraries.
+A C host program must explicitly load
+the standard libraries into a state,
+if it wants its scripts to use them.
+For that,
+the host program can call the function luaL_openlibs.
Alternatively,
-the host program can open them individually by using
-luaL_requiref to call
-luaopen_base (for the basic library),
-luaopen_package (for the package library),
-luaopen_coroutine (for the coroutine library),
-luaopen_string (for the string library),
-luaopen_utf8 (for the UTF-8 library),
-luaopen_table (for the table library),
-luaopen_math (for the mathematical library),
-luaopen_io (for the I/O library),
-luaopen_os (for the operating system library),
-and luaopen_debug (for the debug library).
-These functions are declared in lualib.h.
+the host can select which libraries to open,
+by using luaL_openselectedlibs.
+Both functions are declared in the header file lualib.h.
+
+
+
+
+The stand-alone interpreter lua (see §7)
+already opens all standard libraries.
+
+
+
+
luaL_openlibs+[-0, +0, e] +
void luaL_openlibs (lua_State *L);+ +
+Opens all standard Lua libraries into the given state. -
luaL_openselectedlibs+[-0, +0, e] +
void luaL_openselectedlibs (lua_State *L, int load, int preload);+ +
+Opens (loads) and preloads selected standard libraries into the state L.
+(To preload means to add
+the library loader into the table package.preload,
+so that the library can be required later by the program.
+Keep in mind that require itself is provided
+by the package library.
+If a program does not load that library,
+it will be unable to require anything.)
+
+
+
+The integer load selects which libraries to load;
+the integer preload selects which to preload, among those not loaded.
+Both are masks formed by a bitwise OR of the following constants:
+
+
LUA_GLIBK : the basic library.LUA_LOADLIBK : the package library.LUA_COLIBK : the coroutine library.LUA_STRLIBK : the string library.LUA_UTF8LIBK : the UTF-8 library.LUA_TABLIBK : the table library.LUA_MATHLIBK : the mathematical library.LUA_IOLIBK : the I/O library.LUA_OSLIBK : the operating system library.LUA_DBLIBK : the debug library.The basic library provides core functions to Lua. @@ -7967,59 +8336,92 @@
collect":
+collect":
Performs a full garbage-collection cycle.
This is the default option.
stop":
+stop":
Stops automatic execution of the garbage collector.
The collector will run only when explicitly invoked,
until a call to restart it.
restart":
+restart":
Restarts automatic execution of the garbage collector.
count":
+count":
Returns the total memory in use by Lua in Kbytes.
The value has a fractional part,
so that it multiplied by 1024
gives the exact number of bytes in use by Lua.
step":
+step":
Performs a garbage-collection step.
-The step "size" is controlled by arg.
-With a zero value,
-the collector will perform one basic (indivisible) step.
-For non-zero values,
-the collector will perform as if that amount of memory
-(in Kbytes) had been allocated by Lua.
-Returns true if the step finished a collection cycle.
+This option may be followed by an extra argument,
+an integer with the step size.
+
+
+
+If the size is a positive n,
+the collector acts as if n new bytes have been allocated.
+If the size is zero,
+the collector performs a basic step.
+In incremental mode,
+a basic step corresponds to the current step size.
+In generational mode,
+a basic step performs a full minor collection or
+an incremental step,
+if the collector has scheduled one.
+
+
+
+In incremental mode, +the function returns true if the step finished a collection cycle. +In generational mode, +the function returns true if the step finished a major collection.
isrunning":
+isrunning":
Returns a boolean that tells whether the collector is running
(i.e., not stopped).
incremental":
-Change the collector mode to incremental.
-This option can be followed by three numbers:
-the garbage-collector pause,
-the step multiplier,
-and the step size (see §2.5.1).
-A zero means to not change that value.
+incremental":
+Changes the collector mode to incremental and returns the previous mode.
generational":
-Change the collector mode to generational.
-This option can be followed by two numbers:
-the garbage-collector minor multiplier
-and the major multiplier (see §2.5.2).
-A zero means to not change that value.
+generational":
+Changes the collector mode to generational and returns the previous mode.
+param":
+Changes and/or retrieves the values of a parameter of the collector.
+This option must be followed by one or two extra arguments:
+The name of the parameter being changed or retrieved (a string)
+and an optional new value for that parameter,
+an integer in the range [0,100000].
+The first argument must have one of the following values:
+
+minormul": The minor multiplier. majorminor": The major-minor multiplier. minormajor": The minor-major multiplier. pause": The garbage-collector pause. stepmul": The step multiplier. stepsize": The step size. +The call always returns the previous value of the parameter. +If the call does not give a new value, +the value is left unchanged. + + +
+Lua stores these values in a compressed format, +so, the value returned as the previous value may not be +exactly the last value set.
@@ -8035,10 +8437,10 @@
dofile ([filename])dofile executes the content of the standard input (stdin).
-Returns all values returned by the chunk.
In case of errors, dofile propagates the error
to its caller.
(That is, dofile does not run in protected mode.)
@@ -8096,7 +8498,7 @@
-Returns three values (an iterator function, the table t, and 0)
+Returns three values (an iterator function, the value t, and 0)
so that the construction
@@ -8172,11 +8574,10 @@6.1 – Basic Functions
-It is safe to load malformed binary chunks; -
loadsignals an appropriate error. -However, -Lua does not check the consistency of the code inside binary chunks; -running maliciously crafted bytecode can crash the interpreter. +Lua does not check the consistency of binary chunks. +Maliciously crafted binary chunks can crash +the interpreter. +You can use themodeparameter to prevent loading binary chunks. @@ -8237,13 +8638,13 @@6.1 – Basic Functions
If
thas a metamethod__pairs, -calls it withtas argument and returns the first three +calls it withtas argument and returns the first four results from the call.Otherwise, -returns three values: the
nextfunction, the tablet, and nil, +returns thenextfunction, the tablet, plus two nil values, so that the construction@@ -8373,7 +8774,7 @@6.1 – Basic Functions
To change the metatable of other types from Lua code, -you must use the debug library (§6.10). +you must use the debug library (§6.11). @@ -8463,7 +8864,7 @@
6.1 – Basic Functions
A global variable (not a function) that holds a string containing the running Lua version. -The current value of this variable is "
Lua 5.4". +The current value of this variable is "Lua 5.5". @@ -8505,7 +8906,7 @@6.1 – Basic Functions
-6.2 – Coroutine Manipulation
+6.3 – Coroutine Manipulation
This library comprises the operations to manipulate coroutines, @@ -8514,7 +8915,7 @@
6.2 – Coroutine Manipulation
-
+
coroutine.close (co)
coroutine.close ([co])@@ -8522,12 +8923,24 @@
6.2 – Coroutine Manipulation
that is, closes all its pending to-be-closed variables and puts the coroutine in a dead state. -The given coroutine must be dead or suspended. -In case of error +The default forcois the running coroutine. + + ++The given coroutine must be dead, suspended, +or be the running coroutine. +For the running coroutine, +this function does not return. +Instead, the resume that (re)started the coroutine returns. + + +
+For other coroutines, +in case of error (either the original error that stopped the coroutine or errors in closing methods), -returns false plus the error object; -otherwise returns true. +this function returns false plus the error object; +otherwise it returns true. @@ -8650,7 +9063,7 @@
6.2 – Coroutine Manipulation
-6.3 – Modules
+6.4 – Modules
The package library provides basic @@ -8773,7 +9186,7 @@
6.3 – Modules
Lua initializes the C path
package.cpathin the same way it initializes the Lua pathpackage.path, -using the environment variableLUA_CPATH_5_4, +using the environment variableLUA_CPATH_5_5, or the environment variableLUA_CPATH, or a default path defined inluaconf.h. @@ -8836,9 +9249,9 @@6.3 – Modules
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
dlfcnstandard). +As such,loadlibis only available on some platforms: +Linux, Windows, Mac OS X, Solaris, BSD, +plus other Unix systems that support thedlfcnstandard.@@ -8866,7 +9279,7 @@
6.3 – Modules
At start-up, Lua initializes this variable with -the value of the environment variable
LUA_PATH_5_4or +the value of the environment variableLUA_PATH_5_5or the environment variableLUA_PATHor with a default path defined inluaconf.h, if those environment variables are not defined. @@ -9036,7 +9449,7 @@6.3 – Modules
-6.4 – String Manipulation
+6.5 – String Manipulation
@@ -9129,7 +9542,7 @@6.4 – String Manipulation
Looks for the first match of -
pattern(see §6.4.1) in the strings. +pattern(see §6.5.1) in the strings. If it finds a match, thenfindreturns the indices ofswhere this occurrence starts and ends; otherwise, it returns fail. @@ -9160,9 +9573,12 @@6.4 – String Manipulation
following the description given in its first argument, which must be a string. The format string follows the same rules as the ISO C functionsprintf. -The only differences are that the conversion specifiers and modifiers -F,n,*,h,L, andlare not supported -and that there is an extra specifier,q. +The accepted conversion specifiers are +A,a,c,d,E,e,f,G,g, +i,o,p,s,u,X,x, and '%', +plus a non-C specifierq. +The accepted flags are '-', '+', '#', +'0', and '' (space). Both width and precision, when present, are limited to two digits. @@ -9227,7 +9643,7 @@6.4 – String Manipulation
Returns an iterator function that, each time it is called, -returns the next captures from
string.gmatch (s, pattern [, init])pattern(see §6.4.1) +returns the next captures frompattern(see §6.5.1) over the strings. Ifpatternspecifies no captures, then the whole match is produced in each call. @@ -9269,7 +9685,7 @@6.4 – String Manipulation
Returns a copy of
string.gsub (s, pattern, repl [, n])sin which all (or the firstn, if given) -occurrences of thepattern(see §6.4.1) have been +occurrences of thepattern(see §6.5.1) have been replaced by a replacement string specified byrepl, which can be a string, a table, or a function.gsubalso returns, as its second value, @@ -9318,25 +9734,25 @@6.4 – String Manipulation
x = string.gsub("hello world", "(%w+)", "%1 %1") - --> x="hello hello world world" + -- x="hello hello world world" x = string.gsub("hello world", "%w+", "%0 %0", 1) - --> x="hello hello world" + -- x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") - --> x="world hello Lua from" + -- x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) - --> x="home = /home/roberto, user = roberto" + -- x="home = /home/roberto, user = roberto" x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return load(s)() end) - --> x="4+5 = 9" + -- x="4+5 = 9" - local t = {name="lua", version="5.4"} + local t = {name="lua", version="5.5"} x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) - --> x="lua-5.4.tar.gz" + -- x="lua-5.5.tar.gz"@@ -9373,7 +9789,7 @@6.4 – String Manipulation
Looks for the first match of -the
pattern(see §6.4.1) in the strings. +thepattern(see §6.5.1) in the strings. If it finds one, thenmatchreturns the captures from the pattern; otherwise it returns fail. @@ -9393,7 +9809,7 @@6.4 – String Manipulation
Returns a binary string containing the values
v1,v2, etc. serialized in binary form (packed) -according to the format stringfmt(see §6.4.2). +according to the format stringfmt(see §6.5.2). @@ -9406,7 +9822,7 @@6.4 – String Manipulation
Returns the length of a string resulting fromstring.packwith the given format. The format string cannot have the variable-length options -'s' or 'z' (see §6.4.2). +'s' or 'z' (see §6.5.2). @@ -9453,7 +9869,7 @@6.4 – String Manipulation
In particular, the callstring.sub(s,1,j)returns a prefix ofswith lengthj, -andstring.sub(s, -i)(for a positivei) +andstring.sub(s,-i)(for a positivei) returns a suffix ofswith lengthi. @@ -9477,7 +9893,7 @@6.4 – String Manipulation
Returns the values packed in string
s(seestring.pack) -according to the format stringfmt(see §6.4.2). +according to the format stringfmt(see §6.5.2). An optionalposmarks where to start reading ins(default is 1). After the read values, @@ -9502,7 +9918,7 @@6.4 – String Manipulation
-6.4.1 – Patterns
+6.5.1 – Patterns
@@ -9526,35 +9942,35 @@Character Class:
^$()%.[]*+-?)
represents the character x itself.
.: (a dot) represents all characters..: (a dot) represents all characters.%a: represents all letters.%a: represents all letters.%c: represents all control characters.%c: represents all control characters.%d: represents all digits.%d: represents all digits.%g: represents all printable characters except space.%g: represents all printable characters except space.%l: represents all lowercase letters.%l: represents all lowercase letters.%p: represents all punctuation characters.%p: represents all punctuation characters.%s: represents all space characters.%s: represents all space characters.%u: represents all uppercase letters.%u: represents all uppercase letters.%w: represents all alphanumeric characters.%w: represents all alphanumeric characters.%x: represents all hexadecimal digits.%x: represents all hexadecimal digits.%x: (where x is any non-alphanumeric character)
+%x: (where x is any non-alphanumeric character)
represents the character x.
This is the standard way to escape the magic characters.
Any non-alphanumeric character
@@ -9562,7 +9978,7 @@
can be preceded by a '%' to represent itself in a pattern.
[set]:
+[set]:
represents the class which is the union of all
characters in set.
A range of characters can be specified by
@@ -9592,7 +10008,7 @@ have no meaning.
[^set]:
+[^set]:
represents the complement of set,
where set is interpreted as above.
-
The first argument to string.pack,
@@ -9757,37 +10173,37 @@
<: sets little endian>: sets big endian=: sets native endian![n]: sets maximum alignment to n
+<: sets little endian>: sets big endian=: sets native endian![n]: sets maximum alignment to n
(default is native alignment)b: a signed byte (char)B: an unsigned byte (char)h: a signed short (native size)H: an unsigned short (native size)l: a signed long (native size)L: an unsigned long (native size)j: a lua_IntegerJ: a lua_UnsignedT: a size_t (native size)i[n]: a signed int with n bytes
+b: a signed byte (char)B: an unsigned byte (char)h: a signed short (native size)H: an unsigned short (native size)l: a signed long (native size)L: an unsigned long (native size)j: a lua_IntegerJ: a lua_UnsignedT: a size_t (native size)i[n]: a signed int with n bytes
(default is native size)I[n]: an unsigned int with n bytes
+I[n]: an unsigned int with n bytes
(default is native size)f: a float (native size)d: a double (native size)n: a lua_Numbercn: a fixed-sized string with n bytesz: a zero-terminated strings[n]: a string preceded by its length
+f: a float (native size)d: a double (native size)n: a lua_Numbercn: a fixed-sized string with n bytesz: a zero-terminated strings[n]: a string preceded by its length
coded as an unsigned integer with n bytes
(default is a size_t)x: one byte of paddingXop: an empty item that aligns
+x: one byte of paddingXop: an empty item that aligns
according to option op
(which is otherwise ignored) ': (space) ignored ': (space) ignored
(A "[n]" means an optional integral numeral.)
Except for padding, spaces, and configurations
@@ -9841,7 +10257,7 @@
This library provides basic support for UTF-8 encoding. @@ -9898,7 +10314,7 @@
The pattern (a string, not a function) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*"
-(see §6.4.1),
+(see §6.5.1),
which matches exactly one UTF-8 byte sequence,
assuming that the subject is a valid UTF-8 string.
@@ -9955,23 +10371,33 @@
-Returns the position (in bytes) where the encoding of the
-n-th character of s
-(counting from position i) starts.
+Returns the position of the n-th character of s
+(counting from byte position i) as two integers:
+The index (in bytes) where its encoding starts and the
+index (in bytes) where it ends.
+
+
+
+If the specified character is right after the end of s,
+the function behaves as if there was a '\0' there.
+If the specified character is neither in the subject
+nor right after its end,
+the function returns fail.
+
+
+
A negative n gets characters before position i.
The default for i is 1 when n is non-negative
and #s + 1 otherwise,
-so that utf8.offset(s, -n) gets the offset of the
+so that utf8.offset(s,-n) gets the offset of the
n-th character from the end of the string.
-If the specified character is neither in the subject
-nor right after its end,
-the function returns fail.
As a special case,
-when n is 0 the function returns the start of the encoding
-of the character that contains the i-th byte of s.
+when n is 0 the function returns the start and end
+of the encoding of the character that contains the
+i-th byte of s.
@@ -9983,7 +10409,7 @@
This library provides generic functions for table manipulation. @@ -10012,6 +10438,25 @@
+
table.create (nseq [, nrec])+Creates a new empty table, preallocating memory. +This preallocation may help performance and save memory +when you know in advance how many elements the table will have. + + +
+Parameter nseq is a hint for how many elements the table
+will have as a sequence.
+Optional parameter nrec is a hint for how many other elements
+the table will have; its default is zero.
+
+
+
+
table.insert (list, [pos,] value)
Inserts element value at position pos in list,
shifting up the elements
-list[pos], list[pos+1], ···, list[#list].
+list[pos],list[pos+1],···,list[#list].
The default value for pos is #list+1,
so that a call table.insert(t,x) inserts x at the end
of the list t.
@@ -10039,6 +10484,8 @@
a2 is a1.
The destination range can overlap with the source range.
The number of elements to be moved must fit in a Lua integer.
+If f is larger than e,
+nothing is moved.
@@ -10069,7 +10516,7 @@
pos is an integer between 1 and #list,
it shifts down the elements
-list[pos+1], list[pos+2], ···, list[#list]
+list[pos+1],list[pos+2],···,list[#list]
and erases element list[#list];
The index pos can also be 0 when #list is 0,
or #list + 1.
@@ -10134,7 +10581,7 @@ This library provides basic mathematical functions. @@ -10260,6 +10707,21 @@
+
math.frexp (x)
+Returns two numbers m and e such that x = m2e,
+where e is an integer.
+When x is zero, NaN, +inf, or -inf,
+m is equal to x;
+otherwise, the absolute value of m
+is in the range [0.5, 1) .
+
+
+
+
math.huge+
math.ldexp (m, e)
+Returns m2e, where e is an integer.
+
+
+
+
math.log (x [, base])
When called without arguments,
returns a pseudo-random float with uniform distribution
-in the range [0,1).
+in the range [0, 1).
When called with two integers m and n,
math.random returns a pseudo-random integer
with uniform distribution in the range [m, n].
@@ -10391,7 +10863,7 @@
When called with at least one argument,
the integer parameters x and y are
-joined into a 128-bit seed that
+joined into a seed that
is used to reinitialize the pseudo-random generator;
equal seeds produce equal sequences of numbers.
The default for y is zero.
@@ -10488,7 +10960,7 @@
The I/O library provides two different styles for file manipulation. @@ -10623,12 +11095,12 @@
mode string can be any of the following:
r": read mode (the default);w": write mode;a": append mode;r+": update mode, all previous data is preserved;w+": update mode, all previous data is erased;a+": append update mode, previous data is preserved,
+r": read mode (the default);w": write mode;a": append mode;r+": update mode, all previous data is preserved;w+": update mode, all previous data is erased;a+": append update mode, previous data is preserved,
writing is only allowed at the end of file.
The mode string can also have a 'b' at the end,
@@ -10786,7 +11258,7 @@
n":
+n":
reads a numeral and returns it as a float or an integer,
following the lexical conventions of Lua.
(The numeral may have leading whitespaces and a sign.)
@@ -10798,24 +11270,24 @@ a":
+a":
reads the whole file, starting at the current position.
On end of file, it returns the empty string;
this format never fails.
l":
+l":
reads the next line skipping the end of line,
returning fail on end of file.
This is the default format.
L":
+L":
reads the next line keeping the end-of-line character (if present),
returning fail on end of file.
number is zero,
@@ -10840,9 +11312,9 @@ whence, as follows:
set": base is position 0 (beginning of the file);cur": base is current position;end": base is end of file;set": base is position 0 (beginning of the file);cur": base is current position;end": base is end of file;
In case of success, seek returns the final file position,
measured in bytes from the beginning of the file.
@@ -10872,9 +11344,9 @@
no": no buffering.full": full buffering.line": line buffering.no": no buffering.full": full buffering.line": line buffering.@@ -10902,6 +11374,9 @@
In case of success, this function returns file.
+Otherwise, it returns four values:
+fail, the error message, the error code,
+and the number of bytes it was able to write.
@@ -10909,7 +11384,7 @@
This library is implemented through table os.
@@ -11009,12 +11484,12 @@
exit":
+exit":
the command terminated normally;
the following number is the exit status of the command.
signal":
+signal":
the command was terminated by a signal;
the following number is the signal that terminated the command.
-Returns the current time when called without arguments,
+Returns the current local time when called without arguments,
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
@@ -11201,7 +11676,7 @@
This library provides @@ -11327,6 +11802,12 @@
The function returns fail if there is no variable with the given index, and raises an error when called with a level out of range. @@ -11422,9 +11903,9 @@
c': the hook is called every time Lua calls a function;r': the hook is called every time Lua returns from a function;l': the hook is called every time Lua enters a new line of code.c': the hook is called every time Lua calls a function;r': the hook is called every time Lua returns from a function;l': the hook is called every time Lua enters a new line of code.
Moreover,
with a count different from zero,
@@ -11591,20 +12072,18 @@
-e stat: execute string stat;-i: enter interactive mode after running script;-l mod: "require" mod and assign the
+-e stat: execute string stat;-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
+-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.
-(The form -l g=mod was introduced in release 5.4.4.)
-
+
-v: print version information;-E: ignore environment variables;-W: turn warnings on;--: stop handling options;-: execute stdin as a file and stop handling options.
After handling its options, lua runs the given script.
@@ -11616,7 +12095,7 @@
When called without the option -E,
-the interpreter checks for an environment variable LUA_INIT_5_4
+the interpreter checks for an environment variable LUA_INIT_5_5
(or LUA_INIT if the versioned name is not defined)
before running any argument.
If the variable content has the format @filename,
@@ -11691,14 +12170,36 @@
+Note that, as each complete line is read as a new chunk, +local variables do not outlive lines. +To steer clear of confusion, +the interpreter gives a warning if a line starts with the +reserved word local: + +
+ > x = 20 -- global 'x' + > local x = 10; print(x) + --> warning: locals do not survive across lines in interactive mode + --> 10 + > print(x) -- back to global 'x' + --> 20 + > do -- incomplete chunk + >> local x = 10; print(x) -- '>>' prompts for line completion + >> print(x) + >> end -- chunk completed + --> 10 + --> 10 ++
If the global variable _PROMPT contains a string,
then its value is used as the prompt.
@@ -11756,7 +12257,7 @@
Here we list the incompatibilities that you may find when moving a program -from Lua 5.3 to Lua 5.4. +from Lua 5.4 to Lua 5.5.
@@ -11803,51 +12304,23 @@
"1" + "2" now is an integer,
-not a float.
+The word global is a reserved word.
+Do not use it as a regular name.
__lt metamethod to emulate __le
-has been removed.
-When needed, this metamethod must be explicitly defined.
+A chain of __call metamethods can have at most 15 objects.
__gc metamethods that are not functions.
-Any value will be called, if present.
-(Non-callable values will generate a warning,
-like any other error when calling a finalizer.)
+In an error, a nil as the error object is replaced by a
+string message.
print does not call tostring
-to format its arguments;
-instead, it has this functionality hardwired.
-You should use __tostring to modify how values are printed.
-math.random
-now starts with a somewhat random seed.
-Moreover, it uses a different algorithm.
-utf8 library
-do not accept surrogates as valid code points.
-An extra parameter in these functions makes them more permissive.
-setpause" and "setstepmul"
-of the function collectgarbage are deprecated.
-You should use the new option "incremental" to set them.
-io.lines now returns four values,
-instead of just one.
-That can be a problem when it is used as the sole
-argument to another function that has optional parameters,
-such as in load(io.lines(filename, "L")).
-To fix that issue,
-you can wrap the call into parentheses,
-to adjust its number of results to one.
+Parameters for the garbage collection are not set
+with the options "incremental" and "generational";
+instead, there is a new option "param" to that end.
+Moreover, there were some changes in the parameters themselves.
lua_newuserdata,
-lua_setuservalue, and lua_getuservalue were
-replaced by lua_newuserdatauv,
-lua_setiuservalue, and lua_getiuservalue,
-which have an extra argument.
+In lua_call and related functions,
+the maximum value for the number of required results
+(nresults) is 250.
+If you really need a larger value,
+use LUA_MULTRET and then adjust the stack size.
+Previously, this limit was unspecified.
+lua_newstate has a third parameter,
+a seed for the hashing of strings.
+-For compatibility, the old names still work as macros assuming -one single user value. -Note, however, that userdata with zero user values -are more efficient memory-wise. +
lua_resetthread is deprecated;
+it is equivalent to lua_closethread with
+from being NULL.
lua_resume has an extra parameter.
-This out parameter returns the number of values on
-the top of the stack that were yielded or returned by the coroutine.
-(In previous versions,
-those values were the entire stack.)
+The function lua_setcstacklimit is deprecated.
+Calls to it can simply be removed.
lua_version returns the version number,
-instead of an address of the version number.
-The Lua core should work correctly with libraries using their
-own static copies of the same core,
-so there is no need to check whether they are using the same
-address space.
+The function lua_dump changed the way it keeps the stack
+through the calls to the writer function.
+(That was not specified in previous versions.)
+Also, it calls the writer function one extra time,
+to signal the end of the dump.
LUA_ERRGCMM was removed.
-Errors in finalizers are never propagated;
-instead, they generate a warning.
+Parameters for the garbage collection are not set
+with the options LUA_GCINC and LUA_GCGEN;
+instead, there is a new option LUA_GCPARAM to that end.
+Moreover, there were some changes in the parameters themselves.
LUA_GCSETPAUSE and LUA_GCSETSTEPMUL
-of the function lua_gc are deprecated.
-You should use the new option LUA_GCINC to set them.
+The function lua_pushvfstring now reports errors,
+instead of raising them.