diff website/src/manual.html.luan @ 395:a7cb58532846

work on manual
author Franklin Schmidt <fschmidt@gmail.com>
date Fri, 24 Apr 2015 17:42:22 -0600
parents 2f5cc9c2cbf0
children ba8b0aae6453
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 &ndash; <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">&sect;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">&sect;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 &ndash; <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 &lsquo;<b>=</b>&rsquo; explist
 	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
 	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
-</pre><p>
+</pre></tt></p>
+
+<p>
 Expressions are discussed in <a href="#3.4">&sect;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&nbsp;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">&sect;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">&sect;2.2</a>).
-
-
-
-
-
-<h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
+<tt>_ENV.x = val</tt> (see <a href="#2.2">&sect;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">&sect;3.3.5</a>).
+</pre></tt></p>
+
+<p>
+Luan also has a <b>for</b> statement (see <a href="#3.3.5">&sect;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 ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
-</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] [&lsquo;<b>;</b>&rsquo;]
-</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 &ndash; <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 &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; 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 {&lsquo;<b>,</b>&rsquo; Name}
+</pre></tt></p>
+
+<p>
+A <b>for</b> statement like
+
+<p><tt><pre>
+     for <i>var_1</i>, &middot;&middot;&middot;, <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> &gt;= 0 and <em>var</em> &gt; <em>limit</em>) or (<em>step</em> &lt; 0 and <em>var</em> &lt; <em>limit</em>) then
-           break
-         end
-         local v = <em>var</em>
-         <em>block</em>
+         local <i>var_1</i>, &middot;&middot;&middot;, <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&nbsp;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 {&lsquo;<b>,</b>&rsquo; Name}
-</pre><p>
-A <b>for</b> statement like
-
-<pre>
-     for <em>var_1</em>, &middot;&middot;&middot;, <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>, &middot;&middot;&middot;, <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 &ndash; <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">&sect;3.4.10</a>.
 
 
 
-
-
-<h3>3.3.7 &ndash; <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 [&lsquo;<b>=</b>&rsquo; 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">&sect;3.3.3</a>).
 Otherwise, all variables are initialized with <b>nil</b>.
@@ -1190,15 +1099,12 @@
 
 
 
-
-
-
-<h2>3.4 &ndash; <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 | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
-</pre>
+</pre></tt></p>
 
 <p>
 Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
@@ -1218,18 +1124,16 @@
 function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
 table constructors are explained in <a href="#3.4.9">&sect;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">&sect;3.4.11</a>.
 
 
 <p>
 Binary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
-bitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
 relational operators (see <a href="#3.4.4">&sect;3.4.4</a>), logical operators (see <a href="#3.4.5">&sect;3.4.5</a>),
 and the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
 Unary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
-the unary bitwise not (see <a href="#3.4.2">&sect;3.4.2</a>),
 the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
 and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;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 &ndash; <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">&sect;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&nbsp;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 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
-Lua supports the following bitwise operators:
-
-<ul>
-<li><b><code>&amp;</code>: </b>bitwise and</li>
-<li><b><code>&#124;</code>: </b>bitwise or</li>
-<li><b><code>~</code>: </b>bitwise exclusive or</li>
-<li><b><code>&gt;&gt;</code>: </b>right shift</li>
-<li><b><code>&lt;&lt;</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">&sect;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.)