4587 lines
127 KiB
HTML
4587 lines
127 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
|
|
<head>
|
|
<title>Teliva Reference Manual</title>
|
|
<link rel="stylesheet" type="text/css" href="lua.css">
|
|
<link rel="stylesheet" type="text/css" href="manual.css">
|
|
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<h1>
|
|
Teliva Reference Manual
|
|
</h1>
|
|
|
|
<small>
|
|
by Kartik Agaram
|
|
</small>
|
|
|
|
<p>
|
|
Based on <a href="http://www.lua.org/">Lua 5.1</a> by Roberto Ierusalimschy,
|
|
Luiz Henrique de Figueiredo, Waldemar Celes
|
|
|
|
<p>
|
|
<small>
|
|
Copyright © 2006–2012 Lua.org, PUC-Rio.
|
|
Freely available under the terms of the
|
|
<a href="http://www.lua.org/license.html">Lua license</a>.
|
|
</small>
|
|
|
|
<hr>
|
|
<p>
|
|
|
|
<a href="contents.html#contents">contents</A>
|
|
·
|
|
<a href="contents.html#index">index</A>
|
|
·
|
|
<A HREF="http://www.lua.org/manual/">other versions</A>
|
|
|
|
<!-- ====================================================================== -->
|
|
<p>
|
|
|
|
<!-- $Id: manual.of,v 1.49.1.2 2012/01/13 20:23:26 roberto Exp $ -->
|
|
|
|
|
|
|
|
|
|
<h1>1 - <a name="1">Introduction</a></h1>
|
|
|
|
Teliva is a platform based on Lua for sandboxed software packaged with an
|
|
environment for making changes to it. For a more detailed introduction, see
|
|
<a href='../README.md'>the Readme</a>.
|
|
|
|
<p>
|
|
Teliva is free software, and is provided as usual with no guarantees, as
|
|
stated in its license.
|
|
|
|
<p>
|
|
This manual is based on the Lua manual. Lua features absent in Teliva should
|
|
be absent in this manual as well. <span class='teliva'>Features added to
|
|
Teliva above and beyond Lua will be described in text like this.</span>
|
|
|
|
<p>
|
|
For a discussion of the decisions behind the design of Lua,
|
|
see the technical papers available at Lua's web site.
|
|
For a detailed introduction to programming in Lua,
|
|
see Roberto's book, <em>Programming in Lua (Second Edition)</em>.
|
|
|
|
|
|
|
|
<h1>2 - <a name="2">The Language</a></h1>
|
|
|
|
<p>
|
|
This section describes the lexis, the syntax, and the semantics of Lua.
|
|
In other words,
|
|
this section describes
|
|
which tokens are valid,
|
|
how they can be combined,
|
|
and what their combinations mean.
|
|
|
|
|
|
<p>
|
|
The language constructs will be explained using the usual extended BNF notation,
|
|
in which
|
|
{<em>a</em>} means 0 or more <em>a</em>'s, and
|
|
[<em>a</em>] means an optional <em>a</em>.
|
|
Non-terminals are shown like non-terminal,
|
|
keywords are shown like <b>kword</b>,
|
|
and other terminal symbols are shown like `<b>=</b>´.
|
|
The complete syntax of Lua can be found in <a href="#8">§8</a>
|
|
at the end of this manual.
|
|
|
|
|
|
|
|
<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2>
|
|
|
|
<p>
|
|
<em>Names</em>
|
|
(also called <em>identifiers</em>)
|
|
in Lua can be any string of letters,
|
|
digits, and underscores,
|
|
not beginning with a digit.
|
|
This coincides with the definition of names in most languages.
|
|
(The definition of letter depends on the current locale:
|
|
any character considered alphabetic by the current locale
|
|
can be used in an identifier.)
|
|
Identifiers are used to name variables and table fields.
|
|
|
|
|
|
<p>
|
|
The following <em>keywords</em> are reserved
|
|
and cannot be used as names:
|
|
|
|
|
|
<pre>
|
|
and break do else elseif
|
|
end false for function if
|
|
in local nil not or
|
|
repeat return then true until while
|
|
</pre>
|
|
|
|
<p>
|
|
Lua is a case-sensitive language:
|
|
<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
|
|
are two different, valid names.
|
|
As a convention, names starting with an underscore followed by
|
|
uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>)
|
|
are reserved for internal global variables used by Lua.
|
|
|
|
|
|
<p>
|
|
The following strings denote other tokens:
|
|
|
|
<pre>
|
|
+ - * / % ^ #
|
|
== ~= <= >= < > =
|
|
( ) { } [ ]
|
|
; : , . .. ...
|
|
</pre>
|
|
|
|
<p>
|
|
<em>Literal strings</em>
|
|
can be delimited by matching single or double quotes,
|
|
and can contain the following C-like escape sequences:
|
|
'<code>\a</code>' (bell),
|
|
'<code>\b</code>' (backspace),
|
|
'<code>\f</code>' (form feed),
|
|
'<code>\n</code>' (newline),
|
|
'<code>\r</code>' (carriage return),
|
|
'<code>\t</code>' (horizontal tab),
|
|
'<code>\v</code>' (vertical tab),
|
|
'<code>\\</code>' (backslash),
|
|
'<code>\"</code>' (quotation mark [double quote]),
|
|
and '<code>\'</code>' (apostrophe [single quote]).
|
|
Moreover, a backslash followed by a real newline
|
|
results in a newline in the string.
|
|
A character in a string can also be specified by its numerical value
|
|
using the escape sequence <code>\<em>ddd</em></code>,
|
|
where <em>ddd</em> is a sequence of up to three decimal digits.
|
|
(Note that if a numerical escape is to be followed by a digit,
|
|
it must be expressed using exactly three digits.)
|
|
Strings in Lua can contain any 8-bit value, including embedded zeros,
|
|
which can be specified as '<code>\0</code>'.
|
|
|
|
|
|
<p>
|
|
Literal strings can also be defined using a long format
|
|
enclosed by <em>long brackets</em>.
|
|
We define an <em>opening long bracket of level <em>n</em></em> as an opening
|
|
square bracket followed by <em>n</em> equal signs followed by another
|
|
opening square bracket.
|
|
So, an opening long bracket of level 0 is written as <code>[[</code>,
|
|
an opening long bracket of level 1 is written as <code>[=[</code>,
|
|
and so on.
|
|
A <em>closing long bracket</em> is defined similarly;
|
|
for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
|
|
A long string starts with an opening long bracket of any level and
|
|
ends at the first closing long bracket of the same level.
|
|
Literals in this bracketed form can run for several lines,
|
|
do not interpret any escape sequences,
|
|
and ignore long brackets of any other level.
|
|
They can contain anything except a closing bracket of the proper level.
|
|
|
|
|
|
<p>
|
|
For convenience,
|
|
when the opening long bracket is immediately followed by a newline,
|
|
the newline is not included in the string.
|
|
As an example, in a system using ASCII
|
|
(in which '<code>a</code>' is coded as 97,
|
|
newline is coded as 10, and '<code>1</code>' is coded as 49),
|
|
the five literal strings below denote the same string:
|
|
|
|
<pre>
|
|
a = 'alo\n123"'
|
|
a = "alo\n123\""
|
|
a = '\97lo\10\04923"'
|
|
a = [[alo
|
|
123"]]
|
|
a = [==[
|
|
alo
|
|
123"]==]
|
|
</pre>
|
|
|
|
<p>
|
|
A <em>numerical constant</em> can be written with an optional decimal part
|
|
and an optional decimal exponent.
|
|
Lua also accepts integer hexadecimal constants,
|
|
by prefixing them with <code>0x</code>.
|
|
Examples of valid numerical constants are
|
|
|
|
<pre>
|
|
3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
|
|
</pre>
|
|
|
|
<p>
|
|
A <em>comment</em> starts with a double hyphen (<code>--</code>)
|
|
anywhere outside a string.
|
|
If the text immediately after <code>--</code> is not an opening long bracket,
|
|
the comment is a <em>short comment</em>,
|
|
which runs until the end of the line.
|
|
Otherwise, it is a <em>long comment</em>,
|
|
which runs until the corresponding closing long bracket.
|
|
Long comments are frequently used to disable code temporarily.
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.2 - <a name="2.2">Values and Types</a></h2>
|
|
|
|
<p>
|
|
Lua is a <em>dynamically typed language</em>.
|
|
This means that
|
|
variables do not have types; only values do.
|
|
There are no type definitions in the language.
|
|
All values carry their own type.
|
|
|
|
|
|
<p>
|
|
All values in Lua are <em>first-class values</em>.
|
|
This means that all values can be stored in variables,
|
|
passed as arguments to other functions, and returned as results.
|
|
|
|
|
|
<p>
|
|
There are eight basic types in Lua:
|
|
<em>nil</em>, <em>boolean</em>, <em>number</em>,
|
|
<em>string</em>, <em>function</em>, <em>userdata</em>,
|
|
<em>thread</em>, and <em>table</em>.
|
|
<em>Nil</em> is the type of the value <b>nil</b>,
|
|
whose main property is to be different from any other value;
|
|
it usually represents the absence of a useful value.
|
|
<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
|
|
Both <b>nil</b> and <b>false</b> make a condition false;
|
|
any other value makes it true.
|
|
<em>Number</em> represents real (double-precision floating-point) numbers.
|
|
(It is easy to build Lua interpreters that use other
|
|
internal representations for numbers,
|
|
such as single-precision float or long integers;
|
|
see file <code>luaconf.h</code>.)
|
|
<em>String</em> represents arrays of characters.
|
|
|
|
Lua is 8-bit clean:
|
|
strings can contain any 8-bit character,
|
|
including embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>).
|
|
|
|
|
|
<p>
|
|
<div class='teliva'>The type <em>userdata</em> is opaque to Teliva, and
|
|
used by low-level code to manage details of C data stored in Lua
|
|
variables. Unlike Lua, Teliva doesn't support creating or managing userdata
|
|
since it doesn't permit extension by C libraries. This manual doesn't allude
|
|
to userdata further.</div>
|
|
|
|
<p>
|
|
The type <em>thread</em> represents independent threads of execution
|
|
and it is used to implement coroutines (see <a href="#2.11">§2.11</a>).
|
|
Do not confuse Lua threads with operating-system threads.
|
|
Lua supports coroutines on all systems,
|
|
even those that do not support threads.
|
|
|
|
|
|
<p>
|
|
The type <em>table</em> implements associative arrays,
|
|
that is, arrays that can be indexed not only with numbers,
|
|
but with any value (except <b>nil</b>).
|
|
Tables can be <em>heterogeneous</em>;
|
|
that is, they can contain values of all types (except <b>nil</b>).
|
|
Tables are the sole data structuring mechanism in Lua;
|
|
they can be used to represent ordinary arrays,
|
|
symbol tables, sets, records, graphs, trees, etc.
|
|
To represent records, Lua uses the field name as an index.
|
|
The language supports this representation by
|
|
providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
|
|
There are several convenient ways to create tables in Lua
|
|
(see <a href="#2.5.7">§2.5.7</a>).
|
|
|
|
|
|
<p>
|
|
Like indices,
|
|
the value of a table field can be of any type (except <b>nil</b>).
|
|
In particular,
|
|
because functions are first-class values,
|
|
table fields can contain functions.
|
|
Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>).
|
|
|
|
|
|
<p>
|
|
Tables, functions and threads are <em>objects</em>:
|
|
variables do not actually <em>contain</em> these values,
|
|
only <em>references</em> to them.
|
|
Assignment, parameter passing, and function returns
|
|
always manipulate references to such values;
|
|
these operations do not imply any kind of copy.
|
|
|
|
|
|
<p>
|
|
The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
|
|
of a given value.
|
|
|
|
|
|
|
|
<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3>
|
|
|
|
<p>
|
|
Lua provides automatic conversion between
|
|
string and number values at run time.
|
|
Any arithmetic operation applied to a string tries to convert
|
|
this string to a number, following the usual conversion rules.
|
|
Conversely, whenever a number is used where a string is expected,
|
|
the number is converted to a string, in a reasonable format.
|
|
For complete control over how numbers are converted to strings,
|
|
use the <code>format</code> function from the string library
|
|
(see <a href="#pdf-string.format"><code>string.format</code></a>).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.3 - <a name="2.3">Variables</a></h2>
|
|
|
|
<p>
|
|
Variables are places that store values.
|
|
|
|
There are three kinds of variables in Lua:
|
|
global variables, local variables, and table fields.
|
|
|
|
|
|
<p>
|
|
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):
|
|
|
|
<pre>
|
|
var ::= Name
|
|
</pre><p>
|
|
Name denotes identifiers, as defined in <a href="#2.1">§2.1</a>.
|
|
|
|
|
|
<p>
|
|
Any variable is assumed to be global unless explicitly declared
|
|
as a local (see <a href="#2.4.7">§2.4.7</a>).
|
|
Local variables are <em>lexically scoped</em>:
|
|
local variables can be freely accessed by functions
|
|
defined inside their scope (see <a href="#2.6">§2.6</a>).
|
|
|
|
|
|
<p>
|
|
Before the first assignment to a variable, its value is <b>nil</b>.
|
|
|
|
|
|
<p>
|
|
Square brackets are used to index a table:
|
|
|
|
<pre>
|
|
var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´
|
|
</pre><p>
|
|
The meaning of accesses to global variables
|
|
and table fields can be changed via metatables.
|
|
An access to an indexed variable <code>t[i]</code> is equivalent to
|
|
a call <code>gettable_event(t,i)</code>.
|
|
(See <a href="#2.8">§2.8</a> for a complete description of the
|
|
<code>gettable_event</code> function.
|
|
This function is not defined or callable in Lua.
|
|
We use it here only for explanatory purposes.)
|
|
|
|
|
|
<p>
|
|
The syntax <code>var.Name</code> is just syntactic sugar for
|
|
<code>var["Name"]</code>:
|
|
|
|
<pre>
|
|
var ::= prefixexp `<b>.</b>´ Name
|
|
</pre>
|
|
|
|
<p>
|
|
All global variables live as fields in ordinary Lua tables,
|
|
called <em>environment tables</em> or simply
|
|
<em>environments</em> (see <a href="#2.9">§2.9</a>).
|
|
Each function has its own reference to an environment,
|
|
so that all global variables in this function
|
|
will refer to this environment table.
|
|
When a function is created,
|
|
it inherits the environment from the function that created it.
|
|
To get the environment table of a Lua function,
|
|
you call <a href="#pdf-getfenv"><code>getfenv</code></a>.
|
|
To replace it,
|
|
you call <a href="#pdf-setfenv"><code>setfenv</code></a>.
|
|
|
|
|
|
<p>
|
|
An access to a global variable <code>x</code>
|
|
is equivalent to <code>_env.x</code>,
|
|
which in turn is equivalent to
|
|
|
|
<pre>
|
|
gettable_event(_env, "x")
|
|
</pre><p>
|
|
where <code>_env</code> is the environment of the running function.
|
|
(See <a href="#2.8">§2.8</a> for a complete description of the
|
|
<code>gettable_event</code> function.
|
|
This function is not defined or callable in Lua.
|
|
Similarly, the <code>_env</code> variable is not defined in Lua.
|
|
We use them here only for explanatory purposes.)
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.4 - <a name="2.4">Statements</a></h2>
|
|
|
|
<p>
|
|
Lua supports an almost conventional set of statements,
|
|
similar to those in Pascal or C.
|
|
This set includes
|
|
assignments, control structures, function calls,
|
|
and variable declarations.
|
|
|
|
|
|
|
|
<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3>
|
|
|
|
<p>
|
|
The unit of execution of Lua is called a <em>chunk</em>.
|
|
A chunk is simply a sequence of statements,
|
|
which are executed sequentially.
|
|
Each statement can be optionally followed by a semicolon:
|
|
|
|
<pre>
|
|
chunk ::= {stat [`<b>;</b>´]}
|
|
</pre><p>
|
|
There are no empty statements and thus '<code>;;</code>' is not legal.
|
|
|
|
|
|
<p>
|
|
Lua handles a chunk as the body of an anonymous function
|
|
with a variable number of arguments
|
|
(see <a href="#2.5.9">§2.5.9</a>).
|
|
As such, chunks can define local variables,
|
|
receive arguments, and return values.
|
|
|
|
|
|
<p>
|
|
A chunk can be stored in a file or in a string inside the host program.
|
|
To execute a chunk,
|
|
Lua first pre-compiles the chunk into instructions for a virtual machine,
|
|
and then it executes the compiled code
|
|
with an interpreter for the virtual machine.
|
|
|
|
|
|
<p>
|
|
Chunks can also be pre-compiled into binary form;
|
|
see program <code>luac</code> for details.
|
|
Programs in source and compiled forms are interchangeable;
|
|
Lua automatically detects the file type and acts accordingly.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p>
|
|
A block is a list of statements;
|
|
syntactically, a block is the same as a chunk:
|
|
|
|
<pre>
|
|
block ::= chunk
|
|
</pre>
|
|
|
|
<p>
|
|
A block can be explicitly delimited to produce a single statement:
|
|
|
|
<pre>
|
|
stat ::= <b>do</b> block <b>end</b>
|
|
</pre><p>
|
|
Explicit blocks are useful
|
|
to control the scope of variable declarations.
|
|
Explicit blocks are also sometimes used to
|
|
add a <b>return</b> or <b>break</b> statement in the middle
|
|
of another block (see <a href="#2.4.4">§2.4.4</a>).
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3>
|
|
|
|
<p>
|
|
Lua allows multiple assignments.
|
|
Therefore, the syntax for assignment
|
|
defines a list of variables on the left side
|
|
and a list of expressions on the right side.
|
|
The elements in both lists are separated by commas:
|
|
|
|
<pre>
|
|
stat ::= varlist `<b>=</b>´ explist
|
|
varlist ::= var {`<b>,</b>´ var}
|
|
explist ::= exp {`<b>,</b>´ exp}
|
|
</pre><p>
|
|
Expressions are discussed in <a href="#2.5">§2.5</a>.
|
|
|
|
|
|
<p>
|
|
Before the assignment,
|
|
the list of values is <em>adjusted</em> to the length of
|
|
the list of variables.
|
|
If there are more values than needed,
|
|
the excess values are thrown away.
|
|
If there are fewer values than needed,
|
|
the list is extended with as many <b>nil</b>'s as needed.
|
|
If the list of expressions ends with a function call,
|
|
then all values returned by that call enter the list of values,
|
|
before the adjustment
|
|
(except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>).
|
|
|
|
|
|
<p>
|
|
The assignment statement first evaluates all its expressions
|
|
and only then are the assignments performed.
|
|
Thus the code
|
|
|
|
<pre>
|
|
i = 3
|
|
i, a[i] = i+1, 20
|
|
</pre><p>
|
|
sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
|
|
because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
|
|
before it is assigned 4.
|
|
Similarly, the line
|
|
|
|
<pre>
|
|
x, y = y, x
|
|
</pre><p>
|
|
exchanges the values of <code>x</code> and <code>y</code>,
|
|
and
|
|
|
|
<pre>
|
|
x, y, z = y, z, x
|
|
</pre><p>
|
|
cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
|
|
|
|
|
|
<p>
|
|
The meaning of assignments to global variables
|
|
and table fields can be changed via metatables.
|
|
An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
|
|
<code>settable_event(t,i,val)</code>.
|
|
(See <a href="#2.8">§2.8</a> for a complete description of the
|
|
<code>settable_event</code> function.
|
|
This function is not defined or callable in Lua.
|
|
We use it here only for explanatory purposes.)
|
|
|
|
|
|
<p>
|
|
An assignment to a global variable <code>x = val</code>
|
|
is equivalent to the assignment
|
|
<code>_env.x = val</code>,
|
|
which in turn is equivalent to
|
|
|
|
<pre>
|
|
settable_event(_env, "x", val)
|
|
</pre><p>
|
|
where <code>_env</code> is the environment of the running function.
|
|
(The <code>_env</code> variable is not defined in Lua.
|
|
We use it here only for explanatory purposes.)
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p>
|
|
The control structures
|
|
<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
|
|
familiar syntax:
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
|
|
stat ::= <b>repeat</b> block <b>until</b> exp
|
|
stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
|
|
</pre><p>
|
|
Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>).
|
|
|
|
|
|
<p>
|
|
The condition expression of a
|
|
control structure can return any value.
|
|
Both <b>false</b> and <b>nil</b> are considered false.
|
|
All values different from <b>nil</b> and <b>false</b> are considered true
|
|
(in particular, the number 0 and the empty string are also true).
|
|
|
|
|
|
<p>
|
|
In the <b>repeat</b>–<b>until</b> loop,
|
|
the inner block does not end at the <b>until</b> keyword,
|
|
but only after the condition.
|
|
So, the condition can refer to local variables
|
|
declared inside the loop block.
|
|
|
|
|
|
<p>
|
|
The <b>return</b> statement is used to return values
|
|
from a function or a chunk (which is just a function).
|
|
|
|
Functions and chunks can return more than one value,
|
|
and so the syntax for the <b>return</b> statement is
|
|
|
|
<pre>
|
|
stat ::= <b>return</b> [explist]
|
|
</pre>
|
|
|
|
<p>
|
|
The <b>break</b> statement is used to terminate the execution of a
|
|
<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
|
|
skipping to the next statement after the loop:
|
|
|
|
|
|
<pre>
|
|
stat ::= <b>break</b>
|
|
</pre><p>
|
|
A <b>break</b> ends the innermost enclosing loop.
|
|
|
|
|
|
<p>
|
|
The <b>return</b> and <b>break</b>
|
|
statements can only be written as the <em>last</em> statement of a block.
|
|
If it is really necessary to <b>return</b> or <b>break</b> in the
|
|
middle of a block,
|
|
then an explicit inner block can be used,
|
|
as in the idioms
|
|
<code>do return end</code> and <code>do break end</code>,
|
|
because now <b>return</b> and <b>break</b> are the last statements in
|
|
their (inner) blocks.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3>
|
|
|
|
<p>
|
|
|
|
The <b>for</b> statement has two forms:
|
|
one numeric and one generic.
|
|
|
|
|
|
<p>
|
|
The numeric <b>for</b> loop repeats a block of code while a
|
|
control variable runs through an arithmetic progression.
|
|
It has the following syntax:
|
|
|
|
<pre>
|
|
stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b>
|
|
</pre><p>
|
|
The <em>block</em> is repeated for <em>name</em> starting at the value of
|
|
the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
|
|
third <em>exp</em>.
|
|
More precisely, a <b>for</b> statement like
|
|
|
|
<pre>
|
|
for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
|
|
</pre><p>
|
|
is equivalent to the code:
|
|
|
|
<pre>
|
|
do
|
|
local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
|
|
if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
|
|
while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do
|
|
local v = <em>var</em>
|
|
<em>block</em>
|
|
<em>var</em> = <em>var</em> + <em>step</em>
|
|
end
|
|
end
|
|
</pre><p>
|
|
Note the following:
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
All three control expressions are evaluated only once,
|
|
before the loop starts.
|
|
They must all result in numbers.
|
|
</li>
|
|
|
|
<li>
|
|
<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
|
|
The names shown here are for explanatory purposes only.
|
|
</li>
|
|
|
|
<li>
|
|
If the third expression (the step) is absent,
|
|
then a step of 1 is used.
|
|
</li>
|
|
|
|
<li>
|
|
You can use <b>break</b> to exit a <b>for</b> loop.
|
|
</li>
|
|
|
|
<li>
|
|
The loop variable <code>v</code> is local to the loop;
|
|
you cannot use its value after the <b>for</b> ends or is broken.
|
|
If you need this value,
|
|
assign it to another variable before breaking or exiting the loop.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<p>
|
|
The generic <b>for</b> statement works over functions,
|
|
called <em>iterators</em>.
|
|
On each iteration, the iterator function is called to produce a new value,
|
|
stopping when this new value is <b>nil</b>.
|
|
The generic <b>for</b> loop has the following syntax:
|
|
|
|
<pre>
|
|
stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
|
|
namelist ::= Name {`<b>,</b>´ Name}
|
|
</pre><p>
|
|
A <b>for</b> statement like
|
|
|
|
<pre>
|
|
for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
|
|
</pre><p>
|
|
is equivalent to the code:
|
|
|
|
<pre>
|
|
do
|
|
local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
|
|
while true do
|
|
local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
|
|
<em>var</em> = <em>var_1</em>
|
|
if <em>var</em> == nil then break end
|
|
<em>block</em>
|
|
end
|
|
end
|
|
</pre><p>
|
|
Note the following:
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
<code><em>explist</em></code> is evaluated only once.
|
|
Its results are an <em>iterator</em> function,
|
|
a <em>state</em>,
|
|
and an initial value for the first <em>iterator variable</em>.
|
|
</li>
|
|
|
|
<li>
|
|
<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
|
|
The names are here for explanatory purposes only.
|
|
</li>
|
|
|
|
<li>
|
|
You can use <b>break</b> to exit a <b>for</b> loop.
|
|
</li>
|
|
|
|
<li>
|
|
The loop variables <code><em>var_i</em></code> are local to the loop;
|
|
you cannot use their values after the <b>for</b> ends.
|
|
If you need these values,
|
|
then assign them to other variables before breaking or exiting the loop.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p>
|
|
To allow possible side-effects,
|
|
function calls can be executed as statements:
|
|
|
|
<pre>
|
|
stat ::= functioncall
|
|
</pre><p>
|
|
In this case, all returned values are thrown away.
|
|
Function calls are explained in <a href="#2.5.8">§2.5.8</a>.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p>
|
|
Local variables can be declared anywhere inside a block.
|
|
The declaration can include an initial assignment:
|
|
|
|
<pre>
|
|
stat ::= <b>local</b> namelist [`<b>=</b>´ explist]
|
|
</pre><p>
|
|
If present, an initial assignment has the same semantics
|
|
of a multiple assignment (see <a href="#2.4.3">§2.4.3</a>).
|
|
Otherwise, all variables are initialized with <b>nil</b>.
|
|
|
|
|
|
<p>
|
|
A chunk is also a block (see <a href="#2.4.1">§2.4.1</a>),
|
|
and so local variables can be declared in a chunk outside any explicit block.
|
|
The scope of such local variables extends until the end of the chunk.
|
|
|
|
|
|
<p>
|
|
The visibility rules for local variables are explained in <a href="#2.6">§2.6</a>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.5 - <a name="2.5">Expressions</a></h2>
|
|
|
|
<p>
|
|
The basic expressions in Lua are the following:
|
|
|
|
<pre>
|
|
exp ::= prefixexp
|
|
exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
|
|
exp ::= Number
|
|
exp ::= String
|
|
exp ::= function
|
|
exp ::= tableconstructor
|
|
exp ::= `<b>...</b>´
|
|
exp ::= exp binop exp
|
|
exp ::= unop exp
|
|
prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´
|
|
</pre>
|
|
|
|
<p>
|
|
Numbers and literal strings are explained in <a href="#2.1">§2.1</a>;
|
|
variables are explained in <a href="#2.3">§2.3</a>;
|
|
function definitions are explained in <a href="#2.5.9">§2.5.9</a>;
|
|
function calls are explained in <a href="#2.5.8">§2.5.8</a>;
|
|
table constructors are explained in <a href="#2.5.7">§2.5.7</a>.
|
|
Vararg expressions,
|
|
denoted by three dots ('<code>...</code>'), can only be used when
|
|
directly inside a vararg function;
|
|
they are explained in <a href="#2.5.9">§2.5.9</a>.
|
|
|
|
|
|
<p>
|
|
Binary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>),
|
|
relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>),
|
|
and the concatenation operator (see <a href="#2.5.4">§2.5.4</a>).
|
|
Unary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>),
|
|
the unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>),
|
|
and the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>).
|
|
|
|
|
|
<p>
|
|
Both function calls and vararg expressions can result in multiple values.
|
|
If an expression is used as a statement
|
|
(only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)),
|
|
then its return list is adjusted to zero elements,
|
|
thus discarding all returned values.
|
|
If an expression is used as the last (or the only) element
|
|
of a list of expressions,
|
|
then no adjustment is made
|
|
(unless the call is enclosed in parentheses).
|
|
In all other contexts,
|
|
Lua adjusts the result list to one element,
|
|
discarding all values except the first one.
|
|
|
|
|
|
<p>
|
|
Here are some examples:
|
|
|
|
<pre>
|
|
f() -- adjusted to 0 results
|
|
g(f(), x) -- f() is adjusted to 1 result
|
|
g(x, f()) -- g gets x plus all results from f()
|
|
a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
|
|
a,b = ... -- a gets the first vararg parameter, b gets
|
|
-- the second (both a and b can get nil if there
|
|
-- is no corresponding vararg parameter)
|
|
|
|
a,b,c = x, f() -- f() is adjusted to 2 results
|
|
a,b,c = f() -- f() is adjusted to 3 results
|
|
return f() -- returns all results from f()
|
|
return ... -- returns all received vararg parameters
|
|
return x,y,f() -- returns x, y, and all results from f()
|
|
{f()} -- creates a list with all results from f()
|
|
{...} -- creates a list with all vararg parameters
|
|
{f(), nil} -- f() is adjusted to 1 result
|
|
</pre>
|
|
|
|
<p>
|
|
Any expression enclosed in parentheses always results in only one value.
|
|
Thus,
|
|
<code>(f(x,y,z))</code> is always a single value,
|
|
even if <code>f</code> returns several values.
|
|
(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
|
|
or <b>nil</b> if <code>f</code> does not return any values.)
|
|
|
|
|
|
|
|
<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p>
|
|
Lua supports the usual arithmetic operators:
|
|
the binary <code>+</code> (addition),
|
|
<code>-</code> (subtraction), <code>*</code> (multiplication),
|
|
<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation);
|
|
and unary <code>-</code> (negation).
|
|
If the operands are numbers, or strings that can be converted to
|
|
numbers (see <a href="#2.2.1">§2.2.1</a>),
|
|
then all operations have the usual meaning.
|
|
Exponentiation works for any exponent.
|
|
For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>.
|
|
Modulo is defined as
|
|
|
|
<pre>
|
|
a % b == a - math.floor(a/b)*b
|
|
</pre><p>
|
|
That is, it is the remainder of a division that rounds
|
|
the quotient towards minus infinity.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p>
|
|
The relational operators in Lua are
|
|
|
|
<pre>
|
|
== ~= < > <= >=
|
|
</pre><p>
|
|
These operators always result in <b>false</b> or <b>true</b>.
|
|
|
|
|
|
<p>
|
|
Equality (<code>==</code>) first compares the type of its operands.
|
|
If the types are different, then the result is <b>false</b>.
|
|
Otherwise, the values of the operands are compared.
|
|
Numbers and strings are compared in the usual way.
|
|
Objects (tables, threads, and functions)
|
|
are compared by <em>reference</em>:
|
|
two objects are considered equal only if they are the <em>same</em> object.
|
|
Every time you create a new object
|
|
(a table, thread, or function),
|
|
this new object is different from any previously existing object.
|
|
|
|
|
|
<p>
|
|
You can change the way that Lua compares tables by using the "eq" metamethod
|
|
(see <a href="#2.8">§2.8</a>).
|
|
|
|
|
|
<p>
|
|
The conversion rules of <a href="#2.2.1">§2.2.1</a>
|
|
<em>do not</em> apply to equality comparisons.
|
|
Thus, <code>"0"==0</code> evaluates to <b>false</b>,
|
|
and <code>t[0]</code> and <code>t["0"]</code> denote different
|
|
entries in a table.
|
|
|
|
|
|
<p>
|
|
The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
|
|
|
|
|
|
<p>
|
|
The order operators work as follows.
|
|
If both arguments are numbers, then they are compared as such.
|
|
Otherwise, if both arguments are strings,
|
|
then their values are compared according to the current locale.
|
|
Otherwise, Lua tries to call the "lt" or the "le"
|
|
metamethod (see <a href="#2.8">§2.8</a>).
|
|
A comparison <code>a > b</code> is translated to <code>b < a</code>
|
|
and <code>a >= b</code> is translated to <code>b <= a</code>.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p>
|
|
The logical operators in Lua are
|
|
<b>and</b>, <b>or</b>, and <b>not</b>.
|
|
Like the control structures (see <a href="#2.4.4">§2.4.4</a>),
|
|
all logical operators consider both <b>false</b> and <b>nil</b> as false
|
|
and anything else as true.
|
|
|
|
|
|
<p>
|
|
The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
|
|
The conjunction operator <b>and</b> returns its first argument
|
|
if this value is <b>false</b> or <b>nil</b>;
|
|
otherwise, <b>and</b> returns its second argument.
|
|
The disjunction operator <b>or</b> returns its first argument
|
|
if this value is different from <b>nil</b> and <b>false</b>;
|
|
otherwise, <b>or</b> returns its second argument.
|
|
Both <b>and</b> and <b>or</b> use short-cut evaluation;
|
|
that is,
|
|
the second operand is evaluated only if necessary.
|
|
Here are some examples:
|
|
|
|
<pre>
|
|
10 or 20 --> 10
|
|
10 or error() --> 10
|
|
nil or "a" --> "a"
|
|
nil and 10 --> nil
|
|
false and error() --> false
|
|
false and nil --> false
|
|
false or nil --> nil
|
|
10 and 20 --> 20
|
|
</pre><p>
|
|
(In this manual,
|
|
<code>--></code> indicates the result of the preceding expression.)
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p>
|
|
The string concatenation operator in Lua is
|
|
denoted by two dots ('<code>..</code>').
|
|
If both operands are strings or numbers, then they are converted to
|
|
strings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>.
|
|
Otherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>).
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3>
|
|
|
|
<p>
|
|
The length operator is denoted by the unary 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>
|
|
The length of a table <code>t</code> is defined to be any
|
|
integer index <code>n</code>
|
|
such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>;
|
|
moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero.
|
|
For a regular array, with non-nil values from 1 to a given <code>n</code>,
|
|
its length is exactly that <code>n</code>,
|
|
the index of its last value.
|
|
If the array has "holes"
|
|
(that is, <b>nil</b> values between other non-nil values),
|
|
then <code>#t</code> can be any of the indices that
|
|
directly precedes a <b>nil</b> value
|
|
(that is, it may consider any such <b>nil</b> value as the end of
|
|
the array).
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p>
|
|
Operator precedence in Lua follows the table below,
|
|
from lower to higher priority:
|
|
|
|
<pre>
|
|
or
|
|
and
|
|
< > <= >= ~= ==
|
|
..
|
|
+ -
|
|
* / %
|
|
not # - (unary)
|
|
^
|
|
</pre><p>
|
|
As usual,
|
|
you can use parentheses to change the precedences of an expression.
|
|
The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
|
|
operators are right associative.
|
|
All other binary operators are left associative.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p>
|
|
Table constructors are expressions that create tables.
|
|
Every time a constructor is evaluated, a new table is created.
|
|
A constructor can be used to create an empty table
|
|
or to create a table and initialize some of its fields.
|
|
The general syntax for constructors is
|
|
|
|
<pre>
|
|
tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´
|
|
fieldlist ::= field {fieldsep field} [fieldsep]
|
|
field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
|
|
fieldsep ::= `<b>,</b>´ | `<b>;</b>´
|
|
</pre>
|
|
|
|
<p>
|
|
Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
|
|
with key <code>exp1</code> and value <code>exp2</code>.
|
|
A field of the form <code>name = exp</code> is equivalent to
|
|
<code>["name"] = exp</code>.
|
|
Finally, fields of the form <code>exp</code> are equivalent to
|
|
<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers,
|
|
starting with 1.
|
|
Fields in the other formats do not affect this counting.
|
|
For example,
|
|
|
|
<pre>
|
|
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
|
|
</pre><p>
|
|
is equivalent to
|
|
|
|
<pre>
|
|
do
|
|
local t = {}
|
|
t[f(1)] = g
|
|
t[1] = "x" -- 1st exp
|
|
t[2] = "y" -- 2nd exp
|
|
t.x = 1 -- t["x"] = 1
|
|
t[3] = f(x) -- 3rd exp
|
|
t[30] = 23
|
|
t[4] = 45 -- 4th exp
|
|
a = t
|
|
end
|
|
</pre>
|
|
|
|
<p>
|
|
If the last field in the list has the form <code>exp</code>
|
|
and the expression is a function call or a vararg expression,
|
|
then all values returned by this expression enter the list consecutively
|
|
(see <a href="#2.5.8">§2.5.8</a>).
|
|
To avoid this,
|
|
enclose the function call or the vararg expression
|
|
in parentheses (see <a href="#2.5">§2.5</a>).
|
|
|
|
|
|
<p>
|
|
The field list can have an optional trailing separator,
|
|
as a convenience for machine-generated code.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p>
|
|
A function call in Lua has the following syntax:
|
|
|
|
<pre>
|
|
functioncall ::= prefixexp args
|
|
</pre><p>
|
|
In a function call,
|
|
first prefixexp and args are evaluated.
|
|
If the value of prefixexp has type <em>function</em>,
|
|
then this function is called
|
|
with the given arguments.
|
|
Otherwise, the prefixexp "call" metamethod is called,
|
|
having as first parameter the value of prefixexp,
|
|
followed by the original call arguments
|
|
(see <a href="#2.8">§2.8</a>).
|
|
|
|
|
|
<p>
|
|
The form
|
|
|
|
<pre>
|
|
functioncall ::= prefixexp `<b>:</b>´ Name args
|
|
</pre><p>
|
|
can be used to call "methods".
|
|
A call <code>v:name(<em>args</em>)</code>
|
|
is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
|
|
except that <code>v</code> is evaluated only once.
|
|
|
|
|
|
<p>
|
|
Arguments have the following syntax:
|
|
|
|
<pre>
|
|
args ::= `<b>(</b>´ [explist] `<b>)</b>´
|
|
args ::= tableconstructor
|
|
args ::= String
|
|
</pre><p>
|
|
All argument expressions are evaluated before the call.
|
|
A call of the form <code>f{<em>fields</em>}</code> is
|
|
syntactic sugar for <code>f({<em>fields</em>})</code>;
|
|
that is, the argument list is a single new table.
|
|
A call of the form <code>f'<em>string</em>'</code>
|
|
(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
|
|
is syntactic sugar for <code>f('<em>string</em>')</code>;
|
|
that is, the argument list is a single literal string.
|
|
|
|
|
|
<p>
|
|
As an exception to the free-format syntax of Lua,
|
|
you cannot put a line break before the '<code>(</code>' in a function call.
|
|
This restriction avoids some ambiguities in the language.
|
|
If you write
|
|
|
|
<pre>
|
|
a = f
|
|
(g).x(a)
|
|
</pre><p>
|
|
Lua would see that as a single statement, <code>a = f(g).x(a)</code>.
|
|
So, if you want two statements, you must add a semi-colon between them.
|
|
If you actually want to call <code>f</code>,
|
|
you must remove the line break before <code>(g)</code>.
|
|
|
|
|
|
<p>
|
|
A call of the form <code>return</code> <em>functioncall</em> is called
|
|
a <em>tail call</em>.
|
|
Lua implements <em>proper tail calls</em>
|
|
(or <em>proper tail recursion</em>):
|
|
in a tail call,
|
|
the called function reuses the stack entry of the calling function.
|
|
Therefore, there is no limit on the number of nested tail calls that
|
|
a program can execute.
|
|
However, a tail call erases any debug information about the
|
|
calling function.
|
|
Note that a tail call only happens with a particular syntax,
|
|
where the <b>return</b> has one single function call as argument;
|
|
this syntax makes the calling function return exactly
|
|
the returns of the called function.
|
|
So, none of the following examples are tail calls:
|
|
|
|
<pre>
|
|
return (f(x)) -- results adjusted to 1
|
|
return 2 * f(x)
|
|
return x, f(x) -- additional results
|
|
f(x); return -- results discarded
|
|
return x or f(x) -- results adjusted to 1
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3>
|
|
|
|
<p>
|
|
The syntax for function definition is
|
|
|
|
<pre>
|
|
function ::= <b>function</b> funcbody
|
|
funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b>
|
|
</pre>
|
|
|
|
<p>
|
|
The following syntactic sugar simplifies function definitions:
|
|
|
|
<pre>
|
|
stat ::= <b>function</b> funcname funcbody
|
|
stat ::= <b>local</b> <b>function</b> Name funcbody
|
|
funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name]
|
|
</pre><p>
|
|
The statement
|
|
|
|
<pre>
|
|
function f () <em>body</em> end
|
|
</pre><p>
|
|
translates to
|
|
|
|
<pre>
|
|
f = function () <em>body</em> end
|
|
</pre><p>
|
|
The statement
|
|
|
|
<pre>
|
|
function t.a.b.c.f () <em>body</em> end
|
|
</pre><p>
|
|
translates to
|
|
|
|
<pre>
|
|
t.a.b.c.f = function () <em>body</em> end
|
|
</pre><p>
|
|
The statement
|
|
|
|
<pre>
|
|
local function f () <em>body</em> end
|
|
</pre><p>
|
|
translates to
|
|
|
|
<pre>
|
|
local f; f = function () <em>body</em> end
|
|
</pre><p>
|
|
<em>not</em> to
|
|
|
|
<pre>
|
|
local f = function () <em>body</em> end
|
|
</pre><p>
|
|
(This only makes a difference when the body of the function
|
|
contains references to <code>f</code>.)
|
|
|
|
|
|
<p>
|
|
A function definition is an executable expression,
|
|
whose value has type <em>function</em>.
|
|
When Lua pre-compiles a chunk,
|
|
all its function bodies are pre-compiled too.
|
|
Then, whenever Lua executes the function definition,
|
|
the function is <em>instantiated</em> (or <em>closed</em>).
|
|
This function instance (or <em>closure</em>)
|
|
is the final value of the expression.
|
|
Different instances of the same function
|
|
can refer to different external local variables
|
|
and can have different environment tables.
|
|
|
|
|
|
<p>
|
|
Parameters act as local variables that are
|
|
initialized with the argument values:
|
|
|
|
<pre>
|
|
parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´
|
|
</pre><p>
|
|
When a function is called,
|
|
the list of arguments is adjusted to
|
|
the length of the list of parameters,
|
|
unless the function is a variadic or <em>vararg function</em>,
|
|
which is
|
|
indicated by three dots ('<code>...</code>') at the end of its parameter list.
|
|
A vararg function does not adjust its argument list;
|
|
instead, it collects all extra arguments and supplies them
|
|
to the function through a <em>vararg expression</em>,
|
|
which is also written as three dots.
|
|
The value of this expression is a list of all actual extra arguments,
|
|
similar to a function with multiple results.
|
|
If a vararg expression is used inside another expression
|
|
or in the middle of a list of expressions,
|
|
then its return list is adjusted to one element.
|
|
If the expression is used as the last element of a list of expressions,
|
|
then no adjustment is made
|
|
(unless that last expression is enclosed in parentheses).
|
|
|
|
|
|
<p>
|
|
As an example, consider the following definitions:
|
|
|
|
<pre>
|
|
function f(a, b) end
|
|
function g(a, b, ...) end
|
|
function r() return 1,2,3 end
|
|
</pre><p>
|
|
Then, we have the following mapping from arguments to parameters and
|
|
to the vararg expression:
|
|
|
|
<pre>
|
|
CALL PARAMETERS
|
|
|
|
f(3) a=3, b=nil
|
|
f(3, 4) a=3, b=4
|
|
f(3, 4, 5) a=3, b=4
|
|
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
|
|
</pre>
|
|
|
|
<p>
|
|
Results are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>).
|
|
If control reaches the end of a function
|
|
without encountering a <b>return</b> statement,
|
|
then the function returns with no results.
|
|
|
|
|
|
<p>
|
|
The <em>colon</em> syntax
|
|
is used for defining <em>methods</em>,
|
|
that is, functions that have an implicit extra parameter <code>self</code>.
|
|
Thus, the statement
|
|
|
|
<pre>
|
|
function t.a.b.c:f (<em>params</em>) <em>body</em> end
|
|
</pre><p>
|
|
is syntactic sugar for
|
|
|
|
<pre>
|
|
t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.6 - <a name="2.6">Visibility Rules</a></h2>
|
|
|
|
<p>
|
|
|
|
Lua is a lexically scoped language.
|
|
The scope of variables begins at the first statement <em>after</em>
|
|
their declaration and lasts until the end of the innermost block that
|
|
includes the declaration.
|
|
Consider the following example:
|
|
|
|
<pre>
|
|
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)
|
|
</pre>
|
|
|
|
<p>
|
|
Notice that, in a declaration like <code>local x = x</code>,
|
|
the new <code>x</code> being declared is not in scope yet,
|
|
and so the second <code>x</code> refers to the outside variable.
|
|
|
|
|
|
<p>
|
|
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 <em>upvalue</em>, or <em>external local variable</em>,
|
|
inside the inner function.
|
|
|
|
|
|
<p>
|
|
Notice that each execution of a <b>local</b> statement
|
|
defines new local variables.
|
|
Consider the following example:
|
|
|
|
<pre>
|
|
a = {}
|
|
local x = 20
|
|
for i=1,10 do
|
|
local y = 0
|
|
a[i] = function () y=y+1; return x+y end
|
|
end
|
|
</pre><p>
|
|
The loop creates ten closures
|
|
(that is, ten instances of the anonymous function).
|
|
Each of these closures uses a different <code>y</code> variable,
|
|
while all of them share the same <code>x</code>.
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.7 - <a name="2.7">Error Handling</a></h2>
|
|
|
|
<p>
|
|
<div class='teliva'>
|
|
Errors returned by Teliva code should display on screen in red. Please report
|
|
crashes or other behavior.
|
|
</div>
|
|
|
|
|
|
<p>
|
|
Lua code can explicitly generate an error by calling the
|
|
<a href="#pdf-error"><code>error</code></a> function.
|
|
If you need to catch errors in Lua,
|
|
you can use the <a href="#pdf-pcall"><code>pcall</code></a> function.
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.8 - <a name="2.8">Metatables</a></h2>
|
|
|
|
<p>
|
|
Every value in Lua can have a <em>metatable</em>.
|
|
This <em>metatable</em> is an ordinary Lua table
|
|
that defines the behavior of the original value
|
|
under certain special operations.
|
|
You can change several aspects of the behavior
|
|
of operations over a value by setting specific fields in its metatable.
|
|
For instance, when a non-numeric value is the operand of an addition,
|
|
Lua checks for a function in the field <code>"__add"</code> in its metatable.
|
|
If it finds one,
|
|
Lua calls this function to perform the addition.
|
|
|
|
|
|
<p>
|
|
We call the keys in a metatable <em>events</em>
|
|
and the values <em>metamethods</em>.
|
|
In the previous example, the event is <code>"add"</code>
|
|
and the metamethod is the function that performs the addition.
|
|
|
|
|
|
<p>
|
|
You can query the metatable of any value
|
|
through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
|
|
|
|
|
|
<p>
|
|
You can replace the metatable of tables
|
|
through the <a href="#pdf-setmetatable"><code>setmetatable</code></a>
|
|
function.
|
|
|
|
|
|
<p>
|
|
Tables have individual metatables
|
|
(although multiple tables can share their metatables).
|
|
Values of all other types share one single metatable per type;
|
|
that is, there is one single metatable for all numbers,
|
|
one for all strings, etc.
|
|
|
|
|
|
<p>
|
|
A metatable controls how an object behaves in arithmetic operations,
|
|
order comparisons, concatenation, length operation, and indexing.
|
|
For each of these operations Lua associates a specific key
|
|
called an <em>event</em>.
|
|
When Lua performs one of these operations over a value,
|
|
it checks whether this value has a metatable with the corresponding event.
|
|
If so, the value associated with that key (the metamethod)
|
|
controls how Lua will perform the operation.
|
|
|
|
|
|
<p>
|
|
Metatables control the operations listed next.
|
|
Each operation is identified by its corresponding name.
|
|
The key for each operation is a string with its name prefixed by
|
|
two underscores, '<code>__</code>';
|
|
for instance, the key for operation "add" is the
|
|
string <code>"__add"</code>.
|
|
The semantics of these operations is better explained by a Lua function
|
|
describing how the interpreter executes the operation.
|
|
|
|
|
|
<p>
|
|
The code shown here in Lua is only illustrative;
|
|
the real behavior is hard coded in the interpreter
|
|
and it is much more efficient than this simulation.
|
|
All functions used in these descriptions
|
|
(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.)
|
|
are described in <a href="#5.1">§5.1</a>.
|
|
In particular, to retrieve the metamethod of a given object,
|
|
we use the expression
|
|
|
|
<pre>
|
|
metatable(obj)[event]
|
|
</pre><p>
|
|
This should be read as
|
|
|
|
<pre>
|
|
rawget(getmetatable(obj) or {}, event)
|
|
</pre><p>
|
|
|
|
That is, the access to a metamethod does not invoke other metamethods,
|
|
and the access to objects with no metatables does not fail
|
|
(it simply results in <b>nil</b>).
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li><b>"add":</b>
|
|
the <code>+</code> operation.
|
|
|
|
|
|
|
|
<p>
|
|
The function <code>getbinhandler</code> below defines how Lua chooses a handler
|
|
for a binary operation.
|
|
First, Lua tries the first operand.
|
|
If its type does not define a handler for the operation,
|
|
then Lua tries the second operand.
|
|
|
|
<pre>
|
|
function getbinhandler (op1, op2, event)
|
|
return metatable(op1)[event] or metatable(op2)[event]
|
|
end
|
|
</pre><p>
|
|
By using this function,
|
|
the behavior of the <code>op1 + op2</code> is
|
|
|
|
<pre>
|
|
function add_event (op1, op2)
|
|
local o1, o2 = tonumber(op1), tonumber(op2)
|
|
if o1 and o2 then -- both operands are numeric?
|
|
return o1 + o2 -- '+' here is the primitive 'add'
|
|
else -- at least one of the operands is not numeric
|
|
local h = getbinhandler(op1, op2, "__add")
|
|
if h then
|
|
-- call the handler with both operands
|
|
return (h(op1, op2))
|
|
else -- no handler available: default behavior
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
<li><b>"sub":</b>
|
|
the <code>-</code> operation.
|
|
|
|
Behavior similar to the "add" operation.
|
|
</li>
|
|
|
|
<li><b>"mul":</b>
|
|
the <code>*</code> operation.
|
|
|
|
Behavior similar to the "add" operation.
|
|
</li>
|
|
|
|
<li><b>"div":</b>
|
|
the <code>/</code> operation.
|
|
|
|
Behavior similar to the "add" operation.
|
|
</li>
|
|
|
|
<li><b>"mod":</b>
|
|
the <code>%</code> operation.
|
|
|
|
Behavior similar to the "add" operation,
|
|
with the operation
|
|
<code>o1 - floor(o1/o2)*o2</code> as the primitive operation.
|
|
</li>
|
|
|
|
<li><b>"pow":</b>
|
|
the <code>^</code> (exponentiation) operation.
|
|
|
|
Behavior similar to the "add" operation,
|
|
with the function <code>pow</code> (from the C math library)
|
|
as the primitive operation.
|
|
</li>
|
|
|
|
<li><b>"unm":</b>
|
|
the unary <code>-</code> operation.
|
|
|
|
|
|
<pre>
|
|
function unm_event (op)
|
|
local o = tonumber(op)
|
|
if o then -- operand is numeric?
|
|
return -o -- '-' here is the primitive 'unm'
|
|
else -- the operand is not numeric.
|
|
-- Try to get a handler from the operand
|
|
local h = metatable(op).__unm
|
|
if h then
|
|
-- call the handler with the operand
|
|
return (h(op))
|
|
else -- no handler available: default behavior
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
<li><b>"concat":</b>
|
|
the <code>..</code> (concatenation) operation.
|
|
|
|
|
|
<pre>
|
|
function concat_event (op1, op2)
|
|
if (type(op1) == "string" or type(op1) == "number") and
|
|
(type(op2) == "string" or type(op2) == "number") then
|
|
return op1 .. op2 -- primitive string concatenation
|
|
else
|
|
local h = getbinhandler(op1, op2, "__concat")
|
|
if h then
|
|
return (h(op1, op2))
|
|
else
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
<li><b>"len":</b>
|
|
the <code>#</code> operation.
|
|
|
|
|
|
<pre>
|
|
function len_event (op)
|
|
if type(op) == "string" then
|
|
return strlen(op) -- primitive string length
|
|
elseif type(op) == "table" then
|
|
return #op -- primitive table length
|
|
else
|
|
local h = metatable(op).__len
|
|
if h then
|
|
-- call the handler with the operand
|
|
return (h(op))
|
|
else -- no handler available: default behavior
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
See <a href="#2.5.5">§2.5.5</a> for a description of the length of a table.
|
|
</li>
|
|
|
|
<li><b>"eq":</b>
|
|
the <code>==</code> operation.
|
|
|
|
The function <code>getcomphandler</code> defines how Lua chooses a metamethod
|
|
for comparison operators.
|
|
A metamethod only is selected when both objects
|
|
being compared have the same type
|
|
and the same metamethod for the selected operation.
|
|
|
|
<pre>
|
|
function getcomphandler (op1, op2, event)
|
|
if type(op1) ~= type(op2) then return nil end
|
|
local mm1 = metatable(op1)[event]
|
|
local mm2 = metatable(op2)[event]
|
|
if mm1 == mm2 then return mm1 else return nil end
|
|
end
|
|
</pre><p>
|
|
The "eq" event is defined as follows:
|
|
|
|
<pre>
|
|
function eq_event (op1, op2)
|
|
if type(op1) ~= type(op2) then -- different types?
|
|
return false -- different objects
|
|
end
|
|
if op1 == op2 then -- primitive equal?
|
|
return true -- objects are equal
|
|
end
|
|
-- try metamethod
|
|
local h = getcomphandler(op1, op2, "__eq")
|
|
if h then
|
|
return (h(op1, op2))
|
|
else
|
|
return false
|
|
end
|
|
end
|
|
</pre><p>
|
|
<code>a ~= b</code> is equivalent to <code>not (a == b)</code>.
|
|
</li>
|
|
|
|
<li><b>"lt":</b>
|
|
the <code><</code> operation.
|
|
|
|
|
|
<pre>
|
|
function lt_event (op1, op2)
|
|
if type(op1) == "number" and type(op2) == "number" then
|
|
return op1 < op2 -- numeric comparison
|
|
elseif type(op1) == "string" and type(op2) == "string" then
|
|
return op1 < op2 -- lexicographic comparison
|
|
else
|
|
local h = getcomphandler(op1, op2, "__lt")
|
|
if h then
|
|
return (h(op1, op2))
|
|
else
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
<code>a > b</code> is equivalent to <code>b < a</code>.
|
|
</li>
|
|
|
|
<li><b>"le":</b>
|
|
the <code><=</code> operation.
|
|
|
|
|
|
<pre>
|
|
function le_event (op1, op2)
|
|
if type(op1) == "number" and type(op2) == "number" then
|
|
return op1 <= op2 -- numeric comparison
|
|
elseif type(op1) == "string" and type(op2) == "string" then
|
|
return op1 <= op2 -- lexicographic comparison
|
|
else
|
|
local h = getcomphandler(op1, op2, "__le")
|
|
if h then
|
|
return (h(op1, op2))
|
|
else
|
|
h = getcomphandler(op1, op2, "__lt")
|
|
if h then
|
|
return not h(op2, op1)
|
|
else
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
<code>a >= b</code> is equivalent to <code>b <= a</code>.
|
|
Note that, in the absence of a "le" metamethod,
|
|
Lua tries the "lt", assuming that <code>a <= b</code> is
|
|
equivalent to <code>not (b < a)</code>.
|
|
</li>
|
|
|
|
<li><b>"index":</b>
|
|
The indexing access <code>table[key]</code>.
|
|
|
|
|
|
<pre>
|
|
function gettable_event (table, key)
|
|
local h
|
|
if type(table) == "table" then
|
|
local v = rawget(table, key)
|
|
if v ~= nil then return v end
|
|
h = metatable(table).__index
|
|
if h == nil then return nil end
|
|
else
|
|
h = metatable(table).__index
|
|
if h == nil then
|
|
error(···)
|
|
end
|
|
end
|
|
if type(h) == "function" then
|
|
return (h(table, key)) -- call the handler
|
|
else return h[key] -- or repeat operation on it
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
<li><b>"newindex":</b>
|
|
The indexing assignment <code>table[key] = value</code>.
|
|
|
|
|
|
<pre>
|
|
function settable_event (table, key, value)
|
|
local h
|
|
if type(table) == "table" then
|
|
local v = rawget(table, key)
|
|
if v ~= nil then rawset(table, key, value); return end
|
|
h = metatable(table).__newindex
|
|
if h == nil then rawset(table, key, value); return end
|
|
else
|
|
h = metatable(table).__newindex
|
|
if h == nil then
|
|
error(···)
|
|
end
|
|
end
|
|
if type(h) == "function" then
|
|
h(table, key,value) -- call the handler
|
|
else h[key] = value -- or repeat operation on it
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
<li><b>"call":</b>
|
|
called when Lua calls a value.
|
|
|
|
|
|
<pre>
|
|
function function_event (func, ...)
|
|
if type(func) == "function" then
|
|
return func(...) -- primitive call
|
|
else
|
|
local h = metatable(func).__call
|
|
if h then
|
|
return h(func, ...)
|
|
else
|
|
error(···)
|
|
end
|
|
end
|
|
end
|
|
</pre><p>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h2>2.9 - <a name="2.9">Environments</a></h2>
|
|
|
|
<p>
|
|
Besides metatables, objects of types thread and function
|
|
have another table associated with them, called their
|
|
<em>environment</em>.
|
|
Like metatables, environments are regular tables and
|
|
multiple objects can share the same environment.
|
|
|
|
|
|
<p>
|
|
Threads are created sharing the environment of the creating thread.
|
|
Nested Lua functions are created sharing the environment of
|
|
the creating Lua function.
|
|
|
|
|
|
<p>
|
|
Environments associated with threads are called
|
|
<em>global environments</em>.
|
|
They are used as the default environment for threads.
|
|
|
|
|
|
<p>
|
|
Environments associated with Lua functions are used to resolve
|
|
all accesses to global variables within the function (see <a href="#2.3">§2.3</a>).
|
|
They are used as the default environment for nested Lua functions
|
|
created by the function.
|
|
|
|
|
|
<p>
|
|
You can change the environment of a Lua function or the
|
|
running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>.
|
|
You can get the environment of a Lua function or the running thread
|
|
by calling <a href="#pdf-getfenv"><code>getfenv</code></a>.
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.10 - <a name="2.10">Garbage Collection</a></h2>
|
|
|
|
<p>
|
|
Lua performs automatic memory management.
|
|
This means that
|
|
you have to worry neither about allocating memory for new objects
|
|
nor about freeing it when the objects are no longer needed.
|
|
Lua manages memory automatically by running
|
|
a <em>garbage collector</em> from time to time
|
|
to collect all <em>dead objects</em>
|
|
(that is, objects that are no longer accessible from Lua).
|
|
All memory used by Lua is subject to automatic management:
|
|
tables, functions, threads, strings, etc.
|
|
|
|
|
|
<p>
|
|
Lua implements an incremental mark-and-sweep collector.
|
|
It uses two numbers to control its garbage-collection cycles:
|
|
the <em>garbage-collector pause</em> and
|
|
the <em>garbage-collector step multiplier</em>.
|
|
Both use percentage points as units
|
|
(so that a value of 100 means an internal value of 1).
|
|
|
|
|
|
<p>
|
|
The garbage-collector pause
|
|
controls how long the collector waits before starting a new cycle.
|
|
Larger values make the collector less aggressive.
|
|
Values smaller 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.
|
|
|
|
|
|
<p>
|
|
The step multiplier
|
|
controls the relative speed of the collector relative to
|
|
memory allocation.
|
|
Larger values make the collector more aggressive but also increase
|
|
the size of each incremental step.
|
|
Values smaller than 100 make the collector too slow and
|
|
can result in the collector never finishing a cycle.
|
|
The default, 200, means that the collector runs at "twice"
|
|
the speed of memory allocation.
|
|
|
|
|
|
<p>
|
|
<div class='teliva'>Modifying these parameters requires changes to Teliva's C
|
|
sources.</div>
|
|
|
|
|
|
|
|
<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3>
|
|
|
|
<p>
|
|
A <em>weak table</em> is a table whose elements are
|
|
<em>weak references</em>.
|
|
A weak reference is ignored by the garbage collector.
|
|
In other words,
|
|
if the only references to an object are weak references,
|
|
then the garbage collector will collect this object.
|
|
|
|
|
|
<p>
|
|
A weak table can have weak keys, weak values, or both.
|
|
A table with weak keys allows the collection of its keys,
|
|
but prevents the collection of its values.
|
|
A table with both weak keys and weak values allows the collection of
|
|
both keys and values.
|
|
In any case, if either the key or the value is collected,
|
|
the whole pair is removed from the table.
|
|
The weakness of a table is controlled by the
|
|
<code>__mode</code> field of its metatable.
|
|
If the <code>__mode</code> field is a string containing the character '<code>k</code>',
|
|
the keys in the table are weak.
|
|
If <code>__mode</code> contains '<code>v</code>',
|
|
the values in the table are weak.
|
|
|
|
|
|
<p>
|
|
After you use a table as a metatable,
|
|
you should not change the value of its <code>__mode</code> field.
|
|
Otherwise, the weak behavior of the tables controlled by this
|
|
metatable is undefined.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>2.11 - <a name="2.11">Coroutines</a></h2>
|
|
|
|
<p>
|
|
Lua supports coroutines,
|
|
also called <em>collaborative multithreading</em>.
|
|
A coroutine in Lua represents an independent thread of execution.
|
|
Unlike threads in multithread systems, however,
|
|
a coroutine only suspends its execution by explicitly calling
|
|
a yield function.
|
|
|
|
|
|
<p>
|
|
You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
|
|
Its sole argument is a function
|
|
that is the main function of the coroutine.
|
|
The <code>create</code> function only creates a new coroutine and
|
|
returns a handle to it (an object of type <em>thread</em>);
|
|
it does not start the coroutine execution.
|
|
|
|
|
|
<p>
|
|
When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
|
|
passing as its first argument
|
|
a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
|
|
the coroutine starts its execution,
|
|
at the first line of its main function.
|
|
Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on
|
|
to the coroutine main function.
|
|
After the coroutine starts running,
|
|
it runs until it terminates or <em>yields</em>.
|
|
|
|
|
|
<p>
|
|
A coroutine can terminate its execution in two ways:
|
|
normally, when its main function returns
|
|
(explicitly or implicitly, after the last instruction);
|
|
and abnormally, if there is an unprotected error.
|
|
In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
|
|
plus any values returned by the coroutine main function.
|
|
In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
|
|
plus an error message.
|
|
|
|
|
|
<p>
|
|
A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
|
|
When a coroutine yields,
|
|
the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
|
|
even if the yield happens inside nested function calls
|
|
(that is, not in the main function,
|
|
but in a function directly or indirectly called by the main function).
|
|
In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
|
|
plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
|
|
The next time you resume the same coroutine,
|
|
it continues its execution from the point where it yielded,
|
|
with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
|
|
arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
|
|
|
|
|
|
<p>
|
|
Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
|
|
the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
|
|
but instead of returning the coroutine itself,
|
|
it returns a function that, when called, resumes the coroutine.
|
|
Any arguments passed to this function
|
|
go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
|
|
<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
|
|
except the first one (the boolean error code).
|
|
Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
|
|
<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
|
|
any error is propagated to the caller.
|
|
|
|
|
|
<p>
|
|
As an example,
|
|
consider the following code:
|
|
|
|
<pre>
|
|
function foo (a)
|
|
print("foo", a)
|
|
return coroutine.yield(2*a)
|
|
end
|
|
|
|
co = coroutine.create(function (a,b)
|
|
print("co-body", a, b)
|
|
local r = foo(a+1)
|
|
print("co-body", r)
|
|
local r, s = coroutine.yield(a+b, a-b)
|
|
print("co-body", r, s)
|
|
return b, "end"
|
|
end)
|
|
|
|
print("main", coroutine.resume(co, 1, 10))
|
|
print("main", coroutine.resume(co, "r"))
|
|
print("main", coroutine.resume(co, "x", "y"))
|
|
print("main", coroutine.resume(co, "x", "y"))
|
|
</pre><p>
|
|
When you run it, it produces the following output:
|
|
|
|
<pre>
|
|
co-body 1 10
|
|
foo 2
|
|
|
|
main true 4
|
|
co-body r
|
|
main true 11 -9
|
|
co-body x y
|
|
main true 10 end
|
|
main false cannot resume dead coroutine
|
|
</pre>
|
|
|
|
<div class='teliva'>
|
|
Coroutines are powerful, but require some experience to use tastefully. Try to
|
|
use them judiciously. If you find yourself juggling lots of coroutines and
|
|
trying to decide which one to try to resume, you should probably be using
|
|
<a href='#5.13'>tasks and channels</a> instead. On the other hand, tasks have
|
|
some cognitive overheads. You have to explicitly manage them with
|
|
<a href='#pdf-task.scheduler'><code>task.scheduler</code></a>, and errors can
|
|
sometimes be hard to track down. For simple generators that emit elements
|
|
on demand, a coroutine is likely the best solution.
|
|
</div>
|
|
|
|
|
|
<h1>3 - <a name="3">C API</a></h1>
|
|
|
|
<div class='teliva'>Unlike Lua, Teliva isn't intended to be modified at the C
|
|
level. However, forks of Teliva are encouraged.</div>
|
|
|
|
|
|
<h1>5 - <a name="5">Standard Libraries</a></h1>
|
|
|
|
<p>
|
|
The standard Lua libraries provide useful functions
|
|
that are implemented directly in C.
|
|
Some of these functions provide essential services to the language
|
|
(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
|
|
others provide access to "outside" services (e.g., I/O);
|
|
and others could be implemented in Lua itself,
|
|
but are quite useful or have critical performance requirements that
|
|
deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
|
|
|
|
|
|
<p>
|
|
Currently, Lua has the following standard libraries:
|
|
|
|
<ul>
|
|
|
|
<li>basic library, which includes the coroutine sub-library;</li>
|
|
|
|
<li>package library;</li>
|
|
|
|
<li>string manipulation;</li>
|
|
|
|
<li>table manipulation;</li>
|
|
|
|
<li>mathematical functions (sin, log, etc.);</li>
|
|
|
|
<li>input and output;</li>
|
|
|
|
<li>operating system facilities;</li>
|
|
|
|
<li>debug facilities.</li>
|
|
|
|
</ul><p>
|
|
Except for the basic and package libraries,
|
|
each library provides all its functions as fields of a global table
|
|
or as methods of its objects.
|
|
|
|
|
|
<h2>5.1 - <a name="5.1">Basic Primitives</a></h2>
|
|
|
|
<p>
|
|
The basic library provides some core functions to Lua.
|
|
If you do not include this library in your application,
|
|
you should check carefully whether you need to provide
|
|
implementations for some of its facilities.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-arg"><code>arg</code></a></h3>
|
|
A global variable containing any commandline arguments.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
|
|
Issues an error when
|
|
the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
|
|
otherwise, returns all its arguments.
|
|
<code>message</code> is an error message;
|
|
when absent, it defaults to "assertion failed!"
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
This function is a generic interface to the garbage collector.
|
|
It performs different functions according to its first argument, <code>opt</code>:
|
|
|
|
<ul>
|
|
|
|
<li><b>"collect":</b>
|
|
performs a full garbage-collection cycle.
|
|
This is the default option.
|
|
</li>
|
|
|
|
<li><b>"stop":</b>
|
|
stops the garbage collector.
|
|
</li>
|
|
|
|
<li><b>"restart":</b>
|
|
restarts the garbage collector.
|
|
</li>
|
|
|
|
<li><b>"count":</b>
|
|
returns the total memory in use by Lua (in Kbytes).
|
|
</li>
|
|
|
|
<li><b>"step":</b>
|
|
performs a garbage-collection step.
|
|
The step "size" is controlled by <code>arg</code>
|
|
(larger values mean more steps) in a non-specified way.
|
|
If you want to control the step size
|
|
you must experimentally tune the value of <code>arg</code>.
|
|
Returns <b>true</b> if the step finished a collection cycle.
|
|
</li>
|
|
|
|
<li><b>"setpause":</b>
|
|
sets <code>arg</code> as the new value for the <em>pause</em> of
|
|
the collector (see <a href="#2.10">§2.10</a>).
|
|
Returns the previous value for <em>pause</em>.
|
|
</li>
|
|
|
|
<li><b>"setstepmul":</b>
|
|
sets <code>arg</code> as the new value for the <em>step multiplier</em> of
|
|
the collector (see <a href="#2.10">§2.10</a>).
|
|
Returns the previous value for <em>step</em>.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
|
|
Terminates the last protected function called
|
|
and returns <code>message</code> as the error message.
|
|
Function <code>error</code> never returns.
|
|
|
|
|
|
<p>
|
|
Usually, <code>error</code> adds some information about the error position
|
|
at the beginning of the message.
|
|
The <code>level</code> argument specifies how to get the error position.
|
|
With level 1 (the default), the error position is where the
|
|
<code>error</code> function was called.
|
|
Level 2 points the error to where the function
|
|
that called <code>error</code> was called; and so on.
|
|
Passing a level 0 avoids the addition of error position information
|
|
to the message.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
|
|
A global variable that
|
|
holds the global environment (that is, <code>_G._G = _G</code>).
|
|
Lua itself does not use this variable;
|
|
changing its value does not affect any environment,
|
|
nor vice-versa.
|
|
(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3>
|
|
Returns the current environment in use by the function.
|
|
<code>f</code> can be a Lua function or a number
|
|
that specifies the function at that stack level:
|
|
Level 1 is the function calling <code>getfenv</code>.
|
|
If the given function is not a Lua function,
|
|
or if <code>f</code> is 0,
|
|
<code>getfenv</code> returns the global environment.
|
|
The default for <code>f</code> is 1.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
If <code>object</code> does not have a metatable, returns <b>nil</b>.
|
|
Otherwise,
|
|
if the object's metatable has a <code>"__metatable"</code> field,
|
|
returns the associated value.
|
|
Otherwise, returns the metatable of the given object.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns three values: an iterator function, the table <code>t</code>, and 0,
|
|
so that the construction
|
|
|
|
<pre>
|
|
for i,v in ipairs(t) do <em>body</em> end
|
|
</pre><p>
|
|
will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···,
|
|
up to the first integer key absent from the table.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Allows a program to traverse all fields of a table.
|
|
Its first argument is a table and its second argument
|
|
is an index in this table.
|
|
<code>next</code> returns the next index of the table
|
|
and its associated value.
|
|
When called with <b>nil</b> as its second argument,
|
|
<code>next</code> returns an initial index
|
|
and its associated value.
|
|
When called with the last index,
|
|
or with <b>nil</b> in an empty table,
|
|
<code>next</code> returns <b>nil</b>.
|
|
If the second argument is absent, then it is interpreted as <b>nil</b>.
|
|
In particular,
|
|
you can use <code>next(t)</code> to check whether a table is empty.
|
|
|
|
|
|
<p>
|
|
The order in which the indices are enumerated is not specified,
|
|
<em>even for numeric indices</em>.
|
|
(To traverse a table in numeric order,
|
|
use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.)
|
|
|
|
|
|
<p>
|
|
The behavior of <code>next</code> is <em>undefined</em> if,
|
|
during the traversal,
|
|
you assign any value to a non-existent field in the table.
|
|
You may however modify existing fields.
|
|
In particular, you may clear existing fields.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
|
|
so that the construction
|
|
|
|
<pre>
|
|
for k,v in pairs(t) do <em>body</em> end
|
|
</pre><p>
|
|
will iterate over all key–value pairs of table <code>t</code>.
|
|
|
|
|
|
<p>
|
|
See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
|
|
the table during its traversal.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
|
|
Receives any number of arguments,
|
|
and prints their values to <code>stdout</code>,
|
|
using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
|
|
<code>print</code> is not intended for formatted output,
|
|
but only as a quick way to show a value,
|
|
typically for debugging.
|
|
For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
|
|
Checks whether <code>v1</code> is equal to <code>v2</code>,
|
|
without invoking any metamethod.
|
|
Returns a boolean.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
|
|
Gets the real value of <code>table[index]</code>,
|
|
without invoking any metamethod.
|
|
<code>table</code> must be a table;
|
|
<code>index</code> may be any value.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
|
|
Sets the real value of <code>table[index]</code> to <code>value</code>,
|
|
without invoking any metamethod.
|
|
<code>table</code> must be a table,
|
|
<code>index</code> any value different from <b>nil</b>,
|
|
and <code>value</code> any Lua value.
|
|
|
|
|
|
<p>
|
|
This function returns <code>table</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
If <code>index</code> is a number,
|
|
returns all arguments after argument number <code>index</code>.
|
|
Otherwise, <code>index</code> must be the string <code>"#"</code>,
|
|
and <code>select</code> returns the total number of extra arguments it received.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets the environment to be used by the given function.
|
|
<code>f</code> can be a Lua function or a number
|
|
that specifies the function at that stack level:
|
|
Level 1 is the function calling <code>setfenv</code>.
|
|
<code>setfenv</code> returns the given function.
|
|
|
|
|
|
<p>
|
|
As a special case, when <code>f</code> is 0 <code>setfenv</code> changes
|
|
the environment of the running thread.
|
|
In this case, <code>setfenv</code> returns no values.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets the metatable for the given table.
|
|
(You cannot change the metatable of other types.)
|
|
If <code>metatable</code> is <b>nil</b>,
|
|
removes the metatable of the given table.
|
|
If the original metatable has a <code>"__metatable"</code> field,
|
|
raises an error.
|
|
|
|
|
|
<p>
|
|
This function returns <code>table</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
|
|
Tries to convert its argument to a number.
|
|
If the argument is already a number or a string convertible
|
|
to a number, then <code>tonumber</code> returns this number;
|
|
otherwise, it returns <b>nil</b>.
|
|
|
|
|
|
<p>
|
|
An optional argument specifies the base to interpret the numeral.
|
|
The base may be any integer between 2 and 36, inclusive.
|
|
In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
|
|
represents 10, '<code>B</code>' represents 11, and so forth,
|
|
with '<code>Z</code>' representing 35.
|
|
In base 10 (the default), the number can have a decimal part,
|
|
as well as an optional exponent part (see <a href="#2.1">§2.1</a>).
|
|
In other bases, only unsigned integers are accepted.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3>
|
|
Receives an argument of any type and
|
|
converts it to a string in a reasonable format.
|
|
For complete control of how numbers are converted,
|
|
use <a href="#pdf-string.format"><code>string.format</code></a>.
|
|
|
|
|
|
<p>
|
|
If the metatable of <code>e</code> has a <code>"__tostring"</code> field,
|
|
then <code>tostring</code> calls the corresponding value
|
|
with <code>e</code> as argument,
|
|
and uses the result of the call as its result.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
|
|
Returns the type of its only argument, coded as a string.
|
|
The possible results of this function are
|
|
"<code>nil</code>" (a string, not the value <b>nil</b>),
|
|
"<code>number</code>",
|
|
"<code>string</code>",
|
|
"<code>boolean</code>",
|
|
"<code>table</code>",
|
|
"<code>function</code>",
|
|
"<code>thread</code>",
|
|
and "<code>userdata</code>".
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3>
|
|
Returns the elements from the given table.
|
|
This function is equivalent to
|
|
|
|
<pre>
|
|
return list[i], list[i+1], ···, list[j]
|
|
</pre><p>
|
|
except that the above code can be written only for a fixed number
|
|
of elements.
|
|
By default, <code>i</code> is 1 and <code>j</code> is the length of the list,
|
|
as defined by the length operator (see <a href="#2.5.5">§2.5.5</a>).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
|
|
A global variable (not a function) that
|
|
holds a string containing the current interpreter version.
|
|
The current contents of this variable is "<code>Lua 5.1</code>".
|
|
|
|
|
|
|
|
|
|
<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2>
|
|
|
|
<p>
|
|
The operations related to coroutines comprise a sub-library of
|
|
the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
|
|
See <a href="#2.11">§2.11</a> for a general description of coroutines.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Creates a new coroutine, with body <code>f</code>.
|
|
<code>f</code> must be a Lua function.
|
|
Returns this new coroutine,
|
|
an object with type <code>"thread"</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Starts or continues the execution of coroutine <code>co</code>.
|
|
The first time you resume a coroutine,
|
|
it starts running its body.
|
|
The values <code>val1</code>, ··· are passed
|
|
as the arguments to the body function.
|
|
If the coroutine has yielded,
|
|
<code>resume</code> restarts it;
|
|
the values <code>val1</code>, ··· are passed
|
|
as the results from the yield.
|
|
|
|
|
|
<p>
|
|
If the coroutine runs without any errors,
|
|
<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
|
|
(if the coroutine yields) or any values returned by the body function
|
|
(if the coroutine terminates).
|
|
If there is any error,
|
|
<code>resume</code> returns <b>false</b> plus the error message.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the running coroutine,
|
|
or <b>nil</b> when called by the main thread.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the status of coroutine <code>co</code>, as a string:
|
|
<code>"running"</code>,
|
|
if the coroutine is running (that is, it called <code>status</code>);
|
|
<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
|
|
or if it has not started running yet;
|
|
<code>"normal"</code> if the coroutine is active but not running
|
|
(that is, it has resumed another coroutine);
|
|
and <code>"dead"</code> if the coroutine has finished its body function,
|
|
or if it has stopped with an error.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Creates a new coroutine, with body <code>f</code>.
|
|
<code>f</code> must be a Lua function.
|
|
Returns a function that resumes the coroutine each time it is called.
|
|
Any arguments passed to the function behave as the
|
|
extra arguments to <code>resume</code>.
|
|
Returns the same values returned by <code>resume</code>,
|
|
except the first boolean.
|
|
In case of error, propagates the error.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Suspends the execution of the calling coroutine.
|
|
The coroutine cannot be running a primitive implemented in
|
|
C, a metamethod, or an iterator.
|
|
Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>5.4 - <a name="5.4">String Manipulation</a></h2>
|
|
|
|
<p>
|
|
This library provides generic functions for string manipulation,
|
|
such as finding and extracting substrings, and pattern matching.
|
|
When indexing a string in Lua, the first character is at position 1
|
|
(not at 0, as in C).
|
|
Indices are allowed to be negative and are interpreted as indexing backwards,
|
|
from the end of the string.
|
|
Thus, the last character is at position -1, and so on.
|
|
|
|
|
|
<p>
|
|
The string library provides all its functions inside the table
|
|
<a name="pdf-string"><code>string</code></a>.
|
|
It also sets a metatable for strings
|
|
where the <code>__index</code> field points to the <code>string</code> table.
|
|
Therefore, you can use the string functions in object-oriented style.
|
|
For instance, <code>string.byte(s, i)</code>
|
|
can be written as <code>s:byte(i)</code>.
|
|
|
|
|
|
<p>
|
|
The string library assumes one-byte character encodings.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
|
|
Returns the internal numerical codes of the characters <code>s[i]</code>,
|
|
<code>s[i+1]</code>, ···, <code>s[j]</code>.
|
|
The default value for <code>i</code> is 1;
|
|
the default value for <code>j</code> is <code>i</code>.
|
|
|
|
|
|
<p>
|
|
Note that numerical codes are not necessarily portable across platforms.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
|
|
Receives zero or more integers.
|
|
Returns a string with length equal to the number of arguments,
|
|
in which each character has the internal numerical code equal
|
|
to its corresponding argument.
|
|
|
|
|
|
<p>
|
|
Note that numerical codes are not necessarily portable across platforms.
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
|
|
Looks for the first match of
|
|
<code>pattern</code> in the string <code>s</code>.
|
|
If it finds a match, then <code>find</code> returns the indices of <code>s</code>
|
|
where this occurrence starts and ends;
|
|
otherwise, it returns <b>nil</b>.
|
|
A third, optional numerical argument <code>init</code> specifies
|
|
where to start the search;
|
|
its default value is 1 and can be negative.
|
|
A value of <b>true</b> as a fourth, optional argument <code>plain</code>
|
|
turns off the pattern matching facilities,
|
|
so the function does a plain "find substring" operation,
|
|
with no characters in <code>pattern</code> being considered "magic".
|
|
Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
|
|
|
|
|
|
<p>
|
|
If the pattern has captures,
|
|
then in a successful match
|
|
the captured values are also returned,
|
|
after the two indices.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
|
|
Returns a formatted version of its variable number of arguments
|
|
following the description given in its first argument (which must be a string).
|
|
The format string follows the same rules as the <code>printf</code> family of
|
|
standard C functions.
|
|
The only differences are that the options/modifiers
|
|
<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>,
|
|
and <code>h</code> are not supported
|
|
and that there is an extra option, <code>q</code>.
|
|
The <code>q</code> option formats a string in a form suitable to be safely read
|
|
back by the Lua interpreter:
|
|
the string is written between double quotes,
|
|
and all double quotes, newlines, embedded zeros,
|
|
and backslashes in the string
|
|
are correctly escaped when written.
|
|
For instance, the call
|
|
|
|
<pre>
|
|
string.format('%q', 'a string with "quotes" and \n new line')
|
|
</pre><p>
|
|
will produce the string:
|
|
|
|
<pre>
|
|
"a string with \"quotes\" and \
|
|
new line"
|
|
</pre>
|
|
|
|
<p>
|
|
The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>,
|
|
<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all
|
|
expect a number as argument,
|
|
whereas <code>q</code> and <code>s</code> expect a string.
|
|
|
|
|
|
<p>
|
|
This function does not accept string values
|
|
containing embedded zeros,
|
|
except as arguments to the <code>q</code> option.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
|
|
Returns an iterator function that,
|
|
each time it is called,
|
|
returns the next captures from <code>pattern</code> over string <code>s</code>.
|
|
If <code>pattern</code> specifies no captures,
|
|
then the whole match is produced in each call.
|
|
|
|
|
|
<p>
|
|
As an example, the following loop
|
|
|
|
<pre>
|
|
s = "hello world from Lua"
|
|
for w in string.gmatch(s, "%a+") do
|
|
print(w)
|
|
end
|
|
</pre><p>
|
|
will iterate over all the words from string <code>s</code>,
|
|
printing one per line.
|
|
The next example collects all pairs <code>key=value</code> from the
|
|
given string into a table:
|
|
|
|
<pre>
|
|
t = {}
|
|
s = "from=world, to=Lua"
|
|
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
|
|
t[k] = v
|
|
end
|
|
</pre>
|
|
|
|
<p>
|
|
For this function, a '<code>^</code>' at the start of a pattern does not
|
|
work as an anchor, as this would prevent the iteration.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
|
|
Returns a copy of <code>s</code>
|
|
in which all (or the first <code>n</code>, if given)
|
|
occurrences of the <code>pattern</code> have been
|
|
replaced by a replacement string specified by <code>repl</code>,
|
|
which can be a string, a table, or a function.
|
|
<code>gsub</code> also returns, as its second value,
|
|
the total number of matches that occurred.
|
|
|
|
|
|
<p>
|
|
If <code>repl</code> is a string, then its value is used for replacement.
|
|
The character <code>%</code> works as an escape character:
|
|
any sequence in <code>repl</code> of the form <code>%<em>n</em></code>,
|
|
with <em>n</em> between 1 and 9,
|
|
stands for the value of the <em>n</em>-th captured substring (see below).
|
|
The sequence <code>%0</code> stands for the whole match.
|
|
The sequence <code>%%</code> stands for a single <code>%</code>.
|
|
|
|
|
|
<p>
|
|
If <code>repl</code> is a table, then the table is queried for every match,
|
|
using the first capture as the key;
|
|
if the pattern specifies no captures,
|
|
then the whole match is used as the key.
|
|
|
|
|
|
<p>
|
|
If <code>repl</code> is a function, then this function is called every time a
|
|
match occurs, with all captured substrings passed as arguments,
|
|
in order;
|
|
if the pattern specifies no captures,
|
|
then the whole match is passed as a sole argument.
|
|
|
|
|
|
<p>
|
|
If the value returned by the table query or by the function call
|
|
is a string or a number,
|
|
then it is used as the replacement string;
|
|
otherwise, if it is <b>false</b> or <b>nil</b>,
|
|
then there is no replacement
|
|
(that is, the original match is kept in the string).
|
|
|
|
|
|
<p>
|
|
Here are some examples:
|
|
|
|
<pre>
|
|
x = string.gsub("hello world", "(%w+)", "%1 %1")
|
|
--> x="hello hello world world"
|
|
|
|
x = string.gsub("hello world", "%w+", "%0 %0", 1)
|
|
--> x="hello hello world"
|
|
|
|
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
|
|
--> x="world hello Lua from"
|
|
|
|
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
|
|
--> x="home = /home/roberto, user = roberto"
|
|
|
|
local t = {name="lua", version="5.1"}
|
|
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
|
|
--> x="lua-5.1.tar.gz"
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
|
|
Receives a string and returns its length.
|
|
The empty string <code>""</code> has length 0.
|
|
Embedded zeros are counted,
|
|
so <code>"a\000bc\000"</code> has length 5.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
|
|
Receives a string and returns a copy of this string with all
|
|
uppercase letters changed to lowercase.
|
|
All other characters are left unchanged.
|
|
The definition of what an uppercase letter is depends on the current locale.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
|
|
Looks for the first <em>match</em> of
|
|
<code>pattern</code> in the string <code>s</code>.
|
|
If it finds one, then <code>match</code> returns
|
|
the captures from the pattern;
|
|
otherwise it returns <b>nil</b>.
|
|
If <code>pattern</code> specifies no captures,
|
|
then the whole match is returned.
|
|
A third, optional numerical argument <code>init</code> specifies
|
|
where to start the search;
|
|
its default value is 1 and can be negative.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3>
|
|
Returns a string that is the concatenation of <code>n</code> copies of
|
|
the string <code>s</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
|
|
Returns a string that is the string <code>s</code> reversed.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
|
|
Returns the substring of <code>s</code> that
|
|
starts at <code>i</code> and continues until <code>j</code>;
|
|
<code>i</code> and <code>j</code> can be negative.
|
|
If <code>j</code> is absent, then it is assumed to be equal to -1
|
|
(which is the same as the string length).
|
|
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>
|
|
with length <code>i</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
|
|
Receives a string and returns a copy of this string with all
|
|
lowercase letters changed to uppercase.
|
|
All other characters are left unchanged.
|
|
The definition of what a lowercase letter is depends on the current locale.
|
|
|
|
|
|
|
|
<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3>
|
|
|
|
|
|
<h4>Character Class:</h4><p>
|
|
A <em>character class</em> is used to represent a set of characters.
|
|
The following combinations are allowed in describing a character class:
|
|
|
|
<ul>
|
|
|
|
<li><b><em>x</em>:</b>
|
|
(where <em>x</em> is not one of the <em>magic characters</em>
|
|
<code>^$()%.[]*+-?</code>)
|
|
represents the character <em>x</em> itself.
|
|
</li>
|
|
|
|
<li><b><code>.</code>:</b> (a dot) represents all characters.</li>
|
|
|
|
<li><b><code>%a</code>:</b> represents all letters.</li>
|
|
|
|
<li><b><code>%c</code>:</b> represents all control characters.</li>
|
|
|
|
<li><b><code>%d</code>:</b> represents all digits.</li>
|
|
|
|
<li><b><code>%l</code>:</b> represents all lowercase letters.</li>
|
|
|
|
<li><b><code>%p</code>:</b> represents all punctuation characters.</li>
|
|
|
|
<li><b><code>%s</code>:</b> represents all space characters.</li>
|
|
|
|
<li><b><code>%u</code>:</b> represents all uppercase letters.</li>
|
|
|
|
<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li>
|
|
|
|
<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li>
|
|
|
|
<li><b><code>%z</code>:</b> represents the character with representation 0.</li>
|
|
|
|
<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character)
|
|
represents the character <em>x</em>.
|
|
This is the standard way to escape the magic characters.
|
|
Any punctuation character (even the non magic)
|
|
can be preceded by a '<code>%</code>'
|
|
when used to represent itself in a pattern.
|
|
</li>
|
|
|
|
<li><b><code>[<em>set</em>]</code>:</b>
|
|
represents the class which is the union of all
|
|
characters in <em>set</em>.
|
|
A range of characters can be specified by
|
|
separating the end characters of the range with a '<code>-</code>'.
|
|
All classes <code>%</code><em>x</em> described above can also be used as
|
|
components in <em>set</em>.
|
|
All other characters in <em>set</em> represent themselves.
|
|
For example, <code>[%w_]</code> (or <code>[_%w]</code>)
|
|
represents all alphanumeric characters plus the underscore,
|
|
<code>[0-7]</code> represents the octal digits,
|
|
and <code>[0-7%l%-]</code> represents the octal digits plus
|
|
the lowercase letters plus the '<code>-</code>' character.
|
|
|
|
|
|
<p>
|
|
The interaction between ranges and classes is not defined.
|
|
Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
|
|
have no meaning.
|
|
</li>
|
|
|
|
<li><b><code>[^<em>set</em>]</code>:</b>
|
|
represents the complement of <em>set</em>,
|
|
where <em>set</em> is interpreted as above.
|
|
</li>
|
|
|
|
</ul><p>
|
|
For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
|
|
the corresponding uppercase letter represents the complement of the class.
|
|
For instance, <code>%S</code> represents all non-space characters.
|
|
|
|
|
|
<p>
|
|
The definitions of letter, space, and other character groups
|
|
depend on the current locale.
|
|
In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
|
|
|
|
|
|
|
|
|
|
|
|
<h4>Pattern Item:</h4><p>
|
|
A <em>pattern item</em> can be
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
a single character class,
|
|
which matches any single character in the class;
|
|
</li>
|
|
|
|
<li>
|
|
a single character class followed by '<code>*</code>',
|
|
which matches 0 or more repetitions of characters in the class.
|
|
These repetition items will always match the longest possible sequence;
|
|
</li>
|
|
|
|
<li>
|
|
a single character class followed by '<code>+</code>',
|
|
which matches 1 or more repetitions of characters in the class.
|
|
These repetition items will always match the longest possible sequence;
|
|
</li>
|
|
|
|
<li>
|
|
a single character class followed by '<code>-</code>',
|
|
which also matches 0 or more repetitions of characters in the class.
|
|
Unlike '<code>*</code>',
|
|
these repetition items will always match the <em>shortest</em> possible sequence;
|
|
</li>
|
|
|
|
<li>
|
|
a single character class followed by '<code>?</code>',
|
|
which matches 0 or 1 occurrence of a character in the class;
|
|
</li>
|
|
|
|
<li>
|
|
<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
|
|
such item matches a substring equal to the <em>n</em>-th captured string
|
|
(see below);
|
|
</li>
|
|
|
|
<li>
|
|
<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
|
|
such item matches strings that start with <em>x</em>, end with <em>y</em>,
|
|
and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
|
|
This means that, if one reads the string from left to right,
|
|
counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
|
|
the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
|
|
For instance, the item <code>%b()</code> matches expressions with
|
|
balanced parentheses.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h4>Pattern:</h4><p>
|
|
A <em>pattern</em> is a sequence of pattern items.
|
|
A '<code>^</code>' at the beginning of a pattern anchors the match at the
|
|
beginning of the subject string.
|
|
A '<code>$</code>' at the end of a pattern anchors the match at the
|
|
end of the subject string.
|
|
At other positions,
|
|
'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
|
|
|
|
|
|
|
|
|
|
|
|
<h4>Captures:</h4><p>
|
|
A pattern can contain sub-patterns enclosed in parentheses;
|
|
they describe <em>captures</em>.
|
|
When a match succeeds, the substrings of the subject string
|
|
that match captures are stored (<em>captured</em>) for future use.
|
|
Captures are numbered according to their left parentheses.
|
|
For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
|
|
the part of the string matching <code>"a*(.)%w(%s*)"</code> is
|
|
stored as the first capture (and therefore has number 1);
|
|
the character matching "<code>.</code>" is captured with number 2,
|
|
and the part matching "<code>%s*</code>" has number 3.
|
|
|
|
|
|
<p>
|
|
As a special case, the empty capture <code>()</code> captures
|
|
the current string position (a number).
|
|
For instance, if we apply the pattern <code>"()aa()"</code> on the
|
|
string <code>"flaaap"</code>, there will be two captures: 3 and 5.
|
|
|
|
|
|
<p>
|
|
A pattern cannot contain embedded zeros. Use <code>%z</code> instead.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p>
|
|
This library provides generic functions for table manipulation.
|
|
It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
|
|
|
|
|
|
<p>
|
|
Most functions in the table library assume that the table
|
|
represents an array or a list.
|
|
For these functions, when we talk about the "length" of a table
|
|
we mean the result of the length operator.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
|
|
Given an array where all elements are strings or numbers,
|
|
returns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>.
|
|
The default value for <code>sep</code> is the empty string,
|
|
the default for <code>i</code> is 1,
|
|
and the default for <code>j</code> is the length of the table.
|
|
If <code>i</code> is greater than <code>j</code>, returns the empty string.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>,
|
|
shifting up other elements to open space, if necessary.
|
|
The default value for <code>pos</code> is <code>n+1</code>,
|
|
where <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>),
|
|
so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
|
|
of table <code>t</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the largest positive numerical index of the given table,
|
|
or zero if the table has no positive numerical indices.
|
|
(To do its job this function does a linear traversal of
|
|
the whole table.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Removes from <code>table</code> the element at position <code>pos</code>,
|
|
shifting down other elements to close the space, if necessary.
|
|
Returns the value of the removed element.
|
|
The default value for <code>pos</code> is <code>n</code>,
|
|
where <code>n</code> is the length of the table,
|
|
so that a call <code>table.remove(t)</code> removes the last element
|
|
of table <code>t</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3>
|
|
Sorts table elements in a given order, <em>in-place</em>,
|
|
from <code>table[1]</code> to <code>table[n]</code>,
|
|
where <code>n</code> is the length of the table.
|
|
If <code>comp</code> is given,
|
|
then it must be a function that receives two table elements,
|
|
and returns true
|
|
when the first is less than the second
|
|
(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort).
|
|
If <code>comp</code> is not given,
|
|
then the standard Lua operator <code><</code> is used instead.
|
|
|
|
|
|
<p>
|
|
The sort algorithm is not stable;
|
|
that is, elements considered equal by the given order
|
|
may have their relative positions changed by the sort.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2>
|
|
|
|
<p>
|
|
This library is an interface to the standard C math library.
|
|
It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the absolute value of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the arc cosine of <code>x</code> (in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the arc sine of <code>x</code> (in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the arc tangent of <code>x</code> (in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the arc tangent of <code>y/x</code> (in radians),
|
|
but uses the signs of both parameters to find the
|
|
quadrant of the result.
|
|
(It also handles correctly the case of <code>x</code> being zero.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the smallest integer larger than or equal to <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the cosine of <code>x</code> (assumed to be in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the hyperbolic cosine of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the angle <code>x</code> (given in radians) in degrees.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the value <em>e<sup>x</sup></em>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the largest integer smaller than or equal to <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the remainder of the division of <code>x</code> by <code>y</code>
|
|
that rounds the quotient towards zero.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>,
|
|
<code>e</code> is an integer and the absolute value of <code>m</code> is
|
|
in the range <em>[0.5, 1)</em>
|
|
(or zero when <code>x</code> is zero).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
|
|
|
|
|
|
<p>
|
|
The value <code>HUGE_VAL</code>,
|
|
a value larger than or equal to any other numerical value.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the natural logarithm of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the base-10 logarithm of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the maximum value among its arguments.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the minimum value among its arguments.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns two numbers,
|
|
the integral part of <code>x</code> and the fractional part of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
|
|
|
|
|
|
<p>
|
|
The value of <em>pi</em>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns <em>x<sup>y</sup></em>.
|
|
(You can also use the expression <code>x^y</code> to compute this value.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the angle <code>x</code> (given in degrees) in radians.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
This function is an interface to the simple
|
|
pseudo-random generator function <code>rand</code> provided by ANSI C.
|
|
(No guarantees can be given for its statistical properties.)
|
|
|
|
|
|
<p>
|
|
When called without arguments,
|
|
returns a uniform pseudo-random real number
|
|
in the range <em>[0,1)</em>.
|
|
When called with an integer number <code>m</code>,
|
|
<code>math.random</code> returns
|
|
a uniform pseudo-random integer in the range <em>[1, m]</em>.
|
|
When called with two integer numbers <code>m</code> and <code>n</code>,
|
|
<code>math.random</code> returns a uniform pseudo-random
|
|
integer in the range <em>[m, n]</em>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets <code>x</code> as the "seed"
|
|
for the pseudo-random generator:
|
|
equal seeds produce equal sequences of numbers.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the sine of <code>x</code> (assumed to be in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the hyperbolic sine of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the square root of <code>x</code>.
|
|
(You can also use the expression <code>x^0.5</code> to compute this value.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the tangent of <code>x</code> (assumed to be in radians).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the hyperbolic tangent of <code>x</code>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>5.7 - <a name="5.7">File Input and Output Facilities</a></h2>
|
|
|
|
<div class='teliva'>
|
|
While Teliva supports the standard Lua primitives for managing files via
|
|
handles, idiomatic Teliva uses some slightly different primitives that use a
|
|
subtly different file object (name tbd).
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-start_reading"><code>start_reading (fs, filename)</code></a></h3>
|
|
|
|
<p>
|
|
This function opens a file exclusively for reading, and returns an object (NOT
|
|
a file handle as in Lua) or <b>nil</b> on error. If the returned object is
|
|
stored in variable <code>f</code>, <code>f.read(format)</code> will read from
|
|
the file. Legal values for <code>format</code> are identical to
|
|
<a href='#pdf-file:read'><code>file:read(format)</code></a>.
|
|
|
|
<p>
|
|
(The <code>fs</code> parameter is currently unused. It will be used to pass in
|
|
fake file systems for tests.)
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-start_writing"><code>start_writing(fs, filename)</code></a></h3>
|
|
|
|
<p>
|
|
This function opens a file exclusively for writing, and returns an object (NOT
|
|
a file handle as in Lua) or <b>nil</b> on error. If the result is stored in
|
|
variable <code>f</code>, <code>f.write(x)</code> will write <code>x</code> to
|
|
the file. <code>f.close()</code> will persist the changes and make them
|
|
externally visible. All changes will be hidden until <code>f.close()</code>.
|
|
|
|
<p>
|
|
(The <code>fs</code> parameter is currently unused. It will be used to pass in
|
|
fake file systems for tests.)
|
|
|
|
|
|
<hr>
|
|
The rest of this section describes Lua's standard primitives for File I/O.
|
|
</div>
|
|
|
|
|
|
<p>
|
|
Unless otherwise stated,
|
|
all File I/O functions return <b>nil</b> on failure
|
|
(plus an error message as a second result and
|
|
a system-dependent error code as a third result)
|
|
and some value different from <b>nil</b> on success.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-io.close"><code>io.close (file)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Equivalent to <code>file:close()</code>.
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
This function opens a file,
|
|
in the mode specified in the string <code>mode</code>.
|
|
It returns a new file handle,
|
|
or, in case of errors, <b>nil</b> plus an error message.
|
|
|
|
|
|
<p>
|
|
The <code>mode</code> string can be any of the following:
|
|
|
|
<ul>
|
|
<li><b>"r":</b> read mode (the default);</li>
|
|
<li><b>"w":</b> write mode;</li>
|
|
<li><b>"a":</b> append mode;</li>
|
|
<li><b>"r+":</b> update mode, all previous data is preserved;</li>
|
|
<li><b>"w+":</b> update mode, all previous data is erased;</li>
|
|
<li><b>"a+":</b> append update mode, previous data is preserved,
|
|
writing is only allowed at the end of file.</li>
|
|
</ul><p>
|
|
The <code>mode</code> string can also have a '<code>b</code>' at the end,
|
|
which is needed in some systems to open the file in binary mode.
|
|
This string is exactly what is used in the
|
|
standard C function <code>fopen</code>.
|
|
|
|
<div class='teliva'>
|
|
<em>This function is sandboxed. It may fail if the computer owner's
|
|
permissions disallow it.</em>
|
|
</div>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a handle for a temporary file.
|
|
This file is opened in update mode
|
|
and it is automatically removed when the program ends.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Checks whether <code>obj</code> is a valid file handle.
|
|
Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
|
|
<code>"closed file"</code> if <code>obj</code> is a closed file handle,
|
|
or <b>nil</b> if <code>obj</code> is not a file handle.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Closes <code>file</code>.
|
|
Note that files are automatically closed when
|
|
their handles are garbage collected,
|
|
but that takes an unpredictable amount of time to happen.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Saves any written data to <code>file</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns an iterator function that,
|
|
each time it is called,
|
|
returns a new line from the file.
|
|
Therefore, the construction
|
|
|
|
<pre>
|
|
for line in file:lines() do <em>body</em> end
|
|
</pre><p>
|
|
will iterate over all lines of the file.
|
|
(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
|
|
when the loop ends.)
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Reads the file <code>file</code>,
|
|
according to the given formats, which specify what to read.
|
|
For each format,
|
|
the function returns a string (or a number) with the characters read,
|
|
or <b>nil</b> if it cannot read data with the specified format.
|
|
When called without formats,
|
|
it uses a default format that reads the entire next line
|
|
(see below).
|
|
|
|
|
|
<p>
|
|
The available formats are
|
|
|
|
<ul>
|
|
|
|
<li><b>"*n":</b>
|
|
reads a number;
|
|
this is the only format that returns a number instead of a string.
|
|
</li>
|
|
|
|
<li><b>"*a":</b>
|
|
reads the whole file, starting at the current position.
|
|
On end of file, it returns the empty string.
|
|
</li>
|
|
|
|
<li><b>"*l":</b>
|
|
reads the next line (skipping the end of line),
|
|
returning <b>nil</b> on end of file.
|
|
This is the default format.
|
|
</li>
|
|
|
|
<li><b><em>number</em>:</b>
|
|
reads a string with up to this number of characters,
|
|
returning <b>nil</b> on end of file.
|
|
If number is zero,
|
|
it reads nothing and returns an empty string,
|
|
or <b>nil</b> on end of file.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets and gets the file position,
|
|
measured from the beginning of the file,
|
|
to the position given by <code>offset</code> plus a base
|
|
specified by the string <code>whence</code>, as follows:
|
|
|
|
<ul>
|
|
<li><b>"set":</b> base is position 0 (beginning of the file);</li>
|
|
<li><b>"cur":</b> base is current position;</li>
|
|
<li><b>"end":</b> base is end of file;</li>
|
|
</ul><p>
|
|
In case of success, function <code>seek</code> returns the final file position,
|
|
measured in bytes from the beginning of the file.
|
|
If this function fails, it returns <b>nil</b>,
|
|
plus a string describing the error.
|
|
|
|
|
|
<p>
|
|
The default value for <code>whence</code> is <code>"cur"</code>,
|
|
and for <code>offset</code> is 0.
|
|
Therefore, the call <code>file:seek()</code> returns the current
|
|
file position, without changing it;
|
|
the call <code>file:seek("set")</code> sets the position to the
|
|
beginning of the file (and returns 0);
|
|
and the call <code>file:seek("end")</code> sets the position to the
|
|
end of the file, and returns its size.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets the buffering mode for an output file.
|
|
There are three available modes:
|
|
|
|
<ul>
|
|
|
|
<li><b>"no":</b>
|
|
no buffering; the result of any output operation appears immediately.
|
|
</li>
|
|
|
|
<li><b>"full":</b>
|
|
full buffering; output operation is performed only
|
|
when the buffer is full (or when you explicitly <code>flush</code> the file
|
|
(see <a href="#pdf-io.flush"><code>io.flush</code></a>)).
|
|
</li>
|
|
|
|
<li><b>"line":</b>
|
|
line buffering; output is buffered until a newline is output
|
|
or there is any input from some special files
|
|
(such as a terminal device).
|
|
</li>
|
|
|
|
</ul><p>
|
|
For the last two cases, <code>size</code>
|
|
specifies the size of the buffer, in bytes.
|
|
The default is an appropriate size.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Writes the value of each of its arguments to
|
|
the <code>file</code>.
|
|
The arguments must be strings or numbers.
|
|
To write other values,
|
|
use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2>
|
|
|
|
<p>
|
|
This library is implemented through table <a name="pdf-os"><code>os</code></a>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns an approximation of the amount in seconds of CPU time
|
|
used by the program.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a string or a table containing date and time,
|
|
formatted according to the given string <code>format</code>.
|
|
|
|
|
|
<p>
|
|
If the <code>time</code> argument is present,
|
|
this is the time to be formatted
|
|
(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
|
|
Otherwise, <code>date</code> formats the current time.
|
|
|
|
|
|
<p>
|
|
If <code>format</code> starts with '<code>!</code>',
|
|
then the date is formatted in Coordinated Universal Time.
|
|
After this optional character,
|
|
if <code>format</code> is the string "<code>*t</code>",
|
|
then <code>date</code> returns a table with the following fields:
|
|
<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31),
|
|
<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61),
|
|
<code>wday</code> (weekday, Sunday is 1),
|
|
<code>yday</code> (day of the year),
|
|
and <code>isdst</code> (daylight saving flag, a boolean).
|
|
|
|
|
|
<p>
|
|
If <code>format</code> is not "<code>*t</code>",
|
|
then <code>date</code> returns the date as a string,
|
|
formatted according to the same rules as the C function <code>strftime</code>.
|
|
|
|
|
|
<p>
|
|
When called without arguments,
|
|
<code>date</code> returns a reasonable date and time representation that depends on
|
|
the host system and on the current locale
|
|
(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the number of seconds from time <code>t1</code> to time <code>t2</code>.
|
|
In POSIX, Windows, and some other systems,
|
|
this value is exactly <code>t2</code><em>-</em><code>t1</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Calls the C function <code>exit</code>,
|
|
with an optional <code>code</code>,
|
|
to terminate the host program.
|
|
The default value for <code>code</code> is the success code.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Deletes the file or directory with the given name.
|
|
Directories must be empty to be removed.
|
|
If this function fails, it returns <b>nil</b>,
|
|
plus a string describing the error.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Renames 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.
|
|
|
|
<div class='teliva'>
|
|
<em>This function is sandboxed. It may fail if the computer owner's
|
|
permissions disallow it.</em>
|
|
</div>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets the current locale of the program.
|
|
<code>locale</code> is a string specifying a locale;
|
|
<code>category</code> is an optional string describing which category to change:
|
|
<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
|
|
<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
|
|
the default category is <code>"all"</code>.
|
|
The function returns the name of the new locale,
|
|
or <b>nil</b> if the request cannot be honored.
|
|
|
|
|
|
<p>
|
|
If <code>locale</code> is the empty string,
|
|
the current locale is set to an implementation-defined native locale.
|
|
If <code>locale</code> is the string "<code>C</code>",
|
|
the current locale is set to the standard C locale.
|
|
|
|
|
|
<p>
|
|
When called with <b>nil</b> as the first argument,
|
|
this function only returns the name of the current locale
|
|
for the given category.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns the current time when called without arguments,
|
|
or a time representing the date and time specified by the given table.
|
|
This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
|
|
and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code>
|
|
(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function).
|
|
|
|
|
|
<p>
|
|
The returned value is a number, whose meaning depends on your system.
|
|
In POSIX, Windows, and some other systems, this number counts the number
|
|
of seconds since some given start time (the "epoch").
|
|
In other systems, the meaning is not specified,
|
|
and the number returned by <code>time</code> can be used only as an argument to
|
|
<code>date</code> and <code>difftime</code>.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a string with a file name that can
|
|
be used for a temporary file.
|
|
The file must be explicitly opened before its use
|
|
and explicitly removed when no longer needed.
|
|
|
|
|
|
<p>
|
|
On some systems (POSIX),
|
|
this function also creates a file with that name,
|
|
to avoid security risks.
|
|
(Someone else might create the file with wrong permissions
|
|
in the time between getting the name and creating the file.)
|
|
You still have to open the file to use it
|
|
and to remove it (even if you do not use it).
|
|
|
|
|
|
<p>
|
|
When possible,
|
|
you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
|
|
which automatically removes the file when the program ends.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class='teliva'>
|
|
<h2>5.10 - <a name="5.10">Curses Window Facilities</a></h2>
|
|
|
|
Teliva includes curses facilities identical to Lua's <a href='http://lcurses.github.io/lcurses/'>lcurses</a>
|
|
library. As there, the top-level module is called <code>curses</code>. All apps
|
|
start with the terminal window initialized using
|
|
<a href="#pdf-curses.initscr"><code>curses.initscr</code></a>. Look at the
|
|
sample apps for example usage.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-curses.initscr"><code>curses.initscr ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Initializes the current terminal to stop scrolling and enable moving the
|
|
cursor. You shouldn't need to ever call this from Teliva; it's always called
|
|
for you before an app is loaded.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-curses.stdscr"><code>curses.stdscr ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a <em>window</em> object for the current terminal. Most curses
|
|
operations require a window. Windows are an app's gateway to both print to
|
|
screen and read keys from keyboard. Teliva's template.tlv for new applications
|
|
saves the result in a global called <code>Window</code>, so you should be able
|
|
to avoid calling <code>stdscr</code> directly most of the time.
|
|
|
|
<p>
|
|
Curses supports multiple and nested windows. They haven't been tried
|
|
yet in the context of Teliva, but they're expected to work. Please report your
|
|
experience if you try them out.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window"><code>window {}</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Creates a fake window suitable for passing around in tests. The table passed
|
|
in should have two keys: a <a href='#pdf-kbd'><code>kbd</code></a>
|
|
containing a keyboard, and a <a href='#pdf-scr'><code>scr</code></a>
|
|
containing a screen.
|
|
|
|
<p>
|
|
This helper is implemented in template.tlv, so new apps should pick it up from
|
|
there.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-kbd"><code>kbd (str)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Creates a fake keyboard suitable for passing into
|
|
<a href='#pdf-window'><code>window</code></a> with the characters in
|
|
<code>str</code> already “typed in”.
|
|
|
|
|
|
|
|
<p>
|
|
This helper is implemented in template.tlv, so new apps should pick it up from
|
|
there.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-scr"><code>scr {}</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Creates a fake screen suitable for passing into
|
|
<a href='#pdf-window'><code>window</code></a>. The table passed in should
|
|
contain two keys: a height <code>h</code> and a width <code>w</code>.
|
|
|
|
|
|
<p>
|
|
This helper is implemented in template.tlv, so new apps should pick it up from
|
|
there.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:clear"><code>window:clear ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Clears all prints in <code>window</code>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:refresh"><code>window:refresh ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Flushes all prints to <code>window</code>. Also redraws the Teliva menu.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:addch"><code>window:addch (c)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Prints character <code>c</code> with
|
|
<a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>the current attributes</a>
|
|
at the cursor in <code>window</code>. May not be visible until
|
|
<a href="#pdf-window:refresh"><code>window:refresh</code></a> is called.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:mvaddch"><code>window:mvaddch (y, x, c)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Moves <code>window</code>'s cursor to (<code>x</code>, <code>y</code>) before
|
|
printing character <code>c</code> to it with
|
|
<a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>the current attributes</a>.
|
|
May not be visible until <a href="#pdf-window:refresh"><code>window:refresh</code></a>
|
|
is called.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:addstr"><code>window:addstr (str)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Prints string <code>str</code> with
|
|
<a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>the current attributes</a>
|
|
at the cursor in <code>window</code>. May not be visible until
|
|
<a href="#pdf-window:refresh"><code>window:refresh</code></a> is called.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:mvaddstr"><code>window:mvaddstr (y, x, str)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Moves <code>window</code>'s cursor to (<code>x</code>, <code>y</code>) before
|
|
printing string <code>str</code> to it with
|
|
<a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>the current attributes</a>.
|
|
May not be visible until <a href="#pdf-window:refresh"><code>window:refresh</code></a> is called.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:getmaxyx"><code>window:getmaxyx ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns <code>window</code>'s <code>height</code> and <code>width</code>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:getyx"><code>window:getyx ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns <code>window</code>'s cursor coordinates <code>y</code> and
|
|
<code>x</code>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:attrset"><code>window:attrset (attr)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Sets <a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>the current attributes</a>
|
|
for future prints to <code>window</code>. Attributes can be one of:
|
|
|
|
<ul>
|
|
<li><code>curses.A_NORMAL</code>: disables all other attributes.
|
|
<li><code>curses.A_BOLD</code>
|
|
<li><code>curses.A_REVERSE</code>: swaps foreground and background colors.
|
|
<li><code>curses.color_pair(n)</code> for some integer <code>n</code>: color
|
|
pair <code>n</code> which must have been initialized using
|
|
<a href="#pdf-curses.init_pair"><code>curses.init_pair</code></a>.
|
|
</ul>
|
|
|
|
<p>
|
|
Since Lua 5.1 has no bitwise operations, this function currently only supports
|
|
setting a single attribute.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:attron"><code>window:attron (attr)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Adds the given <a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>attribute</a>
|
|
to the set of current attributes for future prints to <code>window</code>. For
|
|
the list of available attributes see <a href="#pdf-window:attrset"><code>window:attrset</code></a>.
|
|
|
|
<p>
|
|
Since Lua 5.1 has no bitwise operations, this function currently only supports
|
|
adding a single attribute at a time.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:attroff"><code>window:attroff (attr)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Removes the given <a href='https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html'>attribute</a>
|
|
from the set of current attributes for future prints to <code>window</code>.
|
|
the list of available attributes see <a href="#pdf-window:attrset"><code>window:attrset</code></a>.
|
|
|
|
<p>
|
|
Since Lua 5.1 has no bitwise operations, this function currently only supports
|
|
removing a single attribute at a time.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-curses.init_pair"><code>curses.init_pair (i, fg, bg)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Initializes color pair <code>i</code> to (<code>foreground</code>, <code>background</code>).
|
|
Now calls to <a href='#pdf-curses.color_pair'>curses.color_pair(i)</code></a> will
|
|
yield the attributes for that color pair.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-curses.color_pair"><code>curses.color_pair (i)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns attributes for a (<code>foreground</code>, <code>background</code>)
|
|
pair of colors suitable to pass into
|
|
<a href="#pdf-window:attrset"><code>window:attrset</code></a>,
|
|
<a href="#pdf-window:attron"><code>window:attron</code></a> and
|
|
<a href="#pdf-window:attroff"><code>window:attroff</code></a>.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:getch"><code>window:getch ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a character from the keyboard. Waits for a key to be pressed by
|
|
default, but this behavior can be changed by calling <a href="#pdf-window:nodelay"><code>window:nodelay(true)</code></a>.
|
|
|
|
<p>
|
|
<code>window:getch</code> is the only supported way to get input from
|
|
keyboard in Teliva, handling Teliva's menu and so on.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-window:nodelay"><code>window:nodelay (on)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Forces <a href="#pdf-window:getch"><code>window:getch()</code></a> to be non-blocking.
|
|
|
|
|
|
<hr>
|
|
Besides these, there are other primitives that have never been used in Teliva
|
|
apps, but should still work. Please report if you try them out.
|
|
|
|
</div>
|
|
|
|
<div class='teliva'>
|
|
<h2>5.11 - <a name="5.11">Networking Facilities</a></h2>
|
|
|
|
Teliva includes the following well-known Lua libraries for networking:
|
|
|
|
<li><a href='https://w3.impa.br/~diego/software/luasocket/reference.html'>LuaSocket</a>,
|
|
consisting of modules <code>socket</code>, <code>http</code>, <code>url</code>,
|
|
<code>headers</code>, <code>mime</code> and <code>ltn12</code>.
|
|
|
|
<li><a href='https://github.com/brunoos/luasec/wiki'>LuaSec</a>,
|
|
consisting of modules <code>https</code> and <code>ssl</code>.
|
|
|
|
<div class='teliva'>
|
|
<em>Networking primitives are sandboxed, and may fail if the computer owner's
|
|
permissions disallow it.</em>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class='teliva'>
|
|
<h2>5.12 - <a name="5.12">JSON Facilities</a></h2>
|
|
|
|
Teliva includes the well-known
|
|
<a href='https://github.com/rxi/json.lua'>json.lua</a> library (module
|
|
<code>json</code>). It also includes a variant in module <code>jsonf</code> that can
|
|
read JSON from channels opened by
|
|
<a href='#pdf-start_reading'><code>start_reading</code></a>.
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-json.encode"><code>json.encode (value)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a string representing <code>value</code> encoded in JSON.
|
|
|
|
<pre>
|
|
json.encode({ 1, 2, 3, { x = 10 } }) -- Returns '[1,2,3,{"x":10}]'
|
|
</pre><p>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-json.decode"><code>json.decode (str)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Returns a value representing the JSON string <code>str</code>.
|
|
|
|
<pre>
|
|
json.decode('[1,2,3,{"x":10}]') -- Returns { 1, 2, 3, { x = 10 } }
|
|
</pre><p>
|
|
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-jsonf.decode"><code>jsonf.decode (f)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Reads a value encoded in JSON from a file and returns it.
|
|
<code>f</code> is the type of file object returned by
|
|
<a href='#pdf-start_reading'><code>start_reading</code></a> (i.e. supporting
|
|
<code>f.read(format)</code>).
|
|
|
|
For example, suppose file <code>foo</code> contains '[1,2,3,{"x":10}]'. Then:
|
|
<pre>
|
|
local infile = start_reading(nil, 'foo')
|
|
jsonf.decode(infile) -- Returns { 1, 2, 3, { x = 10 } }
|
|
</pre><p>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<div class='teliva'>
|
|
<h2>5.13 - <a name="5.13">Tasks and Channels</a></h2>
|
|
|
|
Teliva includes the well-known
|
|
<a href='https://github.com/majek/lua-channels#readme'>lua-channels</a>
|
|
library in module <code>task</code>. See sieve.tlv for a basic example.
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-task.spawn"><code>task.spawn (fun, [...])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Run <code>fun</code> as a coroutine with given parameters. Spawn tasks instead of
|
|
just calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>
|
|
when you can't statically predict how your coroutines will transfer control to
|
|
each other.
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-task.scheduler"><code>task.scheduler ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Starts running any spawned tasks. Execution transfers to spawned tasks;
|
|
this function only returns when there are no tasks left to run or when all
|
|
tasks are blocked (deadlock).
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-Channel:new"><code>task.Channel:new ([size])</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Create a new channel with given size (which defaults to 0).
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-channel:send"><code>channel:send (value)</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Write <code>value</code> to a channel. Blocks the current coroutine if the
|
|
channel is already full. (Channels with size 0 always block if there isn't
|
|
already a coroutine trying to <a href="#pdf-channel:recv"><code>recv</code></a>
|
|
from them.)
|
|
|
|
|
|
<p>
|
|
<hr><h3><a name="pdf-channel:recv"><code>channel:recv ()</code></a></h3>
|
|
|
|
|
|
<p>
|
|
Read a value from a channel. Blocks the current coroutine if the
|
|
channel is empty and there isn't already a coroutine trying to
|
|
<a href="#pdf-channel:send"><code>send</code></a> to them.
|
|
|
|
|
|
<hr>
|
|
Besides these, there are other primitives that have never been used in Teliva
|
|
apps, but should still work. Please report if you try them out.
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1>
|
|
|
|
<p>
|
|
Here is the complete syntax of Lua in extended BNF.
|
|
(It does not describe operator precedences.)
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]]
|
|
|
|
block ::= chunk
|
|
|
|
stat ::= varlist `<b>=</b>´ explist |
|
|
functioncall |
|
|
<b>do</b> block <b>end</b> |
|
|
<b>while</b> exp <b>do</b> block <b>end</b> |
|
|
<b>repeat</b> block <b>until</b> exp |
|
|
<b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
|
|
<b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> |
|
|
<b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
|
|
<b>function</b> funcname funcbody |
|
|
<b>local</b> <b>function</b> Name funcbody |
|
|
<b>local</b> namelist [`<b>=</b>´ explist]
|
|
|
|
laststat ::= <b>return</b> [explist] | <b>break</b>
|
|
|
|
funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name]
|
|
|
|
varlist ::= var {`<b>,</b>´ var}
|
|
|
|
var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name
|
|
|
|
namelist ::= Name {`<b>,</b>´ Name}
|
|
|
|
explist ::= {exp `<b>,</b>´} exp
|
|
|
|
exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function |
|
|
prefixexp | tableconstructor | exp binop exp | unop exp
|
|
|
|
prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´
|
|
|
|
functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args
|
|
|
|
args ::= `<b>(</b>´ [explist] `<b>)</b>´ | tableconstructor | String
|
|
|
|
function ::= <b>function</b> funcbody
|
|
|
|
funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b>
|
|
|
|
parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´
|
|
|
|
tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´
|
|
|
|
fieldlist ::= field {fieldsep field} [fieldsep]
|
|
|
|
field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
|
|
|
|
fieldsep ::= `<b>,</b>´ | `<b>;</b>´
|
|
|
|
binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ |
|
|
`<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ |
|
|
<b>and</b> | <b>or</b>
|
|
|
|
unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´
|
|
|
|
</pre>
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
<SMALL CLASS="footer">
|
|
Last update:
|
|
Mon Feb 13 18:54:19 BRST 2012
|
|
</SMALL>
|
|
|
|
</body></html>
|
|
|