diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 1625 |
1 files changed, 722 insertions, 903 deletions
diff --git a/doc/manual.html b/doc/manual.html index eeacdcc9..aa1afa28 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -16,10 +16,15 @@ Lua 5.3 Reference Manual </h1> +<P> +<IMG SRC="alert.png" ALIGN="absbottom"> +<EM>All details may change in the final version.</EM> +<P> + by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes <p> <small> -Copyright © 2011–2013 Lua.org, PUC-Rio. +Copyright © 2011–2014 Lua.org, PUC-Rio. Freely available under the terms of the <a href="http://www.lua.org/license.html">Lua license</a>. </small> @@ -33,7 +38,7 @@ Freely available under the terms of the <!-- ====================================================================== --> <p> -<!-- $Id: manual.of,v 1.105 2013/07/05 18:48:52 roberto Exp $ --> +<!-- $Id: manual.of,v 1.114 2014/03/21 18:32:52 roberto Exp $ --> @@ -119,11 +124,8 @@ it usually represents the absence of a useful value. <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. Both <b>nil</b> and <b>false</b> make a condition false; any other value makes it true. -<em>Number</em> represents both integer numbers and -real (floating-point) numbers. -Standard Lua uses 64-bit integers and double-precision floats, -but it is easy to compile Lua so that it -uses 32-bit integers and single-precision floats. +<em>Number</em> represents both +integral numbers and real (floating-point) numbers. <em>String</em> represents immutable sequences of bytes. Lua is 8-bit clean: @@ -132,9 +134,26 @@ including embedded zeros ('<code>\0</code>'). <p> +The type <em>number</em> uses two internal representations, +one called <em>integer</em> and the other called <em>float</em>. +Lua has explicit rules about when each representation is used, +but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). +Therefore, +the programmer has the option of mostly ignore the difference +between integers and floats +or assume complete control about the representation of each value. +Standard Lua uses 64-bit integers and double-precision (64-bit) floats, +but you can also compile Lua so that it +uses 32-bit integers and/or single-precision (32-bit) floats. +The option with 32 bits both for integers and floats +(what is called <em>Small Lua</em>) is particularly attractive +for small machines. + + +<p> Lua can call (and manipulate) functions written in Lua and functions written in C -(see <a href="#3.4.9">§3.4.9</a>). +(see <a href="#3.4.10">§3.4.10</a>). <p> @@ -183,14 +202,14 @@ To represent records, Lua uses the field name as an index. The language supports this representation by providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. There are several convenient ways to create tables in Lua -(see <a href="#3.4.8">§3.4.8</a>). +(see <a href="#3.4.9">§3.4.9</a>). <p> We use the term <em>sequence</em> to denote a table where the set of all positive numeric keys is equal to <em>{1..n}</em> for some integer <em>n</em>, -which is called the length of the sequence (see <a href="#3.4.6">§3.4.6</a>). +which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>). <p> @@ -199,7 +218,7 @@ the values of table fields can be of any type. In particular, because functions are first-class values, table fields can contain functions. -Thus tables can also carry <em>methods</em> (see <a href="#3.4.10">§3.4.10</a>). +Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). <p> @@ -212,6 +231,18 @@ if and only if <code>i</code> and <code>j</code> are raw equal <p> +In particular, floats with integral values +are equal to their respective integers +(e.g., <code>1.0 == 1</code>). +To avoid ambiguities, +any float with integral value used as a key +is converted to its respective integer. +For instance, if you write <code>a[2.0] = true</code>, +the actual key inserted into the table will be the +integer <code>2</code>. + + +<p> Tables, functions, threads, and (full) userdata values are <em>objects</em>: variables do not actually <em>contain</em> these values, only <em>references</em> to them. @@ -382,57 +413,37 @@ but the string library sets a metatable for the string type (see <a href="#6.4"> <p> -A metatable controls how an object behaves in arithmetic operations, -order comparisons, concatenation, length operation, and indexing. +A metatable controls how an object behaves in +arithmetic and bitwise operations, +order comparisons, concatenation, length operation, calls, and indexing. A metatable also can define a function to be called when a userdata or a table is garbage collected. -When Lua performs one of these operations over a value, -it checks whether this value has a metatable with the corresponding event. -If so, the value associated with that key (the metamethod) -controls how Lua will perform the operation. <p> -Metatables control the operations listed next. -Each operation is identified by its corresponding name. -The key for each operation is a string with its name prefixed by +A detailed list of events controlled by metatables is given next. +Each operation is identified by its corresponding event name. +The key for each event is a string with its name prefixed by two underscores, '<code>__</code>'; for instance, the key for operation "add" is the string "<code>__add</code>". - - -<p> -The semantics of these operations is better explained by a Lua function -describing how the interpreter executes the operation. -The code shown here in Lua is only illustrative; -the real behavior is hard coded in the interpreter -and it is much more efficient than this simulation. -All functions used in these descriptions -(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.) -are described in <a href="#6.1">§6.1</a>. -In particular, to retrieve the metamethod of a given object, -we use the expression +Note that queries for metamethods are always raw; +the access to a metamethod does not invoke other metamethods. +You can emulate how Lua queries a metamethod for an object <code>obj</code> +with the following code: <pre> - metatable(obj)[event] -</pre><p> -This should be read as - -<pre> - rawget(getmetatable(obj) or {}, event) -</pre><p> -This means that the access to a metamethod does not invoke other metamethods, -and access to objects with no metatables does not fail -(it simply results in <b>nil</b>). - + rawget(getmetatable(obj) or {}, event_name) +</pre> <p> -For the unary <code>-</code> and <code>#</code> operators, -the metamethod is called with a dummy second argument. -This extra argument is only to simplify Lua's internals; -it may be removed in future versions and therefore it is not present -in the following code. -(For most uses this extra argument is irrelevant.) +For the unary minus and the bitwise not operators, +the metamethod is computed and called with a dummy second operand, +equal to the first one. +This extra operand is only to simplify Lua's internals +(by making these operators behave like a binary operation) +and may be removed in future versions. +(For most uses this extra operand is irrelevant.) @@ -441,39 +452,19 @@ in the following code. <li><b>"add": </b> the <code>+</code> operation. - - -<p> -The function <code>getbinhandler</code> below defines how Lua chooses a handler -for a binary operation. -First, Lua tries the first operand. -If its type does not define a handler for the operation, -then Lua tries the second operand. - -<pre> - function getbinhandler (op1, op2, event) - return metatable(op1)[event] or metatable(op2)[event] - end -</pre><p> -By using this function, -the behavior of the <code>op1 + op2</code> is - -<pre> - function add_event (op1, op2) - local o1, o2 = tonumber(op1), tonumber(op2) - if o1 and o2 then -- both operands are numeric? - return o1 + o2 -- '+' here is the primitive 'add' - else -- at least one of the operands is not numeric - local h = getbinhandler(op1, op2, "__add") - if h then - -- call the handler with both operands - return (h(op1, op2)) - else -- no handler available: default behavior - error(···) - end - end - end -</pre><p> +If any operand for an addition is not a number +(nor a string coercible to a number), +Lua will try to call a metamethod. +First, Lua will check the first operand (even if it is valid). +If that operand does not define a metamethod for the "<code>__add</code>" event, +then Lua will check the second operand. +If Lua cannot find a metamethod, +it raises an error. +Otherwise, +it calls the metamethod with the two operands as arguments, +and the result of the call +(adjusted to one value) +is the result of the operation. </li> <li><b>"sub": </b> @@ -497,263 +488,177 @@ Behavior similar to the "add" operation. <li><b>"mod": </b> the <code>%</code> operation. -Behavior similar to the "add" operation, -with the operation -<code>o1 - floor(o1/o2)*o2</code> as the primitive operation. +Behavior similar to the "add" operation. </li> <li><b>"pow": </b> the <code>^</code> (exponentiation) operation. -Behavior similar to the "add" operation, -with the function <code>pow</code> (from the C math library) -as the primitive operation. +Behavior similar to the "add" operation. </li> <li><b>"unm": </b> -the unary <code>-</code> operation. +the <code>-</code> (unary minus) operation. +Behavior similar to the "add" operation. +</li> -<pre> - function unm_event (op) - local o = tonumber(op) - if o then -- operand is numeric? - return -o -- '-' here is the primitive 'unm' - else -- the operand is not numeric. - -- Try to get a handler from the operand - local h = metatable(op).__unm - if h then - -- call the handler with the operand - return (h(op)) - else -- no handler available: default behavior - error(···) - end - end - end -</pre><p> +<li><b>"idiv": </b> +the <code>//</code> (integer division) operation. + +Behavior similar to the "add" operation, +except that Lua will try a metamethod +if any operator is neither an integer +nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). </li> -<li><b>"concat": </b> -the <code>..</code> (concatenation) operation. +<li><b>"band": </b> +the <code>&</code> (bitwise and) operation. +Behavior similar to the "idiv" operation. +</li> -<pre> - function concat_event (op1, op2) - if (type(op1) == "string" or type(op1) == "number") and - (type(op2) == "string" or type(op2) == "number") then - return op1 .. op2 -- primitive string concatenation - else - local h = getbinhandler(op1, op2, "__concat") - if h then - return (h(op1, op2)) - else - error(···) - end - end - end -</pre><p> +<li><b>"bor": </b> +the <code>|</code> (bitwise or) operation. + +Behavior similar to the "band" operation. </li> -<li><b>"len": </b> -the <code>#</code> operation. +<li><b>"bxor": </b> +the <code>~</code> (bitwise exclusive or) operation. +Behavior similar to the "band" operation. +</li> -<pre> - function len_event (op) - if type(op) == "string" then - return strlen(op) -- primitive string length - else - local h = metatable(op).__len - if h then - return (h(op)) -- call handler with the operand - elseif type(op) == "table" then - return #op -- primitive table length - else -- no handler available: error - error(···) - end - end - end -</pre><p> -See <a href="#3.4.6">§3.4.6</a> for a description of the length of a table. +<li><b>"bnot": </b> +the <code>~</code> (bitwise unary not) operation. + +Behavior similar to the "band" operation. </li> -<li><b>"eq": </b> -the <code>==</code> operation. +<li><b>"shl": </b> +the <code><<</code> (bitwise left shift) operation. -The function <code>getequalhandler</code> defines how Lua chooses a metamethod -for equality. -A metamethod is selected only when both values -being compared have the same type -and the same metamethod for the selected operation, -and the values are either tables or full userdata. +Behavior similar to the "band" operation. +</li> -<pre> - function getequalhandler (op1, op2) - if type(op1) ~= type(op2) or - (type(op1) ~= "table" and type(op1) ~= "userdata") then - return nil -- different values - end - local mm1 = metatable(op1).__eq - local mm2 = metatable(op2).__eq - if mm1 == mm2 then return mm1 else return nil end - end -</pre><p> -The "eq" event is defined as follows: +<li><b>"shr": </b> +the <code>>></code> (bitwise right shift) operation. -<pre> - function eq_event (op1, op2) - if op1 == op2 then -- primitive equal? - return true -- values are equal - end - -- try metamethod - local h = getequalhandler(op1, op2) - if h then - return not not h(op1, op2) - else - return false - end - end -</pre><p> -Note that the result is always a boolean. +Behavior similar to the "band" operation. </li> -<li><b>"lt": </b> -the <code><</code> operation. +<li><b>"concat": </b> +the <code>..</code> (concatenation) operation. +Behavior similar to the "add" operation, +except that Lua will try a metamethod +if any operator is neither a string nor a number +(which is always coercible to a string). +</li> -<pre> - function lt_event (op1, op2) - if type(op1) == "number" and type(op2) == "number" then - return op1 < op2 -- numeric comparison - elseif type(op1) == "string" and type(op2) == "string" then - return op1 < op2 -- lexicographic comparison - else - local h = getbinhandler(op1, op2, "__lt") - if h then - return not not h(op1, op2) - else - error(···) - end - end - end -</pre><p> -Note that the result is always a boolean. +<li><b>"len": </b> +the <code>#</code> (length) operation. + +If the object is not a string, +Lua will try its metamethod. +If there is a metamethod, +Lua calls it with the object as argument, +and the result of the call +(always adjusted to one value) +is the result of the operation. +If there is no metamethod but the object is a table, +then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). +Otherwise, Lua raises an error. </li> -<li><b>"le": </b> -the <code><=</code> operation. +<li><b>"eq": </b> +the <code>==</code> (equal) operation. +Lua will try a metamethod only when the values +being compared are both either tables or full userdata, +both have the same metamethod, +and they are not primitively equal. +The result of the call is always converted to a boolean. +</li> -<pre> - function le_event (op1, op2) - if type(op1) == "number" and type(op2) == "number" then - return op1 <= op2 -- numeric comparison - elseif type(op1) == "string" and type(op2) == "string" then - return op1 <= op2 -- lexicographic comparison - else - local h = getbinhandler(op1, op2, "__le") - if h then - return not not h(op1, op2) - else - h = getbinhandler(op1, op2, "__lt") - if h then - return not h(op2, op1) - else - error(···) - end - end - end - end -</pre><p> -Note that, in the absence of a "le" metamethod, -Lua tries the "lt", assuming that <code>a <= b</code> is -equivalent to <code>not (b < a)</code>. +<li><b>"lt": </b> +the <code><</code> (less than) operation. +Behavior similar to the "add" operation, +except that the result of the call is always converted to a boolean. +</li> -<p> +<li><b>"le": </b> +the <code><=</code> (less equal) operation. + +Unlike other operations, +The less-equal operation can use two different events. +First, Lua looks for the "<code>__le</code>" metamethod in both operands, +like in the "add" operation. +If it cannot find such a metamethod, +then it will try the "<code>__lt</code>" event, +assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. As with the other comparison operators, the result is always a boolean. </li> <li><b>"index": </b> The indexing access <code>table[key]</code>. -Note that the metamethod is tried only + +This event happens when <code>table</code> is not a table or when <code>key</code> is not present in <code>table</code>. -(When <code>table</code> is not a table, -no key is ever present, -so the metamethod is always tried.) +The metamethod is looked up in <code>table</code>. -<pre> - function gettable_event (table, key) - local h - if type(table) == "table" then - local v = rawget(table, key) - -- if key is present, return raw value - if v ~= nil then return v end - h = metatable(table).__index - if h == nil then return nil end - else - h = metatable(table).__index - if h == nil then - error(···) - end - end - if type(h) == "function" then - return (h(table, key)) -- call the handler - else return h[key] -- or repeat operation on it - end - end -</pre><p> +<p> +Despite the name, +the metamethod for this event can be either a function or a table. +If it is a function, +it is called with <code>table</code> and <code>key</code> as arguments. +If it is a table, +the final result is the result of indexing this table with <code>key</code>. +(This indexing is regular, not raw, +and therefore can trigger another metamethod.) </li> <li><b>"newindex": </b> The indexing assignment <code>table[key] = value</code>. -Note that the metamethod is tried only + +Like the index event, +this event happens when <code>table</code> is not a table or when <code>key</code> is not present in <code>table</code>. +The metamethod is looked up in <code>table</code>. -<pre> - function settable_event (table, key, value) - local h - if type(table) == "table" then - local v = rawget(table, key) - -- if key is present, do raw assignment - if v ~= nil then rawset(table, key, value); return end - h = metatable(table).__newindex - if h == nil then rawset(table, key, value); return end - else - h = metatable(table).__newindex - if h == nil then - error(···) - end - end - if type(h) == "function" then - h(table, key,value) -- call the handler - else h[key] = value -- or repeat operation on it - end - end -</pre><p> +<p> +Again like with indexing, +the metamethod for this event can be either a function or a table. +If it is a function, +it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. +If it is a table, +Lua does an indexing assignment to this table with the same key and value. +(This assignment is regular, not raw, +and therefore can trigger another metamethod.) + + +<p> +Whenever there is a metamethod, +Lua does not perform the primitive assignment. +(If necessary, +the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> +to do the assignment.) </li> <li><b>"call": </b> -called when Lua calls a value. +The call operation <code>func(args)</code>. - -<pre> - function function_event (func, ...) - if type(func) == "function" then - return func(...) -- primitive call - else - local h = metatable(func).__call - if h then - return h(func, ...) - else - error(···) - end - end - end -</pre><p> +This event happens when Lua tries to call a non-function value +(that is, <code>func</code> is not a function). +The metamethod is looked up in <code>func</code>. +If present, +the metamethod is called with <code>func</code> as its first argument, +followed by the arguments of the original call (<code>args</code>). </li> </ul> @@ -800,7 +705,8 @@ 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. -Values smaller than 100 make the collector too slow and +You should not use values smaller than 100, +as 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" @@ -825,21 +731,6 @@ You can also use these functions to control the collector directly (e.g., stop and restart it). -<p> -As an experimental feature in Lua 5.3, -you can change the collector's operation mode -from incremental to <em>generational</em>. -A <em>generational collector</em> assumes that most objects die young, -and therefore it traverses only young (recently created) objects. -This behavior can reduce the time used by the collector, -but also increases memory usage (as old dead objects may accumulate). -To mitigate this second problem, -from time to time the generational collector performs a full collection. -Remember that this is an experimental feature; -you are welcome to try it, -but check your gains. - - <h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> @@ -872,17 +763,14 @@ 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 does the equivalent of the following function -for each object in that list: +Lua goes through that list: +For each object, +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.) -<pre> - function gc_event (obj) - local h = metatable(obj).__gc - if type(h) == "function" then - h(obj) - end - end -</pre> <p> At the end of each garbage-collection cycle, @@ -1228,6 +1116,15 @@ which can be specified as '<code>\0</code>'. <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 @@ -1290,15 +1187,15 @@ which start with <code>0x</code> or <code>0X</code>. Hexadecimal constants also accept an optional fractional part plus an optional binary exponent, marked by a letter '<code>p</code>' or '<code>P</code>'. -A numeric constant with an fractional dot or an exponent -denotes a floating-point number; -otherwise it denotes an integer number. +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 floating-point constants are +Examples of valid float constants are <pre> 3.0 3.1416 314.16e-2 0.31416E1 34e1 @@ -1471,7 +1368,7 @@ a chunk is simply a block: <p> Lua handles a chunk as the body of an anonymous function with a variable number of arguments -(see <a href="#3.4.10">§3.4.10</a>). +(see <a href="#3.4.11">§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 @@ -1490,10 +1387,9 @@ with an interpreter for the virtual machine. <p> Chunks can also be precompiled into binary form; -see program <code>luac</code> for details. +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. - +Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). @@ -1698,7 +1594,7 @@ is equivalent to the code: <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 <em>var</em>, <em>limit</em>, <em>step</em> = convert(<em>e1</em>, <em>e2</em>, <em>e3</em>) if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do local v = <em>var</em> @@ -1707,6 +1603,13 @@ is equivalent to the code: end end </pre><p> +where <code>convert</code> returns +its three arguments unaltered +if they are all integers, +otherwise it converts them to floats. + + +<p> Note the following: <ul> @@ -1718,6 +1621,12 @@ They must all result in numbers. </li> <li> +If any of the three control values is not an integer, +all three values are converted to floats, +so that the loop is done with floats. +</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> @@ -1728,14 +1637,14 @@ then a step of 1 is used. </li> <li> -You can use <b>break</b> to exit a <b>for</b> loop. +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; you cannot use its value after the <b>for</b> ends or is broken. -If you need this value, -assign it to another variable before breaking or exiting the loop. +If you need its value, +assign it to another variable before exiting the loop. </li> </ul> @@ -1809,7 +1718,7 @@ function calls can be executed as statements: stat ::= functioncall </pre><p> In this case, all returned values are thrown away. -Function calls are explained in <a href="#3.4.9">§3.4.9</a>. +Function calls are explained in <a href="#3.4.10">§3.4.10</a>. @@ -1862,22 +1771,24 @@ The basic expressions in Lua are the following: <p> Numbers and literal strings are explained in <a href="#3.1">§3.1</a>; variables are explained in <a href="#3.2">§3.2</a>; -function definitions are explained in <a href="#3.4.10">§3.4.10</a>; -function calls are explained in <a href="#3.4.9">§3.4.9</a>; -table constructors are explained in <a href="#3.4.8">§3.4.8</a>. +function definitions are explained in <a href="#3.4.11">§3.4.11</a>; +function calls are explained in <a href="#3.4.10">§3.4.10</a>; +table constructors are explained in <a href="#3.4.9">§3.4.9</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="#3.4.10">§3.4.10</a>. +they are explained in <a href="#3.4.11">§3.4.11</a>. <p> Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), -relational operators (see <a href="#3.4.3">§3.4.3</a>), logical operators (see <a href="#3.4.4">§3.4.4</a>), -and the concatenation operator (see <a href="#3.4.5">§3.4.5</a>). +bitwise operators (see <a href="#3.4.2">§3.4.2</a>), +relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), +and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), -the unary <b>not</b> (see <a href="#3.4.4">§3.4.4</a>), -and the unary <em>length operator</em> (see <a href="#3.4.6">§3.4.6</a>). +the unary bitwise not (see <a href="#3.4.2">§3.4.2</a>), +the unary logic <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), +and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). <p> @@ -1939,41 +1850,33 @@ that rounds the quotient towards minus infinite (floor). <p> -With the exception of division, integer division, and exponentiation, +With the exception of division and integer 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.2">§3.4.2</a>), -then they are converted to floating-point numbers, +numbers (see <a href="#3.4.3">§3.4.3</a>), +then they are converted to floats, the operation is performed following the usual rules for floating-point arithmetic -(usually following the IEEE 754 standard), -and the result is a floating-point number. +(usually the IEEE 754 standard), +and the result is a float. <p> -Division (<code>/</code>) always converts its operands to floating-point numbers -and its result is always a floating-point number. +Division (<code>/</code>) always converts its operands to floats +and its result is always a float. <p> -Integer division (<code>//</code>) converts its operands to integer numbers -(see <a href="#3.4.2">§3.4.2</a>) -and its result is always an integer number. +Integer division (<code>//</code>) converts its operands to integers +(see <a href="#3.4.3">§3.4.3</a>) +and its result is always an integer. The result is always rounded towards minus infinite (floor). <p> -Exponentiation (<code>^</code>) checks whether both operands are integers and -the exponent is non-negative. -In that case, the exponentiation is performed as an integer operation -and the result is an integer number. -Otherwise, it is performed as a floatint-point operation (<code>pow</code>). - - -<p> In case of overflows in integer arithmetic, all operations <em>wrap around</em>, according to the usual rules of two-complement arithmetic. @@ -1982,15 +1885,41 @@ according to the usual rules of two-complement arithmetic. -<h3>3.4.2 – <a name="3.4.2">Coercions and Conversions</a></h3> +<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> +Lua supports the following bitwise operators: +the binary <code>&</code> (bitwise and), +<code>|</code> (bitwise or), <code>~</code> (bitwise exclusive or), +<code>>></code> (right shift), <code><<</code> (left shift), +and unary <code>~</code> (bitwise not). + + +<p> +All bitwise operations convert its operands to integers +(see <a href="#3.4.3">§3.4.3</a>), +operate on all bits of those integers, +and result in an integer. + <p> -Lua provides some automatic conversions between types at run time. -Most binary operations applied to mixed numbers +Both right and left shifts fill with zeros the vacant bits. +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 (all bits are shifted out). + + + + + +<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> +Lua provides some automatic conversions between some +types and representations at run time. +Most arithmetic operations applied to mixed numbers (integers and floats) convert the integer operand to a float; this is called the <em>usual rule</em>. -Division always convert integer operands to floats, -and integer division always convert floating operands to integers. +Division always convert integer operands to floats; +integer division and bitwise operators +always convert float operands to integers. The C API also converts both integers to floats and floats to integers, as needed. Moreover, string concatenation accepts numbers as arguments, @@ -2015,8 +1944,8 @@ This kind of conversion never fails. <p> The conversion from float to integer first takes the floor of the float number. -If that value can be represented as an integer number -(that is, it is in the range of integer numbers), +If that value can be represented as an integer +(that is, it is in the range of integer representation), that is the result. Otherwise, the conversion fails. @@ -2027,14 +1956,12 @@ follows the rules of the Lua lexer. (The string may have leading and trailing spaces and a sign.) There is no direct conversion from strings to integers: If a string is provided where an integer is needed, -Lua converts the string to a float an then the float to an integer. +Lua converts the string to a float and then the float to an integer. <p> -The conversion from numbers to strings use a reasonable, +The conversion from numbers to strings use a human-readable, non-specified format. -Floating-point numbers always produce strings with some -floating-point indication (either a decimal dot or an exponent). For complete control over how numbers are converted to strings, use the <code>format</code> function from the string library (see <a href="#pdf-string.format"><code>string.format</code></a>). @@ -2043,7 +1970,7 @@ use the <code>format</code> function from the string library -<h3>3.4.3 – <a name="3.4.3">Relational Operators</a></h3><p> +<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> The relational operators in Lua are <pre> @@ -2060,7 +1987,7 @@ Strings are compared in the obvious way. Numbers follow the usual rule for binary operations: if both operands are integers, the are compared as integers. -Otherwise, they are converted to floating-point numbers +Otherwise, they are converted to floats and compared as such. @@ -2109,7 +2036,7 @@ and <code>a >= b</code> is translated to <code>b <= a</code>. -<h3>3.4.4 – <a name="3.4.4">Logical Operators</a></h3><p> +<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> The logical operators in Lua are <b>and</b>, <b>or</b>, and <b>not</b>. Like the control structures (see <a href="#3.3.4">§3.3.4</a>), @@ -2125,7 +2052,7 @@ otherwise, <b>and</b> returns its second argument. The disjunction operator <b>or</b> returns its first argument if this value is different from <b>nil</b> and <b>false</b>; otherwise, <b>or</b> returns its second argument. -Both <b>and</b> and <b>or</b> use short-cut evaluation; +Both <b>and</b> and <b>or</b> use short-circuit evaluation; that is, the second operand is evaluated only if necessary. Here are some examples: @@ -2147,18 +2074,18 @@ Here are some examples: -<h3>3.4.5 – <a name="3.4.5">Concatenation</a></h3><p> +<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> The string concatenation operator in Lua is denoted by two dots ('<code>..</code>'). If both operands are strings or numbers, then they are converted to -strings according to the rules mentioned in <a href="#3.4.2">§3.4.2</a>. +strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). -<h3>3.4.6 – <a name="3.4.6">The Length Operator</a></h3> +<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> <p> The length operator is denoted by the unary prefix operator <code>#</code>. @@ -2196,7 +2123,7 @@ with whether a table is a sequence. -<h3>3.4.7 – <a name="3.4.7">Precedence</a></h3><p> +<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> Operator precedence in Lua follows the table below, from lower to higher priority: @@ -2220,7 +2147,7 @@ All other binary operators are left associative. -<h3>3.4.8 – <a name="3.4.8">Table Constructors</a></h3><p> +<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> Table constructors are expressions that create tables. Every time a constructor is evaluated, a new table is created. A constructor can be used to create an empty table @@ -2268,7 +2195,7 @@ is equivalent to If the last field in the list has the form <code>exp</code> and the expression is a function call or a vararg expression, then all values returned by this expression enter the list consecutively -(see <a href="#3.4.9">§3.4.9</a>). +(see <a href="#3.4.10">§3.4.10</a>). <p> @@ -2279,7 +2206,7 @@ as a convenience for machine-generated code. -<h3>3.4.9 – <a name="3.4.9">Function Calls</a></h3><p> +<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> A function call in Lua has the following syntax: <pre> @@ -2354,7 +2281,7 @@ So, none of the following examples are tail calls: -<h3>3.4.10 – <a name="3.4.10">Function Definitions</a></h3> +<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> <p> The syntax for function definition is @@ -3046,8 +2973,8 @@ it seems to be a safe assumption.) <pre>void lua_arith (lua_State *L, int op);</pre> <p> -Performs an arithmetic operation over the two values -(or one, in the case of negation) +Performs an arithmetic or bitwise operation over the two values +(or one, in the case of negations) at the top of the stack, with the value at the top being the second operand, pops these values, and pushes the result of the operation. @@ -3064,9 +2991,16 @@ The value of <code>op</code> must be one of the following constants: <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs division (<code>/</code>)</li> +<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs integer division (<code>//</code>)</li> <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> +<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li> +<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li> +<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>|</code>)</li> +<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li> +<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> +<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> </ul> @@ -3283,7 +3217,7 @@ If <code>n</code> is 1, the result is the single value on the stack (that is, the function does nothing); if <code>n</code> is 0, the result is the empty string. Concatenation is performed following the usual semantics of Lua -(see <a href="#3.4.5">§3.4.5</a>). +(see <a href="#3.4.6">§3.4.6</a>). @@ -3404,24 +3338,18 @@ memory in use by Lua by 1024. <li><b><code>LUA_GCSTEP</code>: </b> performs an incremental step of garbage collection. -The step "size" is controlled by <code>data</code> -(larger values mean more steps) in a non-specified way. -If you want to control the step size -you must experimentally tune the value of <code>data</code>. -The function returns 1 if the step finished a -garbage-collection cycle. </li> <li><b><code>LUA_GCSETPAUSE</code>: </b> sets <code>data</code> as the new value -for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>). -The function returns the previous value of the pause. +for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) +and returns the previous value of the pause. </li> <li><b><code>LUA_GCSETSTEPMUL</code>: </b> sets <code>data</code> as the new value for the <em>step multiplier</em> of -the collector (see <a href="#2.5">§2.5</a>). -The function returns the previous value of the step multiplier. +the collector (see <a href="#2.5">§2.5</a>) +and returns the previous value of the step multiplier. </li> <li><b><code>LUA_GCISRUNNING</code>: </b> @@ -3429,16 +3357,6 @@ returns a boolean that tells whether the collector is running (i.e., not stopped). </li> -<li><b><code>LUA_GCGEN</code>: </b> -changes the collector to generational mode -(see <a href="#2.5">§2.5</a>). -</li> - -<li><b><code>LUA_GCINC</code>: </b> -changes the collector to incremental mode. -This is the default mode. -</li> - </ul> <p> @@ -3514,10 +3432,11 @@ for the "index" event (see <a href="#2.4">§2.4</a>). <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> <span class="apii">[-0, +1, <em>e</em>]</span> -<pre>void lua_getglobal (lua_State *L, const char *name);</pre> +<pre>int lua_getglobal (lua_State *L, const char *name);</pre> <p> Pushes onto the stack the value of the global <code>name</code>. +Returns the type of that value. @@ -3538,7 +3457,7 @@ the function returns 0 and pushes nothing on the stack. <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> <span class="apii">[-1, +1, <em>e</em>]</span> -<pre>void lua_gettable (lua_State *L, int index);</pre> +<pre>int lua_gettable (lua_State *L, int index);</pre> <p> Pushes onto the stack the value <code>t[k]</code>, @@ -3553,6 +3472,10 @@ As in Lua, this function may trigger a metamethod for the "index" event (see <a href="#2.4">§2.4</a>). +<p> +Returns the type of the pushed value. + + @@ -3577,7 +3500,6 @@ this result is equal to the number of elements in the stack <p> Pushes onto the stack the Lua value associated with the userdata at the given index. -This Lua value must be a table or <b>nil</b>. @@ -3598,17 +3520,18 @@ because a pseudo-index is not an actual stack position. <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> -<pre>typedef ptrdiff_t lua_Integer;</pre> +<pre>typedef long long int lua_Integer;</pre> <p> -The type of integer numbers in Lua. +The type of integers in Lua. <p> -By default it is defined as <code>long long</code>, -usually a 64-bit two-complement integer, -but it can also be <code>long</code> or <code>int</code>, -usually a 32-bit two-complement integer. +By default this type is <code>long long</code> +(usually a 64-bit two-complement integer), +but that can be changed in <code>luaconf.h</code> +to <code>long</code> or <code>int</code> +(usually a 32-bit two-complement integer). @@ -3780,7 +3703,7 @@ Returns 1 if the value at the given index is a userdata <p> Returns the "length" of the value at the given index; -it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.6">§3.4.6</a>). +it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). The result is pushed on the stack. @@ -3973,8 +3896,11 @@ the table during its traversal. <pre>typedef double lua_Number;</pre> <p> -The type of floating-point numbers in Lua. -By default, it is double, +The type of floats in Lua. + + +<p> +By default this type is double, but that can be changed in <code>luaconf.h</code> to a single float. @@ -4183,12 +4109,14 @@ the result is a Lua string and Lua takes care of memory allocation The conversion specifiers are quite restricted. There are no flags, widths, or precisions. The conversion specifiers can only be -'<code>%%</code>' (inserts a '<code>%</code>' in the string), +'<code>%%</code>' (inserts the character '<code>%</code>'), '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), +'<code>%L</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), '<code>%p</code>' (inserts a pointer as a hexadecimal numeral), -'<code>%d</code>' (inserts an <code>int</code>), and -'<code>%c</code>' (inserts an <code>int</code> as a byte). +'<code>%d</code>' (inserts an <code>int</code>), +'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and +'<code>%U</code>' (inserts an <code>int</code> as a UTF-8 byte sequence). </li> </ul> @@ -4289,7 +4217,7 @@ Pushes a nil value onto the stack. <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> <p> -Pushes a number with value <code>n</code> onto the stack. +Pushes a float with value <code>n</code> onto the stack. @@ -4335,7 +4263,7 @@ Returns 1 if this thread is the main thread of its state. <pre>void lua_pushunsigned (lua_State *L, lua_Unsigned n);</pre> <p> -Pushes a number with value <code>n</code> onto the stack. +Pushes an integer with value <code>n</code> onto the stack. @@ -4384,7 +4312,7 @@ Also returns 0 if any of the indices are non valid. <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> <span class="apii">[-1, +1, –]</span> -<pre>void lua_rawget (lua_State *L, int index);</pre> +<pre>int lua_rawget (lua_State *L, int index);</pre> <p> Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access @@ -4396,7 +4324,7 @@ Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> <span class="apii">[-0, +1, –]</span> -<pre>void lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> +<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> <p> Pushes onto the stack the value <code>t[n]</code>, @@ -4405,12 +4333,16 @@ The access is raw; that is, it does not invoke metamethods. +<p> +Returns the type of the pushed value. + + <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> <span class="apii">[-0, +1, –]</span> -<pre>void lua_rawgetp (lua_State *L, int index, const void *p);</pre> +<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> <p> Pushes onto the stack the value <code>t[k]</code>, @@ -4420,6 +4352,10 @@ The access is raw; that is, it does not invoke metamethods. +<p> +Returns the type of the pushed value. + + @@ -4699,7 +4635,7 @@ If <code>index</code> is 0, then all stack elements are removed. <pre>void lua_setuservalue (lua_State *L, int index);</pre> <p> -Pops a table or <b>nil</b> from the stack and sets it as +Pops a value from the stack and sets it as the new value associated to the userdata at the given index. @@ -4818,7 +4754,7 @@ Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <co Converts the Lua value at the given index to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. The Lua value must be an integer, -or a number or string convertible to an integer (see <a href="#3.4.2">§3.4.2</a>); +or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); otherwise, <code>lua_tointegerx</code> returns 0. @@ -4881,7 +4817,7 @@ Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code Converts the Lua value at the given index to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). The Lua value must be a number or a string convertible to a number -(see <a href="#3.4.2">§3.4.2</a>); +(see <a href="#3.4.3">§3.4.3</a>); otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. @@ -4960,7 +4896,7 @@ to the unsigned integral type <a href="#lua_Unsigned"><code>lua_Unsigned</code>< The Lua value must be an integer, or a float, or a string convertible to a number -(see <a href="#3.4.2">§3.4.2</a>); +(see <a href="#3.4.3">§3.4.3</a>); otherwise, <code>lua_tounsignedx</code> returns 0. @@ -5544,7 +5480,7 @@ calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</cod <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> <span class="apii">[-0, +0, –]</span> -<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> +<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> <p> Sets the debugging hook function. @@ -5779,7 +5715,6 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). Adds the zero-terminated string pointed to by <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). -The string cannot contain embedded zeros. @@ -5814,7 +5749,7 @@ which is the value to be added to the buffer. <p> Checks whether <code>cond</code> is true. -If not, raises an error with a standard message. +If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). @@ -5825,14 +5760,15 @@ If not, raises an error with a standard message. <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> <p> -Raises an error with a standard message -that includes <code>extramsg</code> as a comment. +Raises an error reporting a problem with argument <code>arg</code> +of the C function that called it, +using a standard message +that includes <code>extramsg</code> as a comment: - -<p> -This function never returns, -but it is an idiom to use it in C functions -as <code>return luaL_argerror(<em>args</em>)</code>. +<pre> + bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) +</pre><p> +This function never returns. @@ -6304,7 +6240,7 @@ Pushes the resulting string on the stack and returns it. <p> Returns the "length" of the value at the given index as a number; -it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.6">§3.4.6</a>). +it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). Raises an error if the result of the operation is not an integer. (This case only can happen through metamethods.) @@ -6461,7 +6397,8 @@ If the registry already has the key <code>tname</code>, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, -adds it to the registry with key <code>tname</code>, +adds to this new table the pair <code>__name = tname</code>, +adds to the registry the pair <code></code>[tname] = new table, and returns 1. @@ -6781,6 +6718,43 @@ in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code> +<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> +<pre>typedef struct luaL_Stream { + FILE *f; + lua_CFunction closef; +} luaL_Stream;</pre> + +<p> +The standard representation for file handles, +which is used by the standard I/O library. + + +<p> +A file handle is implemented as a full userdata, +with a metatable called <code>LUA_FILEHANDLE</code>. +<code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name. +The metatable is created by the I/O library +(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). + + +<p> +This userdata must start with the structure <code>luaL_Stream</code>; +it can contain other data after this initial structure. +Field <code>f</code> points to the corresponding C stream +(or it can be <code>NULL</code> to indicate an incompletely created handle). +Field <code>closef</code> points to a Lua function +that will be called to close the stream +when the handle is closed or collected; +this function receives the file handle as its sole argument and +must return either <b>true</b> (in case of success) +or <b>nil</b> plus an error message (in case of error). +Once Lua calls this field, +the field value is changed to <b>nil</b> to signal that the handle is closed. + + + + + <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> <span class="apii">[-0, +0, <em>e</em>]</span> <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> @@ -6888,8 +6862,6 @@ This function is used to build a prefix for error messages. - - <h1>6 – <a name="6">Standard Libraries</a></h1> <p> @@ -6918,11 +6890,11 @@ Currently, Lua has the following standard libraries: <li>string manipulation (<a href="#6.4">§6.4</a>);</li> -<li>table manipulation (<a href="#6.5">§6.5</a>);</li> +<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> -<li>mathematical functions (<a href="#6.6">§6.6</a>) (sin, log, etc.);</li> +<li>table manipulation (<a href="#6.6">§6.6</a>);</li> -<li>bitwise operations (<a href="#6.7">§6.7</a>);</li> +<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> <li>input and output (<a href="#6.8">§6.8</a>);</li> @@ -6949,7 +6921,6 @@ the host program can open them individually by using <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), -<a name="pdf-luaopen_bit32"><code>luaopen_bit32</code></a> (for the bit library), <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). @@ -7003,25 +6974,21 @@ restarts automatic execution of the garbage collector. </li> <li><b>"<code>count</code>": </b> -returns the total memory in use by Lua (in Kbytes) and -a second value with the total memory in bytes modulo 1024. -The first value has a fractional part, -so the following equality is always true: - -<pre> - k, b = collectgarbage("count") - assert(k*1024 == math.floor(k)*1024 + b) -</pre><p> -(The second result is useful when Lua is compiled -with a non floating-point type for numbers.) +returns the total memory in use by Lua in Kbytes. +The value has a fractional part, +so that it multiplied by 1024 +gives the exact number of bytes in use by Lua +(except for overflows). </li> <li><b>"<code>step</code>": </b> performs a garbage-collection step. -The step "size" is controlled by <code>arg</code> -(larger values mean more steps) in a non-specified way. -If you want to control the step size -you must experimentally tune the value of <code>arg</code>. +The step "size" is controlled by <code>arg</code>. +With a zero value, +the collector will perform one basic (indivisible) step. +For non-zero values, +the collector will perform as if that amount of memory +(in KBytes) had been allocated by Lua. Returns <b>true</b> if the step finished a collection cycle. </li> @@ -7095,7 +7062,7 @@ A global variable (not a function) that holds the global environment (see <a href="#2.2">§2.2</a>). Lua itself does not use this variable; changing its value does not affect any environment, -nor vice-versa. +nor vice versa. @@ -7190,6 +7157,12 @@ or "<code>bt</code>" (both binary and text). The default is "<code>bt</code>". +<p> +Lua does not check the consistency of binary chunks. +Maliciously crafted binary chunks can crash +the interpreter. + + <p> @@ -7328,7 +7301,7 @@ without invoking any metamethod. Returns the length of the object <code>v</code>, which must be a table or a string, without invoking any metamethod. -Returns an integer number. +Returns an integer. @@ -7417,7 +7390,9 @@ the function returns <b>nil</b>. <p> <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> Receives a value of any type and -converts it to a string in a reasonable format. +converts it to a string in a human-readable format. +Floats always produce strings with some +floating-point indication (either a decimal dot or an exponent). (For complete control of how numbers are converted, use <a href="#pdf-string.format"><code>string.format</code></a>.) @@ -7451,7 +7426,7 @@ and "<code>userdata</code>". <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> A global variable (not a function) that holds a string containing the current interpreter version. -The current contents of this variable is "<code>Lua 5.3</code>". +The current value of this variable is "<code>Lua 5.3</code>". @@ -7981,13 +7956,19 @@ Numerical codes are not necessarily portable across platforms. <p> -<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> +<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> <p> -Returns a string containing a binary representation of the given function, +Returns a string containing a binary representation +(a <em>binary chunk</em>) +of the given function, so that a later <a href="#pdf-load"><code>load</code></a> on this string returns a copy of the function (but with new upvalues). +If <code>strip</code> is a true value, +the binary representation is created without debug information +about the function +(local variable names, lines, etc.). @@ -8055,11 +8036,7 @@ Options <code>G</code>, and <code>g</code> all expect a number as argument. Options <code>c</code>, <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> -also expect a number, -but the range of that number may be limited by -the underlying C implementation. -For options <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>, -the number cannot be negative. +expect an integer. Option <code>q</code> expects a string; option <code>s</code> expects a string without embedded zeros. If the argument to option <code>s</code> is not a string, @@ -8175,9 +8152,9 @@ Here are some examples: end) --> x="4+5 = 9" - local t = {name="lua", version="5.2"} + local t = {name="lua", version="5.3"} x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) - --> x="lua-5.2.tar.gz" + --> x="lua-5.3.tar.gz" </pre> @@ -8219,6 +8196,45 @@ its default value is 1 and can be negative. <p> +<hr><h3><a name="pdf-string.packfloat"><code>string.packfloat (n [, size [, endianess]])</code></a></h3> +Returns a string with the machine representation of float <code>n</code>, +with given size and endianess. +The <code>size</code> is the string "<code>f</code>" (single precision), +"<code>d</code>" (double precision), or "<code>n</code>", +which means the size of a <a href="#lua_Number"><code>lua_Number</code></a>; +its default is St{n}. +The endianess is the string "<code>l</code>" (little endian), "<code>b</code>" (big endian), +or "<code>n</code>" (native); +the default is the native endianess. + + +<p> +(This function may not work correctly for non-native endianess +in mixed-endian architectures.) + + + + +<p> +<hr><h3><a name="pdf-string.packint"><code>string.packint (n [, size [, endianess]])</code></a></h3> +Returns a string with the machine representation of integer <code>n</code>, +with <code>size</code> bytes and given endianess. +The <code>size</code> can be any value from 1 to 8 or 0, +which means the size of a <a href="#lua_Integer"><code>lua_Integer</code></a>; +its default is zero. +The endianess is the string "<code>l</code>" (little endian), "<code>b</code>" (big endian), +or "<code>n</code>" (native); +the default is the native endianess. + + +<p> +(This function may not work correctly for native endianess +in mixed-endian architectures.) + + + + +<p> <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> Returns a string that is the concatenation of <code>n</code> copies of the string <code>s</code> separated by the string <code>sep</code>. @@ -8263,6 +8279,28 @@ the function returns the empty string. <p> +<hr><h3><a name="pdf-string.unpackfloat"><code>string.unpackfloat (s [, pos [, size [, endianess]]])</code></a></h3> +Reads the machine representation of a float starting at position +<code>pos</code> in string <code>s</code> and returns that number. +See <a href="#pdf-string.packfloat"><code>string.packfloat</code></a> for details about <code>size</code> and <code>endianess</code>. + + + + +<p> +<hr><h3><a name="pdf-string.unpackint"><code>string.unpackint (s [, pos [, size [, endianess]]])</code></a></h3> +Reads the machine representation of an integer starting at position +<code>pos</code> in string <code>s</code> and returns that integer. +See <a href="#pdf-string.packint"><code>string.packint</code></a> for details about <code>size</code> and <code>endianess</code>. + + +<p> +Integers are always read as signed. + + + + +<p> <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. @@ -8321,7 +8359,7 @@ represents the class which is the union of all characters in <em>set</em>. A range of characters can be specified by separating the end characters of the range, -in ascending order, with a '<code>-</code>', +in ascending order, with a '<code>-</code>'. All classes <code>%</code><em>x</em> described above can also be used as components in <em>set</em>. All other characters in <em>set</em> represent themselves. @@ -8466,7 +8504,110 @@ string <code>"flaaap"</code>, there will be two captures: 3 and 5. -<h2>6.5 – <a name="6.5">Table Manipulation</a></h2> +<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> + +<p> +This library provides basic support for UTF-8 encoding. +It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. +This library does not provide any support for Unicode other +than the handling of the encoding. +Any operation that needs the meaning of a character, +such as character classification, is outside its scope. + + +<p> +Unless stated otherwise, +all functions that expect a byte index as a parameter +assume that the given position is either the start of a byte sequence +or one plus the length of the subject string. +As in the string library, +negative indices count from the end of the string. + + +<p> +<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> +Receives zero or more integers, +converts each one to its corresponding UTF-8 byte sequence +and returns a string with the concatenation of all these sequences. + + + + +<p> +<hr><h3><a name="pdf-utf8.charpatt"><code>utf8.charpatt</code></a></h3> +The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" +(see <a href="#6.4.1">§6.4.1</a>), +which matches exactly one UTF-8 byte sequence, +assuming that the subject is a valid UTF-8 string. + + + + +<p> +<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> + + +<p> +Returns values so that the construction + +<pre> + for p, c in utf8.codes(s) do <em>body</em> end +</pre><p> +will iterate over all characters in string <code>s</code>, +with <code>p</code> being the position (in bytes) and <code>c</code> the code point +of each character. +It raises an error if it meets any invalid byte sequence. + + + + +<p> +<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> +Returns the codepoints (as integers) from all characters in <code>s</code> +that start between byte position <code>i</code> and <code>j</code> (both included). +The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. +It raises an error if it meets any invalid byte sequence. + + + + +<p> +<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i])</code></a></h3> +Returns the number of UTF-8 characters in string <code>s</code>, +starting from position <code>i</code>. +The default for <code>i</code> is 1. +Returns <b>nil</b> if the sufix of <code>s</code> starting at <code>i</code> +contains any invalid byte sequence. + + + + +<p> +<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> +Returns the byte index where the encoding of the +<code>n</code>-th character of <code>s</code> starts, +counting from position <code>i</code>. +A negative <code>n</code> gets characters before position <code>i</code>. +The default for <code>i</code> is 1. +Returns <b>nil</b> if the subject does not have such character. + + +<p> +As a special case, +when <code>n</code> is 0 the function returns the start of the encoding +of the character that contains the <code>i</code>-th byte of <code>s</code>. + + +<p> +This function assumes that <code>s</code> is a valid UTF-8 string. + + + + + + + +<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> <p> This library provides generic functions for table manipulation. @@ -8476,7 +8617,7 @@ It provides all its functions inside the table <a name="pdf-table"><code>table</ <p> Remember that, whenever an operation needs the length of a table, the table should be a proper sequence -or have a <code>__len</code> metamethod (see <a href="#3.4.6">§3.4.6</a>). +or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>). All functions ignore non-numeric keys in tables given as arguments. @@ -8546,8 +8687,8 @@ in those cases, the function erases the element <code>list[pos]</code>. <p> The default value for <code>pos</code> is <code>#list</code>, -so that a call <code>table.remove(t)</code> removes the last element -of list <code>t</code>. +so that a call <code>table.remove(l)</code> removes the last element +of list <code>l</code>. @@ -8581,7 +8722,7 @@ may have their relative positions changed by the sort. <p> -Returns the elements from the given table. +Returns the elements from the given list. This function is equivalent to <pre> @@ -8595,14 +8736,13 @@ By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. -<h2>6.6 – <a name="6.6">Mathematical Functions</a></h2> +<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> <p> This library is an interface to the standard C math library. It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>. Unless stated otherwise, -all functions in this library operate with and return -floating-point numbers. +all functions in this library operate with and return floats. <p> @@ -8713,7 +8853,8 @@ Returns the value <em>e<sup>x</sup></em>. <p> -Returns the largest integer smaller than or equal to <code>x</code>. +Returns a float with the largest +integral value smaller than or equal to <code>x</code>. @@ -8758,8 +8899,7 @@ a value larger than or equal to any other numerical value. <p> -Returns the largest integer smaller than or equal to <code>x</code> -as an integer number. +Returns the largest integer smaller than or equal to <code>x</code>. If the value does not fit in an integer, returns <b>nil</b>. @@ -8767,16 +8907,6 @@ returns <b>nil</b>. <p> -<hr><h3><a name="pdf-math.isfloat"><code>math.isfloat (x)</code></a></h3> - - -<p> -Returns whether <code>x</code> is a floating-point number. - - - - -<p> <hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3> @@ -8872,11 +9002,11 @@ pseudo-random generator function <code>rand</code> provided by Standard C. <p> When called without arguments, -returns a uniform pseudo-random float number +returns a uniform pseudo-random float in the range <em>[0,1)</em>. -When called with two integer values <code>m</code> and <code>n</code>, +When called with two integers <code>m</code> and <code>n</code>, <code>math.random</code> returns a uniform pseudo-random -integer number in the range <em>[m, n]</em>. +integer in the range <em>[m, n]</em>. The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. @@ -8945,229 +9075,14 @@ Returns the hyperbolic tangent of <code>x</code>. - - - -<h2>6.7 – <a name="6.7">Bitwise Operations</a></h2> - -<p> -This library provides bitwise operations. -It provides all its functions inside the table <a name="pdf-bit32"><code>bit32</code></a>. - - -<p> -Unless otherwise stated, -all functions accept numeric arguments in the range -<em>(-2<sup>51</sup>,+2<sup>51</sup>)</em>; -each argument is normalized to -the remainder of its division by <em>2<sup>32</sup></em> -and truncated to an integer (in some unspecified way), -so that its final value falls in the range <em>[0,2<sup>32</sup> - 1]</em>. -Similarly, all results are in the range <em>[0,2<sup>32</sup> - 1]</em>. -Note that <code>bit32.bnot(0)</code> is <code>0xFFFFFFFF</code>, -which is different from <code>-1</code>. - - -<p> -<hr><h3><a name="pdf-bit32.arshift"><code>bit32.arshift (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the left. - - -<p> -This shift operation is what is called arithmetic shift. -Vacant bits on the left are filled -with copies of the higher bit of <code>x</code>; -vacant bits on the right are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero or <code>0xFFFFFFFF</code> (all original bits are shifted out). - - - - -<p> -<hr><h3><a name="pdf-bit32.band"><code>bit32.band (···)</code></a></h3> - - -<p> -Returns the bitwise <em>and</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.bnot"><code>bit32.bnot (x)</code></a></h3> - - -<p> -Returns the bitwise negation of <code>x</code>. -For any integer <code>x</code>, -the following identity holds: - -<pre> - assert(bit32.bnot(x) == (-1 - x) % 2^32) -</pre> - - - -<p> -<hr><h3><a name="pdf-bit32.bor"><code>bit32.bor (···)</code></a></h3> - - -<p> -Returns the bitwise <em>or</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.btest"><code>bit32.btest (···)</code></a></h3> - - -<p> -Returns a boolean signaling -whether the bitwise <em>and</em> of its operands is different from zero. - - - - -<p> -<hr><h3><a name="pdf-bit32.bxor"><code>bit32.bxor (···)</code></a></h3> - - -<p> -Returns the bitwise <em>exclusive or</em> of its operands. - - - - -<p> -<hr><h3><a name="pdf-bit32.extract"><code>bit32.extract (n, field [, width])</code></a></h3> - - -<p> -Returns the unsigned number formed by the bits -<code>field</code> to <code>field + width - 1</code> from <code>n</code>. -Bits are numbered from 0 (least significant) to 31 (most significant). -All accessed bits must be in the range <em>[0, 31]</em>. - - -<p> -The default for <code>width</code> is 1. - - - - -<p> -<hr><h3><a name="pdf-bit32.replace"><code>bit32.replace (n, v, field [, width])</code></a></h3> - - -<p> -Returns a copy of <code>n</code> with -the bits <code>field</code> to <code>field + width - 1</code> -replaced by the value <code>v</code>. -See <a href="#pdf-bit32.extract"><code>bit32.extract</code></a> for details about <code>field</code> and <code>width</code>. - - - - -<p> -<hr><h3><a name="pdf-bit32.lrotate"><code>bit32.lrotate (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> rotated <code>disp</code> bits to the left. -The number <code>disp</code> may be any representable integer. - - -<p> -For any valid displacement, -the following identity holds: - -<pre> - assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32)) -</pre><p> -In particular, -negative displacements rotate to the right. - - - - -<p> -<hr><h3><a name="pdf-bit32.lshift"><code>bit32.lshift (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the left. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the right. -In any direction, vacant bits are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero (all bits are shifted out). - - -<p> -For positive displacements, -the following equality holds: - -<pre> - assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32) -</pre> - - - -<p> -<hr><h3><a name="pdf-bit32.rrotate"><code>bit32.rrotate (x, disp)</code></a></h3> - - -<p> -Returns the number <code>x</code> rotated <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. - - -<p> -For any valid displacement, -the following identity holds: - -<pre> - assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32)) -</pre><p> -In particular, -negative displacements rotate to the left. - - - - -<p> -<hr><h3><a name="pdf-bit32.rshift"><code>bit32.rshift (x, disp)</code></a></h3> - - <p> -Returns the number <code>x</code> shifted <code>disp</code> bits to the right. -The number <code>disp</code> may be any representable integer. -Negative displacements shift to the left. -In any direction, vacant bits are filled with zeros. -In particular, -displacements with absolute values higher than 31 -result in zero (all bits are shifted out). - +<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> -<p> -For positive displacements, -the following equality holds: - -<pre> - assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp)) -</pre> <p> -This shift operation is what is called logical shift. +Returns "<code>integer</code>" if <code>x</code> is an integer, +"<code>float</code>" if it is a float, +or <b>nil</b> if <code>x</code> is not a number. @@ -9179,24 +9094,24 @@ This shift operation is what is called logical shift. <p> The I/O library provides two different styles for file manipulation. -The first one uses implicit file descriptors; +The first one uses implicit file handles; that is, there are operations to set a default input file and a default output file, and all input/output operations are over these default files. -The second style uses explicit file descriptors. +The second style uses explicit file handles. <p> -When using implicit file descriptors, +When using implicit file handles, all operations are supplied by table <a name="pdf-io"><code>io</code></a>. -When using explicit file descriptors, -the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor -and then all operations are supplied as methods of the file descriptor. +When using explicit file handles, +the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle +and then all operations are supplied as methods of the file handle. <p> The table <code>io</code> also provides -three predefined file descriptors with their usual meanings from C: +three predefined file handles with their usual meanings from C: <a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. The I/O library never closes these files. @@ -9207,7 +9122,7 @@ all I/O functions return <b>nil</b> on failure (plus an error message as a second result and a system-dependent error code as a third result) and some value different from <b>nil</b> on success. -On non-Posix systems, +On non-POSIX systems, the computation of the error message and error code in case of errors may be not thread safe, @@ -9264,12 +9179,12 @@ Opens the given file name in read mode and returns an iterator function that works like <code>file:lines(···)</code> over the opened file. When the iterator function detects the end of file, -it returns <b>nil</b> (to finish the loop) and automatically closes the file. +it returns no values (to finish the loop) and automatically closes the file. <p> The call <code>io.lines()</code> (with no file name) is equivalent -to <code>io.input():lines()</code>; +to <code>io.input():lines("*l")</code>; that is, it iterates over the lines of the default input file. In this case it does not close the file when the loop ends. @@ -9449,7 +9364,7 @@ instead of returning an error code. Reads the file <code>file</code>, according to the given formats, which specify what to read. For each format, -the function returns a string (or a number) with the characters read, +the function returns a string or a number with the characters read, or <b>nil</b> if it cannot read data with the specified format. When called without formats, it uses a default format that reads the next line @@ -9462,8 +9377,15 @@ The available formats are <ul> <li><b>"<code>*n</code>": </b> -reads a number; -this is the only format that returns a number instead of a string. +reads a number and returns it as a float. +If the input has only a prefix of a valid number +(e.g., "<code>0x</code>" or "<code>3.4e-</code>"), +this format can read the entire prefix +even when returning <b>nil</b>. +</li> + +<li><b>"<code>*i</code>": </b> +reads an integral number and returns it as an integer. </li> <li><b>"<code>*a</code>": </b> @@ -9478,19 +9400,21 @@ This is the default format. </li> <li><b>"<code>*L</code>": </b> -reads the next line keeping the end of line (if present), +reads the next line keeping the end-of-line character (if present), returning <b>nil</b> on end of file. </li> <li><b><em>number</em>: </b> reads a string with up to this number of bytes, returning <b>nil</b> on end of file. -If number is zero, +If <code>number</code> is zero, it reads nothing and returns an empty string, or <b>nil</b> on end of file. </li> -</ul> +</ul><p> +The formats "<code>*l</code>" and "<code>*L</code>" should be used only for text files. + @@ -9643,7 +9567,7 @@ the host system and on the current locale <p> -On non-Posix systems, +On non-POSIX systems, this function may be not thread safe because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. @@ -9673,7 +9597,7 @@ Its first result is <b>true</b> if the command terminated successfully, or <b>nil</b> otherwise. After this first result -the function returns a string and a number, +the function returns a string plus a number, as follows: <ul> @@ -9975,8 +9899,9 @@ and raises an error when called with a level out of range. <p> Variable names starting with '<code>(</code>' (open parenthesis) -represent internal variables -(loop control variables, temporaries, varargs, and C function locals). +represent variables with no known names +(internal variables like loop control variables, +and variables from chunks saved without debug information). <p> @@ -10017,6 +9942,12 @@ with index <code>up</code> of the function <code>f</code>. The function returns <b>nil</b> if there is no upvalue with the given index. +<p> +Variable names starting with '<code>(</code>' (open parenthesis) +represent variables with no known names +(variables from chunks saved without debug information). + + <p> @@ -10037,8 +9968,8 @@ returns <b>nil</b>. <p> Returns the number of bits in the underlying representation -of integer (if <code>t</code> is "<code>i</code>") -or float numbers (if <code>t</code> is "<code>f</code>"). +of an integer (if <code>t</code> is "<code>i</code>") +or a float (if <code>t</code> is "<code>f</code>"). @@ -10140,7 +10071,6 @@ Otherwise, it returns the name of the upvalue. <p> Sets the given <code>value</code> as the Lua value associated to the given <code>udata</code>. -<code>value</code> must be a table or <b>nil</b>; <code>udata</code> must be a full userdata. @@ -10352,139 +10282,65 @@ is a more portable solution.) <p> Here we list the incompatibilities that you may find when moving a program -from Lua 5.1 to Lua 5.2. +from Lua 5.2 to Lua 5.3. You can avoid some incompatibilities by compiling Lua with appropriate options (see file <code>luaconf.h</code>). However, -all these compatibility options will be removed in the next version of Lua. -Similarly, -all features marked as deprecated in Lua 5.1 -have been removed in Lua 5.2. - - - -<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> -<ul> - -<li> -The concept of <em>environment</em> changed. -Only Lua functions have environments. -To set the environment of a Lua function, -use the variable <code>_ENV</code> or the function <a href="#pdf-load"><code>load</code></a>. +all these compatibility options will be removed in the future. <p> -C functions no longer have environments. -Use an upvalue with a shared table if you need to keep -shared state among several C functions. -(You may use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> to open a C library -with all functions sharing a common upvalue.) +Lua versions can always change the C API in ways that +do not imply source-code changes in a program, +such as the numeric values for constants +or the implementation of functions as macros. +Therefore, +you should never assume that binaries are compatible between +different Lua versions. +Always recompile clients of the Lua API when +using a new version. <p> -To manipulate the "environment" of a userdata -(which is now called user value), -use the new functions -<a href="#lua_getuservalue"><code>lua_getuservalue</code></a> and <a href="#lua_setuservalue"><code>lua_setuservalue</code></a>. -</li> - -<li> -Lua identifiers cannot use locale-dependent letters. -</li> - -<li> -Doing a step or a full collection in the garbage collector -does not restart the collector if it has been stopped. -</li> - -<li> -Weak tables with weak keys now perform like <em>ephemeron tables</em>. -</li> - -<li> -The event <em>tail return</em> in debug hooks was removed. -Instead, tail calls generate a special new event, -<em>tail call</em>, so that the debugger can know that -there will not be a corresponding return event. -</li> - -<li> -Equality between function values has changed. -Now, a function definition may not create a new value; -it may reuse some previous value if there is no -observable difference to the new function. -</li> - -</ul> - +The standard paths in the official distribution may +change between versions. -<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> +<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> <ul> <li> -Function <code>module</code> is deprecated. -It is easy to set up a module with regular Lua code. -Modules are not expected to set global variables. -</li> +The main difference between Lua 5.2 and Lua 5.3 is the +introduction of an integer subtype for numbers. +Although this change should not affect "normal" computations, +some computations +(mainly those that involve some kind of overflow) +can give different results. -<li> -Functions <code>setfenv</code> and <code>getfenv</code> were removed, -because of the changes in environments. -</li> - -<li> -Function <code>math.log10</code> is deprecated. -Use <a href="#pdf-math.log"><code>math.log</code></a> with 10 as its second argument, instead. -</li> - -<li> -Function <code>loadstring</code> is deprecated. -Use <code>load</code> instead; it now accepts string arguments -and are exactly equivalent to <code>loadstring</code>. -</li> - -<li> -Function <code>table.maxn</code> is deprecated. -Write it in Lua if you really need it. -</li> - -<li> -Function <code>os.execute</code> now returns <b>true</b> when command -terminates successfully and <b>nil</b> plus error information -otherwise. -</li> - -<li> -Function <code>unpack</code> was moved into the table library -and therefore must be called as <a href="#pdf-table.unpack"><code>table.unpack</code></a>. -</li> -<li> -Character class <code>%z</code> in patterns is deprecated, -as now patterns may contain '<code>\0</code>' as a regular character. -</li> +<p> +You can fix these differences by forcing a number to be a float +(in Lua 5.2 all numbers were float), +in particular writing constants with an ending <code>.0</code> +or using <code>x = x + 0.0</code> to convert a variable. +(This recommendation is only for a quick fix +for an occasional incompatibility, +not as a general guideline for good programming. +For good programming, +use floats where you need floats +and integers where you need integers.) -<li> -The table <code>package.loaders</code> was renamed <code>package.searchers</code>. -</li> -<li> -Lua does not have bytecode verification anymore. -So, all functions that load code -(<a href="#pdf-load"><code>load</code></a> and <a href="#pdf-loadfile"><code>loadfile</code></a>) -are potentially insecure when loading untrusted binary data. -(Actually, those functions were already insecure because -of flaws in the verification algorithm.) -When in doubt, -use the <code>mode</code> argument of those functions -to restrict them to loading textual chunks. +<p> +Although not formally an incompatibility, +the proper differentiation between floats and integers +can sometimes have a big impact on performance. </li> <li> -The standard paths in the official distribution may -change between versions. +The generational mode for the garbage collector was removed. +(It was an experimental feature in Lua 5.2.) </li> </ul> @@ -10492,76 +10348,39 @@ change between versions. -<h2>8.3 – <a name="8.3">Changes in the API</a></h2> +<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> <ul> <li> -Pseudoindex <code>LUA_GLOBALSINDEX</code> was removed. -You must get the global environment from the registry -(see <a href="#4.5">§4.5</a>). +The conversion of a float to a string through <a href="#pdf-tostring"><code>tostring</code></a> +(which is used by <a href="#pdf-print"><code>print</code></a>) now adds a <code>.0</code> suffix if the +number has an integral value. +(For instance, the float 2.0 will be printed as <code>2.0</code>, +not as <code>2</code>.) +You should always use an explicit format +when you need a specific format for numbers. </li> <li> -Pseudoindex <code>LUA_ENVIRONINDEX</code> -and functions <code>lua_getfenv</code>/<code>lua_setfenv</code> -were removed, -as C functions no longer have environments. +The <code>bit32</code> library has been deprecated. +It is easy to require a compatible external library or, +better yet, to replace its functions with appropriate bitwise operations. +(Just keep in mind that <code>bit32</code> operates on 32-bit integers, +while the bitwise operators in Standard Lua operate on 64-bit integers.) </li> -<li> -Function <code>luaL_register</code> is deprecated. -Use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> so that your module does not create globals. -(Modules are not expected to set global variables anymore.) -</li> +</ul> -<li> -The <code>osize</code> argument to the allocation function -may not be zero when creating a new block, -that is, when <code>ptr</code> is <code>NULL</code> -(see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). -Use only the test <code>ptr == NULL</code> to check whether -the block is new. -</li> -<li> -Finalizers (<code>__gc</code> metamethods) for userdata are called in the -reverse order that they were marked for finalization, -not that they were created (see <a href="#2.5.1">§2.5.1</a>). -(Most userdata are marked immediately after they are created.) -Moreover, -if the metatable does not have a <code>__gc</code> field when set, -the finalizer will not be called, -even if it is set later. -</li> - -<li> -<code>luaL_typerror</code> was removed. -Write your own version if you need it. -</li> -<li> -Function <code>lua_cpcall</code> is deprecated. -You can simply push the function with <a href="#lua_pushcfunction"><code>lua_pushcfunction</code></a> -and call it with <a href="#lua_pcall"><code>lua_pcall</code></a>. -</li> -<li> -Functions <code>lua_equal</code> and <code>lua_lessthan</code> are deprecated. -Use the new <a href="#lua_compare"><code>lua_compare</code></a> with appropriate options instead. -</li> +<h2>8.3 – <a name="8.3">Changes in the API</a></h2> -<li> -Function <code>lua_objlen</code> was renamed <a href="#lua_rawlen"><code>lua_rawlen</code></a>. -</li> -<li> -Function <a href="#lua_load"><code>lua_load</code></a> has an extra parameter, <code>mode</code>. -Pass <code>NULL</code> to simulate the old behavior. -</li> +<ul> <li> -Function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter, <code>from</code>. -Pass <code>NULL</code> or the thread doing the call. +No changes (yet). </li> </ul> @@ -10649,17 +10468,17 @@ Here is the complete syntax of Lua in extended BNF. - +} <HR> <SMALL CLASS="footer"> Last update: -Fri Jul 5 23:09:01 BRT 2013 +Fri Mar 21 17:33:56 BRT 2014 </SMALL> <!-- -Last change: updated for Lua 5.3.0 (work1) +Last change: updated for Lua 5.3.0 (work2) --> </body></html> |