<P>
<SMALL>
-Copyright © 2015–2016 Lua.org, PUC-Rio.
+Copyright © 2015–2017 Lua.org, PUC-Rio.
Freely available under the terms of the
<a href="http://www.lua.org/license.html">Lua license</a>.
</SMALL>
<!-- ====================================================================== -->
<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 $ -->
<p>
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.
To represent records, Lua uses the field name as an index.
The language supports this representation by
<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,
the values of table fields can be of any type.
In particular,
will call the message handler again.
If this loop goes on for too long,
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.)
<p>
Only objects that have an explicit construction
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,
and therefore are not removed from weak tables
(unless their associated values are collected).
<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
are two different, valid names.
As a convention,
-programs should avoid creating
+programs should avoid creating
names that start with an underscore followed by
one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
</pre>
<p>
-<em>Literal strings</em>
+A <em>short literal string</em>
can be delimited by matching single or double quotes,
and can contain the following C-like escape sequences:
'<code>\a</code>' (bell),
'<code>\\</code>' (backslash),
'<code>\"</code>' (quotation mark [double 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.
The escape sequence '<code>\z</code>' skips the following span
of white-space characters,
it is particularly useful to break and indent a long literal string
into multiple lines without adding the newlines and spaces
into the string contents.
+A short literal string cannot contain unescaped line breaks
+nor escapes not forming a valid escape sequence.
<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
with the escape sequence <code>\x<em>XX</em></code>,
where <em>XX</em> is a sequence of exactly two hexadecimal digits,
<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,
when the opening long bracket is immediately followed by a newline,
the newline is not included in the string.
</pre>
<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>)
can be written with an optional fractional part
and an optional decimal exponent,
Hexadecimal constants also accept an optional fractional part
plus an optional binary exponent,
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;
otherwise,
if its value fits in an integer,
<p>
-Floor division (<code>//</code>) is a division
+Floor division (<code>//</code>) is a division
that rounds the quotient towards minus infinity,
that is, the floor of the division of its operands.
The C API also converts both integers to floats and
floats to integers, as needed.
Moreover, string concatenation accepts numbers as arguments,
-besides strings.
+besides strings.
<p>
<p>
-All conversions from strings to numbers
+All conversions from strings to numbers
accept both a dot and the current locale mark
as the radix character.
(The Lua lexer, however, accepts only a dot.)
<p>
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>
-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>
-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>
- {10, 20, nil, 40}
+ (border == 0 or t[border] ~= nil) and t[border + 1] == nil
</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.
+<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>).
+
+
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>
Lua uses a <em>virtual stack</em> to pass values to and from C.
Each element in this stack represents a Lua value
(<b>nil</b>, number, string, etc.).
+Functions in the API can access this stack through the
+Lua state parameter that they receive.
<p>
which is independent of previous stacks and of stacks of
C functions that are still active.
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>).
(Lua will use exceptions if you compile it as C++;
search for <code>LUAI_THROW</code> in the source code for details.)
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;
that is, it does a long jump.
A <em>protected environment</em> uses <code>setjmp</code>
<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,
Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
and then calls <code>abort</code>,
<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>);
in particular, the error object is at the top of the stack.
However, there is no guarantee about stack space.
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>.
-
-
<p>
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
(directly or indirectly by calling another function that yields),
Lua cannot return to <code>foo</code> any more,
<p>
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>.
This original function then calls one of those three functions in the C API,
which we will call the <em>callee function</em>,
The function results are pushed onto the stack when the function returns.
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>.
-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,
but it does not ensure any extra space in the stack.
The function results are pushed onto the stack in direct order
<pre>int lua_getuservalue (lua_State *L, int index);</pre>
<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.
Returns <code>NULL</code> if it cannot create the thread or the state
(due to lack of memory).
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
passes to the allocator in every call.
<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
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>
</ul>
<p>
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.
In that case, it never raises a memory error.
<p>
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,
when called, invokes the corresponding C function.
<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
<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:
<pre>
<p>
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.
<p>
When the coroutine is resumed again,
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
from the previous function,
with the <code>n</code> results removed and
<p>
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
that includes <code>extramsg</code> as a comment:
<p>
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>
-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>
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.
+
+
<p>
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.
<p>
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>,
-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>.
<p>
Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
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>).
In particular,
the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</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>.
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.
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.
<p>
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
in the tables given as arguments.
<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.
<p>
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.
with the given name.
If this function fails, it returns <b>nil</b>,
plus a string describing the error and the error code.
+Otherwise, it returns true.
<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>,
plus a string describing the error and the error code.
+Otherwise, it returns true.
<p>
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>.
<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>
(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
before running any argument.
<p>
In case of unprotected errors in the script,
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>,
the interpreter calls this metamethod to produce the final message.
Otherwise, the interpreter converts the error object to a string
-
<P CLASS="footer">
Last update:
-Mon May 30 13:11:08 BRT 2016
+Mon Jan 9 13:30:53 BRST 2017
</P>
<!--
-Last change: revised for Lua 5.3.3
+Last change: revised for Lua 5.3.4
-->
</body></html>
projects / platform / upstream / lua.git / blobdiff