diff options
| author | Peter Drahoš <drahosp@gmail.com> | 2011-12-17 00:09:39 +0100 |
|---|---|---|
| committer | Peter Drahoš <drahosp@gmail.com> | 2011-12-17 00:09:39 +0100 |
| commit | 9358cd648bc92ccdd4b3492375a53f2c8ca18bbc (patch) | |
| tree | b02f34a7dea1a90ae30a2e6c81430f1bcf9f1826 | |
| parent | 52eff16f51750cf47afaa5ac27a8705a1c580859 (diff) | |
| download | lua-9358cd648bc92ccdd4b3492375a53f2c8ca18bbc.tar.gz | |
Lua 5.2 release.
| -rw-r--r--[-rwxr-xr-x] | doc/contents.html | 21 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/logo.gif | bin | 4232 -> 4232 bytes | |||
| -rw-r--r-- | doc/lua.1 | 116 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/lua.css | 5 | ||||
| -rw-r--r-- | doc/luac.1 | 118 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/manual.css | 8 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/manual.html | 1133 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/osi-certified-72x60.png | bin | 3774 -> 3774 bytes | |||
| -rw-r--r--[-rwxr-xr-x] | doc/readme.html | 110 | ||||
| -rw-r--r-- | src/luaconf.h | 529 |
10 files changed, 1501 insertions, 539 deletions
diff --git a/doc/contents.html b/doc/contents.html index 788bf6c..5342723 100755..100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -21,11 +21,6 @@ Lua 5.2 Reference Manual </H1> <P> -<IMG SRC="alert.png" ALIGN="absbottom" ALT="[!]"> -<EM>This is a beta version of Lua 5.2. -Some details may change in the final version.</EM> - -<P> The reference manual is the official definition of the Lua language. For a complete introduction to Lua programming, see the book <A HREF="http://www.lua.org/docs.html#books">Programming in Lua</A>. @@ -95,7 +90,7 @@ Freely available under the terms of the <UL> <LI><A HREF="manual.html#4.1">4.1 – The Stack</A> <LI><A HREF="manual.html#4.2">4.2 – Stack Size</A> -<LI><A HREF="manual.html#4.3">4.3 – Pseudo-Indices</A> +<LI><A HREF="manual.html#4.3">4.3 – Valid and Acceptable Indices</A> <LI><A HREF="manual.html#4.4">4.4 – C Closures</A> <LI><A HREF="manual.html#4.5">4.5 – Registry</A> <LI><A HREF="manual.html#4.6">4.6 – Error Handling in C</A> @@ -154,8 +149,8 @@ Freely available under the terms of the <A HREF="manual.html#pdf-error">error</A><BR> <A HREF="manual.html#pdf-getmetatable">getmetatable</A><BR> <A HREF="manual.html#pdf-ipairs">ipairs</A><BR> -<A HREF="manual.html#pdf-load">load</A><BR> <A HREF="manual.html#pdf-loadfile">loadfile</A><BR> +<A HREF="manual.html#pdf-load">load</A><BR> <A HREF="manual.html#pdf-next">next</A><BR> <A HREF="manual.html#pdf-pairs">pairs</A><BR> <A HREF="manual.html#pdf-pcall">pcall</A><BR> @@ -406,6 +401,8 @@ Freely available under the terms of the <A HREF="manual.html#lua_rawlen">lua_rawlen</A><BR> <A HREF="manual.html#lua_rawset">lua_rawset</A><BR> <A HREF="manual.html#lua_rawseti">lua_rawseti</A><BR> +<A HREF="manual.html#lua_rawgetp">lua_rawgetp</A><BR> +<A HREF="manual.html#lua_rawsetp">lua_rawsetp</A><BR> <A HREF="manual.html#lua_register">lua_register</A><BR> <A HREF="manual.html#lua_remove">lua_remove</A><BR> <A HREF="manual.html#lua_replace">lua_replace</A><BR> @@ -463,8 +460,8 @@ Freely available under the terms of the <A HREF="manual.html#luaL_buffinitsize">luaL_buffinitsize</A><BR> <A HREF="manual.html#luaL_callmeta">luaL_callmeta</A><BR> <A HREF="manual.html#luaL_checkany">luaL_checkany</A><BR> -<A HREF="manual.html#luaL_checkint">luaL_checkint</A><BR> <A HREF="manual.html#luaL_checkinteger">luaL_checkinteger</A><BR> +<A HREF="manual.html#luaL_checkint">luaL_checkint</A><BR> <A HREF="manual.html#luaL_checklong">luaL_checklong</A><BR> <A HREF="manual.html#luaL_checklstring">luaL_checklstring</A><BR> <A HREF="manual.html#luaL_checknumber">luaL_checknumber</A><BR> @@ -486,15 +483,17 @@ Freely available under the terms of the <A HREF="manual.html#luaL_gsub">luaL_gsub</A><BR> <A HREF="manual.html#luaL_len">luaL_len</A><BR> <A HREF="manual.html#luaL_loadbuffer">luaL_loadbuffer</A><BR> +<A HREF="manual.html#luaL_loadbufferx">luaL_loadbufferx</A><BR> <A HREF="manual.html#luaL_loadfile">luaL_loadfile</A><BR> +<A HREF="manual.html#luaL_loadfilex">luaL_loadfilex</A><BR> <A HREF="manual.html#luaL_loadstring">luaL_loadstring</A><BR> <A HREF="manual.html#luaL_newlib">luaL_newlib</A><BR> <A HREF="manual.html#luaL_newlibtable">luaL_newlibtable</A><BR> <A HREF="manual.html#luaL_newmetatable">luaL_newmetatable</A><BR> <A HREF="manual.html#luaL_newstate">luaL_newstate</A><BR> <A HREF="manual.html#luaL_openlibs">luaL_openlibs</A><BR> -<A HREF="manual.html#luaL_optint">luaL_optint</A><BR> <A HREF="manual.html#luaL_optinteger">luaL_optinteger</A><BR> +<A HREF="manual.html#luaL_optint">luaL_optint</A><BR> <A HREF="manual.html#luaL_optlong">luaL_optlong</A><BR> <A HREF="manual.html#luaL_optlstring">luaL_optlstring</A><BR> <A HREF="manual.html#luaL_optnumber">luaL_optnumber</A><BR> @@ -522,10 +521,10 @@ Freely available under the terms of the <HR> <SMALL CLASS="footer"> Last update: -Tue Jun 28 14:53:13 BRT 2011 +Tue Nov 29 22:30:23 BRST 2011 </SMALL> <!-- -Last change: revised for Lua 5.2.0 (beta) +Last change: revised for Lua 5.2.0 --> </BODY> diff --git a/doc/logo.gif b/doc/logo.gif Binary files differindex 2f5e4ac..2f5e4ac 100755..100644 --- a/doc/logo.gif +++ b/doc/logo.gif diff --git a/doc/lua.1 b/doc/lua.1 new file mode 100644 index 0000000..1dbf043 --- /dev/null +++ b/doc/lua.1 @@ -0,0 +1,116 @@ +.\" $Id: lua.man,v 1.13 2011/11/16 17:16:53 lhf Exp $ +.TH LUA 1 "$Date: 2011/11/16 17:16:53 $" +.SH NAME +lua \- Lua interpreter +.SH SYNOPSIS +.B lua +[ +.I options +] +[ +.I script +[ +.I args +] +] +.SH DESCRIPTION +.B lua +is the standalone Lua interpreter. +It loads and executes Lua programs, +either in textual source form or +in precompiled binary form. +(Precompiled binaries are output by +.BR luac , +the Lua compiler.) +.B lua +can be used as a batch interpreter and also interactively. +.LP +The given +.I options +are handled in order and then +the Lua program in file +.I script +is loaded and executed. +The given +.I args +are available to +.I script +as strings in a global table named +.BR arg . +If no options or arguments are given, +then +.B "\-v \-i" +is assumed when the standard input is a terminal; +otherwise, +.B "\-" +is assumed. +.LP +In interactive mode, +.B lua +prompts the user, +reads lines from the standard input, +and executes them as they are read. +If a line does not contain a complete statement, +then a secondary prompt is displayed and +lines are read until a complete statement is formed or +a syntax error is found. +If a line starts with +.BR '=' , +then +.B lua +evaluates and displays +the values of the expressions in the remainder of the line. +.LP +At the very start, +before even handling the command line, +.B lua +checks the contents of the environment variables +.B LUA_INIT_5_2 +or +.BR LUA_INIT , +in that order. +If the contents is of the form +.RI '@ filename ', +then +.I filename +is executed. +Otherwise, the string is assumed to be a Lua statement and is executed. +.SH OPTIONS +.TP +.BI \-e " stat" +execute statement +.IR stat . +.TP +.B \-i +enter interactive mode after executing +.IR script . +.TP +.BI \-l " name" +execute the equivalent of +.IB name =require(' name ') +before executing +.IR script . +.TP +.B \-v +show version information. +.TP +.B \-E +ignore environment variables. +.TP +.B \-\- +stop handling options. +.TP +.B \- +stop handling options and execute the standard input as a file. +.SH "SEE ALSO" +.BR luac (1) +.br +The documentation at lua.org, +especially section 7 of the reference manual. +.SH DIAGNOSTICS +Error messages should be self explanatory. +.SH AUTHORS +R. Ierusalimschy, +L. H. de Figueiredo, +W. Celes +.\" EOF diff --git a/doc/lua.css b/doc/lua.css index fb462d9..54708f8 100755..100644 --- a/doc/lua.css +++ b/doc/lua.css @@ -1,7 +1,6 @@ body { color: #000000 ; background-color: #FFFFFF ; - font-family: sans-serif ; font-family: Helvetica, Arial, sans-serif ; text-align: justify ; margin-right: 20px ; @@ -18,12 +17,13 @@ h2 { padding-top: 0.4em ; padding-bottom: 0.4em ; padding-left: 20px ; + padding-right: 20px ; margin-left: -20px ; background-color: #E0E0FF ; } h3 { - padding-left: 8px ; + padding-left: 0.5em ; border-left: solid #E0E0FF 1em ; } @@ -76,7 +76,6 @@ input[type=text] { -moz-border-radius: 2em ; background-image: url('images/search.png') ; background-repeat: no-repeat; - background-position: left center ; background-position: 4px center ; padding-left: 20px ; height: 2em ; diff --git a/doc/luac.1 b/doc/luac.1 new file mode 100644 index 0000000..33a4ed0 --- /dev/null +++ b/doc/luac.1 @@ -0,0 +1,118 @@ +.\" $Id: luac.man,v 1.29 2011/11/16 13:53:40 lhf Exp $ +.TH LUAC 1 "$Date: 2011/11/16 13:53:40 $" +.SH NAME +luac \- Lua compiler +.SH SYNOPSIS +.B luac +[ +.I options +] [ +.I filenames +] +.SH DESCRIPTION +.B luac +is the Lua compiler. +It translates programs written in the Lua programming language +into binary files containing precompiled chunks +that can be later loaded and executed. +.LP +The main advantages of precompiling chunks are: +faster loading, +protecting source code from accidental user changes, +and +off-line syntax checking. +Precompiling does not imply faster execution +because in Lua chunks are always compiled into bytecodes before being executed. +.B luac +simply allows those bytecodes to be saved in a file for later execution. +Precompiled chunks are not necessarily smaller than the corresponding source. +The main goal in precompiling is faster loading. +.LP +In the command line, +you can mix +text files containing Lua source and +binary files containing precompiled chunks. +.B luac +produces a single output file containing the combined bytecodes +for all files given. +Executing the combined file is equivalent to executing the given files. +By default, +the output file is named +.BR luac.out , +but you can change this with the +.B \-o +option. +.LP +Precompiled chunks are +.I not +portable across different architectures. +Moreover, +the internal format of precompiled chunks +is likely to change when a new version of Lua is released. +Make sure you save the source files of all Lua programs that you precompile. +.LP +.SH OPTIONS +.TP +.B \-l +produce a listing of the compiled bytecode for Lua's virtual machine. +Listing bytecodes is useful to learn about Lua's virtual machine. +If no files are given, then +.B luac +loads +.B luac.out +and lists its contents. +Use +.B \-l \-l +for a full listing. +.TP +.BI \-o " file" +output to +.IR file , +instead of the default +.BR luac.out . +(You can use +.B "'\-'" +for standard output, +but not on platforms that open standard output in text mode.) +The output file may be one of the given files because +all files are loaded before the output file is written. +Be careful not to overwrite precious files. +.TP +.B \-p +load files but do not generate any output file. +Used mainly for syntax checking and for testing precompiled chunks: +corrupted files will probably generate errors when loaded. +If no files are given, then +.B luac +loads +.B luac.out +and tests its contents. +No messages are displayed if the file loads without errors. +.TP +.B \-s +strip debug information before writing the output file. +This saves some space in very large chunks, +but if errors occur when running a stripped chunk, +then the error messages may not contain the full information they usually do. +In particular, +line numbers and names of local variables are lost. +.TP +.B \-v +show version information. +.TP +.B \-\- +stop handling options. +.TP +.B \- +stop handling options and process standard input. +.SH "SEE ALSO" +.BR lua (1) +.br +The documentation at lua.org. +.SH DIAGNOSTICS +Error messages should be self explanatory. +.SH AUTHORS +R. Ierusalimschy, +L. H. de Figueiredo, +W. Celes +.\" EOF diff --git a/doc/manual.css b/doc/manual.css index 6d5a3f0..ac357a8 100755..100644 --- a/doc/manual.css +++ b/doc/manual.css @@ -1,14 +1,18 @@ h3 code { font-family: inherit ; + font-size: inherit ; } -pre { - font-size: 105% ; +pre, code { + font-size: 12pt ; } span.apii { float: right ; font-family: inherit ; + font-style: normal ; + font-size: small ; + color: gray ; } p+h1, ul+h1 { diff --git a/doc/manual.html b/doc/manual.html index 7215565..360d316 100755..100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -16,11 +16,6 @@ Lua 5.2 Reference Manual </h1> -<IMG SRC="alert.png" ALIGN="absbottom" ALT="[!]"> -<EM>This is a beta version of Lua 5.2. -Some details may change in the final version.</EM> -<P> - by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes <p> <small> @@ -38,7 +33,7 @@ Freely available under the terms of the <!-- ====================================================================== --> <p> -<!-- $Id: manual.of,v 1.86 2011/07/08 20:00:45 roberto Exp $ --> +<!-- $Id: manual.of,v 1.94 2011/12/12 15:26:26 roberto Exp $ --> @@ -51,8 +46,8 @@ general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. -Lua is intended to be used as a powerful, light-weight -scripting language for any program that needs one. +Lua is intended to be used as a powerful, lightweight, +embeddable scripting language for any program that needs one. Lua is implemented as a library, written in <em>clean C</em>, the common subset of Standard C and C++. @@ -86,14 +81,14 @@ this document is dry in places. For a discussion of the decisions behind the design of Lua, see the technical papers available at Lua's web site. For a detailed introduction to programming in Lua, -see Roberto's book, <em>Programming in Lua</em> (second edition). +see Roberto's book, <em>Programming in Lua</em>. <h1>2 – <a name="2">Basic Concepts</a></h1> <p> -This section describes some basic concepts of the language. +This section describes the basic concepts of the language. @@ -148,11 +143,14 @@ functions written in C <p> The type <em>userdata</em> is provided to allow arbitrary C data to be stored in Lua variables. -This type corresponds to a block of raw memory -and has no pre-defined operations in Lua, +A userdata value is a pointer to a block of raw memory. +There are two kinds of userdata: +full userdata, where the block of memory is managed by Lua, +and light userdata, where the block of memory is managed by the host. +Userdata has no predefined operations in Lua, except assignment and identity test. -However, by using <em>metatables</em>, -the programmer can define operations for userdata values +By using <em>metatables</em>, +the programmer can define operations for full userdata values (see <a href="#2.4">§2.4</a>). Userdata values cannot be created or modified in Lua, only through the C API. @@ -200,7 +198,7 @@ which is called the length of the sequence (see <a href="#3.4.6">§3.4.6</a> <p> Like indices, -the value of a table field can be of any type. +the values of table fields can be of any type. In particular, because functions are first-class values, table fields can contain functions. @@ -227,7 +225,7 @@ these operations do not imply any kind of copy. <p> The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type -of a given value. +of a given value (see <a href="#6.1">§6.1</a>). @@ -239,8 +237,8 @@ of a given value. As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, any reference to a global name <code>var</code> is syntactically translated to <code>_ENV.var</code>. -Moreover, every chunk is compiled in the scope of an external -variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), +Moreover, every chunk is compiled in the scope of +an external local variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), so <code>_ENV</code> itself is never a global name in a chunk. @@ -252,12 +250,11 @@ In particular, you can define new variables and parameters with that name. Each reference to a global name uses the <code>_ENV</code> that is visible at that point in the program, -following the usual visibility rules of Lua. +following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). <p> -Any table used as the value of <code>_ENV</code> is usually called -an <em>environment</em>. +Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. <p> @@ -268,13 +265,14 @@ In Lua, the variable <a href="#pdf-_G"><code>_G</code></a> is initialized with t <p> When Lua compiles a chunk, -it initializes the value of its <code>_ENV</code> variable +it initializes the value of its <code>_ENV</code> upvalue with the global environment (see <a href="#pdf-load"><code>load</code></a>). Therefore, by default, global variables in Lua code refer to entries in the global environment. -Moreover, all standard libraries are loaded in the global environment, +Moreover, all standard libraries are loaded in the global environment and several functions there operate on that environment. -You can use <a href="#pdf-load"><code>load</code></a> to load a chunk with a different environment. +You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) +to load a chunk with a different environment. (In C, you have to load the chunk and then change the value of its first upvalue.) @@ -325,7 +323,7 @@ any value for the error object. <p> When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, -you may give an <em>message handler</em> +you may give a <em>message handler</em> to be called in case of errors. This function is called with the original error message and returns a new error message. @@ -389,8 +387,8 @@ 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 also can define a function to be called when a userdata -is garbage collected. +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) @@ -427,8 +425,8 @@ This should be read as rawget(getmetatable(obj) or {}, event) </pre><p> -That is, the access to a metamethod does not invoke other metamethods, -and the access to objects with no metatables does not fail +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>). @@ -590,13 +588,17 @@ 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 same metamethod for the selected operation, +and the values are either tables or full userdata. <pre> - function getequalhandler (op1, op2, event) - if type(op1) ~= type(op2) then return nil end - local mm1 = metatable(op1)[event] - local mm2 = metatable(op2)[event] + 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> @@ -604,21 +606,19 @@ The "eq" event is defined as follows: <pre> function eq_event (op1, op2) - if type(op1) ~= type(op2) then -- different types? - return false -- different values - end if op1 == op2 then -- primitive equal? return true -- values are equal end -- try metamethod - local h = getequalhandler(op1, op2, "__eq") + local h = getequalhandler(op1, op2) if h then - return (h(op1, op2)) + return not not h(op1, op2) else return false end end </pre><p> +Note that the result is always a boolean. </li> <li><b>"lt": </b> @@ -634,13 +634,14 @@ the <code><</code> operation. else local h = getbinhandler(op1, op2, "__lt") if h then - return (h(op1, op2)) + return not not h(op1, op2) else error(···) end end end </pre><p> +Note that the result is always a boolean. </li> <li><b>"le": </b> @@ -656,7 +657,7 @@ the <code><=</code> operation. else local h = getbinhandler(op1, op2, "__le") if h then - return (h(op1, op2)) + return not not h(op1, op2) else h = getbinhandler(op1, op2, "__lt") if h then @@ -671,6 +672,11 @@ the <code><=</code> operation. 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>. + + +<p> +As with the other comparison operators, +the result is always a boolean. </li> <li><b>"index": </b> @@ -770,7 +776,7 @@ 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: -tables, userdata, functions, threads, strings, etc. +strings, tables, userdata, functions, threads, internal structures, etc. <p> @@ -819,10 +825,25 @@ 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. -With these functions you can also control +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.2, +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> @@ -879,11 +900,17 @@ the execution of the regular code. <p> -Because the object being collected must still be used by the finalizer -and even <em>resurrected</em> -(e.g., stored by the finalizer in a global variable), -the object memory is freed only when it becomes completely inaccessible -(that is, in the next garbage-collection cycle unless it was resurrected). +Because the object being collected must still be used by the finalizer, +it (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 there is a permanent resurrection. +In any case, +the object memory is freed only when it becomes completely inaccessible; +its finalizer will never be called twice. @@ -927,32 +954,42 @@ the pair is removed. <p> -After you use a table as a metatable, -you should not change the value of its <code>__mode</code> field. -Otherwise, the weak behavior of the tables controlled by this -metatable is undefined. +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 -can be removed from weak tables. -Values, such as numbers and booleans, +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 its associated value is collected). -Lua treats strings and light C functions as non-object values. +Although strings are subject to garbage collection, +they do not have an explicit construction, +and therefore are not removed from weak tables. <p> -Objects marked for finalization have a special behavior in weak tables. -When a marked object is a value in a weak table, -it is removed from the table before running its finalizer. -However, when it is a key, -it is removed from the table only after running its finalizer. +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. + + @@ -1060,7 +1097,6 @@ 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 @@ -1090,7 +1126,7 @@ and what their combinations mean. <p> -The language constructs will be explained using the usual extended BNF notation, +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>. @@ -1176,7 +1212,7 @@ into the string contents. <p> -A character in a literal string can also be specified by its numerical value. +A byte in a literal string can also be specified 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>, @@ -1407,13 +1443,13 @@ even if it does not use that variable. <p> A chunk can be stored in a file or in a string inside the host program. To execute a chunk, -Lua first pre-compiles the chunk into instructions for a virtual machine, +Lua first precompiles the chunk into instructions for a virtual machine, and then it executes the compiled code with an interpreter for the virtual machine. <p> -Chunks can also be pre-compiled into binary form; +Chunks can also be precompiled into binary form; see program <code>luac</code> for details. Programs in source and compiled forms are interchangeable; Lua automatically detects the file type and acts accordingly. @@ -1555,7 +1591,7 @@ enter into the scope of a local variable. <p> -Both labels and empty statements are called <em>void statements</em>, +Labels and empty statements are called <em>void statements</em>, as they perform no actions. @@ -1806,14 +1842,13 @@ and the unary <em>length operator</em> (see <a href="#3.4.6">§3.4.6</a>). <p> Both function calls and vararg expressions can result in multiple values. -If an expression is used as a statement -(only possible for function calls (see <a href="#3.3.6">§3.3.6</a>)), +If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), then its return list is adjusted to zero elements, thus discarding all returned values. If an expression is used as the last (or the only) element of a list of expressions, then no adjustment is made -(unless the call is enclosed in parentheses). +(unless the expression is enclosed in parentheses). In all other contexts, Lua adjusts the result list to one element, discarding all values except the first one. @@ -1881,8 +1916,7 @@ Lua provides automatic conversion between string and number values at run time. Any arithmetic operation applied to a string tries to convert this string to a number, following the rules of the Lua lexer. -(The string may have leading and trailing spaces, -plus an optional sign.) +(The string may have leading and trailing spaces and a sign.) Conversely, whenever a number is used where a string is expected, the number is converted to a string, in a reasonable format. For complete control over how numbers are converted to strings, @@ -1992,7 +2026,7 @@ 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>. -Otherwise, the "concat" metamethod is called (see <a href="#2.4">§2.4</a>). +Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). @@ -2254,8 +2288,8 @@ contains references to <code>f</code>.) <p> A function definition is an executable expression, whose value has type <em>function</em>. -When Lua pre-compiles a chunk, -all its function bodies are pre-compiled too. +When Lua precompiles a chunk, +all its function bodies are precompiled too. Then, whenever Lua executes the function definition, the function is <em>instantiated</em> (or <em>closed</em>). This function instance (or <em>closure</em>) @@ -2272,9 +2306,9 @@ initialized with the argument values: When a function is called, the list of arguments is adjusted to the length of the list of parameters, -unless the function is a variadic or <em>vararg function</em>, -which is -indicated by three dots ('<code>...</code>') at the end of its parameter list. +unless the function is a <em>vararg function</em>, +which is indicated by three dots ('<code>...</code>') +at the end of its parameter list. A vararg function does not adjust its argument list; instead, it collects all extra arguments and supplies them to the function through a <em>vararg expression</em>, @@ -2425,7 +2459,8 @@ are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. <p> Even when we use the term "function", any facility in the API may be provided as a macro instead. -All such macros use each of their arguments exactly once +Except where stated otherwise, +all such macros use each of their arguments exactly once (except for the first argument, which is always a Lua state), and so do not generate any hidden side-effects. @@ -2434,8 +2469,7 @@ and so do not generate any hidden side-effects. As in most C libraries, the Lua API functions do not check their arguments for validity or consistency. However, you can change this behavior by compiling Lua -with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>, -in file <code>luaconf.h</code>. +with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. @@ -2472,10 +2506,6 @@ index <em>n</em> represents the last element; index -1 also represents the last element (that is, the element at the top) and index <em>-n</em> represents the first element. -We say that an index is <em>valid</em> -if it lies between 1 and the stack top -(that is, if <code>1 ≤ abs(index) ≤ top</code>). - @@ -2494,7 +2524,7 @@ to ensure that the stack has extra slots when pushing new elements. <p> Whenever Lua calls C, -it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available. +it ensures that the stack has at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. <code>LUA_MINSTACK</code> is defined as 20, so that usually you do not have to worry about stack space unless your code has loops pushing elements onto the stack. @@ -2509,33 +2539,66 @@ So, before pushing anything in the stack after such a call you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. + + + +<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> + +<p> +Any function in the API that receives stack indices +works only with <em>valid indices</em> or <em>acceptable indices</em>. + + +<p> +A <em>valid index</em> is an index that refers to a +valid position within the stack, that is, +it lies between 1 and the stack top +(<code>1 ≤ abs(index) ≤ top</code>). + +Usually, functions that need a specific stack position +(e.g., <a href="#lua_remove"><code>lua_remove</code></a>) require valid indices. + + <p> -Most query functions accept as indices any value inside the -available stack space, that is, indices up to the maximum stack size -that you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>. -Such indices are called <em>acceptable indices</em>. -More formally, we define an <em>acceptable index</em> +Functions that do not need a specific stack position, +but only a value in the stack (e.g., query functions), +can be called with acceptable indices. +An <em>acceptable index</em> refers to a position within +the space allocated for the stack, +that is, indices up to the stack size. +More formally, we define an acceptable index as follows: <pre> (index < 0 && abs(index) <= top) || - (index > 0 && index <= stackspace) + (index > 0 && index <= stack size) </pre><p> -Note that 0 is never an acceptable index. +(Note that 0 is never an acceptable index.) +When a function is called, +its stack size is <code>top + LUA_MINSTACK</code>. +You can change its stack size through function <a href="#lua_checkstack"><code>lua_checkstack</code></a>. +<p> +Acceptable indices serve to avoid extra tests +against the stack top when querying the stack. +For instance, a C function can query its third argument +without the need to first check whether there is a third argument, +that is, without the need to check whether 3 is a valid index. +<p> +For functions that can be called with acceptable indices, +any non-valid index is treated as if it +contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. -<h2>4.3 – <a name="4.3">Pseudo-Indices</a></h2> <p> Unless otherwise noted, any function that accepts valid indices also accepts <em>pseudo-indices</em>, which represent some Lua values that are accessible to C code but which are not in the stack. -Pseudo-indices are used to access -the registry +Pseudo-indices are used to access the registry and the upvalues of a C function (see <a href="#4.4">§4.4</a>). @@ -2547,10 +2610,10 @@ and the upvalues of a C function (see <a href="#4.4">§4.4</a>). <p> When a C function is created, it is possible to associate some values with it, -thus creating a <em>C closure</em>; +thus creating a <em>C closure</em> +(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); these values are called <em>upvalues</em> and are -accessible to the function whenever it is called -(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). +accessible to the function whenever it is called. <p> @@ -2573,12 +2636,13 @@ produces an acceptable (but invalid) index. <p> Lua provides a <em>registry</em>, -a pre-defined table that can be used by any C code to -store whatever Lua value it needs to store. -This table is always located at pseudo-index +a predefined table that can be used by any C code to +store whatever Lua values it needs to store. +The registry table is always located at pseudo-index <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. Any C library can store data into this table, -but it should take care to choose keys different from those used +but it should take care to choose keys +that are different from those used by other libraries, to avoid collisions. Typically, you should use as key a string containing your library name, or a light userdata with the address of a C object in your code, @@ -2610,7 +2674,6 @@ the main thread of the state. <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has the global environment. -This is the C equivalent to the <a href="#pdf-_G"><code>_G</code></a> global variable. </li> </ul> @@ -2629,8 +2692,8 @@ and runtime errors) it <em>raises</em> an error; that is, it does a long jump. A <em>protected environment</em> uses <code>setjmp</code> -to set a recover point; -any error jumps to the most recent active recover point. +to set a recovery point; +any error jumps to the most recent active recovery point. <p> @@ -2639,7 +2702,16 @@ Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpani and then calls <code>abort</code>, thus exiting the host application. Your panic function can avoid this exit by -never returning (e.g., doing a long jump). +never returning +(e.g., doing a long jump to your own recovery point outside Lua). + + +<p> +The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); +in particular, the error message is at the top of the stack. +However, there is no guarantees about stack space. +To push anything on the stack, +the panic function should first check the available space (see <a href="#4.2">§4.2</a>). <p> @@ -2673,12 +2745,11 @@ Lua raises an error whenever it tries to yield across an API call, except for three functions: <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>. All those functions receive a <em>continuation function</em> -(as a parameter called <code>k</code>) to continue execution after an yield. +(as a parameter called <code>k</code>) to continue execution after a yield. <p> -To explain continuations, -let us set some terminology. +We need to set some terminology to explain continuations. We have a C function called from Lua which we will call the <em>original function</em>. This original function then calls one of those three functions in the C API, @@ -2704,7 +2775,7 @@ of the original function. <p> -Lua treats the continuation function as if it was the original function. +Lua treats the continuation function as if it were the original function. The continuation function receives the same Lua stack from the original function, in the same state it would be if the callee function had returned. @@ -2712,7 +2783,7 @@ in the same state it would be if the callee function had returned. after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are removed from the stack and replaced by the results from the call.) It also has the same upvalues. -Whatever it returns is handled by Lua as if it was the return +Whatever it returns is handled by Lua as if it were the return of the original function. @@ -2749,15 +2820,14 @@ by looking only at its arguments The third field, <code>x</code>, tells whether the function may throw errors: '<code>-</code>' means the function never throws any error; -'<code>m</code>' means the function may throw an error -only due to not enough memory; +'<code>m</code>' means the function may throw only memory allocation errors; '<code>e</code>' means the function may throw other kinds of errors; '<code>v</code>' means the function may throw an error on purpose. <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_absindex (lua_State *L, int idx);</pre> <p> @@ -2795,7 +2865,7 @@ that is, the size given when it was allocated or reallocated. <p> When <code>ptr</code> is <code>NULL</code>, -<code>osize</code> codes the kind of object that Lua is allocating. +<code>osize</code> encodes the kind of object that Lua is allocating. <code>osize</code> is any of <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when) @@ -2818,7 +2888,7 @@ and return <code>NULL</code>. When <code>nsize</code> is not zero, the allocator should behave like <code>realloc</code>. The allocator returns <code>NULL</code> -if and only if it cannot fill the request. +if and only if it cannot fulfill the request. Lua assumes that the allocator never fails when <code>osize >= nsize</code>. @@ -2843,8 +2913,8 @@ Note that Standard C ensures that <code>free(NULL)</code> has no effect and that <code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. This code assumes that <code>realloc</code> does not fail when shrinking a block. -Standard C does not ensure this behavior, -but it seems a safe assumption. +(Although Standard C does not ensure this behavior, +it seems to be a safe assumption.) @@ -2883,25 +2953,18 @@ The value of <code>op</code> must be one of the following constants: <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> <p> Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). -<p> -The panic function should not try to run anything on the failed Lua state. -However, it can still use the debug API (see <a href="#4.9">§4.9</a>) -to gather information about the state. -In particular, the error message is at the top of the stack. - - <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> -<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> +<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> <p> @@ -3025,12 +3088,12 @@ of numerical arguments and returns their average and sum: <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_checkstack (lua_State *L, int extra);</pre> <p> Ensures that there are at least <code>extra</code> free stack slots in the stack. -It returns false if it cannot grant the request, +It returns false if it cannot fulfill the request, because it would cause the stack to be larger than a fixed maximum size (typically at least a few thousand elements) or because it cannot allocate memory for the new stack size. @@ -3043,7 +3106,7 @@ it is left unchanged. <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void lua_close (lua_State *L);</pre> <p> @@ -3052,10 +3115,9 @@ Destroys all objects in the given Lua state and frees all dynamic memory used by this state. On several platforms, you may not need to call this function, because all resources are naturally released when the host program ends. -On the other hand, long-running programs, -such as a daemon or a web server, -might need to release states as soon as they are not needed, -to avoid growing too large. +On the other hand, long-running programs that create multiple states, +such as daemons or web servers, +might need to close states as soon as they are not needed. @@ -3066,6 +3128,7 @@ to avoid growing too large. <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> <p> +Compares two Lua values. Returns 1 if the value at acceptable index <code>index1</code> satisfies <code>op</code> when compared with the value at acceptable index <code>index2</code>, following the semantics of the corresponding Lua operator @@ -3106,7 +3169,7 @@ Concatenation is performed following the usual semantics of Lua <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> <p> @@ -3176,7 +3239,7 @@ Generates a Lua error. The error message (which can actually be a Lua value of any type) must be on the stack top. This function does a long jump, -and therefore never returns. +and therefore never returns (see <a href="#luaL_error"><code>luaL_error</code></a>). @@ -3245,10 +3308,20 @@ 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> -For more details about some options, +For more details about these options, see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. @@ -3256,7 +3329,7 @@ see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> <p> @@ -3269,7 +3342,7 @@ opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. <hr><h3><a name="lua_getctx"><code>lua_getctx</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_getctx (lua_State *L, int *ctx);</pre> <p> @@ -3293,12 +3366,12 @@ When the callee is <a href="#lua_pcallk"><code>lua_pcallk</code></a>, Lua may also call its continuation function to handle errors during the call. That is, upon an error in the function called by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, -Lua may not return <a href="#lua_pcallk"><code>lua_pcallk</code></a> +Lua may not return to the original function but instead may call the continuation function. In that case, a call to <a href="#lua_getctx"><code>lua_getctx</code></a> will return the error code (the value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>); the value of <code>ctx</code> will be set to the context information, -as in the case of an yield. +as in the case of a yield. @@ -3324,21 +3397,19 @@ for the "index" event (see <a href="#2.4">§2.4</a>). <p> Pushes onto the stack the value of the global <code>name</code>. -It is defined as a macro. <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>-</em>]</span> +<span class="apii">[-0, +(0|1), –]</span> <pre>int lua_getmetatable (lua_State *L, int index);</pre> <p> Pushes onto the stack the metatable of the value at the given acceptable index. -If the index is not valid, -or if the value does not have a metatable, +If the value does not have a metatable, the function returns 0 and pushes nothing on the stack. @@ -3366,7 +3437,7 @@ for the "index" event (see <a href="#2.4">§2.4</a>). <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_gettop (lua_State *L);</pre> <p> @@ -3380,7 +3451,7 @@ this result is equal to the number of elements in the stack <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_getuservalue (lua_State *L, int index);</pre> <p> @@ -3393,7 +3464,7 @@ This Lua value must be a table or <b>nil</b>. <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> -<span class="apii">[-1, +1, <em>-</em>]</span> +<span class="apii">[-1, +1, –]</span> <pre>void lua_insert (lua_State *L, int index);</pre> <p> @@ -3423,11 +3494,11 @@ which is usually the largest signed integral type the machine handles <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isboolean (lua_State *L, int index);</pre> <p> -Returns 1 if the value at the given acceptable index has type boolean, +Returns 1 if the value at the given acceptable index is a boolean, and 0 otherwise. @@ -3435,7 +3506,7 @@ and 0 otherwise. <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_iscfunction (lua_State *L, int index);</pre> <p> @@ -3447,7 +3518,7 @@ and 0 otherwise. <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isfunction (lua_State *L, int index);</pre> <p> @@ -3459,7 +3530,7 @@ Returns 1 if the value at the given acceptable index is a function <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_islightuserdata (lua_State *L, int index);</pre> <p> @@ -3471,7 +3542,7 @@ and 0 otherwise. <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isnil (lua_State *L, int index);</pre> <p> @@ -3483,7 +3554,7 @@ and 0 otherwise. <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isnone (lua_State *L, int index);</pre> <p> @@ -3496,7 +3567,7 @@ and 0 otherwise. <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isnoneornil (lua_State *L, int index);</pre> <p> @@ -3510,7 +3581,7 @@ and 0 otherwise. <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isnumber (lua_State *L, int index);</pre> <p> @@ -3523,7 +3594,7 @@ and 0 otherwise. <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isstring (lua_State *L, int index);</pre> <p> @@ -3536,7 +3607,7 @@ and 0 otherwise. <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_istable (lua_State *L, int index);</pre> <p> @@ -3548,7 +3619,7 @@ and 0 otherwise. <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isthread (lua_State *L, int index);</pre> <p> @@ -3560,7 +3631,7 @@ and 0 otherwise. <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_isuserdata (lua_State *L, int index);</pre> <p> @@ -3585,29 +3656,33 @@ The result is pushed on the stack. <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>int lua_load (lua_State *L, lua_Reader reader, void *data, - const char *source);</pre> + const char *source, + const char *mode);</pre> <p> -Loads a Lua chunk. +Loads a Lua chunk (without running it). If there are no errors, -<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua +<code>lua_load</code> pushes the compiled chunk as a Lua function on top of the stack. Otherwise, it pushes an error message. -The return values of <a href="#lua_load"><code>lua_load</code></a> are: + + +<p> +The return values of <code>lua_load</code> are: <ul> -<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors;</li> +<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> -syntax error during pre-compilation;</li> +syntax error during precompilation;</li> <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> -memory allocation error.</li> +memory allocation error;</li> <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> error while running a <code>__gc</code> metamethod. @@ -3618,17 +3693,7 @@ It is generated by the garbage collector.) </ul> <p> -This function only loads a chunk; -it does not run it. - - -<p> -<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary, -and loads it accordingly (see program <code>luac</code>). - - -<p> -The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function +The <code>lua_load</code> function uses a user-supplied <code>reader</code> function to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). The <code>data</code> argument is an opaque value passed to the reader function. @@ -3639,28 +3704,36 @@ which is used for error messages and in debug information (see <a href="#4.9">&s <p> +<code>lua_load</code> automatically detects whether the chunk is text or binary +and loads it accordingly (see program <code>luac</code>). +The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, +with the addition that +a <code>NULL</code> value is equivalent to the string "<code>bt</code>". + + +<p> If the resulting function has one upvalue, this upvalue is set to the value of the global environment stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). -(When loading main chunks, -this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).) +When loading main chunks, +this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> <p> Creates a new thread running in a new, independent state. -Returns <code>NULL</code> if cannot create the thread/state +Returns <code>NULL</code> if cannot create the thread or the state (due to lack of memory). The argument <code>f</code> is the allocator function; Lua does all memory allocation for this state through this function. The second argument, <code>ud</code>, is an opaque pointer that Lua -simply passes to the allocator in every call. +passes to the allocator in every call. @@ -3686,7 +3759,7 @@ It is equivalent to <code>lua_createtable(L, 0, 0)</code>. Creates a new thread, pushes it on the stack, and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. The new thread returned by this function shares with the original thread -all global objects (such as tables), +its global environment, but has an independent execution stack. @@ -3707,15 +3780,7 @@ like any Lua object. This function allocates a new block of memory with the given size, pushes onto the stack a new full userdata with the block address, and returns this address. - - -<p> -Userdata represent C values in Lua. -A <em>full userdata</em> represents a block of memory. -It is an object (like a table): -you must create it, it can have its own metatable, -and you can detect when it is being collected. -A full userdata is only equal to itself (under raw equality). +The host program can freely use this memory. @@ -3780,7 +3845,7 @@ Lua to operate with another type for numbers (e.g., float or long). <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> -<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> +<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> <p> @@ -3855,9 +3920,13 @@ It is generated by the garbage collector.) <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> -<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> -<pre>int lua_pcallk (lua_State *L, int nargs, int nresults, int errfunc, - int ctx, lua_CFunction k);</pre> +<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> +<pre>int lua_pcallk (lua_State *L, + int nargs, + int nresults, + int errfunc, + int ctx, + lua_CFunction k);</pre> <p> This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, @@ -3868,7 +3937,7 @@ but allows the called function to yield (see <a href="#4.7">§4.7</a>). <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> -<span class="apii">[-n, +0, <em>-</em>]</span> +<span class="apii">[-n, +0, –]</span> <pre>void lua_pop (lua_State *L, int n);</pre> <p> @@ -3879,7 +3948,7 @@ Pops <code>n</code> elements from the stack. <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushboolean (lua_State *L, int b);</pre> <p> @@ -3920,14 +3989,14 @@ The maximum value for <code>n</code> is 255. When <code>n</code> is zero, this function creates a <em>light C function</em>, which is just a pointer to the C function. -In that case, it cannot throw a memory error. +In that case, it never throws a memory error. <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> <p> @@ -3948,7 +4017,9 @@ and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code>< <pre> #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) -</pre> +</pre><p> +Note that <code>f</code> is used twice. + @@ -3980,7 +4051,7 @@ The conversion specifiers can only be '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</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 character). +'<code>%c</code>' (inserts an <code>int</code> as a byte). </li> </ul> @@ -3989,7 +4060,7 @@ The conversion specifiers can only be <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> <p> @@ -4000,7 +4071,7 @@ Pushes a number with value <code>n</code> onto the stack. <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> <p> @@ -4027,7 +4098,7 @@ light userdata with the same C address. <p> This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, but can be used only when <code>s</code> is a literal string. -In these cases, it automatically provides the string length. +It automatically provides the string length. @@ -4055,7 +4126,7 @@ Returns a pointer to the internal copy of the string. <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushnil (lua_State *L);</pre> <p> @@ -4066,7 +4137,7 @@ Pushes a nil value onto the stack. <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> <p> @@ -4100,7 +4171,7 @@ If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>int lua_pushthread (lua_State *L);</pre> <p> @@ -4112,7 +4183,7 @@ Returns 1 if this thread is the main thread of its state. <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_pushvalue (lua_State *L, int index);</pre> <p> @@ -4138,7 +4209,7 @@ instead of a variable number of arguments. <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> <p> @@ -4153,7 +4224,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, <em>-</em>]</span> +<span class="apii">[-1, +1, –]</span> <pre>void lua_rawget (lua_State *L, int index);</pre> <p> @@ -4165,7 +4236,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, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void lua_rawgeti (lua_State *L, int index, int n);</pre> <p> @@ -4178,8 +4249,23 @@ that is, it does not invoke metamethods. +<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> + +<p> +Pushes onto the stack the value <code>t[k]</code>, +where <code>t</code> is the table at the given valid index and +<code>k</code> is the pointer <code>p</code> represented as a light userdata. +The access is raw; +that is, it does not invoke metamethods. + + + + + <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>size_t lua_rawlen (lua_State *L, int index);</pre> <p> @@ -4226,6 +4312,26 @@ that is, it does not invoke metamethods. +<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> +<span class="apii">[-1, +0, <em>m</em>]</span> +<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> + +<p> +Does the equivalent of <code>t[k] = v</code>, +where <code>t</code> is the table at the given valid index, +<code>k</code> is the pointer <code>p</code> represented as a light userdata, +and <code>v</code> is the value at the top of the stack. + + +<p> +This function pops the value from the stack. +The assignment is raw; +that is, it does not invoke metamethods. + + + + + <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> <pre>typedef const char * (*lua_Reader) (lua_State *L, void *data, @@ -4250,9 +4356,7 @@ The reader function may return pieces of any size greater than zero. <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> <span class="apii">[-0, +0, <em>e</em>]</span> -<pre>void lua_register (lua_State *L, - const char *name, - lua_CFunction f);</pre> +<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> <p> Sets the C function <code>f</code> as the new value of global <code>name</code>. @@ -4267,7 +4371,7 @@ It is defined as a macro: <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> -<span class="apii">[-1, +0, <em>-</em>]</span> +<span class="apii">[-1, +0, –]</span> <pre>void lua_remove (lua_State *L, int index);</pre> <p> @@ -4281,7 +4385,7 @@ because a pseudo-index is not an actual stack position. <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> -<span class="apii">[-1, +0, <em>-</em>]</span> +<span class="apii">[-1, +0, –]</span> <pre>void lua_replace (lua_State *L, int index);</pre> <p> @@ -4295,8 +4399,8 @@ and then pops the top element. <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> -<span class="apii">[-?, +?, <em>-</em>]</span> -<pre>int lua_resume (lua_State *L, int narg);</pre> +<span class="apii">[-?, +?, –]</span> +<pre>int lua_resume (lua_State *L, lua_State *from, int narg);</pre> <p> Starts and resumes a coroutine in a given thread. @@ -4330,11 +4434,17 @@ be passed as results from <code>yield</code>, and then call <a href="#lua_resume"><code>lua_resume</code></a>. +<p> +The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. +If there is no such coroutine, +this parameter can be <code>NULL</code>. + + <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> <p> @@ -4371,14 +4481,13 @@ for the "newindex" event (see <a href="#2.4">§2.4</a>). <p> Pops a value from the stack and sets it as the new value of global <code>name</code>. -It is defined as a macro. <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> -<span class="apii">[-1, +0, <em>-</em>]</span> +<span class="apii">[-1, +0, –]</span> <pre>void lua_setmetatable (lua_State *L, int index);</pre> <p> @@ -4411,7 +4520,7 @@ for the "newindex" event (see <a href="#2.4">§2.4</a>). <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> -<span class="apii">[-?, +?, <em>-</em>]</span> +<span class="apii">[-?, +?, –]</span> <pre>void lua_settop (lua_State *L, int index);</pre> <p> @@ -4426,7 +4535,7 @@ If <code>index</code> is 0, then all stack elements are removed. <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> -<span class="apii">[-1, +0, <em>-</em>]</span> +<span class="apii">[-1, +0, –]</span> <pre>void lua_setuservalue (lua_State *L, int index);</pre> <p> @@ -4457,7 +4566,7 @@ which creates a Lua state from scratch. <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_status (lua_State *L);</pre> <p> @@ -4482,7 +4591,7 @@ You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_toboolean (lua_State *L, int index);</pre> <p> @@ -4501,7 +4610,7 @@ use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> <p> @@ -4514,18 +4623,18 @@ otherwise, returns <code>NULL</code>. <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> <p> -A macro equivalent to <code>lua_tointegerx(L, index, NULL)</code>. +Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> <p> @@ -4533,7 +4642,7 @@ Converts the Lua value at the given acceptable index to the signed integral type <a href="#lua_Integer"><code>lua_Integer</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>); -otherwise, <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> returns 0. +otherwise, <code>lua_tointegerx</code> returns 0. <p> @@ -4542,7 +4651,7 @@ it is truncated in some non-specified way. <p> -If <code>isnum</code> is different from <code>NULL</code>, +If <code>isnum</code> is not <code>NULL</code>, its referent is assigned a boolean value that indicates whether the operation succeeded. @@ -4561,20 +4670,20 @@ it also sets <code>*len</code> with the string length. The Lua value must be a string or a number; otherwise, the function returns <code>NULL</code>. If the value is a number, -then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also +then <code>lua_tolstring</code> also <em>changes the actual value in the stack to a string</em>. (This change confuses <a href="#lua_next"><code>lua_next</code></a> -when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) +when <code>lua_tolstring</code> is applied to keys during a table traversal.) <p> -<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer +<code>lua_tolstring</code> returns a fully aligned pointer to a string inside the Lua state. This string always has a zero ('<code>\0</code>') after its last character (as in C), but can contain other zeros in its body. Because Lua has garbage collection, -there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a> +there is no guarantee that the pointer returned by <code>lua_tolstring</code> will be valid after the corresponding value is removed from the stack. @@ -4582,18 +4691,18 @@ will be valid after the corresponding value is removed from the stack. <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> <p> -A macro equivalent to <code>lua_tonumberx(L, index, NULL)</code>. +Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> <p> @@ -4605,7 +4714,7 @@ otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns <p> -If <code>isnum</code> is different from <code>NULL</code>, +If <code>isnum</code> is not <code>NULL</code>, its referent is assigned a boolean value that indicates whether the operation succeeded. @@ -4614,14 +4723,14 @@ indicates whether the operation succeeded. <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>const void *lua_topointer (lua_State *L, int index);</pre> <p> Converts the value at the given acceptable index to a generic C pointer (<code>void*</code>). The value can be a userdata, a table, a thread, or a function; -otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. +otherwise, <code>lua_topointer</code> returns <code>NULL</code>. Different objects will give different pointers. There is no way to convert the pointer back to its original value. @@ -4645,7 +4754,7 @@ Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> <p> @@ -4659,18 +4768,18 @@ otherwise, the function returns <code>NULL</code>. <hr><h3><a name="lua_tounsigned"><code>lua_tounsigned</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Unsigned lua_tounsigned (lua_State *L, int index);</pre> <p> -A macro equivalent to <code>lua_tounsignedx(L, index, NULL)</code>. +Equivalent to <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> with <code>isnum</code> equal to <code>NULL</code>. <hr><h3><a name="lua_tounsignedx"><code>lua_tounsignedx</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);</pre> <p> @@ -4678,7 +4787,7 @@ Converts the Lua value at the given acceptable index to the unsigned integral type <a href="#lua_Unsigned"><code>lua_Unsigned</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>); -otherwise, <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> returns 0. +otherwise, <code>lua_tounsignedx</code> returns 0. <p> @@ -4690,7 +4799,7 @@ one more than the maximum representable value. <p> -If <code>isnum</code> is different from <code>NULL</code>, +If <code>isnum</code> is not <code>NULL</code>, its referent is assigned a boolean value that indicates whether the operation succeeded. @@ -4699,7 +4808,7 @@ indicates whether the operation succeeded. <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void *lua_touserdata (lua_State *L, int index);</pre> <p> @@ -4714,13 +4823,12 @@ Otherwise, returns <code>NULL</code>. <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_type (lua_State *L, int index);</pre> <p> Returns the type of the value in the given acceptable index, -or <code>LUA_TNONE</code> for a non-valid index -(that is, an index to an "empty" stack position). +or <code>LUA_TNONE</code> for a non-valid index. The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants defined in <code>lua.h</code>: <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, @@ -4739,7 +4847,7 @@ and <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>const char *lua_typename (lua_State *L, int tp);</pre> <p> @@ -4807,11 +4915,11 @@ calling the writer again. <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> -<span class="apii">[-?, +?, <em>-</em>]</span> +<span class="apii">[-?, +?, –]</span> <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> <p> -Exchange values between different threads of the same global state. +Exchange values between different threads of the same state. <p> @@ -4823,7 +4931,7 @@ and pushes them onto the stack <code>to</code>. <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> -<span class="apii">[-?, +?, <em>-</em>]</span> +<span class="apii">[-?, +?, –]</span> <pre>int lua_yield (lua_State *L, int nresults);</pre> <p> @@ -4838,7 +4946,7 @@ the function calling <code>lua_yield</code>. <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> -<span class="apii">[-?, +?, <em>-</em>]</span> +<span class="apii">[-?, +?, –]</span> <pre>int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);</pre> <p> @@ -4850,7 +4958,7 @@ This function should only be called as the return expression of a C function, as follows: <pre> - return lua_yield (L, nresults, i, k); + return lua_yieldk (L, n, i, k); </pre><p> When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a> in that way, the running coroutine suspends its execution, @@ -4928,7 +5036,7 @@ If <code>source</code> starts with a '<code>@</code>', it means that the function was defined in a file where the file name follows the '<code>@</code>'. If <code>source</code> starts with a '<code>=</code>', -the rest of it should describe the source in a user-dependent manner. +the remainder of its contents describe the source in a user-dependent manner. Otherwise, the function was defined in a string where <code>source</code> is that string. @@ -4994,7 +5102,7 @@ the number of fixed parameters of the function </li> <li><b><code>isvararg</code>: </b> -whether the function is a vararg function +true if the function is a vararg function (always true for C functions). </li> @@ -5004,7 +5112,7 @@ whether the function is a vararg function <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_Hook lua_gethook (lua_State *L);</pre> <p> @@ -5015,7 +5123,7 @@ Returns the current hook function. <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_gethookcount (lua_State *L);</pre> <p> @@ -5026,7 +5134,7 @@ Returns the current hook count. <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_gethookmask (lua_State *L);</pre> <p> @@ -5115,7 +5223,7 @@ This function returns 0 on error <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>-</em>]</span> +<span class="apii">[-0, +(0|1), –]</span> <pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> <p> @@ -5156,7 +5264,7 @@ the number of active local variables. <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> <p> @@ -5179,7 +5287,7 @@ it returns 0. <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>-</em>]</span> +<span class="apii">[-0, +(0|1), –]</span> <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> <p> @@ -5241,7 +5349,7 @@ this execution occurs without any calls to hooks. <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> <p> @@ -5294,7 +5402,7 @@ A hook is disabled by setting <code>mask</code> to zero. <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> -<span class="apii">[-(0|1), +0, <em>-</em>]</span> +<span class="apii">[-(0|1), +0, –]</span> <pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> <p> @@ -5316,7 +5424,7 @@ the number of active local variables. <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> -<span class="apii">[-(0|1), +0, <em>-</em>]</span> +<span class="apii">[-(0|1), +0, –]</span> <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> <p> @@ -5337,7 +5445,7 @@ when the index is greater than the number of upvalues. <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> <p> @@ -5386,7 +5494,7 @@ common tasks. <p> -All functions from the auxiliary library +All functions and types from the auxiliary library are defined in header file <code>lauxlib.h</code> and have a prefix <code>luaL_</code>. @@ -5395,6 +5503,8 @@ have a prefix <code>luaL_</code>. All functions in the auxiliary library are built on top of the basic API, and so they provide nothing that cannot be done with that API. +Nevertheless, the use of the auxiliary library ensures +more consistency to your code. <p> @@ -5432,7 +5542,7 @@ in alphabetical order. <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> <p> -Adds the character <code>c</code> to the buffer <code>B</code> +Adds the byte <code>c</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). @@ -5474,7 +5584,7 @@ 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 should not contain embedded zeros. +The string cannot contain embedded zeros. @@ -5509,12 +5619,8 @@ which is the value to be added to the buffer. <p> Checks whether <code>cond</code> is true. -If not, raises an error with the following message, -where <code>func</code> is retrieved from the call stack: +If not, raises an error with a standard message. -<pre> - bad argument #<narg> to <func> (<extramsg>) -</pre> @@ -5524,12 +5630,9 @@ where <code>func</code> is retrieved from the call stack: <pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> <p> -Raises an error with the following message, -where <code>func</code> is retrieved from the call stack: +Raises an error with a standard message +that includes <code>extramsg</code> as a comment. -<pre> - bad argument #<narg> to <func> (<extramsg>) -</pre> <p> This function never returns, @@ -5553,17 +5656,17 @@ Its pattern of use is as follows: <ul> -<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> +<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> -<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> +<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> <li> -Then you add string pieces to the buffer calling any of +Then add string pieces to the buffer calling any of the <code>luaL_add*</code> functions. </li> <li> -You finish by calling <code>luaL_pushresult(&b)</code>. +Finish by calling <code>luaL_pushresult(&b)</code>. This call leaves the final string on the top of the stack. </li> @@ -5575,15 +5678,15 @@ you can use the buffer like this: <ul> -<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> +<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> -<li>Then you initialize it and preallocate a space of +<li>Then initialize it and preallocate a space of size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> -<li>Then you copy the string into that space.</li> +<li>Then copy the string into that space.</li> <li> -You finish by calling <code>luaL_pushresult(&b, sz)</code>, +Finish by calling <code>luaL_pushresult(&b, sz)</code>, where <code>sz</code> is the total size of the resulting string copied into that space. </li> @@ -5611,7 +5714,7 @@ plus the final string on its top. <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> <p> @@ -5647,7 +5750,7 @@ Calls a metamethod. <p> If the object at index <code>obj</code> has a metatable and this metatable has a field <code>e</code>, -this function calls this field and passes the object as its only argument. +this function calls this field passing the object as its only argument. In this case this function returns true and pushes onto the stack the value returned by the call. If there is no metatable or no metamethod, @@ -5755,7 +5858,7 @@ if the string cannot be found. <p> If <code>def</code> is not <code>NULL</code>, the function uses <code>def</code> as a default value when -there is no argument <code>narg</code> or if this argument is <b>nil</b>. +there is no argument <code>narg</code> or when this argument is <b>nil</b>. <p> @@ -5836,7 +5939,7 @@ and returns this number cast to a <a href="#lua_Unsigned"><code>lua_Unsigned</co <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void luaL_checkversion (lua_State *L);</pre> <p> @@ -5870,7 +5973,7 @@ or true in case of errors. <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> -<span class="apii">[-0, +?, <em>-</em>]</span> +<span class="apii">[-0, +?, –]</span> <pre>int luaL_dostring (lua_State *L, const char *str);</pre> <p> @@ -5952,7 +6055,7 @@ returns false and pushes nothing. <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> <p> @@ -6012,13 +6115,28 @@ Raises an error if the result of the operation is not a number. <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name);</pre> <p> +Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. + + + + + +<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> +<span class="apii">[-0, +1, –]</span> +<pre>int luaL_loadbufferx (lua_State *L, + const char *buff, + size_t sz, + const char *name, + const char *mode);</pre> + +<p> Loads a buffer as a Lua chunk. This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the buffer pointed to by <code>buff</code> with size <code>sz</code>. @@ -6028,6 +6146,7 @@ buffer pointed to by <code>buff</code> with size <code>sz</code>. This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. <code>name</code> is the chunk name, used for debug information and error messages. +The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. @@ -6038,6 +6157,18 @@ used for debug information and error messages. <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> <p> +Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. + + + + + +<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> +<span class="apii">[-0, +1, <em>m</em>]</span> +<pre>int luaL_loadfilex (lua_State *L, const char *filename, + const char *mode);</pre> + +<p> Loads a file as a Lua chunk. This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file named <code>filename</code>. @@ -6047,9 +6178,13 @@ The first line in the file is ignored if it starts with a <code>#</code>. <p> +The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. + + +<p> This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> -if it cannot open/read the file. +if it cannot open/read the file or the file has a wrong mode. <p> @@ -6061,7 +6196,7 @@ it does not run it. <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>-</em>]</span> +<span class="apii">[-0, +1, –]</span> <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> <p> @@ -6141,7 +6276,7 @@ with <code>tname</code> in the registry. <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>lua_State *luaL_newstate (void);</pre> <p> @@ -6434,7 +6569,7 @@ These values are popped from the stack after the registration. <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> <p> @@ -6499,7 +6634,7 @@ to start the traceback. <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>const char *luaL_typename (lua_State *L, int index);</pre> <p> @@ -6510,7 +6645,7 @@ Returns the name of the type of the value at the given index. <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> -<span class="apii">[-0, +0, <em>-</em>]</span> +<span class="apii">[-0, +0, –]</span> <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> <p> @@ -6575,28 +6710,28 @@ Currently, Lua has the following standard libraries: <ul> -<li>basic library;</li> +<li>basic library (<a href="#6.1">§6.1</a>);</li> -<li>package library;</li> +<li>coroutine library (<a href="#6.2">§6.2</a>);</li> -<li>coroutine library;</li> +<li>package library (<a href="#6.3">§6.3</a>);</li> -<li>string manipulation;</li> +<li>string manipulation (<a href="#6.4">§6.4</a>);</li> -<li>table manipulation;</li> +<li>table manipulation (<a href="#6.5">§6.5</a>);</li> -<li>mathematical functions (sin, log, etc.);</li> +<li>mathematical functions (<a href="#6.6">§6.6</a>) (sin, log, etc.);</li> -<li>bitwise operations;</li> +<li>bitwise operations (<a href="#6.7">§6.7</a>);</li> -<li>input and output;</li> +<li>input and output (<a href="#6.8">§6.8</a>);</li> -<li>operating system facilities;</li> +<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> -<li>debug facilities.</li> +<li>debug facilities (<a href="#6.10">§6.10</a>).</li> </ul><p> -Except for the basic and package libraries, +Except for the basic and the package libraries, each library provides all its functions as fields of a global table or as methods of its objects. @@ -6606,7 +6741,8 @@ To have access to these libraries, the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, which opens all standard libraries. Alternatively, -it can open them individually by calling +the host program can open them individually by using +<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), @@ -6617,17 +6753,14 @@ it can open them individually by calling <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). -These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a> -and should not be called directly: -you must call them like any other Lua C function, -e.g., by using <a href="#lua_call"><code>lua_call</code></a>. +These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. <h2>6.1 – <a name="6.1">Basic Functions</a></h2> <p> -The basic library provides some core functions to Lua. +The basic library provides core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities. @@ -6660,13 +6793,13 @@ This is the default option. </li> <li><b>"<code>stop</code>": </b> -stops automatic invocation of the garbage collector. -The collector will run only when explcitly invoked, +stops automatic execution of the garbage collector. +The collector will run only when explicitly invoked, until a call to restart it. </li> <li><b>"<code>restart</code>": </b> -restarts automatic invocation the garbage collector. +restarts automatic execution of the garbage collector. </li> <li><b>"<code>count</code>": </b> @@ -6709,6 +6842,16 @@ returns a boolean that tells whether the collector is running (i.e., not stopped). </li> +<li><b>"<code>generational</code>": </b> +changes the collector to generational mode. +This is an experimental feature (see <a href="#2.5">§2.5</a>). +</li> + +<li><b>"<code>incremental</code>": </b> +changes the collector to incremental mode. +This is the default mode. +</li> + </ul> @@ -6789,7 +6932,7 @@ so that the construction <pre> for i,v in ipairs(t) do <em>body</em> end </pre><p> -will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···, +will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., up to the first integer key absent from the table. @@ -6813,7 +6956,7 @@ A return of an empty string, <b>nil</b>, or no value signals the end of the chun <p> -If there are no errors, +If there are no syntactic errors, returns the compiled chunk as a function; otherwise, returns <b>nil</b> plus the error message. @@ -6823,8 +6966,8 @@ If the resulting function has upvalues, the first upvalue is set to the value of the global environment or to <code>env</code>, if that parameter is given. -(When loading main chunks, -the first upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).) +When loading main chunks, +the first upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). <p> @@ -6832,21 +6975,22 @@ the first upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&se and debug information (see <a href="#4.9">§4.9</a>). When absent, it defaults to <code>ld</code>, if <code>ld</code> is a string, -or to "<code>=(load)</code>". +or to "<code>=(load)</code>" otherwise. <p> The string <code>mode</code> controls whether the chunk can be text or binary (that is, a precompiled chunk). -A letter '<code>t</code>' in <code>mode</code> allows a text chunk; -a letter '<code>b</code>' allows a binary chunk. +It may be the string "<code>b</code>" (only binary chunks), +"<code>t</code>" (only text chunks), +or "<code>bt</code>" (both binary and text). The default is "<code>bt</code>". <p> -<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> +<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> <p> @@ -6945,13 +7089,14 @@ In case of any error, <code>pcall</code> returns <b>false</b> plus the error mes <p> <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> -Receives any number of arguments, +Receives any number of arguments and prints their values to <code>stdout</code>, -using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. +using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. <code>print</code> is not intended for formatted output, but only as a quick way to show a value, -typically for debugging. -For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. +for instance for debugging. +For complete control over the output, +use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. @@ -6990,7 +7135,7 @@ Returns an integer number. Sets the real value of <code>table[index]</code> to <code>value</code>, without invoking any metamethod. <code>table</code> must be a table, -<code>index</code> any value different from <b>nil</b>, +<code>index</code> any value different from <b>nil</b> and NaN, and <code>value</code> any Lua value. @@ -7035,37 +7180,43 @@ This function returns <code>table</code>. <p> <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> -Tries to convert its argument to a number. -If the argument is already a number or a string convertible -to a number, then <code>tonumber</code> returns this number; + + +<p> +When called with no <code>base</code>, +<code>tonumber</code> tries to convert its argument to a number. +If the argument is already a number or +a string convertible to a number (see <a href="#3.4.2">§3.4.2</a>), +then <code>tonumber</code> returns this number; otherwise, it returns <b>nil</b>. <p> -An optional argument specifies the base to interpret the numeral. +When called with <code>base</code>, +then <code>e</code> should be a string to be interpreted as +an integer numeral in that base. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter '<code>A</code>' (in either upper or lower case) represents 10, '<code>B</code>' represents 11, and so forth, with '<code>Z</code>' representing 35. -In base 10 (the default), -the numeral is converted following the coercion rules (see <a href="#3.4.2">§3.4.2</a>). -In other bases, only integers are accepted. +If the string <code>e</code> is not a valid numeral in the given base, +the function returns <b>nil</b>. <p> -<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3> -Receives an argument of any type and +<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. -For complete control of how numbers are converted, -use <a href="#pdf-string.format"><code>string.format</code></a>. +(For complete control of how numbers are converted, +use <a href="#pdf-string.format"><code>string.format</code></a>.) <p> -If the metatable of <code>e</code> has a <code>"__tostring"</code> field, +If the metatable of <code>v</code> has a <code>"__tostring"</code> field, then <code>tostring</code> calls the corresponding value -with <code>e</code> as argument, +with <code>v</code> as argument, and uses the result of the call as its result. @@ -7139,11 +7290,11 @@ an object with type <code>"thread"</code>. Starts or continues the execution of coroutine <code>co</code>. The first time you resume a coroutine, it starts running its body. -The values <code>val1</code>, ··· are passed +The values <code>val1</code>, ... are passed as the arguments to the body function. If the coroutine has yielded, <code>resume</code> restarts it; -the values <code>val1</code>, ··· are passed +the values <code>val1</code>, ... are passed as the results from the yield. @@ -7280,7 +7431,7 @@ final value of <code>package.loaded[modname]</code>. <p> If there is any error loading or running the module, or if it cannot find any loader for the module, -then <code>require</code> signals an error. +then <code>require</code> raises an error. @@ -7309,8 +7460,8 @@ Default is '<code>?</code>'.</li> is replaced by the executable's directory. Default is '<code>!</code>'.</li> -<li>The fifth line is a mark to ignore all before it when building the -<code>luaopen_</code> function name. +<li>The fifth line is a mark to ignore all text before it +when building the <code>luaopen_</code> function name. Default is '<code>-</code>'.</li> </ul> @@ -7372,7 +7523,7 @@ available to other dynamically linked libraries. Otherwise, it looks for a function <code>funcname</code> inside the library and returns this function as a C function. -(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). +(So, <code>funcname</code> must follow the prototype <a href="#lua_CFunction"><code>lua_CFunction</code></a>). <p> @@ -7409,7 +7560,7 @@ At start-up, Lua initializes this variable with the value of the environment variable <a name="pdf-LUA_PATH_5_2"><code>LUA_PATH_5_2</code></a> or the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or with a default path defined in <code>luaconf.h</code>, -if the environment variable is not defined. +if those environment variables are not defined. Any "<code>;;</code>" in the value of the environment variable is replaced by the default path. @@ -7511,7 +7662,7 @@ with each submodule keeping its original open function. <p> -All searchers except the first (preload) return as the extra value +All searchers except the first one (preload) return as the extra value the file name where the module was found, as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. The first searcher returns no extra value. @@ -7520,7 +7671,7 @@ The first searcher returns no extra value. <p> -<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep])</code></a></h3> +<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> <p> @@ -7528,17 +7679,16 @@ Searches for the given <code>name</code> in the given <code>path</code>. <p> -A path is string containing a sequence of +A path is a string containing a sequence of <em>templates</em> separated by semicolons. For each template, -the function changes each interrogation -mark in the template by a copy of <code>name</code> +the function replaces each interrogation mark (if any) +in the template with a copy of <code>name</code> wherein all occurrences of <code>sep</code> (a dot, by default) -were replaced by the system's directory separator, +were replaced by <code>rep</code> +(the system's directory separator, by default), and then tries to open the resulting file name. -If <code>sep</code> is the empty string, -the replacement is not done. <p> @@ -7583,7 +7733,7 @@ The string library provides all its functions inside the table It also sets a metatable for strings where the <code>__index</code> field points to the <code>string</code> table. Therefore, you can use the string functions in object-oriented style. -For instance, <code>string.byte(s, i)</code> +For instance, <code>string.byte(s,i)</code> can be written as <code>s:byte(i)</code>. @@ -7594,13 +7744,15 @@ The string library assumes one-byte character encodings. <p> <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> Returns the internal numerical codes of the characters <code>s[i]</code>, -<code>s[i+1]</code>, ···, <code>s[j]</code>. +<code>s[i+1]</code>, ..., <code>s[j]</code>. The default value for <code>i</code> is 1; the default value for <code>j</code> is <code>i</code>. +These indices are corrected +following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. <p> -Note that numerical codes are not necessarily portable across platforms. +Numerical codes are not necessarily portable across platforms. @@ -7614,7 +7766,7 @@ to its corresponding argument. <p> -Note that numerical codes are not necessarily portable across platforms. +Numerical codes are not necessarily portable across platforms. @@ -7694,9 +7846,11 @@ 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> -expect an integer as argument; -the range of that integer may be limited by +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. 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, @@ -7709,7 +7863,7 @@ it is converted to one following the same rules of <a href="#pdf-tostring"><code <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> Returns an iterator function that, each time it is called, -returns the next captures from <code>pattern</code> over string <code>s</code>. +returns the next captures from <code>pattern</code> over the string <code>s</code>. If <code>pattern</code> specifies no captures, then the whole match is produced in each call. @@ -7737,7 +7891,7 @@ given string into a table: </pre> <p> -For this function, a '<code>^</code>' at the start of a pattern does not +For this function, a caret '<code>^</code>' at the start of a pattern does not work as an anchor, as this would prevent the iteration. @@ -7884,6 +8038,17 @@ and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> with length <code>i</code>. +<p> +If, after the translation of negative indices, +<code>i</code> is less than 1, +it is corrected to 1. +If <code>j</code> is greater than the string length, +it is corrected to that length. +If, after these corrections, +<code>i</code> is greater than <code>j</code>, +the function returns the empty string. + + <p> @@ -8050,7 +8215,7 @@ they were the character '<code>\0</code>'. <h4>Pattern:</h4><p> A <em>pattern</em> is a sequence of pattern items. -A '<code>^</code>' at the beginning of a pattern anchors the match at the +A caret '<code>^</code>' at the beginning of a pattern anchors the match at the beginning of the subject string. A '<code>$</code>' at the end of a pattern anchors the match at the end of the subject string. @@ -8147,7 +8312,6 @@ of list <code>t</code>. <p> Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "<code>n</code>" with the total number of parameters. -Also returns, as a second result, the total number of parameters. Note that the resulting table may not be a sequence. @@ -8589,7 +8753,7 @@ result in zero or <code>0xFFFFFFFF</code> (all original bits are shifted out). <p> -Returns the bitwise and of its operands. +Returns the bitwise <em>and</em> of its operands. @@ -8614,7 +8778,7 @@ the following identity holds: <p> -Returns the bitwise or of its operands. +Returns the bitwise <em>or</em> of its operands. @@ -8625,7 +8789,7 @@ Returns the bitwise or of its operands. <p> Returns a boolean signaling -whether the bitwise and of its operands is different from zero. +whether the bitwise <em>and</em> of its operands is different from zero. @@ -8635,7 +8799,7 @@ whether the bitwise and of its operands is different from zero. <p> -Returns the bitwise exclusive or of its operands. +Returns the bitwise <em>exclusive or</em> of its operands. @@ -8845,7 +9009,7 @@ instead of returning an error code. <p> -<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename] ···)</code></a></h3> +<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3> <p> @@ -8863,6 +9027,11 @@ 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. +<p> +In case of errors this function raises the error, +instead of returning an error code. + + <p> @@ -9007,15 +9176,20 @@ each time it is called, reads the file according to the given formats. When no format is given, uses "*l" as a default. -Therefore, the construction +As an example, the construction <pre> for c in file:lines(1) do <em>body</em> end </pre><p> will iterate over all characters of the file, starting at the current position. -(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file -when the loop ends.) +Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file +when the loop ends. + + +<p> +In case of errors this function raises the error, +instead of returning an error code. @@ -9062,7 +9236,7 @@ returning <b>nil</b> on end of file. </li> <li><b><em>number</em>: </b> -reads a string with up to this number of characters, +reads a string with up to this number of bytes, returning <b>nil</b> on end of file. If number is zero, it reads nothing and returns an empty string, @@ -9074,7 +9248,7 @@ or <b>nil</b> on end of file. <p> -<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3> +<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> <p> @@ -9088,9 +9262,9 @@ specified by the string <code>whence</code>, as follows: <li><b>"<code>cur</code>": </b> base is current position;</li> <li><b>"<code>end</code>": </b> base is end of file;</li> </ul><p> -In case of success, function <code>seek</code> returns the final file position, +In case of success, <code>seek</code> returns the final file position, measured in bytes from the beginning of the file. -If this function fails, it returns <b>nil</b>, +If <code>seek</code> fails, it returns <b>nil</b>, plus a string describing the error. @@ -9123,8 +9297,8 @@ no buffering; the result of any output operation appears immediately. <li><b>"<code>full</code>": </b> full buffering; output operation is performed only -when the buffer is full (or when you explicitly <code>flush</code> the file -(see <a href="#pdf-io.flush"><code>io.flush</code></a>)). +when the buffer is full or when +you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). </li> <li><b>"<code>line</code>": </b> @@ -9146,11 +9320,8 @@ The default is an appropriate size. <p> -Writes the value of each of its arguments to -the <code>file</code>. +Writes the value of each of its arguments to <code>file</code>. The arguments must be strings or numbers. -To write other values, -use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. <p> @@ -9202,8 +9373,8 @@ then the date is formatted in Coordinated Universal Time. After this optional character, if <code>format</code> is the string "<code>*t</code>", then <code>date</code> returns a table with the following fields: -<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), -<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), +<code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31), +<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), <code>wday</code> (weekday, Sunday is 1), <code>yday</code> (day of the year), and <code>isdst</code> (daylight saving flag, a boolean). @@ -9224,6 +9395,11 @@ the host system and on the current locale (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). +<p> +On some systems, +this function may be not thread safe. + + <p> @@ -9314,7 +9490,7 @@ or <b>nil</b> if the variable is not defined. Deletes the file (or empty directory, on POSIX systems) with the given name. If this function fails, it returns <b>nil</b>, -plus a string describing the error. +plus a string describing the error and the error code. @@ -9326,7 +9502,7 @@ plus a string describing the error. <p> Renames file or directory named <code>oldname</code> to <code>newname</code>. If this function fails, it returns <b>nil</b>, -plus a string describing the error. +plus a string describing the error and the error code. @@ -9337,7 +9513,7 @@ plus a string describing the error. <p> Sets the current locale of the program. -<code>locale</code> is a string specifying a locale; +<code>locale</code> is a system-dependent string specifying a locale; <code>category</code> is an optional string describing which category to change: <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; @@ -9369,8 +9545,12 @@ for the given category. Returns the current time when called without arguments, or a time representing the date and time specified by the given table. This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, -and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> -(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function). +and may have fields +<code>hour</code> (default is 12), +<code>min</code> (default is 0), +<code>sec</code> (default is 0), +and <code>isdst</code> (default is <b>nil</b>). +For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. <p> @@ -9380,7 +9560,7 @@ this number counts the number of seconds since some given start time (the "epoch"). In other systems, the meaning is not specified, and the number returned by <code>time</code> can be used only as an argument to -<code>date</code> and <code>difftime</code>. +<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. @@ -9421,9 +9601,9 @@ which automatically removes the file when the program ends. <p> This library provides -the functionality of the debug interface to Lua programs. +the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. You should exert care when using this library. -Several of these functions +Several of its functions violate basic assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside; @@ -9458,7 +9638,7 @@ so that the caller continues its execution. <p> Note that commands for <code>debug.debug</code> are not lexically nested -within any function, and so have no direct access to local variables. +within any function and so have no direct access to local variables. @@ -9477,20 +9657,20 @@ and the current hook count <p> -<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3> +<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> <p> Returns a table with information about a function. -You can give the function directly, -or you can give a number as the value of <code>function</code>, -which means the function running at level <code>function</code> of the call stack +You can give the function directly +or you can give a number as the value of <code>f</code>, +which means the function running at level <code>f</code> of the call stack of the given thread: level 0 is the current function (<code>getinfo</code> itself); level 1 is the function that called <code>getinfo</code> (except for tail calls, which do not count on the stack); and so on. -If <code>function</code> is a number larger than the number of active functions, +If <code>f</code> is a number larger than the number of active functions, then <code>getinfo</code> returns <b>nil</b>. @@ -9554,11 +9734,11 @@ In that case, <code>getlocal</code> returns only the name of function parameters <p> -<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3> +<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> <p> -Returns the metatable of the given <code>object</code> +Returns the metatable of the given <code>value</code> or <b>nil</b> if it does not have a metatable. @@ -9575,12 +9755,12 @@ Returns the registry table (see <a href="#4.5">§4.5</a>). <p> -<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3> +<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> <p> This function returns the name and the value of the upvalue -with index <code>up</code> of the function <code>func</code>. +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. @@ -9662,24 +9842,24 @@ variable indices and names. <p> -<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3> +<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> <p> -Sets the metatable for the given <code>object</code> to the given <code>table</code> +Sets the metatable for the given <code>value</code> to the given <code>table</code> (which can be <b>nil</b>). -Returns <code>object</code>. +Returns <code>value</code>. <p> -<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3> +<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> <p> This function assigns the value <code>value</code> to the upvalue -with index <code>up</code> of the function <code>func</code>. +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. Otherwise, it returns the name of the upvalue. @@ -9723,7 +9903,7 @@ to start the traceback <p> -<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (function, n)</code></a></h3> +<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> <p> @@ -9743,12 +9923,12 @@ will return identical ids for those upvalue indices. <p> -<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (func1, n1, func2, n2)</code></a></h3> +<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> <p> -Make the <code>n1</code>-th upvalue of the Lua closure <code>func1</code> -refer to the <code>n2</code>-th upvalue of the Lua closure <code>func2</code>. +Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> +refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. @@ -9779,6 +9959,7 @@ The options are: <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> <li><b><code>-v</code>: </b> prints version information;</li> +<li><b><code>-E</code>: </b> ignores environment variables;</li> <li><b><code>--</code>: </b> stops handling options;</li> <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> </ul><p> @@ -9791,24 +9972,35 @@ and as <code>lua -</code> otherwise. <p> -Before running any argument, +When called without option <code>-E</code>, the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_2"><code>LUA_INIT_5_2</code></a> -(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined). -If its format is <code>@<em>filename</em></code>, +(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined) +before running any argument. +If the variable content has the format <code>@<em>filename</em></code>, then <code>lua</code> executes the file. Otherwise, <code>lua</code> executes the string itself. <p> -All options are handled in order, except <code>-i</code>. +When called with option <code>-E</code>, +besides ignoring <code>LUA_INIT</code>, +Lua also ignores +the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, +setting the values of +<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> +with the default paths defined in <code>luaconf.h</code>. + + +<p> +All options are handled in order, except <code>-i</code> and <code>-E</code>. For instance, an invocation like <pre> $ lua -e'a=1' -e 'print(a)' script.lua </pre><p> -will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'), +will first set <code>a</code> to 1, then print the value of <code>a</code>, and finally run the file <code>script.lua</code> with no arguments. -(Here <code>$</code> is the shell prompt. Your prompt can be different.) +(Here <code>$</code> is the shell prompt. Your prompt may be different.) <p> @@ -9835,7 +10027,7 @@ then creates a table [1] = "t1", [2] = "t2" } </pre><p> and finally runs the file <code>b.lua</code>. -The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ··· +The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... as arguments; it can also access these arguments with the vararg expression '<code>...</code>'. @@ -9862,29 +10054,8 @@ the interpreter does not report the error. When finishing normally, the interpreter closes its main Lua state (see <a href="#lua_close"><code>lua_close</code></a>). -The script can avoid this step by terminating -through <a href="#pdf-os.exit"><code>os.exit</code></a>. - - -<p> -If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, -then its value is used as the prompt. -Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, -its value is used as the secondary prompt -(issued during incomplete statements). -Therefore, both prompts can be changed directly on the command line -or in any Lua programs by assigning to <code>_PROMPT</code>. -See the next example: - -<pre> - $ lua -e"_PROMPT='myprompt> '" -i -</pre><p> -(The outer pair of quotes is for the shell, -the inner pair is for Lua.) -Note the use of <code>-i</code> to enter interactive mode; -otherwise, -the program would just end silently -right after the assignment to <code>_PROMPT</code>. +The script can avoid this step by +calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. <p> @@ -9900,7 +10071,7 @@ as in #!/usr/local/bin/lua </pre><p> (Of course, -the location of the Lua interpreter can be different in your machine. +the location of the Lua interpreter may be different in your machine. If <code>lua</code> is in your <code>PATH</code>, then @@ -9914,9 +10085,9 @@ is a more portable solution.) <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> <p> -Here we list the incompatibilities that you can find when moving a program +Here we list the incompatibilities that you may find when moving a program from Lua 5.1 to Lua 5.2. -You can avoid some incompatibilities compiling Lua with +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. @@ -9934,7 +10105,7 @@ use the variable <code>_ENV</code> or the function <a href="#pdf-load"><code>loa <p> -C functions do not have environments any more. +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 @@ -9964,8 +10135,8 @@ Weak tables with weak keys now perform like <em>ephemeron tables</em>. <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 there will -not be a corresponding return event. +<em>tail call</em>, so that the debugger can know that +there will not be a corresponding return event. </li> <li> @@ -9985,8 +10156,8 @@ observable difference to the new function. <li> Function <code>module</code> is deprecated. -Modules are not expected to set global variables anymore, -and it is easy to set up a module with regular Lua code. +It is easy to set up a module with regular Lua code. +Modules are not expected to set global variables. </li> <li> @@ -10036,10 +10207,15 @@ 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 bugs in the verification algorithm.) +of flaws in the verification algorithm.) When in doubt, -use the <code>mode</code> argument in function <a href="#pdf-load"><code>load</code></a> -to restrict it to loading textual chunks. +use the <code>mode</code> argument of those functions +to restrict them to loading textual chunks. +</li> + +<li> +The standard paths in the official distribution may +change between versions. </li> </ul> @@ -10060,13 +10236,12 @@ You must get the global environment from the registry Pseudoindex <code>LUA_ENVIRONINDEX</code> and functions <code>lua_getfenv</code>/<code>lua_setfenv</code> were removed, -as C functions do not have environments any more. +as C functions no longer have environments. </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 anymore. +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> @@ -10081,7 +10256,7 @@ the block is new. <li> Finalizers (<code>__gc</code> metamethods) for userdata are called in the -reverse order that they were marked, +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, @@ -10110,6 +10285,16 @@ Use the new <a href="#lua_compare"><code>lua_compare</code></a> with appropriate 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> + +<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. +</li> + </ul> @@ -10160,7 +10345,7 @@ Here is the complete syntax of Lua in extended BNF. explist ::= exp {‘<b>,</b>’ exp} - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | ‘<b>...</b>’ | function | + exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | ‘<b>...</b>’ | functiondef | prefixexp | tableconstructor | exp binop exp | unop exp prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ @@ -10202,10 +10387,10 @@ Here is the complete syntax of Lua in extended BNF. <HR> <SMALL CLASS="footer"> Last update: -Fri Jul 8 17:11:02 BRT 2011 +Mon Dec 12 15:21:08 BRST 2011 </SMALL> <!-- -Last change: revised for Lua 5.2.0 (beta) +Last change: revised for Lua 5.2.0 --> </body></html> diff --git a/doc/osi-certified-72x60.png b/doc/osi-certified-72x60.png Binary files differindex 07df5f6..07df5f6 100755..100644 --- a/doc/osi-certified-72x60.png +++ b/doc/osi-certified-72x60.png diff --git a/doc/readme.html b/doc/readme.html index 5cb41d4..f0c77a1 100755..100644 --- a/doc/readme.html +++ b/doc/readme.html @@ -6,18 +6,21 @@ <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> <STYLE TYPE="text/css"> blockquote, .display { - color: black ; - padding: 8px ; border: solid #a0a0a0 2px ; - xbackground-color: #EFEFFF ; - margin-left: 0px ; + padding: 1em ; + margin: 0px ; +} + +.display { + word-spacing: 0.25em ; +} + +dl.display dd { + padding-bottom: 0.2em ; } tt, kbd, code { - font-size: 120% ; - xcolor: black ; - xpadding: 4px ; - xbackground-color: #E0E0E0 ; + font-size: 12pt ; } </STYLE> </HEAD> @@ -27,15 +30,10 @@ tt, kbd, code { <HR> <H1> <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua" BORDER=0></A> -Welcome to Lua 5.2 (beta) +Welcome to Lua 5.2 </H1> <P> -<IMG SRC="alert.png" ALIGN="absbottom" ALT="[!]"> -<EM>This is a beta version of Lua 5.2. -Some details may change in the final version.</EM> - -<P> <A HREF="#about">about</A> · <A HREF="#install">installation</A> @@ -86,7 +84,7 @@ form. You need to build it before using it. Building Lua should be straightforward because -Lua is implemented in pure ANSI C, and compiles unmodified in all known +Lua is implemented in pure ANSI C and compiles unmodified in all known platforms that have an ANSI C compiler. Lua also compiles unmodified as C++. The instructions given below for building Lua are for Unix-like platforms. @@ -120,15 +118,16 @@ Here are the details. <OL> <LI> Open a terminal window and move to -the top-level directory, which is named lua-5.2.0. +the top-level directory, which is named <TT>lua-5.2.0</TT>. The Makefile there controls both the build process and the installation process. <P> <LI> Do "<KBD>make</KBD>" and see if your platform is listed. The platforms currently supported are: -<BLOCKQUOTE> - aix ansi bsd freebsd generic linux macosx mingw posix solaris -</BLOCKQUOTE> +<P> +<P CLASS="display"> + aix ansi bsd freebsd generic linux macosx mingw posix solaris +</P> <P> If your platform is listed, just do "<KBD>make xxx</KBD>", where xxx is your platform name. @@ -138,7 +137,7 @@ The Makefile there controls both the build process and the installation process. <P> <LI> The compilation takes only a few moments -and produces three files in the src directory: +and produces three files in the <TT>src</TT> directory: lua (the interpreter), luac (the compiler), and liblua.a (the library). @@ -147,12 +146,15 @@ and liblua.a (the library). To check that Lua has been built correctly, do "<KBD>make test</KBD>" after building Lua. This will run the interpreter and print its version string. </OL> +<P> +If you're running Linux and get compilation errors, +make sure you have installed the <TT>readline</TT> development package. <H3>Installing Lua</H3> <P> Once you have built Lua, you may want to install it in an official place in your system. In this case, do "<KBD>make install</KBD>". The official - place and the way to install files are defined in Makefile. You'll + place and the way to install files are defined in the Makefile. You'll probably need the right permissions to install files. <P> @@ -198,9 +200,9 @@ and liblua.a (the library). <P> Three kinds of things can be customized by editing a file: <UL> - <LI> Where and how to install Lua — edit Makefile. - <LI> How to build Lua — edit src/Makefile. - <LI> Lua features — edit src/luaconf.h. + <LI> Where and how to install Lua — edit <TT>Makefile</TT>. + <LI> How to build Lua — edit <TT>src/Makefile</TT>. + <LI> Lua features — edit <TT>src/luaconf.h</TT>. </UL> <P> @@ -211,13 +213,13 @@ and liblua.a (the library). <P> On the other hand, if you need to customize some Lua features, you'll need - to edit src/luaconf.h before building and installing Lua. + to edit <TT>src/luaconf.h</TT> before building and installing Lua. The edited file will be the one installed, and it will be used by any Lua clients that you build, to ensure consistency. Further customization is available to experts by editing the Lua sources. <P> - We strongly recommend that you enable dynamic loading in src/luaconf.h. + We strongly recommend that you enable dynamic loading in <TT>src/luaconf.h</TT>. This is done automatically for all platforms listed above that have this feature and also for Windows. @@ -238,7 +240,6 @@ lmem.c lobject.c lopcodes.c lparser.c lstate.c lstring.c ltable.c ltm.c lundump.c lvm.c lzio.c lauxlib.c lbaselib.c lbitlib.c lcorolib.c ldblib.c liolib.c lmathlib.c loslib.c lstrlib.c ltablib.c loadlib.c linit.c - <DT> interpreter: <DD> @@ -257,11 +258,11 @@ compiler: those dynamic libraries — but <EM>don't</EM> link the Lua library into each dynamic library. For Unix, we recommend that the Lua library be linked statically into the host program and its symbols exported for - dynamic linking; src/Makefile does this for the Lua interpreter. + dynamic linking; <TT>src/Makefile</TT> does this for the Lua interpreter. For Windows, we recommend that the Lua library be a DLL. <P> - As mentioned above, you may edit src/luaconf.h to customize + As mentioned above, you may edit <TT>src/luaconf.h</TT> to customize some features before building Lua. <H2><A NAME="changes">Changes since Lua 5.1</A></H2> @@ -290,7 +291,7 @@ Here are the other changes introduced in Lua 5.2: <UL> <LI> no more fenv for threads or functions <LI> tables honor the <CODE>__len</CODE> metamethod -<LI> hex and <CODE>\*</CODE> escapes in strings +<LI> hex and <CODE>\z</CODE> escapes in strings <LI> support for hexadecimal floats <LI> order metamethods work for different types <LI> no more verification of opcode consistency @@ -302,8 +303,8 @@ Here are the other changes introduced in Lua 5.2: <H3>Libraries</H3> <UL> <LI> arguments for function called through <CODE>xpcall</CODE> -<LI> optional 'mode' argument to load (to control binary x text) -<LI> optional 'env' argument to load (environment for loaded chunk) +<LI> optional 'mode' argument to load and loadfile (to control binary x text) +<LI> optional 'env' argument to load and loadfile (environment for loaded chunk) <LI> <CODE>loadlib</CODE> may load libraries with global names (RTLD_GLOBAL) <LI> new function <CODE>package.searchpath</CODE> <LI> modules receive their paths when loaded @@ -324,15 +325,23 @@ Here are the other changes introduced in Lua 5.2: <H3>C API</H3> <UL> <LI> main thread predefined in the registry -<LI> new constants <CODE>LUA_OK</CODE> and <CODE>LUA_ERRGCMM</CODE> -<LI> new <CODE>lua_compare</CODE>, <CODE>lua_arith</CODE>, and <CODE>lua_len</CODE> -<LI> new <CODE>lua_version</CODE> and <CODE>luaL_checkversion</CODE> +<LI> new functions +<CODE>lua_absindex</CODE>, +<CODE>lua_arith</CODE>, +<CODE>lua_compare</CODE>, +<CODE>lua_copy</CODE>, +<CODE>lua_len</CODE>, +<CODE>lua_rawgetp</CODE>, +<CODE>lua_rawsetp</CODE>, +<CODE>lua_upvalueid</CODE>, +<CODE>lua_upvaluejoin</CODE>, +<CODE>lua_version</CODE>. +<LI> new functions +<CODE>luaL_checkversion</CODE>, +<CODE>luaL_setmetatable</CODE>, +<CODE>luaL_testudata</CODE>, +<CODE>luaL_tolstring</CODE>. <LI> <CODE>lua_pushstring</CODE> and <CODE>pushlstring</CODE> return string -<LI> new <CODE>luaL_testudata</CODE> and <CODE>luaL_setmetatable</CODE> -<LI> new <CODE>luaL_tolstring</CODE> -<LI> new <CODE>lua_copy</CODE> -<LI> new <CODE>lua_absindex</CODE> -<LI> new <CODE>lua_upvalueid</CODE> and <CODE>lua_upvaluejoin</CODE> <LI> <CODE>nparams</CODE> and <CODE>isvararg</CODE> available in debug API <LI> new <CODE>lua_Unsigned</CODE> </UL> @@ -340,15 +349,17 @@ Here are the other changes introduced in Lua 5.2: <H3>Implementation</H3> <UL> <LI> max constants per function raised to 2<SUP>26</SUP> +<LI> generational mode for garbage collection (experimental) +<LI> NaN trick (experimental) <LI> internal (immutable) version of ctypes <LI> simpler implementation for string buffers -<LI> udata with finalizers are kept in a separated list for the GC -<LI> <CODE>CallInfo</CODE> stack now is a linked list <LI> parser uses much less C-stack space (no more auto arrays) -<LI> new hash for floats -<LI> handling of non-string error messages in the standalone interpreter -<LI> generational mode for garbage collection (experimental) -<LI> NaN trick (experimental) +</UL> + +<H3>Lua standalone interpreter</H3> +<UL> +<LI> new <CODE>-E</CODE> option to avoid environment variables +<LI> handling of non-string error messages </UL> <H2><A NAME="license">License</A></H2> @@ -369,7 +380,7 @@ then you should give us credit by including the appropriate copyright notice som For details, see <A HREF="http://www.lua.org/license.html">this</A>. -<BLOCKQUOTE> +<BLOCKQUOTE STYLE="padding-bottom: 0em"> Copyright © 1994–2011 Lua.org, PUC-Rio. <P> @@ -393,14 +404,15 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. </BLOCKQUOTE> +<P> <HR> <SMALL CLASS="footer"> Last update: -Fri Jun 24 11:30:57 BRT 2011 +Wed Nov 23 16:17:22 BRST 2011 </SMALL> <!-- -Last change: revised for Lua 5.2.0 (beta) +Last change: revised for Lua 5.2.0 --> </BODY> diff --git a/src/luaconf.h b/src/luaconf.h new file mode 100644 index 0000000..bab401e --- /dev/null +++ b/src/luaconf.h @@ -0,0 +1,529 @@ +/* +** $Id: luaconf.h,v 1.170 2011/12/06 16:58:36 roberto Exp $ +** Configuration file for Lua +** See Copyright Notice in lua.h +*/ + + +#ifndef lconfig_h +#define lconfig_h + +#include <limits.h> +#include <stddef.h> + + +/* +** ================================================================== +** Search for "@@" to find all configurable definitions. +** =================================================================== +*/ + + +/* +@@ LUA_ANSI controls the use of non-ansi features. +** CHANGE it (define it) if you want Lua to avoid the use of any +** non-ansi feature or library. +*/ +#if !defined(LUA_ANSI) && defined(__STRICT_ANSI__) +#define LUA_ANSI +#endif + + +#if !defined(LUA_ANSI) && defined(_WIN32) && !defined(_WIN32_WCE) +#define LUA_WIN /* enable goodies for regular Windows platforms */ +#endif + +#if defined(LUA_WIN) +#define LUA_DL_DLL +#define LUA_USE_AFORMAT /* assume 'printf' handles 'aA' specifiers */ +#endif + + + +#if defined(LUA_USE_LINUX) +#define LUA_USE_POSIX +#define LUA_USE_DLOPEN /* needs an extra library: -ldl */ +#define LUA_USE_READLINE /* needs some extra libraries */ +#define LUA_USE_STRTODHEX /* assume 'strtod' handles hexa formats */ +#define LUA_USE_AFORMAT /* assume 'printf' handles 'aA' specifiers */ +#define LUA_USE_LONGLONG /* assume support for long long */ +#endif + +#if defined(LUA_USE_MACOSX) +#define LUA_USE_POSIX +#define LUA_USE_DLOPEN /* does not need -ldl */ +#define LUA_USE_READLINE /* needs an extra library: -lreadline */ +#define LUA_USE_STRTODHEX /* assume 'strtod' handles hexa formats */ +#define LUA_USE_AFORMAT /* assume 'printf' handles 'aA' specifiers */ +#define LUA_USE_LONGLONG /* assume support for long long */ +#endif + + + +/* +@@ LUA_USE_POSIX includes all functionality listed as X/Open System +@* Interfaces Extension (XSI). +** CHANGE it (define it) if your system is XSI compatible. +*/ +#if defined(LUA_USE_POSIX) +#define LUA_USE_MKSTEMP +#define LUA_USE_ISATTY +#define LUA_USE_POPEN +#define LUA_USE_ULONGJMP +#define LUA_USE_GMTIME_R +#endif + + + +/* +@@ LUA_PATH_DEFAULT is the default path that Lua uses to look for +@* Lua libraries. +@@ LUA_CPATH_DEFAULT is the default path that Lua uses to look for +@* C libraries. +** CHANGE them if your machine has a non-conventional directory +** hierarchy or if you want to install your libraries in +** non-conventional directories. +*/ +#if defined(_WIN32) /* { */ +/* +** In Windows, any exclamation mark ('!') in the path is replaced by the +** path of the directory of the executable file of the current process. +*/ +#define LUA_LDIR "!\\lua\\" +#define LUA_CDIR "!\\" +#define LUA_PATH_DEFAULT \ + LUA_LDIR"?.lua;" LUA_LDIR"?\\init.lua;" \ + LUA_CDIR"?.lua;" LUA_CDIR"?\\init.lua;" ".\\?.lua" +#define LUA_CPATH_DEFAULT \ + LUA_CDIR"?.dll;" LUA_CDIR"loadall.dll;" ".\\?.dll" + +#else /* }{ */ + +#define LUA_VDIR LUA_VERSION_MAJOR "." LUA_VERSION_MINOR "/" +#define LUA_ROOT "/usr/local/" +#define LUA_LDIR LUA_ROOT "share/lua/" LUA_VDIR +#define LUA_CDIR LUA_ROOT "lib/lua/" LUA_VDIR +#define LUA_PATH_DEFAULT \ + LUA_LDIR"?.lua;" LUA_LDIR"?/init.lua;" \ + LUA_CDIR"?.lua;" LUA_CDIR"?/init.lua;" "./?.lua" +#define LUA_CPATH_DEFAULT \ + LUA_CDIR"?.so;" LUA_CDIR"loadall.so;" "./?.so" +#endif /* } */ + + +/* +@@ LUA_DIRSEP is the directory separator (for submodules). +** CHANGE it if your machine does not use "/" as the directory separator +** and is not Windows. (On Windows Lua automatically uses "\".) +*/ +#if defined(_WIN32) +#define LUA_DIRSEP "\\" +#else +#define LUA_DIRSEP "/" +#endif + + +/* +@@ LUA_ENV is the name of the variable that holds the current +@@ environment, used to access global names. +** CHANGE it if you do not like this name. +*/ +#define LUA_ENV "_ENV" + + +/* +@@ LUA_API is a mark for all core API functions. +@@ LUALIB_API is a mark for all auxiliary library functions. +@@ LUAMOD_API is a mark for all standard library opening functions. +** CHANGE them if you need to define those functions in some special way. +** For instance, if you want to create one Windows DLL with the core and +** the libraries, you may want to use the following definition (define +** LUA_BUILD_AS_DLL to get it). +*/ +#if defined(LUA_BUILD_AS_DLL) /* { */ + +#if defined(LUA_CORE) || defined(LUA_LIB) /* { */ +#define LUA_API __declspec(dllexport) +#else /* }{ */ +#define LUA_API __declspec(dllimport) +#endif /* } */ + +#else /* }{ */ + +#define LUA_API extern + +#endif /* } */ + + +/* more often than not the libs go together with the core */ +#define LUALIB_API LUA_API +#define LUAMOD_API LUALIB_API + + +/* +@@ LUAI_FUNC is a mark for all extern functions that are not to be +@* exported to outside modules. +@@ LUAI_DDEF and LUAI_DDEC are marks for all extern (const) variables +@* that are not to be exported to outside modules (LUAI_DDEF for +@* definitions and LUAI_DDEC for declarations). +** CHANGE them if you need to mark them in some special way. Elf/gcc +** (versions 3.2 and later) mark them as "hidden" to optimize access +** when Lua is compiled as a shared library. Not all elf targets support +** this attribute. Unfortunately, gcc does not offer a way to check +** whether the target offers that support, and those without support +** give a warning about it. To avoid these warnings, change to the +** default definition. +*/ +#if defined(__GNUC__) && ((__GNUC__*100 + __GNUC_MINOR__) >= 302) && \ + defined(__ELF__) /* { */ +#define LUAI_FUNC __attribute__((visibility("hidden"))) extern +#define LUAI_DDEC LUAI_FUNC +#define LUAI_DDEF /* empty */ + +#else /* }{ */ +#define LUAI_FUNC extern +#define LUAI_DDEC extern +#define LUAI_DDEF /* empty */ +#endif /* } */ + + + +/* +@@ LUA_QL describes how error messages quote program elements. +** CHANGE it if you want a different appearance. +*/ +#define LUA_QL(x) "'" x "'" +#define LUA_QS LUA_QL("%s") + + +/* +@@ LUA_IDSIZE gives the maximum size for the description of the source +@* of a function in debug information. +** CHANGE it if you want a different size. +*/ +#define LUA_IDSIZE 60 + + +/* +@@ luai_writestring/luai_writeline define how 'print' prints its results. +** They are only used in libraries and the stand-alone program. (The #if +** avoids including 'stdio.h' everywhere.) +*/ +#if defined(LUA_LIB) || defined(lua_c) +#include <stdio.h> +#define luai_writestring(s,l) fwrite((s), sizeof(char), (l), stdout) +#define luai_writeline() (luai_writestring("\n", 1), fflush(stdout)) +#endif + +/* +@@ luai_writestringerror defines how to print error messages. +** (A format string with one argument is enough for Lua...) +*/ +#define luai_writestringerror(s,p) \ + (fprintf(stderr, (s), (p)), fflush(stderr)) + + + + + +/* +** {================================================================== +** Compatibility with previous versions +** =================================================================== +*/ + +/* +@@ LUA_COMPAT_ALL controls all compatibility options. +** You can define it to get all options, or change specific options +** to fit your specific needs. +*/ +#if defined(LUA_COMPAT_ALL) /* { */ + +/* +@@ LUA_COMPAT_UNPACK controls the presence of global 'unpack'. +** You can replace it with 'table.unpack'. +*/ +#define LUA_COMPAT_UNPACK + +/* +@@ LUA_COMPAT_LOADERS controls the presence of table 'package.loaders'. +** You can replace it with 'package.searchers'. +*/ +#define LUA_COMPAT_LOADERS + +/* +@@ macro 'lua_cpcall' emulates deprecated function lua_cpcall. +** You can call your C function directly (with light C functions). +*/ +#define lua_cpcall(L,f,u) \ + (lua_pushcfunction(L, (f)), \ + lua_pushlightuserdata(L,(u)), \ + lua_pcall(L,1,0,0)) + + +/* +@@ LUA_COMPAT_LOG10 defines the function 'log10' in the math library. +** You can rewrite 'log10(x)' as 'log(x, 10)'. +*/ +#define LUA_COMPAT_LOG10 + +/* +@@ LUA_COMPAT_LOADSTRING defines the function 'loadstring' in the base +** library. You can rewrite 'loadstring(s)' as 'load(s)'. +*/ +#define LUA_COMPAT_LOADSTRING + +/* +@@ LUA_COMPAT_MAXN defines the function 'maxn' in the table library. +*/ +#define LUA_COMPAT_MAXN + +/* +@@ The following macros supply trivial compatibility for some +** changes in the API. The macros themselves document how to +** change your code to avoid using them. +*/ +#define lua_strlen(L,i) lua_rawlen(L, (i)) + +#define lua_objlen(L,i) lua_rawlen(L, (i)) + +#define lua_equal(L,idx1,idx2) lua_compare(L,(idx1),(idx2),LUA_OPEQ) +#define lua_lessthan(L,idx1,idx2) lua_compare(L,(idx1),(idx2),LUA_OPLT) + +/* +@@ LUA_COMPAT_MODULE controls compatibility with previous +** module functions 'module' (Lua) and 'luaL_register' (C). +*/ +#define LUA_COMPAT_MODULE + +#endif /* } */ + +/* }================================================================== */ + + + +/* +@@ LUAI_BITSINT defines the number of bits in an int. +** CHANGE here if Lua cannot automatically detect the number of bits of +** your machine. Probably you do not need to change this. +*/ +/* avoid overflows in comparison */ +#if INT_MAX-20 < 32760 /* { */ +#define LUAI_BITSINT 16 +#elif INT_MAX > 2147483640L /* }{ */ +/* int has at least 32 bits */ +#define LUAI_BITSINT 32 +#else /* }{ */ +#error "you must define LUA_BITSINT with number of bits in an integer" +#endif /* } */ + + +/* +@@ LUA_INT32 is an signed integer with exactly 32 bits. +@@ LUAI_UMEM is an unsigned integer big enough to count the total +@* memory used by Lua. +@@ LUAI_MEM is a signed integer big enough to count the total memory +@* used by Lua. +** CHANGE here if for some weird reason the default definitions are not +** good enough for your machine. Probably you do not need to change +** this. +*/ +#if LUAI_BITSINT >= 32 /* { */ +#define LUA_INT32 int +#define LUAI_UMEM size_t +#define LUAI_MEM ptrdiff_t +#else /* }{ */ +/* 16-bit ints */ +#define LUA_INT32 long +#define LUAI_UMEM unsigned long +#define LUAI_MEM long +#endif /* } */ + + +/* +@@ LUAI_MAXSTACK limits the size of the Lua stack. +** CHANGE it if you need a different limit. This limit is arbitrary; +** its only purpose is to stop Lua to consume unlimited stack +** space (and to reserve some numbers for pseudo-indices). +*/ +#if LUAI_BITSINT >= 32 +#define LUAI_MAXSTACK 1000000 +#else +#define LUAI_MAXSTACK 15000 +#endif + +/* reserve some space for error handling */ +#define LUAI_FIRSTPSEUDOIDX (-LUAI_MAXSTACK - 1000) + + + + +/* +@@ LUAL_BUFFERSIZE is the buffer size used by the lauxlib buffer system. +** CHANGE it if it uses too much C-stack space. +*/ +#define LUAL_BUFFERSIZE BUFSIZ + + + + +/* +** {================================================================== +@@ LUA_NUMBER is the type of numbers in Lua. +** CHANGE the following definitions only if you want to build Lua +** with a number type different from double. You may also need to +** change lua_number2int & lua_number2integer. +** =================================================================== +*/ + +#define LUA_NUMBER_DOUBLE +#define LUA_NUMBER double + +/* +@@ LUAI_UACNUMBER is the result of an 'usual argument conversion' +@* over a number. +*/ +#define LUAI_UACNUMBER double + + +/* +@@ LUA_NUMBER_SCAN is the format for reading numbers. +@@ LUA_NUMBER_FMT is the format for writing numbers. +@@ lua_number2str converts a number to a string. +@@ LUAI_MAXNUMBER2STR is maximum size of previous conversion. +*/ +#define LUA_NUMBER_SCAN "%lf" +#define LUA_NUMBER_FMT "%.14g" +#define lua_number2str(s,n) sprintf((s), LUA_NUMBER_FMT, (n)) +#define LUAI_MAXNUMBER2STR 32 /* 16 digits, sign, point, and \0 */ + + +/* +@@ lua_str2number converts a decimal numeric string to a number. +@@ lua_strx2number converts an hexadecimal numeric string to a number. +** In C99, 'strtod' do both conversions. C89, however, has no function +** to convert floating hexadecimal strings to numbers. For these +** systems, you can leave 'lua_strx2number' undefined and Lua will +** provide its own implementation. +*/ +#define lua_str2number(s,p) strtod((s), (p)) + +#if defined(LUA_USE_STRTODHEX) +#define lua_strx2number(s,p) strtod((s), (p)) +#endif + + +/* +@@ The luai_num* macros define the primitive operations over numbers. +*/ + +/* the following operations need the math library */ +#if defined(lobject_c) || defined(lvm_c) +#include <math.h> +#define luai_nummod(L,a,b) ((a) - floor((a)/(b))*(b)) +#define luai_numpow(L,a,b) (pow(a,b)) +#endif + +/* these are quite standard operations */ +#if defined(LUA_CORE) +#define luai_numadd(L,a,b) ((a)+(b)) +#define luai_numsub(L,a,b) ((a)-(b)) +#define luai_nummul(L,a,b) ((a)*(b)) +#define luai_numdiv(L,a,b) ((a)/(b)) +#define luai_numunm(L,a) (-(a)) +#define luai_numeq(a,b) ((a)==(b)) +#define luai_numlt(L,a,b) ((a)<(b)) +#define luai_numle(L,a,b) ((a)<=(b)) +#define luai_numisnan(L,a) (!luai_numeq((a), (a))) +#endif + + + +/* +@@ LUA_INTEGER is the integral type used by lua_pushinteger/lua_tointeger. +** CHANGE that if ptrdiff_t is not adequate on your machine. (On most +** machines, ptrdiff_t gives a good choice between int or long.) +*/ +#define LUA_INTEGER ptrdiff_t + +/* +@@ LUA_UNSIGNED is the integral type used by lua_pushunsigned/lua_tounsigned. +** It must have at least 32 bits. +*/ +#define LUA_UNSIGNED unsigned LUA_INT32 + + +#if defined(LUA_CORE) /* { */ + +#if defined(LUA_NUMBER_DOUBLE) && !defined(LUA_ANSI) /* { */ + +/* On a Microsoft compiler on a Pentium, use assembler to avoid clashes + with a DirectX idiosyncrasy */ +#if defined(LUA_WIN) && defined(_MSC_VER) && defined(_M_IX86) /* { */ + +#define MS_ASMTRICK + +#else /* }{ */ +/* the next definition uses a trick that should work on any machine + using IEEE754 with a 32-bit integer type */ + +#define LUA_IEEE754TRICK + +/* +@@ LUA_IEEEENDIAN is the endianness of doubles in your machine +** (0 for little endian, 1 for big endian); if not defined, Lua will +** check it dynamically. +*/ +/* check for known architectures */ +#if defined(__i386__) || defined(__i386) || defined(__X86__) || \ + defined (__x86_64) +#define LUA_IEEEENDIAN 0 +#elif defined(__POWERPC__) || defined(__ppc__) +#define LUA_IEEEENDIAN 1 +#endif + +#endif /* } */ + +#endif /* } */ + +#endif /* } */ + +/* }================================================================== */ + + +/* +@@ LUA_NANTRICK_LE/LUA_NANTRICK_BE controls the use of a trick to +** pack all types into a single double value, using NaN values to +** represent non-number values. The trick only works on 32-bit machines +** (ints and pointers are 32-bit values) with numbers represented as +** IEEE 754-2008 doubles with conventional endianess (12345678 or +** 87654321), in CPUs that do not produce signaling NaN values (all NaNs +** are quiet). +*/ +#if defined(LUA_CORE) && \ + defined(LUA_NUMBER_DOUBLE) && !defined(LUA_ANSI) /* { */ + +/* little-endian architectures that satisfy those conditions */ +#if defined(__i386__) || defined(__i386) || defined(__X86__) || \ + defined(_M_IX86) + +#define LUA_NANTRICK_LE + +#endif + +#endif /* } */ + + + + +/* =================================================================== */ + +/* +** Local configuration. You can use this space to add your redefinitions +** without modifying the main part of the file. +*/ + + + +#endif + |
