Mercurial Hosting > luan
changeset 1670:0046c5eb3315
update manual.html
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Tue, 10 May 2022 17:08:50 -0600 |
| parents | fdeb1879fe02 |
| children | 8066b8882732 |
| files | website/src/m.html.luan website/src/manual.html.luan |
| diffstat | 2 files changed, 1340 insertions(+), 5820 deletions(-) [+] |
line wrap: on
line diff
diff -r fdeb1879fe02 -r 0046c5eb3315 website/src/m.html.luan --- a/website/src/m.html.luan Tue May 10 17:04:24 2022 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,3383 +0,0 @@ -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 - } - control = { - title = "Control Structures" - content = function() -%> -<p> -The control structures -<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and -familiar syntax: -</p> - -<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> - -<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> - -<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> - -<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: -</p> - -<pre> - stat ::= <b>break</b> -</pre> - -<p> -A <b>break</b> ends the innermost enclosing loop. -</p> - -<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: -</p> - -<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 -</p> - -<pre> - stat ::= <b>return</b> [explist] [‘<b>;</b>’] -</pre> -<% - end - } - ["for"] = { - title = "For Statement" - content = function() -%> -<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: -</p> - -<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 -</p> - -<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: -</p> - -<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: -</p> - -<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> -<% - end - } - ["try"] = { - title = "Try Statement" - content = function() -%> -<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> -<% - end - } - fn_stmt = { - title = "Function Calls as Statements" - content = function() -%> -<p> -To allow possible side-effects, -function calls can be executed as statements: -</p> - -<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>. -</p> -<% - end - } - logical_stmt = { - title = "Logical Statement" - content = function() -%> -<p> -<a href="#logical_ops">Logical expressions</a> can be statements. -This is useful in cases like this: -</p> - -<pre> - x==5 or error "x should be 5" -</pre> -<% - end - } - local_stmt = { - title = "Local Declarations" - content = function() -%> -<p> -Local variables can be declared anywhere inside a block. -The declaration can include an initial assignment: -</p> - -<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> - -<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> - -<p> -The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. -</p> -<% - end - } - template_stmt = { - title = "Template Statements" - content = function() -%> -<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> -</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> -<% - end - } - } - } - expressions = { - title = "Expressions" - content = function() -%> -<p> -The basic expressions in Luan are the following: -</p> - -<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> - -<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> - -<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> - -<p> -Here are some examples: -</p> - -<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.) -</p> -<% - end - subs = { - arithmetic = { - title = "Arithmetic Operators" - content = function() -%> -<p> -Luan supports the following arithmetic operators: -</p> - -<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> - -<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.) -</p> -<% - end - } - conversions = { - title = "Coercions and Conversions" - content = function() -%> -<p> -Luan generally avoids automatic conversions. -String concatenation automatically converts all of its arguments to strings. -</p> - -<p> -Luan provides library functions for explicit type conversions. -</p> -<% - end - } - relational = { - title = "Relational Operators" - content = function() -%> -<p> -Luan supports the following relational operators: -</p> - -<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> - -<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> - -<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> - -<p> -You can change the way that Luan compares tables -by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). -</p> - -<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> - -<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> - -<p> -The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). -</p> - -<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>. -</p> -<% - end - } - logical_ops = { - title = "Logical Operators" - content = function() -%> -<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> - -<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: -</p> - -<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.) -</p> -<% - end - } - concatenation = { - title = "Concatenation" - content = function() -%> -<p> -The string concatenation operator in Luan is -denoted by two dots ('<code>..</code>'). -All operands are converted to strings. -</p> -<% - end - } - length = { - title = "The Length Operator" - content = function() -%> -<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> - -<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> - -<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 -</p> - -<pre> - {10, 20, nil, 40} -</pre> - -<p> -has a length of <code>2</code>, because that is the last key in sequence. -</p> -<% - end - } - precedence = { - title = "Precedence" - content = function() -%> -<p> -Operator precedence in Luan follows the table below, -from lower to higher priority: -</p> - -<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. -</p> -<% - end - } - constructors = { - title = "Table Constructors" - content = function() -%> -<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 -</p> - -<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, -</p> - -<pre> - a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } -</pre> - -<p> -is equivalent to -</p> - -<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> - -<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> - -<p> -The field list can have an optional trailing separator, -as a convenience for machine-generated code. -</p> -<% - end - } - fn_calls = { - title = "Function Calls" - content = function() -%> -<p> -A function call in Luan has the following syntax: -</p> - -<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> - -<p> -Arguments have the following syntax: -</p> - -<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. -</p> -<% - end - } - fn_def = { - title = "Function Definitions" - content = function() -%> -<p> -The syntax for function definition is -</p> - -<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: -</p> - -<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 -</p> - -<pre> - function f () <em>body</em> end -</pre> - -<p> -translates to -</p> - -<pre> - f = function () <em>body</em> end -</pre> - -<p> -The statement -<p> - -<pre> - function t.a.b.c.f () <em>body</em> end -</pre> - -<p> -translates to -</p> - -<pre> - t.a.b.c.f = function () <em>body</em> end -</pre> - -<p> -The statement -</p> - -<pre> - local function f () <em>body</em> end -</pre> - -<p> -translates to -</p> - -<pre> - local f; f = function () <em>body</em> end -</pre> - -<p> -not to -</p> - -<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> - -<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> - -<p> -Parameters act as local variables that are -initialized with the argument values: -</p> - -<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> - -<p> -As an example, consider the following definitions: -</p> -<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: -</p> -<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. -</p> -<% - end - } - } - } - visibility = { - title = "Visibility Rules" - content = function() -%> -<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: -</p> -<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> - -<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> - -<p> -Notice that each execution of a <b>local</b> statement -defines new local variables. -Consider the following example: -</p> -<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>. -</p> -<% - end - } - } - } - libs = { - title = "Standard Libraries" - content = function() -%> -<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). -</p> -<% - end - subs = { - default_lib = { - title = "Default Environment" - content = function() -%> -<p> -This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>. -</p> -<% - end - subs = { - require = { - title = "<code>require (mod_uri)</code>" - content = function() -%> -<p> -Example use: -</p> -<pre> - local Table = require "luan:Table.luan" -</pre> - -<p> -Could be defined as: -</p> -<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: -</p> -<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. -</p> -<% - end - } - } - } - luan_lib = { - title = "Basic Functions" - content = function() -%> -<p> -Include this library by: -</p> -<pre> - local Luan = require "luan:Luan.luan" -</pre> - -<p> -The basic library provides basic functions to Luan that don't depend on other libaries. -</p> -<% - end - subs = { - ["Luan.do_file"] = { - title = "<code>Luan.do_file ([uri])</code>" - content = function() -%> -<p> -Could be defined as: -</p> -<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> -<% - end - } - ["Luan.error"] = { - title = "<code>Luan.error (message)</code>" - content = function() -%> -<p> -Throws an error containing the message. -</p> - -<p> -Could be defined as: -</p> -<pre> - function Luan.error(message) - <a href="#Luan.new_error">Luan.new_error</a>(message).throw() - end -</pre> -<% - end - } - ["Luan.eval"] = { - title = "<code>Luan.eval (text [, source_name [, env]])</code>" - content = function() -%> -<p> -Evaluates <code>text</code> as a Luan expression. -</p> - -<p> -Could be defined as: -</p> -<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> -<% - end - } - ["Luan.get_metatable"] = { - title = "<code>Luan.get_metatable (table)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.hash_code"] = { - title = "<code>Luan.hash_code (v)</code>" - content = function() -%> -<p> -Returns the hash code of <code>v</code>. -</p> -<% - end - } - ["Luan.ipairs"] = { - title = "<code>Luan.ipairs (t)</code>" - content = function() -%> -<p> -Returns an iterator function -so that the construction -</p> -<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> - -<p> -Could be defined as: -</p> -<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> -<% - end - } - ["Luan.load"] = { - title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>" - content = function() -%> -<p> -Loads a chunk. -</p> - -<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> - -<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> - -<p> -If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. -</p> - -<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>. -</p> -<% - end - } - ["Luan.load_file"] = { - title = "<code>Luan.load_file (file_uri)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.new_error"] = { - title = "<code>Luan.new_error (message)</code>" - content = function() -%> -<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> - -<p> -To print the current stack trace, you could do: -</p> -<pre> - Io.print( Luan.new_error "stack" ) -</pre> -<% - end - } - ["Luan.pairs"] = { - title = "<code>Luan.pairs (t)</code>" - content = function() -%> -<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> - -<p> -Otherwise, -returns a function -so that the construction -</p> -<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> -<% - end - } - ["Luan.range"] = { - title = "<code>Luan.range (start, stop [, step])</code>" - content = function() -%> -<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> - -<p> -Example use: -</p> -<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: -</p> -<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> -<% - end - } - ["Luan.raw_equal"] = { - title = "<code>Luan.raw_equal (v1, v2)</code>" - content = function() -%> -<p> -Checks whether <code>v1</code> is equal to <code>v2</code>, -without invoking any metamethod. -Returns a boolean. -</p> -<% - end - } - ["Luan.raw_get"] = { - title = "<code>Luan.raw_get (table, index)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.raw_len"] = { - title = "<code>Luan.raw_len (v)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.raw_set"] = { - title = "<code>Luan.raw_set (table, index, value)</code>" - content = function() -%> -<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 Luan value. -</p> -<% - end - } - ["Luan.set_metatable"] = { - title = "<code>Luan.set_metatable (table, metatable)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.stringify"] = { - title = "<code>Luan.stringify (v [,options])</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Luan.to_string"] = { - title = "<code>Luan.to_string (v)</code>" - content = function() -%> -<p> -Receives a value of any type and -converts it to a string in a human-readable format. -</p> - -<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. -</p> -<% - end - } - ["Luan.type"] = { - title = "<code>Luan.type (v)</code>" - content = function() -%> -<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>". -</p> -<% - end - } - ["Luan.values"] = { - title = "<code>Luan.values (···)</code>" - content = function() -%> -<p> -Returns a function so that the construction -</p> -<pre> - for i, v in Luan.values(···) do <em>body</em> end -</pre> - -<p> -will iterate over all values of <code>···</code>. -</p> -<% - end - } - ["Luan.VERSION"] = { - title = "<code>Luan.VERSION</code>" - content = function() -%> -<p> -A global variable (not a function) that -holds a string containing the current Luan version. -</p> -<% - end - } - } - } - package_lib = { - title = "Modules" - content = function() -%> -<p> -Include this library by: -</p> -<pre> - local Package = require "luan:Package.luan" -</pre> - -<p> -The package library provides basic -facilities for loading modules in Luan. -</p> -<% - end - subs = { - ["Package.load"] = { - title = "<code>Package.load (mod_uri)</code>" - content = function() -%> -<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> - -<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> - -<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> - -<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. -</p> -<% - end - } - ["Package.loaded"] = { - title = "<code>Package.loaded</code>" - content = function() -%> -<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> - -<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>. -</p> -<% - end - } - } - } - string_lib = { - title = "String Manipulation" - content = function() -%> -<p> -Include this library by: -</p> -<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. -</p> -<% - end - subs = { - ["String.char"] = { - title = "<code>String.char (···)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["String.encode"] = { - title = "<code>String.encode (s)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["String.find"] = { - title = "<code>String.find (s, pattern [, init [, plain]])</code>" - content = function() -%> -<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> - -<p> -If the pattern has captures, -then in a successful match -the captured values are also returned, -after the two indices. -</p> -<% - end - } - ["String.format"] = { - title = "<code>String.format (formatstring, ···)</code>" - content = function() -%> -<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> - -<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. -</p> -<% - end - } - ["String.gmatch"] = { - title = "<code>String.gmatch (s, pattern)</code>" - content = function() -%> -<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> - -<p> -As an example, the following loop -will iterate over all the words from string <code>s</code>, -printing one per line: -</p> -<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: -</p> -<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. -</p> -<% - end - } - ["String.gsub"] = { - title = "<code>String.gsub (s, pattern, repl [, n])</code>" - content = function() -%> -<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> - -<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> - -<p> -If <code>repl</code> is a table, then the table is queried for every match, -using the first capture as the key. -</p> - -<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> - -<p> -In any case, -if the pattern specifies no captures, -then it behaves as if the whole pattern was inside a capture. -</p> - -<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> - -<p> -Here are some examples: -</p> -<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> -<% - end - } - ["String.lower"] = { - title = "<code>String.lower (s)</code>" - content = function() -%> -<p> -Receives a string and returns a copy of this string with all -uppercase letters changed to lowercase. -All other characters are left unchanged. -</p> -<% - end - } - ["String.match"] = { - title = "<code>String.match (s, pattern [, init])</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["String.matches"] = { - title = "<code>String.matches (s, pattern)</code>" - content = function() -%> -<p> -Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>. -This function is equivalent to -</p> -<pre> - return String.match(s,pattern) ~= nil -</pre> -<% - end - } - ["String.regex_quote"] = { - title = "<code>String.regex_quote (s)</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["String.rep"] = { - title = "<code>String.rep (s, n [, sep])</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["String.reverse"] = { - title = "<code>String.reverse (s)</code>" - content = function() -%> -<p> -Returns a string that is the string <code>s</code> reversed. -</p> -<% - end - } - ["String.split"] = { - title = "<code>String.split (s, pattern [, limit])</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["String.sub"] = { - title = "<code>String.sub (s, i [, j])</code>" - content = function() -%> -<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> - -<p> -If, after the translation of negative indices, -<code>i</code> is less than 1, -it is corrected to 1. -If <code>j</code> is greater than the string length, -it is corrected to that length. -If, after these corrections, -<code>i</code> is greater than <code>j</code>, -the function returns the empty string. -</p> -<% - end - } - ["String.to_binary"] = { - title = "<code>String.to_binary (s)</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["String.to_number"] = { - title = "<code>String.to_number (s [, base])</code>" - content = function() -%> -<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> - -<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>. -</p> -<% - end - } - ["String.trim"] = { - title = "<code>String.trim (s)</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["String.unicode"] = { - title = "<code>String.unicode (s [, i [, j]])</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["String.upper"] = { - title = "<code>String.upper (s)</code>" - content = function() -%> -<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. -</p> -<% - end - } - } - } - binary_lib = { - title = "Binary Manipulation" - content = function() -%> -<p> -Include this library by: -</p> -<pre> - local Binary = require "luan:Binary.luan" -</pre> -<% - end - subs = { - ["Binary.binary"] = { - title = "<code>Binary.binary (···)</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Binary.byte"] = { - title = "<code>Binary.byte (b [, i [, j]])</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["Binary.to_string"] = { - title = "<code>Binary.to_string (b [,charset])</code>" - content = function() -%> -<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. -</p> -<% - end - } - } - } - table_lib = { - title = "Table Manipulation" - content = function() -%> -<p> -Include this library by: -</p> -<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>. -</p> -<% - end - subs = { - ["Table.clear"] = { - title = "<code>Table.clear (tbl)</code>" - content = function() -%> -<p> -Clears the table. -</p> -<% - end - } - ["Table.concat"] = { - title = "<code>Table.concat (list [, sep [, i [, j]]])</code>" - content = function() -%> -<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. -</p> -<% - end - } - ["Table.copy"] = { - title = "<code>Table.copy (tbl [, i [, j]])</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["Table.insert"] = { - title = "<code>Table.insert (list, pos, value)</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["Table.is_empty"] = { - title = "<code>Table.is_empty (tbl)</code>" - content = function() -%> -<% - end - } - ["Table.pack"] = { - title = "<code>Table.pack (···)</code>" - content = function() -%> -<p> -Returns a new table with all parameters stored into keys 1, 2, etc. -and with a field "<code>n</code>" with the total number of parameters. -Note that the resulting table may not be a sequence. -</p> -<% - end - } - ["Table.remove"] = { - title = "<code>Table.remove (list, pos)</code>" - content = function() -%> -<p> -Removes from <code>list</code> the element at position <code>pos</code>, -returning the value of the removed element. -When <code>pos</code> is an integer between 1 and <code>#list</code>, -it shifts down the elements -<code>list[pos+1], list[pos+2], ···, list[#list]</code> -and erases element <code>list[#list]</code>; -The index <code>pos</code> can also be 0 when <code>#list</code> is 0, -or <code>#list + 1</code>; -in those cases, the function erases the element <code>list[pos]</code>. -</p> -<% - end - } - ["Table.size"] = { - title = "<code>Table.size (tbl)</code>" - content = function() -%> -<% - end - } - ["Table.sort"] = { - title = "<code>Table.sort (list [, comp])</code>" - content = function() -%> -<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> - -<p> -The sort algorithm is not stable; -that is, elements considered equal by the given order -may have their relative positions changed by the sort. -</p> -<% - end - } - ["Table.unpack"] = { - title = "<code>Table.unpack (list [, i [, j]])</code>" - content = function() -%> -<p> -Returns the elements from the given list. -This function is equivalent to -</p> -<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>. -</p> -<% - end - } - } - } - number_lib = { - title = "Number Manipulation" - content = function() -%> -<p> -Include this library by: -</p> -<pre> - local Number = require "luan:Number.luan" -</pre> -<% - end - subs = { - ["Number.double"] = { - title = "<code>Number.double (x)</code>" - content = function() -%> -<p> -Returns <code>x</code> as a double. -</p> -<% - end - } - ["Number.float"] = { - title = "<code>Number.float (x)</code>" - content = function() -%> -<p> -Returns <code>x</code> as a float. -</p> -<% - end - } - ["Number.integer"] = { - title = "<code>Number.integer (x)</code>" - content = function() -%> -<p> -If the value <code>x</code> is convertible to an integer, -returns that integer. -Otherwise throws an error. -</p> -<% - end - } - ["Number.long"] = { - title = "<code>Number.long (x)</code>" - content = function() -%> -<p> -If the value <code>x</code> is convertible to an long, -returns that long. -Otherwise throws an error. -</p> -<% - end - } - ["Number.long_to_string"] = { - title = "<code>Number.long_to_string (i, radix)</code>" - content = function() -%> -<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>. -</p> -<% - end - } - ["Number.type"] = { - title = "<code>Number.type (x)</code>" - content = function() -%> -<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>". -</p> -<% - end - } - } - } - math_lib = { - title = "Mathematical Functions" - content = function() -%> -<p> -Include this library by: -</p> -<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>. -</p> -<% - end - subs = { - ["Math.abs"] = { - title = "<code>Math.abs (x)</code>" - content = function() -%> -<p> -Returns the absolute value of <code>x</code>. -</p> -<% - end - } - ["Math.acos"] = { - title = "<code>Math.acos (x)</code>" - content = function() -%> -<p> -Returns the arc cosine of <code>x</code> (in radians). -</p> -<% - end - } - ["Math.asin"] = { - title = "<code>Math.asin (x)</code>" - content = function() -%> -<p> -Returns the arc sine of <code>x</code> (in radians). -</p> -<% - end - } - ["Math.atan"] = { - title = "<code>Math.atan (y, x)</code>" - content = function() -%> -<p> -Returns the arc tangent of <code>y/x</code> (in radians), -but uses the signs of both parameters to find the -quadrant of the result. -(It also handles correctly the case of <code>x</code> being zero.) -</p> -<% - end - } - ["Math.ceil"] = { - title = "<code>Math.ceil (x)</code>" - content = function() -%> -<p> -Returns the smallest integral value larger than or equal to <code>x</code>. -</p> -<% - end - } - ["Math.cos"] = { - title = "<code>Math.cos (x)</code>" - content = function() -%> -<p> -Returns the cosine of <code>x</code> (assumed to be in radians). -</p> -<% - end - } - ["Math.deg"] = { - title = "<code>Math.deg (x)</code>" - content = function() -%> -<p> -Converts the angle <code>x</code> from radians to degrees. -</p> -<% - end - } - ["Math.exp"] = { - title = "<code>Math.exp (x)</code>" - content = function() -%> -<p> -Returns the value <em>e<sup>x</sup></em> -(where <code>e</code> is the base of natural logarithms). -</p> -<% - end - } - ["Math.floor"] = { - title = "<code>Math.floor (x)</code>" - content = function() -%> -<p> -Returns the largest integral value smaller than or equal to <code>x</code>. -</p> -<% - end - } - ["Math.fmod"] = { - title = "<code>Math.fmod (x, y)</code>" - content = function() -%> -<p> -Returns the remainder of the division of <code>x</code> by <code>y</code> -that rounds the quotient towards zero. -</p> -<% - end - } - ["Math.huge"] = { - title = "<code>Math.huge</code>" - content = function() -%> -<p> -A value larger than any other numerical value. -</p> -<% - end - } - ["Math.log"] = { - title = "<code>Math.log (x [, base])</code>" - content = function() -%> -<p> -Returns the logarithm of <code>x</code> in the given base. -The default for <code>base</code> is <em>e</em> -(so that the function returns the natural logarithm of <code>x</code>). -</p> -<% - end - } - ["Math.max"] = { - title = "<code>Math.max (x, ···)</code>" - content = function() -%> -<p> -Returns the argument with the maximum value, -according to the Lua operator <code><</code>. -</p> -<% - end - } - ["Math.max_integer"] = { - title = "<code>Math.max_integer</code>" - content = function() -%> -<p> -An integer with the maximum value for an integer. -</p> -<% - end - } - ["Math.min"] = { - title = "<code>Math.min (x, ···)</code>" - content = function() -%> -<p> -Returns the argument with the minimum value, -according to the Lua operator <code><</code>. -</p> -<% - end - } - ["Math.min_integer"] = { - title = "<code>Math.min_integer</code>" - content = function() -%> -<p> -An integer with the minimum value for an integer. -</p> -<% - end - } - ["Math.modf"] = { - title = "<code>Math.modf (x)</code>" - content = function() -%> -<p> -Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. -</p> -<% - end - } - ["Math.pi"] = { - title = "<code>Math.pi</code>" - content = function() -%> -<p> -The value of <em>π</em>. -</p> -<% - end - } - ["Math.rad"] = { - title = "<code>Math.rad (x)</code>" - content = function() -%> -<p> -Converts the angle <code>x</code> from degrees to radians. -</p> -<% - end - } - ["Math.random"] = { - title = "<code>Math.random ([m [, n])</code>" - content = function() -%> -<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> - -<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. -</p> -<% - end - } - ["Math.sin"] = { - title = "<code>Math.sin (x)</code>" - content = function() -%> -<p> -Returns the sine of <code>x</code> (assumed to be in radians). -</p> -<% - end - } - ["Math.sqrt"] = { - title = "<code>Math.sqrt (x)</code>" - content = function() -%> -<p> -Returns the square root of <code>x</code>. -(You can also use the expression <code>x^0.5</code> to compute this value.) -</p> -<% - end - } - ["Math.tan"] = { - title = "<code>Math.tan (x)</code>" - content = function() -%> -<p> -Returns the tangent of <code>x</code> (assumed to be in radians). -</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
diff -r fdeb1879fe02 -r 0046c5eb3315 website/src/manual.html.luan --- a/website/src/manual.html.luan Tue May 10 17:04:24 2022 -0600 +++ b/website/src/manual.html.luan Tue May 10 17:08:50 2022 -0600 @@ -5,150 +5,56 @@ 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() -return function() - Io.stdout = Http.response.text_writer() +local content = { + intro = { + title = "Introduction" + content = function() %> -<!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> +<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> -<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> +Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers. </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> +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: @@ -165,16 +71,15 @@ 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 @@ -182,9 +87,8 @@ 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 - - +Java values are useful when Java access is enabled in Luan. +</p> <p> The type <em>table</em> implements associative arrays, @@ -195,7 +99,7 @@ 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; @@ -206,14 +110,14 @@ 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, @@ -222,7 +126,7 @@ 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 @@ -234,7 +138,7 @@ 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>: @@ -243,47 +147,56 @@ 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. - - - - - -<h3 heading><a name="env" href="#env">Environments</a></h3> - +</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. - - -<h3 heading><a name="error" href="#error">Error Handling</a></h3> - +</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>. - - - -<h3 heading><a name="meta" href="#meta">Metatables and Metamethods</a></h3> - +</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 @@ -295,30 +208,30 @@ 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. @@ -331,6 +244,7 @@ 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) @@ -338,10 +252,12 @@ <p> Here are the events: +</p> <ul> -<li><p><b>"add": </b> +<li><p> +<b>"add": </b> the <code>+</code> operation. If any operand for an addition is a table, @@ -356,53 +272,52 @@ is the result of the operation. Otherwise, it raises an error. -</li> +</p></li> -<li><p><b>"sub": </b> +<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> +</p></li> -<li><p><b>"div": </b> +<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. +</p></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. +</p></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> +</p></li> -<li><p><b>"concat": </b> -the <code>..</code> (concatenation) operation. - +<li><p> +<b>"unm": </b> +the <code>-</code> (unary minus) operation. Behavior similar to the "add" operation. -</li> +</p></li> -<li><p><b>"len": </b> +<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 @@ -411,28 +326,28 @@ 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> +</p></li> -<li><p><b>"eq": </b> +<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> +</p></li> -<li><p><b>"lt": </b> +<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> +</p></li> -<li><p><b>"le": </b> +<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, @@ -442,15 +357,16 @@ 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> +</p></li> -<li><p><b>"index": </b> +<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, @@ -461,16 +377,18 @@ 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> +<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, @@ -481,7 +399,7 @@ 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, @@ -489,29 +407,34 @@ (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> +<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> +</p></li> </ul> - - - - -<h3 heading><a name="gc" href="#gc">Garbage Collection</a></h3> - +<% + end + } + gc = { + title = "Garbage Collection" + content = function() +%> <p> Luan uses Java's garbage collection. - - - - - -<h2 heading><a name="lang" href="#lang">The Language</a></h2> - +</p> +<% + end + } + } + } + lang = { + title = "The Language" + content = function() +%> <p> This section describes the lexis, the syntax, and the semantics of Luan. In other words, @@ -519,7 +442,7 @@ 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, @@ -531,16 +454,20 @@ 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> +<% + 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> @@ -549,12 +476,12 @@ 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> @@ -593,10 +520,11 @@ 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> + - * / % ^ # @@ -628,7 +556,7 @@ 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. @@ -641,7 +569,7 @@ 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 @@ -665,7 +593,7 @@ (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 @@ -676,7 +604,7 @@ 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, @@ -684,6 +612,7 @@ 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"' @@ -710,6 +639,7 @@ denotes a float; otherwise it denotes an integer. Examples of valid integer constants are +</p> <pre> 3 345 0xff 0xBEBADA @@ -717,6 +647,7 @@ <p> Examples of valid float constants are +</p> <pre> 3.0 3.1416 314.16e-2 0.31416E1 34e1 @@ -732,22 +663,25 @@ 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> +<% + 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 @@ -755,18 +689,21 @@ <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>’ @@ -780,11 +717,12 @@ <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 @@ -795,27 +733,32 @@ 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> +<% + 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. - - - -<h4 heading><a name="blocks" href="#blocks">Blocks</a></h4> - +</p> +<% + end + subs = { + blocks = { + title = "Blocks" + content = function() +%> <p> A block is a list of statements, which are executed sequentially: +</p> <pre> block ::= {stat} @@ -826,6 +769,7 @@ 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>’ @@ -833,6 +777,7 @@ <p> A block can be explicitly delimited to produce a single statement: +</p> <pre> stat ::= <b>do</b> block end_do @@ -845,17 +790,19 @@ 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> +<% + 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 @@ -867,7 +814,7 @@ (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. @@ -875,19 +822,21 @@ 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> +<% + 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 @@ -897,7 +846,7 @@ <p> Expressions are discussed in <a href="#expressions">Expressions</a>. - +</p> <p> Before the assignment, @@ -911,12 +860,13 @@ 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 @@ -928,6 +878,7 @@ 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 @@ -936,6 +887,7 @@ <p> exchanges the values of <code>x</code> and <code>y</code>, and +</p> <pre> x, y, z = y, z, x @@ -943,7 +895,7 @@ <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 @@ -954,22 +906,26 @@ <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. - - - -<h4 heading><a name="control" href="#control">Control Structures</a></h4> - +</p> +<% + end + } + control = { + title = "Control Structures" + content = function() +%> <p> The control structures <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and familiar syntax: +</p> <pre> stat ::= <b>while</b> exp <b>do</b> block end_while @@ -981,14 +937,14 @@ <p> Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>). - +</p> <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> <p> In the <b>repeat</b>–<b>until</b> loop, @@ -996,12 +952,13 @@ but only after the condition. So, the condition can refer to local variables declared inside the loop block. - +</p> <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: +</p> <pre> stat ::= <b>break</b> @@ -1009,41 +966,43 @@ <p> A <b>break</b> ends the innermost enclosing loop. - +</p> <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: +</p> <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 +</p> <pre> stat ::= <b>return</b> [explist] [‘<b>;</b>’] </pre> - - - - -<h4 heading><a name="for" href="#for">For Statement</a></h4> - +<% + end + } + ["for"] = { + title = "For Statement" + content = function() +%> <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: +</p> <pre> stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block end_for @@ -1053,6 +1012,7 @@ <p> A <b>for</b> statement like +</p> <pre> for <em>var_1</em>, ···, <em>var_n</em> in <em>exp</em> do <em>block</em> end @@ -1060,6 +1020,7 @@ <p> is equivalent to the code: +</p> <pre> do @@ -1074,51 +1035,53 @@ <p> Note the following: +</p> <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> - + <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> +<% + end + } + ["try"] = { + title = "Try Statement" + content = function() +%> +<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> - +<% + end + } + fn_stmt = { + title = "Function Calls as Statements" + content = function() +%> <p> To allow possible side-effects, function calls can be executed as statements: +</p> <pre> stat ::= functioncall @@ -1127,14 +1090,33 @@ <p> In this case, all returned values are thrown away. Function calls are explained in <a href="#fn_calls">Function Calls</a>. - - +</p> +<% + end + } + logical_stmt = { + title = "Logical Statement" + content = function() +%> +<p> +<a href="#logical_ops">Logical expressions</a> can be statements. +This is useful in cases like this: +</p> -<h4 heading><a name="local_stmt" href="#local_stmt">Local Declarations</a></h4> - +<pre> + x==5 or error "x should be 5" +</pre> +<% + end + } + local_stmt = { + title = "Local Declarations" + content = function() +%> <p> Local variables can be declared anywhere inside a block. The declaration can include an initial assignment: +</p> <pre> stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] @@ -1144,20 +1126,25 @@ 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> <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> <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> +<% + end + } + template_stmt = { + title = "Template Statements" + content = function() +%> <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> +</p> <pre> local name = "Bob" @@ -1167,19 +1154,26 @@ <% </pre> -<p>is equivalent to the code:</p> +<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> - +<% + end + } + } + } + expressions = { + title = "Expressions" + content = function() +%> <p> The basic expressions in Luan are the following: +</p> <pre> exp ::= prefixexp @@ -1204,7 +1198,7 @@ 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> <p> Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>), @@ -1213,7 +1207,7 @@ 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> <p> Both function calls and vararg expressions can result in multiple values. @@ -1228,10 +1222,11 @@ 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> <p> Here are some examples: +</p> <pre> f() -- adjusted to 0 results @@ -1259,13 +1254,17 @@ 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> +<% + end + subs = { + arithmetic = { + title = "Arithmetic Operators" + content = function() +%> <p> Luan supports the following arithmetic operators: +</p> <ul> <li><b><code>+</code>: </b>addition</li> @@ -1279,47 +1278,58 @@ <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> <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> +<% + end + } + conversions = { + title = "Coercions and Conversions" + content = function() +%> <p> Luan generally avoids automatic conversions. String concatenation automatically converts all of its arguments to strings. +</p> <p> Luan provides library functions for explicit type conversions. - - - - -<h4 heading><a name="relational" href="#relational">Relational Operators</a></h4> - +</p> +<% + end + } + relational = { + title = "Relational Operators" + content = function() +%> <p> Luan supports the following relational operators: +</p> <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> + <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> <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> <p> Tables @@ -1328,13 +1338,16 @@ Every time you create a new table, it is different from any previously existing table. Closures are also compared by reference. +</p> <p> You can change the way that Luan compares tables by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). +</p> <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> <p> Equality comparisons do not convert strings to numbers @@ -1342,15 +1355,14 @@ 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> <p> The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). - +</p> <p> The order operators work as follows. - If both arguments are numbers, then they are compared following the usual rule for binary operations. @@ -1360,13 +1372,14 @@ 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> +<% + end + } + logical_ops = { + title = "Logical Operators" + content = function() +%> <p> The logical operators in Luan are <b>and</b>, <b>or</b>, and <b>not</b>. @@ -1374,6 +1387,7 @@ 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> <p> The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. @@ -1387,6 +1401,7 @@ that is, the second operand is evaluated only if necessary. Here are some examples: +</p> <pre> 10 or 20 --> 10 @@ -1402,30 +1417,36 @@ <p> (In this manual, <code>--></code> indicates the result of the preceding expression.) - - - -<h4 heading><a name="concatenation" href="#concatenation">Concatenation</a></h4> - +</p> +<% + end + } + concatenation = { + title = "Concatenation" + content = function() +%> <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> +<% + end + } + length = { + title = "The Length Operator" + content = function() +%> <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> <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> <p> Unless a <code>__len</code> metamethod is given, @@ -1436,6 +1457,7 @@ for some non-negative integer <em>n</em>. In that case, <em>n</em> is its length. Note that a table like +</p> <pre> {10, 20, nil, 40} @@ -1443,16 +1465,18 @@ <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> +<% + end + } + precedence = { + title = "Precedence" + content = function() +%> <p> Operator precedence in Luan follows the table below, from lower to higher priority: +</p> <pre> or @@ -1471,19 +1495,21 @@ 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> +<% + end + } + constructors = { + title = "Table Constructors" + content = function() +%> <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 +</p> <pre> tableconstructor ::= ‘<b>{</b>’ fieldlist ‘<b>}</b>’ @@ -1502,6 +1528,7 @@ starting with 1. Fields in the other formats do not affect this counting. For example, +</p> <pre> a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } @@ -1509,6 +1536,7 @@ <p> is equivalent to +</p> <pre> do @@ -1527,27 +1555,29 @@ <p> The order of the assignments in a constructor is undefined. (This order would be relevant only when there are repeated keys.) - +</p> <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> <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> +<% + end + } + fn_calls = { + title = "Function Calls" + content = function() +%> <p> A function call in Luan has the following syntax: +</p> <pre> functioncall ::= prefixexp args @@ -1559,10 +1589,11 @@ The value of prefixexp must have type <em>function</em>. This function is called with the given arguments. - +</p> <p> Arguments have the following syntax: +</p> <pre> args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ @@ -1579,14 +1610,17 @@ (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> +<% + end + } + fn_def = { + title = "Function Definitions" + content = function() +%> <p> The syntax for function definition is +</p> <pre> functiondef ::= <b>function</b> funcbody @@ -1596,6 +1630,7 @@ <p> The following syntactic sugar simplifies function definitions: +</p> <pre> stat ::= <b>function</b> funcname funcbody @@ -1605,6 +1640,7 @@ <p> The statement +</p> <pre> function f () <em>body</em> end @@ -1612,6 +1648,7 @@ <p> translates to +</p> <pre> f = function () <em>body</em> end @@ -1619,6 +1656,7 @@ <p> The statement +<p> <pre> function t.a.b.c.f () <em>body</em> end @@ -1626,6 +1664,7 @@ <p> translates to +</p> <pre> t.a.b.c.f = function () <em>body</em> end @@ -1633,6 +1672,7 @@ <p> The statement +</p> <pre> local function f () <em>body</em> end @@ -1640,6 +1680,7 @@ <p> translates to +</p> <pre> local f; f = function () <em>body</em> end @@ -1647,6 +1688,7 @@ <p> not to +</p> <pre> local f = function () <em>body</em> end @@ -1655,7 +1697,7 @@ <p> (This only makes a difference when the body of the function contains references to <code>f</code>.) - +</p> <p> A function definition is an executable expression, @@ -1666,11 +1708,12 @@ 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> <p> Parameters act as local variables that are initialized with the argument values: +</p> <pre> parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ @@ -1695,11 +1738,11 @@ 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> <p> As an example, consider the following definitions: - +</p> <pre> function f(a, b) end function g(a, b, ...) end @@ -1709,7 +1752,7 @@ <p> Then, we have the following mapping from arguments to parameters and to the vararg expression: - +</p> <pre> CALL PARAMETERS @@ -1730,17 +1773,23 @@ 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> +<% + end + } + } + } + visibility = { + title = "Visibility Rules" + content = function() +%> <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: - +</p> <pre> x = 10 -- global variable do -- new block @@ -1760,7 +1809,7 @@ 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> <p> Because of the lexical scoping rules, @@ -1769,13 +1818,13 @@ 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> <p> Notice that each execution of a <b>local</b> statement defines new local variables. Consider the following example: - +</p> <pre> a = {} local x = 20 @@ -1790,13 +1839,16 @@ (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> +<% + end + } + } + } + libs = { + title = "Standard Libraries" + content = function() +%> <p> The standard Luan libraries provide useful functions that are implemented both in Java and in Luan itself. @@ -1804,26 +1856,34 @@ 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> +<% + end + subs = { + default_lib = { + title = "Default Environment" + content = function() +%> <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> +<% + end + subs = { + require = { + title = "<code>require (mod_uri)</code>" + content = function() +%> <p> Example use: - +</p> <pre> local Table = require "luan:Table.luan" </pre> <p> Could be defined as: - +</p> <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") @@ -1832,96 +1892,122 @@ <p> A special case is: - +</p> <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> +<% + end + } + } + } + luan_lib = { + title = "Basic Functions" + content = function() +%> <p> Include this library by: - +</p> <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> +<% + end + subs = { + ["Luan.do_file"] = { + title = "<code>Luan.do_file ([uri])</code>" + content = function() +%> <p> Could be defined as: - +</p> <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> - +<% + end + } + ["Luan.error"] = { + title = "<code>Luan.error (message)</code>" + content = function() +%> <p> Throws an error containing the message. +</p> <p> Could be defined as: - +</p> <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> - +<% + end + } + ["Luan.eval"] = { + title = "<code>Luan.eval (text [, source_name [, env]])</code>" + content = function() +%> <p> Evaluates <code>text</code> as a Luan expression. +</p> <p> Could be defined as: - +</p> <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> - +<% + end + } + ["Luan.get_metatable"] = { + title = "<code>Luan.get_metatable (table)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.hash_code"] = { + title = "<code>Luan.hash_code (v)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.ipairs"] = { + title = "<code>Luan.ipairs (t)</code>" + content = function() +%> <p> Returns an iterator function so that the construction - +</p> <pre> for i,v in ipairs(t) do <em>body</em> end </pre> @@ -1930,10 +2016,11 @@ will iterate over the key–value pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., up to the first nil value. +</p> <p> Could be defined as: - +</p> <pre> function Luan.ipairs(t) local i = 0 @@ -1945,94 +2032,103 @@ end end </pre> - - - -<h4 heading><a name="Luan.load" href="#Luan.load"><code>Luan.load (text, [source_name [, env [, persist]]])</code></a></h4> - +<% + end + } + ["Luan.load"] = { + title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>" + content = function() +%> <p> Loads a chunk. +</p> <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> <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> <p> If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. +</p> <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> +<% + end + } + ["Luan.load_file"] = { + title = "<code>Luan.load_file (file_uri)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.new_error"] = { + title = "<code>Luan.new_error (message)</code>" + content = function() +%> <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> <p> To print the current stack trace, you could do: - +</p> <pre> Io.print( Luan.new_error "stack" ) </pre> - - -<h4 heading><a name="Luan.pairs" href="#Luan.pairs"><code>Luan.pairs (t)</code></a></h4> - +<% + end + } + ["Luan.pairs"] = { + title = "<code>Luan.pairs (t)</code>" + content = function() +%> <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> <p> Otherwise, returns a function so that the construction - +</p> <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> +<% + end + } + ["Luan.range"] = { + title = "<code>Luan.range (start, stop [, step])</code>" + content = function() +%> <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> <p> Example use: - +</p> <pre> for i in range(1,10) do Io.print("count up:",i) @@ -2044,7 +2140,7 @@ <p> Could be defined as: - +</p> <pre> function Luan.range(start, stop, step) step = step or 1 @@ -2059,80 +2155,107 @@ end end </pre> - - - -<h4 heading><a name="Luan.raw_equal" href="#Luan.raw_equal"><code>Luan.raw_equal (v1, v2)</code></a></h4> - +<% + end + } + ["Luan.raw_equal"] = { + title = "<code>Luan.raw_equal (v1, v2)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.raw_get"] = { + title = "<code>Luan.raw_get (table, index)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.raw_len"] = { + title = "<code>Luan.raw_len (v)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.raw_set"] = { + title = "<code>Luan.raw_set (table, index, value)</code>" + content = function() +%> <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> - +and <code>value</code> any Luan value. +</p> +<% + end + } + ["Luan.set_metatable"] = { + title = "<code>Luan.set_metatable (table, metatable)</code>" + content = function() +%> <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> +<% + end + } + ["Luan.stringify"] = { + title = "<code>Luan.stringify (v [,options])</code>" + content = function() +%> <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> +<% + end + } + ["Luan.to_string"] = { + title = "<code>Luan.to_string (v)</code>" + content = function() +%> <p> Receives a value of any type and converts it to a string in a human-readable format. +</p> <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> +<% + end + } + ["Luan.type"] = { + title = "<code>Luan.type (v)</code>" + content = function() +%> <p> Returns the type of its only argument, coded as a string. The possible results of this function are @@ -2144,38 +2267,47 @@ "<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> +<% + end + } + ["Luan.values"] = { + title = "<code>Luan.values (···)</code>" + content = function() +%> <p> Returns a function so that the construction - +</p> <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> +<% + end + } + ["Luan.VERSION"] = { + title = "<code>Luan.VERSION</code>" + content = function() +%> <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> +<% + end + } + } + } + package_lib = { + title = "Modules" + content = function() +%> <p> Include this library by: - +</p> <pre> local Package = require "luan:Package.luan" </pre> @@ -2183,10 +2315,14 @@ <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> +<% + end + subs = { + ["Package.load"] = { + title = "<code>Package.load (mod_uri)</code>" + content = function() +%> <p> Loads the given module. The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table @@ -2194,45 +2330,51 @@ 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> <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> <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> <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> +<% + end + } + ["Package.loaded"] = { + title = "<code>Package.loaded</code>" + content = function() +%> <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> <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> +<% + end + } + } + } + string_lib = { + title = "String Manipulation" + content = function() +%> <p> Include this library by: - +</p> <pre> local String = require "luan:String.luan" </pre> @@ -2245,28 +2387,37 @@ 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> +<% + end + subs = { + ["String.char"] = { + title = "<code>String.char (···)</code>" + content = function() +%> <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> +<% + end + } + ["String.encode"] = { + title = "<code>String.encode (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.find"] = { + title = "<code>String.find (s, pattern [, init [, plain]])</code>" + content = function() +%> <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>. @@ -2281,31 +2432,37 @@ 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> <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> +<% + end + } + ["String.format"] = { + title = "<code>String.format (formatstring, ···)</code>" + content = function() +%> <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> <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> +<% + end + } + ["String.gmatch"] = { + title = "<code>String.gmatch (s, pattern)</code>" + content = function() +%> <p> Returns an iterator function that, each time it is called, @@ -2313,13 +2470,13 @@ over the string <code>s</code>. If <code>pattern</code> specifies no captures, then the whole match is produced in each call. - +</p> <p> As an example, the following loop will iterate over all the words from string <code>s</code>, printing one per line: - +</p> <pre> local s = "hello world from Lua" for w in String.gmatch(s, [[\w+]]) do @@ -2330,7 +2487,7 @@ <p> The next example collects all pairs <code>key=value</code> from the given string into a table: - +</p> <pre> local t = {} local s = "from=world, to=Lua" @@ -2342,11 +2499,14 @@ <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> +<% + end + } + ["String.gsub"] = { + title = "<code>String.gsub (s, pattern, repl [, n])</code>" + content = function() +%> <p> Returns a copy of <code>s</code> in which all (or the first <code>n</code>, if given) @@ -2356,7 +2516,7 @@ <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> <p> If <code>repl</code> is a string, then its value is used for replacement. @@ -2365,24 +2525,24 @@ 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> <p> If <code>repl</code> is a table, then the table is queried for every match, using the first capture as the key. - +</p> <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> <p> In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture. - +</p> <p> If the value returned by the table query or by the function call @@ -2391,11 +2551,11 @@ otherwise, if it is <b>nil</b>, then there is no replacement (that is, the original match is kept in the string). - +</p> <p> Here are some examples: - +</p> <pre> x = String.gsub("hello world", [[(\w+)]], "$1 $1") --> x="hello hello world world" @@ -2415,18 +2575,25 @@ 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> +<% + end + } + ["String.lower"] = { + title = "<code>String.lower (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.match"] = { + title = "<code>String.match (s, pattern [, init])</code>" + content = function() +%> <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>. @@ -2438,49 +2605,72 @@ 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> +<% + end + } + ["String.matches"] = { + title = "<code>String.matches (s, pattern)</code>" + content = function() +%> <p> Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>. This function is equivalent to - +</p> <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> +<% + end + } + ["String.regex_quote"] = { + title = "<code>String.regex_quote (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.rep"] = { + title = "<code>String.rep (s, n [, sep])</code>" + content = function() +%> <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> +<% + end + } + ["String.reverse"] = { + title = "<code>String.reverse (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.split"] = { + title = "<code>String.split (s, pattern [, limit])</code>" + content = function() +%> <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> +<% + end + } + ["String.sub"] = { + title = "<code>String.sub (s, i [, j])</code>" + content = function() +%> <p> Returns the substring of <code>s</code> that starts at <code>i</code> and continues until <code>j</code>; @@ -2492,7 +2682,7 @@ 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> <p> If, after the translation of negative indices, @@ -2503,18 +2693,24 @@ 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> +<% + end + } + ["String.to_binary"] = { + title = "<code>String.to_binary (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.to_number"] = { + title = "<code>String.to_number (s [, base])</code>" + content = function() +%> <p> When called with no <code>base</code>, <code>to_number</code> tries to convert its argument to a number. @@ -2522,9 +2718,8 @@ 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> <p> When called with <code>base</code>, @@ -2535,19 +2730,24 @@ 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> +<% + end + } + ["String.trim"] = { + title = "<code>String.trim (s)</code>" + content = function() +%> <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> +<% + end + } + ["String.unicode"] = { + title = "<code>String.unicode (s [, i [, j]])</code>" + content = function() +%> <p> Returns the internal numerical codes of the characters <code>s[i]</code>, <code>s[i+1]</code>, ..., <code>s[j]</code>. @@ -2555,43 +2755,55 @@ 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> +<% + end + } + ["String.upper"] = { + title = "<code>String.upper (s)</code>" + content = function() +%> <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> +<% + end + } + } + } + binary_lib = { + title = "Binary Manipulation" + content = function() +%> <p> Include this library by: - +</p> <pre> local Binary = require "luan:Binary.luan" </pre> - - -<h4 heading><a name="Binary.binary" href="#Binary.binary"><code>Binary.binary (···)</code></a></h4> - +<% + end + subs = { + ["Binary.binary"] = { + title = "<code>Binary.binary (···)</code>" + content = function() +%> <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> +<% + end + } + ["Binary.byte"] = { + title = "<code>Binary.byte (b [, i [, j]])</code>" + content = function() +%> <p> Returns the internal numerical codes of the bytes <code>b[i]</code>, <code>b[i+1]</code>, ..., <code>b[j]</code>. @@ -2599,20 +2811,29 @@ 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> +<% + end + } + ["Binary.to_string"] = { + title = "<code>Binary.to_string (b [,charset])</code>" + content = function() +%> <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> +<% + end + } + } + } + table_lib = { + title = "Table Manipulation" + content = function() +%> <p> Include this library by: - +</p> <pre> local Table = require "luan:Table.luan" </pre> @@ -2620,17 +2841,24 @@ <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> +<% + end + subs = { + ["Table.clear"] = { + title = "<code>Table.clear (tbl)</code>" + content = function() +%> <p> Clears the table. - - -<h4 heading><a name="Table.concat" href="#Table.concat"><code>Table.concat (list [, sep [, i [, j]]])</code></a></h4> - +</p> +<% + end + } + ["Table.concat"] = { + title = "<code>Table.concat (list [, sep [, i [, j]]])</code>" + content = function() +%> <p> Given a list, returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. @@ -2638,43 +2866,57 @@ 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> +<% + end + } + ["Table.copy"] = { + title = "<code>Table.copy (tbl [, i [, j]])</code>" + content = function() +%> <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> +<% + end + } + ["Table.insert"] = { + title = "<code>Table.insert (list, pos, value)</code>" + content = function() +%> <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> +<% + end + } + ["Table.is_empty"] = { + title = "<code>Table.is_empty (tbl)</code>" + content = function() +%> +<% + end + } + ["Table.pack"] = { + title = "<code>Table.pack (···)</code>" + content = function() +%> <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> +<% + end + } + ["Table.remove"] = { + title = "<code>Table.remove (list, pos)</code>" + content = function() +%> <p> Removes from <code>list</code> the element at position <code>pos</code>, returning the value of the removed element. @@ -2685,15 +2927,21 @@ 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> +<% + end + } + ["Table.size"] = { + title = "<code>Table.size (tbl)</code>" + content = function() +%> +<% + end + } + ["Table.sort"] = { + title = "<code>Table.sort (list [, comp])</code>" + content = function() +%> <p> Sorts list elements in a given order, <em>in-place</em>, from <code>list[1]</code> to <code>list[#list]</code>. @@ -2704,81 +2952,122 @@ (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> <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> +<% + end + } + ["Table.unpack"] = { + title = "<code>Table.unpack (list [, i [, j]])</code>" + content = function() +%> <p> Returns the elements from the given list. This function is equivalent to - +</p> <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> +<% + end + } + } + } + number_lib = { + title = "Number Manipulation" + content = function() +%> <p> Include this library by: - +</p> <pre> local Number = require "luan:Number.luan" </pre> - - -<h4 heading><a name="Number.double" href="#Number.double"><code>Number.double (x)</code></a></h4> +<% + end + subs = { + ["Number.double"] = { + title = "<code>Number.double (x)</code>" + content = function() +%> <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> +<% + end + } + ["Number.float"] = { + title = "<code>Number.float (x)</code>" + content = function() +%> <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> +<% + end + } + ["Number.integer"] = { + title = "<code>Number.integer (x)</code>" + content = function() +%> <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> +<% + end + } + ["Number.long"] = { + title = "<code>Number.long (x)</code>" + content = function() +%> <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> +<% + end + } + ["Number.long_to_string"] = { + title = "<code>Number.long_to_string (i, radix)</code>" + content = function() +%> <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> +<% + end + } + ["Number.type"] = { + title = "<code>Number.type (x)</code>" + content = function() +%> <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> +<% + end + } + } + } + math_lib = { + title = "Mathematical Functions" + content = function() +%> <p> Include this library by: - +</p> <pre> local Math = require "luan:Math.luan" </pre> @@ -2786,169 +3075,213 @@ <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> +<% + end + subs = { + ["Math.abs"] = { + title = "<code>Math.abs (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.acos"] = { + title = "<code>Math.acos (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.asin"] = { + title = "<code>Math.asin (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.atan"] = { + title = "<code>Math.atan (y, x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.ceil"] = { + title = "<code>Math.ceil (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.cos"] = { + title = "<code>Math.cos (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.deg"] = { + title = "<code>Math.deg (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.exp"] = { + title = "<code>Math.exp (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.floor"] = { + title = "<code>Math.floor (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.fmod"] = { + title = "<code>Math.fmod (x, y)</code>" + content = function() +%> <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> +<% + end + } + ["Math.huge"] = { + title = "<code>Math.huge</code>" + content = function() +%> <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> +<% + end + } + ["Math.log"] = { + title = "<code>Math.log (x [, base])</code>" + content = function() +%> <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> +<% + end + } + ["Math.max"] = { + title = "<code>Math.max (x, ···)</code>" + content = function() +%> <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> +<% + end + } + ["Math.max_integer"] = { + title = "<code>Math.max_integer</code>" + content = function() +%> <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> +<% + end + } + ["Math.min"] = { + title = "<code>Math.min (x, ···)</code>" + content = function() +%> <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> +<% + end + } + ["Math.min_integer"] = { + title = "<code>Math.min_integer</code>" + content = function() +%> <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> +<% + end + } + ["Math.modf"] = { + title = "<code>Math.modf (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.pi"] = { + title = "<code>Math.pi</code>" + content = function() +%> <p> The value of <em>π</em>. - - - - -<h4 heading><a name="Math.rad" href="#Math.rad"><code>Math.rad (x)</code></a></h4> - +</p> +<% + end + } + ["Math.rad"] = { + title = "<code>Math.rad (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.random"] = { + title = "<code>Math.random ([m [, n])</code>" + content = function() +%> <p> When called without arguments, returns a pseudo-random float with uniform distribution @@ -2958,1521 +3291,91 @@ 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> <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> +<% + end + } + ["Math.sin"] = { + title = "<code>Math.sin (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.sqrt"] = { + title = "<code>Math.sqrt (x)</code>" + content = function() +%> <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> +<% + end + } + ["Math.tan"] = { + title = "<code>Math.tan (x)</code>" + content = function() +%> <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> +<% + end + } + } + } + } + } +} -<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 ---> - +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>