Mercurial Hosting > luan
changeset 1656:540bf2343078
manual work
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Tue, 05 Apr 2022 21:50:24 -0600 |
| parents | de8e25c6d177 |
| children | 58d35500fdb3 |
| files | website/src/m.html.luan website/src/manual_old.html.luan |
| diffstat | 2 files changed, 5448 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/website/src/m.html.luan Tue Apr 05 21:50:24 2022 -0600 @@ -0,0 +1,968 @@ +local Luan = require "luan:Luan.luan" +local error = Luan.error +local Io = require "luan:Io.luan" +local Http = require "luan:http/Http.luan" +local Shared = require "site:/lib/Shared.luan" +local head = Shared.head or error() +local docs_header = Shared.docs_header or error() +local show_toc = Shared.show_toc or error() +local show_content = Shared.show_content or error() + + +local content = { + intro = { + title = "Introduction" + content = function() +%> +<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 features to Luan, but rather by providing a complete set of libraries. +</p> +<% + end + } + basic = { + title = "Basic Concepts" + content = function() +%> +<p> +This section describes the basic concepts of the language. +</p> +<% + end + subs = { + types = { + title = "Values and Types" + content = function() +%> +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<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> + +<p> +The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type +of a given value. +</p> +<% + end + } + env = { + title = "Environments" + content = function() +%> +<p> +The environment of a chunk starts with only one local variable: <code><a href="#require">require</a></code>. This function is 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> + +<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. +</p> +<% + end + } + error = { + title = "Error Handling" + content = function() +%> +<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 the <a href="#try">Try Statement</code></a>. +</p> + +<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>. +</p> +<% + end + } + meta = { + title = "Metatables and Metamethods" + content = function() +%> +<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> + +<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> + +<p> +You can query the metatable of any table +using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function. +</p> + +<p> +You can replace the metatable of tables +using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function. +</p> + +<p> +A metatable controls how a table behaves in +arithmetic operations, bitwise operations, +order comparisons, concatenation, length operation, calls, and indexing. +</p> + +<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: +</p> + +<pre> + raw_get(get_metatable(obj) or {}, "__" .. event_name) +</pre> + +<p> +Here are the events: +</p> + +<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. +</p></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. +</p></li> + +<li><p> +<b>"div": </b> +the <code>/</code> operation. +Behavior similar to the "add" operation. +</p></li> + +<li><p> +<b>"mod": </b> +the <code>%</code> operation. +Behavior similar to the "add" operation. +</p></li> + +<li><p> +<b>"pow": </b> +the <code>^</code> (exponentiation) operation. +Behavior similar to the "add" operation. +</p></li> + +<li><p> +<b>"unm": </b> +the <code>-</code> (unary minus) operation. +Behavior similar to the "add" operation. +</p></li> + +<li><p> +<b>"concat": </b> +the <code>..</code> (concatenation) operation. +Behavior similar to the "add" operation. +</p></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. +</p></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. +</p></li> + +<li><p> +<b>"lt": </b> +the <code><</code> (less than) operation. +Behavior similar to the "add" operation. +The result of the call is always converted to a boolean. +</p></li> + +<li><p> +<b>"le": </b> +the <code><=</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 <= b</code> is equivalent to <code>not (b < a)</code>. +As with the other comparison operators, +the result is always a boolean. +</p></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> + +<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.) +</p> +</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> + +<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> + +<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.) +</p> +</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. +</p></li> + +</ul> +<% + end + } + gc = { + title = "Garbage Collection" + content = function() +%> +<p> +Luan uses Java's garbage collection. +</p> +<% + end + } + } + } + lang = { + title = "The Language" + content = function() +%> +<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> + +<p> +Language constructs will be explained using the usual extended BNF notation, +in which +{<em>a</em>} means 0 or more <em>a</em>'s, and +[<em>a</em>] means an optional <em>a</em>. +Non-terminals are shown like non-terminal, +keywords are shown like <b>kword</b>, +and other terminal symbols are shown like ‘<b>=</b>’. +The complete syntax of Luan can be found in <a href="#9">§9</a> +at the end of this manual. +</p> +<% + end + subs = { + lex = { + title = "Lexical Conventions" + content = function() +%> +<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> + +<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> + +<p> +The following <em>keywords</em> are reserved +and cannot be used as names: +</p> + +<p keywords> + <span>and</span> + <span>break</span> + <span>catch</span> + <span>continue</span> + <span>do</span> + <span>else</span> + <span>elseif</span> + <span>end_do</span> + <span>end_for</span> + <span>end_function</span> + <span>end_if</span> + <span>end_try</span> + <span>end_while</span> + <span>false</span> + <span>finally</span> + <span>for</span> + <span>function</span> + <span>if</span> + <span>in</span> + <span>local</span> + <span>nil</span> + <span>not</span> + <span>or</span> + <span>repeat</span> + <span>return</span> + <span>then</span> + <span>true</span> + <span>try</span> + <span>until</span> + <span>while</span> +</p> + +<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> + +<p> +The following strings denote other tokens: +</p> + +<pre> + + - * / % ^ # + & ~ | << >> // + == ~= <= >= < > = + ( ) { } [ ] :: + ; : , . .. ... +</pre> + +<p> +<em>Literal strings</em> +can be delimited by matching single or double quotes, +and can contain the following C-like escape sequences: +'<code>\a</code>' (bell), +'<code>\b</code>' (backspace), +'<code>\f</code>' (form feed), +'<code>\n</code>' (newline), +'<code>\r</code>' (carriage return), +'<code>\t</code>' (horizontal tab), +'<code>\v</code>' (vertical tab), +'<code>\\</code>' (backslash), +'<code>\"</code>' (quotation mark [double quote]), +and '<code>\'</code>' (apostrophe [single quote]). +A backslash followed by a real newline +results in a newline in the string. +The escape sequence '<code>\z</code>' skips the following span +of white-space characters, +including line breaks; +it is particularly useful to break and indent a long literal string +into multiple lines without adding the newlines and spaces +into the string contents. +</p> + +<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> + +<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> + +<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> + +<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: +</p> + +<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 +</p> + +<pre> + 3 345 0xff 0xBEBADA +</pre> + +<p> +Examples of valid float constants are +</p> + +<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. +</p> +<% + end + } + vars = { + title = "Variables" + content = function() +%> +<p> +Variables are places that store values. +There are three kinds of variables in Luan: +global variables, local variables, and table fields. +</p> + +<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): +</p> + +<pre> + var ::= Name +</pre> + +<p> +Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. +</p> + +<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> + +<p> +Before the first assignment to a variable, its value is <b>nil</b>. +</p> + +<p> +Square brackets are used to index a table: +</p> + +<pre> + var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ +</pre> + +<p> +The meaning of accesses to table fields can be changed via metatables. +An access to an indexed variable <code>t[i]</code> is equivalent to +a call <code>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> + +<p> +The syntax <code>var.Name</code> is just syntactic sugar for +<code>var["Name"]</code>: +</p> + +<pre> + var ::= prefixexp ‘<b>.</b>’ 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>). +</p> +<% + end + } + stmt = { + title = "Statements" + content = function() +%> +<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. +</p> +<% + end + subs = { + blocks = { + title = "Blocks" + content = function() +%> +<p> +A block is a list of statements, +which are executed sequentially: +</p> + +<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: +</p> + +<pre> + stat ::= ‘<b>;</b>’ +</pre> + +<p> +A block can be explicitly delimited to produce a single statement: +</p> + +<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>). +</p> +<% + end + } + chunks = { + title = "Chunks" + content = function() +%> +<p> +The unit of compilation of Luan is called a <em>chunk</em>. +Syntactically, +a chunk is simply a block: +</p> + +<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> + +<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. +</p> +<% + end + } + assignment = { + title = "Assignment" + content = function() +%> +<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: +</p> + +<pre> + stat ::= varlist ‘<b>=</b>’ explist + varlist ::= var {‘<b>,</b>’ var} + explist ::= exp {‘<b>,</b>’ exp} +</pre> + +<p> +Expressions are discussed in <a href="#expressions">Expressions</a>. +</p> + +<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> + +<p> +The assignment statement first evaluates all its expressions +and only then the assignments are performed. +Thus the code +</p> + +<pre> + i = 3 + i, a[i] = i+1, 20 +</pre> + +<p> +sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> +because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) +before it is assigned 4. +Similarly, the line +</p> + +<pre> + x, y = y, x +</pre> + +<p> +exchanges the values of <code>x</code> and <code>y</code>, +and +</p> + +<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> + +<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> + +<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. +</p> +<% + end + } + } + } + } + } +} + + +return function() + Io.stdout = Http.response.text_writer() +%> +<!doctype html> +<html> + <head> +<% head() %> + <title>Luan Reference Manual</title> + <style> + p[keywords] { + font-family: monospace; + margin-left: 40px; + max-width: 700px; + } + p[keywords] span { + display: inline-block; + width: 100px; + } + </style> + </head> + <body> +<% docs_header() %> + <div content> + <h1><a href="manual.html">Luan Reference Manual</a></h1> + <p small> + Original copyright © 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 toc> +<% show_toc(content) %> + </div> + <hr> +<% show_content(content,2) %> + </div> + </body> +</html> +<% +end
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/website/src/manual_old.html.luan Tue Apr 05 21:50:24 2022 -0600 @@ -0,0 +1,4480 @@ +local Luan = require "luan:Luan.luan" +local error = Luan.error +local Io = require "luan:Io.luan" +local Http = require "luan:http/Http.luan" +local Shared = require "site:/lib/Shared.luan" +local head = Shared.head or error() +local docs_header = Shared.docs_header or error() + + +return function() + Io.stdout = Http.response.text_writer() +%> +<!doctype html> +<html> + <head> +<% head() %> + <title>Luan Reference Manual</title> + <style> + div[contents] { + margin-bottom: 1em; + } + ul { + margin: 0; + } + [heading] { + margin-top: 2em; + } + p[keywords] { + font-family: monospace; + margin-left: 40px; + max-width: 700px; + } + p[keywords] span { + display: inline-block; + width: 100px; + } + </style> + </head> + <body> +<% docs_header() %> + <div content> + +<h1><a href="manual.html">Luan Reference Manual</a></h1> + +<p small> +Original copyright © 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="#try">Try 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> + </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" href="#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" href="#basic">Basic Concepts</a></h2> + +<p>This section describes the basic concepts of the language.</p> + +<h3 heading><a name="types" href="#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" href="#env">Environments</a></h3> + +<p> +The environment of a chunk starts with only one local variable: <code><a href="#require">require</a></code>. This function is 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" href="#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 the <a href="#try">Try Statement</code></a>. + + +<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" href="#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><</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><=</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 <= b</code> is equivalent to <code>not (b < 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" href="#gc">Garbage Collection</a></h3> + +<p> +Luan uses Java's garbage collection. + + + + + +<h2 heading><a name="lang" href="#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>} means 0 or more <em>a</em>'s, and +[<em>a</em>] means an optional <em>a</em>. +Non-terminals are shown like non-terminal, +keywords are shown like <b>kword</b>, +and other terminal symbols are shown like ‘<b>=</b>’. +The complete syntax of Luan can be found in <a href="#9">§9</a> +at the end of this manual. + + + +<h3 heading><a name="lex" href="#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: + + +<p keywords> + <span>and</span> + <span>break</span> + <span>catch</span> + <span>continue</span> + <span>do</span> + <span>else</span> + <span>elseif</span> + <span>end_do</span> + <span>end_for</span> + <span>end_function</span> + <span>end_if</span> + <span>end_try</span> + <span>end_while</span> + <span>false</span> + <span>finally</span> + <span>for</span> + <span>function</span> + <span>if</span> + <span>in</span> + <span>local</span> + <span>nil</span> + <span>not</span> + <span>or</span> + <span>repeat</span> + <span>return</span> + <span>then</span> + <span>true</span> + <span>try</span> + <span>until</span> + <span>while</span> +</p> + +<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> + + - * / % ^ # + & ~ | << >> // + == ~= <= >= < > = + ( ) { } [ ] :: + ; : , . .. ... +</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" href="#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 ‘<b>[</b>’ exp ‘<b>]</b>’ +</pre> + +<p> +The meaning of accesses to table fields can be changed via metatables. +An access to an indexed variable <code>t[i]</code> is equivalent to +a call <code>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 ‘<b>.</b>’ 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" href="#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" href="#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 ::= ‘<b>;</b>’ +</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" href="#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" href="#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 ‘<b>=</b>’ explist + varlist ::= var {‘<b>,</b>’ var} + explist ::= exp {‘<b>,</b>’ 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 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" href="#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>–<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>continue</b> statement jumps to the beginning of a +<b>while</b>, <b>repeat</b>, or <b>for</b> loop for next iteration, +skipping the execution of statements inside the body of loop for the current iteration: + +<pre> + stat ::= <b>continue</b> +</pre> + + +<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] [‘<b>;</b>’] +</pre> + + + + +<h4 heading><a name="for" href="#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 {‘<b>,</b>’ Name} + end_for ::= <b>end_for</b> | <b>end</b> +</pre> + +<p> +A <b>for</b> statement like + +<pre> + for <em>var_1</em>, ···, <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>, ···, <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="try" href="#for">Try Statement</a></h4> + +<p>The <b>try</b> statement has the same semantics as in Java.</p> + +<pre> + stat ::= <b>try</b> block [<b>catch</b> Name block] [<b>finally</b> block] end_try + end_try ::= <b>end_try</b> | <b>end</b> +</pre> + + + + +<h4 heading><a name="fn_stmt" href="#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" href="#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 [‘<b>=</b>’ 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" href="#template_stmt">Template Statements</a></h4> + +<p>Template statements provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write 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 , "!\nBye ", name , ".\n" ) +</pre> + + + +<h3 heading><a name="expressions" href="#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 ::= ‘<b>...</b>’ + exp ::= exp binop exp + exp ::= unop exp + prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ +</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" href="#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" href="#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" href="#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><</code>: </b>less than</li> +<li><b><code>></code>: </b>greater than</li> +<li><b><code><=</code>: </b>less or equal</li> +<li><b><code>>=</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 > b</code> is translated to <code>b < a</code> +and <code>a >= b</code> is translated to <code>b <= a</code>. + + + + + +<h4 heading><a name="logical_ops" href="#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 --> 10 + 10 or error() --> 10 + nil or "a" --> "a" + nil and 10 --> nil + false and error() --> false + false and nil --> false + false or nil --> nil + 10 and 20 --> 20 +</pre> + +<p> +(In this manual, +<code>--></code> indicates the result of the preceding expression.) + + + +<h4 heading><a name="concatenation" href="#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" href="#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" href="#precedence">Precedence</a></h4> + +<p> +Operator precedence in Luan follows the table below, +from lower to higher priority: + +<pre> + or + and + < > <= >= ~= == + .. + + - + * / % + 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" href="#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 ::= ‘<b>{</b>’ fieldlist ‘<b>}</b>’ + fieldlist ::= [field] {fieldsep [field]} + field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp + fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ | <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" href="#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 ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ + 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" href="#fn_def">Function Definitions</a></h4> + +<p> +The syntax for function definition is + +<pre> + functiondef ::= <b>function</b> funcbody + funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ 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 {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] +</pre> + +<p> +The statement + +<pre> + function f () <em>body</em> end +</pre> + +<p> +translates to + +<pre> + f = function () <em>body</em> end +</pre> + +<p> +The statement + +<pre> + function t.a.b.c.f () <em>body</em> end +</pre> + +<p> +translates to + +<pre> + t.a.b.c.f = function () <em>body</em> end +</pre> + +<p> +The statement + +<pre> + local function f () <em>body</em> end +</pre> + +<p> +translates to + +<pre> + local f; f = function () <em>body</em> end +</pre> + +<p> +not to + +<pre> + local f = function () <em>body</em> end +</pre> + +<p> +(This only makes a difference when the body of the function +contains references to <code>f</code>.) + + +<p> +A function definition is an executable expression, +whose value has type <em>function</em>. +When Luan precompiles a chunk, +all its function bodies are precompiled too. +Then, whenever Luan executes the function definition, +the function is <em>instantiated</em> (or <em>closed</em>). +This function instance (or <em>closure</em>) +is the final value of the expression. + + +<p> +Parameters act as local variables that are +initialized with the argument values: + +<pre> + parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ +</pre> + +<p> +When a function is called, +the list of arguments is adjusted to +the length of the list of parameters 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, ... --> (nothing) + g(3, 4) a=3, b=4, ... --> (nothing) + g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 + g(5, r()) a=5, b=1, ... --> 2 3 +</pre> + +<p> +Results are returned using the <b>return</b> statement (see <a href="#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. + + +<h3 heading><a name="visibility" href="#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) --> 10 + x = x+1 + do -- another block + local x = x+1 -- another 'x' + print(x) --> 12 + end + print(x) --> 11 + end + print(x) --> 10 (the global one) +</pre> + +<p> +Notice that, in a declaration like <code>local x = x</code>, +the new <code>x</code> being declared is not in scope yet, +and so the second <code>x</code> refers to the outside variable. + + +<p> +Because of the lexical scoping rules, +local variables can be freely accessed by functions +defined inside their scope. +A local variable used by an inner function is called +an <em>upvalue</em>, or <em>external local variable</em>, +inside the inner function. + + +<p> +Notice that each execution of a <b>local</b> statement +defines new local variables. +Consider the following example: + +<pre> + a = {} + local x = 20 + for i=1,10 do + local y = 0 + a[i] = function () y=y+1; return x+y end + end +</pre> + +<p> +The loop creates ten closures +(that is, ten instances of the anonymous function). +Each of these closures uses a different <code>y</code> variable, +while all of them share the same <code>x</code>. + + + + + +<h2 heading><a name="libs" href="#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" href="#default_lib">Default Environment</a></h3> + +<p> +This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>. + + +<h4 heading><a name="require" href="#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> + +<p> +A special case is: + +<pre> + require "java" +</pre> + +<p> +This 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. + + +<h3 heading><a name="luan_lib" href="#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 [, env]])</code></a></h4> + +<p> +Evaluates <code>text</code> as a Luan expression. + +<p> +Could be defined as: + +<pre> + function Luan.eval(text,source_name, env) + return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )() + 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.hash_code" href="#Luan.ipairs"><code>Luan.hash_code (v)</code></a></h4> + +<p> +Returns the hash code of <code>v</code>. + + +<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–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 [, persist]]])</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. Defaults to "load". + +<p> +If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. + +<p> +The <code>persist</code> parameter is a boolean which determines if the compiled code is persistently cached to a temporary file. Defaults to <code>false</code>. + + +<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>. +<code>file_uri</code> can be a string or a uri table. + + +<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–value pairs of table <code>t</code>. + + + +<p> +<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> +Receives any number of arguments +and prints their values to <code>stdout</code>, +using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. +<code>print</code> is not intended for formatted output, +but only as a quick way to show a value, +for instance for debugging. +For complete control over the output, +use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. + + + +<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 [,options])</code></a></h4> + +<p> +Receives a value of any type and converts it to a string that is a Luan expression. <code>options</code> is a table. If <code>options.strict==true</code> then invalid types throw an error. Otherwise invalid types are represented but the resulting expression is invalid. If <code>options.number_types==true</code> then numbers will be wrapped in functions for their type. + + +<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.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 (···)</code></a></h4> + +<p> +Returns a function so that the construction + +<pre> + for i, v in Luan.values(···) do <em>body</em> end +</pre> + +<p> +will iterate over all values of <code>···</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" href="#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" href="#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 1 +(not at 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 (···)</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.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 <code>s</code> +where this occurrence starts and ends; +otherwise, it returns <b>nil</b>. +A third, optional numerical argument <code>init</code> specifies +where to start the search; +its default value is 1 and can be negative. +A value of <b>true</b> as a fourth, optional argument <code>plain</code> +turns off the pattern matching facilities, +so the function does a plain "find substring" operation, +with no characters in <code>pattern</code> being considered magic. +Note that if <code>plain</code> is given, then <code>init</code> must be given as well. + +<p> +If the pattern has captures, +then in a successful match +the captured values are also returned, +after the two indices. + + + + +<h4 heading><a name="String.format" href="#String.format"><code>String.format (formatstring, ···)</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 <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") + --> x="hello hello world world" + + x = String.gsub("hello world", [[\w+]], "$0 $0", 1) + --> x="hello hello world" + + x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1") + --> x="world hello Luan from" + + x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s) + return load(s)() + end) + --> x="4+5 = 9" + + local t = {name="lua", version="5.3"} + x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) + --> x="lua-5.3.tar.gz" +</pre> + + +<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 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.regex_quote" href="#String.regex_quote"><code>String.regex_quote (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.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 10, the letter '<code>A</code>' (in either upper or lower case) +represents 10, '<code>B</code>' represents 11, and so forth, +with '<code>Z</code>' representing 35. +If the string <code>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 1; +the default value for <code>j</code> is <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" href="#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 (···)</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 1; +the default value for <code>j</code> is <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" href="#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] ··· 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] ··· 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], ···, 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 (···)</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], ···, 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><</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], ···, 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" href="#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.float" href="#Number.double"><code>Number.float (x)</code></a></h4> +<p> +Returns <code>x</code> as a float. + + +<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" href="#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, ···)</code></a></h4> + +<p> +Returns the argument with the maximum value, +according to the Lua operator <code><</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, ···)</code></a></h4> + +<p> +Returns the argument with the minimum value, +according to the Lua operator <code><</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>π</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 – <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 ···])</code></a></h3> + + +<p> +Opens the given file name in read mode +and returns an iterator function that +works like <code>file:lines(···)</code> over the opened file. +When the iterator function detects the end of file, +it returns 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 (···)</code></a></h3> + + +<p> +Equivalent to <code>io.input():read(···)</code>. + + + + +<p> +<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> + + +<p> +Returns a handle for a temporary file. +This file is opened in update mode +and it is automatically removed when the program ends. + + + + +<p> +<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> + + +<p> +Checks whether <code>obj</code> is a valid file handle. +Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, +<code>"closed file"</code> if <code>obj</code> is a closed file handle, +or <b>nil</b> if <code>obj</code> is not a file handle. + + + + +<p> +<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> + + +<p> +Equivalent to <code>io.output():write(···)</code>. + + + + +<p> +<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> + + +<p> +Closes <code>file</code>. +Note that files are automatically closed when +their handles are garbage collected, +but that takes an unpredictable amount of time to happen. + + +<p> +When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, +<a href="#pdf-file:close"><code>file:close</code></a> returns the same values +returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. + + + + +<p> +<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> + + +<p> +Saves any written data to <code>file</code>. + + + + +<p> +<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> + + +<p> +Returns an iterator function that, +each time it is called, +reads the file according to the given formats. +When no format is given, +uses "<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 (···)</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 (···)</code></a></h3> + + +<p> +Writes the value of each of its arguments to <code>file</code>. +The arguments must be strings or numbers. + + +<p> +In case of success, this function returns <code>file</code>. +Otherwise it returns <b>nil</b> plus a string describing the error. + + + + + + + +<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> + +<p> +This library is implemented through table <a name="pdf-os"><code>os</code></a>. + + +<p> +<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> + + +<p> +Returns an approximation of the amount in seconds of CPU time +used by the program. + + + + +<p> +<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> + + +<p> +Returns a string or a table containing date and time, +formatted according to the given string <code>format</code>. + + +<p> +If the <code>time</code> argument is present, +this is the time to be formatted +(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). +Otherwise, <code>date</code> formats the current time. + + +<p> +If <code>format</code> starts with '<code>!</code>', +then the date is formatted in Coordinated Universal Time. +After this optional character, +if <code>format</code> is the string "<code>*t</code>", +then <code>date</code> returns a table with the following fields: +<code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31), +<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), +<code>wday</code> (weekday, Sunday is 1), +<code>yday</code> (day of the year), +and <code>isdst</code> (daylight saving flag, a boolean). +This last field may be absent +if the information is not available. + + +<p> +If <code>format</code> is not "<code>*t</code>", +then <code>date</code> returns the date as a string, +formatted according to the same rules as the ISO C function <code>strftime</code>. + + +<p> +When called without arguments, +<code>date</code> returns a reasonable date and time representation that depends on +the host system and on the current locale +(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). + + +<p> +On non-POSIX systems, +this function may be not thread safe +because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. + + + + +<p> +<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> + + +<p> +Returns the 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 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 C function <code>exit</code> to terminate the host program. +If <code>code</code> is <b>true</b>, +the returned status is <code>EXIT_SUCCESS</code>; +if <code>code</code> is <b>false</b>, +the returned status is <code>EXIT_FAILURE</code>; +if <code>code</code> is a number, +the returned status is this number. +The default value for <code>code</code> is <b>true</b>. + + +<p> +If the optional second argument <code>close</code> is true, +closes the Lua state before exiting. + + + + +<p> +<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> + + +<p> +Returns the value of the process environment variable <code>varname</code>, +or <b>nil</b> if the variable is not defined. + + + + +<p> +<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> + + +<p> +Deletes the file (or empty directory, on POSIX systems) +with the given name. +If this function fails, it returns <b>nil</b>, +plus a string describing the error and the error code. + + + + +<p> +<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> + + +<p> +Renames file or directory named <code>oldname</code> to <code>newname</code>. +If this function fails, it returns <b>nil</b>, +plus a string describing the error and the error code. + + + + +<p> +<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> + + +<p> +Sets the current locale of the program. +<code>locale</code> is a system-dependent string specifying a locale; +<code>category</code> is an optional string describing which category to change: +<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, +<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; +the default category is <code>"all"</code>. +The function returns the name of the new locale, +or <b>nil</b> if the request cannot be honored. + + +<p> +If <code>locale</code> is the empty string, +the current locale is set to an implementation-defined native locale. +If <code>locale</code> is the string "<code>C</code>", +the current locale is set to the standard C locale. + + +<p> +When called with <b>nil</b> as the first argument, +this function only returns the name of the current locale +for the given category. + + +<p> +This function may be not thread safe +because of its reliance on C function <code>setlocale</code>. + + + + +<p> +<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> + + +<p> +Returns the current time when called without arguments, +or a time representing the date and time specified by the given table. +This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, +and may have fields +<code>hour</code> (default is 12), +<code>min</code> (default is 0), +<code>sec</code> (default is 0), +and <code>isdst</code> (default is <b>nil</b>). +For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. + + +<p> +The returned value is a number, whose meaning depends on your system. +In POSIX, Windows, and some other systems, +this number counts the number +of seconds since some given start time (the "epoch"). +In other systems, the meaning is not specified, +and the number returned by <code>time</code> can be used only as an argument to +<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. + + + + +<p> +<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> + + +<p> +Returns a string with a file name that can +be used for a temporary file. +The file must be explicitly opened before its use +and explicitly removed when no longer needed. + + +<p> +On POSIX systems, +this function also creates a file with that name, +to avoid security risks. +(Someone else might create the file with wrong permissions +in the time between getting the name and creating the file.) +You still have to open the file to use it +and to remove it (even if you do not use it). + + +<p> +When possible, +you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, +which automatically removes the file when the program ends. + + + + + + + +<h2>6.10 – <a name="6.10">The Debug Library</a></h2> + +<p> +This library provides +the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. +You should exert care when using this library. +Several of its functions +violate basic assumptions about Lua code +(e.g., that variables local to a function +cannot be accessed from outside; +that userdata metatables cannot be changed by Lua code; +that Lua programs do not crash) +and therefore can compromise otherwise secure code. +Moreover, some functions in this library may be slow. + + +<p> +All functions in this library are provided +inside the <a name="pdf-debug"><code>debug</code></a> table. +All functions that operate over a thread +have an optional first argument which is the +thread to operate over. +The default is always the current thread. + + +<p> +<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> + + +<p> +Enters an interactive mode with the user, +running each string that the user enters. +Using simple commands and other debug facilities, +the user can inspect global and local variables, +change their values, evaluate expressions, and so on. +A line containing only the word <code>cont</code> finishes this function, +so that the caller continues its execution. + + +<p> +Note that commands for <code>debug.debug</code> are not lexically nested +within any function and so have no direct access to local variables. + + + + +<p> +<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> + + +<p> +Returns the current hook settings of the thread, as three values: +the current hook function, the current hook mask, +and the current hook count +(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). + + + + +<p> +<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> + + +<p> +Returns a table with information about a function. +You can give the function directly +or you can give a number as the value of <code>f</code>, +which means the function running at level <code>f</code> of the call stack +of the given thread: +level 0 is the current function (<code>getinfo</code> itself); +level 1 is the function that called <code>getinfo</code> +(except for tail calls, which do not count on the stack); +and so on. +If <code>f</code> is a number larger than the number of active functions, +then <code>getinfo</code> returns <b>nil</b>. + + +<p> +The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, +with the string <code>what</code> describing which fields to fill in. +The default for <code>what</code> is to get all information available, +except the table of valid lines. +If present, +the option '<code>f</code>' +adds a field named <code>func</code> with the function itself. +If present, +the option '<code>L</code>' +adds a field named <code>activelines</code> with the table of +valid lines. + + +<p> +For instance, the expression <code>debug.getinfo(1,"n").name</code> returns +a table with a name for the current function, +if a reasonable name can be found, +and the expression <code>debug.getinfo(print)</code> +returns a table with all available information +about the <a href="#pdf-print"><code>print</code></a> function. + + + + +<p> +<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> + + +<p> +This function returns the name and the value of the local variable +with index <code>local</code> of the function at level <code>f</code> of the stack. +This function accesses not only explicit local variables, +but also parameters, temporaries, etc. + + +<p> +The first parameter or local variable has index 1, and so on, +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">§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 2 to get more information about +the running function +(level 0 is the <code>getinfo</code> function, +and level 1 is the hook function). + + + + +<p> +<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> + + +<p> +This function assigns the value <code>value</code> to the local variable +with index <code>local</code> of the function at level <code>level</code> of the stack. +The function returns <b>nil</b> if there is no local +variable with the given index, +and raises an error when called with a <code>level</code> out of range. +(You can call <code>getinfo</code> to check whether the level is valid.) +Otherwise, it returns the name of the local variable. + + +<p> +See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about +variable indices and names. + + + + +<p> +<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> + + +<p> +Sets the metatable for the given <code>value</code> to the given <code>table</code> +(which can be <b>nil</b>). +Returns <code>value</code>. + + + + +<p> +<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> + + +<p> +This function assigns the value <code>value</code> to the upvalue +with index <code>up</code> of the function <code>f</code>. +The function returns <b>nil</b> if there is no upvalue +with the given index. +Otherwise, it returns the name of the upvalue. + + + + +<p> +<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> + + +<p> +Sets the given <code>value</code> as +the Lua value associated to the given <code>udata</code>. +<code>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 – <a name="7">Lua Standalone</a></h1> + +<p> +Although Lua has been designed as an extension language, +to be embedded in a host C program, +it is also frequently used as a standalone language. +An interpreter for Lua as a standalone language, +called simply <code>lua</code>, +is provided with the standard distribution. +The standalone interpreter includes +all standard libraries, including the debug library. +Its usage is: + +<pre> + lua [options] [script [args]] +</pre><p> +The options are: + +<ul> +<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> +<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> +<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> +<li><b><code>-v</code>: </b> prints version information;</li> +<li><b><code>-E</code>: </b> ignores environment variables;</li> +<li><b><code>--</code>: </b> stops handling options;</li> +<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> +</ul><p> +After handling its options, <code>lua</code> runs the given <em>script</em>. +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>, ···, <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 <code>#!</code> form, +as in + +<pre> + #!/usr/local/bin/lua +</pre><p> +(Of course, +the location of the Lua interpreter may be different in your machine. +If <code>lua</code> is in your <code>PATH</code>, +then + +<pre> + #!/usr/bin/env lua +</pre><p> +is a more portable solution.) + + + +<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> + +<p> +Here we list the incompatibilities that you may find when moving a program +from Lua 5.2 to Lua 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 – <a name="8.1">Changes in the Language</a></h2> +<ul> + +<li> +The main difference between Lua 5.2 and Lua 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 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 5.2.) +</li> + +</ul> + + + + +<h2>8.2 – <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 5.2 already worked that way, +but it did not document the change.) +</li> + +</ul> + + + + +<h2>8.3 – <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 – <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">§3.4.8</a>; +for a description of the terminals +Name, Numeral, +and LiteralString, see <a href="#3.1">§3.1</a>.) + + + + +<pre> + + chunk ::= block + + block ::= {stat} [retstat] + + stat ::= ‘<b>;</b>’ | + varlist ‘<b>=</b>’ explist | + functioncall | + label | + <b>break</b> | + <b>goto</b> Name | + <b>do</b> block <b>end</b> | + <b>while</b> exp <b>do</b> block <b>end</b> | + <b>repeat</b> block <b>until</b> exp | + <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | + <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | + <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | + <b>function</b> funcname funcbody | + <b>local</b> <b>function</b> Name funcbody | + <b>local</b> namelist [‘<b>=</b>’ explist] + + retstat ::= <b>return</b> [explist] [‘<b>;</b>’] + + label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ + + funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] + + varlist ::= var {‘<b>,</b>’ var} + + var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name + + namelist ::= Name {‘<b>,</b>’ Name} + + explist ::= exp {‘<b>,</b>’ exp} + + exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | + prefixexp | tableconstructor | exp binop exp | unop exp + + prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ + + functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args + + args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString + + functiondef ::= <b>function</b> funcbody + + funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> + + parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ + + tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ + + fieldlist ::= field {fieldsep field} [fieldsep] + + field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp + + fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ + + binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | + ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | + ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | + <b>and</b> | <b>or</b> + + unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ + +</pre> + +<p> + + + + + + + + +<HR> +<SMALL CLASS="footer"> +Last update: +Fri Jan 16 00:58:20 BRST 2015 +</SMALL> +<!-- +Last change: minor edit +--> + + </div> + </body> +</html> +<% +end