Mercurial Hosting > luan
changeset 776:815c119dac7a
remove docs
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Fri, 26 Aug 2016 14:39:18 -0600 |
| parents | 1a68fc55a80c |
| children | 1460d297e960 |
| files | docs/lua.css docs/manual.css docs/manual.html |
| diffstat | 3 files changed, 0 insertions(+), 5839 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/lua.css Fri Aug 26 14:36:40 2016 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,105 +0,0 @@ -html { - background-color: #F8F8F8 ; -} - -body { - border: solid #a0a0a0 1px ; - border-radius: 20px ; - padding: 26px ; - margin: 16px ; - color: #000000 ; - background-color: #FFFFFF ; - font-family: Helvetica, Arial, sans-serif ; - text-align: justify ; -} - -h1, h2, h3, h4 { - font-family: Verdana, Geneva, sans-serif ; - font-weight: normal ; - font-style: normal ; -} - -h2 { - padding-top: 0.4em ; - padding-bottom: 0.4em ; - padding-left: 0.8em ; - padding-right: 0.8em ; - background-color: #D0D0FF ; - border-radius: 8px ; - border: solid #a0a0a0 1px ; -} - -h3 { - padding-left: 0.5em ; - border-left: solid #D0D0FF 1em ; -} - -table h3 { - padding-left: 0px ; - border-left: none ; -} - -a:link { - color: #000080 ; - background-color: inherit ; - text-decoration: none ; -} - -a:visited { - background-color: inherit ; - text-decoration: none ; -} - -a:link:hover, a:visited:hover { - color: #000080 ; - background-color: #D0D0FF ; - border-radius: 4px; -} - -a:link:active, a:visited:active { - color: #FF0000 ; -} - -h1 a img { - vertical-align: text-bottom ; -} - -hr { - border: 0 ; - height: 1px ; - color: #a0a0a0 ; - background-color: #a0a0a0 ; - display: none ; -} - -table hr { - display: block ; -} - -:target { - background-color: #F8F8F8 ; - padding: 8px ; - border: solid #a0a0a0 2px ; - border-radius: 8px ; -} - -.footer { - color: gray ; - font-size: x-small ; -} - -input[type=text] { - border: solid #a0a0a0 2px ; - border-radius: 2em ; - background-image: url('images/search.png') ; - background-repeat: no-repeat ; - background-position: 4px center ; - padding-left: 20px ; - height: 2em ; -} - -pre.session { - background-color: #F8F8F8 ; - padding: 1em ; - border-radius: 8px ; -}
--- a/docs/manual.css Fri Aug 26 14:36:40 2016 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,27 +0,0 @@ -h3 code { - font-family: inherit ; - font-size: inherit ; -} - -pre, code { - font-size: 12pt ; -} - -span.apii { - float: right ; - font-family: inherit ; - font-style: normal ; - font-size: small ; - color: gray ; -} - -h1:not(.main) { - font-style: normal ; - padding-top: 0.4em ; - padding-bottom: 0.4em ; - padding-left: 16px ; - margin-left: -16px ; - background-color: #D0D0FF ; - border-radius: 8px ; - border: solid #000080 1px ; -}
--- a/docs/manual.html Fri Aug 26 14:36:40 2016 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5707 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> - -<head> -<title>Luan 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 class="main"> -Luan Reference Manual -</h1> - -<P> -The reference manual is the official definition of the Luan language. - -<p> -<small> -Original Copyright © 2011–2013 Lua.org, PUC-Rio. -Freely available under the terms of the -<a href="http://www.lua.org/license.html">Lua license</a>. -Modified for Luan in 2014. -</small> -<hr> -<p> - - -<!-- ====================================================================== --> -<p> - -<!-- $Id: manual.of,v 1.103 2013/03/14 18:51:56 roberto Exp $ --> - - -<H2><A NAME="contents">Contents</A></H2> -<UL style="padding: 0"> -<LI><A HREF="#1">1 – Introduction</A> -<P> -<LI><A HREF="#2">2 – Basic Concepts</A> -<UL> -<LI><A HREF="#2.1">2.1 – Values and Types</A> -<LI><A HREF="#2.2">2.2 – Environments and the Global Environment</A> -<LI><A HREF="#2.3">2.3 – Error Handling</A> -<LI><A HREF="#2.4">2.4 – Metatables and Metamethods</A> -<LI><A HREF="#2.5">2.5 – Garbage Collection</A> -<UL> -<LI><A HREF="#2.5.1">2.5.1 – Garbage-Collection Metamethods</A> -<LI><A HREF="#2.5.2">2.5.2 – Weak Tables</A> -</UL> -<LI><A HREF="#2.6">2.6 – Coroutines</A> -</UL> -<P> -<LI><A HREF="#3">3 – The Language</A> -<UL> -<LI><A HREF="#3.1">3.1 – Lexical Conventions</A> -<LI><A HREF="#3.2">3.2 – Variables</A> -<LI><A HREF="#3.3">3.3 – Statements</A> -<UL> -<LI><A HREF="#3.3.1">3.3.1 – Blocks</A> -<LI><A HREF="#3.3.2">3.3.2 – Chunks</A> -<LI><A HREF="#3.3.3">3.3.3 – Assignment</A> -<LI><A HREF="#3.3.4">3.3.4 – Control Structures</A> -<LI><A HREF="#3.3.5">3.3.5 – For Statement</A> -<LI><A HREF="#3.3.6">3.3.6 – Function Calls as Statements</A> -<LI><A HREF="#3.3.7">3.3.7 – Local Declarations</A> -<LI><A HREF="#3.3.8">3.3.8 – Or/And Statements</A> -</UL> -<LI><A HREF="#3.4">3.4 – Expressions</A> -<UL> -<LI><A HREF="#3.4.1">3.4.1 – Arithmetic Operators</A> -<LI><A HREF="#3.4.2">3.4.2 – Coercion</A> -<LI><A HREF="#3.4.3">3.4.3 – Relational Operators</A> -<LI><A HREF="#3.4.4">3.4.4 – Logical Operators</A> -<LI><A HREF="#3.4.5">3.4.5 – Concatenation</A> -<LI><A HREF="#3.4.6">3.4.6 – The Length Operator</A> -<LI><A HREF="#3.4.7">3.4.7 – Precedence</A> -<LI><A HREF="#3.4.8">3.4.8 – Table Constructors</A> -<LI><A HREF="#3.4.9">3.4.9 – Function Calls</A> -<LI><A HREF="#3.4.10">3.4.10 – Function Definitions</A> -</UL> -<LI><A HREF="#3.5">3.5 – Visibility Rules</A> -</UL> -<P> -<LI><A HREF="#4">4 – The Application Program Interface</A> -<P> -<LI><A HREF="#5">5 – The Auxiliary Library</A> -<P> -<LI><A HREF="#6">6 – Standard Libraries</A> -<UL> -<LI><A HREF="#6.1">6.1 – Basic Functions</A> -<LI><A HREF="#6.2">6.2 – Coroutine Manipulation</A> -<LI><A HREF="#6.3">6.3 – Modules</A> -<LI><A HREF="#6.4">6.4 – String Manipulation</A> -<UL> -<LI><A HREF="#6.4.1">6.4.1 – Patterns</A> -</UL> -<LI><A HREF="#6.5">6.5 – Table Manipulation</A> -<LI><A HREF="#6.6">6.6 – Mathematical Functions</A> -<LI><A HREF="#6.7">6.7 – Bitwise Operations</A> -<LI><A HREF="#6.8">6.8 – Input and Output Facilities</A> -<LI><A HREF="#6.9">6.9 – Operating System Facilities</A> -<LI><A HREF="#6.10">6.10 – The Debug Library</A> -</UL> -<P> -<LI><A HREF="#7">7 – Lua Standalone</A> -<P> -<LI><A HREF="#8">8 – Incompatibilities with the Previous Version</A> -<UL> -<LI><A HREF="#8.1">8.1 – Changes in the Language</A> -<LI><A HREF="#8.2">8.2 – Changes in the Libraries</A> -<LI><A HREF="#8.3">8.3 – Changes in the API</A> -</UL> -<P> -<LI><A HREF="#9">9 – The Complete Syntax of Lua</A> -</UL> - - -<h1>1 – <a name="1">Introduction</a></h1> - -<p>Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that programmers can quickly learn the language and then easily understand any code written in Luan. - -<p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers. By importing the <em>Java</em> package, one can directly call Java from Luan. - -<p>Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding feature to Luan, but rather by providing a complete set of libraries. - -<h1>2 – <a name="2">Basic Concepts</a></h1> - -<p> -This section describes the basic concepts of the language. - - - -<h2>2.1 – <a name="2.1">Values and Types</a></h2> - -<p> -Luan 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 Luan 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>binary</em>, <em>function</em>, <em>userdata</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>Nil</em> is implemented as the Java value <em>null</em>. -<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. -<em>Boolean</em> is implemented as the Java class <em>Boolean</em>. -<em>Number</em> represents real (double-precision floating-point) numbers. -<em>Number</em> is implemented as the Java class <em>Number</em>. Any Java subclass of <em>Number</em> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of -the underlying Java implementation. - -<em>String</em> is implemented as the Java class <em>String</em>. -<em>Binary</em> is implemented as the Java type <em>byte[]</em>. - - -<p> -Luan can call (and manipulate) functions written in Luan and -functions written in Java -(see <a href="#3.4.9">§3.4.9</a>). - - -<p> -The type <em>userdata</em> is provided to allow arbitrary Java objects to -be stored in Lua variables. -A userdata value is a Java object that isn't of the standard Luan types. - - -<p> -Lua has a type <em>thread</em> that Luan lacks because Luan does not have the Lua concept of coroutines. - - -<p> -The type <em>table</em> implements associative arrays, -that is, arrays that can be indexed not only with numbers, -but with any Lua value except <b>nil</b>. -Tables can be <em>heterogeneous</em>; -that is, they can contain values of all types (except <b>nil</b>). -Any key with value <b>nil</b> is not considered part of the table. -Conversely, any key that is not part of a table has -an associated value <b>nil</b>. - - -<p> -Tables are the sole data structuring mechanism in Lua; -they can be used to represent ordinary arrays, sequences, -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="#3.4.8">§3.4.8</a>). - - -<p> -We use the term <em>sequence</em> to denote a table where -the set of all positive numeric keys is equal to <em>{1..n}</em> -for some integer <em>n</em>, -which is called the length of the sequence (see <a href="#3.4.6">§3.4.6</a>). - - -<p> -Like indices, -the values of table fields can be of any type. -In particular, -because functions are first-class values, -table fields can contain functions. -Thus tables can also carry <em>methods</em> (see <a href="#3.4.10">§3.4.10</a>). - - -<p> -The indexing of tables follows -the definition of raw equality in the language. -The expressions <code>a[i]</code> and <code>a[j]</code> -denote the same table element -if and only if <code>i</code> and <code>j</code> are raw equal -(that is, equal without metamethods). - - -<p> -Tables, functions, and userdata values 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 (see <a href="#6.1">§6.1</a>). - - - - - -<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> - -<p> -As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, -any reference to a global name <code>var</code> is syntactically translated -to <code>_ENV.var</code>. -Moreover, every chunk is compiled in the scope of -an external local variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), -so <code>_ENV</code> itself is never a global name in a chunk. - - -<p> -Despite the existence of this external <code>_ENV</code> variable and -the translation of global names, -<code>_ENV</code> is a completely regular name. -In particular, -you can define new variables and parameters with that name. -Each reference to a global name uses the <code>_ENV</code> that is -visible at that point in the program, -following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). - - -<p> -Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. - - -<p> -Lua keeps a distinguished environment called the <em>global environment</em>. -This value is kept in the Luan state implemented in Java. -In Luan, the variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. - - -<p> -When Lua compiles a chunk, -it initializes the value of its <code>_ENV</code> to an empty table. -The values in the global environment become local variables of the chunk. -All standard libraries are loaded in the global environment -and so they become available as local variables. -You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>load_file</code></a>) -to load a chunk with a specific environment instead of starting empty. - - -<p> -If you change the values in the global environment, -all chunks loaded after the change will get the new environment. -Previously loaded chunks are not affected, however, -as each has its own references to the values in its local variables. -Moreover, the variable <a href="#pdf-_G"><code>_G</code></a> -(which is stored in the original global environment) -is never updated by Lua. - - - - - -<h2>2.3 – <a name="2.3">Error Handling</a></h2> - -<p> -Luan error handling is quite different from Lua. - - -<p> -Luan code can explicitly generate an error by calling the -<a href="#pdf-error"><code>error</code></a> function. -Unlike Lua, Luan has <code>try-catch</code> blocks for catching errors. This means that there is no need for Lua's <code>pcall</code> and <code>xpcall</code> functions. - - -<p> -Whenever there is an error, -an <em>error object</em> (also called an <em>error message</em>) -is propagated with information about the error. -Lua itself only generates errors where the error object is a string, -but programs may generate errors with -any value for the error object. - - - - -<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> - -<p> -Every table in Luan can have a <em>metatable</em>. -This <em>metatable</em> is an ordinary Luan table -that defines the behavior of the original table -under certain special operations. -You can change several aspects of the behavior -of operations over a table by setting specific fields in its metatable. -For instance, when a table is the operand of an addition, -Luan checks for a function in the field "<code>__add</code>" of the table's metatable. -If it finds one, -Luan calls this function to perform the addition. - -<p> -Inside Luan's implementation, there is a global metatable that applies to all objects. This metatable is not exposed to Luan users but can be used to change the behavior of objects other than tables. - -<p> -The keys in a metatable are derived from the <em>event</em> names; -the corresponding values are called <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 -using the <a href="#pdf-getmetatable"><code>get_metatable</code></a> function. - - -<p> -You can replace the metatable of tables -using the <a href="#pdf-setmetatable"><code>set_metatable</code></a> function. - - -<p> -Tables have individual metatables -(although multiple tables can share their metatables). -By default, a table has no metatable. - - -<p> -A metatable controls how a table behaves in arithmetic operations, -order comparisons, concatenation, length operation, and indexing. -When Luan performs one of these operations over a table, -it checks whether this table has a metatable with the corresponding event. -If so, the value associated with that key (the metamethod) -controls how Luan 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>". - - -<p> -The semantics of these operations is better explained by a Luan function -describing how the interpreter executes the operation. -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>raw_get</code></a>, <a href="#pdf-tonumber"><code>to_number</code></a>, etc.) -are described in <a href="#6.1">§6.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> - raw_get(get_metatable(obj) or {}, event) -</pre><p> -This means that the access to a metamethod does not invoke other metamethods, -and access to tables with no metatables does not fail -(it simply results in <b>nil</b>). - -<p> - - -<ul> - -<li><b>"add": </b> -the <code>+</code> operation. - - - -<p> -The function <code>get_bin_handler</code> below defines how Luan chooses a handler -for a binary operation. -First, Luan tries the first operand. -If its type does not define a handler for the operation, -then Lua tries the second operand. - -<pre> - function get_bin_handler (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 = to_number(op1), to_number(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 = get_bin_handler(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>"span": </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 = to_number(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 = get_bin_handler(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 - else - local h = metatable(op).__len - if h then - return (h(op)) -- call handler with the operand - elseif type(op) == "table" then - return #op -- primitive table length - else -- no handler available: error - error(···) - end - end - end -</pre><p> -See <a href="#3.4.6">§3.4.6</a> for a description of the length of a table. -</li> - -<li><b>"eq": </b> -the <code>==</code> operation. - -The function <code>get_equal_handler</code> defines how Luan chooses a metamethod -for equality. -A metamethod is selected only when both values -being compared have the same type -and the same metamethod for the selected operation, -and the values are either tables or full userdata. - -<pre> - function get_equal_handler (op1, op2) - if type(op1) ~= type(op2) or - (type(op1) ~= "table" and type(op1) ~= "userdata") then - return nil -- different values - end - local mm1 = metatable(op1).__eq - local mm2 = metatable(op2).__eq - 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 op1 == op2 then -- primitive equal? - return true -- values are equal - end - -- try metamethod - local h = get_equal_handler(op1, op2) - if h then - return to_boolean(h(op1, op2)) - else - return false - end - end -</pre><p> -Note that the result is always a boolean. -</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 = get_bin_handler(op1, op2, "__lt") - if h then - return to_boolean(h(op1, op2)) - else - error(···) - end - end - end -</pre><p> -Note that the result is always a boolean. -</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 = get_bin_handler(op1, op2, "__le") - if h then - return to_boolean(h(op1, op2)) - else - h = get_bin_handler(op1, op2, "__lt") - if h then - return not to_boolean(h(op2, op1)) - else - error(···) - end - end - end - end -</pre><p> -Note that, in the absence of a "le" metamethod, -Luan tries the "lt", assuming that <code>a <= b</code> is -equivalent to <code>not (b < a)</code>. - - -<p> -As with the other comparison operators, -the result is always a boolean. -</li> - -<li><b>"index": </b> -The indexing access <code>table[key]</code>. -Note that the metamethod is tried only -when <code>key</code> is not present in <code>table</code>. -(When <code>table</code> is not a table, -no key is ever present, -so the metamethod is always tried.) - - -<pre> - function get_table_event (table, key) - local h - if type(table) == "table" then - local v = raw_get(table, key) - -- if key is present, return raw value - 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>. -Note that the metamethod is tried only -when <code>key</code> is not present in <code>table</code>. - - -<pre> - function set_table_event (table, key, value) - local h - if type(table) == "table" then - local v = raw_get(table, key) - -- if key is present, do raw assignment - if v ~= nil then raw_set(table, key, value); return end - h = metatable(table).__newindex - if h == nil then raw_set(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 Luan 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.5 – <a name="2.5">Garbage Collection</a></h2> - -<p> -Luan uses Java's garbage collection, so there is very little to say on this subject. So this section is just a place holder to replace the long explanation of Lua's garbage collection which isn't needed by Luan. - -<p> -Lua has <em>weak tables</em> which is a good concept but is not yet implemented in Luan. It will be added when there is a need. - - - -<h2>2.6 – <a name="2.6">Coroutines</a></h2> - -<p> -Unlike Lua, Luan does not support coroutines. Yes coroutines are cool, but they are not simple, so in the name of simplicity, Luan does without them. - - - - - -<h1>3 – <a name="3">The Language</a></h1> - -<p> -This section describes the lexis, the syntax, and the semantics of Luan. -In other words, -this section describes -which tokens are valid, -how they can be combined, -and what their combinations mean. - - -<p> -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 Luan can be found in <a href="#9">§9</a> -at the end of this manual. - - - -<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> - -<p> -Luan ignores spaces and comments -between lexical elements (tokens), -except as delimiters between names and keywords. - -But unlike Lua, Luan generally treats the newline character as a statement separator. This is how most languages work. If a newline is preceded by a backslash, then it is treated like a space. Also, inside of parenthesis (...), brackets [...], and braces {...}, a newline is treated like a space. This allows the Luan parser to catch mistakes more easily. - -<p> -In interactive mode, Luan allows an expression on a line which is then evaluated and printed. This means that entering <em>1+1</em> on an interactive line will produce <em>2</em>. - - -<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. -Identifiers are used to name variables, table fields, and labels. - - -<p> -The following <em>keywords</em> are reserved -and cannot be used as names: - - -<pre> - and break do else elseif end - false for function goto if in - local nil not or repeat return - then true until while -</pre> - -The following <em>keywords</em> are also reserved in Luan but not in Lua: - -<pre> - catch import try -</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 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]). -A backslash followed by a real newline -results in a newline in the string. -The escape sequence '<code>\z</code>' skips the following span -of white-space characters, -including line breaks; -it is particularly useful to break and indent a long literal string -into multiple lines without adding the newlines and spaces -into the string contents. - - -<p> -A byte in a literal string can also be specified by its numerical value. -This can be done with the escape sequence <code>\x<em>XX</em></code>, -where <em>XX</em> is a sequence of exactly two hexadecimal digits, -or with 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 decimal 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 <em>long literal</em> starts with an opening long bracket of any level and -ends at the first closing long bracket of the same level. -It can contain any text except a closing bracket of the proper 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. -Any kind of end-of-line sequence -(carriage return, newline, carriage return followed by newline, -or newline followed by carriage return) -is converted to a simple newline. - - - -<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 fractional part -and an optional decimal exponent, -marked by a letter '<code>e</code>' or '<code>E</code>'. -Lua also accepts hexadecimal constants, -which start with <code>0x</code> or <code>0X</code>. -Hexadecimal constants also accept an optional fractional part -plus an optional binary exponent, -marked by a letter '<code>p</code>' or '<code>P</code>'. -Examples of valid numerical constants are - -<pre> - 3 3.0 3.1416 314.16e-2 0.31416E1 - 0xff 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 -</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>3.2 – <a name="3.2">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="#3.1">§3.1</a>. - - -<p> -Any variable name is assumed to be global unless explicitly declared -as a local (see <a href="#3.3.7">§3.3.7</a>). -Local variables are <em>lexically scoped</em>: -local variables can be freely accessed by functions -defined inside their scope (see <a href="#3.5">§3.5</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 table fields can be changed via metatables. -An access to an indexed variable <code>t[i]</code> is equivalent to -a call <code>get_table_event(t,i)</code>. -(See <a href="#2.4">§2.4</a> for a complete description of the -<code>get_table_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> -An access to a global variable <code>x</code> -is equivalent to <code>_ENV.x</code>. -Due to the way that chunks are compiled, -<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). - - - - - -<h2>3.3 – <a name="3.3">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>3.3.1 – <a name="3.3.1">Blocks</a></h3> - -<p> -A block is a list of statements, -which are executed sequentially: - -<pre> - block ::= {stat} -</pre><p> -Lua has <em>empty statements</em> -that allow you to separate statements with semicolons, -start a block with a semicolon -or write two semicolons in sequence: - -<pre> - stat ::= ‘<b>;</b>’ -</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. - - - - - -<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> - -<p> -The unit of compilation of Lua is called a <em>chunk</em>. -Syntactically, -a chunk is simply a block: - -<pre> - chunk ::= block -</pre> - -<p> -Lua handles a chunk as the body of an anonymous function -with a variable number of arguments -(see <a href="#3.4.10">§3.4.10</a>). -As such, chunks can define local variables, -receive arguments, and return values. -Moreover, such anonymous function is compiled as in the -scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). -The resulting function always has <code>_ENV</code> as its only upvalue, -even if it does not use that variable. - - -<p> -A chunk can be stored in a file or in a string inside the host program. -To execute a chunk, -Lua first precompiles the chunk into instructions for a virtual machine, -and then it executes the compiled code -with an interpreter for the virtual machine. - - - - - - -<h3>3.3.3 – <a name="3.3.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="#3.4">§3.4</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="#3.4">§3.4</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.4">§2.4</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> (see <a href="#2.2">§2.2</a>). - - - - - -<h3>3.3.4 – <a name="3.3.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 (see <a href="#3.3.5">§3.3.5</a>). - - -<p> -The condition expression of a -control structure must return a boolean. -This is unlike Lua and is intended to catch programming errors more quickly. - - -<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>break</b> statement terminates 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> statement is used to return values -from a function or a chunk (which is a function in disguise). - -Functions can return more than one value, -so the syntax for the <b>return</b> statement is - -<pre> - stat ::= <b>return</b> [explist] [‘<b>;</b>’] -</pre> - - - - - -<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> - - -<p> -The <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 <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>expression</em> do <em>block</em> end -</pre><p> -is equivalent to the code: - -<pre> - do - local <em>f</em> = <em>expression</em> - while true do - local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>() - if <em>var_1</em> == nil then break end - <em>block</em> - end - end -</pre><p> -Note the following: - -<ul> - -<li> -<code><em>expression</em></code> is evaluated only once. -Its result is an <em>iterator</em> function. -</li> - -<li> -<code><em>f</em></code> is an invisible variable. -The name is 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> - -<p> -Lua also has a numeric <b>for</b> statement which Luan does not support. Instead, Luan offers the <em>range</em> function (inspired by Python) which does the same thing without adding to the syntax of the language. - - -<h3>3.3.6 – <a name="3.3.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="#3.4.9">§3.4.9</a>. - - - - - -<h3>3.3.7 – <a name="3.3.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="#3.3.3">§3.3.3</a>). -Otherwise, all variables are initialized with <b>nil</b>. - -<p> -A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), -and so local variables can be declared in a chunk outside any explicit block. - - -<p> -The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. - - - -<h3>3.3.8 – <a name="3.3.8">Or/And Statements</a></h3><p> - -<p> -An <b>or</b> or <b>and</b> expression is also considered a statement. This is new for Luan and doesn't exist in Lua. - -<p>For example, consider a function <em>do_something</em> that returns a boolean indicating whether it succeeded or failed. You can then do: - -<pre> - do_something() or error "didn't work" -</pre> - - - - - - -<h2>3.4 – <a name="3.4">Expressions</a></h2> - -<p> -The basic expressions in Luan are the following: - -<pre> - exp ::= prefixexp - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> - exp ::= Number - exp ::= String - exp ::= functiondef - 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="#3.1">§3.1</a>; -variables are explained in <a href="#3.2">§3.2</a>; -function definitions are explained in <a href="#3.4.10">§3.4.10</a>; -function calls are explained in <a href="#3.4.9">§3.4.9</a>; -table constructors are explained in <a href="#3.4.8">§3.4.8</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="#3.4.10">§3.4.10</a>. - - -<p> -Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), -relational operators (see <a href="#3.4.3">§3.4.3</a>), logical operators (see <a href="#3.4.4">§3.4.4</a>), -and the concatenation operator (see <a href="#3.4.5">§3.4.5</a>). -Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), -the unary <b>not</b> (see <a href="#3.4.4">§3.4.4</a>), -and the unary <em>length operator</em> (see <a href="#3.4.6">§3.4.6</a>). - - -<p> -Both function calls and vararg expressions can result in multiple values. -If a function call is used as a statement (see <a href="#3.3.6">§3.3.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 expression is enclosed in parentheses). -In all other contexts, -Lua adjusts the result list to one element, -either discarding all values except the first one -or adding a single <b>nil</b> if there are no values. - - -<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>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> -Luan 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> (mathematical negation). -If the operands are numbers, or strings that can be converted to -numbers (see <a href="#3.4.2">§3.4.2</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>3.4.2 – <a name="3.4.2">Coercion</a></h3> - -<p> -Luan 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 rules of the Lua lexer. -(The string may have leading and trailing spaces and a sign.) -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>). - - - - - -<h3>3.4.3 – <a name="3.4.3">Relational Operators</a></h3><p> -The relational operators in Luan 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. -Tables, userdata, and threads -are compared by reference: -two objects are considered equal only if they are the same object. -Every time you create a new object -(a table, userdata, or thread), -this new object is different from any previously existing object. -Closures with the same reference are always equal. -Closures with any detectable difference -(different behavior, different definition) are always different. - - -<p> -You can change the way that Luan compares tables -by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). - - -<p> -The conversion rules of <a href="#3.4.2">§3.4.2</a> -do not 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.4">§2.4</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>3.4.4 – <a name="3.4.4">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="#3.3.4">§3.3.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>3.4.5 – <a name="3.4.5">Concatenation</a></h3><p> -The string concatenation operator in Luan 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="#3.4.2">§3.4.2</a>. -Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). - - - - - -<h3>3.4.6 – <a name="3.4.6">The Length Operator</a></h3> - -<p> -The length operator is denoted by the unary prefix operator <code>#</code>. -The length of a string is its number of bytes -(that is, the usual meaning of string length when each -character is one byte). - - -<p> -A program can modify the behavior of the length operator for -any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). - - -<p> -Unless a <code>__len</code> metamethod is given, -the length of a table <code>t</code> is only defined if the -table is a <em>sequence</em>, -that is, -the set of its positive numeric keys is equal to <em>{1..n}</em> -for some integer <em>n</em>. -In that case, <em>n</em> is its length. -Note that a table like - -<pre> - {10, 20, nil, 40} -</pre><p> -is not a sequence, because it has the key <code>4</code> -but does not have the key <code>3</code>. -(So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal -to the set of positive numeric keys of that table.) -Note, however, that non-numeric keys do not interfere -with whether a table is a sequence. - - - - - -<h3>3.4.7 – <a name="3.4.7">Precedence</a></h3><p> -Operator precedence in Luan 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>3.4.8 – <a name="3.4.8">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="#3.4.9">§3.4.9</a>). - - -<p> -The field list can have an optional trailing separator, -as a convenience for machine-generated code. - - - - - -<h3>3.4.9 – <a name="3.4.9">Function Calls</a></h3><p> -A function call in Luan 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.4">§2.4</a>). - - -<p> -Lua supports a special function call for "methods" like <em>obj:fn(args)</em> . Luan does not support this. - -<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> -A call of the form <code>return <em>functioncall</em></code> is called -a <em>tail call</em>. -Luan 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>3.4.10 – <a name="3.4.10">Function Definitions</a></h3> - -<p> -The syntax for function definition is - -<pre> - functiondef ::= <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} -</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> -not 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 Luan precompiles a chunk, -all its function bodies are precompiled too. -Then, whenever Luan 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. - - -<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 <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="#3.3.4">§3.3.4</a>). -If control reaches the end of a function -without encountering a <b>return</b> statement, -then the function returns with no results. - - - - -<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> - -<p> - -Luan is a lexically scoped language. -The scope of a local variable begins at the first statement after -its declaration and lasts until the last non-void statement -of the innermost block that includes the declaration. -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>. - - - - - -<h1>4 – <a name="4">The Application Program Interface</a></h1> - -<p> -In the Lua documentation, -this section described the C API for Lua. -Obviously this is not relevant for Luan. -The implementation of Luan is radically different from Lua and will be documented eventually in Javadoc. -So this section is just a placeholder so that Luan documentation can match Lua's documentation. - - - - -<h1>5 – <a name="5">The Auxiliary Library</a></h1> - -<p> -Like the previous section, this section is specific to Lua and is not relevant to Luan. -So this section is just a placeholder. - - - - - -<h1>6 – <a name="6">Standard Libraries</a></h1> - -<p> -The standard Lua libraries provide useful functions -that are implemented directly through the C API. -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> -All libraries are implemented through the official C API -and are provided as separate C modules. -Currently, Lua has the following standard libraries: - -<ul> - -<li>basic library (<a href="#6.1">§6.1</a>);</li> - -<li>coroutine library (<a href="#6.2">§6.2</a>);</li> - -<li>package library (<a href="#6.3">§6.3</a>);</li> - -<li>string manipulation (<a href="#6.4">§6.4</a>);</li> - -<li>table manipulation (<a href="#6.5">§6.5</a>);</li> - -<li>mathematical functions (<a href="#6.6">§6.6</a>) (sin, log, etc.);</li> - -<li>bitwise operations (<a href="#6.7">§6.7</a>);</li> - -<li>input and output (<a href="#6.8">§6.8</a>);</li> - -<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> - -<li>debug facilities (<a href="#6.10">§6.10</a>).</li> - -</ul><p> -Except for the basic and the package libraries, -each library provides all its functions as fields of a global table -or as methods of its objects. - - -<p> -To have access to these libraries, -the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, -which opens all standard libraries. -Alternatively, -the host program can open them individually by using -<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call -<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), -<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), -<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), -<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), -<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), -<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), -<a name="pdf-luaopen_bit32"><code>luaopen_bit32</code></a> (for the bit library), -<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), -<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), -and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). -These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. - - - -<h2>6.1 – <a name="6.1">Basic Functions</a></h2> - -<p> -The basic library provides 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-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>"<code>collect</code>": </b> -performs a full garbage-collection cycle. -This is the default option. -</li> - -<li><b>"<code>stop</code>": </b> -stops automatic execution of the garbage collector. -The collector will run only when explicitly invoked, -until a call to restart it. -</li> - -<li><b>"<code>restart</code>": </b> -restarts automatic execution of the garbage collector. -</li> - -<li><b>"<code>count</code>": </b> -returns the total memory in use by Lua (in Kbytes) and -a second value with the total memory in bytes modulo 1024. -The first value has a fractional part, -so the following equality is always true: - -<pre> - k, b = collectgarbage("count") - assert(k*1024 == math.floor(k)*1024 + b) -</pre><p> -(The second result is useful when Lua is compiled -with a non floating-point type for numbers.) -</li> - -<li><b>"<code>step</code>": </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>"<code>setpause</code>": </b> -sets <code>arg</code> as the new value for the <em>pause</em> of -the collector (see <a href="#2.5">§2.5</a>). -Returns the previous value for <em>pause</em>. -</li> - -<li><b>"<code>setstepmul</code>": </b> -sets <code>arg</code> as the new value for the <em>step multiplier</em> of -the collector (see <a href="#2.5">§2.5</a>). -Returns the previous value for <em>step</em>. -</li> - -<li><b>"<code>isrunning</code>": </b> -returns a boolean that tells whether the collector is running -(i.e., not stopped). -</li> - -<li><b>"<code>generational</code>": </b> -changes the collector to generational mode. -This is an experimental feature (see <a href="#2.5">§2.5</a>). -</li> - -<li><b>"<code>incremental</code>": </b> -changes the collector to incremental mode. -This is the default mode. -</li> - -</ul> - - - -<p> -<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> -Opens the named file and executes its contents as a Lua chunk. -When called without arguments, -<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). -Returns all values returned by the chunk. -In case of errors, <code>dofile</code> propagates the error -to its caller (that is, <code>dofile</code> does not run in protected mode). - - - - -<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, if the message is a string. -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 (not a function) that -holds the global environment (see <a href="#2.2">§2.2</a>). -Lua itself does not use this variable; -changing its value does not affect any environment, -nor vice-versa. - - - - -<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> -If <code>t</code> has a metamethod <code>__ipairs</code>, -calls it with <code>t</code> as argument and returns the first three -results from the call. - - -<p> -Otherwise, -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-load"><code>load (ld [, source [, mode [, env]]])</code></a></h3> - - -<p> -Loads a chunk. - - -<p> -If <code>ld</code> is a string, the chunk is this string. -If <code>ld</code> is a function, -<code>load</code> calls it repeatedly to get the chunk pieces. -Each call to <code>ld</code> must return a string that concatenates -with previous results. -A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. - - -<p> -If there are no syntactic errors, -returns the compiled chunk as a function; -otherwise, returns <b>nil</b> plus the error message. - - -<p> -If the resulting function has upvalues, -the first upvalue is set to the value of <code>env</code>, -if that parameter is given, -or to the value of the global environment. -(When you load a main chunk, -the resulting function will always have exactly one upvalue, -the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). -When you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), -the resulting function can have arbitrary upvalues.) - - -<p> -<code>source</code> is used as the source of the chunk for error messages -and debug information (see <a href="#4.9">§4.9</a>). -When absent, -it defaults to <code>ld</code>, if <code>ld</code> is a string, -or to "<code>=(load)</code>" otherwise. - - -<p> -The string <code>mode</code> controls whether the chunk can be text or binary -(that is, a precompiled chunk). -It may be the string "<code>b</code>" (only binary chunks), -"<code>t</code>" (only text chunks), -or "<code>bt</code>" (both binary and text). -The default is "<code>bt</code>". - - - - -<p> -<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> - - -<p> -Similar to <a href="#pdf-load"><code>load</code></a>, -but gets the chunk from file <code>filename</code> -or from the standard input, -if no file name is given. - - - - -<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>.) - - -<p> -The behavior of <code>next</code> is undefined 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> -If <code>t</code> has a metamethod <code>__pairs</code>, -calls it with <code>t</code> as argument and returns the first three -results from the call. - - -<p> -Otherwise, -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-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> - - -<p> -Calls function <code>f</code> with -the given arguments in <em>protected mode</em>. -This means that any error inside <code>f</code> is not propagated; -instead, <code>pcall</code> catches the error -and returns a status code. -Its first result is the status code (a boolean), -which is true if the call succeeds without errors. -In such case, <code>pcall</code> also returns all results from the call, -after this first result. -In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. - - - - -<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 each argument to a string. -<code>print</code> is not intended for formatted output, -but only as a quick way to show a value, -for instance for debugging. -For complete control over the output, -use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</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-rawlen"><code>rawlen (v)</code></a></h3> -Returns the length of the object <code>v</code>, -which must be a table or a string, -without invoking any metamethod. -Returns an integer number. - - - - -<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 NaN, -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>; -a negative number indexes from the end (-1 is the last argument). -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-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> - - -<p> -Sets the metatable for the given table. -(You cannot change the metatable of other types from Lua, only from C.) -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> - - -<p> -When called with no <code>base</code>, -<code>tonumber</code> tries to convert its argument to a number. -If the argument is already a number or -a string convertible to a number (see <a href="#3.4.2">§3.4.2</a>), -then <code>tonumber</code> returns this number; -otherwise, it returns <b>nil</b>. - - -<p> -When called with <code>base</code>, -then <code>e</code> should be a string to be interpreted as -an integer numeral in that base. -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. -If the string <code>e</code> is not a valid numeral in the given base, -the function returns <b>nil</b>. - - - - -<p> -<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> -Receives a value 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>v</code> has a <code>"__tostring"</code> field, -then <code>tostring</code> calls the corresponding value -with <code>v</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-_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.2</code>". - - - - -<p> -<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> - - -<p> -This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, -except that it sets a new message handler <code>msgh</code>. - - - - - - - -<h2>6.2 – <a name="6.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.6">§2.6</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 plus a boolean, -true when the running coroutine is the main one. - - - - -<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. -Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. - - - - - - - -<h2>6.3 – <a name="6.3">Modules</a></h2> - -<p> -The package library provides basic -facilities for loading modules in Lua. -It exports one function directly in the global environment: -<a href="#pdf-require"><code>require</code></a>. -Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. - - -<p> -<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> - - -<p> -Loads the given module. -The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table -to determine whether <code>modname</code> is already loaded. -If it is, then <code>require</code> returns the value stored -at <code>package.loaded[modname]</code>. -Otherwise, it tries to find a <em>loader</em> for the module. - - -<p> -To find a loader, -<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. -By changing this sequence, -we can change how <code>require</code> looks for a module. -The following explanation is based on the default configuration -for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. - - -<p> -First <code>require</code> queries <code>package.preload[modname]</code>. -If it has a value, -this value (which should be a function) is the loader. -Otherwise <code>require</code> searches for a Lua loader using the -path stored in <a href="#pdf-package.path"><code>package.path</code></a>. -If that also fails, it searches for a C loader using the -path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -If that also fails, -it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). - - -<p> -Once a loader is found, -<code>require</code> calls the loader with two arguments: -<code>modname</code> and an extra value dependent on how it got the loader. -(If the loader came from a file, -this extra value is the file name.) -If the loader returns any non-nil value, -<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. -If the loader does not return a non-nil value and -has not assigned any value to <code>package.loaded[modname]</code>, -then <code>require</code> assigns <b>true</b> to this entry. -In any case, <code>require</code> returns the -final value of <code>package.loaded[modname]</code>. - - -<p> -If there is any error loading or running the module, -or if it cannot find any loader for the module, -then <code>require</code> raises an error. - - - - -<p> -<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> - - -<p> -A string describing some compile-time configurations for packages. -This string is a sequence of lines: - -<ul> - -<li>The first line is the directory separator string. -Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> - -<li>The second line is the character that separates templates in a path. -Default is '<code>;</code>'.</li> - -<li>The third line is the string that marks the -substitution points in a template. -Default is '<code>?</code>'.</li> - -<li>The fourth line is a string that, in a path in Windows, -is replaced by the executable's directory. -Default is '<code>!</code>'.</li> - -<li>The fifth line is a mark to ignore all text before it -when building the <code>luaopen_</code> function name. -Default is '<code>-</code>'.</li> - -</ul> - - - -<p> -<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> - - -<p> -The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. - - -<p> -Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way -it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, -using the environment variable <a name="pdf-LUA_CPATH_5_2"><code>LUA_CPATH_5_2</code></a> -or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> -or a default path defined in <code>luaconf.h</code>. - - - - -<p> -<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control which -modules are already loaded. -When you require a module <code>modname</code> and -<code>package.loaded[modname]</code> is not false, -<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. - - -<p> -This variable is only a reference to the real table; -assignments to this variable do not change the -table used by <a href="#pdf-require"><code>require</code></a>. - - - - -<p> -<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> - - -<p> -Dynamically links the host program with the C library <code>libname</code>. - - -<p> -If <code>funcname</code> is "<code>*</code>", -then it only links with the library, -making the symbols exported by the library -available to other dynamically linked libraries. -Otherwise, -it looks for a function <code>funcname</code> inside the library -and returns this function as a C function. -So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype -(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). - - -<p> -This is a low-level function. -It completely bypasses the package and module system. -Unlike <a href="#pdf-require"><code>require</code></a>, -it does not perform any path searching and -does not automatically adds extensions. -<code>libname</code> must be the complete file name of the C library, -including if necessary a path and an extension. -<code>funcname</code> must be the exact name exported by the C library -(which may depend on the C compiler and linker used). - - -<p> -This function is not supported by Standard C. -As such, it is only available on some platforms -(Windows, Linux, Mac OS X, Solaris, BSD, -plus other Unix systems that support the <code>dlfcn</code> standard). - - - - -<p> -<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> - - -<p> -The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. - - -<p> -At start-up, Lua initializes this variable with -the value of the environment variable <a name="pdf-LUA_PATH_5_2"><code>LUA_PATH_5_2</code></a> or -the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or -with a default path defined in <code>luaconf.h</code>, -if those environment variables are not defined. -Any "<code>;;</code>" in the value of the environment variable -is replaced by the default path. - - - - -<p> -<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> - - -<p> -A table to store loaders for specific modules -(see <a href="#pdf-require"><code>require</code></a>). - - -<p> -This variable is only a reference to the real table; -assignments to this variable do not change the -table used by <a href="#pdf-require"><code>require</code></a>. - - - - -<p> -<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. - - -<p> -Each entry in this table is a <em>searcher function</em>. -When looking for a module, -<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, -with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its -sole parameter. -The function can return another function (the module <em>loader</em>) -plus an extra value that will be passed to that loader, -or a string explaining why it did not find that module -(or <b>nil</b> if it has nothing to say). - - -<p> -Lua initializes this table with four searcher functions. - - -<p> -The first searcher simply looks for a loader in the -<a href="#pdf-package.preload"><code>package.preload</code></a> table. - - -<p> -The second searcher looks for a loader as a Lua library, -using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. -The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. - - -<p> -The third searcher looks for a loader as a C library, -using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -Again, -the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. -For instance, -if the C path is the string - -<pre> - "./?.so;./?.dll;/usr/local/?/init.so" -</pre><p> -the searcher for module <code>foo</code> -will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, -and <code>/usr/local/foo/init.so</code>, in that order. -Once it finds a C library, -this searcher first uses a dynamic link facility to link the -application with the library. -Then it tries to find a C function inside the library to -be used as the loader. -The name of this C function is the string "<code>luaopen_</code>" -concatenated with a copy of the module name where each dot -is replaced by an underscore. -Moreover, if the module name has a hyphen, -its prefix up to (and including) the first hyphen is removed. -For instance, if the module name is <code>a.v1-b.c</code>, -the function name will be <code>luaopen_b_c</code>. - - -<p> -The fourth searcher tries an <em>all-in-one loader</em>. -It searches the C path for a library for -the root name of the given module. -For instance, when requiring <code>a.b.c</code>, -it will search for a C library for <code>a</code>. -If found, it looks into it for an open function for -the submodule; -in our example, that would be <code>luaopen_a_b_c</code>. -With this facility, a package can pack several C submodules -into one single library, -with each submodule keeping its original open function. - - -<p> -All searchers except the first one (preload) return as the extra value -the file name where the module was found, -as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. -The first searcher returns no extra value. - - - - -<p> -<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> - - -<p> -Searches for the given <code>name</code> in the given <code>path</code>. - - -<p> -A path is a string containing a sequence of -<em>templates</em> separated by semicolons. -For each template, -the function replaces each interrogation mark (if any) -in the template with a copy of <code>name</code> -wherein all occurrences of <code>sep</code> -(a dot, by default) -were replaced by <code>rep</code> -(the system's directory separator, by default), -and then tries to open the resulting file name. - - -<p> -For instance, if the path is the string - -<pre> - "./?.lua;./?.lc;/usr/local/?/init.lua" -</pre><p> -the search for the name <code>foo.a</code> -will try to open the files -<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and -<code>/usr/local/foo/a/init.lua</code>, in that order. - - -<p> -Returns the resulting name of the first file that it can -open in read mode (after closing the file), -or <b>nil</b> plus an error message if none succeeds. -(This error message lists all file names it tried to open.) - - - - - - - -<h2>6.4 – <a name="6.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>. -These indices are corrected -following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. - - -<p> -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> -Numerical codes are not necessarily portable across platforms. - - - - -<p> -<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> - - -<p> -Returns a string containing a binary representation of the given function, -so that a later <a href="#pdf-load"><code>load</code></a> on this string returns -a copy of the function (but with new upvalues). - - - - -<p> -<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> - - -<p> -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> - - -<p> -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 ANSI C function <code>sprintf</code>. -The only differences are that the options/modifiers -<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, -and <code>p</code> are not supported -and that there is an extra option, <code>q</code>. -The <code>q</code> option formats a string between double quotes, -using escape sequences when necessary to ensure that -it can safely be read back by the Lua interpreter. -For instance, the call - -<pre> - string.format('%q', 'a string with "quotes" and \n new line') -</pre><p> -may produce the string: - -<pre> - "a string with \"quotes\" and \ - new line" -</pre> - -<p> -Options -<code>A</code> and <code>a</code> (when available), -<code>E</code>, <code>e</code>, <code>f</code>, -<code>G</code>, and <code>g</code> all expect a number as argument. -Options <code>c</code>, <code>d</code>, -<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> -also expect a number, -but the range of that number may be limited by -the underlying C implementation. -For options <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>, -the number cannot be negative. -Option <code>q</code> expects a string; -option <code>s</code> expects a string without embedded zeros. -If the argument to option <code>s</code> is not a string, -it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. - - - - -<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 the 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 -will iterate over all the words from string <code>s</code>, -printing one per line: - -<pre> - s = "hello world from Lua" - for w in string.gmatch(s, "%a+") do - print(w) - end -</pre><p> -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 caret '<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. -The name <code>gsub</code> comes from <em>Global SUBstitution</em>. - - -<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>d</em></code>, -with <em>d</em> between 1 and 9, -stands for the value of the <em>d</em>-th captured substring. -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. - - -<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. - - -<p> -In any case, -if the pattern specifies no captures, -then it behaves as if the whole pattern was inside a capture. - - -<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" - - x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) - return load(s)() - end) - --> x="4+5 = 9" - - local t = {name="lua", version="5.2"} - x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) - --> x="lua-5.2.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 [, sep])</code></a></h3> -Returns a string that is the concatenation of <code>n</code> copies of -the string <code>s</code> separated by the string <code>sep</code>. -The default value for <code>sep</code> is the empty string -(that is, no separator). - - - - -<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> -If, after the translation of negative indices, -<code>i</code> is less than 1, -it is corrected to 1. -If <code>j</code> is greater than the string length, -it is corrected to that length. -If, after these corrections, -<code>i</code> is greater than <code>j</code>, -the function returns the empty string. - - - - -<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>6.4.1 – <a name="6.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>%g</code>: </b> represents all printable characters except space.</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>%<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, -in ascending order, 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 shortest 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> - -<li> -<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; -such item matches an empty string at any position such that -the next character belongs to <em>set</em> -and the previous character does not belong to <em>set</em>. -The set <em>set</em> is interpreted as previously described. -The beginning and the end of the subject are handled as if -they were the character '<code>\0</code>'. -</li> - -</ul> - - - - -<h4>Pattern:</h4><p> -A <em>pattern</em> is a sequence of pattern items. -A caret '<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. - - - - - - - - - - - -<h2>6.5 – <a name="6.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> -Remember that, whenever an operation needs the length of a table, -the table should be a proper sequence -or have a <code>__len</code> metamethod (see <a href="#3.4.6">§3.4.6</a>). -All functions ignore non-numeric keys -in tables given as arguments. - - -<p> -For performance reasons, -all table accesses (get/set) performed by these functions are raw. - - -<p> -<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> - - -<p> -Given a list where all elements are strings or numbers, -returns the string <code>list[i]..sep..list[i+1] ··· sep..list[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 <code>#list</code>. -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 (list, [pos,] value)</code></a></h3> - - -<p> -Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, -shifting up the elements -<code>list[pos], list[pos+1], ···, list[#list]</code>. -The default value for <code>pos</code> is <code>#list+1</code>, -so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end -of list <code>t</code>. - - - - -<p> -<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> - - -<p> -Returns a new table with all parameters stored into keys 1, 2, etc. -and with a field "<code>n</code>" with the total number of parameters. -Note that the resulting table may not be a sequence. - - - - -<p> -<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> - - -<p> -Removes from <code>list</code> the element at position <code>pos</code>, -returning the value of the removed element. -When <code>pos</code> is an integer between 1 and <code>#list</code>, -it shifts down the elements -<code>list[pos+1], list[pos+2], ···, list[#list]</code> -and erases element <code>list[#list]</code>; -The index <code>pos</code> can also be 0 when <code>#list</code> is 0, -or <code>#list + 1</code>; -in those cases, the function erases the element <code>list[pos]</code>. - - -<p> -The default value for <code>pos</code> is <code>#list</code>, -so that a call <code>table.remove(t)</code> removes the last element -of list <code>t</code>. - - - - -<p> -<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> - - -<p> -Sorts list elements in a given order, <em>in-place</em>, -from <code>list[1]</code> to <code>list[#list]</code>. -If <code>comp</code> is given, -then it must be a function that receives two list elements -and returns true when the first element must come -before the second in the final order -(so that <code>not comp(list[i+1],list[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. - - - - -<p> -<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> - - -<p> -Returns the elements from the given table. -This function is equivalent to - -<pre> - return list[i], list[i+1], ···, list[j] -</pre><p> -By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. - - - - - - - -<h2>6.6 – <a name="6.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 [, base])</code></a></h3> - - -<p> -Returns the logarithm of <code>x</code> in the given base. -The default for <code>base</code> is <em>e</em> -(so that the function returns the natural 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>π</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 Standard 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>6.7 – <a name="6.7">Bitwise Operations</a></h2> - -<p> -This library provides bitwise operations. -It provides all its functions inside the table <a name="pdf-bit32"><code>bit32</code></a>. - - -<p> -Unless otherwise stated, -all functions accept numeric arguments in the range -<em>(-2<sup>51</sup>,+2<sup>51</sup>)</em>; -each argument is normalized to -the remainder of its division by <em>2<sup>32</sup></em> -and truncated to an integer (in some unspecified way), -so that its final value falls in the range <em>[0,2<sup>32</sup> - 1]</em>. -Similarly, all results are in the range <em>[0,2<sup>32</sup> - 1]</em>. -Note that <code>bit32.bnot(0)</code> is <code>0xFFFFFFFF</code>, -which is different from <code>-1</code>. - - -<p> -<hr><h3><a name="pdf-bit32.arshift"><code>bit32.arshift (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the left. - - -<p> -This shift operation is what is called arithmetic shift. -Vacant bits on the left are filled -with copies of the higher bit of <code>x</code>; -vacant bits on the right are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero or <code>0xFFFFFFFF</code> (all original bits are shifted out). - - - - -<p> -<hr><h3><a name="pdf-bit32.band"><code>bit32.band (···)</code></a></h3> - - -<p> -Returns the bitwise <em>and</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.bnot"><code>bit32.bnot (x)</code></a></h3> - - -<p> -Returns the bitwise negation of <code>x</code>. -For any integer <code>x</code>, -the following identity holds: - -<pre> - assert(bit32.bnot(x) == (-1 - x) % 2^32) -</pre> - - - -<p> -<hr><h3><a name="pdf-bit32.bor"><code>bit32.bor (···)</code></a></h3> - - -<p> -Returns the bitwise <em>or</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.btest"><code>bit32.btest (···)</code></a></h3> - - -<p> -Returns a boolean signaling -whether the bitwise <em>and</em> of its operands is different from zero. - - - - -<p> -<hr><h3><a name="pdf-bit32.bxor"><code>bit32.bxor (···)</code></a></h3> - - -<p> -Returns the bitwise <em>exclusive or</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.extract"><code>bit32.extract (n, field [, width])</code></a></h3> - - -<p> -Returns the unsigned number formed by the bits -<code>field</code> to <code>field + width - 1</code> from <code>n</code>. -Bits are numbered from 0 (least significant) to 31 (most significant). -All accessed bits must be in the range <em>[0, 31]</em>. - - -<p> -The default for <code>width</code> is 1. - - - - -<p> -<hr><h3><a name="pdf-bit32.replace"><code>bit32.replace (n, v, field [, width])</code></a></h3> - - -<p> -Returns a copy of <code>n</code> with -the bits <code>field</code> to <code>field + width - 1</code> -replaced by the value <code>v</code>. -See <a href="#pdf-bit32.extract"><code>bit32.extract</code></a> for details about <code>field</code> and <code>width</code>. - - - - -<p> -<hr><h3><a name="pdf-bit32.lrotate"><code>bit32.lrotate (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> rotated <code>disp</code> bits to the left. -The number <code>disp</code> may be any representable integer. - - -<p> -For any valid displacement, -the following identity holds: - -<pre> - assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32)) -</pre><p> -In particular, -negative displacements rotate to the right. - - - - -<p> -<hr><h3><a name="pdf-bit32.lshift"><code>bit32.lshift (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the left. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the right. -In any direction, vacant bits are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero (all bits are shifted out). - - -<p> -For positive displacements, -the following equality holds: - -<pre> - assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32) -</pre> - - - -<p> -<hr><h3><a name="pdf-bit32.rrotate"><code>bit32.rrotate (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> rotated <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. - - -<p> -For any valid displacement, -the following identity holds: - -<pre> - assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32)) -</pre><p> -In particular, -negative displacements rotate to the left. - - - - -<p> -<hr><h3><a name="pdf-bit32.rshift"><code>bit32.rshift (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the left. -In any direction, vacant bits are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero (all bits are shifted out). - - -<p> -For positive displacements, -the following equality holds: - -<pre> - assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp)) -</pre> - -<p> -This shift operation is what is called logical shift. - - - - - - - -<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> - -<p> -The I/O library provides two different styles for file manipulation. -The first one uses implicit file descriptors; -that is, there are operations to set a default input file and a -default output file, -and all input/output operations are over these default files. -The second style uses explicit file descriptors. - - -<p> -When using implicit file descriptors, -all operations are supplied by table <a name="pdf-io"><code>io</code></a>. -When using explicit file descriptors, -the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor -and then all operations are supplied as methods of the file descriptor. - - -<p> -The table <code>io</code> also provides -three predefined file descriptors with their usual meanings from C: -<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. -The I/O library never closes these files. - - -<p> -Unless otherwise stated, -all 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. -On non-Posix systems, -the computation of the error message and error code -in case of errors -may be not thread safe, -because they rely on the global C variable <code>errno</code>. - - -<p> -<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> - - -<p> -Equivalent to <code>file:close()</code>. -Without a <code>file</code>, closes the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> - - -<p> -Equivalent to <code>io.output():flush()</code>. - - - - -<p> -<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> - - -<p> -When called with a file name, it opens the named file (in text mode), -and sets its handle as the default input file. -When called with a file handle, -it simply sets this file handle as the default input file. -When called without parameters, -it returns the current default input file. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<p> -<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3> - - -<p> -Opens the given file name in read mode -and returns an iterator function that -works like <code>file:lines(···)</code> over the opened file. -When the iterator function detects the end of file, -it returns <b>nil</b> (to finish the loop) and automatically closes the file. - - -<p> -The call <code>io.lines()</code> (with no file name) is equivalent -to <code>io.input():lines()</code>; -that is, it iterates over the lines of the default input file. -In this case it does not close the file when the loop ends. - - -<p> -In case of errors this function raises the error, -instead of returning an error 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>"<code>r</code>": </b> read mode (the default);</li> -<li><b>"<code>w</code>": </b> write mode;</li> -<li><b>"<code>a</code>": </b> append mode;</li> -<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> -<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> -<li><b>"<code>a+</code>": </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. - - - - -<p> -<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> - - -<p> -Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> - - -<p> -This function is system dependent and is not available -on all platforms. - - -<p> -Starts program <code>prog</code> in a separated process and returns -a file handle that you can use to read data from this program -(if <code>mode</code> is <code>"r"</code>, the default) -or to write data to this program -(if <code>mode</code> is <code>"w"</code>). - - - - -<p> -<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> - - -<p> -Equivalent to <code>io.input():read(···)</code>. - - - - -<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-io.write"><code>io.write (···)</code></a></h3> - - -<p> -Equivalent to <code>io.output():write(···)</code>. - - - - -<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> -When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, -<a href="#pdf-file:close"><code>file:close</code></a> returns the same values -returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. - - - - -<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, -reads the file according to the given formats. -When no format is given, -uses "*l" as a default. -As an example, the construction - -<pre> - for c in file:lines(1) do <em>body</em> end -</pre><p> -will iterate over all characters of the file, -starting at the current position. -Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file -when the loop ends. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<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 next line -(see below). - - -<p> -The available formats are - -<ul> - -<li><b>"<code>*n</code>": </b> -reads a number; -this is the only format that returns a number instead of a string. -</li> - -<li><b>"<code>*a</code>": </b> -reads the whole file, starting at the current position. -On end of file, it returns the empty string. -</li> - -<li><b>"<code>*l</code>": </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>"<code>*L</code>": </b> -reads the next line keeping the end of line (if present), -returning <b>nil</b> on end of file. -</li> - -<li><b><em>number</em>: </b> -reads a string with up to this number of bytes, -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>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> -<li><b>"<code>cur</code>": </b> base is current position;</li> -<li><b>"<code>end</code>": </b> base is end of file;</li> -</ul><p> -In case of success, <code>seek</code> returns the final file position, -measured in bytes from the beginning of the file. -If <code>seek</code> 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>"<code>no</code>": </b> -no buffering; the result of any output operation appears immediately. -</li> - -<li><b>"<code>full</code>": </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>"<code>line</code>": </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 <code>file</code>. -The arguments must be strings or numbers. - - -<p> -In case of success, this function returns <code>file</code>. -Otherwise it returns <b>nil</b> plus a string describing the error. - - - - - - - -<h2>6.9 – <a name="6.9">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). -This last field may be absent -if the information is not available. - - -<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 ANSI 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> -On non-Posix systems, -this function may be not thread safe -because of its reliance on C function <code>gmtime</code> and C function <code>localtime</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.execute"><code>os.execute ([command])</code></a></h3> - - -<p> -This function is equivalent to the ANSI C function <code>system</code>. -It passes <code>command</code> to be executed by an operating system shell. -Its first result is <b>true</b> -if the command terminated successfully, -or <b>nil</b> otherwise. -After this first result -the function returns a string and a number, -as follows: - -<ul> - -<li><b>"<code>exit</code>": </b> -the command terminated normally; -the following number is the exit status of the command. -</li> - -<li><b>"<code>signal</code>": </b> -the command was terminated by a signal; -the following number is the signal that terminated the command. -</li> - -</ul> - -<p> -When called without a <code>command</code>, -<code>os.execute</code> returns a boolean that is true if a shell is available. - - - - -<p> -<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close])</code></a></h3> - - -<p> -Calls the ANSI C function <code>exit</code> to terminate the host program. -If <code>code</code> is <b>true</b>, -the returned status is <code>EXIT_SUCCESS</code>; -if <code>code</code> is <b>false</b>, -the returned status is <code>EXIT_FAILURE</code>; -if <code>code</code> is a number, -the returned status is this number. -The default value for <code>code</code> is <b>true</b>. - - -<p> -If the optional second argument <code>close</code> is true, -closes the Lua state before exiting. - - - - -<p> -<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> - - -<p> -Returns the value of the process environment variable <code>varname</code>, -or <b>nil</b> if the variable is not defined. - - - - -<p> -<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> - - -<p> -Deletes the file (or empty directory, on POSIX systems) -with the given name. -If this function fails, it returns <b>nil</b>, -plus a string describing the error and the error code. - - - - -<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 and the error code. - - - - -<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 system-dependent 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> -This function may be not thread safe -because of its reliance on C function <code>setlocale</code>. - - - - -<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> (default is 12), -<code>min</code> (default is 0), -<code>sec</code> (default is 0), -and <code>isdst</code> (default is <b>nil</b>). -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 -<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. - - - - -<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 POSIX systems, -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. - - - - - - - -<h2>6.10 – <a name="6.10">The Debug Library</a></h2> - -<p> -This library provides -the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. -You should exert care when using this library. -Several of its functions -violate basic assumptions about Lua code -(e.g., that variables local to a function -cannot be accessed from outside; -that userdata metatables cannot be changed by Lua code; -that Lua programs do not crash) -and therefore can compromise otherwise secure code. -Moreover, some functions in this library may be slow. - - -<p> -All functions in this library are provided -inside the <a name="pdf-debug"><code>debug</code></a> table. -All functions that operate over a thread -have an optional first argument which is the -thread to operate over. -The default is always the current thread. - - -<p> -<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> - - -<p> -Enters an interactive mode with the user, -running each string that the user enters. -Using simple commands and other debug facilities, -the user can inspect global and local variables, -change their values, evaluate expressions, and so on. -A line containing only the word <code>cont</code> finishes this function, -so that the caller continues its execution. - - -<p> -Note that commands for <code>debug.debug</code> are not lexically nested -within any function and so have no direct access to local variables. - - - - -<p> -<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> - - -<p> -Returns the current hook settings of the thread, as three values: -the current hook function, the current hook mask, -and the current hook count -(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). - - - - -<p> -<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> - - -<p> -Returns a table with information about a function. -You can give the function directly -or you can give a number as the value of <code>f</code>, -which means the function running at level <code>f</code> of the call stack -of the given thread: -level 0 is the current function (<code>getinfo</code> itself); -level 1 is the function that called <code>getinfo</code> -(except for tail calls, which do not count on the stack); -and so on. -If <code>f</code> is a number larger than the number of active functions, -then <code>getinfo</code> returns <b>nil</b>. - - -<p> -The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, -with the string <code>what</code> describing which fields to fill in. -The default for <code>what</code> is to get all information available, -except the table of valid lines. -If present, -the option '<code>f</code>' -adds a field named <code>func</code> with the function itself. -If present, -the option '<code>L</code>' -adds a field named <code>activelines</code> with the table of -valid lines. - - -<p> -For instance, the expression <code>debug.getinfo(1,"n").name</code> returns -a table with a name for the current function, -if a reasonable name can be found, -and the expression <code>debug.getinfo(print)</code> -returns a table with all available information -about the <a href="#pdf-print"><code>print</code></a> function. - - - - -<p> -<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> - - -<p> -This function returns the name and the value of the local variable -with index <code>local</code> of the function at level <code>f</code> of the stack. -This function accesses not only explicit local variables, -but also parameters, temporaries, etc. - - -<p> -The first parameter or local variable has index 1, and so on, -until the last active variable. -Negative indices refer to vararg parameters; --1 is the first vararg parameter. -The function returns <b>nil</b> if there is no variable with the given index, -and raises an error when called with a level out of range. -(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) - - -<p> -Variable names starting with '<code>(</code>' (open parenthesis) -represent internal variables -(loop control variables, temporaries, varargs, and C function locals). - - -<p> -The parameter <code>f</code> may also be a function. -In that case, <code>getlocal</code> returns only the name of function parameters. - - - - -<p> -<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> - - -<p> -Returns the metatable of the given <code>value</code> -or <b>nil</b> if it does not have a metatable. - - - - -<p> -<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> - - -<p> -Returns the registry table (see <a href="#4.5">§4.5</a>). - - - - -<p> -<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> - - -<p> -This function returns the name and the value of the upvalue -with index <code>up</code> of the function <code>f</code>. -The function returns <b>nil</b> if there is no upvalue with the given index. - - - - -<p> -<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> - - -<p> -Returns the Lua value associated to <code>u</code>. -If <code>u</code> is not a userdata, -returns <b>nil</b>. - - - - -<p> -<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> - - -<p> -Sets the given function as a hook. -The string <code>mask</code> and the number <code>count</code> describe -when the hook will be called. -The string mask may have the following characters, -with the given meaning: - -<ul> -<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> -<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> -<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> -</ul><p> -With a <code>count</code> different from zero, -the hook is called after every <code>count</code> instructions. - - -<p> -When called without arguments, -<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. - - -<p> -When the hook is called, its first parameter is a string -describing the event that has triggered its call: -<code>"call"</code> (or <code>"tail call"</code>), -<code>"return"</code>, -<code>"line"</code>, and <code>"count"</code>. -For line events, -the hook also gets the new line number as its second parameter. -Inside a hook, -you can call <code>getinfo</code> with level 2 to get more information about -the running function -(level 0 is the <code>getinfo</code> function, -and level 1 is the hook function). - - - - -<p> -<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> - - -<p> -This function assigns the value <code>value</code> to the local variable -with index <code>local</code> of the function at level <code>level</code> of the stack. -The function returns <b>nil</b> if there is no local -variable with the given index, -and raises an error when called with a <code>level</code> out of range. -(You can call <code>getinfo</code> to check whether the level is valid.) -Otherwise, it returns the name of the local variable. - - -<p> -See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about -variable indices and names. - - - - -<p> -<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> - - -<p> -Sets the metatable for the given <code>value</code> to the given <code>table</code> -(which can be <b>nil</b>). -Returns <code>value</code>. - - - - -<p> -<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> - - -<p> -This function assigns the value <code>value</code> to the upvalue -with index <code>up</code> of the function <code>f</code>. -The function returns <b>nil</b> if there is no upvalue -with the given index. -Otherwise, it returns the name of the upvalue. - - - - -<p> -<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> - - -<p> -Sets the given <code>value</code> as -the Lua value associated to the given <code>udata</code>. -<code>value</code> must be a table or <b>nil</b>; -<code>udata</code> must be a full userdata. - - -<p> -Returns <code>udata</code>. - - - - -<p> -<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> - - -<p> -If <code>message</code> is present but is neither a string nor <b>nil</b>, -this function returns <code>message</code> without further processing. -Otherwise, -it returns a string with a traceback of the call stack. -An optional <code>message</code> string is appended -at the beginning of the traceback. -An optional <code>level</code> number tells at which level -to start the traceback -(default is 1, the function calling <code>traceback</code>). - - - - -<p> -<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> - - -<p> -Returns an unique identifier (as a light userdata) -for the upvalue numbered <code>n</code> -from the given function. - - -<p> -These unique identifiers allow a program to check whether different -closures share upvalues. -Lua closures that share an upvalue -(that is, that access a same external local variable) -will return identical ids for those upvalue indices. - - - - -<p> -<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> - - -<p> -Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> -refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. - - - - - - - -<h1>7 – <a name="7">Lua Standalone</a></h1> - -<p> -Although Lua has been designed as an extension language, -to be embedded in a host C program, -it is also frequently used as a standalone language. -An interpreter for Lua as a standalone language, -called simply <code>lua</code>, -is provided with the standard distribution. -The standalone interpreter includes -all standard libraries, including the debug library. -Its usage is: - -<pre> - lua [options] [script [args]] -</pre><p> -The options are: - -<ul> -<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> -<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> -<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> -<li><b><code>-v</code>: </b> prints version information;</li> -<li><b><code>-E</code>: </b> ignores environment variables;</li> -<li><b><code>--</code>: </b> stops handling options;</li> -<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> -</ul><p> -After handling its options, <code>lua</code> runs the given <em>script</em>, -passing to it the given <em>args</em> as string arguments. -When called without arguments, -<code>lua</code> behaves as <code>lua -v -i</code> -when the standard input (<code>stdin</code>) is a terminal, -and as <code>lua -</code> otherwise. - - -<p> -When called without option <code>-E</code>, -the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_2"><code>LUA_INIT_5_2</code></a> -(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined) -before running any argument. -If the variable content has the format <code>@<em>filename</em></code>, -then <code>lua</code> executes the file. -Otherwise, <code>lua</code> executes the string itself. - - -<p> -When called with option <code>-E</code>, -besides ignoring <code>LUA_INIT</code>, -Lua also ignores -the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, -setting the values of -<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> -with the default paths defined in <code>luaconf.h</code>. - - -<p> -All options are handled in order, except <code>-i</code> and <code>-E</code>. -For instance, an invocation like - -<pre> - $ lua -e'a=1' -e 'print(a)' script.lua -</pre><p> -will first set <code>a</code> to 1, then print the value of <code>a</code>, -and finally run the file <code>script.lua</code> with no arguments. -(Here <code>$</code> is the shell prompt. Your prompt may be different.) - - -<p> -Before starting to run the script, -<code>lua</code> collects all arguments in the command line -in a global table called <code>arg</code>. -The script name is stored at index 0, -the first argument after the script name goes to index 1, -and so on. -Any arguments before the script name -(that is, the interpreter name plus the options) -go to negative indices. -For instance, in the call - -<pre> - $ lua -la b.lua t1 t2 -</pre><p> -the interpreter first runs the file <code>a.lua</code>, -then creates a table - -<pre> - arg = { [-2] = "lua", [-1] = "-la", - [0] = "b.lua", - [1] = "t1", [2] = "t2" } -</pre><p> -and finally runs the file <code>b.lua</code>. -The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... -as arguments; -it can also access these arguments with the vararg expression '<code>...</code>'. - - -<p> -In interactive mode, -if you write an incomplete statement, -the interpreter waits for its completion -by issuing a different prompt. - - -<p> -In case of unprotected errors in the script, -the interpreter reports the error to the standard error stream. -If the error object is a string, -the interpreter adds a stack traceback to it. -Otherwise, if the error object has a metamethod <code>__tostring</code>, -the interpreter calls this metamethod to produce the final message. -Finally, if the error object is <b>nil</b>, -the interpreter does not report the error. - - -<p> -When finishing normally, -the interpreter closes its main Lua state -(see <a href="#lua_close"><code>lua_close</code></a>). -The script can avoid this step by -calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. - - -<p> -To allow the use of Lua as a -script interpreter in Unix systems, -the standalone interpreter skips -the first line of a chunk if it starts with <code>#</code>. -Therefore, Lua scripts can be made into executable programs -by using <code>chmod +x</code> and the <code>#!</code> form, -as in - -<pre> - #!/usr/local/bin/lua -</pre><p> -(Of course, -the location of the Lua interpreter may be different in your machine. -If <code>lua</code> is in your <code>PATH</code>, -then - -<pre> - #!/usr/bin/env lua -</pre><p> -is a more portable solution.) - - - -<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> - -<p> -Here we list the incompatibilities that you may find when moving a program -from Lua 5.1 to Lua 5.2. -You can avoid some incompatibilities by compiling Lua with -appropriate options (see file <code>luaconf.h</code>). -However, -all these compatibility options will be removed in the next version of Lua. -Similarly, -all features marked as deprecated in Lua 5.1 -have been removed in Lua 5.2. - - - -<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> -<ul> - -<li> -The concept of <em>environment</em> changed. -Only Lua functions have environments. -To set the environment of a Lua function, -use the variable <code>_ENV</code> or the function <a href="#pdf-load"><code>load</code></a>. - - -<p> -C functions no longer have environments. -Use an upvalue with a shared table if you need to keep -shared state among several C functions. -(You may use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> to open a C library -with all functions sharing a common upvalue.) - - -<p> -To manipulate the "environment" of a userdata -(which is now called user value), -use the new functions -<a href="#lua_getuservalue"><code>lua_getuservalue</code></a> and <a href="#lua_setuservalue"><code>lua_setuservalue</code></a>. -</li> - -<li> -Lua identifiers cannot use locale-dependent letters. -</li> - -<li> -Doing a step or a full collection in the garbage collector -does not restart the collector if it has been stopped. -</li> - -<li> -Weak tables with weak keys now perform like <em>ephemeron tables</em>. -</li> - -<li> -The event <em>tail return</em> in debug hooks was removed. -Instead, tail calls generate a special new event, -<em>tail call</em>, so that the debugger can know that -there will not be a corresponding return event. -</li> - -<li> -Equality between function values has changed. -Now, a function definition may not create a new value; -it may reuse some previous value if there is no -observable difference to the new function. -</li> - -</ul> - - - - -<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> -<ul> - -<li> -Function <code>module</code> is deprecated. -It is easy to set up a module with regular Lua code. -Modules are not expected to set global variables. -</li> - -<li> -Functions <code>setfenv</code> and <code>getfenv</code> were removed, -because of the changes in environments. -</li> - -<li> -Function <code>math.log10</code> is deprecated. -Use <a href="#pdf-math.log"><code>math.log</code></a> with 10 as its second argument, instead. -</li> - -<li> -Function <code>loadstring</code> is deprecated. -Use <code>load</code> instead; it now accepts string arguments -and are exactly equivalent to <code>loadstring</code>. -</li> - -<li> -Function <code>table.maxn</code> is deprecated. -Write it in Lua if you really need it. -</li> - -<li> -Function <code>os.execute</code> now returns <b>true</b> when command -terminates successfully and <b>nil</b> plus error information -otherwise. -</li> - -<li> -Function <code>unpack</code> was moved into the table library -and therefore must be called as <a href="#pdf-table.unpack"><code>table.unpack</code></a>. -</li> - -<li> -Character class <code>%z</code> in patterns is deprecated, -as now patterns may contain '<code>\0</code>' as a regular character. -</li> - -<li> -The table <code>package.loaders</code> was renamed <code>package.searchers</code>. -</li> - -<li> -Lua does not have bytecode verification anymore. -So, all functions that load code -(<a href="#pdf-load"><code>load</code></a> and <a href="#pdf-loadfile"><code>loadfile</code></a>) -are potentially insecure when loading untrusted binary data. -(Actually, those functions were already insecure because -of flaws in the verification algorithm.) -When in doubt, -use the <code>mode</code> argument of those functions -to restrict them to loading textual chunks. -</li> - -<li> -The standard paths in the official distribution may -change between versions. -</li> - -</ul> - - - - -<h2>8.3 – <a name="8.3">Changes in the API</a></h2> -<ul> - -<li> -Pseudoindex <code>LUA_GLOBALSINDEX</code> was removed. -You must get the global environment from the registry -(see <a href="#4.5">§4.5</a>). -</li> - -<li> -Pseudoindex <code>LUA_ENVIRONINDEX</code> -and functions <code>lua_getfenv</code>/<code>lua_setfenv</code> -were removed, -as C functions no longer have environments. -</li> - -<li> -Function <code>luaL_register</code> is deprecated. -Use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> so that your module does not create globals. -(Modules are not expected to set global variables anymore.) -</li> - -<li> -The <code>osize</code> argument to the allocation function -may not be zero when creating a new block, -that is, when <code>ptr</code> is <code>NULL</code> -(see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). -Use only the test <code>ptr == NULL</code> to check whether -the block is new. -</li> - -<li> -Finalizers (<code>__gc</code> metamethods) for userdata are called in the -reverse order that they were marked for finalization, -not that they were created (see <a href="#2.5.1">§2.5.1</a>). -(Most userdata are marked immediately after they are created.) -Moreover, -if the metatable does not have a <code>__gc</code> field when set, -the finalizer will not be called, -even if it is set later. -</li> - -<li> -<code>luaL_typerror</code> was removed. -Write your own version if you need it. -</li> - -<li> -Function <code>lua_cpcall</code> is deprecated. -You can simply push the function with <a href="#lua_pushcfunction"><code>lua_pushcfunction</code></a> -and call it with <a href="#lua_pcall"><code>lua_pcall</code></a>. -</li> - -<li> -Functions <code>lua_equal</code> and <code>lua_lessthan</code> are deprecated. -Use the new <a href="#lua_compare"><code>lua_compare</code></a> with appropriate options instead. -</li> - -<li> -Function <code>lua_objlen</code> was renamed <a href="#lua_rawlen"><code>lua_rawlen</code></a>. -</li> - -<li> -Function <a href="#lua_load"><code>lua_load</code></a> has an extra parameter, <code>mode</code>. -Pass <code>NULL</code> to simulate the old behavior. -</li> - -<li> -Function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter, <code>from</code>. -Pass <code>NULL</code> or the thread doing the call. -</li> - -</ul> - - - - -<h1>9 – <a name="9">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 ::= block - - block ::= {stat} [retstat] - - stat ::= ‘<b>;</b>’ | - varlist ‘<b>=</b>’ explist | - functioncall | - label | - <b>break</b> | - <b>goto</b> Name | - <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] - - retstat ::= <b>return</b> [explist] [‘<b>;</b>’] - - label ::= ‘<b>::</b>’ Name ‘<b>::</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>’ | functiondef | - 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 - - functiondef ::= <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: -Thu Mar 21 13:01:53 BRT 2013 -</SMALL> -<!-- -Last change: revised for Lua 5.2.2 ---> - -</body></html> -