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

comparison website/src/manual.html @ 380:6c6c3537035e

work on manual

author	Franklin Schmidt <fschmidt@gmail.com>
date	Wed, 22 Apr 2015 13:10:48 -0600
parents	571057b1666b
children	8557581740db

comparison

equal deleted inserted replaced

-:e9e445e28f0b
+:6c6c3537035e
 	<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 margin-bottom="1em">
+	<a href="#lang">The Language</a>
+	<ul>
+		<li><a href="#lex">Lexical Conventions</a></li>
+		<li><a href="#vars">Variables</a></li>
 	</ul>
 </div>
 <hr/>
 </ul>
-<h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
+<h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
 <p>
-Lua performs automatic memory management.
+Luan uses Java's garbage collection.
-This means that
-you do not have to worry about allocating memory for new objects
-or freeing it when the objects are no longer needed.
-Lua manages memory automatically by running
-a <em>garbage collector</em> to collect all <em>dead objects</em>
-(that is, objects that are no longer accessible from Lua).
+<h2 margin-top="1em"><a name="lang">The Language</a></h2>
-All memory used by Lua is subject to automatic management:
-strings, tables, userdata, functions, threads, internal structures, etc.
+<p>
+This section describes the lexis, the syntax, and the semantics of Luan.
-<p>
-Lua implements an incremental mark-and-sweep collector.
-It uses two numbers to control its garbage-collection cycles:
-the <em>garbage-collector pause</em> and
-the <em>garbage-collector step multiplier</em>.
-Both use percentage points as units
-(e.g., a value of 100 means an internal value of 1).
-<p>
-The garbage-collector pause
-controls how long the collector waits before starting a new cycle.
-Larger values make the collector less aggressive.
-Values smaller than 100 mean the collector will not wait to
-start a new cycle.
-A value of 200 means that the collector waits for the total memory in use
-to double before starting a new cycle.
-<p>
-The garbage-collector step multiplier
-controls the relative speed of the collector relative to
-memory allocation.
-Larger values make the collector more aggressive but also increase
-the size of each incremental step.
-You should not use values smaller than 100,
-because they make the collector too slow and
-can result in the collector never finishing a cycle.
-The default is 200,
-which means that the collector runs at "twice"
-the speed of memory allocation.
-<p>
-If you set the step multiplier to a very large number
-(larger than 10% of the maximum number of
-bytes that the program may use),
-the collector behaves like a stop-the-world collector.
-If you then set the pause to 200,
-the collector behaves as in old Lua versions,
-doing a complete collection every time Lua doubles its
-memory usage.
-<p>
-You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
-or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
-You can also use these functions to control
-the collector directly (e.g., stop and restart it).
-<h3>2.5.1 &ndash; <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
-<p>
-You can set garbage-collector metamethods for tables
-and, using the C&nbsp;API,
-for full userdata (see <a href="#2.4">&sect;2.4</a>).
-These metamethods are also called <em>finalizers</em>.
-Finalizers allow you to coordinate Lua's garbage collection
-with external resource management
-(such as closing files, network or database connections,
-or freeing your own memory).
-<p>
-For an object (table or userdata) to be finalized when collected,
-you must <em>mark</em> it for finalization.
-You mark an object for finalization when you set its metatable
-and the metatable has a field indexed by the string "<code>__gc</code>".
-Note that if you set a metatable without a <code>__gc</code> field
-and later create that field in the metatable,
-the object will not be marked for finalization.
-However, after an object has been marked,
-you can freely change the <code>__gc</code> field of its metatable.
-<p>
-When a marked object becomes garbage,
-it is not collected immediately by the garbage collector.
-Instead, Lua puts it in a list.
-After the collection,
-Lua goes through that list.
-For each object in the list,
-it checks the object's <code>__gc</code> metamethod:
-If it is a function,
-Lua calls it with the object as its single argument;
-if the metamethod is not a function,
-Lua simply ignores it.
-<p>
-At the end of each garbage-collection cycle,
-the finalizers for objects are called in
-the reverse order that the objects were marked for finalization,
-among those collected in that cycle;
-that is, the first finalizer to be called is the one associated
-with the object marked last in the program.
-The execution of each finalizer may occur at any point during
-the execution of the regular code.
-<p>
-Because the object being collected must still be used by the finalizer,
-that object (and other objects accessible only through it)
-must be <em>resurrected</em> by Lua.
-Usually, this resurrection is transient,
-and the object memory is freed in the next garbage-collection cycle.
-However, if the finalizer stores the object in some global place
-(e.g., a global variable),
-then the resurrection is permanent.
-Moreover, if the finalizer marks a finalizing object for finalization again,
-its finalizer will be called again in the next cycle where the
-object is unreachable.
-In any case,
-the object memory is freed only in the GC cycle where
-the object is unreachable and not marked for finalization.
-<p>
-When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
-Lua calls the finalizers of all objects marked for finalization,
-following the reverse order that they were marked.
-If any finalizer marks objects for collection during that phase,
-these marks have no effect.
-<h3>2.5.2 &ndash; <a name="2.5.2">Weak Tables</a></h3>
-<p>
-A <em>weak table</em> is a table whose elements are
-<em>weak references</em>.
-A weak reference is ignored by the garbage collector.
-In other words,
-if the only references to an object are weak references,
-then the garbage collector will collect that object.
-<p>
-A weak table can have weak keys, weak values, or both.
-A table with weak keys allows the collection of its keys,
-but prevents the collection of its values.
-A table with both weak keys and weak values allows the collection of
-both keys and values.
-In any case, if either the key or the value is collected,
-the whole pair is removed from the table.
-The weakness of a table is controlled by the
-<code>__mode</code> field of its metatable.
-If the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
-the keys in the table are weak.
-If <code>__mode</code> contains '<code>v</code>',
-the values in the table are weak.
-<p>
-A table with weak keys and strong values
-is also called an <em>ephemeron table</em>.
-In an ephemeron table,
-a value is considered reachable only if its key is reachable.
-In particular,
-if the only reference to a key comes through its value,
-the pair is removed.
-<p>
-Any change in the weakness of a table may take effect only
-at the next collect cycle.
-In particular, if you change the weakness to a stronger mode,
-Lua may still collect some items from that table
-before the change takes effect.
-<p>
-Only objects that have an explicit construction
-are removed from weak tables.
-Values, such as numbers and light C functions,
-are not subject to garbage collection,
-and therefore are not removed from weak tables
-(unless their associated values are collected).
-Although strings are subject to garbage collection,
-they do not have an explicit construction,
-and therefore are not removed from weak tables.
-<p>
-Resurrected objects
-(that is, objects being finalized
-and objects accessible only through objects being finalized)
-have a special behavior in weak tables.
-They are removed from weak values before running their finalizers,
-but are removed from weak keys only in the next collection
-after running their finalizers, when such objects are actually freed.
-This behavior allows the finalizer to access properties
-associated with the object through weak tables.
-<p>
-If a weak table is among the resurrected objects in a collection cycle,
-it may not be properly cleared until the next cycle.
-<h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
-<p>
-Lua supports coroutines,
-also called <em>collaborative multithreading</em>.
-A coroutine in Lua represents an independent thread of execution.
-Unlike threads in multithread systems, however,
-a coroutine only suspends its execution by explicitly calling
-a yield function.
-<p>
-You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
-Its sole argument is a function
-that is the main function of the coroutine.
-The <code>create</code> function only creates a new coroutine and
-returns a handle to it (an object of type <em>thread</em>);
-it does not start the coroutine.
-<p>
-You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
-When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
-passing as its first argument
-a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
-the coroutine starts its execution,
-at the first line of its main function.
-Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
-as arguments to the coroutine's main function.
-After the coroutine starts running,
-it runs until it terminates or <em>yields</em>.
-<p>
-A coroutine can terminate its execution in two ways:
-normally, when its main function returns
-(explicitly or implicitly, after the last instruction);
-and abnormally, if there is an unprotected error.
-In case of normal termination,
-<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
-plus any values returned by the coroutine main function.
-In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
-plus an error message.
-<p>
-A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
-When a coroutine yields,
-the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
-even if the yield happens inside nested function calls
-(that is, not in the main function,
-but in a function directly or indirectly called by the main function).
-In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
-plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
-The next time you resume the same coroutine,
-it continues its execution from the point where it yielded,
-with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
-arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
-<p>
-Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
-the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
-but instead of returning the coroutine itself,
-it returns a function that, when called, resumes the coroutine.
-Any arguments passed to this function
-go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
-<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
-except the first one (the boolean error code).
-Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
-<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
-any error is propagated to the caller.
-<p>
-As an example of how coroutines work,
-consider the following code:
-<pre>
-function foo (a)
-print("foo", a)
-return coroutine.yield(2*a)
-end
-co = coroutine.create(function (a,b)
-print("co-body", a, b)
-local r = foo(a+1)
-print("co-body", r)
-local r, s = coroutine.yield(a+b, a-b)
-print("co-body", r, s)
-return b, "end"
-end)
-print("main", coroutine.resume(co, 1, 10))
-print("main", coroutine.resume(co, "r"))
-print("main", coroutine.resume(co, "x", "y"))
-print("main", coroutine.resume(co, "x", "y"))
-</pre><p>
-When you run it, it produces the following output:
-<pre>
-co-body 1       10
-foo     2
-main    true    4
-co-body r
-main    true    11      -9
-co-body x       y
-main    true    10      end
-main    false   cannot resume dead coroutine
-</pre>
-<p>
-You can also create and manipulate coroutines through the C API:
-see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
-and <a href="#lua_yield"><code>lua_yield</code></a>.
-<h1>3 &ndash; <a name="3">The Language</a></h1>
-<p>
-This section describes the lexis, the syntax, and the semantics of Lua.
 In other words,
 this section describes
 which tokens are valid,
 how they can be combined,
 and what their combinations mean.
 <p>
 Language constructs will be explained using the usual extended BNF notation,
 in which
-{<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
+{<i>a</i>}&nbsp;means&nbsp;0 or more <i>a</i>'s, and
-[<em>a</em>]&nbsp;means an optional <em>a</em>.
+[<i>a</i>]&nbsp;means an optional <i>a</i>.
 Non-terminals are shown like non-terminal,
 keywords are shown like <b>kword</b>,
 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
-The complete syntax of Lua can be found in <a href="#9">&sect;9</a>
+The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
 at the end of this manual.
-<h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
+<h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
 <p>
-Lua is a free-form language.
+Luan ignores spaces and comments
-It ignores spaces (including new lines) and comments
 between lexical elements (tokens),
 except as delimiters between names and keywords.
+Luan generally considers the end of a line to be the end of a statement.  This catches errors and encourages readability.  The exception to this is in paranthesis ( <i>(...)</i>, <i>[...]</i>, and <i>{...}</i> ) where the end of line is treated as white space.
 <p>
-<em>Names</em>
+<i>Names</i>
-(also called <em>identifiers</em>)
+(also called <i>identifiers</i>)
-in Lua can be any string of letters,
+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>
-The following <em>keywords</em> are reserved
+The following <i>keywords</i> are reserved
 and cannot be used as names:
 <pre>
 and       break     do        else      elseif    end
 local     nil       not       or        repeat    return
 then      true      until     while
 </pre>
 <p>
-Lua is a case-sensitive language:
+Luan is a case-sensitive language:
-<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
+<tt>and</tt> is a reserved word, but <tt>And</tt> and <tt>AND</tt>
 are two different, valid names.
-As a convention,
-programs should avoid creating
-names that start with an underscore followed by
-one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
 <p>
 The following strings denote other tokens:
 +     -     *     /     %     ^     #
 &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
 ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
 (     )     {     }     [     ]     ::
 ;     :     ,     .     ..    ...
 </pre>
 <p>
-<em>Literal strings</em>
+<i>Literal strings</i>
 can be delimited by matching single or double quotes,
 and can contain the following C-like escape sequences:
-'<code>\a</code>' (bell),
+'<tt>\a</tt>' (bell),
-'<code>\b</code>' (backspace),
+'<tt>\b</tt>' (backspace),
-'<code>\f</code>' (form feed),
+'<tt>\f</tt>' (form feed),
-'<code>\n</code>' (newline),
+'<tt>\n</tt>' (newline),
-'<code>\r</code>' (carriage return),
+'<tt>\r</tt>' (carriage return),
-'<code>\t</code>' (horizontal tab),
+'<tt>\t</tt>' (horizontal tab),
-'<code>\v</code>' (vertical tab),
+'<tt>\v</tt>' (vertical tab),
-'<code>\\</code>' (backslash),
+'<tt>\\</tt>' (backslash),
-'<code>\"</code>' (quotation mark [double quote]),
+'<tt>\"</tt>' (quotation mark [double quote]),
-and '<code>\'</code>' (apostrophe [single quote]).
+and '<tt>\'</tt>' (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
+The escape sequence '<tt>\z</tt>' 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>
-Strings in Lua can contain any 8-bit value, including embedded zeros,
+Luan can specify any character in a literal string by its numerical value.
-which can be specified as '<code>\0</code>'.
-More generally,
-we can specify any byte in a literal string by its numerical value.
 This can be done
-with the escape sequence <code>\x<em>XX</em></code>,
+with the escape sequence <tt>\x<i>XX</i></tt>,
-where <em>XX</em> is a sequence of exactly two hexadecimal digits,
+where <i>XX</i> is a sequence of exactly two hexadecimal digits,
-or with the escape sequence <code>\<em>ddd</em></code>,
+or with the escape sequence <tt>\<i>ddd</i></tt>,
-where <em>ddd</em> is a sequence of up to three decimal digits.
+where <i>ddd</i> 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>
-The UTF-8 encoding of a Unicode character
-can be inserted in a literal string with
-the escape sequence <code>\u{<em>XXX</em>}</code>
-(note the mandatory enclosing brackets),
-where <em>XXX</em> is a sequence of one or more hexadecimal digits
-representing the character code point.
-<p>
 Literal strings can also be defined using a long format
-enclosed by <em>long brackets</em>.
+enclosed by <i>long brackets</i>.
-We define an <em>opening long bracket of level <em>n</em></em> as an opening
+We define an <i>opening long bracket of level <i>n</i></i> as an opening
-square bracket followed by <em>n</em> equal signs followed by another
+square bracket followed by <i>n</i> equal signs followed by another
 opening square bracket.
-So, an opening long bracket of level&nbsp;0 is written as <code>[[</code>,
+So, an opening long bracket of level 0 is written as <tt>[[</tt>,
-an opening long bracket of level&nbsp;1 is written as <code>[=[</code>,
+an opening long bracket of level 1 is written as <tt>[=[</tt>,
 and so on.
-A <em>closing long bracket</em> is defined similarly;
+A <i>closing long bracket</i> is defined similarly;
 for instance,
-a closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
+a closing long bracket of level 4 is written as  <tt>]====]</tt>.
-A <em>long literal</em> starts with an opening long bracket of any level and
+A <i>long literal</i> 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.
 or newline followed by carriage return)
 is converted to a simple newline.
 <p>
-Any byte in a literal string not
+Any character in a literal string not
 explicitly affected by the previous rules represents itself.
-However, Lua opens files for parsing in text mode,
+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>
 For convenience,
 when the opening long bracket is immediately followed by a newline,
 the newline is not included in the string.
-As an example, in a system using ASCII
+As an example
-(in which '<code>a</code>' is coded as&nbsp;97,
-newline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
 the five literal strings below denote the same string:
 <pre>
 a = 'alo\n123"'
 a = "alo\n123\""
 a = [[alo
 123"]]
 a = [==[
 alo
 123"]==]
 </pre>
 <p>
-A <em>numerical constant</em> (or <em>numeral</em>)
+A <i>numerical constant</i> (or <i>numeral</i>)
 can be written with an optional fractional part
 and an optional decimal exponent,
-marked by a letter '<code>e</code>' or '<code>E</code>'.
+marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
-Lua also accepts hexadecimal constants,
+Luan also accepts hexadecimal constants,
-which start with <code>0x</code> or <code>0X</code>.
+which start with <tt>0x</tt> or <tt>0X</tt>.
 Hexadecimal constants also accept an optional fractional part
 plus an optional binary exponent,
-marked by a letter '<code>p</code>' or '<code>P</code>'.
+marked by a letter '<tt>p</tt>' or '<tt>P</tt>'.
 A numeric constant with a fractional dot or an exponent
 denotes a float;
 otherwise it denotes an integer.
 Examples of valid integer constants are
 <pre>
 3   345   0xff   0xBEBADA
 </pre><p>
 Examples of valid float constants are
 <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>)
+A <i>comment</i> starts with a double hyphen (<tt>--</tt>)
 anywhere outside a string.
-If the text immediately after <code>--</code> is not an opening long bracket,
+If the text immediately after <tt>--</tt> is not an opening long bracket,
-the comment is a <em>short comment</em>,
+the comment is a <i>short comment</i>,
 which runs until the end of the line.
-Otherwise, it is a <em>long comment</em>,
+Otherwise, it is a <i>long comment</i>,
 which runs until the corresponding closing long bracket.
 Long comments are frequently used to disable code temporarily.
-<h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
+<h3 margin-top="1em"><a name="vars">Variables</a></h3>
 <p>
 Variables are places that store values.
-There are three kinds of variables in Lua:
+There are three kinds of variables in Luan:
 global variables, local variables, and table fields.
 <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):
 <pre>
 	var ::= Name
 </pre><p>
 Name denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
 <p>
 Any variable name is assumed to be global unless explicitly declared
 as a local (see <a href="#3.3.7">&sect;3.3.7</a>).
-Local variables are <em>lexically scoped</em>:
+Local variables are <i>lexically scoped</i>:
 local variables can be freely accessed by functions
 defined inside their scope (see <a href="#3.5">&sect;3.5</a>).
 <p>
 <p>
 Square brackets are used to index a table:
 <pre>
 	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
 </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
+An access to an indexed variable <tt>t[i]</tt> is equivalent to
-a call <code>gettable_event(t,i)</code>.
+a call <tt>gettable_event(t,i)</tt>.
 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
-<code>gettable_event</code> function.
+<tt>gettable_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>
-The syntax <code>var.Name</code> is just syntactic sugar for
+The syntax <tt>var.Name</tt> is just syntactic sugar for
-<code>var["Name"]</code>:
+<tt>var["Name"]</tt>:
 <pre>
 	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
 </pre>
 <p>
-An access to a global variable <code>x</code>
+An access to a global variable <tt>x</tt>
-is equivalent to <code>_ENV.x</code>.
+is equivalent to <tt>_ENV.x</tt>.
 Due to the way that chunks are compiled,
-<code>_ENV</code> is never a global name (see <a href="#2.2">&sect;2.2</a>).
+<tt>_ENV</tt> is never a global name (see <a href="#2.2">&sect;2.2</a>).

Mercurial Hosting > luan

comparison website/src/manual.html @ 380:6c6c3537035e