Mercurial Hosting > luan
diff 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 |
line wrap: on
line diff
--- a/website/src/manual.html Mon Apr 20 12:24:54 2015 -0600 +++ b/website/src/manual.html Wed Apr 22 13:10:48 2015 -0600 @@ -42,6 +42,15 @@ <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> @@ -465,354 +474,19 @@ -<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> - -<p> -Lua performs automatic memory management. -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). -All memory used by Lua is subject to automatic management: -strings, tables, userdata, functions, threads, internal structures, etc. - - -<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 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> - -<p> -You can set garbage-collector metamethods for tables -and, using the C API, -for full userdata (see <a href="#2.4">§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 – <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 '<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 – <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 – <a name="3">The Language</a></h1> - -<p> -This section describes the lexis, the syntax, and the semantics of Lua. +<h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3> + +<p> +Luan uses Java's garbage collection. + + + + + +<h2 margin-top="1em"><a name="lang">The Language</a></h2> + +<p> +This section describes the lexis, the syntax, and the semantics of Luan. In other words, this section describes which tokens are valid, @@ -823,36 +497,35 @@ <p> Language constructs will be explained using the usual extended BNF notation, in which -{<em>a</em>} means 0 or more <em>a</em>'s, and -[<em>a</em>] means an optional <em>a</em>. +{<i>a</i>} means 0 or more <i>a</i>'s, and +[<i>a</i>] 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 ‘<b>=</b>’. -The complete syntax of Lua can be found in <a href="#9">§9</a> +The complete syntax of Luan can be found in <a href="#9">§9</a> at the end of this manual. -<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> - -<p> -Lua is a free-form language. -It ignores spaces (including new lines) and comments +<h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3> + +<p> +Luan ignores spaces and comments between lexical elements (tokens), except as delimiters between names and keywords. - - -<p> -<em>Names</em> -(also called <em>identifiers</em>) -in Lua can be any string of letters, +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> +<i>Names</i> +(also called <i>identifiers</i>) +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: @@ -864,13 +537,9 @@ </pre> <p> -Lua is a case-sensitive language: -<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> +Luan is a case-sensitive language: +<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> @@ -882,25 +551,26 @@ == ~= <= >= < > = ( ) { } [ ] :: ; : , . .. ... + </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), -'<code>\b</code>' (backspace), -'<code>\f</code>' (form feed), -'<code>\n</code>' (newline), -'<code>\r</code>' (carriage return), -'<code>\t</code>' (horizontal tab), -'<code>\v</code>' (vertical tab), -'<code>\\</code>' (backslash), -'<code>\"</code>' (quotation mark [double quote]), -and '<code>\'</code>' (apostrophe [single quote]). +'<tt>\a</tt>' (bell), +'<tt>\b</tt>' (backspace), +'<tt>\f</tt>' (form feed), +'<tt>\n</tt>' (newline), +'<tt>\r</tt>' (carriage return), +'<tt>\t</tt>' (horizontal tab), +'<tt>\v</tt>' (vertical tab), +'<tt>\\</tt>' (backslash), +'<tt>\"</tt>' (quotation mark [double 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 @@ -909,41 +579,29 @@ <p> -Strings in Lua can contain any 8-bit value, including embedded zeros, -which can be specified as '<code>\0</code>'. -More generally, -we can specify any byte in a literal string by its numerical value. +Luan can specify any character in a literal string by its numerical value. This can be done -with the escape sequence <code>\x<em>XX</em></code>, -where <em>XX</em> is a sequence of exactly two hexadecimal digits, -or with the escape sequence <code>\<em>ddd</em></code>, -where <em>ddd</em> is a sequence of up to three decimal digits. +with the escape sequence <tt>\x<i>XX</i></tt>, +where <i>XX</i> is a sequence of exactly two hexadecimal digits, +or with the escape sequence <tt>\<i>ddd</i></tt>, +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>. -We define an <em>opening long bracket of level <em>n</em></em> as an opening -square bracket followed by <em>n</em> equal signs followed by another +enclosed by <i>long brackets</i>. +We define an <i>opening long bracket of level <i>n</i></i> as an opening +square bracket followed by <i>n</i> equal signs followed by another opening square bracket. -So, an opening long bracket of level 0 is written as <code>[[</code>, -an opening long bracket of level 1 is written as <code>[=[</code>, +So, an opening long bracket of level 0 is written as <tt>[[</tt>, +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 4 is written as <code>]====]</code>. -A <em>long literal</em> starts with an opening long bracket of any level and +a closing long bracket of level 4 is written as <tt>]====]</tt>. +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, @@ -956,9 +614,9 @@ <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 @@ -970,9 +628,7 @@ 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 -(in which '<code>a</code>' is coded as 97, -newline is coded as 10, and '<code>1</code>' is coded as 49), +As an example the five literal strings below denote the same string: <pre> @@ -984,18 +640,19 @@ 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>'. -Lua also accepts hexadecimal constants, -which start with <code>0x</code> or <code>0X</code>. +marked by a letter '<tt>e</tt>' or '<tt>E</tt>'. +Luan also accepts hexadecimal constants, +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. @@ -1003,21 +660,23 @@ <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, -the comment is a <em>short comment</em>, +If the text immediately after <tt>--</tt> is not an opening long bracket, +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. @@ -1025,11 +684,11 @@ -<h2>3.2 – <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. @@ -1040,6 +699,7 @@ <pre> var ::= Name + </pre><p> Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. @@ -1047,7 +707,7 @@ <p> Any variable name is assumed to be global unless explicitly declared as a local (see <a href="#3.3.7">§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">§3.5</a>). @@ -1061,29 +721,31 @@ <pre> var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ + </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 -a call <code>gettable_event(t,i)</code>. +An access to an indexed variable <tt>t[i]</tt> is equivalent to +a call <tt>gettable_event(t,i)</tt>. (See <a href="#2.4">§2.4</a> for a complete description of the -<code>gettable_event</code> function. -This function is not defined or callable in Lua. +<tt>gettable_event</tt> function. +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 -<code>var["Name"]</code>: +The syntax <tt>var.Name</tt> is just syntactic sugar for +<tt>var["Name"]</tt>: <pre> var ::= prefixexp ‘<b>.</b>’ Name + </pre> <p> -An access to a global variable <code>x</code> -is equivalent to <code>_ENV.x</code>. +An access to a global variable <tt>x</tt> +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">§2.2</a>). +<tt>_ENV</tt> is never a global name (see <a href="#2.2">§2.2</a>).