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

comparison 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

comparison

equal deleted inserted replaced

-:c3d21bdc83b5
+:a7cb58532846
 		<li><a href="#vars">Variables</a></li>
 		<li>
 			<a href="#stmts">Statements</a>
 			<ul>
 				<li><a href="#blocks">Blocks</a></li>
+				<li><a href="#chunks">Chunks</a></li>
+				<li><a href="#assignment">Assignment</a></li>
+				<li><a href="#control">Control Structures</a></li>
+				<li><a href="#for">For Statement</a></li>
+				<li><a href="#fn_stmt">Function Calls as Statements</a></li>
+				<li><a href="#local_stmt">Local Declarations</a></li>
+			</ul>
+		</li>
+		<li>
+			<a href="#expressions">Expressions</a>
+			<ul>
+				<li><a href="#arithmetic">Arithmetic Operators</a></li>
 			</ul>
 		</li>
 	</ul>
 </div>
 assignments, control structures, function calls,
 and variable declarations.
-<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,
 which are executed sequentially:
-<h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
+<h4 margin-top="1em"><a name="chunks">Chunks</a></h4>
 <p>
-The unit of compilation of Lua is called a <em>chunk</em>.
+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>
+</pre></tt></p>
 <p>
-Lua handles a chunk as the body of an anonymous function
+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,
+Luan first <i>loads</i> it,
-precompiling the chunk's code into instructions for a virtual machine,
+compiling the chunk's code,
-and then Lua executes the compiled code
+and then Luan 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.
+<h4 margin-top="1em"><a name="assignment">Assignment</a></h4>
-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>).
+<p>
+Luan allows multiple assignments.
-<h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
-<p>
-Lua 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.
 If there are fewer values than needed,
 the list is extended with as many  <b>nil</b>'s as needed.
 <p>
 The assignment statement first evaluates all its expressions
 and only then the assignments are performed.
 Thus the code
-<pre>
+<p><tt><pre>
 i = 3
 i, a[i] = i+1, 20
-</pre><p>
+</pre></tt></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)
+<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>
+</pre></tt></p>
-exchanges the values of <code>x</code> and <code>y</code>,
+<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>
+</pre></tt></p>
-cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
+<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
+An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to
-<code>settable_event(t,i,val)</code>.
+<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.
+<tt>settable_event</tt> function.
-This function is not defined or callable in Lua.
+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>).
+<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>
-<h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
+<p>
 The control structures
 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
 familiar syntax:
+<p><tt><pre>
-<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>
+</pre></tt></p>
-Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
+<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.
+control structure must be a boolean.
-Both <b>false</b> and <b>nil</b> are considered false.
+Any other value type will produce an error.
-All values different from <b>nil</b> and <b>false</b> are considered true
+This helps catch errors and makes code more readable.
-(in particular, the number 0 and the empty string are also true).
 <p>
 In the <b>repeat</b>&ndash;<b>until</b> loop,
 the inner block does not end at the <b>until</b> keyword,
 So, the condition can refer to local variables
 declared inside the loop block.
 <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.
 <p>
 The <b>return</b> statement is used to return values
 (which is an anonymous function).
 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>
+</pre></tt></p>
-<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,
+<h4 margin-top="1em"><a name="for">For Statement</a></h4>
-then an explicit inner block can be used,
-as in the idiom <code>do return end</code>,
+<p>
-because now <b>return</b> is the last statement in its (inner) block.
+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:
-<h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
+<p><tt><pre>
+	stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b>
-<p>
+	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
+</pre></tt></p>
-The <b>for</b> statement has two forms:
-one numeric and one generic.
+<p>
+A <b>for</b> statement like
-<p>
+<p><tt><pre>
-The numeric <b>for</b> loop repeats a block of code while a
+for <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> in <i>exp</i> do <i>block</i> end
-control variable runs through an arithmetic progression.
+</pre></tt></p>
-It has the following syntax:
+<p>
-<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>
 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>)
+local <i>f</i> = <i>exp</i>
-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>
 while true do
-<em>var</em> = <em>var</em> + <em>step</em>
+local <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> = <i>f</i>()
-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
+if <i>var_1</i> == nil then break end
-break
+<i>block</i>
-end
-local v = <em>var</em>
-<em>block</em>
 end
 end
-</pre>
+</pre></tt></p>
 <p>
 Note the following:
 <ul>
 <li>
-All three control expressions are evaluated only once,
+<tt><i>exp</i></tt> is evaluated only once.
-before the loop starts.
+Its result is an <i>iterator</i> function.
-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.
+<tt><i>f</i></tt> is an invisible variable.
-The names shown here are for explanatory purposes only.
+The name is here 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.
-</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.
 </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;
+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.
 </li>
 </ul>
-<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>.
+<h4 margin-top="1em"><a name="local_stmt">Local Declarations</a></h4>
-<h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
+<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>.
 The visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
+<h3 margin-top="1em"><a name="expressions">Expressions</a></h3>
+<p>
-<h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
+The basic expressions in Luan are the following:
-<p>
+<p><tt><pre>
-The basic expressions in Lua are the following:
-<pre>
 	exp ::= prefixexp
 	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
 	exp ::= Numeral
 	exp ::= LiteralString
 	exp ::= functiondef
 	exp ::= tableconstructor
 	exp ::= &lsquo;<b>...</b>&rsquo;
 	exp ::= exp binop exp
 	exp ::= unop exp
 	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
-</pre>
+</pre></tt></p>
 <p>
 Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
 variables are explained in <a href="#3.2">&sect;3.2</a>;
 function definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
 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>).
 <p>
 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,
-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.
 <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()
 a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
 a,b = ...          -- a gets the first vararg parameter, b gets
 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>
+</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,
+<tt>(f(x,y,z))</tt> is always a single value,
-even if <code>f</code> returns several values.
+even if <tt>f</tt> returns several values.
-(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
+(The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt>
-or <b>nil</b> if <code>f</code> does not return any values.)
+or <b>nil</b> if <tt>f</tt> does not return any values.)
-<h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
+<h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4>
-Lua supports the following arithmetic operators:
+<p>
+Luan supports the following arithmetic operators:
 <ul>
-<li><b><code>+</code>: </b>addition</li>
+<li><b><tt>+</tt>: </b>addition</li>
-<li><b><code>-</code>: </b>subtraction</li>
+<li><b><tt>-</tt>: </b>subtraction</li>
-<li><b><code>*</code>: </b>multiplication</li>
+<li><b><tt>*</tt>: </b>multiplication</li>
-<li><b><code>/</code>: </b>float division</li>
+<li><b><tt>/</tt>: </b>division</li>
-<li><b><code>//</code>: </b>floor division</li>
+<li><b><tt>%</tt>: </b>modulo</li>
-<li><b><code>%</code>: </b>modulo</li>
+<li><b><tt>^</tt>: </b>exponentiation</li>
-<li><b><code>^</code>: </b>exponentiation</li>
+<li><b><tt>-</tt>: </b>unary minus</li>
-<li><b><code>-</code>: </b>unary minus</li>
 </ul>
 <p>
-With the exception of exponentiation and float division,
+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.
-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.
 <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>
-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).
 <h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
 Lua provides some automatic conversions between some

Mercurial Hosting > luan

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