|
@@ -19,7 +19,7 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
|
|
|
|
|
|
<P>
|
|
<P>
|
|
<SMALL>
|
|
<SMALL>
|
|
-Copyright © 2015–2016 Lua.org, PUC-Rio.
|
|
|
|
|
|
+Copyright © 2015–2017 Lua.org, PUC-Rio.
|
|
Freely available under the terms of the
|
|
Freely available under the terms of the
|
|
<a href="http://www.lua.org/license.html">Lua license</a>.
|
|
<a href="http://www.lua.org/license.html">Lua license</a>.
|
|
</SMALL>
|
|
</SMALL>
|
|
@@ -35,7 +35,7 @@ Freely available under the terms of the
|
|
<!-- ====================================================================== -->
|
|
<!-- ====================================================================== -->
|
|
<p>
|
|
<p>
|
|
|
|
|
|
-<!-- $Id: manual.of,v 1.162 2016/05/30 15:57:03 roberto Exp $ -->
|
|
|
|
|
|
+<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -216,7 +216,7 @@ an associated value <b>nil</b>.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Tables are the sole data-structuring mechanism in Lua;
|
|
Tables are the sole data-structuring mechanism in Lua;
|
|
-they can be used to represent ordinary arrays, sequences,
|
|
|
|
|
|
+they can be used to represent ordinary arrays, lists,
|
|
symbol tables, sets, records, graphs, trees, etc.
|
|
symbol tables, sets, records, graphs, trees, etc.
|
|
To represent records, Lua uses the field name as an index.
|
|
To represent records, Lua uses the field name as an index.
|
|
The language supports this representation by
|
|
The language supports this representation by
|
|
@@ -226,13 +226,6 @@ There are several convenient ways to create tables in Lua
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-We use the term <em>sequence</em> to denote a table where
|
|
|
|
-the set of all positive numeric keys is equal to {1..<em>n</em>}
|
|
|
|
-for some non-negative integer <em>n</em>,
|
|
|
|
-which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>).
|
|
|
|
-
|
|
|
|
-
|
|
|
|
-<p>
|
|
|
|
Like indices,
|
|
Like indices,
|
|
the values of table fields can be of any type.
|
|
the values of table fields can be of any type.
|
|
In particular,
|
|
In particular,
|
|
@@ -378,6 +371,9 @@ so, an error inside the message handler
|
|
will call the message handler again.
|
|
will call the message handler again.
|
|
If this loop goes on for too long,
|
|
If this loop goes on for too long,
|
|
Lua breaks it and returns an appropriate message.
|
|
Lua breaks it and returns an appropriate message.
|
|
|
|
+(The message handler is called only for regular runtime errors.
|
|
|
|
+It is not called for memory-allocation errors
|
|
|
|
+nor for errors while running finalizers.)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -873,7 +869,7 @@ before the change takes effect.
|
|
<p>
|
|
<p>
|
|
Only objects that have an explicit construction
|
|
Only objects that have an explicit construction
|
|
are removed from weak tables.
|
|
are removed from weak tables.
|
|
-Values, such as numbers and light C functions,
|
|
|
|
|
|
+Values, such as numbers and light C functions,
|
|
are not subject to garbage collection,
|
|
are not subject to garbage collection,
|
|
and therefore are not removed from weak tables
|
|
and therefore are not removed from weak tables
|
|
(unless their associated values are collected).
|
|
(unless their associated values are collected).
|
|
@@ -1084,7 +1080,7 @@ Lua is a case-sensitive language:
|
|
<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
|
|
<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
|
|
are two different, valid names.
|
|
are two different, valid names.
|
|
As a convention,
|
|
As a convention,
|
|
-programs should avoid creating
|
|
|
|
|
|
+programs should avoid creating
|
|
names that start with an underscore followed by
|
|
names that start with an underscore followed by
|
|
one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
|
|
one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
|
|
|
|
|
|
@@ -1101,7 +1097,7 @@ The following strings denote other tokens:
|
|
</pre>
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-<em>Literal strings</em>
|
|
|
|
|
|
+A <em>short literal string</em>
|
|
can be delimited by matching single or double quotes,
|
|
can be delimited by matching single or double quotes,
|
|
and can contain the following C-like escape sequences:
|
|
and can contain the following C-like escape sequences:
|
|
'<code>\a</code>' (bell),
|
|
'<code>\a</code>' (bell),
|
|
@@ -1114,7 +1110,7 @@ and can contain the following C-like escape sequences:
|
|
'<code>\\</code>' (backslash),
|
|
'<code>\\</code>' (backslash),
|
|
'<code>\"</code>' (quotation mark [double quote]),
|
|
'<code>\"</code>' (quotation mark [double quote]),
|
|
and '<code>\'</code>' (apostrophe [single quote]).
|
|
and '<code>\'</code>' (apostrophe [single quote]).
|
|
-A backslash followed by a real newline
|
|
|
|
|
|
+A backslash followed by a line break
|
|
results in a newline in the string.
|
|
results in a newline in the string.
|
|
The escape sequence '<code>\z</code>' skips the following span
|
|
The escape sequence '<code>\z</code>' skips the following span
|
|
of white-space characters,
|
|
of white-space characters,
|
|
@@ -1122,13 +1118,13 @@ including line breaks;
|
|
it is particularly useful to break and indent a long literal string
|
|
it is particularly useful to break and indent a long literal string
|
|
into multiple lines without adding the newlines and spaces
|
|
into multiple lines without adding the newlines and spaces
|
|
into the string contents.
|
|
into the string contents.
|
|
|
|
+A short literal string cannot contain unescaped line breaks
|
|
|
|
+nor escapes not forming a valid escape sequence.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Strings in Lua can contain any 8-bit value, including embedded zeros,
|
|
|
|
-which can be specified as '<code>\0</code>'.
|
|
|
|
-More generally,
|
|
|
|
-we can specify any byte in a literal string by its numeric value.
|
|
|
|
|
|
+We can specify any byte in a short literal string by its numeric value
|
|
|
|
+(including embedded zeros).
|
|
This can be done
|
|
This can be done
|
|
with the escape sequence <code>\x<em>XX</em></code>,
|
|
with the escape sequence <code>\x<em>XX</em></code>,
|
|
where <em>XX</em> is a sequence of exactly two hexadecimal digits,
|
|
where <em>XX</em> is a sequence of exactly two hexadecimal digits,
|
|
@@ -1172,17 +1168,6 @@ is converted to a simple newline.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Any byte in a literal string not
|
|
|
|
-explicitly affected by the previous rules represents itself.
|
|
|
|
-However, Lua opens files for parsing in text mode,
|
|
|
|
-and the system file functions may have problems with
|
|
|
|
-some control characters.
|
|
|
|
-So, it is safer to represent
|
|
|
|
-non-text data as a quoted literal with
|
|
|
|
-explicit escape sequences for the non-text characters.
|
|
|
|
-
|
|
|
|
-
|
|
|
|
-<p>
|
|
|
|
For convenience,
|
|
For convenience,
|
|
when the opening long bracket is immediately followed by a newline,
|
|
when the opening long bracket is immediately followed by a newline,
|
|
the newline is not included in the string.
|
|
the newline is not included in the string.
|
|
@@ -1203,6 +1188,17 @@ the five literal strings below denote the same string:
|
|
</pre>
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
<p>
|
|
|
|
+Any byte in a literal string not
|
|
|
|
+explicitly affected by the previous rules represents itself.
|
|
|
|
+However, Lua opens files for parsing in text mode,
|
|
|
|
+and the system file functions may have problems with
|
|
|
|
+some control characters.
|
|
|
|
+So, it is safer to represent
|
|
|
|
+non-text data as a quoted literal with
|
|
|
|
+explicit escape sequences for the non-text characters.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
A <em>numeric constant</em> (or <em>numeral</em>)
|
|
A <em>numeric constant</em> (or <em>numeral</em>)
|
|
can be written with an optional fractional part
|
|
can be written with an optional fractional part
|
|
and an optional decimal exponent,
|
|
and an optional decimal exponent,
|
|
@@ -1212,7 +1208,7 @@ which start with <code>0x</code> or <code>0X</code>.
|
|
Hexadecimal constants also accept an optional fractional part
|
|
Hexadecimal constants also accept an optional fractional part
|
|
plus an optional binary exponent,
|
|
plus an optional binary exponent,
|
|
marked by a letter '<code>p</code>' or '<code>P</code>'.
|
|
marked by a letter '<code>p</code>' or '<code>P</code>'.
|
|
-A numeric constant with a radix point or an exponent
|
|
|
|
|
|
+A numeric constant with a radix point or an exponent
|
|
denotes a float;
|
|
denotes a float;
|
|
otherwise,
|
|
otherwise,
|
|
if its value fits in an integer,
|
|
if its value fits in an integer,
|
|
@@ -1897,7 +1893,7 @@ so that it works for non-integer exponents too.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Floor division (<code>//</code>) is a division
|
|
|
|
|
|
+Floor division (<code>//</code>) is a division
|
|
that rounds the quotient towards minus infinity,
|
|
that rounds the quotient towards minus infinity,
|
|
that is, the floor of the division of its operands.
|
|
that is, the floor of the division of its operands.
|
|
|
|
|
|
@@ -1959,7 +1955,7 @@ this is called the <em>usual rule</em>.
|
|
The C API also converts both integers to floats and
|
|
The C API also converts both integers to floats and
|
|
floats to integers, as needed.
|
|
floats to integers, as needed.
|
|
Moreover, string concatenation accepts numbers as arguments,
|
|
Moreover, string concatenation accepts numbers as arguments,
|
|
-besides strings.
|
|
|
|
|
|
+besides strings.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
@@ -1997,7 +1993,7 @@ is converted to the type (float or integer) required by the context
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-All conversions from strings to numbers
|
|
|
|
|
|
+All conversions from strings to numbers
|
|
accept both a dot and the current locale mark
|
|
accept both a dot and the current locale mark
|
|
as the radix character.
|
|
as the radix character.
|
|
(The Lua lexer, however, accepts only a dot.)
|
|
(The Lua lexer, however, accepts only a dot.)
|
|
@@ -2140,37 +2136,66 @@ Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&s
|
|
|
|
|
|
<p>
|
|
<p>
|
|
The length operator is denoted by the unary prefix operator <code>#</code>.
|
|
The length operator is denoted by the unary prefix operator <code>#</code>.
|
|
-The length of a string is its number of bytes
|
|
|
|
-(that is, the usual meaning of string length when each
|
|
|
|
-character is one byte).
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-A program can modify the behavior of the length operator for
|
|
|
|
-any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
|
|
|
|
|
|
+The length of a string is its number of bytes
|
|
|
|
+(that is, the usual meaning of string length when each
|
|
|
|
+character is one byte).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Unless a <code>__len</code> metamethod is given,
|
|
|
|
-the length of a table <code>t</code> is only defined if the
|
|
|
|
-table is a <em>sequence</em>,
|
|
|
|
-that is,
|
|
|
|
-the set of its positive numeric keys is equal to <em>{1..n}</em>
|
|
|
|
-for some non-negative integer <em>n</em>.
|
|
|
|
-In that case, <em>n</em> is its length.
|
|
|
|
-Note that a table like
|
|
|
|
|
|
+The length operator applied on a table
|
|
|
|
+returns a border in that table.
|
|
|
|
+A <em>border</em> in a table <code>t</code> is any natural number
|
|
|
|
+that satisfies the following condition:
|
|
|
|
|
|
<pre>
|
|
<pre>
|
|
- {10, 20, nil, 40}
|
|
|
|
|
|
+ (border == 0 or t[border] ~= nil) and t[border + 1] == nil
|
|
</pre><p>
|
|
</pre><p>
|
|
-is not a sequence, because it has the key <code>4</code>
|
|
|
|
-but does not have the key <code>3</code>.
|
|
|
|
-(So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal
|
|
|
|
-to the set of positive numeric keys of that table.)
|
|
|
|
-Note, however, that non-numeric keys do not interfere
|
|
|
|
|
|
+In words,
|
|
|
|
+a border is any (natural) index in a table
|
|
|
|
+where a non-nil value is followed by a nil value
|
|
|
|
+(or zero, when index 1 is nil).
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+A table with exactly one border is called a <em>sequence</em>.
|
|
|
|
+For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
|
|
|
|
+as it has only one border (5).
|
|
|
|
+The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
|
|
|
|
+and therefore it is not a sequence.
|
|
|
|
+The table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
|
|
|
|
+has three borders (0, 3, and 6),
|
|
|
|
+so it is not a sequence, too.
|
|
|
|
+The table <code>{}</code> is a sequence with border 0.
|
|
|
|
+Note that non-natural keys do not interfere
|
|
with whether a table is a sequence.
|
|
with whether a table is a sequence.
|
|
|
|
|
|
|
|
|
|
|
|
+<p>
|
|
|
|
+When <code>t</code> is a sequence,
|
|
|
|
+<code>#t</code> returns its only border,
|
|
|
|
+which corresponds to the intuitive notion of the length of the sequence.
|
|
|
|
+When <code>t</code> is not a sequence,
|
|
|
|
+<code>#t</code> can return any of its borders.
|
|
|
|
+(The exact one depends on details of
|
|
|
|
+the internal representation of the table,
|
|
|
|
+which in turn can depend on how the table was populated and
|
|
|
|
+the memory addresses of its non-numeric keys.)
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+The computation of the length of a table
|
|
|
|
+has a guaranteed worst time of <em>O(log n)</em>,
|
|
|
|
+where <em>n</em> is the largest natural key in the table.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+A program can modify the behavior of the length operator for
|
|
|
|
+any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
|
|
|
|
+
|
|
|
|
+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -2585,6 +2610,28 @@ However, you can change this behavior by compiling Lua
|
|
with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
|
|
with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
|
|
|
|
|
|
|
|
|
|
|
|
+<p>
|
|
|
|
+The Lua library is fully reentrant:
|
|
|
|
+it has no global variables.
|
|
|
|
+It keeps all information it needs in a dynamic structure,
|
|
|
|
+called the <em>Lua state</em>.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+Each Lua state has one or more threads,
|
|
|
|
+which correspond to independent, cooperative lines of execution.
|
|
|
|
+The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
|
|
|
|
+(Indirectly, through the thread, it also refers to the
|
|
|
|
+Lua state associated to the thread.)
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+A pointer to a thread must be passed as the first argument to
|
|
|
|
+every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
|
|
|
|
+which creates a Lua state from scratch and returns a pointer
|
|
|
|
+to the <em>main thread</em> in the new state.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
|
|
<h2>4.1 – <a name="4.1">The Stack</a></h2>
|
|
<h2>4.1 – <a name="4.1">The Stack</a></h2>
|
|
|
|
|
|
@@ -2592,6 +2639,8 @@ with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a>
|
|
Lua uses a <em>virtual stack</em> to pass values to and from C.
|
|
Lua uses a <em>virtual stack</em> to pass values to and from C.
|
|
Each element in this stack represents a Lua value
|
|
Each element in this stack represents a Lua value
|
|
(<b>nil</b>, number, string, etc.).
|
|
(<b>nil</b>, number, string, etc.).
|
|
|
|
+Functions in the API can access this stack through the
|
|
|
|
+Lua state parameter that they receive.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
@@ -2599,7 +2648,8 @@ Whenever Lua calls C, the called function gets a new stack,
|
|
which is independent of previous stacks and of stacks of
|
|
which is independent of previous stacks and of stacks of
|
|
C functions that are still active.
|
|
C functions that are still active.
|
|
This stack initially contains any arguments to the C function
|
|
This stack initially contains any arguments to the C function
|
|
-and it is where the C function pushes its results
|
|
|
|
|
|
+and it is where the C function can store temporary
|
|
|
|
+Lua values and must push its results
|
|
to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
|
|
to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
|
|
|
|
|
|
|
|
|
|
@@ -2791,8 +2841,7 @@ Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
|
|
(Lua will use exceptions if you compile it as C++;
|
|
(Lua will use exceptions if you compile it as C++;
|
|
search for <code>LUAI_THROW</code> in the source code for details.)
|
|
search for <code>LUAI_THROW</code> in the source code for details.)
|
|
When Lua faces any error
|
|
When Lua faces any error
|
|
-(such as a memory allocation error, type errors, syntax errors,
|
|
|
|
-and runtime errors)
|
|
|
|
|
|
+(such as a memory allocation error or a type error)
|
|
it <em>raises</em> an error;
|
|
it <em>raises</em> an error;
|
|
that is, it does a long jump.
|
|
that is, it does a long jump.
|
|
A <em>protected environment</em> uses <code>setjmp</code>
|
|
A <em>protected environment</em> uses <code>setjmp</code>
|
|
@@ -2801,6 +2850,17 @@ any error jumps to the most recent active recovery point.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
|
|
+Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
|
|
+Most functions in the API can raise an error,
|
|
|
|
+for instance due to a memory allocation error.
|
|
|
|
+The documentation for each function indicates whether
|
|
|
|
+it can raise errors.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
If an error happens outside any protected environment,
|
|
If an error happens outside any protected environment,
|
|
Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
|
|
Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
|
|
and then calls <code>abort</code>,
|
|
and then calls <code>abort</code>,
|
|
@@ -2811,6 +2871,23 @@ never returning
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
|
|
+The panic function,
|
|
|
|
+as its name implies,
|
|
|
|
+is a mechanism of last resort.
|
|
|
|
+Programs should avoid it.
|
|
|
|
+As a general rule,
|
|
|
|
+when a C function is called by Lua with a Lua state,
|
|
|
|
+it can do whatever it wants on that Lua state,
|
|
|
|
+as it should be already protected.
|
|
|
|
+However,
|
|
|
|
+when C code operates on other Lua states
|
|
|
|
+(e.g., a Lua parameter to the function,
|
|
|
|
+a Lua state stored in the registry, or
|
|
|
|
+the result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
|
|
|
|
+it should use them only in API calls that cannot raise errors.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
+<p>
|
|
The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
|
|
The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
|
|
in particular, the error object is at the top of the stack.
|
|
in particular, the error object is at the top of the stack.
|
|
However, there is no guarantee about stack space.
|
|
However, there is no guarantee about stack space.
|
|
@@ -2818,17 +2895,6 @@ To push anything on the stack,
|
|
the panic function must first check the available space (see <a href="#4.2">§4.2</a>).
|
|
the panic function must first check the available space (see <a href="#4.2">§4.2</a>).
|
|
|
|
|
|
|
|
|
|
-<p>
|
|
|
|
-Most functions in the API can raise an error,
|
|
|
|
-for instance due to a memory allocation error.
|
|
|
|
-The documentation for each function indicates whether
|
|
|
|
-it can raise errors.
|
|
|
|
-
|
|
|
|
-
|
|
|
|
-<p>
|
|
|
|
-Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
|
|
|
|
-
|
|
|
|
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -2836,7 +2902,7 @@ Inside a C function you can raise an error by calling <a href="#lua_error">
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
|
|
Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
|
|
-Therefore, if a C function <code>foo</code> calls an API function
|
|
|
|
|
|
+Therefore, if a C function <code>foo</code> calls an API function
|
|
and this API function yields
|
|
and this API function yields
|
|
(directly or indirectly by calling another function that yields),
|
|
(directly or indirectly by calling another function that yields),
|
|
Lua cannot return to <code>foo</code> any more,
|
|
Lua cannot return to <code>foo</code> any more,
|
|
@@ -2854,7 +2920,7 @@ All those functions receive a <em>continuation function</em>
|
|
|
|
|
|
<p>
|
|
<p>
|
|
We need to set some terminology to explain continuations.
|
|
We need to set some terminology to explain continuations.
|
|
-We have a C function called from Lua which we will call
|
|
|
|
|
|
+We have a C function called from Lua which we will call
|
|
the <em>original function</em>.
|
|
the <em>original function</em>.
|
|
This original function then calls one of those three functions in the C API,
|
|
This original function then calls one of those three functions in the C API,
|
|
which we will call the <em>callee function</em>,
|
|
which we will call the <em>callee function</em>,
|
|
@@ -3169,7 +3235,7 @@ when the function is called.
|
|
The function results are pushed onto the stack when the function returns.
|
|
The function results are pushed onto the stack when the function returns.
|
|
The number of results is adjusted to <code>nresults</code>,
|
|
The number of results is adjusted to <code>nresults</code>,
|
|
unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
|
|
unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
|
|
-In this case, all results from the function are pushed.
|
|
|
|
|
|
+In this case, all results from the function are pushed;
|
|
Lua takes care that the returned values fit into the stack space,
|
|
Lua takes care that the returned values fit into the stack space,
|
|
but it does not ensure any extra space in the stack.
|
|
but it does not ensure any extra space in the stack.
|
|
The function results are pushed onto the stack in direct order
|
|
The function results are pushed onto the stack in direct order
|
|
@@ -3655,7 +3721,7 @@ in particular, 0 means an empty stack.
|
|
<pre>int lua_getuservalue (lua_State *L, int index);</pre>
|
|
<pre>int lua_getuservalue (lua_State *L, int index);</pre>
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Pushes onto the stack the Lua value associated with the userdata
|
|
|
|
|
|
+Pushes onto the stack the Lua value associated with the full userdata
|
|
at the given index.
|
|
at the given index.
|
|
|
|
|
|
|
|
|
|
@@ -3998,7 +4064,8 @@ Creates a new thread running in a new, independent state.
|
|
Returns <code>NULL</code> if it cannot create the thread or the state
|
|
Returns <code>NULL</code> if it cannot create the thread or the state
|
|
(due to lack of memory).
|
|
(due to lack of memory).
|
|
The argument <code>f</code> is the allocator function;
|
|
The argument <code>f</code> is the allocator function;
|
|
-Lua does all memory allocation for this state through this function.
|
|
|
|
|
|
+Lua does all memory allocation for this state
|
|
|
|
+through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
|
|
The second argument, <code>ud</code>, is an opaque pointer that Lua
|
|
The second argument, <code>ud</code>, is an opaque pointer that Lua
|
|
passes to the allocator in every call.
|
|
passes to the allocator in every call.
|
|
|
|
|
|
@@ -4202,7 +4269,9 @@ error while running the message handler.
|
|
|
|
|
|
<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
|
|
<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
|
|
error while running a <code>__gc</code> metamethod.
|
|
error while running a <code>__gc</code> metamethod.
|
|
-(This error typically has no relation with the function being called.)
|
|
|
|
|
|
+For such errors, Lua does not call the message handler
|
|
|
|
+(as this kind of error typically has no relation
|
|
|
|
+with the function being called).
|
|
</li>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</ul>
|
|
@@ -4278,7 +4347,7 @@ The maximum value for <code>n</code> is 255.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
When <code>n</code> is zero,
|
|
When <code>n</code> is zero,
|
|
-this function creates a <em>light C function</em>,
|
|
|
|
|
|
+this function creates a <em>light C function</em>,
|
|
which is just a pointer to the C function.
|
|
which is just a pointer to the C function.
|
|
In that case, it never raises a memory error.
|
|
In that case, it never raises a memory error.
|
|
|
|
|
|
@@ -4292,7 +4361,7 @@ In that case, it never raises a memory error.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Pushes a C function onto the stack.
|
|
Pushes a C function onto the stack.
|
|
-This function receives a pointer to a C function
|
|
|
|
|
|
+This function receives a pointer to a C function
|
|
and pushes onto the stack a Lua value of type <code>function</code> that,
|
|
and pushes onto the stack a Lua value of type <code>function</code> that,
|
|
when called, invokes the corresponding C function.
|
|
when called, invokes the corresponding C function.
|
|
|
|
|
|
@@ -4667,7 +4736,7 @@ The reader function may return pieces of any size greater than zero.
|
|
<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
|
|
<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Sets the C function <code>f</code> as the new value of global <code>name</code>.
|
|
|
|
|
|
+Sets the C function <code>f</code> as the new value of global <code>name</code>.
|
|
It is defined as a macro:
|
|
It is defined as a macro:
|
|
|
|
|
|
<pre>
|
|
<pre>
|
|
@@ -4888,7 +4957,7 @@ If <code>index</code> is 0, then all stack elements are removed.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Pops a value from the stack and sets it as
|
|
Pops a value from the stack and sets it as
|
|
-the new value associated to the userdata at the given index.
|
|
|
|
|
|
+the new value associated to the full userdata at the given index.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -5302,7 +5371,7 @@ that will be passed as results to <a href="#lua_resume"><code>lua_resume</code><
|
|
<p>
|
|
<p>
|
|
When the coroutine is resumed again,
|
|
When the coroutine is resumed again,
|
|
Lua calls the given continuation function <code>k</code> to continue
|
|
Lua calls the given continuation function <code>k</code> to continue
|
|
-the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
|
|
|
|
|
|
+the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
|
|
This continuation function receives the same stack
|
|
This continuation function receives the same stack
|
|
from the previous function,
|
|
from the previous function,
|
|
with the <code>n</code> results removed and
|
|
with the <code>n</code> results removed and
|
|
@@ -6013,7 +6082,7 @@ If it is not, raises an error with a standard message (see <a href="#luaL_argerr
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Raises an error reporting a problem with argument <code>arg</code>
|
|
Raises an error reporting a problem with argument <code>arg</code>
|
|
-of the C function that called it,
|
|
|
|
|
|
+of the C function that called it,
|
|
using a standard message
|
|
using a standard message
|
|
that includes <code>extramsg</code> as a comment:
|
|
that includes <code>extramsg</code> as a comment:
|
|
|
|
|
|
@@ -6534,7 +6603,8 @@ The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_
|
|
<p>
|
|
<p>
|
|
This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
|
|
This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
|
|
but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
|
|
but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
|
|
-if it cannot open/read the file or the file has a wrong mode.
|
|
|
|
|
|
+for file-related errors
|
|
|
|
+(e.g., it cannot open or read the file).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
@@ -6727,6 +6797,11 @@ If the result is <code>NULL</code>
|
|
its length is considered zero.
|
|
its length is considered zero.
|
|
|
|
|
|
|
|
|
|
|
|
+<p>
|
|
|
|
+This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
|
|
|
|
+so all conversions and caveats of that function apply here.
|
|
|
|
+
|
|
|
|
+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -7674,7 +7749,7 @@ Returns true when the running coroutine can yield.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
A running coroutine is yieldable if it is not the main thread and
|
|
A running coroutine is yieldable if it is not the main thread and
|
|
-it is not inside a non-yieldable C function.
|
|
|
|
|
|
+it is not inside a non-yieldable C function.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -7876,8 +7951,8 @@ The path used by <a href="#pdf-require"><code>require</code></a> to search for a
|
|
<p>
|
|
<p>
|
|
Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
|
|
Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
|
|
it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
|
|
it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
|
|
-using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
|
|
|
|
-or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
|
|
|
|
|
|
+using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>,
|
|
|
|
+or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
|
|
or a default path defined in <code>luaconf.h</code>.
|
|
or a default path defined in <code>luaconf.h</code>.
|
|
|
|
|
|
|
|
|
|
@@ -8434,7 +8509,7 @@ its default value is 1 and can be negative.
|
|
<p>
|
|
<p>
|
|
Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
|
|
Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
|
|
packed (that is, serialized in binary form)
|
|
packed (that is, serialized in binary form)
|
|
-according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
|
|
|
|
|
|
+according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -8485,7 +8560,8 @@ If <code>j</code> is absent, then it is assumed to be equal to -1
|
|
In particular,
|
|
In particular,
|
|
the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
|
|
the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
|
|
with length <code>j</code>,
|
|
with length <code>j</code>,
|
|
-and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
|
|
|
|
|
|
+and <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
|
|
|
|
+returns a suffix of <code>s</code>
|
|
with length <code>i</code>.
|
|
with length <code>i</code>.
|
|
|
|
|
|
|
|
|
|
@@ -8902,7 +8978,7 @@ Returns the number of UTF-8 characters in string <code>s</code>
|
|
that start between positions <code>i</code> and <code>j</code> (both inclusive).
|
|
that start between positions <code>i</code> and <code>j</code> (both inclusive).
|
|
The default for <code>i</code> is 1 and for <code>j</code> is -1.
|
|
The default for <code>i</code> is 1 and for <code>j</code> is -1.
|
|
If it finds any invalid byte sequence,
|
|
If it finds any invalid byte sequence,
|
|
-returns a false value plus the position of the first invalid byte.
|
|
|
|
|
|
+returns a false value plus the position of the first invalid byte.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -8946,8 +9022,7 @@ It provides all its functions inside the table <a name="pdf-table"><code>table</
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Remember that, whenever an operation needs the length of a table,
|
|
Remember that, whenever an operation needs the length of a table,
|
|
-the table must be a proper sequence
|
|
|
|
-or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>).
|
|
|
|
|
|
+all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>).
|
|
All functions ignore non-numeric keys
|
|
All functions ignore non-numeric keys
|
|
in the tables given as arguments.
|
|
in the tables given as arguments.
|
|
|
|
|
|
@@ -9063,9 +9138,8 @@ Otherwise, no valid sort may be possible.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-The sort algorithm is not stable;
|
|
|
|
-that is, elements not comparable by the given order
|
|
|
|
-(e.g., equal elements)
|
|
|
|
|
|
+The sort algorithm is not stable:
|
|
|
|
+elements considered equal by the given order
|
|
may have their relative positions changed by the sort.
|
|
may have their relative positions changed by the sort.
|
|
|
|
|
|
|
|
|
|
@@ -9401,7 +9475,7 @@ or <b>nil</b> if <code>x</code> is not a number.
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Returns a boolean,
|
|
Returns a boolean,
|
|
-true if integer <code>m</code> is below integer <code>n</code> when
|
|
|
|
|
|
+true if and only if integer <code>m</code> is below integer <code>n</code> when
|
|
they are compared as unsigned integers.
|
|
they are compared as unsigned integers.
|
|
|
|
|
|
|
|
|
|
@@ -9987,6 +10061,7 @@ Deletes the file (or empty directory, on POSIX systems)
|
|
with the given name.
|
|
with the given name.
|
|
If this function fails, it returns <b>nil</b>,
|
|
If this function fails, it returns <b>nil</b>,
|
|
plus a string describing the error and the error code.
|
|
plus a string describing the error and the error code.
|
|
|
|
+Otherwise, it returns true.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -9996,9 +10071,10 @@ plus a string describing the error and the error code.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-Renames file or directory named <code>oldname</code> to <code>newname</code>.
|
|
|
|
|
|
+Renames the file or directory named <code>oldname</code> to <code>newname</code>.
|
|
If this function fails, it returns <b>nil</b>,
|
|
If this function fails, it returns <b>nil</b>,
|
|
plus a string describing the error and the error code.
|
|
plus a string describing the error and the error code.
|
|
|
|
+Otherwise, it returns true.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -10291,7 +10367,7 @@ represent variables with no known names
|
|
|
|
|
|
<p>
|
|
<p>
|
|
Returns the Lua value associated to <code>u</code>.
|
|
Returns the Lua value associated to <code>u</code>.
|
|
-If <code>u</code> is not a userdata,
|
|
|
|
|
|
+If <code>u</code> is not a full userdata,
|
|
returns <b>nil</b>.
|
|
returns <b>nil</b>.
|
|
|
|
|
|
|
|
|
|
@@ -10490,7 +10566,7 @@ and as <code>lua -</code> otherwise.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<p>
|
|
-When called without option <code>-E</code>,
|
|
|
|
|
|
+When called without option <code>-E</code>,
|
|
the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
|
|
the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
|
|
(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
|
|
(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
|
|
before running any argument.
|
|
before running any argument.
|
|
@@ -10582,7 +10658,7 @@ its value is used as the secondary prompt
|
|
<p>
|
|
<p>
|
|
In case of unprotected errors in the script,
|
|
In case of unprotected errors in the script,
|
|
the interpreter reports the error to the standard error stream.
|
|
the interpreter reports the error to the standard error stream.
|
|
-If the error object is not a string but
|
|
|
|
|
|
+If the error object is not a string but
|
|
has a metamethod <code>__tostring</code>,
|
|
has a metamethod <code>__tostring</code>,
|
|
the interpreter calls this metamethod to produce the final message.
|
|
the interpreter calls this metamethod to produce the final message.
|
|
Otherwise, the interpreter converts the error object to a string
|
|
Otherwise, the interpreter converts the error object to a string
|
|
@@ -10897,13 +10973,12 @@ and LiteralString, see <a href="#3.1">§3.1</a>.)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-
|
|
|
|
<P CLASS="footer">
|
|
<P CLASS="footer">
|
|
Last update:
|
|
Last update:
|
|
-Mon May 30 13:11:08 BRT 2016
|
|
|
|
|
|
+Mon Jan 9 13:30:53 BRST 2017
|
|
</P>
|
|
</P>
|
|
<!--
|
|
<!--
|
|
-Last change: revised for Lua 5.3.3
|
|
|
|
|
|
+Last change: revised for Lua 5.3.4
|
|
-->
|
|
-->
|
|
|
|
|
|
</body></html>
|
|
</body></html>
|