Mercurial Hosting > luan
changeset 395:a7cb58532846
work on manual
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Fri, 24 Apr 2015 17:42:22 -0600 |
| parents | c3d21bdc83b5 |
| children | ba8b0aae6453 |
| files | website/src/manual.html.luan |
| diffstat | 1 files changed, 164 insertions(+), 323 deletions(-) [+] |
line wrap: on
line diff
--- a/website/src/manual.html.luan Fri Apr 24 14:17:40 2015 -0600 +++ b/website/src/manual.html.luan Fri Apr 24 17:42:22 2015 -0600 @@ -54,6 +54,18 @@ <a href="#stmts">Statements</a> <ul> <li><a href="#blocks">Blocks</a></li> + <li><a href="#chunks">Chunks</a></li> + <li><a href="#assignment">Assignment</a></li> + <li><a href="#control">Control Structures</a></li> + <li><a href="#for">For Statement</a></li> + <li><a href="#fn_stmt">Function Calls as Statements</a></li> + <li><a href="#local_stmt">Local Declarations</a></li> + </ul> + </li> + <li> + <a href="#expressions">Expressions</a> + <ul> + <li><a href="#arithmetic">Arithmetic Operators</a></li> </ul> </li> </ul> @@ -765,7 +777,7 @@ -<h3 margin-top="1em"><a name="blocks">Blocks</a></h3> +<h4 margin-top="1em"><a name="blocks">Blocks</a></h4> <p> A block is a list of statements, @@ -803,68 +815,58 @@ -<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> - -<p> -The unit of compilation of Lua is called a <em>chunk</em>. +<h4 margin-top="1em"><a name="chunks">Chunks</a></h4> + +<p> +The unit of compilation of Luan is called a <i>chunk</i>. Syntactically, a chunk is simply a block: -<pre> +<p><tt><pre> chunk ::= block -</pre> - -<p> -Lua handles a chunk as the body of an anonymous function +</pre></tt></p> + +<p> +Luan handles a chunk as the body of an anonymous function with a variable number of arguments (see <a href="#3.4.11">§3.4.11</a>). As such, chunks can define local variables, receive arguments, and return values. -Moreover, such anonymous function is compiled as in the -scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). -The resulting function always has <code>_ENV</code> as its only upvalue, -even if it does not use that variable. <p> A chunk can be stored in a file or in a string inside the host program. To execute a chunk, -Lua first <em>loads</em> it, -precompiling the chunk's code into instructions for a virtual machine, -and then Lua executes the compiled code -with an interpreter for the virtual machine. - - -<p> -Chunks can also be precompiled into binary form; -see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. -Programs in source and compiled forms are interchangeable; -Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). - - - - - -<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> - -<p> -Lua allows multiple assignments. +Luan first <i>loads</i> it, +compiling the chunk's code, +and then Luan executes the compiled code. + + + + + +<h4 margin-top="1em"><a name="assignment">Assignment</a></h4> + +<p> +Luan allows multiple assignments. Therefore, the syntax for assignment defines a list of variables on the left side and a list of expressions on the right side. The elements in both lists are separated by commas: -<pre> +<p><tt><pre> stat ::= varlist ‘<b>=</b>’ explist varlist ::= var {‘<b>,</b>’ var} explist ::= exp {‘<b>,</b>’ exp} -</pre><p> +</pre></tt></p> + +<p> Expressions are discussed in <a href="#3.4">§3.4</a>. <p> Before the assignment, -the list of values is <em>adjusted</em> to the length of +the list of values is <i>adjusted</i> to the length of the list of variables. If there are more values than needed, the excess values are thrown away. @@ -881,69 +883,74 @@ and only then the assignments are performed. Thus the code -<pre> +<p><tt><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) +</pre></tt></p> + +<p> +sets <tt>a[3]</tt> to 20, without affecting <tt>a[4]</tt> +because the <tt>i</tt> in <tt>a[i]</tt> is evaluated (to 3) before it is assigned 4. Similarly, the line -<pre> +<p><tt><pre> x, y = y, x -</pre><p> -exchanges the values of <code>x</code> and <code>y</code>, +</pre></tt></p> + +<p> +exchanges the values of <tt>x</tt> and <tt>y</tt>, and -<pre> +<p><tt><pre> x, y, z = y, z, x -</pre><p> -cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. +</pre></tt></p> + +<p> +cyclically permutes the values of <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>. <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>. +An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to +<tt>settable_event(t,i,val)</tt>. (See <a href="#2.4">§2.4</a> for a complete description of the -<code>settable_event</code> function. -This function is not defined or callable in Lua. +<tt>settable_event</tt> function. +This function is not defined or callable in Luan. We use it here only for explanatory purposes.) <p> -An assignment to a global name <code>x = val</code> +An assignment to a global name <tt>x = val</tt> is equivalent to the assignment -<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). - - - - - -<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> +<tt>_ENV.x = val</tt> (see <a href="#2.2">§2.2</a>). + + + + +<h4 margin-top="1em"><a name="control">Control Structures</a></h4> + +<p> The control structures <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and familiar syntax: - - - -<pre> +<p><tt><pre> stat ::= <b>while</b> exp <b>do</b> block <b>end</b> stat ::= <b>repeat</b> block <b>until</b> exp stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> -</pre><p> -Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). +</pre></tt></p> + +<p> +Luan also has a <b>for</b> statement (see <a href="#3.3.5">§3.3.5</a>). <p> The condition expression of a -control structure can return any value. -Both <b>false</b> and <b>nil</b> are considered false. -All values different from <b>nil</b> and <b>false</b> are considered true -(in particular, the number 0 and the empty string are also true). +control structure must be a boolean. +Any other value type will produce an error. +This helps catch errors and makes code more readable. <p> @@ -955,41 +962,16 @@ <p> -The <b>goto</b> statement transfers the program control to a label. -For syntactical reasons, -labels in Lua are considered statements too: - - - -<pre> - stat ::= <b>goto</b> Name - stat ::= label - label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ -</pre> - -<p> -A label is visible in the entire block where it is defined, -except -inside nested blocks where a label with the same name is defined and -inside nested functions. -A goto may jump to any visible label as long as it does not -enter into the scope of a local variable. - - -<p> -Labels and empty statements are called <em>void statements</em>, -as they perform no actions. - - -<p> The <b>break</b> statement terminates the execution of a <b>while</b>, <b>repeat</b>, or <b>for</b> loop, skipping to the next statement after the loop: -<pre> +<p><tt><pre> stat ::= <b>break</b> -</pre><p> +</pre></tt></p> + +<p> A <b>break</b> ends the innermost enclosing loop. @@ -1001,63 +983,47 @@ Functions can return more than one value, so the syntax for the <b>return</b> statement is -<pre> +<p><tt><pre> stat ::= <b>return</b> [explist] [‘<b>;</b>’] -</pre> - -<p> -The <b>return</b> statement can only be written -as the last statement of a block. -If it is really necessary to <b>return</b> in the middle of a block, -then an explicit inner block can be used, -as in the idiom <code>do return end</code>, -because now <b>return</b> is the last statement in its (inner) block. - - - - - -<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> - -<p> - -The <b>for</b> statement has two forms: -one numeric and one generic. - - -<p> -The numeric <b>for</b> loop repeats a block of code while a -control variable runs through an arithmetic progression. -It has the following syntax: - -<pre> - stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> -</pre><p> -The <em>block</em> is repeated for <em>name</em> starting at the value of -the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the -third <em>exp</em>. -More precisely, a <b>for</b> statement like - -<pre> - for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end -</pre><p> +</pre></tt></p> + + + + +<h4 margin-top="1em"><a name="for">For Statement</a></h4> + +<p> +The <b>for</b> statement works over functions, +called <i>iterators</i>. +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><tt><pre> + stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b> + namelist ::= Name {‘<b>,</b>’ Name} +</pre></tt></p> + +<p> +A <b>for</b> statement like + +<p><tt><pre> + for <i>var_1</i>, ···, <i>var_n</i> in <i>exp</i> do <i>block</i> end +</pre></tt></p> + +<p> is equivalent to the code: -<pre> +<p><tt><pre> do - local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) - if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end - <em>var</em> = <em>var</em> - <em>step</em> + local <i>f</i> = <i>exp</i> while true do - <em>var</em> = <em>var</em> + <em>step</em> - if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then - break - end - local v = <em>var</em> - <em>block</em> + local <i>var_1</i>, ···, <i>var_n</i> = <i>f</i>() + if <i>var_1</i> == nil then break end + <i>block</i> end end -</pre> +</pre></tt></p> <p> Note the following: @@ -1065,76 +1031,13 @@ <ul> <li> -All three control expressions are evaluated only once, -before the loop starts. -They must all result in numbers. -</li> - -<li> -<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. -The names shown here are for explanatory purposes only. -</li> - -<li> -If the third expression (the step) is absent, -then a step of 1 is used. -</li> - -<li> -You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. +<tt><i>exp</i></tt> is evaluated only once. +Its result is an <i>iterator</i> function. </li> <li> -The loop variable <code>v</code> is local to the loop body. -If you need its value after the loop, -assign it to another variable before exiting the loop. -</li> - -</ul> - -<p> -The generic <b>for</b> statement works over functions, -called <em>iterators</em>. -On each iteration, the iterator function is called to produce a new value, -stopping when this new value is <b>nil</b>. -The generic <b>for</b> loop has the following syntax: - -<pre> - stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> - namelist ::= Name {‘<b>,</b>’ Name} -</pre><p> -A <b>for</b> statement like - -<pre> - for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end -</pre><p> -is equivalent to the code: - -<pre> - do - local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> - while true do - local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) - if <em>var_1</em> == nil then break end - <em>var</em> = <em>var_1</em> - <em>block</em> - end - end -</pre><p> -Note the following: - -<ul> - -<li> -<code><em>explist</em></code> is evaluated only once. -Its results are an <em>iterator</em> function, -a <em>state</em>, -and an initial value for the first <em>iterator variable</em>. -</li> - -<li> -<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. -The names are here for explanatory purposes only. +<tt><i>f</i></tt> is an invisible variable. +The name is here for explanatory purposes only. </li> <li> @@ -1142,7 +1045,7 @@ </li> <li> -The loop variables <code><em>var_i</em></code> are local to the loop; +The loop variables <tt><i>var_i</i></tt> 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. @@ -1153,27 +1056,33 @@ -<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> +<h4 margin-top="1em"><a name="fn_stmt">Function Calls as Statements</a></h4> + +<p> To allow possible side-effects, function calls can be executed as statements: -<pre> +<p><tt><pre> stat ::= functioncall -</pre><p> +</pre></tt></p> + +<p> In this case, all returned values are thrown away. Function calls are explained in <a href="#3.4.10">§3.4.10</a>. - - -<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> +<h4 margin-top="1em"><a name="local_stmt">Local Declarations</a></h4> + +<p> Local variables can be declared anywhere inside a block. The declaration can include an initial assignment: -<pre> +<p><tt><pre> stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] -</pre><p> +</pre></tt></p> + +<p> If present, an initial assignment has the same semantics of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). Otherwise, all variables are initialized with <b>nil</b>. @@ -1190,15 +1099,12 @@ - - - -<h2>3.4 – <a name="3.4">Expressions</a></h2> - -<p> -The basic expressions in Lua are the following: - -<pre> +<h3 margin-top="1em"><a name="expressions">Expressions</a></h3> + +<p> +The basic expressions in Luan are the following: + +<p><tt><pre> exp ::= prefixexp exp ::= <b>nil</b> | <b>false</b> | <b>true</b> exp ::= Numeral @@ -1209,7 +1115,7 @@ exp ::= exp binop exp exp ::= unop exp prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ -</pre> +</pre></tt></p> <p> Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; @@ -1218,18 +1124,16 @@ function calls are explained in <a href="#3.4.10">§3.4.10</a>; table constructors are explained in <a href="#3.4.9">§3.4.9</a>. Vararg expressions, -denoted by three dots ('<code>...</code>'), can only be used when +denoted by three dots ('<tt>...</tt>'), can only be used when directly inside a vararg function; they are explained in <a href="#3.4.11">§3.4.11</a>. <p> Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), -bitwise operators (see <a href="#3.4.2">§3.4.2</a>), relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), -the unary bitwise not (see <a href="#3.4.2">§3.4.2</a>), the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). @@ -1244,7 +1148,7 @@ then no adjustment is made (unless the expression is enclosed in parentheses). In all other contexts, -Lua adjusts the result list to one element, +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. @@ -1252,7 +1156,7 @@ <p> Here are some examples: -<pre> +<p><tt><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() @@ -1269,103 +1173,40 @@ {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> +</pre></tt></p> <p> Any expression enclosed in parentheses always results in only one value. Thus, -<code>(f(x,y,z))</code> is always a single value, -even if <code>f</code> returns several values. -(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> -or <b>nil</b> if <code>f</code> does not return any values.) - - - -<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> -Lua supports the following arithmetic operators: +<tt>(f(x,y,z))</tt> is always a single value, +even if <tt>f</tt> returns several values. +(The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt> +or <b>nil</b> if <tt>f</tt> does not return any values.) + + + +<h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4> + +<p> +Luan supports the following arithmetic operators: <ul> -<li><b><code>+</code>: </b>addition</li> -<li><b><code>-</code>: </b>subtraction</li> -<li><b><code>*</code>: </b>multiplication</li> -<li><b><code>/</code>: </b>float division</li> -<li><b><code>//</code>: </b>floor division</li> -<li><b><code>%</code>: </b>modulo</li> -<li><b><code>^</code>: </b>exponentiation</li> -<li><b><code>-</code>: </b>unary minus</li> +<li><b><tt>+</tt>: </b>addition</li> +<li><b><tt>-</tt>: </b>subtraction</li> +<li><b><tt>*</tt>: </b>multiplication</li> +<li><b><tt>/</tt>: </b>division</li> +<li><b><tt>%</tt>: </b>modulo</li> +<li><b><tt>^</tt>: </b>exponentiation</li> +<li><b><tt>-</tt>: </b>unary minus</li> </ul> <p> -With the exception of exponentiation and float division, -the arithmetic operators work as follows: -If both operands are integers, -the operation is performed over integers and the result is an integer. -Otherwise, if both operands are numbers -or strings that can be converted to -numbers (see <a href="#3.4.3">§3.4.3</a>), -then they are converted to floats, -the operation is performed following the usual rules -for floating-point arithmetic -(usually the IEEE 754 standard), -and the result is a float. - - -<p> -Exponentiation and float division (<code>/</code>) -always convert their operands to floats -and the result is always a float. -Exponentiation uses the ISO C function <code>pow</code>, -so that it works for non-integer exponents too. - - -<p> -Floor division (<code>//</code>) is a division -that rounds the quotient towards minus infinite, -that is, the floor of the division of its operands. - +Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function. <p> Modulo is defined as the remainder of a division that rounds the quotient towards minus infinite (floor division). - - -<p> -In case of overflows in integer arithmetic, -all operations <em>wrap around</em>, -according to the usual rules of two-complement arithmetic. -(In other words, -they return the unique representable integer -that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) - - - -<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> -Lua supports the following bitwise operators: - -<ul> -<li><b><code>&</code>: </b>bitwise and</li> -<li><b><code>|</code>: </b>bitwise or</li> -<li><b><code>~</code>: </b>bitwise exclusive or</li> -<li><b><code>>></code>: </b>right shift</li> -<li><b><code><<</code>: </b>left shift</li> -<li><b><code>~</code>: </b>unary bitwise not</li> -</ul> - -<p> -All bitwise operations convert its operands to integers -(see <a href="#3.4.3">§3.4.3</a>), -operate on all bits of those integers, -and result in an integer. - - -<p> -Both right and left shifts fill the vacant bits with zeros. -Negative displacements shift to the other direction; -displacements with absolute values equal to or higher than -the number of bits in an integer -result in zero (as all bits are shifted out). - - +(The Java modulo operator is not used.)