repo/luan: website/src/manual.html comparison

comparison website/src/manual.html @ 1325:28c1fc6d9d29

website - make docs html

author	Franklin Schmidt <fschmidt@gmail.com>
date	Thu, 07 Feb 2019 23:00:20 -0700
parents	website/src/manual.html.luan@1660136ac451
children	29d6d7d79c41

comparison

equal deleted inserted replaced

-:1660136ac451
+:28c1fc6d9d29
+<!doctype html>
+<html>
+<head>
+	<title>Luan Reference Manual</title>
+	<style>
+		@import "/site.css";
+	</style>
+</head>
+<body>
+<div small><a href="/">Luan</a></div>
+<h1>Luan Reference Manual</h1>
+<p small>
+Original copyright &copy; 2015 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.
+</p>
+<hr/>
+<h2>Contents</h2>
+<div contents><a href="#intro">Introduction</a></div>
+<div contents>
+	<a href="#basic">Basic Concepts</a>
+	<ul>
+		<li><a href="#types">Values and Types</a></li>
+		<li><a href="#env">Environments</a></li>
+		<li><a href="#error">Error Handling</a></li>
+		<li><a href="#meta">Metatables and Metamethods</a></li>
+		<li><a href="#gc">Garbage Collection</a></li>
+	</ul>
+</div>
+<div contents>
+	<a href="#lang">The Language</a>
+	<ul>
+		<li><a href="#lex">Lexical Conventions</a></li>
+		<li><a href="#vars">Variables</a></li>
+		<li>
+			<a href="#stmts">Statements</a>
+			<ul>
+				<li><a href="#blocks">Blocks</a></li>
+				<li><a href="#chunks">Chunks</a></li>
+				<li><a href="#assignment">Assignment</a></li>
+				<li><a href="#control">Control Structures</a></li>
+				<li><a href="#for">For Statement</a></li>
+				<li><a href="#fn_stmt">Function Calls as Statements</a></li>
+				<li><a href="#local_stmt">Local Declarations</a></li>
+				<li><a href="#template_stmt">Template Statements</a></li>
+			</ul>
+		</li>
+		<li>
+			<a href="#expressions">Expressions</a>
+			<ul>
+				<li><a href="#arithmetic">Arithmetic Operators</a></li>
+				<li><a href="#conversions">Coercions and Conversions</a></li>
+				<li><a href="#relational">Relational Operators</a></li>
+				<li><a href="#logical_ops">Logical Operators</a></li>
+				<li><a href="#concatenation">Concatenation</a></li>
+				<li><a href="#length">The Length Operator</a></li>
+				<li><a href="#precedence">Precedence</a></li>
+				<li><a href="#constructors">Table Constructors</a></li>
+				<li><a href="#fn_calls">Function Calls</a></li>
+				<li><a href="#fn_def">Function Definitions</a></li>
+				<li><a href="#template_expr">Template Expressions</a></li>
+			</ul>
+		</li>
+		<li><a href="#visibility">Visibility Rules</a></li>
+	</ul>
+</div>
+<div contents>
+	<a href="#libs">Standard Libraries</a>
+	<ul>
+		<li><a href="#default_lib">Default Environment</a></li>
+		<li><a href="#luan_lib">Basic Functions</a></li>
+		<li><a href="#package_lib">Modules</a></li>
+		<li><a href="#string_lib">String Manipulation</a></li>
+		<li><a href="#binary_lib">Binary Manipulation</a></li>
+		<li><a href="#table_lib">Table Manipulation</a></li>
+		<li><a href="#number_lib">Number Manipulation</a></li>
+		<li><a href="#math_lib">Mathematical Functions</a></li>
+	</ul>
+</div>
+<hr/>
+<h2 heading><a name="intro">Introduction</a></h2>
+<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 one can quickly learn the language and then easily understand any code written in Luan.</p>
+<p>Luan is implemented in Java and is tightly coupled with Java.  So it makes a great scripting language for Java programmers.</p>
+<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.</p>
+<h2 heading><a name="basic">Basic Concepts</a></h2>
+<p>This section describes the basic concepts of the language.</p>
+<h3 heading><a name="types">Values and Types</a></h3>
+<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 Luan:
+<em>nil</em>, <em>boolean</em>, <em>number</em>,
+<em>string</em>, <em>binary</em>, <em>function</em>, <em>java</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 both
+integer numbers and real (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="#fn_calls">Function Calls</a>).
+Both are represented by the type <em>function</em>.
+<p>
+The type <em>java</em> is provided to allow arbitrary Java objects to
+be stored in Luan variables.
+A <em>java</em> value is a Java object that isn't one of the standard Luan types.
+Java values have no predefined operations in Luan,
+except assignment and identity test.
+Java values are useful when Java access is enabled in Luan
+<p>
+The type <em>table</em> implements associative arrays,
+that is, arrays that can be indexed not only with numbers,
+but with any Luan 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 Luan;
+they can be used to represent ordinary arrays, sequences,
+symbol tables, sets, records, graphs, trees, etc.
+To represent records, Luan 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 Luan
+(see <a href="#constructors">Table Constructors</a>).
+<p>
+We use the term <em>sequence</em> to denote a table where
+the set of all positive numeric keys is equal to {1..<em>n</em>}
+for some non-negative integer <em>n</em>,
+which is called the length of the sequence (see <a href="#length">The Length Operator</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="#fn_def">Function Definitions</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).
+In particular, floats with integral values
+are equal to their respective integers
+(e.g., <code>1.0 == 1</code>).
+<p>
+Luan values are <em>objects</em>:
+variables do not actually <em>contain</em> values,
+only <em>references</em> to them.
+Assignment, parameter passing, and function returns
+always manipulate references to values;
+these operations do not imply any kind of copy.
+<p>
+The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type
+of a given value.
+<h3 heading><a name="env">Environments</a></h3>
+<p>
+The environment of a chunk starts with only two local variables: <code><a href="#require">require</a></code> and <code><a href="#java">java</a></code>.  These are functions are used to load and access libraries and other modules.  All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>.
+<p>
+As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>,
+any reference to a free name
+(that is, a name not bound to any declaration) <code>var</code>
+can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined.
+<h3 heading><a name="error">Error Handling</a></h3>
+<p>
+Luan code can explicitly generate an error by calling the
+<a href="#Luan.error"><code>error</code></a> function.
+If you need to catch errors in Luan,
+you can use <a href="#Luan.pcall"><code>pcall</code></a> or <a href="#Luan.try"><code>try</code></a>
+to call a given function in <em>protected mode</em>.
+<p>
+Whenever there is an error,
+an <em>error table</em>
+is propagated with information about the error.
+See <a href="#Luan.new_error"><code>Luan.new_error</code></a>.
+<h3 heading><a name="meta">Metatables and Metamethods</a></h3>
+<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 value
+under certain special operations.
+You can change several aspects of the behavior
+of operations over a value by setting specific fields in its metatable.
+For instance, when a 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>
+The keys in a metatable are derived from the <em>event</em> names;
+the corresponding values are called <ii>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 table
+using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function.
+<p>
+You can replace the metatable of tables
+using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function.
+<p>
+A metatable controls how a table behaves in
+arithmetic operations, bitwise operations,
+order comparisons, concatenation, length operation, calls, and indexing.
+<p>
+A detailed list of events controlled by metatables is given next.
+Each operation is identified by its corresponding event name.
+The key for each event 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>".
+Note that queries for metamethods are always raw;
+the access to a metamethod does not invoke other metamethods.
+You can emulate how Luan queries a metamethod for an object <code>obj</code>
+with the following code:
+<pre>
+raw_get(get_metatable(obj) or {}, "__" .. event_name)
+</pre>
+<p>
+Here are the events:
+<ul>
+<li><p><b>"add": </b>
+the <code>+</code> operation.
+If any operand for an addition is a table,
+Luan will try to call a metamethod.
+First, Luan will check the first operand (even if it is valid).
+If that operand does not define a metamethod for the "<code>__add</code>" event,
+then Luan will check the second operand.
+If Luan can find a metamethod,
+it calls the metamethod with the two operands as arguments,
+and the result of the call
+(adjusted to one value)
+is the result of the operation.
+Otherwise,
+it raises an error.
+</li>
+<li><p><b>"sub": </b>
+the <code>-</code> operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"mul": </b>
+the <code>*</code> operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"div": </b>
+the <code>/</code> operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"mod": </b>
+the <code>%</code> operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"pow": </b>
+the <code>^</code> (exponentiation) operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"unm": </b>
+the <code>-</code> (unary minus) operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"concat": </b>
+the <code>..</code> (concatenation) operation.
+Behavior similar to the "add" operation.
+</li>
+<li><p><b>"len": </b>
+the <code>#</code> (length) operation.
+If there is a metamethod,
+Luan calls it with the object as argument,
+and the result of the call
+(always adjusted to one value)
+is the result of the operation.
+If there is no metamethod but the object is a table,
+then Luan uses the table length operation (see <a href="#length">The Length Operator</a>).
+Otherwise, Luan raises an error.
+</li>
+<li><p><b>"eq": </b>
+the <code>==</code> (equal) operation.
+Behavior similar to the "add" operation,
+except that Luan will try a metamethod only when the values
+being compared are both tables
+and they are not primitively equal.
+The result of the call is always converted to a boolean.
+</li>
+<li><p><b>"lt": </b>
+the <code>&lt;</code> (less than) operation.
+Behavior similar to the "add" operation.
+The result of the call is always converted to a boolean.
+</li>
+<li><p><b>"le": </b>
+the <code>&lt;=</code> (less equal) operation.
+Unlike other operations,
+The less-equal operation can use two different events.
+First, Luan looks for the "<code>__le</code>" metamethod in both operands,
+like in the "lt" operation.
+If it cannot find such a metamethod,
+then it will try the "<code>__lt</code>" event,
+assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
+As with the other comparison operators,
+the result is always a boolean.
+</li>
+<li><p><b>"index": </b>
+The indexing access <code>table[key]</code>.
+This event happens
+when <code>key</code> is not present in <code>table</code>.
+The metamethod is looked up in <code>table</code>.
+<p>
+Despite the name,
+the metamethod for this event can be any type.
+If it is a function,
+it is called with <code>table</code> and <code>key</code> as arguments.
+Otherwise
+the final result is the result of indexing this metamethod object with <code>key</code>.
+(This indexing is regular, not raw,
+and therefore can trigger another metamethod if the metamethod object is a table.)
+</li>
+<li><p><b>"new_index": </b>
+The indexing assignment <code>table[key] = value</code>.
+Like the index event,
+this event happens when
+when <code>key</code> is not present in <code>table</code>.
+The metamethod is looked up in <code>table</code>.
+<p>
+Like with indexing,
+the metamethod for this event can be either a function or a table.
+If it is a function,
+it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
+If it is a table,
+Luan does an indexing assignment to this table with the same key and value.
+(This assignment is regular, not raw,
+and therefore can trigger another metamethod.)
+<p>
+Whenever there is a "new_index" metamethod,
+Luan does not perform the primitive assignment.
+(If necessary,
+the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a>
+to do the assignment.)
+</li>
+<li><p><b>"gc":</b>
+This is when a table is garbage collected.  When the table's <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#finalize()">finalize</a> method is called by the Java garbage collector, if there is a "<code>__gc</code>" metamethod then it is called with the table as a parameter.
+</li>
+</ul>
+<h3 heading><a name="gc">Garbage Collection</a></h3>
+<p>
+Luan uses Java's garbage collection.
+<h2 heading><a name="lang">The Language</a></h2>
+<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>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
+[<em>a</em>]&nbsp;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 &lsquo;<b>=</b>&rsquo;.
+The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
+at the end of this manual.
+<h3 heading><a name="lex">Lexical Conventions</a></h3>
+<p>
+Luan ignores spaces and comments
+between lexical elements (tokens),
+except as delimiters between names and keywords.
+Luan considers the end of a line to be the end of a statement.  This catches errors and encourages readability.  If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space.
+<p>
+<em>Names</em>
+(also called <em>identifiers</em>)
+in Luan 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
+end_do    end_for   end_function        end_if    end_while
+false     for       function  goto      if        in
+local     nil       not       or        repeat    return
+then      true      until     while
+</pre>
+<p>
+Luan 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.
+<p>
+The following strings denote other tokens:
+<pre>
++     -     *     /     %     ^     #
+&amp;     ~     |     &lt;&lt;    &gt;&gt;    //
+==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
+(     )     {     }     [     ]     ::
+;     :     ,     .     ..    ...
+</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>
+Luan can specify any character in a literal string 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>\u<em>XXXX</em></code>,
+where <em>XXXX</em> is a sequence of exactly four 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 sequence is to be followed by a digit,
+it must be expressed using exactly three digits.)
+<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 same level.
+Literals in this bracketed form can run for several lines,
+do not interpret any escape sequences,
+and ignore long brackets of any other level.
+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>
+Any character in a literal string not
+explicitly affected by the previous rules represents itself.
+However, Luan opens files for parsing in text mode,
+and the system file functions may have problems with
+some control characters.
+So, it is safer to represent
+non-text data as a quoted literal with
+explicit escape sequences for non-text characters.
+<p>
+For convenience,
+when the opening long bracket is immediately followed by a newline,
+the newline is not included in the string.
+As an example
+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> (or <em>numeral</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>'.
+Luan 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>'.
+A numeric constant with a fractional dot or an exponent
+denotes a float;
+otherwise it denotes an integer.
+Examples of valid integer constants are
+<pre>
+3   345   0xff   0xBEBADA
+</pre>
+<p>
+Examples of valid float constants are
+<pre>
+3.0     3.1416     314.16e-2     0.31416E1     34e1
+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.
+<h3 heading><a name="vars">Variables</a></h3>
+<p>
+Variables are places that store values.
+There are three kinds of variables in Luan:
+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="#lex">Lexical Conventions</a>.
+<p>
+Local variables are <em>lexically scoped</em>:
+local variables can be freely accessed by functions
+defined inside their scope (see <a href="#visibility">Visibility Rules</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 &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
+</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>gettable_event(t,i)</code>.
+(See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
+<code>gettable_event</code> function.
+This function is not defined or callable in Luan.
+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 &lsquo;<b>.</b>&rsquo; Name
+</pre>
+<p>
+Global variables are not available by default.  To enable global variable, you must define <code>_ENV</code> as a local variable whose value is a table.  If <code>_ENV</code> is not defined, then an unrecognized variable name will produce a compile error.  If <code>_ENV</code> is defined then an access to an unrecognized variable name will be consider a global variable.  So then an acces to 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="#env">Environments</a>).
+<h3 heading><a name="stmts">Statements</a></h3>
+<p>
+Luan 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.
+<h4 heading><a name="blocks">Blocks</a></h4>
+<p>
+A block is a list of statements,
+which are executed sequentially:
+<pre>
+	block ::= {stat}
+</pre>
+<p>
+Luan 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 ::= &lsquo;<b>;</b>&rsquo;
+</pre>
+<p>
+A block can be explicitly delimited to produce a single statement:
+<pre>
+	stat ::= <b>do</b> block end_do
+	end_do ::= <b>end_do</b> | <b>end</b>
+</pre>
+<p>
+Explicit blocks are useful
+to control the scope of variable declarations.
+Explicit blocks are also sometimes used to
+add a <b>return</b> statement in the middle
+of another block (see <a href="#control">Control Structures</a>).
+<h4 heading><a name="chunks">Chunks</a></h4>
+<p>
+The unit of compilation of Luan is called a <em>chunk</em>.
+Syntactically,
+a chunk is simply a block:
+<pre>
+	chunk ::= block
+</pre>
+<p>
+Luan handles a chunk as the body of an anonymous function
+with a variable number of arguments
+(see <a href="#fn_def">Function Definitions</a>).
+As such, chunks can define local variables,
+receive arguments, and return values.
+<p>
+A chunk can be stored in a file or in a string inside the host program.
+To execute a chunk,
+Luan first <em>loads</em> it,
+compiling the chunk's code,
+and then Luan executes the compiled code.
+<h4 heading><a name="assignment">Assignment</a></h4>
+<p>
+Luan 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 &lsquo;<b>=</b>&rsquo; explist
+	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
+	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
+</pre>
+<p>
+Expressions are discussed in <a href="#expressions">Expressions</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="#expressions">Expressions</a>).
+<p>
+The assignment statement first evaluates all its expressions
+and only then the assignments are 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&nbsp;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="#meta">Metatables and Metamethods</a> for a complete description of the
+<code>settable_event</code> function.
+This function is not defined or callable in Luan.
+We use it here only for explanatory purposes.)
+<p>
+An assignment to a global name <code>x = val</code>
+is equivalent to the assignment
+<code>_ENV.x = val</code> (see <a href="#env">Environments</a>).
+Global names are only available when <code>_ENV</code> is defined.
+<h4 heading><a name="control">Control Structures</a></h4>
+<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 end_while
+	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] end_if
+	end_while ::= <b>end_while</b> | <b>end</b>
+	end_if ::= <b>end_if</b> | <b>end</b>
+</pre>
+<p>
+Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>).
+<p>
+The condition expression of a
+control structure must be a boolean.
+Any other value type will produce an error.
+This helps catch errors and makes code more readable.
+<p>
+In the <b>repeat</b>&ndash;<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 an anonymous function).
+Functions can return more than one value,
+so the syntax for the <b>return</b> statement is
+<pre>
+	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
+</pre>
+<h4 heading><a name="for">For Statement</a></h4>
+<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> exp <b>do</b> block end_for
+	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
+	end_for ::= <b>end_for</b> | <b>end</b>
+</pre>
+<p>
+A <b>for</b> statement like
+<pre>
+for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>exp</em> do <em>block</em> end
+</pre>
+<p>
+is equivalent to the code:
+<pre>
+do
+local <em>f</em> = <em>exp</em>
+while true do
+local <em>var_1</em>, &middot;&middot;&middot;, <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>exp</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>
+<h4 heading><a name="fn_stmt">Function Calls as Statements</a></h4>
+<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="#fn_calls">Function Calls</a>.
+<h4 heading><a name="local_stmt">Local Declarations</a></h4>
+<p>
+Local variables can be declared anywhere inside a block.
+The declaration can include an initial assignment:
+<pre>
+	stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
+</pre>
+<p>
+If present, an initial assignment has the same semantics
+of a multiple assignment (see <a href="#assignment">Assignment</a>).
+Otherwise, all variables are initialized with <b>nil</b>.
+<p>
+A chunk is also a block (see <a href="#chunks">Chunks</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="#visibility">Visibility Rules</a>.
+<h4 heading><a name="template_stmt">Template Statements</a></h4>
+<p>Template statements are based on <a href="#template_expr">template exressions</a> and provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way.  Template statements write the equivalent template exression to standard output.  For example:</p>
+<pre>
+	local name = "Bob"
+	%>
+	Hello <%= name %>!
+	Bye <%= name %>.
+	<%
+</pre>
+<p>is equivalent to the code:</p>
+<pre>
+	local name = "Bob"
+	require("luan:Io.luan").stdout.write( %>
+	Hello <%= name %>!
+	Bye <%= name %>.
+	<% )
+</pre>
+<h3 heading><a name="expressions">Expressions</a></h3>
+<p>
+The basic expressions in Luan are the following:
+<pre>
+	exp ::= prefixexp
+	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
+	exp ::= Numeral
+	exp ::= LiteralString
+	exp ::= functiondef
+	exp ::= tableconstructor
+	exp ::= &lsquo;<b>...</b>&rsquo;
+	exp ::= exp binop exp
+	exp ::= unop exp
+	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
+</pre>
+<p>
+Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>;
+variables are explained in <a href="#vars">Variables</a>;
+function definitions are explained in <a href="#fn_def">Function Definitions</a>;
+function calls are explained in <a href="#fn_calls">Function Calls</a>;
+table constructors are explained in <a href="#constructors">Table Constructors</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="#fn_def">Function Definitions</a>.
+<p>
+Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>),
+relational operators (see <a href="#relational">Relational Operators</a>), logical operators (see <a href="#logical_ops">Logical Operators</a>),
+and the concatenation operator (see <a href="#concatenation">Concatenation</a>).
+Unary operators comprise the unary minus (see <a href="#arithmetic">Arithmetic Operators</a>),
+the unary logical <b>not</b> (see <a href="#logical_ops">Logical Operators</a>),
+and the unary <em>length operator</em> (see <a href="#length">The Length Operator</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="#fn_stmt">Function Calls as Statements</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,
+Luan 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.)
+<h4 heading><a name="arithmetic">Arithmetic Operators</a></h4>
+<p>
+Luan supports the following arithmetic operators:
+<ul>
+<li><b><code>+</code>: </b>addition</li>
+<li><b><code>-</code>: </b>subtraction</li>
+<li><b><code>*</code>: </b>multiplication</li>
+<li><b><code>/</code>: </b>division</li>
+<li><b><code>%</code>: </b>modulo</li>
+<li><b><code>^</code>: </b>exponentiation</li>
+<li><b><code>-</code>: </b>unary minus</li>
+</ul>
+<p>
+Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java.  Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function.
+<p>
+Modulo is defined as the remainder of a division
+that rounds the quotient towards minus infinite (floor division).
+(The Java modulo operator is not used.)
+<h4 heading><a name="conversions">Coercions and Conversions</a></h4>
+<p>
+Luan generally avoids automatic conversions.
+String concatenation automatically converts all of its arguments to strings.
+<p>
+Luan provides library functions for explicit type conversions.
+<h4 heading><a name="relational">Relational Operators</a></h4>
+<p>
+Luan supports the following relational operators:
+<ul>
+<li><b><code>==</code>: </b>equality</li>
+<li><b><code>~=</code>: </b>inequality</li>
+<li><b><code>&lt;</code>: </b>less than</li>
+<li><b><code>&gt;</code>: </b>greater than</li>
+<li><b><code>&lt;=</code>: </b>less or equal</li>
+<li><b><code>&gt;=</code>: </b>greater or equal</li>
+</ul><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.
+Strings, numbers, and binary values are compared in the obvious way (by value).
+<p>
+Tables
+are compared by reference:
+two objects are considered equal only if they are the same object.
+Every time you create a new table,
+it is different from any previously existing table.
+Closures are also compared by reference.
+<p>
+You can change the way that Luan compares tables
+by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>).
+<p>
+Java values are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><code>equals</code></a> method.
+<p>
+Equality comparisons do not convert strings to numbers
+or vice versa.
+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 following
+the usual rule for binary operations.
+Otherwise, if both arguments are strings,
+then their values are compared according to the current locale.
+Otherwise, Luan tries to call the "lt" or the "le"
+metamethod (see <a href="#meta">Metatables and Metamethods</a>).
+A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
+and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
+<h4 heading><a name="logical_ops">Logical Operators</a></h4>
+<p>
+The logical operators in Luan are
+<b>and</b>, <b>or</b>, and <b>not</b>.
+The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
+and anything else as true.
+Like the control structures (see <a href="#control">Control Structures</a>),
+the <b>not</b> operator requires a boolean value.
+<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-circuit evaluation;
+that is,
+the second operand is evaluated only if necessary.
+Here are some examples:
+<pre>
+10 or 20            --&gt; 10
+10 or error()       --&gt; 10
+nil or "a"          --&gt; "a"
+nil and 10          --&gt; nil
+false and error()   --&gt; false
+false and nil       --&gt; false
+false or nil        --&gt; nil
+10 and 20           --&gt; 20
+</pre>
+<p>
+(In this manual,
+<code>--&gt;</code> indicates the result of the preceding expression.)
+<h4 heading><a name="concatenation">Concatenation</a></h4>
+<p>
+The string concatenation operator in Luan is
+denoted by two dots ('<code>..</code>').
+All operands are converted to strings.
+<h4 heading><a name="length">The Length Operator</a></h4>
+<p>
+The length operator is denoted by the unary prefix operator <code>#</code>.
+The length of a string is its number of characters.
+The length of a binary is its number of bytes.
+<p>
+A program can modify the behavior of the length operator for
+any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>).
+<p>
+Unless a <code>__len</code> metamethod is given,
+the length of a table <code>t</code> is defined
+as the number of elements in <em>sequence</em>,
+that is,
+the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
+for some non-negative integer <em>n</em>.
+In that case, <em>n</em> is its length.
+Note that a table like
+<pre>
+{10, 20, nil, 40}
+</pre>
+<p>
+has a length of <code>2</code>, because that is the last key in sequence.
+<h4 heading><a name="precedence">Precedence</a></h4>
+<p>
+Operator precedence in Luan follows the table below,
+from lower to higher priority:
+<pre>
+or
+and
+&lt;     &gt;     &lt;=    &gt;=    ~=    ==
+..
++     -
+*     /     %
+unary operators (not   #     -)
+^
+</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.
+<h4 heading><a name="constructors">Table Constructors</a></h4>
+<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 ::= &lsquo;<b>{</b>&rsquo; fieldlist &lsquo;<b>}</b>&rsquo;
+	fieldlist ::= [field] {fieldsep [field]}
+	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
+	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo; | <b>end_of_line</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 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>
+The order of the assignments in a constructor is undefined.
+(This order would be relevant only when there are repeated keys.)
+<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="#fn_calls">Function Calls</a>).
+<p>
+The field list can have an optional trailing separator,
+as a convenience for machine-generated code.
+<h4 heading><a name="fn_calls">Function Calls</a></h4>
+<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.
+The value of prefixexp must have type <em>function</em>.
+This function is called
+with the given arguments.
+<p>
+Arguments have the following syntax:
+<pre>
+	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
+	args ::= tableconstructor
+	args ::= LiteralString
+</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.
+<h4 heading><a name="fn_def">Function Definitions</a></h4>
+<p>
+The syntax for function definition is
+<pre>
+	functiondef ::= <b>function</b> funcbody
+	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block end_function
+	end_function ::= <b>end_function</b> | <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 {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; 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 [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
+</pre>
+<p>
+When a function is called,
+the list of arguments is adjusted to
+the length of the list of parameters if the list is too short,
+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)       runtime error
+f(r(), 10)       runtime error
+f(r())           runtime error
+g(3)             a=3, b=nil, ... --&gt;  (nothing)
+g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
+g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
+g(5, r())        a=5, b=1,   ... --&gt;  2  3
+</pre>
+<p>
+Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>).
+If control reaches the end of a function
+without encountering a <b>return</b> statement,
+then the function returns with no results.
+<h4 heading><a name="template_expr">Template Expressions</a></h4>
+<p>Luan template expression are based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>.  Template expressions return multiple values.  Here is an example:</p>
+<pre>
+	local name = "Bob"
+	write( %>Hello <%= name %>!<% )
+</pre>
+<p>This is equivalent to the code:</p>
+<pre>
+	local name = "Bob"
+	write( "Hello ", name, "!" )
+</pre>
+<p>The strings in template expressions may be multiple lines.</p>
+<h3 heading><a name="visibility">Visibility Rules</a></h3>
+<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)            --&gt; 10
+x = x+1
+do                  -- another block
+local x = x+1     -- another 'x'
+print(x)          --&gt; 12
+end
+print(x)            --&gt; 11
+end
+print(x)              --&gt; 10  (the global one)
+</pre>
+<p>
+Notice that, in a declaration like <code>local x = x</code>,
+the new <code>x</code> being declared is not in scope yet,
+and so the second <code>x</code> refers to the outside variable.
+<p>
+Because of the lexical scoping rules,
+local variables can be freely accessed by functions
+defined inside their scope.
+A local variable used by an inner function is called
+an <em>upvalue</em>, or <em>external local variable</em>,
+inside the inner function.
+<p>
+Notice that each execution of a <b>local</b> statement
+defines new local variables.
+Consider the following example:
+<pre>
+a = {}
+local x = 20
+for i=1,10 do
+local y = 0
+a[i] = function () y=y+1; return x+y end
+end
+</pre>
+<p>
+The loop creates ten closures
+(that is, ten instances of the anonymous function).
+Each of these closures uses a different <code>y</code> variable,
+while all of them share the same <code>x</code>.
+<h2 heading><a name="libs">Standard Libraries</a></h2>
+<p>
+The standard Luan libraries provide useful functions
+that are implemented both in Java and in Luan itself.
+How each function is implemented shouldn't matter to the user.
+Some of these functions provide essential services to the language
+(e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>);
+others provide access to "outside" services (e.g., I/O).
+<h3 heading><a name="default_lib">Default Environment</a></h3>
+<p>
+These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>.
+<h4 heading><a name="require"><code>java ()</code></a></h4>
+<p>
+This function enables Java in the current chunk if that chunk has permission to use Java.  If the chunk doesn't have permission to use Java, then an error is thrown.
+<h4 heading><a name="require"><code>require (mod_uri)</code></a></h4>
+<p>
+Example use:
+<pre>
+	local Table = require "luan:Table.luan"
+</pre>
+<p>
+Could be defined as:
+<pre>
+	local function require(mod_name)
+		return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
+	end
+</pre>
+<h3 heading><a name="luan_lib">Basic Functions</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Luan = require "luan:Luan.luan"
+</pre>
+<p>
+The basic library provides basic functions to Luan that don't depend on other libaries.
+<h4 heading><a name="Luan.do_file" href="#Luan.do_file"><code>Luan.do_file ([uri])</code></a></h4>
+<p>
+Could be defined as:
+<pre>
+	function Luan.do_file(uri)
+		local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found")
+		return fn()
+	end
+</pre>
+<h4 heading><a name="Luan.error" href="#Luan.error"><code>Luan.error (message)</code></a></h4>
+<p>
+Throws an error containing the message.
+<p>
+Could be defined as:
+<pre>
+	function Luan.error(message)
+		<a href="#Luan.new_error">Luan.new_error</a>(message).throw()
+	end
+</pre>
+<h4 heading><a name="Luan.eval" href="#Luan.eval"><code>Luan.eval (text [, source_name])</code></a></h4>
+<p>
+Evaluates <code>text</code> as a Luan expression.
+<p>
+Could be defined as:
+<pre>
+	function Luan.eval(text,source_name)
+		return Luan.load( "return "..text, source_name or "eval" )()
+	end
+</pre>
+<h4 heading><a name="Luan.get_metatable" href="#Luan.get_metatable"><code>Luan.get_metatable (table)</code></a></h4>
+<p>
+If <code>table</code> does not have a metatable, returns <b>nil</b>.
+Otherwise,
+if the table's metatable has a <code>"__metatable"</code> field,
+returns the associated value.
+Otherwise, returns the metatable of the given table.
+<h4 heading><a name="Luan.ipairs" href="#Luan.ipairs"><code>Luan.ipairs (t)</code></a></h4>
+<p>
+Returns an iterator function
+so that the construction
+<pre>
+	for i,v in ipairs(t) do <em>body</em> end
+</pre>
+<p>
+will iterate over the key&ndash;value pairs
+(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
+up to the first nil value.
+<p>
+Could be defined as:
+<pre>
+	function Luan.ipairs(t)
+		local i = 0
+		return function()
+			if i < #t then
+				i = i + 1
+				return i, t[i]
+			end
+		end
+	end
+</pre>
+<h4 heading><a name="Luan.load" href="#Luan.load"><code>Luan.load (text, source_name [, env])</code></a></h4>
+<p>
+Loads a chunk.
+<p>
+The <code>text</code> is compiled.
+If there are no syntactic errors,
+returns the compiled chunk as a function;
+otherwise, throws an error.
+<p>
+The <code>source_name</code> parameter is a string saying where the text came from.  It is used to produce error messages.
+<p>
+If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk.
+<h4 heading><a name="Luan.load_file" href="#Luan.load_file"><code>Luan.load_file ([file_uri])</code></a></h4>
+<p>
+Similar to <a href="#Luan.load"><code>load</code></a>,
+but gets the chunk from file <code>file_uri</code>
+or from the standard input,
+if no file uri is given.
+<p>
+Could be defined as:
+<pre>
+	function Luan.load_file(file_uri)
+		file_uri = file_uri or "stdin:"
+		local f = Io.uri(file_uri)
+		if not f.exists() then
+			return nil
+		end
+		return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri )
+	end
+</pre>
+<h4 heading><a name="Luan.new_error" href="#Luan.new_error"><code>Luan.new_error (message)</code></a></h4>
+<p>
+Creates a new error table containing the message assigned to "<code>message</code>".  The error table also contains a <code>throw</code> function which throws the error.  The table also contains a list of stack trace elements where each stack trace element is a table containing "<code>source</code>", "<code>line</code>", and possible "<code>call_to</code>".  The table also has a metatable containing "<code>__to_string</code>" to render the error.
+<p>
+To print the current stack trace, you could do:
+<pre>
+	Io.print( Luan.new_error "stack" )
+</pre>
+<h4 heading><a name="Luan.pairs" href="#Luan.pairs"><code>Luan.pairs (t)</code></a></h4>
+<p>
+If <code>t</code> has a metamethod <code>__pairs</code>,
+calls it with <code>t</code> as argument and returns the
+result from the call.
+<p>
+Otherwise,
+returns a function
+so that the construction
+<pre>
+	for k,v in pairs(t) do <em>body</em> end
+</pre>
+<p>
+will iterate over all key&ndash;value pairs of table <code>t</code>.
+<h4 heading><a name="Luan.pcall" href="#Luan.pcall"><code>Luan.pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h4>
+<p>
+Calls function <code>f</code> with
+the given arguments in <em>protected mode</em>.
+This means that any error inside&nbsp;<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.
+<p>
+<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</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>.
+<h4 heading><a name="Luan.range" href="#Luan.range"><code>Luan.range (start, stop [, step])</code></a></h4>
+<p>
+Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers.
+<p>
+Example use:
+<pre>
+	for i in range(1,10) do
+		Io.print("count up:",i)
+	end
+	for i in range(10,0,-1) do
+		Io.print("count down:",i)
+	end
+</pre>
+<p>
+Could be defined as:
+<pre>
+	function Luan.range(start, stop, step)
+		step = step or 1
+		step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)"
+		local i = start
+		return function()
+			if step > 0 and i <= stop or step < 0 and i >= stop then
+				local rtn = i
+				i = i + step
+				return rtn
+			end
+		end
+	end
+</pre>
+<h4 heading><a name="Luan.raw_equal" href="#Luan.raw_equal"><code>Luan.raw_equal (v1, v2)</code></a></h4>
+<p>
+Checks whether <code>v1</code> is equal to <code>v2</code>,
+without invoking any metamethod.
+Returns a boolean.
+<h4 heading><a name="Luan.raw_get" href="#Luan.raw_get"><code>Luan.raw_get (table, index)</code></a></h4>
+<p>
+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.
+<h4 heading><a name="Luan.raw_len" href="#Luan.raw_len"><code>Luan.raw_len (v)</code></a></h4>
+<p>
+Returns the length of the object <code>v</code>,
+which must be a table or a string,
+without invoking any metamethod.
+Returns an integer.
+<h4 heading><a name="Luan.raw_set" href="#Luan.raw_set"><code>Luan.raw_set (table, index, value)</code></a></h4>
+<p>
+Sets the real value of <code>table[index]</code> to <code>value</code>,
+without invoking any metamethod.
+<code>table</code> must be a table,
+<code>index</code> any value different from <b>nil</b>,
+and <code>value</code> any Lua value.
+<h4 heading><a name="Luan.set_metatable" href="#Luan.set_metatable"><code>Luan.set_metatable (table, metatable)</code></a></h4>
+<p>
+Sets the metatable for the given table.
+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.
+<h4 heading><a name="Luan.stringify" href="#Luan.stringify"><code>Luan.stringify (v [,strict])</code></a></h4>
+<p>
+Receives a value of any type and converts it to a string that is a Luan expression.  <code>strict</code> is a string.  If <code>strict</code> is 'strict' then invalid types throw an error.  If <code>strict</code> is nil then invalid types are represented but the resulting expression is invalid.  <code>strict</code> defaults to <b>nil</b>.
+<h4 heading><a name="Luan.to_string" href="#Luan.to_string"><code>Luan.to_string (v)</code></a></h4>
+<p>
+Receives a value of any type and
+converts it to a string in a human-readable format.
+<p>
+If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
+then <code>to_string</code> calls the corresponding value
+with <code>v</code> as argument,
+and uses the result of the call as its result.
+<h4 heading><a name="Luan.try" href="#Luan.try"><code>Luan.try (t, &middot;&middot;&middot;)</code></a></h4>
+<p>
+Implements try-catch as found in other languages where each block is in table <code>t</code>.  <code>t[1]</code> is the "try" block.  The <code>t.catch</code> and <code>t.finally</code> blocks are optional.  Any extra arguments are passed to the "try" function.  Returns the result of the "try" block or the "catch" block.
+<p>
+Example use:
+<pre>
+try {
+	function()
+		a_dangerous_fn()
+	end
+	catch = function(e)
+		-- handle error
+	end
+	finally = function()
+		-- clean up
+	end
+}
+</pre>
+<p>
+Could be defined as:
+<pre>
+	function Luan.try(t)
+		local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) }
+		if r[1] then
+			Table.remove(r,1)
+		elseif t.catch ~= nil then
+			r = { t.catch(r[2]) }
+		else
+			t.finally and t.finally()
+			r[2].throw()
+		end
+		t.finally and t.finally()
+		return Table.unpack(r)
+	end
+</pre>
+<h4 heading><a name="Luan.type" href="#Luan.type"><code>Luan.type (v)</code></a></h4>
+<p>
+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>binary</code>",
+"<code>boolean</code>",
+"<code>table</code>",
+"<code>function</code>",
+and "<code>java</code>".
+<h4 heading><a name="Luan.values" href="#Luan.values"><code>Luan.values (&middot;&middot;&middot;)</code></a></h4>
+<p>
+Returns a function so that the construction
+<pre>
+	for i, v in Luan.values(&middot;&middot;&middot;) do <em>body</em> end
+</pre>
+<p>
+will iterate over all values of <code>&middot;&middot;&middot;</code>.
+<h4 heading><a name="Luan.VERSION" href="#Luan.VERSION"><code>Luan.VERSION</code></a></h4>
+<p>
+A global variable (not a function) that
+holds a string containing the current Luan version.
+<h3 heading><a name="package_lib">Modules</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Package = require "luan:Package.luan"
+</pre>
+<p>
+The package library provides basic
+facilities for loading modules in Luan.
+<h4 heading><a name="Package.load" href="#Package.load"><code>Package.load (mod_uri)</code></a></h4>
+<p>
+Loads the given module.
+The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table
+to determine whether <code>mod_uri</code> is already loaded.
+If it is, then <code>Package.load</code> returns the value stored
+at <code>Package.loaded[mod_uri]</code>.
+Otherwise, it tries to load a new value for the module.
+<p>
+To load a new value, <code>Package.load</code> first checks if <code>mod_uri</code> starts with "<b>java:</b>".  If yes, then this is a Java class which is loaded by special Java code.
+<p>
+Otherwise <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code>.  If the file doesn't exist, then <code>Package.load</code> returns <b>false</b>.  If the file exists, then its content is compiled into a chunk by calling <a href="#Luan.load"><code>Luan.load</code></a>.  This chunk is run passing in <code>mod_uri</code> as an argument.  The value returned by the chunk must not be <b>nil</b> and is loaded.
+<p>
+If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>.  The value is returned.
+<h4 heading><a name="Package.loaded" href="#Package.loaded"><code>Package.loaded</code></a></h4>
+<p>
+A table used by <a href="#Package.load"><code>Package.load</code></a> to control which
+modules are already loaded.
+When you load a module <code>mod_uri</code> and
+<code>Package.loaded[mod_uri]</code> is not <b>nil</b>,
+<a href="#Package.load"><code>Package.load</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="#Package.load"><code>Package.load</code></a>.
+<h3 heading><a name="string_lib">String Manipulation</a></h3>
+<p>
+Include this library by:
+<pre>
+	local String = require "luan:String.luan"
+</pre>
+<p>
+This library provides generic functions for string manipulation,
+such as finding and extracting substrings, and pattern matching.
+When indexing a string in Luan, the first character is at position&nbsp;1
+(not at&nbsp;0, as in Java).
+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.
+<h4 heading><a name="String.char" href="#String.char"><code>String.char (&middot;&middot;&middot;)</code></a></h4>
+<p>
+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.
+<h4 heading><a name="String.concat" href="#String.concat"><code>String.concat (&middot;&middot;&middot;)</code></a></h4>
+<p>
+Concatenates the <a href="#Luan.to_string"><code>to_string</code></a> value of all arguments.
+<h4 heading><a name="String.encode" href="#String.encode"><code>String.encode (s)</code></a></h4>
+<p>
+Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
+<h4 heading><a name="String.find" href="#String.find"><code>String.find (s, pattern [, init [, plain]])</code></a></h4>
+<p>
+Looks for the first match of
+<code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
+If it finds a match, then <code>find</code> returns the indices of&nbsp;<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&nbsp;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.
+<h4 heading><a name="String.format" href="#String.format"><code>String.format (formatstring, &middot;&middot;&middot;)</code></a></h4>
+<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 Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally.
+<p>
+Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number.
+<h4 heading><a name="String.gmatch" href="#String.gmatch"><code>String.gmatch (s, pattern)</code></a></h4>
+<p>
+Returns an iterator function that,
+each time it is called,
+returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>)
+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>
+	local s = "hello world from Lua"
+	for w in String.gmatch(s, [[\w+]]) do
+		print(w)
+	end
+</pre>
+<p>
+The next example collects all pairs <code>key=value</code> from the
+given string into a table:
+<pre>
+	local t = {}
+	local 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.
+<h4 heading><a name="String.gsub" href="#String.gsub"><code>String.gsub (s, pattern, repl [, n])</code></a></h4>
+<p>
+Returns a copy of <code>s</code>
+in which all (or the first <code>n</code>, if given)
+occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 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&nbsp;<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.
+<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 not <b>nil</b>,
+then it is used as the replacement string;
+otherwise, if it is <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")
+--&gt; x="hello hello world world"
+x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
+--&gt; x="hello hello world"
+x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
+--&gt; x="world hello Luan from"
+x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
+return load(s)()
+end)
+--&gt; x="4+5 = 9"
+local t = {name="lua", version="5.3"}
+x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
+--&gt; x="lua-5.3.tar.gz"
+</pre>
+<h4 heading><a name="String.literal" href="#String.literal"><code>String.literal (s)</code></a></h4>
+<p>
+Returns a string which matches the literal string <code>s</code> in a regular expression.  This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>.
+<h4 heading><a name="String.lower" href="#String.lower"><code>String.lower (s)</code></a></h4>
+<p>
+Receives a string and returns a copy of this string with all
+uppercase letters changed to lowercase.
+All other characters are left unchanged.
+<h4 heading><a name="String.match" href="#String.match"><code>String.match (s, pattern [, init])</code></a></h4>
+<p>
+Looks for the first <em>match</em> of
+<code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 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&nbsp;1 and can be negative.
+<h4 heading><a name="String.matches" href="#String.matches"><code>String.matches (s, pattern)</code></a></h4>
+<p>
+Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
+This function is equivalent to
+<pre>
+return String.match(s,pattern) ~= nil
+</pre>
+<h4 heading><a name="String.rep" href="#String.rep"><code>String.rep (s, n [, sep])</code></a></h4>
+<p>
+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).
+Returns the empty string if <code>n</code> is not positive.
+<h4 heading><a name="String.reverse" href="#String.reverse"><code>String.reverse (s)</code></a></h4>
+<p>
+Returns a string that is the string <code>s</code> reversed.
+<h4 heading><a name="String.split" href="#String.match"><code>String.split (s, pattern [, limit])</code></a></h4>
+<p>
+Splits <code>s</code> using regex <code>pattern</code> and returns the results.  If <code>limit</code> is positive, then only returns at most that many results.  If <code>limit</code> is zero, then remove trailing empty results.
+<h4 heading><a name="String.sub" href="#String.sub"><code>String.sub (s, i [, j])</code></a></h4>
+<p>
+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.
+<h4 heading><a name="String.to_binary" href="#String.to_binary"><code>String.to_binary (s)</code></a></h4>
+<p>
+Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>.
+<h4 heading><a name="String.to_number" href="#String.to_number"><code>String.to_number (s [, base])</code></a></h4>
+<p>
+When called with no <code>base</code>,
+<code>to_number</code> tries to convert its argument to a number.
+If the argument is
+a string convertible to a number,
+then <code>to_number</code> returns this number;
+otherwise, it returns <b>nil</b>.
+The conversion of strings can result in integers or floats.
+<p>
+When called with <code>base</code>,
+then <code>s</code> must be a string to be interpreted as
+an integer numeral in that base.
+In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
+represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
+with '<code>Z</code>' representing 35.
+If the string <code>s</code> is not a valid numeral in the given base,
+the function returns <b>nil</b>.
+<h4 heading><a name="String.trim" href="#String.trim"><code>String.trim (s)</code></a></h4>
+<p>
+Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>.
+<h4 heading><a name="String.unicode" href="#String.unicode"><code>String.unicode (s [, i [, j]])</code></a></h4>
+<p>
+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&nbsp;1;
+the default value for <code>j</code> is&nbsp;<code>i</code>.
+These indices are corrected
+following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+<h4 heading><a name="String.upper" href="#String.upper"><code>String.upper (s)</code></a></h4>
+<p>
+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 heading><a name="binary_lib">Binary Manipulation</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Binary = require "luan:Binary.luan"
+</pre>
+<h4 heading><a name="Binary.binary" href="#Binary.binary"><code>Binary.binary (&middot;&middot;&middot;)</code></a></h4>
+<p>
+Receives zero or more bytes (as integers).
+Returns a binary with length equal to the number of arguments,
+in which each byte has the internal numerical code equal
+to its corresponding argument.
+<h4 heading><a name="Binary.byte" href="#Binary.byte"><code>Binary.byte (b [, i [, j]])</code></a></h4>
+<p>
+Returns the internal numerical codes of the bytes <code>b[i]</code>,
+<code>b[i+1]</code>, ..., <code>b[j]</code>.
+The default value for <code>i</code> is&nbsp;1;
+the default value for <code>j</code> is&nbsp;<code>i</code>.
+These indices are corrected
+following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+<h4 heading><a name="Binary.to_string" href="#Binary.to_string"><code>Binary.to_string (b [,charset])</code></a></h4>
+<p>
+If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char.
+<h3 heading><a name="table_lib">Table Manipulation</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Table = require "luan:Table.luan"
+</pre>
+<p>
+This library provides generic functions for table manipulation.
+It provides all its functions inside the table <code>Table</code>.
+<h4 heading><a name="Table.clear" href="#Table.clear"><code>Table.clear (tbl)</code></a></h4>
+<p>
+Clears the table.
+<h4 heading><a name="Table.concat" href="#Table.concat"><code>Table.concat (list [, sep [, i [, j]]])</code></a></h4>
+<p>
+Given a list,
+returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; 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.
+<h4 heading><a name="Table.copy" href="#Table.copy"><code>Table.copy (tbl [, i [, j]])</code></a></h4>
+<p>
+If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
+Otherwise returns a new table which is a list of the elements <code>tbl[i] &middot;&middot;&middot; tbl[j]</code>.
+By default, <code>j</code> is <code>#tbl</code>.
+<h4 heading><a name="Table.insert" href="#Table.insert"><code>Table.insert (list, pos, value)</code></a></h4>
+<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], &middot;&middot;&middot;, list[#list]</code>.
+<h4 heading><a name="Table.is_empty" href="#Table.is_empty"><code>Table.is_empty (tbl)</code></a></h4>
+<h4 heading><a name="Table.pack" href="#Table.pack"><code>Table.pack (&middot;&middot;&middot;)</code></a></h4>
+<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.
+<h4 heading><a name="Table.remove" href="#Table.remove"><code>Table.remove (list, pos)</code></a></h4>
+<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], &middot;&middot;&middot;, 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>.
+<h4 heading><a name="Table.size" href="#Table.size"><code>Table.size (tbl)</code></a></h4>
+<h4 heading><a name="Table.sort" href="#Table.sort"><code>Table.sort (list [, comp])</code></a></h4>
+<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>&lt;</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.
+<h4 heading><a name="Table.unpack" href="#Table.unpack"><code>Table.unpack (list [, i [, j]])</code></a></h4>
+<p>
+Returns the elements from the given list.
+This function is equivalent to
+<pre>
+return list[i], list[i+1], &middot;&middot;&middot;, list[j]
+</pre>
+<p>
+By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
+<h3 heading><a name="number_lib">Number Manipulation</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Number = require "luan:Number.luan"
+</pre>
+<h4 heading><a name="Number.double" href="#Number.double"><code>Number.double (x)</code></a></h4>
+<p>
+Returns <code>x</code> as a double.
+<h4 heading><a name="Number.integer" href="#Number.integer"><code>Number.integer (x)</code></a></h4>
+<p>
+If the value <code>x</code> is convertible to an integer,
+returns that integer.
+Otherwise throws an error.
+<h4 heading><a name="Number.long" href="#Number.long"><code>Number.long (x)</code></a></h4>
+<p>
+If the value <code>x</code> is convertible to an long,
+returns that long.
+Otherwise throws an error.
+<h4 heading><a name="Number.long_to_string" href="#Number.long_to_string"><code>Number.long_to_string (i, radix)</code></a></h4>
+<p>
+Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>.
+<h4 heading><a name="Number.type" href="#Number.type"><code>Number.type (x)</code></a></h4>
+<p>
+Returns a string for the numeric type of <code>x</code>.  Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>".
+<h3 heading><a name="math_lib">Mathematical Functions</a></h3>
+<p>
+Include this library by:
+<pre>
+	local Math = require "luan:Math.luan"
+</pre>
+<p>
+This library provides basic mathematical functions.
+It provides all its functions and constants inside the table <code>Math</code>.
+<h4 heading><a name="Math.abs" href="#Math.abs"><code>Math.abs (x)</code></a></h4>
+<p>
+Returns the absolute value of <code>x</code>.
+<h4 heading><a name="Math.acos" href="#Math.acos"><code>Math.acos (x)</code></a></h4>
+<p>
+Returns the arc cosine of <code>x</code> (in radians).
+<h4 heading><a name="Math.asin" href="#Math.asin"><code>Math.asin (x)</code></a></h4>
+<p>
+Returns the arc sine of <code>x</code> (in radians).
+<h4 heading><a name="Math.atan" href="#Math.atan"><code>Math.atan (y, x)</code></a></h4>
+<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.)
+<h4 heading><a name="Math.ceil" href="#Math.ceil"><code>Math.ceil (x)</code></a></h4>
+<p>
+Returns the smallest integral value larger than or equal to <code>x</code>.
+<h4 heading><a name="Math.cos" href="#Math.cos"><code>Math.cos (x)</code></a></h4>
+<p>
+Returns the cosine of <code>x</code> (assumed to be in radians).
+<h4 heading><a name="Math.deg" href="#Math.deg"><code>Math.deg (x)</code></a></h4>
+<p>
+Converts the angle <code>x</code> from radians to degrees.
+<h4 heading><a name="Math.exp" href="#Math.exp"><code>Math.exp (x)</code></a></h4>
+<p>
+Returns the value <em>e<sup>x</sup></em>
+(where <code>e</code> is the base of natural logarithms).
+<h4 heading><a name="Math.floor" href="#Math.floor"><code>Math.floor (x)</code></a></h4>
+<p>
+Returns the largest integral value smaller than or equal to <code>x</code>.
+<h4 heading><a name="Math.fmod" href="#Math.fmod"><code>Math.fmod (x, y)</code></a></h4>
+<p>
+Returns the remainder of the division of <code>x</code> by <code>y</code>
+that rounds the quotient towards zero.
+<h4 heading><a name="Math.huge" href="#Math.huge"><code>Math.huge</code></a></h4>
+<p>
+A value larger than any other numerical value.
+<h4 heading><a name="Math.log" href="#Math.log"><code>Math.log (x [, base])</code></a></h4>
+<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>).
+<h4 heading><a name="Math.max" href="#Math.max"><code>Math.max (x, &middot;&middot;&middot;)</code></a></h4>
+<p>
+Returns the argument with the maximum value,
+according to the Lua operator <code>&lt;</code>.
+<h4 heading><a name="Math.max_integer" href="#Math.max_integer"><code>Math.max_integer</code></a></h4>
+<p>
+An integer with the maximum value for an integer.
+<h4 heading><a name="Math.min" href="#Math.min"><code>Math.min (x, &middot;&middot;&middot;)</code></a></h4>
+<p>
+Returns the argument with the minimum value,
+according to the Lua operator <code>&lt;</code>.
+<h4 heading><a name="Math.min_integer" href="#Math.min_integer"><code>Math.min_integer</code></a></h4>
+<p>
+An integer with the minimum value for an integer.
+<h4 heading><a name="Math.modf" href="#Math.modf"><code>Math.modf (x)</code></a></h4>
+<p>
+Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
+<h4 heading><a name="Math.pi" href="#Math.pi"><code>Math.pi</code></a></h4>
+<p>
+The value of <em>&pi;</em>.
+<h4 heading><a name="Math.rad" href="#Math.rad"><code>Math.rad (x)</code></a></h4>
+<p>
+Converts the angle <code>x</code> from degrees to radians.
+<h4 heading><a name="Math.random" href="#Math.random"><code>Math.random ([m [, n])</code></a></h4>
+<p>
+When called without arguments,
+returns a pseudo-random float with uniform distribution
+in the range  <em>[0,1)</em>.
+When called with two integers <code>m</code> and <code>n</code>,
+<code>Math.random</code> returns a pseudo-random integer
+with uniform distribution in the range <em>[m, n]</em>.
+(The value <em>m-n</em> cannot be negative and must fit in a Luan integer.)
+The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>.
+<p>
+This function is an interface to the underling
+pseudo-random generator function provided by Java.
+No guarantees can be given for its statistical properties.
+<h4 heading><a name="Math.sin" href="#Math.sin"><code>Math.sin (x)</code></a></h4>
+<p>
+Returns the sine of <code>x</code> (assumed to be in radians).
+<h4 heading><a name="Math.sqrt" href="#Math.sqrt"><code>Math.sqrt (x)</code></a></h4>
+<p>
+Returns the square root of <code>x</code>.
+(You can also use the expression <code>x^0.5</code> to compute this value.)
+<h4 heading><a name="Math.tan" href="#Math.tan"><code>Math.tan (x)</code></a></h4>
+<p>
+Returns the tangent of <code>x</code> (assumed to be in radians).
+<h2>6.8 &ndash; <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 handles;
+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 handles.
+<p>
+When using implicit file handles,
+all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
+When using explicit file handles,
+the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
+and then all operations are supplied as methods of the file handle.
+<p>
+The table <code>io</code> also provides
+three predefined file handles 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 &middot;&middot;&middot;])</code></a></h3>
+<p>
+Opens the given file name in read mode
+and returns an iterator function that
+works like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
+When the iterator function detects the end of file,
+it returns no values (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("*l")</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 (&middot;&middot;&middot;)</code></a></h3>
+<p>
+Equivalent to <code>io.input():read(&middot;&middot;&middot;)</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 (&middot;&middot;&middot;)</code></a></h3>
+<p>
+Equivalent to <code>io.output():write(&middot;&middot;&middot;)</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 (&middot;&middot;&middot;)</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 "<code>l</code>" 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 (&middot;&middot;&middot;)</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.
+(In this latter case,
+the function does not read subsequent formats.)
+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 numeral and returns it as a float or an integer,
+following the lexical conventions of Lua.
+(The numeral may have leading spaces and a sign.)
+This format always reads the longest input sequence that
+is a valid prefix for a number;
+if that prefix does not form a valid number
+(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
+it is discarded and the function returns <b>nil</b>.
+</li>
+<li><b>"<code>i</code>": </b>
+reads an integral number and returns it as an integer.
+</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 character (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 <code>number</code> is zero,
+it reads nothing and returns an empty string,
+or <b>nil</b> on end of file.
+</li>
+</ul><p>
+The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
+<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 (&middot;&middot;&middot;)</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 &ndash; <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&ndash;12), <code>day</code> (1&ndash;31),
+<code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
+<code>wday</code> (weekday, Sunday is&nbsp;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 ISO&nbsp;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&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
+<p>
+<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
+<p>
+Returns the difference, in seconds,
+from time <code>t1</code> to time <code>t2</code>
+(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
+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 ISO&nbsp;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 plus 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 ISO&nbsp;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&nbsp;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 &ndash; <a name="6.10">The Debug Library</a></h2>
+<p>
+This library provides
+the functionality of the debug interface (<a href="#4.9">&sect;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&nbsp;0 is the current function (<code>getinfo</code> itself);
+level&nbsp;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&nbsp;1, and so on,
+following the order that they are declared in the code,
+counting only the variables that are active
+in the current scope of the function.
+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 variables with no known names
+(internal variables such as loop control variables,
+and variables from chunks saved without debug information).
+<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">&sect;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>
+Variable names starting with '<code>(</code>' (open parenthesis)
+represent variables with no known names
+(variables from chunks saved without debug information).
+<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 any combination of 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>
+Moreover,
+with a <code>count</code> different from zero,
+the hook is called also 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&nbsp;2 to get more information about
+the running function
+(level&nbsp;0 is the <code>getinfo</code> function,
+and level&nbsp;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>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.
+The 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 a 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 &ndash; <a name="7">Lua Standalone</a></h1>
+<p>
+Although Lua has been designed as an extension language,
+to be embedded in a host C&nbsp;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>.
+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_3"><code>LUA_INIT_5_3</code></a>
+(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
+before running any argument.
+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 running any code,
+<code>lua</code> collects all command-line arguments
+in a global table called <code>arg</code>.
+The script name goes to 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 its options)
+go to negative indices.
+For instance, in the call
+<pre>
+$ lua -la b.lua t1 t2
+</pre><p>
+the table is like this:
+<pre>
+arg = { [-2] = "lua", [-1] = "-la",
+[0] = "b.lua",
+[1] = "t1", [2] = "t2" }
+</pre><p>
+If there is no script in the call,
+the interpreter name goes to index 0,
+followed by the other arguments.
+For instance, the call
+<pre>
+$ lua -e "print(arg[1])"
+</pre><p>
+will print "<code>-e</code>".
+If there is a script,
+the script is called with parameters
+<code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
+(Like all chunks in Lua,
+the script is compiled as a vararg function.)
+<p>
+In interactive mode,
+Lua repeatedly prompts and waits for a line.
+After reading a line,
+Lua first try to interpret the line as an expression.
+If it succeeds, it prints its value.
+Otherwise, it interprets the line as a statement.
+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 not a string but
+has a metamethod <code>__to_string</code>,
+the interpreter calls this metamethod to produce the final message.
+Otherwise, the interpreter converts the error object to a string
+and adds a stack traceback to it.
+<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&nbsp;<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 &ndash; <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&nbsp;5.2 to Lua&nbsp;5.3.
+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 future.
+<p>
+Lua versions can always change the C API in ways that
+do not imply source-code changes in a program,
+such as the numeric values for constants
+or the implementation of functions as macros.
+Therefore,
+you should not assume that binaries are compatible between
+different Lua versions.
+Always recompile clients of the Lua API when
+using a new version.
+<p>
+Similarly, Lua versions can always change the internal representation
+of precompiled chunks;
+precompiled chunks are not compatible between different Lua versions.
+<p>
+The standard paths in the official distribution may
+change between versions.
+<h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
+<ul>
+<li>
+The main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
+introduction of an integer subtype for numbers.
+Although this change should not affect "normal" computations,
+some computations
+(mainly those that involve some kind of overflow)
+can give different results.
+<p>
+You can fix these differences by forcing a number to be a float
+(in Lua&nbsp;5.2 all numbers were float),
+in particular writing constants with an ending <code>.0</code>
+or using <code>x = x + 0.0</code> to convert a variable.
+(This recommendation is only for a quick fix
+for an occasional incompatibility;
+it is not a general guideline for good programming.
+For good programming,
+use floats where you need floats
+and integers where you need integers.)
+</li>
+<li>
+The conversion of a float to a string now adds a <code>.0</code> suffix
+to the result if it looks like an integer.
+(For instance, the float 2.0 will be printed as <code>2.0</code>,
+not as <code>2</code>.)
+You should always use an explicit format
+when you need a specific format for numbers.
+<p>
+(Formally this is not an incompatibility,
+because Lua does not specify how numbers are formatted as strings,
+but some programs assumed a specific format.)
+</li>
+<li>
+The generational mode for the garbage collector was removed.
+(It was an experimental feature in Lua&nbsp;5.2.)
+</li>
+</ul>
+<h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
+<ul>
+<li>
+The <code>bit32</code> library has been deprecated.
+It is easy to require a compatible external library or,
+better yet, to replace its functions with appropriate bitwise operations.
+(Keep in mind that <code>bit32</code> operates on 32-bit integers,
+while the bitwise operators in standard Lua operate on 64-bit integers.)
+</li>
+<li>
+The Table library now respects metamethods
+for setting and getting elements.
+</li>
+<li>
+The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
+its <code>__ipairs</code> metamethod has been deprecated.
+</li>
+<li>
+Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
+For compatibility, Lua will continue to ignore this character.
+</li>
+<li>
+The following functions were deprecated in the mathematical library:
+<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
+<code>frexp</code>, and <code>ldexp</code>.
+You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
+you can replace <code>math.atan2</code> with <code>math.atan</code>,
+which now accepts one or two parameters;
+you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
+For the other operations,
+you can either use an external library or
+implement them in Lua.
+</li>
+<li>
+The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
+changed the way it handles versioned names.
+Now, the version should come after the module name
+(as is usual in most other tools).
+For compatibility, that searcher still tries the old format
+if it cannot find an open function according to the new style.
+(Lua&nbsp;5.2 already worked that way,
+but it did not document the change.)
+</li>
+</ul>
+<h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
+<ul>
+<li>
+Continuation functions now receive as parameters what they needed
+to get through <code>lua_getctx</code>,
+so <code>lua_getctx</code> has been removed.
+Adapt your code accordingly.
+</li>
+<li>
+Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
+Use 0 as the value of this parameter to get the old behavior.
+</li>
+<li>
+Functions to inject/project unsigned integers
+(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
+<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
+were deprecated.
+Use their signed equivalents with a type cast.
+</li>
+<li>
+Macros to project non-default integer types
+(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
+were deprecated.
+Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
+(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
+</li>
+</ul>
+<h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
+<p>
+Here is the complete syntax of Lua in extended BNF.
+As usual in extended BNF,
+{A} means 0 or more As,
+and [A] means an optional A.
+(For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
+for a description of the terminals
+Name, Numeral,
+and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
+<pre>
+	chunk ::= block
+	block ::= {stat} [retstat]
+	stat ::=  &lsquo;<b>;</b>&rsquo; |
+		 varlist &lsquo;<b>=</b>&rsquo; 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 &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; 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 [&lsquo;<b>=</b>&rsquo; explist]
+	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
+	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
+	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
+	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
+	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
+	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
+	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
+	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
+		 prefixexp | tableconstructor | exp binop exp | unop exp
+	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
+	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
+	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
+	functiondef ::= <b>function</b> funcbody
+	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
+	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
+	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
+	fieldlist ::= field {fieldsep field} [fieldsep]
+	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
+	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
+	binop ::=  &lsquo;<b>+</b>&rsquo; | &lsquo;<b>-</b>&rsquo; | &lsquo;<b>*</b>&rsquo; | &lsquo;<b>/</b>&rsquo; | &lsquo;<b>//</b>&rsquo; | &lsquo;<b>^</b>&rsquo; | &lsquo;<b>%</b>&rsquo; |
+		 &lsquo;<b>&amp;</b>&rsquo; | &lsquo;<b>~</b>&rsquo; | &lsquo;<b>|</b>&rsquo; | &lsquo;<b>&gt;&gt;</b>&rsquo; | &lsquo;<b>&lt;&lt;</b>&rsquo; | &lsquo;<b>..</b>&rsquo; |
+		 &lsquo;<b>&lt;</b>&rsquo; | &lsquo;<b>&lt;=</b>&rsquo; | &lsquo;<b>&gt;</b>&rsquo; | &lsquo;<b>&gt;=</b>&rsquo; | &lsquo;<b>==</b>&rsquo; | &lsquo;<b>~=</b>&rsquo; |
+		 <b>and</b> | <b>or</b>
+	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
+</pre>
+<p>
+<HR>
+<SMALL CLASS="footer">
+Last update:
+Fri Jan 16 00:58:20 BRST 2015
+</SMALL>
+<!--
+Last change: minor edit
+-->
+</body>
+</html>

Mercurial Hosting > luan

comparison website/src/manual.html @ 1325:28c1fc6d9d29