changeset 1660:2968e43cdd44

manual work
author Franklin Schmidt <fschmidt@gmail.com>
date Tue, 19 Apr 2022 23:46:06 -0600
parents 500c706ed4ea
children 08177ced7fa0
files website/src/diff.html.luan website/src/m.html.luan website/src/site.css
diffstat 3 files changed, 461 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/website/src/diff.html.luan	Tue Apr 19 13:26:33 2022 -0600
+++ b/website/src/diff.html.luan	Tue Apr 19 23:46:06 2022 -0600
@@ -98,7 +98,7 @@
 %>
 <p>Unlike Lua, 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>Luan has exactly the same set of keywords as Lua and has the same other lexical conventions.</p>
+<p>Luan has a similar set of keywords to Lua and has the same other lexical conventions.</p>
 <%
 				end
 			}
--- a/website/src/m.html.luan	Tue Apr 19 13:26:33 2022 -0600
+++ b/website/src/m.html.luan	Tue Apr 19 23:46:06 2022 -0600
@@ -917,6 +917,465 @@
 <%
 						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>&ndash;<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] [&lsquo;<b>;</b>&rsquo;]
+</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 {&lsquo;<b>,</b>&rsquo; 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>, &middot;&middot;&middot;, <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>, &middot;&middot;&middot;, <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 [&lsquo;<b>=</b>&rsquo; 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"
+	%&gt;
+	Hello &lt;%= name %&gt;!
+	Bye &lt;%= name %&gt;.
+	&lt;%
+</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 ::= &lsquo;<b>...</b>&rsquo;
+	exp ::= exp binop exp
+	exp ::= unop exp
+	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
+</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>&lt;</code>: </b>less than</li>
+	<li><b><code>&gt;</code>: </b>greater than</li>
+	<li><b><code>&lt;=</code>: </b>less or equal</li>
+	<li><b><code>&gt;=</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 &gt; b</code> is translated to <code>b &lt; a</code>
+and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
+</p>
+<%
+						end
+					}
 				}
 			}
 		}
--- a/website/src/site.css	Tue Apr 19 13:26:33 2022 -0600
+++ b/website/src/site.css	Tue Apr 19 23:46:06 2022 -0600
@@ -23,6 +23,7 @@
 [content] {
 	margin-left: 3%;
 	margin-right: 3%;
+	margin-bottom: 2em;
 }
 
 [small] {