| @@ -8,9 +8,9 @@ · 7 unmodified lines |
| 8 | 8 | |
| 9 | 9 | <body bgcolor="#FFFFFF"> |
| 10 | 10 | |
| 11 | | −<hr/> |
| 11 | +<hr /> |
| 12 | 12 | <h1> |
| 13 | | −<a href="http://www.lua.org/home.html"><img src="logo.gif" alt="[Lua logo]" border="0"/></a> |
| 13 | +<a href="http://www.lua.org/home.html"><img src="logo.gif" alt="[Lua logo]" border="0" /></a> |
| 14 | 14 | Lua 5.1 Reference Manual |
| 15 | 15 | </h1> |
| 16 | 16 | |
| @@ -18,16 +18,15 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes · 1 unmodified line |
| 18 | 18 | <p> |
| 19 | 19 | <small> |
| 20 | 20 | <a href="http://www.lua.org/copyright.html">Copyright</a> |
| 21 | | −© 2005 Lua.org, PUC-Rio. All rights reserved. |
| 21 | +© 2006 Lua.org, PUC-Rio. All rights reserved. |
| 22 | 22 | </small> |
| 23 | | −<hr/> |
| 23 | +<hr /> |
| 24 | 24 | |
| 25 | 25 | <p> |
| 26 | 26 | <p> |
| 27 | 27 | <!-- ====================================================================== --> |
| 28 | 28 | |
| 29 | 29 | |
| 30 | | − |
| 31 | 30 | <a name="1"></a><h1>1 - Introduction</h1> |
| 32 | 31 | |
| 33 | 32 | <p>Lua is an extension programming language designed to support |
| @@ -36,7 +35,7 @@ facilities. · 2 unmodified lines |
| 36 | 35 | It also offers good support for object-oriented programming, |
| 37 | 36 | functional programming, and data-driven programming. |
| 38 | 37 | Lua is intended to be used as a powerful, light-weight |
| 39 | | −configuration language for any program that needs one. |
| 38 | +scripting language for any program that needs one. |
| 40 | 39 | Lua is implemented as a library, written in <em>clean</em> C |
| 41 | 40 | (that is, in the common subset of ANSI C and C++). |
| 42 | 41 | |
| @@ -49,42 +48,21 @@ and can register C functions to be called by Lua code. · 6 unmodified lines |
| 49 | 48 | Through the use of C functions, Lua can be augmented to cope with |
| 50 | 49 | a wide range of different domains, |
| 51 | 50 | thus creating customized programming languages sharing a syntactical framework. |
| 52 | | − |
| 53 | | −<p>The Lua distribution includes a stand-alone embedding program, |
| 54 | | −<code>lua</code>, that uses the Lua library to offer a complete Lua interpreter. |
| 51 | +The Lua distribution includes a sample host program called <code>lua</code>, |
| 52 | +which uses the Lua library to offer a complete, stand-alone Lua interpreter. |
| 55 | 53 | |
| 56 | 54 | <p>Lua is free software, |
| 57 | 55 | and is provided as usual with no guarantees, |
| 58 | | −as stated in its copyright notice. |
| 56 | +as stated in its license. |
| 59 | 57 | The implementation described in this manual is available |
| 60 | 58 | at Lua's official web site, <code>www.lua.org</code>. |
| 61 | 59 | |
| 62 | 60 | <p>Like any other reference manual, |
| 63 | 61 | this document is dry in places. |
| 64 | 62 | For a discussion of the decisions behind the design of Lua, |
| 65 | | −see the papers below, |
| 66 | | −which are available at Lua's web site. |
| 67 | | −<ul> |
| 68 | | −<li> |
| 69 | | −R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. |
| 70 | | −Lua---an extensible extension language. |
| 71 | | −<em>Software: Practice & Experience</em> <b>26</b>:6 (1996) 635--652. |
| 72 | | −<li> |
| 73 | | −L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. |
| 74 | | −The design and implementation of a language for extending applications. |
| 75 | | −<em>Proceedings of XXI Brazilian Seminar on Software and Hardware</em> |
| 76 | | −(1994) 273--283. |
| 77 | | −<li> |
| 78 | | −L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. |
| 79 | | −Lua: an extensible embedded language. |
| 80 | | −<em>Dr. Dobb's Journal</em> <b>21</b>:12 (Dec 1996) 26--33. |
| 81 | | −<li> |
| 82 | | −R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. |
| 83 | | −The evolution of an extension language: a history of Lua, |
| 84 | | −<em>Proceedings of V Brazilian Symposium on Programming Languages</em> (2001) B-14--B-28. |
| 85 | | −</ul> |
| 86 | | − |
| 87 | | −<p>Lua means "moon" in Portuguese and is pronounced LOO-ah. |
| 63 | +see the technical papers available at Lua's web site. |
| 64 | +For a detailed introduction to programming in Lua, |
| 65 | +see Roberto's book, <em>Programming in Lua</em>. |
| 88 | 66 | |
| 89 | 67 | <p> |
| 90 | 68 | <a name="language"></a><a name="2"></a><h1>2 - The Language</h1> |
| @@ -96,7 +74,7 @@ which tokens are valid, · 5 unmodified lines |
| 96 | 74 | how they can be combined, |
| 97 | 75 | and what their combinations mean. |
| 98 | 76 | |
| 99 | | −<p>The language constructs will be explained using the usual extended BNF, |
| 77 | +<p>The language constructs will be explained using the usual extended BNF notation, |
| 100 | 78 | in which |
| 101 | 79 | {<em>a</em>} means 0 or more <em>a</em>'s, and |
| 102 | 80 | [<em>a</em>] means an optional <em>a</em>. |
| @@ -104,16 +82,20 @@ Non-terminals are shown in <em>italics</em>, · 1 unmodified line |
| 104 | 82 | keywords are shown in <b>bold</b>, |
| 105 | 83 | and other terminal symbols are shown in <code>typewriter</code> font, |
| 106 | 84 | enclosed in single quotes. |
| 85 | +The complete syntax of Lua can be found at the end of this manual. |
| 107 | 86 | |
| 108 | 87 | <p><a name="lexical"></a><a name="2.1"></a><h2>2.1 - Lexical Conventions</h2> |
| 109 | 88 | |
| 110 | | −<p><em>Names</em> in Lua can be any string of letters, |
| 89 | +<p><em>Names</em> |
| 90 | +(also called <em>identifiers</em>) |
| 91 | +in Lua can be any string of letters, |
| 111 | 92 | digits, and underscores, |
| 112 | 93 | not beginning with a digit. |
| 113 | 94 | This coincides with the definition of names in most languages. |
| 114 | 95 | (The definition of letter depends on the current locale: |
| 115 | 96 | any character considered alphabetic by the current locale |
| 116 | 97 | can be used in an identifier.) |
| 98 | +Identifiers are used to name variables and table fields. |
| 117 | 99 | |
| 118 | 100 | <p>The following <em>keywords</em> are reserved |
| 119 | 101 | and cannot be used as names: |
| @@ -130,7 +112,7 @@ and cannot be used as names: · 10 unmodified lines |
| 130 | 112 | are two different, valid names. |
| 131 | 113 | As a convention, names starting with an underscore followed by |
| 132 | 114 | uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) |
| 133 | | −are reserved for internal variables used by Lua. |
| 115 | +are reserved for internal global variables used by Lua. |
| 134 | 116 | |
| 135 | 117 | <p>The following strings denote other tokens: |
| 136 | 118 | <pre> |
| @@ -152,8 +134,8 @@ and can contain the following C-like escape sequences: · 15 unmodified lines |
| 152 | 134 | <li><b><code>\t</code></b> --- horizontal tab |
| 153 | 135 | <li><b><code>\v</code></b> --- vertical tab |
| 154 | 136 | <li><b><code>\\</code></b> --- backslash |
| 155 | | −<li><b><code>\"</code></b> --- quotation mark |
| 156 | | −<li><b><code>\'</code></b> --- apostrophe |
| 137 | +<li><b><code>\"</code></b> --- quotation mark (double quote) |
| 138 | +<li><b><code>\'</code></b> --- apostrophe (single quote) |
| 157 | 139 | </ul> |
| 158 | 140 | Moreover, a `<code>\</code><em>newline</em>´ |
| 159 | 141 | (that is, a backslash followed by a real newline) |
| @@ -161,38 +143,51 @@ results in a newline in the string. · 1 unmodified line |
| 161 | 143 | A character in a string may also be specified by its numerical value |
| 162 | 144 | using the escape sequence `<code>\</code><em>ddd</em>´, |
| 163 | 145 | where <em>ddd</em> is a sequence of up to three decimal digits. |
| 146 | +(Note that if a numerical escape is to be followed by a digit, |
| 147 | +it must be expressed using exactly three digits.) |
| 164 | 148 | Strings in Lua may contain any 8-bit value, including embedded zeros, |
| 165 | 149 | which can be specified as `<code>\0</code>´. |
| 166 | 150 | |
| 151 | +<p>To put a double (single) quote, a newline, a backslash, |
| 152 | +or an embedded zero |
| 153 | +inside a literal string enclosed by double (single) quotes |
| 154 | +you must use an escape sequence. |
| 155 | +Any other character may be directly inserted into the literal. |
| 156 | +(Some control characters may cause problems for the file system, |
| 157 | +but Lua has no problem with them.) |
| 158 | + |
| 167 | 159 | <p>Literal strings can also be defined using a long format |
| 168 | | −enclosed by <em>l-brackets</em> (long brackets). |
| 169 | | −We define an <em>opening l-bracket of level <em>n</em></em> as an opening |
| 160 | +enclosed by <em>long brackets</em>. |
| 161 | +We define an <em>opening long bracket of level <em>n</em></em> as an opening |
| 170 | 162 | square bracket followed by <em>n</em> equal signs followed by another |
| 171 | 163 | opening square bracket. |
| 172 | | −So, an opening l-bracket of level 0 is written as <code>[[</code>, |
| 173 | | −an opening l-bracket of level 1 is written as <code>[=[</code>, |
| 164 | +So, an opening long bracket of level 0 is written as <code>[[</code>, |
| 165 | +an opening long bracket of level 1 is written as <code>[=[</code>, |
| 174 | 166 | and so on. |
| 175 | | −A <em>closing l-bracket</em> is defined similarly; |
| 176 | | −for instance, a closing l-bracket of level 4 is written as <code>]====]</code>. |
| 177 | | −A long string starts with an opening l-bracket of any level and |
| 178 | | −ends at the first closing l-bracket of the same level. |
| 167 | +A <em>closing long bracket</em> is defined similarly; |
| 168 | +for instance, a closing long bracket of level 4 is written as <code>]====]</code>. |
| 169 | +A long string starts with an opening long bracket of any level and |
| 170 | +ends at the first closing long bracket of the same level. |
| 179 | 171 | Literals in this bracketed form may run for several lines, |
| 180 | 172 | do not interpret any escape sequences, |
| 181 | | −and ignore l-brackets of any other level. |
| 173 | +and ignore long brackets of any other level. |
| 174 | +They may contain anything except a closing bracket of the proper level |
| 175 | +or embedded zeros. |
| 182 | 176 | |
| 183 | 177 | <p>For convenience, |
| 184 | | −when the opening l-bracket is immediately followed by a newline, |
| 178 | +when the opening long bracket is immediately followed by a newline, |
| 185 | 179 | the newline is not included in the string. |
| 186 | 180 | As an example, in a system using ASCII |
| 187 | 181 | (in which `<code>a</code>´ is coded as 97, |
| 188 | 182 | newline is coded as 10, and `<code>1</code>´ is coded as 49), |
| 189 | 183 | the four literals below denote the same string: |
| 190 | 184 | <pre> |
| 191 | | − (1) "alo\n123\"" |
| 192 | | − (2) '\97lo\10\04923"' |
| 193 | | − (3) [[alo |
| 185 | + (1) 'alo\n123"' |
| 186 | + (2) "alo\n123\"" |
| 187 | + (3) '\97lo\10\04923"' |
| 188 | + (4) [[alo |
| 194 | 189 | 123"]] |
| 195 | | − (4) [==[ |
| 190 | + (5) [==[ |
| 196 | 191 | alo |
| 197 | 192 | 123"]==] |
| 198 | 193 | </pre> |
| @@ -204,13 +199,14 @@ Examples of valid numerical constants are · 5 unmodified lines |
| 204 | 199 | 3 3.0 3.1416 314.16e-2 0.31416E1 |
| 205 | 200 | </pre> |
| 206 | 201 | |
| 207 | | −<p><em>Comments</em> start anywhere outside a string with a |
| 208 | | −double hyphen (<code>--</code>). |
| 209 | | −If the text immediately after <code>--</code> is not an opening l-bracket, |
| 202 | +<p><em>Comments</em> start with a double hyphen (<code>--</code>) |
| 203 | +anywhere outside a string. |
| 204 | +If the text immediately after <code>--</code> is not an opening long bracket, |
| 210 | 205 | the comment is a <em>short comment</em>, |
| 211 | 206 | which runs until the end of the line. |
| 212 | 207 | Otherwise, it is a <em>long comment</em>, |
| 213 | | −which runs until the corresponding closing l-bracket. |
| 208 | +which runs until the corresponding closing long bracket. |
| 209 | +Long comments are frequently used to disable code temporarily. |
| 214 | 210 | |
| 215 | 211 | <p><a name="TypesSec"></a><a name="2.2"></a><h2>2.2 - Values and Types</h2> |
| 216 | 212 | |
| @@ -220,15 +216,19 @@ variables do not have types; only values do. · 3 unmodified lines |
| 220 | 216 | There are no type definitions in the language. |
| 221 | 217 | All values carry their own type. |
| 222 | 218 | |
| 219 | +<p>All values in Lua are <em>first-class values</em>. |
| 220 | +That means that all values can be stored in variables, |
| 221 | +passed as arguments to other functions, and returned as results. |
| 222 | + |
| 223 | 223 | <p>There are eight basic types in Lua: |
| 224 | 224 | <em>nil</em>, <em>boolean</em>, <em>number</em>, |
| 225 | 225 | <em>string</em>, <em>function</em>, <em>userdata</em>, |
| 226 | 226 | <em>thread</em>, and <em>table</em>. |
| 227 | 227 | <em>Nil</em> is the type of the value <b>nil</b>, |
| 228 | 228 | whose main property is to be different from any other value; |
| 229 | | −usually it represents the absence of a useful value. |
| 229 | +it usually represents the absence of a useful value. |
| 230 | 230 | <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. |
| 231 | | −In Lua, both <b>nil</b> and <b>false</b> make a condition false; |
| 231 | +Both <b>nil</b> and <b>false</b> make a condition false; |
| 232 | 232 | any other value makes it true. |
| 233 | 233 | <em>Number</em> represents real (double-precision floating-point) numbers. |
| 234 | 234 | (It is easy to build Lua interpreters that use other |
| @@ -239,12 +239,9 @@ See file <code>luaconf.h</code>.) · 4 unmodified lines |
| 239 | 239 | |
| 240 | 240 | Lua is 8-bit clean: |
| 241 | 241 | Strings may contain any 8-bit character, |
| 242 | | −including embedded zeros (<code>'\0'</code>) (see <a href="#lexical">2.1</a>). |
| 242 | +including embedded zeros (`<code>\0</code>´) (see <a href="#lexical">2.1</a>). |
| 243 | 243 | |
| 244 | | −<p>Functions are <em>first-class values</em> in Lua. |
| 245 | | −That means that functions can be stored in variables, |
| 246 | | −passed as arguments to other functions, and returned as results. |
| 247 | | −Lua can call (and manipulate) functions written in Lua and |
| 244 | +<p>Lua can call (and manipulate) functions written in Lua and |
| 248 | 245 | functions written in C |
| 249 | 246 | (see <a href="#functioncall">2.5.8</a>). |
| 250 | 247 | |
| @@ -262,12 +259,14 @@ This guarantees the integrity of data owned by the host program. · 11 unmodified lines |
| 262 | 259 | |
| 263 | 260 | <p>The type <em>thread</em> represents independent threads of execution |
| 264 | 261 | and it is used to implement coroutines (see <a href="#coroutine">2.11</a>). |
| 262 | +Do not confuse Lua threads with operating-system threads. |
| 263 | +Lua supports coroutines on all systems, |
| 264 | +even those that do not support threads. |
| 265 | 265 | |
| 266 | 266 | <p>The type <em>table</em> implements associative arrays, |
| 267 | 267 | that is, arrays that can be indexed not only with numbers, |
| 268 | 268 | but with any value (except <b>nil</b>). |
| 269 | | −Moreover, |
| 270 | | −tables can be <em>heterogeneous</em>, |
| 269 | +Tables can be <em>heterogeneous</em>; |
| 271 | 270 | that is, they can contain values of all types (except <b>nil</b>). |
| 272 | 271 | Tables are the sole data structuring mechanism in Lua; |
| 273 | 272 | they may be used to represent ordinary arrays, |
| @@ -281,11 +280,11 @@ There are several convenient ways to create tables in Lua · 7 unmodified lines |
| 281 | 280 | <p>Like indices, |
| 282 | 281 | the value of a table field can be of any type (except <b>nil</b>). |
| 283 | 282 | In particular, |
| 284 | | −because functions are first class values, |
| 283 | +because functions are first-class values, |
| 285 | 284 | table fields may contain functions. |
| 286 | 285 | Thus tables may also carry <em>methods</em> (see <a href="#func-def">2.5.9</a>). |
| 287 | 286 | |
| 288 | | −<p>Tables, functions, and userdata values are <em>objects</em>: |
| 287 | +<p>Strings, tables, functions, and userdata values are <em>objects</em>: |
| 289 | 288 | variables do not actually <em>contain</em> these values, |
| 290 | 289 | only <em>references</em> to them. |
| 291 | 290 | Assignment, parameter passing, and function returns |
| @@ -300,7 +299,7 @@ of a given value. · 8 unmodified lines |
| 300 | 299 | <p>Lua provides automatic conversion between |
| 301 | 300 | string and number values at run time. |
| 302 | 301 | Any arithmetic operation applied to a string tries to convert |
| 303 | | −that string to a number, following the usual rules. |
| 302 | +that string to a number, following the usual conversion rules. |
| 304 | 303 | Conversely, whenever a number is used where a string is expected, |
| 305 | 304 | the number is converted to a string, in a reasonable format. |
| 306 | 305 | For complete control of how numbers are converted to strings, |
| @@ -315,12 +314,14 @@ There are three kinds of variables in Lua: · 8 unmodified lines |
| 315 | 314 | global variables, local variables, and table fields. |
| 316 | 315 | |
| 317 | 316 | <p>A single name can denote a global variable or a local variable |
| 318 | | −(or a formal parameter of a function, |
| 319 | | −which is a particular form of local variable): |
| 317 | +(or a function formal parameter, |
| 318 | +which is a particular kind of local variable): |
| 320 | 319 | <pre> |
| 321 | 320 | var ::= Name |
| 322 | 321 | </pre> |
| 323 | | −Variables are assumed to be global unless explicitly declared local |
| 322 | +Name denotes identifiers, as defined in (see <a href="#lexical">2.1</a>). |
| 323 | + |
| 324 | +<p>Variables are assumed to be global unless explicitly declared local |
| 324 | 325 | (see <a href="#localvar">2.4.7</a>). |
| 325 | 326 | Local variables are <em>lexically scoped</em>: |
| 326 | 327 | Local variables can be freely accessed by functions |
| @@ -334,12 +335,12 @@ defined inside their scope (see <a href="#visibility">2.6</a>). · 7 unmodified lines |
| 334 | 335 | </pre> |
| 335 | 336 | The first expression (<em>prefixexp</em>) should result in a table value; |
| 336 | 337 | the second expression (<em>exp</em>) |
| 337 | | −identifies a specific entry inside that table. |
| 338 | +identifies a specific entry in that table. |
| 338 | 339 | The expression denoting the table to be indexed has a restricted syntax; |
| 339 | 340 | see <a href="#expressions">2.5</a> for details. |
| 340 | 341 | |
| 341 | | −<p>The syntax <code>var.NAME</code> is just syntactic sugar for |
| 342 | | −<code>var["NAME"]</code>: |
| 342 | +<p>The syntax <code>var.Name</code> is just syntactic sugar for |
| 343 | +<code>var["Name"]</code> and is used to denote table fields: |
| 343 | 344 | <pre> |
| 344 | 345 | var ::= prefixexp `<b>.</b>´ Name |
| 345 | 346 | </pre> |
| @@ -361,8 +362,10 @@ so that all global variables in that function · 15 unmodified lines |
| 361 | 362 | will refer to that environment table. |
| 362 | 363 | When a function is created, |
| 363 | 364 | it inherits the environment from the function that created it. |
| 364 | | −To replace or get the environment table of a Lua function, |
| 365 | | −you call <a href="#pdf-setfenv"><code>setfenv</code></a> or <a href="#pdf-getfenv"><code>getfenv</code></a>. |
| 365 | +To get the environment table of a Lua function, |
| 366 | +you call <a href="#pdf-setfenv"><code>setfenv</code></a>. |
| 367 | +To replace it, |
| 368 | +you call <a href="#pdf-setfenv"><code>setfenv</code></a>. |
| 366 | 369 | (You can only manipulate the environment of C functions |
| 367 | 370 | through the debug library; (see <a href="#libdebug">5.9</a>).) |
| 368 | 371 | |
| @@ -384,7 +387,7 @@ We use them here only for explanatory purposes.) · 15 unmodified lines |
| 384 | 387 | <p>Lua supports an almost conventional set of statements, |
| 385 | 388 | similar to those in Pascal or C. |
| 386 | 389 | This set includes |
| 387 | | −assignment, control structures, procedure calls, |
| 390 | +assignment, control structures, function calls, |
| 388 | 391 | table constructors, and variable declarations. |
| 389 | 392 | |
| 390 | 393 | <p><a name="chunks"></a><a name="2.4.1"></a><h3>2.4.1 - Chunks</h3> |
| @@ -396,6 +399,7 @@ Each statement can be optionally followed by a semicolon: · 5 unmodified lines |
| 396 | 399 | <pre> |
| 397 | 400 | chunk ::= {stat [`<b>;</b>´]} |
| 398 | 401 | </pre> |
| 402 | +There are no empty statements and thus `<code>;;</code>´ is not legal. |
| 399 | 403 | |
| 400 | 404 | <p>Lua handles a chunk as the body of an anonymous function |
| 401 | 405 | with a variable number of arguments |
| @@ -404,7 +408,7 @@ As such, chunks can define local variables, · 2 unmodified lines |
| 404 | 408 | receive arguments, and return values. |
| 405 | 409 | |
| 406 | 410 | <p>A chunk may be stored in a file or in a string inside the host program. |
| 407 | | −When a chunk is executed, first it is pre-compiled into opcodes for |
| 411 | +When a chunk is executed, first it is pre-compiled into instructions for |
| 408 | 412 | a virtual machine, |
| 409 | 413 | and then the compiled code is executed |
| 410 | 414 | by an interpreter for the virtual machine. |
| @@ -417,7 +421,7 @@ Lua automatically detects the file type and acts accordingly. · 6 unmodified lines |
| 417 | 421 | |
| 418 | 422 | <p><a name="2.4.2"></a><h3>2.4.2 - Blocks</h3> |
| 419 | 423 | A block is a list of statements; |
| 420 | | −syntactically, a block is equal to a chunk: |
| 424 | +syntactically, a block is the same as a chunk: |
| 421 | 425 | <pre> |
| 422 | 426 | block ::= chunk |
| 423 | 427 | </pre> |
| @@ -455,7 +459,7 @@ the excess values are thrown away. · 31 unmodified lines |
| 455 | 459 | If there are fewer values than needed, |
| 456 | 460 | the list is extended with as many <b>nil</b>'s as needed. |
| 457 | 461 | If the list of expressions ends with a function call, |
| 458 | | −then all values returned by that function call enter in the list of values, |
| 462 | +then all values returned by that call enter in the list of values, |
| 459 | 463 | before the adjustment |
| 460 | 464 | (except when the call is enclosed in parentheses; see <a href="#expressions">2.5</a>). |
| 461 | 465 | |
| @@ -509,7 +513,7 @@ familiar syntax: · 47 unmodified lines |
| 509 | 513 | </pre> |
| 510 | 514 | Lua also has a <b>for</b> statement, in two flavors (see <a href="#for">2.4.5</a>). |
| 511 | 515 | |
| 512 | | −<p>The condition expression <em>exp</em> of a |
| 516 | +<p>The condition expression of a |
| 513 | 517 | control structure may return any value. |
| 514 | 518 | Both <b>false</b> and <b>nil</b> are considered false. |
| 515 | 519 | All values different from <b>nil</b> and <b>false</b> are considered true |
| @@ -518,11 +522,11 @@ All values different from <b>nil</b> and <b>false</b> are considered true · 2 unmodified lines |
| 518 | 522 | <p>In the <b>repeat</b>--<b>until</b> loop, |
| 519 | 523 | the inner block does not end at the <b>until</b> keyword, |
| 520 | 524 | but only after the condition. |
| 521 | | −That means the condition can refer to local variables |
| 522 | | −declared inside the loop. |
| 525 | +So, the condition can refer to local variables |
| 526 | +declared inside the loop block. |
| 523 | 527 | |
| 524 | 528 | <p>The <b>return</b> statement is used to return values |
| 525 | | −from a function or from a chunk. |
| 529 | +from a function or a chunk (which is just a function). |
| 526 | 530 | |
| 527 | 531 | Functions and chunks may return more than one value, |
| 528 | 532 | so the syntax for the <b>return</b> statement is |
| @@ -530,7 +534,7 @@ so the syntax for the <b>return</b> statement is · 1 unmodified line |
| 530 | 534 | stat ::= <b>return</b> [explist1] |
| 531 | 535 | </pre> |
| 532 | 536 | |
| 533 | | −<p>The <b>break</b> statement can be used to terminate the execution of a |
| 537 | +<p>The <b>break</b> statement is used to terminate the execution of a |
| 534 | 538 | <b>while</b>, <b>repeat</b>, or <b>for</b> loop, |
| 535 | 539 | skipping to the next statement after the loop: |
| 536 | 540 | |
| @@ -539,7 +543,7 @@ skipping to the next statement after the loop: · 2 unmodified lines |
| 539 | 543 | </pre> |
| 540 | 544 | A <b>break</b> ends the innermost enclosing loop. |
| 541 | 545 | |
| 542 | | −<p>For syntactic reasons, <b>return</b> and <b>break</b> |
| 546 | +<p>The <b>return</b> and <b>break</b> |
| 543 | 547 | statements can only be written as the <em>last</em> statement of a block. |
| 544 | 548 | If it is really necessary to <b>return</b> or <b>break</b> in the |
| 545 | 549 | middle of a block, |
| @@ -599,11 +603,12 @@ then assign it to another variable before breaking or exiting the loop. · 53 unmodified lines |
| 599 | 603 | |
| 600 | 604 | <p>The generic <b>for</b> statement works over functions, |
| 601 | 605 | called <em>iterators</em>. |
| 602 | | −For each iteration, it calls its iterator function to produce a new value, |
| 603 | | −stopping when the new value is <b>nil</b>. |
| 606 | +On each iteration, the iterator function is called to produce a new value, |
| 607 | +stopping when this new value is <b>nil</b>. |
| 604 | 608 | The generic <b>for</b> loop has the following syntax: |
| 605 | 609 | <pre> |
| 606 | | − stat ::= <b>for</b> Name {`<b>,</b>´ Name} <b>in</b> explist1 <b>do</b> block <b>end</b> |
| 610 | + stat ::= <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> |
| 611 | + namelist ::= Name {`<b>,</b>´ Name} |
| 607 | 612 | </pre> |
| 608 | 613 | A <b>for</b> statement like |
| 609 | 614 | <pre> |
| @@ -649,14 +654,13 @@ Local variables may be declared anywhere inside a block. · 39 unmodified lines |
| 649 | 654 | The declaration may include an initial assignment: |
| 650 | 655 | <pre> |
| 651 | 656 | stat ::= <b>local</b> namelist [`<b>=</b>´ explist1] |
| 652 | | − namelist ::= Name {`<b>,</b>´ Name} |
| 653 | 657 | </pre> |
| 654 | 658 | If present, an initial assignment has the same semantics |
| 655 | 659 | of a multiple assignment (see <a href="#assignment">2.4.3</a>). |
| 656 | 660 | Otherwise, all variables are initialized with <b>nil</b>. |
| 657 | 661 | |
| 658 | 662 | <p>A chunk is also a block (see <a href="#chunks">2.4.1</a>), |
| 659 | | −so local variables can be declared in a chunk outside any explicit block. |
| 663 | +and so local variables can be declared in a chunk outside any explicit block. |
| 660 | 664 | The scope of such local variables extends until the end of the chunk. |
| 661 | 665 | |
| 662 | 666 | <p>The visibility rules for local variables are explained in <a href="#visibility">2.6</a>. |
| @@ -669,7 +673,7 @@ The basic expressions in Lua are the following: · 6 unmodified lines |
| 669 | 673 | exp ::= prefixexp |
| 670 | 674 | exp ::= <b>nil</b> | <b>false</b> | <b>true</b> |
| 671 | 675 | exp ::= Number |
| 672 | | − exp ::= Literal |
| 676 | + exp ::= String |
| 673 | 677 | exp ::= function |
| 674 | 678 | exp ::= tableconstructor |
| 675 | 679 | exp ::= `<b>...</b>´ |
| @@ -684,7 +688,7 @@ function definitions are explained in <a href="#func-def">2.5.9</a>; · 8 unmodified lines |
| 684 | 688 | function calls are explained in <a href="#functioncall">2.5.8</a>; |
| 685 | 689 | table constructors are explained in <a href="#tableconstructor">2.5.7</a>. |
| 686 | 690 | Vararg expressions, |
| 687 | | −denoted by three dots (...), can only be used inside |
| 691 | +denoted by three dots (`<code>...</code>´), can only be used inside |
| 688 | 692 | vararg functions; |
| 689 | 693 | they are explained in <a href="#func-def">2.5.9</a>. |
| 690 | 694 | |
| @@ -738,18 +742,18 @@ or <b>nil</b> if <code>f</code> does not return any values.) · 47 unmodified lines |
| 738 | 742 | Lua supports the usual arithmetic operators: |
| 739 | 743 | the binary <code>+</code> (addition), |
| 740 | 744 | <code>-</code> (subtraction), <code>*</code> (multiplication), |
| 741 | | −<code>/</code> (division), <code>%</code> (modulus), and <code>^</code> (exponentiation); |
| 745 | +<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); |
| 742 | 746 | and unary <code>-</code> (negation). |
| 743 | 747 | If the operands are numbers, or strings that can be converted to |
| 744 | 748 | numbers (see <a href="#coercion">2.2.1</a>), |
| 745 | 749 | then all operations have the usual meaning. |
| 746 | 750 | Exponentiation works for any exponent. |
| 747 | | −For instance, <code>x^-0.5</code> computes the inverse of the square root of <code>x</code>. |
| 751 | +For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. |
| 748 | 752 | Modulus is defined as |
| 749 | 753 | <pre> |
| 750 | | − a % b == a - math.floor(a/b)*b |
| 754 | + a % b == a - math.floor(a/b)*b |
| 751 | 755 | </pre> |
| 752 | | −That is, it is the remaining of a division that rounds |
| 756 | +That is, it is the remainder of a division that rounds |
| 753 | 757 | the quotient towards minus infinity. |
| 754 | 758 | |
| 755 | 759 | <p><a name="rel-ops"></a><a name="2.5.2"></a><h3>2.5.2 - Relational Operators</h3> |
| @@ -766,11 +770,12 @@ Numbers and strings are compared in the usual way. · 10 unmodified lines |
| 766 | 770 | Objects (tables, userdata, threads, and functions) |
| 767 | 771 | are compared by <em>reference</em>: |
| 768 | 772 | Two objects are considered equal only if they are the <em>same</em> object. |
| 769 | | −Every time you create a new object (a table, userdata, or function), |
| 773 | +Every time you create a new object |
| 774 | +(a table, userdata, thread, or function), |
| 770 | 775 | this new object is different from any previously existing object. |
| 771 | 776 | |
| 772 | 777 | <p>You can change the way that Lua compares tables and userdata |
| 773 | | −using the "eq" metamethod (see <a href="#metatable">2.8</a>). |
| 778 | +by using the "eq" metamethod (see <a href="#metatable">2.8</a>). |
| 774 | 779 | |
| 775 | 780 | <p>The conversion rules of <a href="#coercion">2.2.1</a> |
| 776 | 781 | <em>do not</em> apply to equality comparisons. |
| @@ -799,27 +804,29 @@ all logical operators consider both <b>false</b> and <b>nil</b> as false · 22 unmodified lines |
| 799 | 804 | and anything else as true. |
| 800 | 805 | |
| 801 | 806 | |
| 802 | | −<p>The operator <b>not</b> always returns <b>false</b> or <b>true</b>. |
| 803 | | − |
| 804 | | −<p>The conjunction operator <b>and</b> returns its first argument |
| 807 | +<p>The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. |
| 808 | +The conjunction operator <b>and</b> returns its first argument |
| 805 | 809 | if this value is <b>false</b> or <b>nil</b>; |
| 806 | 810 | otherwise, <b>and</b> returns its second argument. |
| 807 | 811 | The disjunction operator <b>or</b> returns its first argument |
| 808 | 812 | if this value is different from <b>nil</b> and <b>false</b>; |
| 809 | 813 | otherwise, <b>or</b> returns its second argument. |
| 810 | | −Both <b>and</b> and <b>or</b> use short-cut evaluation, |
| 814 | +Both <b>and</b> and <b>or</b> use short-cut evaluation; |
| 811 | 815 | that is, |
| 812 | 816 | the second operand is evaluated only if necessary. |
| 813 | | −For example, |
| 817 | +Here are some examples: |
| 814 | 818 | <pre> |
| 815 | | − 10 or error() -> 10 |
| 816 | | − nil or "a" -> "a" |
| 817 | | − nil and 10 -> nil |
| 818 | | − false and error() -> false |
| 819 | | − false and nil -> false |
| 820 | | − false or nil -> nil |
| 821 | | − 10 and 20 -> 20 |
| 819 | + 10 or 20 --> 10 |
| 820 | + 10 or error() --> 10 |
| 821 | + nil or "a" --> "a" |
| 822 | + nil and 10 --> nil |
| 823 | + false and error() --> false |
| 824 | + false and nil --> false |
| 825 | + false or nil --> nil |
| 826 | + 10 and 20 --> 20 |
| 822 | 827 | </pre> |
| 828 | +(Here and in the sequel, |
| 829 | +`<code>--></code>´ indicates the result of the preceding expression.) |
| 823 | 830 | |
| 824 | 831 | <p><a name="concat"></a><a name="2.5.4"></a><h3>2.5.4 - Concatenation</h3> |
| 825 | 832 | The string concatenation operator in Lua is |
| @@ -830,21 +837,22 @@ Otherwise, the "concat" metamethod is called (see <a href="#metatable">2.8</a>). · 4 unmodified lines |
| 830 | 837 | |
| 831 | 838 | <p><a name="len-op"></a><a name="2.5.5"></a><h3>2.5.5 - The Length Operator</h3> |
| 832 | 839 | |
| 833 | | −<p>The length operator is denoted by the prefix <code>#</code>. |
| 840 | +<p>The length operator is denoted by the unary operator <code>#</code>. |
| 834 | 841 | The length of a string is its number of bytes |
| 835 | 842 | (that is, the usual meaning of string length when each |
| 836 | 843 | character is one byte). |
| 837 | | −The length of a table <code>t</code> is defined to be any |
| 844 | + |
| 845 | +<p>The length of a table <code>t</code> is defined to be any |
| 838 | 846 | integer index <code>n</code> |
| 839 | 847 | such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; |
| 840 | 848 | moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> may be zero. |
| 841 | | − |
| 842 | | −<p>For a regular array, with non-nil values from 1 to a given <code>n</code>, |
| 849 | +For a regular array, with non-nil values from 1 to a given <code>n</code>, |
| 843 | 850 | its length is exactly that <code>n</code>, |
| 844 | 851 | the index of its last value. |
| 845 | 852 | If the array has "holes" |
| 846 | 853 | (that is, <b>nil</b> values between other non-nil values), |
| 847 | | −then <code>#t</code> may be any of the indices that precede a <b>nil</b> value |
| 854 | +then <code>#t</code> may be any of the indices that |
| 855 | +directly precedes a <b>nil</b> value |
| 848 | 856 | (that is, it may consider any such <b>nil</b> value as the end of |
| 849 | 857 | the array). |
| 850 | 858 | |
| @@ -861,7 +869,8 @@ from lower to higher priority: · 10 unmodified lines |
| 861 | 869 | not # - (unary) |
| 862 | 870 | ^ |
| 863 | 871 | </pre> |
| 864 | | −You can use parentheses to change the precedences of an expression. |
| 872 | +As usual, |
| 873 | +you can use parentheses to change the precedences of an expression. |
| 865 | 874 | The concatenation (`<code>..</code>´) and exponentiation (`<code>^</code>´) |
| 866 | 875 | operators are right associative. |
| 867 | 876 | All other binary operators are left associative. |
| @@ -889,20 +898,20 @@ starting with 1. · 21 unmodified lines |
| 889 | 898 | Fields in the other formats do not affect this counting. |
| 890 | 899 | For example, |
| 891 | 900 | <pre> |
| 892 | | − a = {[f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45} |
| 901 | + a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } |
| 893 | 902 | </pre> |
| 894 | 903 | is equivalent to |
| 895 | 904 | <pre> |
| 896 | 905 | do |
| 897 | | − local temp = {} |
| 898 | | − temp[f(1)] = g |
| 899 | | − temp[1] = "x" -- 1st exp |
| 900 | | − temp[2] = "y" -- 2nd exp |
| 901 | | − temp.x = 1 -- temp["x"] = 1 |
| 902 | | − temp[3] = f(x) -- 3rd exp |
| 903 | | − temp[30] = 23 |
| 904 | | − temp[4] = 45 -- 4th exp |
| 905 | | − a = temp |
| 906 | + local t = {} |
| 907 | + t[f(1)] = g |
| 908 | + t[1] = "x" -- 1st exp |
| 909 | + t[2] = "y" -- 2nd exp |
| 910 | + t.x = 1 -- t["x"] = 1 |
| 911 | + t[3] = f(x) -- 3rd exp |
| 912 | + t[30] = 23 |
| 913 | + t[4] = 45 -- 4th exp |
| 914 | + a = t |
| 906 | 915 | end |
| 907 | 916 | </pre> |
| 908 | 917 | |
| @@ -927,7 +936,7 @@ first <em>prefixexp</em> and <em>args</em> are evaluated. · 18 unmodified lines |
| 927 | 936 | If the value of <em>prefixexp</em> has type <em>function</em>, |
| 928 | 937 | then that function is called |
| 929 | 938 | with the given arguments. |
| 930 | | −Otherwise, its "call" metamethod is called, |
| 939 | +Otherwise, the <em>prefixexp</em> "call" metamethod is called, |
| 931 | 940 | having as first parameter the value of <em>prefixexp</em>, |
| 932 | 941 | followed by the original call arguments |
| 933 | 942 | (see <a href="#metatable">2.8</a>). |
| @@ -945,16 +954,14 @@ except that <code>v</code> is evaluated only once. · 11 unmodified lines |
| 945 | 954 | <pre> |
| 946 | 955 | args ::= `<b>(</b>´ [explist1] `<b>)</b>´ |
| 947 | 956 | args ::= tableconstructor |
| 948 | | − args ::= Literal |
| 957 | + args ::= String |
| 949 | 958 | </pre> |
| 950 | 959 | All argument expressions are evaluated before the call. |
| 951 | | −A call of the form <code>f{...}</code> is syntactic sugar for |
| 952 | | −<code>f({...})</code>, that is, |
| 953 | | −the argument list is a single new table. |
| 960 | +A call of the form <code>f{...}</code> is syntactic sugar for <code>f({...})</code>; |
| 961 | +that is, the argument list is a single new table. |
| 954 | 962 | A call of the form <code>f'...'</code> |
| 955 | | −(or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for |
| 956 | | −<code>f('...')</code>, that is, |
| 957 | | −the argument list is a single literal string. |
| 963 | +(or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for <code>f('...')</code>; |
| 964 | +that is, the argument list is a single literal string. |
| 958 | 965 | |
| 959 | 966 | <p>As an exception to the free-format syntax of Lua, |
| 960 | 967 | you cannot put a line break before the `<code>(</code>´ in a function call. |
| @@ -964,7 +971,7 @@ If you write · 3 unmodified lines |
| 964 | 971 | a = f |
| 965 | 972 | (g).x(a) |
| 966 | 973 | </pre> |
| 967 | | −Lua would read that as <code>a = f(g).x(a)</code>. |
| 974 | +Lua would see that as a single statement, <code>a = f(g).x(a)</code>. |
| 968 | 975 | So, if you want two statements, you must add a semi-colon between them. |
| 969 | 976 | If you actually want to call <code>f</code>, |
| 970 | 977 | you must remove the line break before <code>(g)</code>. |
| @@ -981,15 +988,15 @@ However, a tail call erases any debug information about the · 10 unmodified lines |
| 981 | 988 | calling function. |
| 982 | 989 | Note that a tail call only happens with a particular syntax, |
| 983 | 990 | where the <b>return</b> has one single function call as argument; |
| 984 | | −this syntax makes the calling function returns exactly |
| 991 | +this syntax makes the calling function return exactly |
| 985 | 992 | the returns of the called function. |
| 986 | | −So, all the following examples are not tail calls: |
| 993 | +So, none of the following examples are tail calls: |
| 987 | 994 | <pre> |
| 988 | | − return (f(x)) -- results adjusted to 1 |
| 989 | | − return 2 * f(x) |
| 990 | | − return x, f(x) -- additional results |
| 991 | | − f(x); return -- results discarded |
| 992 | | − return x or f(x) -- results adjusted to 1 |
| 995 | + return (f(x)) -- results adjusted to 1 |
| 996 | + return 2 * f(x) |
| 997 | + return x, f(x) -- additional results |
| 998 | + f(x); return -- results discarded |
| 999 | + return x or f(x) -- results adjusted to 1 |
| 993 | 1000 | </pre> |
| 994 | 1001 | |
| 995 | 1002 | <p><a name="func-def"></a><a name="2.5.9"></a><h3>2.5.9 - Function Definitions</h3> |
| @@ -1030,6 +1037,12 @@ translates to · 34 unmodified lines |
| 1030 | 1037 | <pre> |
| 1031 | 1038 | local f; f = function () ... end |
| 1032 | 1039 | </pre> |
| 1040 | +<em>not</em> this: |
| 1041 | +<pre> |
| 1042 | + local f = function () ... end |
| 1043 | +</pre> |
| 1044 | +(This only makes a difference when the body of the function |
| 1045 | +contains references to <code>f</code>.) |
| 1033 | 1046 | |
| 1034 | 1047 | <p>A function definition is an executable expression, |
| 1035 | 1048 | whose value has type <em>function</em>. |
| @@ -1084,10 +1097,10 @@ to the vararg expression: · 48 unmodified lines |
| 1084 | 1097 | f(r(), 10) a=1, b=10 |
| 1085 | 1098 | f(r()) a=1, b=2 |
| 1086 | 1099 | |
| 1087 | | − g(3) a=3, b=nil, ... -> (nothing) |
| 1088 | | − g(3, 4) a=3, b=4, ... -> (nothing) |
| 1089 | | − g(3, 4, 5, 8) a=3, b=4, ... -> 5 8 |
| 1090 | | − g(5, r()) a=5, b=1, ... -> 2 3 |
| 1100 | + g(3) a=3, b=nil, ... --> (nothing) |
| 1101 | + g(3, 4) a=3, b=4, ... --> (nothing) |
| 1102 | + g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 |
| 1103 | + g(5, r()) a=5, b=1, ... --> 2 3 |
| 1091 | 1104 | </pre> |
| 1092 | 1105 | |
| 1093 | 1106 | <p>Results are returned using the <b>return</b> statement (see <a href="#control">2.4.4</a>). |
| @@ -1114,36 +1127,29 @@ is syntactic sugar for · 20 unmodified lines |
| 1114 | 1127 | The scope of variables begins at the first statement <em>after</em> |
| 1115 | 1128 | their declaration and lasts until the end of the innermost block that |
| 1116 | 1129 | includes the declaration. |
| 1117 | | −For instance: |
| 1118 | | −<pre> |
| 1119 | | − x = 10 -- global variable |
| 1120 | | − do -- new block |
| 1121 | | − local x = x -- new `x', with value 10 |
| 1122 | | − print(x) --> 10 |
| 1123 | | − x = x+1 |
| 1124 | | − do -- another block |
| 1125 | | − local x = x+1 -- another `x' |
| 1126 | | − print(x) --> 12 |
| 1127 | | − end |
| 1128 | | − print(x) --> 11 |
| 1129 | | − end |
| 1130 | | − print(x) --> 10 (the global one) |
| 1130 | +Consider the following example: |
| 1131 | +<pre> |
| 1132 | + x = 10 -- global variable |
| 1133 | + do -- new block |
| 1134 | + local x = x -- new `x', with value 10 |
| 1135 | + print(x) --> 10 |
| 1136 | + x = x+1 |
| 1137 | + do -- another block |
| 1138 | + local x = x+1 -- another `x' |
| 1139 | + print(x) --> 12 |
| 1140 | + end |
| 1141 | + print(x) --> 11 |
| 1142 | + end |
| 1143 | + print(x) --> 10 (the global one) |
| 1131 | 1144 | </pre> |
| 1132 | | −Notice that, in a declaration like <code>local x = x</code>, |
| 1145 | + |
| 1146 | +<p>Notice that, in a declaration like <code>local x = x</code>, |
| 1133 | 1147 | the new <code>x</code> being declared is not in scope yet, |
| 1134 | 1148 | and so the second <code>x</code> refers to the outside variable. |
| 1135 | 1149 | |
| 1136 | 1150 | <p>Because of the lexical scoping rules, |
| 1137 | 1151 | local variables can be freely accessed by functions |
| 1138 | 1152 | defined inside their scope. |
| 1139 | | −For instance: |
| 1140 | | −<pre> |
| 1141 | | − local counter = 0 |
| 1142 | | − function inc (x) |
| 1143 | | − counter = counter + x |
| 1144 | | − return counter |
| 1145 | | − end |
| 1146 | | −</pre> |
| 1147 | 1153 | A local variable used by an inner function is called |
| 1148 | 1154 | an <em>upvalue</em>, or <em>external local variable</em>, |
| 1149 | 1155 | inside the inner function. |
| @@ -1152,12 +1158,12 @@ inside the inner function. · 2 unmodified lines |
| 1152 | 1158 | defines new local variables. |
| 1153 | 1159 | Consider the following example: |
| 1154 | 1160 | <pre> |
| 1155 | | − a = {} |
| 1156 | | − local x = 20 |
| 1157 | | − for i=1,10 do |
| 1158 | | − local y = 0 |
| 1159 | | − a[i] = function () y=y+1; return x+y end |
| 1160 | | − end |
| 1161 | + a = {} |
| 1162 | + local x = 20 |
| 1163 | + for i=1,10 do |
| 1164 | + local y = 0 |
| 1165 | + a[i] = function () y=y+1; return x+y end |
| 1166 | + end |
| 1161 | 1167 | </pre> |
| 1162 | 1168 | The loop creates ten closures |
| 1163 | 1169 | (that is, ten instances of the anonymous function). |
| @@ -1166,13 +1172,13 @@ while all of them share the same <code>x</code>. · 2 unmodified lines |
| 1166 | 1172 | |
| 1167 | 1173 | <p><a name="error"></a><a name="2.7"></a><h2>2.7 - Error Handling</h2> |
| 1168 | 1174 | |
| 1169 | | −<p>Because Lua is an extension language, |
| 1175 | +<p>Because Lua is an embedded extension language, |
| 1170 | 1176 | all Lua actions start from C code in the host program |
| 1171 | 1177 | calling a function from the Lua library (see <a href="#lua_pcall"></a>). |
| 1172 | 1178 | Whenever an error occurs during Lua compilation or execution, |
| 1173 | 1179 | control returns to C, |
| 1174 | 1180 | which can take appropriate measures |
| 1175 | | −(such as print an error message). |
| 1181 | +(such as printing an error message). |
| 1176 | 1182 | |
| 1177 | 1183 | <p>Lua code can explicitly generate an error by calling the |
| 1178 | 1184 | <a href="#pdf-error"><code>error</code></a> function. |
| @@ -1215,7 +1221,7 @@ So, there is one single metatable for all numbers, · 36 unmodified lines |
| 1215 | 1221 | and for all strings, etc. |
| 1216 | 1222 | |
| 1217 | 1223 | <p>A metatable may control how an object behaves in arithmetic operations, |
| 1218 | | −order comparisons, concatenation, and indexing. |
| 1224 | +order comparisons, concatenation, length operation, and indexing. |
| 1219 | 1225 | A metatable can also define a function to be called when a userdata |
| 1220 | 1226 | is garbage collected. |
| 1221 | 1227 | For each of those operations Lua associates a specific key |
| @@ -1228,7 +1234,7 @@ controls how Lua will perform the operation. · 6 unmodified lines |
| 1228 | 1234 | <p>Metatables control the operations listed next. |
| 1229 | 1235 | Each operation is identified by its corresponding name. |
| 1230 | 1236 | The key for each operation is a string with its name prefixed by |
| 1231 | | −two underscores; |
| 1237 | +two underscores, `<code>__</code>´; |
| 1232 | 1238 | for instance, the key for operation "add" is the |
| 1233 | 1239 | string <code>"__add"</code>. |
| 1234 | 1240 | The semantics of these operations is better explained by a Lua function |
| @@ -1243,11 +1249,11 @@ are described in <a href="#predefined">5.1</a>. · 8 unmodified lines |
| 1243 | 1249 | In particular, to retrieve the metamethod of a given object, |
| 1244 | 1250 | we use the expression |
| 1245 | 1251 | <pre> |
| 1246 | | − metatable(obj)[event] |
| 1252 | + metatable(obj)[event] |
| 1247 | 1253 | </pre> |
| 1248 | 1254 | This should be read as |
| 1249 | 1255 | <pre> |
| 1250 | | − rawget(metatable(obj) or {}, event) |
| 1256 | + rawget(getmetatable(obj) or {}, event) |
| 1251 | 1257 | </pre> |
| 1252 | 1258 | That is, the access to a metamethod does not invoke other metamethods, |
| 1253 | 1259 | and the access to objects with no metatables does not fail |
| @@ -1522,11 +1528,11 @@ called when Lua calls a value. · 268 unmodified lines |
| 1522 | 1528 | <p>Besides metatables, |
| 1523 | 1529 | objects of types thread, function, and userdata |
| 1524 | 1530 | have another table associated with them, |
| 1525 | | −called <em>environment</em>. |
| 1531 | +called their <em>environment</em>. |
| 1526 | 1532 | Like metatables, environments are regular tables and |
| 1527 | 1533 | multiple objects can share the same environment. |
| 1528 | 1534 | |
| 1529 | | −<p>Environments associated with userdata has no meaning for Lua. |
| 1535 | +<p>Environments associated with userdata have no meaning for Lua. |
| 1530 | 1536 | It is only a feature for programmers to associate a table to |
| 1531 | 1537 | a userdata. |
| 1532 | 1538 | |
| @@ -1557,10 +1563,10 @@ use the C API. · 24 unmodified lines |
| 1557 | 1563 | |
| 1558 | 1564 | <p><a name="GC"></a><a name="2.10"></a><h2>2.10 - Garbage Collection</h2> |
| 1559 | 1565 | |
| 1560 | | −<p>Lua does automatic memory management. |
| 1566 | +<p>Lua performs automatic memory management. |
| 1561 | 1567 | That means that |
| 1562 | 1568 | you do not have to worry about allocating memory for new objects |
| 1563 | | −and freeing it when the objects are no longer needed. |
| 1569 | +not about freeing it when the objects are no longer needed. |
| 1564 | 1570 | Lua manages memory automatically by running |
| 1565 | 1571 | a <em>garbage collector</em> from time to time |
| 1566 | 1572 | to collect all <em>dead objects</em> |
| @@ -1568,9 +1574,12 @@ to collect all <em>dead objects</em> · 1 unmodified line |
| 1568 | 1574 | All objects in Lua are subject to automatic management: |
| 1569 | 1575 | tables, userdata, functions, threads, and strings. |
| 1570 | 1576 | |
| 1571 | | −<p>Lua 5.1 implements an incremental mark-and-sweep collector. |
| 1572 | | −It uses two numbers to control its garbage-collection cycles. |
| 1573 | | −One number, the <em>garbage-collector pause</em>, |
| 1577 | +<p>Lua implements an incremental mark-and-sweep collector. |
| 1578 | +It uses two numbers to control its garbage-collection cycles: |
| 1579 | +the <em>garbage-collector pause</em> and |
| 1580 | +the <em>garbage-collector multiplier</em>. |
| 1581 | + |
| 1582 | +<p>The garbage-collector pause |
| 1574 | 1583 | controls how long the collector waits before starting a new cycle. |
| 1575 | 1584 | Larger values make the collector less aggressive. |
| 1576 | 1585 | Values smaller than 1 mean the collector will not wait to |
| @@ -1578,7 +1587,7 @@ start a new cycle. · 1 unmodified line |
| 1578 | 1587 | A value of 2 means that the collector waits more or less to double |
| 1579 | 1588 | the total memory in use before starting a new cycle. |
| 1580 | 1589 | |
| 1581 | | −<p>The other number, the <em>garbage-collector multiplier</em>, |
| 1590 | +<p>The garbage-collector multiplier |
| 1582 | 1591 | controls the relative speed of the collector relative to |
| 1583 | 1592 | memory allocation. |
| 1584 | 1593 | Larger values make the collector more aggressive but also increases |
| @@ -1605,7 +1614,7 @@ with external resource management · 20 unmodified lines |
| 1605 | 1614 | (such as closing files, network or database connections, |
| 1606 | 1615 | or freeing your own memory). |
| 1607 | 1616 | |
| 1608 | | −<p>Free userdata with a field <code>__gc</code> in their metatables are not |
| 1617 | +<p>Garbage userdata with a field <code>__gc</code> in their metatables are not |
| 1609 | 1618 | collected immediately by the garbage collector. |
| 1610 | 1619 | Instead, Lua puts them in a list. |
| 1611 | 1620 | After the collection, |
| @@ -1676,8 +1685,8 @@ passing as its first argument · 64 unmodified lines |
| 1676 | 1685 | the thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, |
| 1677 | 1686 | the coroutine starts its execution, |
| 1678 | 1687 | at the first line of its main function. |
| 1679 | | −Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are given as |
| 1680 | | −parameters for the coroutine main function. |
| 1688 | +Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on |
| 1689 | +to the coroutine main function. |
| 1681 | 1690 | After the coroutine starts running, |
| 1682 | 1691 | it runs until it terminates or <em>yields</em>. |
| 1683 | 1692 | |
| @@ -1703,43 +1712,39 @@ it continues its execution from the point where it yielded, · 19 unmodified lines |
| 1703 | 1712 | with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra |
| 1704 | 1713 | arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. |
| 1705 | 1714 | |
| 1706 | | −<p>The <code>coroutine.wrap</code> function creates a coroutine |
| 1707 | | −like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, |
| 1715 | +<p>The <code>coroutine.wrap</code> function creates a coroutine, |
| 1716 | +just like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, |
| 1708 | 1717 | but instead of returning the coroutine itself, |
| 1709 | 1718 | it returns a function that, when called, resumes the coroutine. |
| 1710 | 1719 | Any arguments passed to that function |
| 1711 | | −go as extra arguments to resume. |
| 1712 | | −The function returns all the values returned by resume, |
| 1720 | +go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. |
| 1721 | +<code>coroutine.wrap</code> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, |
| 1713 | 1722 | except the first one (the boolean error code). |
| 1714 | 1723 | Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, |
| 1715 | | −this function does not catch errors; |
| 1724 | +<code>coroutine.wrap</code> does not catch errors; |
| 1716 | 1725 | any error is propagated to the caller. |
| 1717 | 1726 | |
| 1718 | 1727 | <p>As an example, |
| 1719 | 1728 | consider the next code: |
| 1720 | 1729 | <pre> |
| 1721 | | −function foo1 (a) |
| 1730 | +function foo (a) |
| 1722 | 1731 | print("foo", a) |
| 1723 | 1732 | return coroutine.yield(2*a) |
| 1724 | 1733 | end |
| 1725 | 1734 | |
| 1726 | 1735 | co = coroutine.create(function (a,b) |
| 1727 | 1736 | print("co-body", a, b) |
| 1728 | | − local r = foo1(a+1) |
| 1737 | + local r = foo(a+1) |
| 1729 | 1738 | print("co-body", r) |
| 1730 | 1739 | local r, s = coroutine.yield(a+b, a-b) |
| 1731 | 1740 | print("co-body", r, s) |
| 1732 | 1741 | return b, "end" |
| 1733 | 1742 | end) |
| 1734 | 1743 | |
| 1735 | | −a, b = coroutine.resume(co, 1, 10) |
| 1736 | | −print("main", a, b) |
| 1737 | | −a, b, c = coroutine.resume(co, "r") |
| 1738 | | −print("main", a, b, c) |
| 1739 | | −a, b, c = coroutine.resume(co, "x", "y") |
| 1740 | | −print("main", a, b, c) |
| 1741 | | −a, b = coroutine.resume(co, "x", "y") |
| 1742 | | −print("main", a, b) |
| 1744 | +print("main", coroutine.resume(co, 1, 10)) |
| 1745 | +print("main", coroutine.resume(co, "r")) |
| 1746 | +print("main", coroutine.resume(co, "x", "y")) |
| 1747 | +print("main", coroutine.resume(co, "x", "y")) |
| 1743 | 1748 | </pre> |
| 1744 | 1749 | When you run it, it produces the following output: |
| 1745 | 1750 | <pre> |
| @@ -1767,10 +1772,10 @@ are declared in the header file <code>lua.h</code>. · 21 unmodified lines |
| 1767 | 1772 | any facility in the API may be provided as a macro instead. |
| 1768 | 1773 | All such macros use each of its arguments exactly once |
| 1769 | 1774 | (except for the first argument, which is always a Lua state), |
| 1770 | | −and so do not generate hidden side-effects. |
| 1775 | +and so do not generate any hidden side-effects. |
| 1771 | 1776 | |
| 1772 | | −<p>Like in most C libraries, |
| 1773 | | −the Lua API functions do not check their arguments. |
| 1777 | +<p>As in most C libraries, |
| 1778 | +the Lua API functions do not check their arguments for validity or consistency. |
| 1774 | 1779 | However, you can change this behavior by compiling Lua |
| 1775 | 1780 | with a proper definition for the macro <code>luai_apicheck</code>, |
| 1776 | 1781 | in file <code>luaconf.h</code>. |
| @@ -1784,7 +1789,7 @@ Each element in this stack represents a Lua value · 7 unmodified lines |
| 1784 | 1789 | <p>Whenever Lua calls C, the called function gets a new stack, |
| 1785 | 1790 | which is independent of previous stacks and of stacks of |
| 1786 | 1791 | C functions that are still active. |
| 1787 | | −That stack initially contains any arguments to the C function, |
| 1792 | +That stack initially contains any arguments to the C function |
| 1788 | 1793 | and it is where the C function pushes its results |
| 1789 | 1794 | to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). |
| 1790 | 1795 | |
| @@ -1794,7 +1799,7 @@ Instead, they can refer to any element in the stack · 3 unmodified lines |
| 1794 | 1799 | by using an <em>index</em>: |
| 1795 | 1800 | A positive index represents an <em>absolute</em> stack position |
| 1796 | 1801 | (starting at 1); |
| 1797 | | −a negative index represents an <em>offset</em> from the top of the stack. |
| 1802 | +a negative index represents an <em>offset</em> relative to the top of the stack. |
| 1798 | 1803 | More specifically, if the stack has <em>n</em> elements, |
| 1799 | 1804 | then index 1 represents the first element |
| 1800 | 1805 | (that is, the element that was pushed onto the stack first) |
| @@ -1811,6 +1816,8 @@ if it lies between 1 and the stack top · 10 unmodified lines |
| 1811 | 1816 | <p><a name="3.2"></a><h2>3.2 - Stack Size</h2> |
| 1812 | 1817 | |
| 1813 | 1818 | <p>When you interact with Lua API, |
| 1819 | +you are responsible for ensuring consistency. |
| 1820 | +In particular, |
| 1814 | 1821 | <em>you are responsible for controlling stack overflow</em>. |
| 1815 | 1822 | You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> |
| 1816 | 1823 | to grow the stack size. |
| @@ -1828,7 +1835,7 @@ Such indices are called <em>acceptable indices</em>. · 11 unmodified lines |
| 1828 | 1835 | More formally, we define an <em>acceptable index</em> |
| 1829 | 1836 | as follows: |
| 1830 | 1837 | <pre> |
| 1831 | | − (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) |
| 1838 | + (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) |
| 1832 | 1839 | </pre> |
| 1833 | 1840 | Note that 0 is never an acceptable index. |
| 1834 | 1841 | |
| @@ -1837,8 +1844,8 @@ Note that 0 is never an acceptable index. · 2 unmodified lines |
| 1837 | 1844 | <p>Unless otherwise noted, |
| 1838 | 1845 | any function that accepts valid indices can also be called with |
| 1839 | 1846 | <em>pseudo-indices</em>, |
| 1840 | | −which represent some Lua values that are accessible to the C code |
| 1841 | | −but are not in the stack. |
| 1847 | +which represent some Lua values that are accessible to C code |
| 1848 | +but which are not in the stack. |
| 1842 | 1849 | Pseudo-indices are used to access the thread environment, |
| 1843 | 1850 | the function environment, |
| 1844 | 1851 | the registry, |
| @@ -1861,11 +1868,12 @@ For instance, to access the value of a global variable, do · 16 unmodified lines |
| 1861 | 1868 | <p>When a C function is created, |
| 1862 | 1869 | it is possible to associate some values with it, |
| 1863 | 1870 | thus creating a <em>C closure</em>; |
| 1864 | | −these values are then accessible to the function whenever it is called |
| 1871 | +these values are called <em>upvalues</em> and are |
| 1872 | +accessible to the function whenever it is called |
| 1865 | 1873 | (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). |
| 1866 | 1874 | |
| 1867 | 1875 | <p>Whenever a C function is called, |
| 1868 | | −its associated values are located at specific pseudo-indices. |
| 1876 | +its upvalues are located at specific pseudo-indices. |
| 1869 | 1877 | Those pseudo-indices are produced by the macro |
| 1870 | 1878 | <code>lua_upvalueindex</code>. |
| 1871 | 1879 | The first value associated with a function is at position |
| @@ -1877,13 +1885,14 @@ produces an acceptable (but invalid) index. · 5 unmodified lines |
| 1877 | 1885 | |
| 1878 | 1886 | <p><a name="registry"></a><a name="3.5"></a><h2>3.5 - Registry</h2> |
| 1879 | 1887 | |
| 1880 | | −<p>Lua provides a registry, |
| 1888 | +<p>Lua provides a <em>registry</em>, |
| 1881 | 1889 | a pre-defined table that can be used by any C code to |
| 1882 | 1890 | store whatever Lua value it needs to store. |
| 1883 | 1891 | This table is always located at pseudo-index |
| 1884 | 1892 | <code>LUA_REGISTRYINDEX</code>. |
| 1885 | 1893 | Any C library can store data into this table, |
| 1886 | | −as long as it chooses keys different from other libraries. |
| 1894 | +but it should take care to choose keys different from those used |
| 1895 | +by other libraries, to avoid collisions. |
| 1887 | 1896 | Typically, you should use as key a string containing your library name |
| 1888 | 1897 | or a light userdata with the address of a C object in your code. |
| 1889 | 1898 | |
| @@ -1894,9 +1903,13 @@ and therefore should not be used by other purposes. · 4 unmodified lines |
| 1894 | 1903 | <p><a name="3.6"></a><h2>3.6 - Error Handling in C</h2> |
| 1895 | 1904 | |
| 1896 | 1905 | <p>Internally, Lua uses the C <code>longjmp</code> facility to handle errors. |
| 1906 | +(You can also choose to use exceptions if you use C++; |
| 1907 | +See file <code>luaconf.h</code>.) |
| 1897 | 1908 | When Lua faces any error |
| 1898 | | −(such as memory allocation errors, type errors, syntax errors) |
| 1899 | | −it <em>raises</em> an error, that is, it does a long jump. |
| 1909 | +(such as memory allocation errors, type errors, syntax errors, |
| 1910 | +and runtime errors) |
| 1911 | +it <em>raises</em> an error; |
| 1912 | +that is, it does a long jump. |
| 1900 | 1913 | A <em>protected environment</em> uses <code>setjmp</code> |
| 1901 | 1914 | to set a recover point; |
| 1902 | 1915 | any error jumps to the most recent active recover point. |
| @@ -1909,7 +1922,7 @@ so they never raise an error: · 6 unmodified lines |
| 1909 | 1922 | <a href="#lua_newstate"><code>lua_newstate</code></a>, <a href="#lua_close"><code>lua_close</code></a>, <a href="#lua_load"><code>lua_load</code></a>, |
| 1910 | 1923 | <a href="#lua_pcall"><code>lua_pcall</code></a>, and <a href="#lua_cpcall"><code>lua_cpcall</code></a>. |
| 1911 | 1924 | |
| 1912 | | −<p>Inside a C function you can raise an error calling <a href="#lua_error"><code>lua_error</code></a>. |
| 1925 | +<p>Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. |
| 1913 | 1926 | |
| 1914 | 1927 | <p><a name="3.7"></a><h2>3.7 - Functions and Types</h2> |
| 1915 | 1928 | |
| @@ -1917,7 +1930,7 @@ so they never raise an error: · 1 unmodified line |
| 1917 | 1930 | alphabetical order. |
| 1918 | 1931 | |
| 1919 | 1932 | <p><a name="lua_Alloc"></a> |
| 1920 | | −<hr/><h3><code>lua_Alloc</code></h3> |
| 1933 | +<hr /><h3><code>lua_Alloc</code></h3> |
| 1921 | 1934 | <pre> |
| 1922 | 1935 | typedef void * (*lua_Alloc) (void *ud, |
| 1923 | 1936 | void *ptr, |
| @@ -1927,12 +1940,12 @@ alphabetical order. · 3 unmodified lines |
| 1927 | 1940 | </pre> |
| 1928 | 1941 | |
| 1929 | 1942 | |
| 1930 | | −<p>The allocator function used by Lua states. |
| 1943 | +<p>The type of the memory allocation function used by Lua states. |
| 1931 | 1944 | The allocator function must provide a |
| 1932 | 1945 | functionality similar to <code>realloc</code>, |
| 1933 | 1946 | but not exactly the same. |
| 1934 | | −Its arguments are <code>ud</code>, |
| 1935 | | −the opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; |
| 1947 | +Its arguments are |
| 1948 | +<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; |
| 1936 | 1949 | <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; |
| 1937 | 1950 | <code>osize</code>, the original size of the block; |
| 1938 | 1951 | <code>nsize</code>, the new size of the block. |
| @@ -1943,30 +1956,30 @@ it should free the block pointed by <code>ptr</code>. · 4 unmodified lines |
| 1943 | 1956 | When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> |
| 1944 | 1957 | if and only if it cannot fill the request. |
| 1945 | 1958 | When <code>nsize</code> is not zero and <code>osize</code> is zero, |
| 1946 | | −the allocator behaves like <code>malloc</code>. |
| 1959 | +the allocator should behave like <code>malloc</code>. |
| 1947 | 1960 | When <code>nsize</code> and <code>osize</code> are not zero, |
| 1948 | 1961 | the allocator behaves like <code>realloc</code>. |
| 1949 | 1962 | Lua assumes that the allocator never fails when |
| 1950 | 1963 | <code>osize >= nsize</code>. |
| 1951 | 1964 | |
| 1952 | | −<p>A simple implementation for the allocator function |
| 1953 | | −could be like this: |
| 1965 | +<p>Here is a simple implementation for the allocator function. |
| 1966 | +It is used in the auxiliary library by <a href="#lua_newstate"><code>lua_newstate</code></a>. |
| 1954 | 1967 | <pre> |
| 1955 | 1968 | static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { |
| 1956 | 1969 | (void)ud; /* not used */ |
| 1957 | 1970 | (void)osize; /* not used */ |
| 1958 | 1971 | if (nsize == 0) { |
| 1959 | | − free(ptr); /* ANSI ensures that free(NULL) has no effect */ |
| 1972 | + free(ptr); /* ANSI requires that free(NULL) has no effect */ |
| 1960 | 1973 | return NULL; |
| 1961 | 1974 | } |
| 1962 | 1975 | else |
| 1963 | | − /* ANSI ensures that realloc(NULL, size) == malloc(size) */ |
| 1976 | + /* ANSI requires that realloc(NULL, size) == malloc(size) */ |
| 1964 | 1977 | return realloc(ptr, nsize); |
| 1965 | 1978 | } |
| 1966 | 1979 | </pre> |
| 1967 | 1980 | |
| 1968 | 1981 | <p><a name="lua_atpanic"></a> |
| 1969 | | −<hr/><h3><code>lua_atpanic</code></h3> |
| 1982 | +<hr /><h3><code>lua_atpanic</code></h3> |
| 1970 | 1983 | <pre> |
| 1971 | 1984 | lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); |
| 1972 | 1985 | </pre> |
| @@ -1976,14 +1989,15 @@ static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { · 3 unmodified lines |
| 1976 | 1989 | |
| 1977 | 1990 | <p>If an error happens outside any protected environment, |
| 1978 | 1991 | Lua calls a <em>panic function</em> |
| 1979 | | −and then calls <code>exit(EXIT_FAILURE)</code>. |
| 1980 | | −Your new panic function may avoid the application exit by |
| 1992 | +and then calls <code>exit(EXIT_FAILURE)</code>, |
| 1993 | +thus exiting the host application. |
| 1994 | +Your panic function may avoid this exit by |
| 1981 | 1995 | never returning (e.g., doing a long jump). |
| 1982 | 1996 | |
| 1983 | 1997 | <p>The panic function can access the error message at the top of the stack. |
| 1984 | 1998 | |
| 1985 | 1999 | <p><a name="lua_call"></a> |
| 1986 | | −<hr/><h3><code>lua_call</code></h3> |
| 2000 | +<hr /><h3><code>lua_call</code></h3> |
| 1987 | 2001 | <pre> |
| 1988 | 2002 | void lua_call (lua_State *L, int nargs, int nresults); |
| 1989 | 2003 | </pre> |
| @@ -1994,18 +2008,20 @@ never returning (e.g., doing a long jump). · 4 unmodified lines |
| 1994 | 2008 | <p>To call a function you must use the following protocol: |
| 1995 | 2009 | First, the function to be called is pushed onto the stack; |
| 1996 | 2010 | then, the arguments to the function are pushed |
| 1997 | | −in direct order, that is, the first argument is pushed first. |
| 2011 | +in direct order; |
| 2012 | +that is, the first argument is pushed first. |
| 1998 | 2013 | Finally you call <a href="#lua_call"><code>lua_call</code></a>; |
| 1999 | 2014 | <code>nargs</code> is the number of arguments that you pushed onto the stack. |
| 2000 | | −All arguments and the function value are popped from the stack, |
| 2001 | | −and the function results are pushed. |
| 2002 | | −The number of results are adjusted to <code>nresults</code>, |
| 2015 | +All arguments and the function value are popped from the stack |
| 2016 | +when the function is called. |
| 2017 | +The function results are pushed onto the stack when the function returns. |
| 2018 | +The number of results is adjusted to <code>nresults</code>, |
| 2003 | 2019 | unless <code>nresults</code> is <code>LUA_MULTRET</code>. |
| 2004 | 2020 | In that case, <em>all</em> results from the function are pushed. |
| 2005 | 2021 | Lua takes care that the returned values fit into the stack space. |
| 2006 | 2022 | The function results are pushed onto the stack in direct order |
| 2007 | 2023 | (the first result is pushed first), |
| 2008 | | −so that after the call the last result is on the top. |
| 2024 | +so that after the call the last result is on the top of the stack. |
| 2009 | 2025 | |
| 2010 | 2026 | <p>Any error inside the called function is propagated upwards |
| 2011 | 2027 | (with a <code>longjmp</code>). |
| @@ -2017,21 +2033,21 @@ equivalent to this Lua code: · 5 unmodified lines |
| 2017 | 2033 | </pre> |
| 2018 | 2034 | Here it is in C: |
| 2019 | 2035 | <pre> |
| 2020 | | − lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* global `t' (for later use) */ |
| 2021 | 2036 | lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ |
| 2022 | 2037 | lua_pushstring(L, "how"); /* 1st argument */ |
| 2023 | | − lua_getfield(L, -3, "x"); /* push result of t.x (2nd arg) */ |
| 2038 | + lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ |
| 2039 | + lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ |
| 2040 | + lua_remove(L, -2); /* remove `t' from the stack */ |
| 2024 | 2041 | lua_pushinteger(L, 14); /* 3rd argument */ |
| 2025 | 2042 | lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ |
| 2026 | 2043 | lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global variable `a' */ |
| 2027 | | − lua_pop(L, 1); /* remove `t' from the stack */ |
| 2028 | 2044 | </pre> |
| 2029 | 2045 | Note that the code above is "balanced": |
| 2030 | 2046 | at its end, the stack is back to its original configuration. |
| 2031 | 2047 | This is considered good programming practice. |
| 2032 | 2048 | |
| 2033 | 2049 | <p><a name="lua_CFunction"></a> |
| 2034 | | −<hr/><h3><code>lua_CFunction</code></h3> |
| 2050 | +<hr /><h3><code>lua_CFunction</code></h3> |
| 2035 | 2051 | <pre> |
| 2036 | 2052 | typedef int (*lua_CFunction) (lua_State *L); |
| 2037 | 2053 | </pre> |
| @@ -2040,17 +2056,19 @@ This is considered good programming practice. · 2 unmodified lines |
| 2040 | 2056 | <p>Type for C functions. |
| 2041 | 2057 | |
| 2042 | 2058 | <p>In order to communicate properly with Lua, |
| 2043 | | −a C function must follow the following protocol, |
| 2059 | +a C function must use the following protocol, |
| 2044 | 2060 | which defines the way parameters and results are passed: |
| 2045 | 2061 | A C function receives its arguments from Lua in its stack |
| 2046 | 2062 | in direct order (the first argument is pushed first). |
| 2047 | 2063 | So, when the function starts, |
| 2048 | | −its first argument (if any) is at index 1. |
| 2064 | +<a href="#lua_gettop(L)"><code>lua_gettop(L)</code></a> returns the number of arguments received by the function. |
| 2065 | +The first argument (if any) is at index 1 |
| 2066 | +and its last argument is at index <a href="#lua_gettop(L)"><code>lua_gettop(L)</code></a>. |
| 2049 | 2067 | To return values to Lua, a C function just pushes them onto the stack, |
| 2050 | 2068 | in direct order (the first result is pushed first), |
| 2051 | 2069 | and returns the number of results. |
| 2052 | 2070 | Any other value in the stack below the results will be properly |
| 2053 | | −discharged by Lua. |
| 2071 | +discarded by Lua. |
| 2054 | 2072 | Like a Lua function, a C function called by Lua can also return |
| 2055 | 2073 | many results. |
| 2056 | 2074 | |
| @@ -2075,20 +2093,20 @@ of numerical arguments and returns their average and sum: · 18 unmodified lines |
| 2075 | 2093 | </pre> |
| 2076 | 2094 | |
| 2077 | 2095 | <p><a name="lua_checkstack"></a> |
| 2078 | | −<hr/><h3><code>lua_checkstack</code></h3> |
| 2096 | +<hr /><h3><code>lua_checkstack</code></h3> |
| 2079 | 2097 | <pre> |
| 2080 | 2098 | int lua_checkstack (lua_State *L, int extra); |
| 2081 | 2099 | </pre> |
| 2082 | 2100 | |
| 2083 | 2101 | |
| 2084 | | −<p>Grows the stack size to <code>top + extra</code> elements; |
| 2102 | +<p>Ensures that there are at least <code>extra</code> free stack slots in the stack. |
| 2085 | 2103 | it returns false if it cannot grow the stack to that size. |
| 2086 | 2104 | This function never shrinks the stack; |
| 2087 | 2105 | if the stack is already larger than the new size, |
| 2088 | 2106 | it is left unchanged. |
| 2089 | 2107 | |
| 2090 | 2108 | <p><a name="lua_close"></a> |
| 2091 | | −<hr/><h3><code>lua_close</code></h3> |
| 2109 | +<hr /><h3><code>lua_close</code></h3> |
| 2092 | 2110 | <pre> |
| 2093 | 2111 | void lua_close (lua_State *L); |
| 2094 | 2112 | </pre> |
| @@ -2105,7 +2123,7 @@ might need to release states as soon as they are not needed, · 10 unmodified lines |
| 2105 | 2123 | to avoid growing too large. |
| 2106 | 2124 | |
| 2107 | 2125 | <p><a name="lua_concat"></a> |
| 2108 | | −<hr/><h3><code>lua_concat</code></h3> |
| 2126 | +<hr /><h3><code>lua_concat</code></h3> |
| 2109 | 2127 | <pre> |
| 2110 | 2128 | void lua_concat (lua_State *L, int n); |
| 2111 | 2129 | </pre> |
| @@ -2120,7 +2138,7 @@ Concatenation is done following the usual semantics of Lua · 8 unmodified lines |
| 2120 | 2138 | (see <a href="#concat">2.5.4</a>). |
| 2121 | 2139 | |
| 2122 | 2140 | <p><a name="lua_cpcall"></a> |
| 2123 | | −<hr/><h3><code>lua_cpcall</code></h3> |
| 2141 | +<hr /><h3><code>lua_cpcall</code></h3> |
| 2124 | 2142 | <pre> |
| 2125 | 2143 | int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); |
| 2126 | 2144 | </pre> |
| @@ -2133,10 +2151,10 @@ In case of errors, · 6 unmodified lines |
| 2133 | 2151 | <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, |
| 2134 | 2152 | plus the error object on the top of the stack; |
| 2135 | 2153 | otherwise, it returns zero, and does not change the stack. |
| 2136 | | −Any value returned by <code>func</code> is discarded. |
| 2154 | +All values returned by <code>func</code> are discarded. |
| 2137 | 2155 | |
| 2138 | 2156 | <p><a name="lua_createtable"></a> |
| 2139 | | −<hr/><h3><code>lua_createtable</code></h3> |
| 2157 | +<hr /><h3><code>lua_createtable</code></h3> |
| 2140 | 2158 | <pre> |
| 2141 | 2159 | void lua_createtable (lua_State *L, int narr, int nrec); |
| 2142 | 2160 | </pre> |
| @@ -2144,25 +2162,26 @@ Any value returned by <code>func</code> is discarded. · 1 unmodified line |
| 2144 | 2162 | |
| 2145 | 2163 | <p>Creates a new empty table and pushes it onto the stack. |
| 2146 | 2164 | The new table has space pre-allocated |
| 2147 | | −for <code>narr</code> array elements plus <code>nrec</code> non-array elements. |
| 2165 | +for <code>narr</code> array elements and <code>nrec</code> non-array elements. |
| 2148 | 2166 | This pre-allocation is useful when you know exactly how many elements |
| 2149 | 2167 | the table will have. |
| 2150 | 2168 | Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. |
| 2151 | 2169 | |
| 2152 | 2170 | <p><a name="lua_dump"></a> |
| 2153 | | −<hr/><h3><code>lua_dump</code></h3> |
| 2171 | +<hr /><h3><code>lua_dump</code></h3> |
| 2154 | 2172 | <pre> |
| 2155 | 2173 | int lua_dump (lua_State *L, lua_Writer writer, void *data); |
| 2156 | 2174 | </pre> |
| 2157 | 2175 | |
| 2158 | 2176 | |
| 2159 | 2177 | <p>Dumps a function as a binary chunk. |
| 2160 | | −This function receives a Lua function on the top of the stack |
| 2178 | +Receives a Lua function on the top of the stack |
| 2161 | 2179 | and produces a binary chunk that, |
| 2162 | 2180 | if loaded again, |
| 2163 | 2181 | results in a function equivalent to the one dumped. |
| 2164 | 2182 | As it produces parts of the chunk, |
| 2165 | 2183 | <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) |
| 2184 | +with the given <code>data</code> |
| 2166 | 2185 | to write them. |
| 2167 | 2186 | |
| 2168 | 2187 | <p>The value returned is the error code returned by the last |
| @@ -2172,7 +2191,7 @@ call to the writer; · 3 unmodified lines |
| 2172 | 2191 | <p>This function does not pop the function from the stack. |
| 2173 | 2192 | |
| 2174 | 2193 | <p><a name="lua_equal"></a> |
| 2175 | | −<hr/><h3><code>lua_equal</code></h3> |
| 2194 | +<hr /><h3><code>lua_equal</code></h3> |
| 2176 | 2195 | <pre> |
| 2177 | 2196 | int lua_equal (lua_State *L, int index1, int index2); |
| 2178 | 2197 | </pre> |
| @@ -2183,23 +2202,24 @@ call to the writer; · 4 unmodified lines |
| 2183 | 2202 | following the semantics of the Lua <code>==</code> operator |
| 2184 | 2203 | (that is, may call metamethods). |
| 2185 | 2204 | Otherwise returns 0. |
| 2186 | | −Also returns 0 if any of the indices are non valid. |
| 2205 | +Also returns 0 if any of the indices is non valid. |
| 2187 | 2206 | |
| 2188 | 2207 | <p><a name="lua_error"></a> |
| 2189 | | −<hr/><h3><code>lua_error</code></h3> |
| 2208 | +<hr /><h3><code>lua_error</code></h3> |
| 2190 | 2209 | <pre> |
| 2191 | 2210 | int lua_error (lua_State *L); |
| 2192 | 2211 | </pre> |
| 2193 | 2212 | |
| 2194 | 2213 | |
| 2195 | 2214 | <p>Generates a Lua error. |
| 2196 | | −The error message (which actually can be any type of object) |
| 2215 | +The error message (which can actually be a Lua value of any type) |
| 2197 | 2216 | must be on the stack top. |
| 2198 | 2217 | This function does a long jump, |
| 2199 | 2218 | and therefore never returns. |
| 2219 | +(see <a href="#pdf-luaL_error"><code>luaL_error</code></a>). |
| 2200 | 2220 | |
| 2201 | 2221 | <p><a name="lua_gc"></a> |
| 2202 | | −<hr/><h3><code>lua_gc</code></h3> |
| 2222 | +<hr /><h3><code>lua_gc</code></h3> |
| 2203 | 2223 | <pre> |
| 2204 | 2224 | int lua_gc (lua_State *L, int what, int data); |
| 2205 | 2225 | </pre> |
| @@ -2227,28 +2247,28 @@ you must tune experimentally the value of <code>data</code>. · 21 unmodified lines |
| 2227 | 2247 | The function returns 1 if that step finished a |
| 2228 | 2248 | garbage-collection cycle. |
| 2229 | 2249 | <li> <code>LUA_GCSETPAUSE</code>--- |
| 2230 | | −sets <em><code>data</code>/100</em> as the new value |
| 2250 | +sets <code>data</code>/100 as the new value |
| 2231 | 2251 | for the <em>pause</em> of the collector (see <a href="#GC">2.10</a>). |
| 2232 | 2252 | The function returns the previous value of the pause. |
| 2233 | 2253 | <li> <code>LUA_GCSETSTEPMUL</code>--- |
| 2234 | | −sets <em><code>arg</code>/100</em> as the new value for the <em>step multiplier</em> of |
| 2254 | +sets <code>arg</code>/100 as the new value for the <em>step multiplier</em> of |
| 2235 | 2255 | the collector (see <a href="#GC">2.10</a>). |
| 2236 | 2256 | The function returns the previous value of the step multiplier. |
| 2237 | 2257 | </ul> |
| 2238 | 2258 | |
| 2239 | 2259 | <p><a name="lua_getallocf"></a> |
| 2240 | | −<hr/><h3><code>lua_getallocf</code></h3> |
| 2260 | +<hr /><h3><code>lua_getallocf</code></h3> |
| 2241 | 2261 | <pre> |
| 2242 | 2262 | lua_Alloc lua_getallocf (lua_State *L, void **ud); |
| 2243 | 2263 | </pre> |
| 2244 | 2264 | |
| 2245 | 2265 | |
| 2246 | | −<p>Returns the allocator function of a given state. |
| 2247 | | −If <code>ud</code> is not <code>NULL</code> Lua stores in <code>*ud</code> the |
| 2266 | +<p>Returns the memory allocator function of a given state. |
| 2267 | +If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the |
| 2248 | 2268 | opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. |
| 2249 | 2269 | |
| 2250 | 2270 | <p><a name="lua_getfenv"></a> |
| 2251 | | −<hr/><h3><code>lua_getfenv</code></h3> |
| 2271 | +<hr /><h3><code>lua_getfenv</code></h3> |
| 2252 | 2272 | <pre> |
| 2253 | 2273 | void lua_getfenv (lua_State *L, int index); |
| 2254 | 2274 | </pre> |
| @@ -2258,7 +2278,7 @@ opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. · 3 unmodified lines |
| 2258 | 2278 | the value at the given index. |
| 2259 | 2279 | |
| 2260 | 2280 | <p><a name="lua_getfield"></a> |
| 2261 | | −<hr/><h3><code>lua_getfield</code></h3> |
| 2281 | +<hr /><h3><code>lua_getfield</code></h3> |
| 2262 | 2282 | <pre> |
| 2263 | 2283 | void lua_getfield (lua_State *L, int index, const char *k); |
| 2264 | 2284 | </pre> |
| @@ -2270,7 +2290,7 @@ As in Lua, this function may trigger a metamethod · 5 unmodified lines |
| 2270 | 2290 | for the "index" event (see <a href="#metatable">2.8</a>). |
| 2271 | 2291 | |
| 2272 | 2292 | <p><a name="lua_getmetatable"></a> |
| 2273 | | −<hr/><h3><code>lua_getmetatable</code></h3> |
| 2293 | +<hr /><h3><code>lua_getmetatable</code></h3> |
| 2274 | 2294 | <pre> |
| 2275 | 2295 | int lua_getmetatable (lua_State *L, int index); |
| 2276 | 2296 | </pre> |
| @@ -2283,7 +2303,7 @@ or if the value does not have a metatable, · 6 unmodified lines |
| 2283 | 2303 | returns 0 and pushes nothing on the stack. |
| 2284 | 2304 | |
| 2285 | 2305 | <p><a name="lua_gettable"></a> |
| 2286 | | −<hr/><h3><code>lua_gettable</code></h3> |
| 2306 | +<hr /><h3><code>lua_gettable</code></h3> |
| 2287 | 2307 | <pre> |
| 2288 | 2308 | void lua_gettable (lua_State *L, int index); |
| 2289 | 2309 | </pre> |
| @@ -2299,7 +2319,7 @@ As in Lua, this function may trigger a metamethod · 9 unmodified lines |
| 2299 | 2319 | for the "index" event (see <a href="#metatable">2.8</a>). |
| 2300 | 2320 | |
| 2301 | 2321 | <p><a name="lua_gettop"></a> |
| 2302 | | −<hr/><h3><code>lua_gettop</code></h3> |
| 2322 | +<hr /><h3><code>lua_gettop</code></h3> |
| 2303 | 2323 | <pre> |
| 2304 | 2324 | int lua_gettop (lua_State *L); |
| 2305 | 2325 | </pre> |
| @@ -2311,7 +2331,7 @@ that result is equal to the number of elements in the stack · 5 unmodified lines |
| 2311 | 2331 | (and so 0 means an empty stack). |
| 2312 | 2332 | |
| 2313 | 2333 | <p><a name="lua_insert"></a> |
| 2314 | | −<hr/><h3><code>lua_insert</code></h3> |
| 2334 | +<hr /><h3><code>lua_insert</code></h3> |
| 2315 | 2335 | <pre> |
| 2316 | 2336 | void lua_insert (lua_State *L, int index); |
| 2317 | 2337 | </pre> |
| @@ -2323,7 +2343,7 @@ Cannot be called with a pseudo-index, · 5 unmodified lines |
| 2323 | 2343 | because a pseudo-index is not an actual stack position. |
| 2324 | 2344 | |
| 2325 | 2345 | <p><a name="lua_Integer"></a> |
| 2326 | | −<hr/><h3><code>lua_Integer</code></h3> |
| 2346 | +<hr /><h3><code>lua_Integer</code></h3> |
| 2327 | 2347 | <pre> |
| 2328 | 2348 | typedef ptrdiff_t lua_Integer; |
| 2329 | 2349 | </pre> |
| @@ -2332,11 +2352,11 @@ because a pseudo-index is not an actual stack position. · 2 unmodified lines |
| 2332 | 2352 | <p>The type used by the Lua API to represent integral values. |
| 2333 | 2353 | |
| 2334 | 2354 | <p>By default it is a <code>ptrdiff_t</code>, |
| 2335 | | −which is usually the largest type the machine handles |
| 2355 | +which is usually the largest integral type the machine handles |
| 2336 | 2356 | "comfortably". |
| 2337 | 2357 | |
| 2338 | 2358 | <p><a name="lua_isboolean"></a> |
| 2339 | | −<hr/><h3><code>lua_isboolean</code></h3> |
| 2359 | +<hr /><h3><code>lua_isboolean</code></h3> |
| 2340 | 2360 | <pre> |
| 2341 | 2361 | int lua_isboolean (lua_State *L, int index); |
| 2342 | 2362 | </pre> |
| @@ -2346,7 +2366,7 @@ which is usually the largest type the machine handles · 3 unmodified lines |
| 2346 | 2366 | and 0 otherwise. |
| 2347 | 2367 | |
| 2348 | 2368 | <p><a name="lua_iscfunction"></a> |
| 2349 | | −<hr/><h3><code>lua_iscfunction</code></h3> |
| 2369 | +<hr /><h3><code>lua_iscfunction</code></h3> |
| 2350 | 2370 | <pre> |
| 2351 | 2371 | int lua_iscfunction (lua_State *L, int index); |
| 2352 | 2372 | </pre> |
| @@ -2356,7 +2376,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2356 | 2376 | and 0 otherwise. |
| 2357 | 2377 | |
| 2358 | 2378 | <p><a name="lua_isfunction"></a> |
| 2359 | | −<hr/><h3><code>lua_isfunction</code></h3> |
| 2379 | +<hr /><h3><code>lua_isfunction</code></h3> |
| 2360 | 2380 | <pre> |
| 2361 | 2381 | int lua_isfunction (lua_State *L, int index); |
| 2362 | 2382 | </pre> |
| @@ -2366,7 +2386,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2366 | 2386 | (either C or Lua), and 0 otherwise. |
| 2367 | 2387 | |
| 2368 | 2388 | <p><a name="lua_islightuserdata"></a> |
| 2369 | | −<hr/><h3><code>lua_islightuserdata</code></h3> |
| 2389 | +<hr /><h3><code>lua_islightuserdata</code></h3> |
| 2370 | 2390 | <pre> |
| 2371 | 2391 | int lua_islightuserdata (lua_State *L, int index); |
| 2372 | 2392 | </pre> |
| @@ -2376,7 +2396,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2376 | 2396 | and 0 otherwise. |
| 2377 | 2397 | |
| 2378 | 2398 | <p><a name="lua_isnil"></a> |
| 2379 | | −<hr/><h3><code>lua_isnil</code></h3> |
| 2399 | +<hr /><h3><code>lua_isnil</code></h3> |
| 2380 | 2400 | <pre> |
| 2381 | 2401 | int lua_isnil (lua_State *L, int index); |
| 2382 | 2402 | </pre> |
| @@ -2386,7 +2406,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2386 | 2406 | and 0 otherwise. |
| 2387 | 2407 | |
| 2388 | 2408 | <p><a name="lua_isnumber"></a> |
| 2389 | | −<hr/><h3><code>lua_isnumber</code></h3> |
| 2409 | +<hr /><h3><code>lua_isnumber</code></h3> |
| 2390 | 2410 | <pre> |
| 2391 | 2411 | int lua_isnumber (lua_State *L, int index); |
| 2392 | 2412 | </pre> |
| @@ -2397,7 +2417,7 @@ or a string convertible to a number, · 4 unmodified lines |
| 2397 | 2417 | and 0 otherwise. |
| 2398 | 2418 | |
| 2399 | 2419 | <p><a name="lua_isstring"></a> |
| 2400 | | −<hr/><h3><code>lua_isstring</code></h3> |
| 2420 | +<hr /><h3><code>lua_isstring</code></h3> |
| 2401 | 2421 | <pre> |
| 2402 | 2422 | int lua_isstring (lua_State *L, int index); |
| 2403 | 2423 | </pre> |
| @@ -2408,7 +2428,7 @@ or a number (which is always convertible to a string), · 4 unmodified lines |
| 2408 | 2428 | and 0 otherwise. |
| 2409 | 2429 | |
| 2410 | 2430 | <p><a name="lua_istable"></a> |
| 2411 | | −<hr/><h3><code>lua_istable</code></h3> |
| 2431 | +<hr /><h3><code>lua_istable</code></h3> |
| 2412 | 2432 | <pre> |
| 2413 | 2433 | int lua_istable (lua_State *L, int index); |
| 2414 | 2434 | </pre> |
| @@ -2418,7 +2438,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2418 | 2438 | and 0 otherwise. |
| 2419 | 2439 | |
| 2420 | 2440 | <p><a name="lua_isthread"></a> |
| 2421 | | −<hr/><h3><code>lua_isthread</code></h3> |
| 2441 | +<hr /><h3><code>lua_isthread</code></h3> |
| 2422 | 2442 | <pre> |
| 2423 | 2443 | int lua_isthread (lua_State *L, int index); |
| 2424 | 2444 | </pre> |
| @@ -2428,7 +2448,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2428 | 2448 | and 0 otherwise. |
| 2429 | 2449 | |
| 2430 | 2450 | <p><a name="lua_isuserdata"></a> |
| 2431 | | −<hr/><h3><code>lua_isuserdata</code></h3> |
| 2451 | +<hr /><h3><code>lua_isuserdata</code></h3> |
| 2432 | 2452 | <pre> |
| 2433 | 2453 | int lua_isuserdata (lua_State *L, int index); |
| 2434 | 2454 | </pre> |
| @@ -2438,21 +2458,21 @@ and 0 otherwise. · 3 unmodified lines |
| 2438 | 2458 | (either full or light), and 0 otherwise. |
| 2439 | 2459 | |
| 2440 | 2460 | <p><a name="lua_lessthan"></a> |
| 2441 | | −<hr/><h3><code>lua_lessthan</code></h3> |
| 2461 | +<hr /><h3><code>lua_lessthan</code></h3> |
| 2442 | 2462 | <pre> |
| 2443 | 2463 | int lua_lessthan (lua_State *L, int index1, int index2); |
| 2444 | 2464 | </pre> |
| 2445 | 2465 | |
| 2446 | 2466 | |
| 2447 | | −<p>Returns 1 if the value in acceptable index <code>index1</code> is smaller |
| 2448 | | −than the value in acceptable index <code>index2</code>, |
| 2467 | +<p>Returns 1 if the value at acceptable index <code>index1</code> is smaller |
| 2468 | +than the value at acceptable index <code>index2</code>, |
| 2449 | 2469 | following the semantics of the Lua <code><</code> operator |
| 2450 | 2470 | (that is, may call metamethods). |
| 2451 | 2471 | Otherwise returns 0. |
| 2452 | | −Also returns 0 if any of the indices are non valid. |
| 2472 | +Also returns 0 if any of the indices is non valid. |
| 2453 | 2473 | |
| 2454 | 2474 | <p><a name="lua_load"></a> |
| 2455 | | −<hr/><h3><code>lua_load</code></h3> |
| 2475 | +<hr /><h3><code>lua_load</code></h3> |
| 2456 | 2476 | <pre> |
| 2457 | 2477 | int lua_load (lua_State *L, lua_Reader reader, void *data, |
| 2458 | 2478 | const char *chunkname); |
| @@ -2481,11 +2501,11 @@ and loads it accordingly (see program <code>luac</code>). · 22 unmodified lines |
| 2481 | 2501 | (see <a href="#lua_Reader"><code>lua_Reader</code></a>). |
| 2482 | 2502 | The <code>data</code> argument is an opaque value passed to the reader function. |
| 2483 | 2503 | |
| 2484 | | −<p>The <code>chunkname</code> argument gives the chunk name. |
| 2485 | | −It is used for error messages and debug information (see <a href="#debugI">3.8</a>). |
| 2504 | +<p>The <code>chunkname</code> argument gives a name to the chunk, |
| 2505 | +which is used for error messages and in debug information (see <a href="#debugI">3.8</a>). |
| 2486 | 2506 | |
| 2487 | 2507 | <p><a name="lua_newstate"></a> |
| 2488 | | −<hr/><h3><code>lua_newstate</code></h3> |
| 2508 | +<hr /><h3><code>lua_newstate</code></h3> |
| 2489 | 2509 | <pre> |
| 2490 | 2510 | lua_State *lua_newstate (lua_Alloc f, void *ud); |
| 2491 | 2511 | </pre> |
| @@ -2493,14 +2513,14 @@ It is used for error messages and debug information (see <a href="#debugI">3.8</ · 1 unmodified line |
| 2493 | 2513 | |
| 2494 | 2514 | <p>Creates a new, independent state. |
| 2495 | 2515 | Returns <code>NULL</code> if cannot create the state |
| 2496 | | −(not enough memory). |
| 2516 | +(due to lack of memory). |
| 2497 | 2517 | The argument <code>f</code> is the allocator function; |
| 2498 | 2518 | Lua does all memory allocation for that state through that function. |
| 2499 | 2519 | The second argument, <code>ud</code>, is an opaque pointer that Lua |
| 2500 | 2520 | simply passes to the allocator in every call. |
| 2501 | 2521 | |
| 2502 | 2522 | <p><a name="lua_newtable"></a> |
| 2503 | | −<hr/><h3><code>lua_newtable</code></h3> |
| 2523 | +<hr /><h3><code>lua_newtable</code></h3> |
| 2504 | 2524 | <pre> |
| 2505 | 2525 | void lua_newtable (lua_State *L); |
| 2506 | 2526 | </pre> |
| @@ -2510,7 +2530,7 @@ simply passes to the allocator in every call. · 3 unmodified lines |
| 2510 | 2530 | Equivalent to <code>lua_createtable(L, 0, 0)</code>. |
| 2511 | 2531 | |
| 2512 | 2532 | <p><a name="lua_newthread"></a> |
| 2513 | | −<hr/><h3><code>lua_newthread</code></h3> |
| 2533 | +<hr /><h3><code>lua_newthread</code></h3> |
| 2514 | 2534 | <pre> |
| 2515 | 2535 | lua_State *lua_newthread (lua_State *L); |
| 2516 | 2536 | </pre> |
| @@ -2520,14 +2540,14 @@ Equivalent to <code>lua_createtable(L, 0, 0)</code>. · 3 unmodified lines |
| 2520 | 2540 | and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. |
| 2521 | 2541 | The new state returned by this function shares with the original state |
| 2522 | 2542 | all global objects (such as tables), |
| 2523 | | −but has an independent run-time stack. |
| 2543 | +but has an independent execution stack. |
| 2524 | 2544 | |
| 2525 | 2545 | <p>There is no explicit function to close or to destroy a thread. |
| 2526 | 2546 | Threads are subject to garbage collection, |
| 2527 | 2547 | like any Lua object. |
| 2528 | 2548 | |
| 2529 | 2549 | <p><a name="lua_newuserdata"></a> |
| 2530 | | −<hr/><h3><code>lua_newuserdata</code></h3> |
| 2550 | +<hr /><h3><code>lua_newuserdata</code></h3> |
| 2531 | 2551 | <pre> |
| 2532 | 2552 | void *lua_newuserdata (lua_State *L, size_t size); |
| 2533 | 2553 | </pre> |
| @@ -2544,21 +2564,22 @@ You must create it, it can have its own metatable, · 10 unmodified lines |
| 2544 | 2564 | and you can detect when it is being collected. |
| 2545 | 2565 | A full userdata is only equal to itself (under raw equality). |
| 2546 | 2566 | |
| 2547 | | −<p>When Lua collects a full userdata, |
| 2548 | | −it calls the userdata's <code>gc</code> metamethod, if any, |
| 2549 | | −and then it frees the userdata's corresponding memory. |
| 2567 | +<p>When Lua collects a full userdata with a <code>gc</code> metamethod, |
| 2568 | +Lua calls the metamethod and marks the userdata as finalized. |
| 2569 | +When that userdata is collected again then |
| 2570 | +Lua frees its corresponding memory. |
| 2550 | 2571 | |
| 2551 | 2572 | <p><a name="lua_next"></a> |
| 2552 | | −<hr/><h3><code>lua_next</code></h3> |
| 2573 | +<hr /><h3><code>lua_next</code></h3> |
| 2553 | 2574 | <pre> |
| 2554 | 2575 | int lua_next (lua_State *L, int index); |
| 2555 | 2576 | </pre> |
| 2556 | 2577 | |
| 2557 | 2578 | |
| 2558 | 2579 | <p>Pops a key from the stack, |
| 2559 | | −and pushes a key-value pair from the table |
| 2580 | +and pushes a key-value pair from the table at the given index |
| 2560 | 2581 | (the "next" pair after the given key). |
| 2561 | | −If there are no more elements, |
| 2582 | +If there are no more elements in the table, |
| 2562 | 2583 | then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). |
| 2563 | 2584 | |
| 2564 | 2585 | <p>A typical traversal looks like this: |
| @@ -2581,33 +2602,34 @@ the value at the given index; · 16 unmodified lines |
| 2581 | 2602 | this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. |
| 2582 | 2603 | |
| 2583 | 2604 | <p><a name="lua_Number"></a> |
| 2584 | | −<hr/><h3><code>lua_Number</code></h3> |
| 2605 | +<hr /><h3><code>lua_Number</code></h3> |
| 2585 | 2606 | <pre> |
| 2586 | 2607 | typedef double lua_Number; |
| 2587 | 2608 | </pre> |
| 2588 | 2609 | |
| 2589 | 2610 | |
| 2590 | 2611 | <p>The type of numbers in Lua. |
| 2612 | +By default, it is double, but that can be changed in <code>luaconf.h</code>. |
| 2591 | 2613 | |
| 2592 | 2614 | <p>Through the configuration file you can change |
| 2593 | 2615 | Lua to operate with other type for numbers (e.g., float or long). |
| 2594 | 2616 | |
| 2595 | 2617 | <p><a name="lua_objlen"></a> |
| 2596 | | −<hr/><h3><code>lua_objlen</code></h3> |
| 2618 | +<hr /><h3><code>lua_objlen</code></h3> |
| 2597 | 2619 | <pre> |
| 2598 | 2620 | size_t lua_objlen (lua_State *L, int index); |
| 2599 | 2621 | </pre> |
| 2600 | 2622 | |
| 2601 | 2623 | |
| 2602 | 2624 | <p>Returns the "length" of the value at the given acceptable index: |
| 2603 | | −For strings, this is the string length; |
| 2604 | | −for tables, this is the result of the length operator (`<code>#</code>´). |
| 2625 | +for strings, this is the string length; |
| 2626 | +for tables, this is the result of the length operator (`<code>#</code>´); |
| 2605 | 2627 | for userdata, this is the size of the block of memory allocated |
| 2606 | | −for the userdatum. |
| 2607 | | −For other values, returns 0. |
| 2628 | +for the userdata; |
| 2629 | +for other values, it is 0. |
| 2608 | 2630 | |
| 2609 | 2631 | <p><a name="lua_pcall"></a> |
| 2610 | | −<hr/><h3><code>lua_pcall</code></h3> |
| 2632 | +<hr /><h3><code>lua_pcall</code></h3> |
| 2611 | 2633 | <pre> |
| 2612 | 2634 | lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); |
| 2613 | 2635 | </pre> |
| @@ -2628,13 +2650,14 @@ Like <a href="#lua_call"><code>lua_call</code></a>, · 14 unmodified lines |
| 2628 | 2650 | and its arguments from the stack. |
| 2629 | 2651 | |
| 2630 | 2652 | <p>If <code>errfunc</code> is 0, |
| 2631 | | −then the error message returned is exactly the original error message. |
| 2653 | +then the error message returned on the stack |
| 2654 | +is exactly the original error message. |
| 2632 | 2655 | Otherwise, <code>errfunc</code> is the stack index of an |
| 2633 | 2656 | <em>error handler function</em>. |
| 2634 | 2657 | (In the current implementation, that index cannot be a pseudo-index.) |
| 2635 | 2658 | In case of runtime errors, |
| 2636 | 2659 | that function will be called with the error message |
| 2637 | | −and its return value will be the message returned by <a href="#lua_pcall"><code>lua_pcall</code></a>. |
| 2660 | +and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. |
| 2638 | 2661 | |
| 2639 | 2662 | <p>Typically, the error handler function is used to add more debug |
| 2640 | 2663 | information to the error message, such as a stack traceback. |
| @@ -2653,7 +2676,7 @@ error while running the error handler function. · 12 unmodified lines |
| 2653 | 2676 | </ul> |
| 2654 | 2677 | |
| 2655 | 2678 | <p><a name="lua_pop"></a> |
| 2656 | | −<hr/><h3><code>lua_pop</code></h3> |
| 2679 | +<hr /><h3><code>lua_pop</code></h3> |
| 2657 | 2680 | <pre> |
| 2658 | 2681 | void lua_pop (lua_State *L, int n); |
| 2659 | 2682 | </pre> |
| @@ -2662,7 +2685,7 @@ error while running the error handler function. · 2 unmodified lines |
| 2662 | 2685 | <p>Pops <code>n</code> elements from the stack. |
| 2663 | 2686 | |
| 2664 | 2687 | <p><a name="lua_pushboolean"></a> |
| 2665 | | −<hr/><h3><code>lua_pushboolean</code></h3> |
| 2688 | +<hr /><h3><code>lua_pushboolean</code></h3> |
| 2666 | 2689 | <pre> |
| 2667 | 2690 | void lua_pushboolean (lua_State *L, int b); |
| 2668 | 2691 | </pre> |
| @@ -2671,7 +2694,7 @@ error while running the error handler function. · 2 unmodified lines |
| 2671 | 2694 | <p>Pushes a boolean value with value <code>b</code> onto the stack. |
| 2672 | 2695 | |
| 2673 | 2696 | <p><a name="lua_pushcclosure"></a> |
| 2674 | | −<hr/><h3><code>lua_pushcclosure</code></h3> |
| 2697 | +<hr /><h3><code>lua_pushcclosure</code></h3> |
| 2675 | 2698 | <pre> |
| 2676 | 2699 | void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); |
| 2677 | 2700 | </pre> |
| @@ -2686,14 +2709,14 @@ these values are then accessible to the function whenever it is called. · 8 unmodified lines |
| 2686 | 2709 | To associate values with a C function, |
| 2687 | 2710 | first these values should be pushed onto the stack |
| 2688 | 2711 | (when there are multiple values, the first value is pushed first). |
| 2689 | | −Then the function <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> |
| 2690 | | −is used to create and push the C function onto the stack, |
| 2712 | +Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> |
| 2713 | +is called to create and push the C function onto the stack, |
| 2691 | 2714 | with the argument <code>n</code> telling how many values should be |
| 2692 | 2715 | associated with the function. |
| 2693 | 2716 | <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. |
| 2694 | 2717 | |
| 2695 | 2718 | <p><a name="lua_pushcfunction"></a> |
| 2696 | | −<hr/><h3><code>lua_pushcfunction</code></h3> |
| 2719 | +<hr /><h3><code>lua_pushcfunction</code></h3> |
| 2697 | 2720 | <pre> |
| 2698 | 2721 | void lua_pushcfunction (lua_State *L, lua_CFunction f); |
| 2699 | 2722 | </pre> |
| @@ -2703,7 +2726,7 @@ associated with the function. · 3 unmodified lines |
| 2703 | 2726 | This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. |
| 2704 | 2727 | |
| 2705 | 2728 | <p><a name="lua_pushfstring"></a> |
| 2706 | | −<hr/><h3><code>lua_pushfstring</code></h3> |
| 2729 | +<hr /><h3><code>lua_pushfstring</code></h3> |
| 2707 | 2730 | <pre> |
| 2708 | 2731 | const char *lua_pushfstring (lua_State *L, const char *fmt, ...); |
| 2709 | 2732 | </pre> |
| @@ -2711,15 +2734,15 @@ This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. · 1 unmodified line |
| 2711 | 2734 | |
| 2712 | 2735 | <p>Pushes onto the stack a formatted string |
| 2713 | 2736 | and returns a pointer to that string. |
| 2714 | | −It is similar to the C function <code>sprintf</code> |
| 2715 | | −but with some important differences: |
| 2737 | +It is similar to the C function <code>sprintf</code>, |
| 2738 | +but has some important differences: |
| 2716 | 2739 | <ul> |
| 2717 | 2740 | <li> You do not have to allocate the space for the result: |
| 2718 | 2741 | The result is a Lua string and Lua takes care of memory allocation |
| 2719 | 2742 | (and deallocation, through garbage collection). |
| 2720 | 2743 | <li> The conversion specifiers are quite restricted. |
| 2721 | 2744 | There are no flags, widths, or precisions. |
| 2722 | | −The conversion specifiers can be simply |
| 2745 | +The conversion specifiers can only be |
| 2723 | 2746 | `<code>%%</code>´ (inserts a `<code>%</code>´ in the string), |
| 2724 | 2747 | `<code>%s</code>´ (inserts a zero-terminated string, with no size restrictions), |
| 2725 | 2748 | `<code>%f</code>´ (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), |
| @@ -2729,7 +2752,7 @@ The conversion specifiers can be simply · 3 unmodified lines |
| 2729 | 2752 | </ul> |
| 2730 | 2753 | |
| 2731 | 2754 | <p><a name="lua_pushinteger"></a> |
| 2732 | | −<hr/><h3><code>lua_pushinteger</code></h3> |
| 2755 | +<hr /><h3><code>lua_pushinteger</code></h3> |
| 2733 | 2756 | <pre> |
| 2734 | 2757 | void lua_pushinteger (lua_State *L, lua_Integer n); |
| 2735 | 2758 | </pre> |
| @@ -2738,7 +2761,7 @@ The conversion specifiers can be simply · 2 unmodified lines |
| 2738 | 2761 | <p>Pushes a number with value <code>n</code> onto the stack. |
| 2739 | 2762 | |
| 2740 | 2763 | <p><a name="lua_pushlightuserdata"></a> |
| 2741 | | −<hr/><h3><code>lua_pushlightuserdata</code></h3> |
| 2764 | +<hr /><h3><code>lua_pushlightuserdata</code></h3> |
| 2742 | 2765 | <pre> |
| 2743 | 2766 | void lua_pushlightuserdata (lua_State *L, void *p); |
| 2744 | 2767 | </pre> |
| @@ -2755,7 +2778,7 @@ A light userdata is equal to "any" · 10 unmodified lines |
| 2755 | 2778 | light userdata with the same C address. |
| 2756 | 2779 | |
| 2757 | 2780 | <p><a name="lua_pushlstring"></a> |
| 2758 | | −<hr/><h3><code>lua_pushlstring</code></h3> |
| 2781 | +<hr /><h3><code>lua_pushlstring</code></h3> |
| 2759 | 2782 | <pre> |
| 2760 | 2783 | void lua_pushlstring (lua_State *L, const char *s, size_t len); |
| 2761 | 2784 | </pre> |
| @@ -2766,9 +2789,10 @@ onto the stack. · 4 unmodified lines |
| 2766 | 2789 | Lua makes (or reuses) an internal copy of the given string, |
| 2767 | 2790 | so the memory at <code>s</code> can be freed or reused immediately after |
| 2768 | 2791 | the function returns. |
| 2792 | +The string can contain embedded zeros. |
| 2769 | 2793 | |
| 2770 | 2794 | <p><a name="lua_pushnil"></a> |
| 2771 | | −<hr/><h3><code>lua_pushnil</code></h3> |
| 2795 | +<hr /><h3><code>lua_pushnil</code></h3> |
| 2772 | 2796 | <pre> |
| 2773 | 2797 | void lua_pushnil (lua_State *L); |
| 2774 | 2798 | </pre> |
| @@ -2777,7 +2801,7 @@ the function returns. · 2 unmodified lines |
| 2777 | 2801 | <p>Pushes a nil value onto the stack. |
| 2778 | 2802 | |
| 2779 | 2803 | <p><a name="lua_pushnumber"></a> |
| 2780 | | −<hr/><h3><code>lua_pushnumber</code></h3> |
| 2804 | +<hr /><h3><code>lua_pushnumber</code></h3> |
| 2781 | 2805 | <pre> |
| 2782 | 2806 | void lua_pushnumber (lua_State *L, lua_Number n); |
| 2783 | 2807 | </pre> |
| @@ -2786,7 +2810,7 @@ the function returns. · 2 unmodified lines |
| 2786 | 2810 | <p>Pushes a number with value <code>n</code> onto the stack. |
| 2787 | 2811 | |
| 2788 | 2812 | <p><a name="lua_pushstring"></a> |
| 2789 | | −<hr/><h3><code>lua_pushstring</code></h3> |
| 2813 | +<hr /><h3><code>lua_pushstring</code></h3> |
| 2790 | 2814 | <pre> |
| 2791 | 2815 | void lua_pushstring (lua_State *L, const char *s); |
| 2792 | 2816 | </pre> |
| @@ -2797,9 +2821,20 @@ onto the stack. · 4 unmodified lines |
| 2797 | 2821 | Lua makes (or reuses) an internal copy of the given string, |
| 2798 | 2822 | so the memory at <code>s</code> can be freed or reused immediately after |
| 2799 | 2823 | the function returns. |
| 2824 | +The string cannot embedded zeros; |
| 2825 | +it is assumed to end at the first zero. |
| 2826 | + |
| 2827 | +<p><a name="lua_pushthread"></a> |
| 2828 | +<hr /><h3><code>lua_pushthread</code></h3> |
| 2829 | +<pre> |
| 2830 | + void lua_pushthread (lua_State *L); |
| 2831 | +</pre> |
| 2832 | + |
| 2833 | + |
| 2834 | +<p>Pushes the thread represented by <code>L</code> onto the stack. |
| 2800 | 2835 | |
| 2801 | 2836 | <p><a name="lua_pushvalue"></a> |
| 2802 | | −<hr/><h3><code>lua_pushvalue</code></h3> |
| 2837 | +<hr /><h3><code>lua_pushvalue</code></h3> |
| 2803 | 2838 | <pre> |
| 2804 | 2839 | void lua_pushvalue (lua_State *L, int index); |
| 2805 | 2840 | </pre> |
| @@ -2809,7 +2844,7 @@ the function returns. · 3 unmodified lines |
| 2809 | 2844 | onto the stack. |
| 2810 | 2845 | |
| 2811 | 2846 | <p><a name="lua_pushvfstring"></a> |
| 2812 | | −<hr/><h3><code>lua_pushvfstring</code></h3> |
| 2847 | +<hr /><h3><code>lua_pushvfstring</code></h3> |
| 2813 | 2848 | <pre> |
| 2814 | 2849 | const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); |
| 2815 | 2850 | </pre> |
| @@ -2819,7 +2854,7 @@ onto the stack. · 3 unmodified lines |
| 2819 | 2854 | instead of a variable number of arguments. |
| 2820 | 2855 | |
| 2821 | 2856 | <p><a name="lua_rawequal"></a> |
| 2822 | | −<hr/><h3><code>lua_rawequal</code></h3> |
| 2857 | +<hr /><h3><code>lua_rawequal</code></h3> |
| 2823 | 2858 | <pre> |
| 2824 | 2859 | int lua_rawequal (lua_State *L, int index1, int index2); |
| 2825 | 2860 | </pre> |
| @@ -2832,17 +2867,17 @@ Otherwise returns 0. · 6 unmodified lines |
| 2832 | 2867 | Also returns 0 if any of the indices are non valid. |
| 2833 | 2868 | |
| 2834 | 2869 | <p><a name="lua_rawget"></a> |
| 2835 | | −<hr/><h3><code>lua_rawget</code></h3> |
| 2870 | +<hr /><h3><code>lua_rawget</code></h3> |
| 2836 | 2871 | <pre> |
| 2837 | 2872 | void lua_rawget (lua_State *L, int index); |
| 2838 | 2873 | </pre> |
| 2839 | 2874 | |
| 2840 | 2875 | |
| 2841 | | −<p>Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but doing a raw indexing |
| 2876 | +<p>Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access |
| 2842 | 2877 | (i.e., without metamethods). |
| 2843 | 2878 | |
| 2844 | 2879 | <p><a name="lua_rawgeti"></a> |
| 2845 | | −<hr/><h3><code>lua_rawgeti</code></h3> |
| 2880 | +<hr /><h3><code>lua_rawgeti</code></h3> |
| 2846 | 2881 | <pre> |
| 2847 | 2882 | void lua_rawgeti (lua_State *L, int index, int n); |
| 2848 | 2883 | </pre> |
| @@ -2850,36 +2885,36 @@ Also returns 0 if any of the indices are non valid. · 1 unmodified line |
| 2850 | 2885 | |
| 2851 | 2886 | <p>Pushes onto the stack the value <code>t[n]</code>, |
| 2852 | 2887 | where <code>t</code> is the value at the given valid index <code>index</code>. |
| 2853 | | −The access is raw, |
| 2888 | +The access is raw; |
| 2854 | 2889 | that is, it does not invoke metamethods. |
| 2855 | 2890 | |
| 2856 | 2891 | <p><a name="lua_rawset"></a> |
| 2857 | | −<hr/><h3><code>lua_rawset</code></h3> |
| 2892 | +<hr /><h3><code>lua_rawset</code></h3> |
| 2858 | 2893 | <pre> |
| 2859 | 2894 | void lua_rawset (lua_State *L, int index); |
| 2860 | 2895 | </pre> |
| 2861 | 2896 | |
| 2862 | 2897 | |
| 2863 | | −<p>Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but doing a raw assignment |
| 2898 | +<p>Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment |
| 2864 | 2899 | (i.e., without metamethods). |
| 2865 | 2900 | |
| 2866 | 2901 | <p><a name="lua_rawseti"></a> |
| 2867 | | −<hr/><h3><code>lua_rawseti</code></h3> |
| 2902 | +<hr /><h3><code>lua_rawseti</code></h3> |
| 2868 | 2903 | <pre> |
| 2869 | 2904 | void lua_rawseti (lua_State *L, int index, int n); |
| 2870 | 2905 | </pre> |
| 2871 | 2906 | |
| 2872 | 2907 | |
| 2873 | | −<p>Does the equivalent to <code>t[n] = v</code>, |
| 2908 | +<p>Does the equivalent of <code>t[n] = v</code>, |
| 2874 | 2909 | where <code>t</code> is the value at the given valid index <code>index</code> |
| 2875 | 2910 | and <code>v</code> is the value at the top of the stack, |
| 2876 | 2911 | |
| 2877 | 2912 | <p>This function pops the value from the stack. |
| 2878 | | −The assignment is raw, |
| 2913 | +The assignment is raw; |
| 2879 | 2914 | that is, it does not invoke metamethods. |
| 2880 | 2915 | |
| 2881 | 2916 | <p><a name="lua_Reader"></a> |
| 2882 | | −<hr/><h3><code>lua_Reader</code></h3> |
| 2917 | +<hr /><h3><code>lua_Reader</code></h3> |
| 2883 | 2918 | <pre> |
| 2884 | 2919 | typedef const char * (*lua_Reader) |
| 2885 | 2920 | (lua_State *L, void *data, size_t *size); |
| @@ -2894,11 +2929,12 @@ passing along its <code>data</code> parameter. · 8 unmodified lines |
| 2894 | 2929 | The reader must return a pointer to a block of memory |
| 2895 | 2930 | with a new piece of the chunk |
| 2896 | 2931 | and set <code>size</code> to the block size. |
| 2897 | | −To signal the end of the chunk, the reader returns <code>NULL</code>. |
| 2932 | +The block must exist until the reader function is called again. |
| 2933 | +To signal the end of the chunk, the reader must return <code>NULL</code>. |
| 2898 | 2934 | The reader function may return pieces of any size greater than zero. |
| 2899 | 2935 | |
| 2900 | 2936 | <p><a name="lua_remove"></a> |
| 2901 | | −<hr/><h3><code>lua_remove</code></h3> |
| 2937 | +<hr /><h3><code>lua_remove</code></h3> |
| 2902 | 2938 | <pre> |
| 2903 | 2939 | void lua_remove (lua_State *L, int index); |
| 2904 | 2940 | </pre> |
| @@ -2910,7 +2946,7 @@ Cannot be called with a pseudo-index, · 5 unmodified lines |
| 2910 | 2946 | because a pseudo-index is not an actual stack position. |
| 2911 | 2947 | |
| 2912 | 2948 | <p><a name="lua_replace"></a> |
| 2913 | | −<hr/><h3><code>lua_replace</code></h3> |
| 2949 | +<hr /><h3><code>lua_replace</code></h3> |
| 2914 | 2950 | <pre> |
| 2915 | 2951 | void lua_replace (lua_State *L, int index); |
| 2916 | 2952 | </pre> |
| @@ -2921,7 +2957,7 @@ without shifting any element · 4 unmodified lines |
| 2921 | 2957 | (therefore replacing the value at the given position). |
| 2922 | 2958 | |
| 2923 | 2959 | <p><a name="lua_resume"></a> |
| 2924 | | −<hr/><h3><code>lua_resume</code></h3> |
| 2960 | +<hr /><h3><code>lua_resume</code></h3> |
| 2925 | 2961 | <pre> |
| 2926 | 2962 | int lua_resume (lua_State *L, int narg); |
| 2927 | 2963 | </pre> |
| @@ -2931,7 +2967,7 @@ without shifting any element · 3 unmodified lines |
| 2931 | 2967 | |
| 2932 | 2968 | <p>To start a coroutine, you first create a new thread |
| 2933 | 2969 | (see <a href="#lua_newthread"><code>lua_newthread</code></a>); |
| 2934 | | −then you push on its stack the body function plus any eventual arguments; |
| 2970 | +then you push on its stack the main function plus any eventual arguments; |
| 2935 | 2971 | then you call <a href="#lua_resume"><code>lua_resume</code></a>, |
| 2936 | 2972 | with <code>narg</code> being the number of arguments. |
| 2937 | 2973 | This call returns when the coroutine suspends or finishes its execution. |
| @@ -2944,14 +2980,14 @@ without errors, · 6 unmodified lines |
| 2944 | 2980 | or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). |
| 2945 | 2981 | In case of errors, |
| 2946 | 2982 | the stack is not unwound, |
| 2947 | | −so you can use the debug API over it; |
| 2983 | +so you can use the debug API over it. |
| 2948 | 2984 | The error message is on the top of the stack. |
| 2949 | 2985 | To restart a coroutine, you put on its stack only the values to |
| 2950 | 2986 | be passed as results from <code>yield</code>, |
| 2951 | 2987 | and then call <a href="#lua_resume"><code>lua_resume</code></a>. |
| 2952 | 2988 | |
| 2953 | 2989 | <p><a name="lua_setallocf"></a> |
| 2954 | | −<hr/><h3><code>lua_setallocf</code></h3> |
| 2990 | +<hr /><h3><code>lua_setallocf</code></h3> |
| 2955 | 2991 | <pre> |
| 2956 | 2992 | void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); |
| 2957 | 2993 | </pre> |
| @@ -2961,7 +2997,7 @@ and then call <a href="#lua_resume"><code>lua_resume</code></a>. · 3 unmodified lines |
| 2961 | 2997 | with user data <code>ud</code>. |
| 2962 | 2998 | |
| 2963 | 2999 | <p><a name="lua_setfenv"></a> |
| 2964 | | −<hr/><h3><code>lua_setfenv</code></h3> |
| 3000 | +<hr /><h3><code>lua_setfenv</code></h3> |
| 2965 | 3001 | <pre> |
| 2966 | 3002 | int lua_setfenv (lua_State *L, int index); |
| 2967 | 3003 | </pre> |
| @@ -2971,10 +3007,11 @@ with user data <code>ud</code>. · 3 unmodified lines |
| 2971 | 3007 | the new environment for the value at the given index. |
| 2972 | 3008 | If the value at the given index is |
| 2973 | 3009 | neither a function nor a thread nor a userdata, |
| 2974 | | −<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0 (false). |
| 3010 | +<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. |
| 3011 | +Otherwise it returns 1. |
| 2975 | 3012 | |
| 2976 | 3013 | <p><a name="lua_setfield"></a> |
| 2977 | | −<hr/><h3><code>lua_setfield</code></h3> |
| 3014 | +<hr /><h3><code>lua_setfield</code></h3> |
| 2978 | 3015 | <pre> |
| 2979 | 3016 | void lua_setfield (lua_State *L, int index, const char *k); |
| 2980 | 3017 | </pre> |
| @@ -2989,7 +3026,7 @@ As in Lua, this function may trigger a metamethod · 8 unmodified lines |
| 2989 | 3026 | for the "newindex" event (see <a href="#metatable">2.8</a>). |
| 2990 | 3027 | |
| 2991 | 3028 | <p><a name="lua_setmetatable"></a> |
| 2992 | | −<hr/><h3><code>lua_setmetatable</code></h3> |
| 3029 | +<hr /><h3><code>lua_setmetatable</code></h3> |
| 2993 | 3030 | <pre> |
| 2994 | 3031 | int lua_setmetatable (lua_State *L, int index); |
| 2995 | 3032 | </pre> |
| @@ -3000,7 +3037,7 @@ sets it as the new metatable for the value at the given · 4 unmodified lines |
| 3000 | 3037 | acceptable index. |
| 3001 | 3038 | |
| 3002 | 3039 | <p><a name="lua_settable"></a> |
| 3003 | | −<hr/><h3><code>lua_settable</code></h3> |
| 3040 | +<hr /><h3><code>lua_settable</code></h3> |
| 3004 | 3041 | <pre> |
| 3005 | 3042 | void lua_settable (lua_State *L, int index); |
| 3006 | 3043 | </pre> |
| @@ -3016,7 +3053,7 @@ As in Lua, this function may trigger a metamethod · 9 unmodified lines |
| 3016 | 3053 | for the "newindex" event (see <a href="#metatable">2.8</a>). |
| 3017 | 3054 | |
| 3018 | 3055 | <p><a name="lua_settop"></a> |
| 3019 | | −<hr/><h3><code>lua_settop</code></h3> |
| 3056 | +<hr /><h3><code>lua_settop</code></h3> |
| 3020 | 3057 | <pre> |
| 3021 | 3058 | void lua_settop (lua_State *L, int index); |
| 3022 | 3059 | </pre> |
| @@ -3029,7 +3066,7 @@ then the new elements are filled with <b>nil</b>. · 6 unmodified lines |
| 3029 | 3066 | If <code>index</code> is 0, then all stack elements are removed. |
| 3030 | 3067 | |
| 3031 | 3068 | <p><a name="lua_State"></a> |
| 3032 | | −<hr/><h3><code>lua_State</code></h3> |
| 3069 | +<hr /><h3><code>lua_State</code></h3> |
| 3033 | 3070 | <pre> |
| 3034 | 3071 | typedef struct lua_State lua_State; |
| 3035 | 3072 | </pre> |
| @@ -3044,8 +3081,21 @@ All information about a state is kept in this structure. · 8 unmodified lines |
| 3044 | 3081 | every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, |
| 3045 | 3082 | which creates a Lua state from scratch. |
| 3046 | 3083 | |
| 3084 | +<p><a name="lua_status"></a> |
| 3085 | +<hr /><h3><code>lua_status</code></h3> |
| 3086 | +<pre> |
| 3087 | + int lua_status (lua_State *L); |
| 3088 | +</pre> |
| 3089 | + |
| 3090 | + |
| 3091 | +<p>Returns the status of the thread <code>L</code>. |
| 3092 | + |
| 3093 | +<p>The status can by 0 for a normal thread, |
| 3094 | +an error code if the thread finished its execution with an error, |
| 3095 | +or <code>LUA_YIELD</code> if the thread is suspended. |
| 3096 | + |
| 3047 | 3097 | <p><a name="lua_toboolean"></a> |
| 3048 | | −<hr/><h3><code>lua_toboolean</code></h3> |
| 3098 | +<hr /><h3><code>lua_toboolean</code></h3> |
| 3049 | 3099 | <pre> |
| 3050 | 3100 | int lua_toboolean (lua_State *L, int index); |
| 3051 | 3101 | </pre> |
| @@ -3058,11 +3108,11 @@ Like all tests in Lua, · 6 unmodified lines |
| 3058 | 3108 | different from <b>false</b> and <b>nil</b>; |
| 3059 | 3109 | otherwise it returns 0. |
| 3060 | 3110 | It also returns 0 when called with a non-valid index. |
| 3061 | | −(If you want to accept only real boolean values, |
| 3111 | +(If you want to accept only actual boolean values, |
| 3062 | 3112 | use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) |
| 3063 | 3113 | |
| 3064 | 3114 | <p><a name="lua_tocfunction"></a> |
| 3065 | | −<hr/><h3><code>lua_tocfunction</code></h3> |
| 3115 | +<hr /><h3><code>lua_tocfunction</code></h3> |
| 3066 | 3116 | <pre> |
| 3067 | 3117 | lua_CFunction lua_tocfunction (lua_State *L, int index); |
| 3068 | 3118 | </pre> |
| @@ -3073,7 +3123,7 @@ That value must be a C function; · 4 unmodified lines |
| 3073 | 3123 | otherwise, returns <code>NULL</code>. |
| 3074 | 3124 | |
| 3075 | 3125 | <p><a name="lua_tointeger"></a> |
| 3076 | | −<hr/><h3><code>lua_tointeger</code></h3> |
| 3126 | +<hr /><h3><code>lua_tointeger</code></h3> |
| 3077 | 3127 | <pre> |
| 3078 | 3128 | lua_Integer lua_tointeger (lua_State *L, int idx); |
| 3079 | 3129 | </pre> |
| @@ -3089,7 +3139,7 @@ otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. · 9 unmodified lines |
| 3089 | 3139 | it is truncated in some non-specified way. |
| 3090 | 3140 | |
| 3091 | 3141 | <p><a name="lua_tolstring"></a> |
| 3092 | | −<hr/><h3><code>lua_tolstring</code></h3> |
| 3142 | +<hr /><h3><code>lua_tolstring</code></h3> |
| 3093 | 3143 | <pre> |
| 3094 | 3144 | const char *lua_tolstring (lua_State *L, int index, size_t *len); |
| 3095 | 3145 | </pre> |
| @@ -3105,11 +3155,11 @@ If the value is a number, · 9 unmodified lines |
| 3105 | 3155 | then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also |
| 3106 | 3156 | <em>changes the actual value in the stack to a string</em>. |
| 3107 | 3157 | (This change confuses <a href="#lua_next"><code>lua_next</code></a> |
| 3108 | | −when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys.) |
| 3158 | +when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) |
| 3109 | 3159 | |
| 3110 | 3160 | <p><a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer |
| 3111 | 3161 | to a string inside the Lua state. |
| 3112 | | −This string always has a zero (<code>'\0'</code>) |
| 3162 | +This string always has a zero (`<code>\0</code>´) |
| 3113 | 3163 | after its last character (as in C), |
| 3114 | 3164 | but may contain other zeros in its body. |
| 3115 | 3165 | Because Lua has garbage collection, |
| @@ -3117,7 +3167,7 @@ there is no guarantee that the pointer returned by <a href="#lua_tolstring"><cod · 1 unmodified line |
| 3117 | 3167 | will be valid after the corresponding value is removed from the stack. |
| 3118 | 3168 | |
| 3119 | 3169 | <p><a name="lua_tonumber"></a> |
| 3120 | | −<hr/><h3><code>lua_tonumber</code></h3> |
| 3170 | +<hr /><h3><code>lua_tonumber</code></h3> |
| 3121 | 3171 | <pre> |
| 3122 | 3172 | lua_Number lua_tonumber (lua_State *L, int index); |
| 3123 | 3173 | </pre> |
| @@ -3130,23 +3180,23 @@ The Lua value must be a number or a string convertible to number · 6 unmodified lines |
| 3130 | 3180 | otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. |
| 3131 | 3181 | |
| 3132 | 3182 | <p><a name="lua_topointer"></a> |
| 3133 | | −<hr/><h3><code>lua_topointer</code></h3> |
| 3183 | +<hr /><h3><code>lua_topointer</code></h3> |
| 3134 | 3184 | <pre> |
| 3135 | 3185 | const void *lua_topointer (lua_State *L, int index); |
| 3136 | 3186 | </pre> |
| 3137 | 3187 | |
| 3138 | 3188 | |
| 3139 | 3189 | <p>Converts the value at the given acceptable index to a generic |
| 3140 | | −C pointer (<code>void *</code>). |
| 3190 | +C pointer (<code>void*</code>). |
| 3141 | 3191 | The value may be a userdata, a table, a thread, or a function; |
| 3142 | 3192 | otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. |
| 3143 | 3193 | Lua ensures that different objects return different pointers. |
| 3144 | 3194 | There is no direct way to convert the pointer back to its original value. |
| 3145 | 3195 | |
| 3146 | | −<p>Typically this function is used for debug information. |
| 3196 | +<p>Typically this function is used only for debug information. |
| 3147 | 3197 | |
| 3148 | 3198 | <p><a name="lua_tostring"></a> |
| 3149 | | −<hr/><h3><code>lua_tostring</code></h3> |
| 3199 | +<hr /><h3><code>lua_tostring</code></h3> |
| 3150 | 3200 | <pre> |
| 3151 | 3201 | const char *lua_tostring (lua_State *L, int index); |
| 3152 | 3202 | </pre> |
| @@ -3155,19 +3205,19 @@ There is no direct way to convert the pointer back to its original value. · 2 unmodified lines |
| 3155 | 3205 | <p>Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. |
| 3156 | 3206 | |
| 3157 | 3207 | <p><a name="lua_tothread"></a> |
| 3158 | | −<hr/><h3><code>lua_tothread</code></h3> |
| 3208 | +<hr /><h3><code>lua_tothread</code></h3> |
| 3159 | 3209 | <pre> |
| 3160 | 3210 | lua_State *lua_tothread (lua_State *L, int index); |
| 3161 | 3211 | </pre> |
| 3162 | 3212 | |
| 3163 | 3213 | |
| 3164 | 3214 | <p>Converts the value at the given acceptable index to a Lua thread |
| 3165 | | −(represented as <code>lua_State *</code>). |
| 3215 | +(represented as <code>lua_State*</code>). |
| 3166 | 3216 | This value must be a thread; |
| 3167 | 3217 | otherwise, the function returns <code>NULL</code>. |
| 3168 | 3218 | |
| 3169 | 3219 | <p><a name="lua_touserdata"></a> |
| 3170 | | −<hr/><h3><code>lua_touserdata</code></h3> |
| 3220 | +<hr /><h3><code>lua_touserdata</code></h3> |
| 3171 | 3221 | <pre> |
| 3172 | 3222 | void *lua_touserdata (lua_State *L, int index); |
| 3173 | 3223 | </pre> |
| @@ -3180,7 +3230,7 @@ returns its pointer. · 6 unmodified lines |
| 3180 | 3230 | Otherwise, returns <code>NULL</code>. |
| 3181 | 3231 | |
| 3182 | 3232 | <p><a name="lua_type"></a> |
| 3183 | | −<hr/><h3><code>lua_type</code></h3> |
| 3233 | +<hr /><h3><code>lua_type</code></h3> |
| 3184 | 3234 | <pre> |
| 3185 | 3235 | int lua_type (lua_State *L, int index); |
| 3186 | 3236 | </pre> |
| @@ -3199,10 +3249,21 @@ defined in <code>lua.h</code>: · 12 unmodified lines |
| 3199 | 3249 | <code>LUA_TFUNCTION</code>, |
| 3200 | 3250 | <code>LUA_TUSERDATA</code>, |
| 3201 | 3251 | <code>LUA_TTHREAD</code>, |
| 3252 | +and |
| 3202 | 3253 | <code>LUA_TLIGHTUSERDATA</code>. |
| 3203 | 3254 | |
| 3255 | +<p><a name="lua_typename"></a> |
| 3256 | +<hr /><h3><code>lua_typename</code></h3> |
| 3257 | +<pre> |
| 3258 | + const char *lua_typename (lua_State *L, int tp); |
| 3259 | +</pre> |
| 3260 | + |
| 3261 | + |
| 3262 | +<p>Returns the name of the type encoded by the value <code>tp</code>, |
| 3263 | +which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. |
| 3264 | + |
| 3204 | 3265 | <p><a name="lua_Writer"></a> |
| 3205 | | −<hr/><h3><code>lua_Writer</code></h3> |
| 3266 | +<hr /><h3><code>lua_Writer</code></h3> |
| 3206 | 3267 | <pre> |
| 3207 | 3268 | typedef int (*lua_Writer) |
| 3208 | 3269 | (lua_State *L, const void* p, size_t sz, void* ud); |
| @@ -3223,19 +3284,19 @@ any other value means an error and stops <a href="#lua_dump"><code>lua_dump</cod · 14 unmodified lines |
| 3223 | 3284 | calling the writer again. |
| 3224 | 3285 | |
| 3225 | 3286 | <p><a name="lua_xmove"></a> |
| 3226 | | −<hr/><h3><code>lua_xmove</code></h3> |
| 3287 | +<hr /><h3><code>lua_xmove</code></h3> |
| 3227 | 3288 | <pre> |
| 3228 | 3289 | void lua_xmove (lua_State *from, lua_State *to, int n); |
| 3229 | 3290 | </pre> |
| 3230 | 3291 | |
| 3231 | 3292 | |
| 3232 | | −<p>Exchange values between different threads of the same global state. |
| 3293 | +<p>Exchange values between different threads of the <em>same</em> global state. |
| 3233 | 3294 | |
| 3234 | 3295 | <p>This function pops <code>n</code> values from the stack <code>from</code>, |
| 3235 | 3296 | and pushes them into the stack <code>to</code>. |
| 3236 | 3297 | |
| 3237 | 3298 | <p><a name="lua_yield"></a> |
| 3238 | | −<hr/><h3><code>lua_yield</code></h3> |
| 3299 | +<hr /><h3><code>lua_yield</code></h3> |
| 3239 | 3300 | <pre> |
| 3240 | 3301 | int lua_yield (lua_State *L, int nresults); |
| 3241 | 3302 | </pre> |
| @@ -3243,7 +3304,7 @@ and pushes them into the stack <code>to</code>. · 1 unmodified line |
| 3243 | 3304 | |
| 3244 | 3305 | <p>Yields a coroutine. |
| 3245 | 3306 | |
| 3246 | | −<p>This function can only be called as the |
| 3307 | +<p>This function should only be called as the |
| 3247 | 3308 | return expression of a C function, as follows: |
| 3248 | 3309 | <pre> |
| 3249 | 3310 | return lua_yield (L, nresults); |
| @@ -3265,20 +3326,19 @@ kinds of debuggers, profilers, and other tools · 15 unmodified lines |
| 3265 | 3326 | that need "inside information" from the interpreter. |
| 3266 | 3327 | |
| 3267 | 3328 | <p><a name="lua_Debug"></a> |
| 3268 | | −<hr/><h3><code>lua_Debug</code></h3> |
| 3329 | +<hr /><h3><code>lua_Debug</code></h3> |
| 3269 | 3330 | <pre> |
| 3270 | 3331 | typedef struct lua_Debug { |
| 3271 | 3332 | int event; |
| 3272 | | − const char *name; /* (n) */ |
| 3273 | | − const char *namewhat; /* (n) */ |
| 3274 | | − const char *what; /* (S) */ |
| 3275 | | − const char *source; /* (S) */ |
| 3276 | | − int currentline; /* (l) */ |
| 3277 | | − int nups; /* (u) number of upvalues */ |
| 3278 | | − int linedefined; /* (S) */ |
| 3279 | | − int lastlinedefined; /* (S) */ |
| 3333 | + const char *name; /* (n) */ |
| 3334 | + const char *namewhat; /* (n) */ |
| 3335 | + const char *what; /* (S) */ |
| 3336 | + const char *source; /* (S) */ |
| 3337 | + int currentline; /* (l) */ |
| 3338 | + int nups; /* (u) number of upvalues */ |
| 3339 | + int linedefined; /* (S) */ |
| 3340 | + int lastlinedefined; /* (S) */ |
| 3280 | 3341 | char short_src[LUA_IDSIZE]; /* (S) */ |
| 3281 | | − |
| 3282 | 3342 | /* private part */ |
| 3283 | 3343 | ... |
| 3284 | 3344 | } lua_Debug; |
| @@ -3295,36 +3355,37 @@ call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. · 10 unmodified lines |
| 3295 | 3355 | |
| 3296 | 3356 | <p>The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: |
| 3297 | 3357 | <ul> |
| 3298 | | −<li><b><code>source</code></b> |
| 3358 | +<li><b><code>source</code></b> --- |
| 3299 | 3359 | If the function was defined in a string, |
| 3300 | 3360 | then <code>source</code> is that string. |
| 3301 | 3361 | If the function was defined in a file, |
| 3302 | 3362 | then <code>source</code> starts with a `<code>@</code>´ followed by the file name. |
| 3303 | 3363 | |
| 3304 | | −<p><li><b><code>short_src</code></b> |
| 3305 | | −A "printable" version of <code>source</code>, to be used in error messages. |
| 3364 | +<p><li><b><code>short_src</code></b> --- |
| 3365 | +a "printable" version of <code>source</code>, to be used in error messages. |
| 3306 | 3366 | |
| 3307 | | −<p><li><b><code>linedefined</code></b> |
| 3367 | +<p><li><b><code>linedefined</code></b> --- |
| 3308 | 3368 | the line number where the definition of the function starts. |
| 3309 | 3369 | |
| 3310 | | −<p><li><b><code>lastlinedefined</code></b> |
| 3370 | +<p><li><b><code>lastlinedefined</code></b> --- |
| 3311 | 3371 | the line number where the definition of the function ends. |
| 3312 | 3372 | |
| 3313 | | −<p><li><b><code>what</code></b> the string <code>"Lua"</code> if this is a Lua function, |
| 3314 | | −<code>"C"</code> if this is a C function, |
| 3315 | | −<code>"main"</code> if this is the main part of a chunk, |
| 3316 | | −and <code>"tail"</code> if this was a function that did a tail call. |
| 3373 | +<p><li><b><code>what</code></b> --- |
| 3374 | +the string <code>"Lua"</code> if the function is a Lua function, |
| 3375 | +<code>"C"</code> if it is a C function, |
| 3376 | +<code>"main"</code> if it is the main part of a chunk, |
| 3377 | +and <code>"tail"</code> if it was a function that did a tail call. |
| 3317 | 3378 | In the latter case, |
| 3318 | | −Lua has no other information about this function. |
| 3379 | +Lua has no other information about the function. |
| 3319 | 3380 | |
| 3320 | | −<p><li><b><code>currentline</code></b> |
| 3381 | +<p><li><b><code>currentline</code></b> --- |
| 3321 | 3382 | the current line where the given function is executing. |
| 3322 | 3383 | When no line information is available, |
| 3323 | 3384 | <code>currentline</code> is set to <em>-1</em>. |
| 3324 | 3385 | |
| 3325 | | −<p><li><b><code>name</code></b> |
| 3386 | +<p><li><b><code>name</code></b> --- |
| 3326 | 3387 | a reasonable name for the given function. |
| 3327 | | −Because functions in Lua are first class values, |
| 3388 | +Because functions in Lua are first-class values, |
| 3328 | 3389 | they do not have a fixed name: |
| 3329 | 3390 | Some functions may be the value of multiple global variables, |
| 3330 | 3391 | while others may be stored only in a table field. |
| @@ -3333,21 +3394,21 @@ called to find a suitable name. · 2 unmodified lines |
| 3333 | 3394 | If it cannot find a name, |
| 3334 | 3395 | then <code>name</code> is set to <code>NULL</code>. |
| 3335 | 3396 | |
| 3336 | | −<p><li><b><code>namewhat</code></b> |
| 3337 | | −Explains the <code>name</code> field. |
| 3397 | +<p><li><b><code>namewhat</code></b> --- |
| 3398 | +explains the <code>name</code> field. |
| 3338 | 3399 | The value of <code>namewhat</code> can be |
| 3339 | 3400 | <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, |
| 3340 | 3401 | <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), |
| 3341 | 3402 | according to how the function was called. |
| 3342 | 3403 | (Lua uses the empty string when no other option seems to apply.) |
| 3343 | 3404 | |
| 3344 | | −<p><li><b><code>nups</code></b> |
| 3345 | | −The number of upvalues of the function. |
| 3405 | +<p><li><b><code>nups</code></b> --- |
| 3406 | +the number of upvalues of the function. |
| 3346 | 3407 | |
| 3347 | 3408 | <p></ul> |
| 3348 | 3409 | |
| 3349 | 3410 | <p><a name="lua_gethook"></a> |
| 3350 | | −<hr/><h3><code>lua_gethook</code></h3> |
| 3411 | +<hr /><h3><code>lua_gethook</code></h3> |
| 3351 | 3412 | <pre> |
| 3352 | 3413 | lua_Hook lua_gethook (lua_State *L); |
| 3353 | 3414 | </pre> |
| @@ -3356,7 +3417,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3356 | 3417 | <p>Returns the current hook function. |
| 3357 | 3418 | |
| 3358 | 3419 | <p><a name="lua_gethookcount"></a> |
| 3359 | | −<hr/><h3><code>lua_gethookcount</code></h3> |
| 3420 | +<hr /><h3><code>lua_gethookcount</code></h3> |
| 3360 | 3421 | <pre> |
| 3361 | 3422 | int lua_gethookcount (lua_State *L); |
| 3362 | 3423 | </pre> |
| @@ -3365,7 +3426,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3365 | 3426 | <p>Returns the current hook count. |
| 3366 | 3427 | |
| 3367 | 3428 | <p><a name="lua_gethookmask"></a> |
| 3368 | | −<hr/><h3><code>lua_gethookmask</code></h3> |
| 3429 | +<hr /><h3><code>lua_gethookmask</code></h3> |
| 3369 | 3430 | <pre> |
| 3370 | 3431 | int lua_gethookmask (lua_State *L); |
| 3371 | 3432 | </pre> |
| @@ -3374,7 +3435,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3374 | 3435 | <p>Returns the current hook mask. |
| 3375 | 3436 | |
| 3376 | 3437 | <p><a name="lua_getinfo"></a> |
| 3377 | | −<hr/><h3><code>lua_getinfo</code></h3> |
| 3438 | +<hr /><h3><code>lua_getinfo</code></h3> |
| 3378 | 3439 | <pre> |
| 3379 | 3440 | int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); |
| 3380 | 3441 | </pre> |
| @@ -3408,7 +3469,7 @@ you can write the following code: · 27 unmodified lines |
| 3408 | 3469 | </pre> |
| 3409 | 3470 | |
| 3410 | 3471 | <p><a name="lua_getlocal"></a> |
| 3411 | | −<hr/><h3><code>lua_getlocal</code></h3> |
| 3472 | +<hr /><h3><code>lua_getlocal</code></h3> |
| 3412 | 3473 | <pre> |
| 3413 | 3474 | const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); |
| 3414 | 3475 | </pre> |
| @@ -3421,7 +3482,7 @@ given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). · 6 unmodified lines |
| 3421 | 3482 | The index <code>n</code> selects which local variable to inspect |
| 3422 | 3483 | (1 is the first parameter or active local variable, and so on, |
| 3423 | 3484 | until the last active local variable). |
| 3424 | | −<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack, |
| 3485 | +<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack |
| 3425 | 3486 | and returns its name. |
| 3426 | 3487 | |
| 3427 | 3488 | <p>Variable names starting with `<code>(</code>´ (open parentheses) |
| @@ -3433,7 +3494,7 @@ when the index is greater than · 5 unmodified lines |
| 3433 | 3494 | the number of active local variables. |
| 3434 | 3495 | |
| 3435 | 3496 | <p><a name="lua_getstack"></a> |
| 3436 | | −<hr/><h3><code>lua_getstack</code></h3> |
| 3497 | +<hr /><h3><code>lua_getstack</code></h3> |
| 3437 | 3498 | <pre> |
| 3438 | 3499 | int lua_getstack (lua_State *L, int level, lua_Debug *ar); |
| 3439 | 3500 | </pre> |
| @@ -3451,7 +3512,7 @@ when called with a level greater than the stack depth, · 11 unmodified lines |
| 3451 | 3512 | it returns 0. |
| 3452 | 3513 | |
| 3453 | 3514 | <p><a name="lua_getupvalue"></a> |
| 3454 | | −<hr/><h3><code>lua_getupvalue</code></h3> |
| 3515 | +<hr /><h3><code>lua_getupvalue</code></h3> |
| 3455 | 3516 | <pre> |
| 3456 | 3517 | const char *lua_getupvalue (lua_State *L, int funcindex, int n); |
| 3457 | 3518 | </pre> |
| @@ -3466,7 +3527,8 @@ pushes the upvalue's value onto the stack, · 8 unmodified lines |
| 3466 | 3527 | and returns its name. |
| 3467 | 3528 | <code>funcindex</code> points to the closure in the stack. |
| 3468 | 3529 | (Upvalues have no particular order, |
| 3469 | | −as they are active through the whole function.) |
| 3530 | +as they are active through the whole function. |
| 3531 | +So, they are numbered in an arbitrary order.) |
| 3470 | 3532 | |
| 3471 | 3533 | <p>Returns <code>NULL</code> (and pushes nothing) |
| 3472 | 3534 | when the index is greater than the number of upvalues. |
| @@ -3474,7 +3536,7 @@ For C functions, this function uses the empty string <code>""</code> · 1 unmodified line |
| 3474 | 3536 | as a name for all upvalues. |
| 3475 | 3537 | |
| 3476 | 3538 | <p><a name="lua_Hook"></a> |
| 3477 | | −<hr/><h3><code>lua_Hook</code></h3> |
| 3539 | +<hr /><h3><code>lua_Hook</code></h3> |
| 3478 | 3540 | <pre> |
| 3479 | 3541 | typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); |
| 3480 | 3542 | </pre> |
| @@ -3502,7 +3564,7 @@ Therefore, if a hook calls back Lua to execute a function or a chunk, · 21 unmodified lines |
| 3502 | 3564 | that execution occurs without any calls to hooks. |
| 3503 | 3565 | |
| 3504 | 3566 | <p><a name="lua_sethook"></a> |
| 3505 | | −<hr/><h3><code>lua_sethook</code></h3> |
| 3567 | +<hr /><h3><code>lua_sethook</code></h3> |
| 3506 | 3568 | <pre> |
| 3507 | 3569 | int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); |
| 3508 | 3570 | </pre> |
| @@ -3512,7 +3574,7 @@ that execution occurs without any calls to hooks. · 3 unmodified lines |
| 3512 | 3574 | |
| 3513 | 3575 | <p><code>func</code> is the hook function. |
| 3514 | 3576 | <code>mask</code> specifies on which events the hook will be called: |
| 3515 | | −It is formed by a disjunction of the constants |
| 3577 | +It is formed by a bitwise or of the constants |
| 3516 | 3578 | <code>LUA_MASKCALL</code>, |
| 3517 | 3579 | <code>LUA_MASKRET</code>, |
| 3518 | 3580 | <code>LUA_MASKLINE</code>, |
| @@ -3522,9 +3584,11 @@ includes <code>LUA_MASKCOUNT</code>. · 3 unmodified lines |
| 3522 | 3584 | For each event, the hook is called as explained below: |
| 3523 | 3585 | <ul> |
| 3524 | 3586 | <li><b>The call hook</b> is called when the interpreter calls a function. |
| 3525 | | −The hook is called just after Lua enters the new function. |
| 3587 | +The hook is called just after Lua enters the new function, |
| 3588 | +before the function gets its arguments. |
| 3526 | 3589 | <li><b>The return hook</b> is called when the interpreter returns from a function. |
| 3527 | 3590 | The hook is called just before Lua leaves the function. |
| 3591 | +You have no access to the values to be returned by the function. |
| 3528 | 3592 | <li><b>The line hook</b> is called when the interpreter is about to |
| 3529 | 3593 | start the execution of a new line of code, |
| 3530 | 3594 | or when it jumps back in the code (even to the same line). |
| @@ -3537,14 +3601,14 @@ or when it jumps back in the code (even to the same line). · 6 unmodified lines |
| 3537 | 3601 | <p>A hook is disabled by setting <code>mask</code> to zero. |
| 3538 | 3602 | |
| 3539 | 3603 | <p><a name="lua_setlocal"></a> |
| 3540 | | −<hr/><h3><code>lua_setlocal</code></h3> |
| 3604 | +<hr /><h3><code>lua_setlocal</code></h3> |
| 3541 | 3605 | <pre> |
| 3542 | 3606 | const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); |
| 3543 | 3607 | </pre> |
| 3544 | 3608 | |
| 3545 | 3609 | |
| 3546 | 3610 | <p>Sets the value of a local variable of a given activation record. |
| 3547 | | −Parameters <code>ar</code> and <code>n</code> are like in <a href="#lua_getlocal"><code>lua_getlocal</code></a> |
| 3611 | +Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> |
| 3548 | 3612 | (see <a href="#lua_getlocal"></a>). |
| 3549 | 3613 | <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack |
| 3550 | 3614 | to the variable and returns its name. |
| @@ -3555,14 +3619,14 @@ when the index is greater than · 4 unmodified lines |
| 3555 | 3619 | the number of active local variables. |
| 3556 | 3620 | |
| 3557 | 3621 | <p><a name="lua_setupvalue"></a> |
| 3558 | | −<hr/><h3><code>lua_setupvalue</code></h3> |
| 3622 | +<hr /><h3><code>lua_setupvalue</code></h3> |
| 3559 | 3623 | <pre> |
| 3560 | 3624 | const char *lua_setupvalue (lua_State *L, int funcindex, int n); |
| 3561 | 3625 | </pre> |
| 3562 | 3626 | |
| 3563 | 3627 | |
| 3564 | 3628 | <p>Sets the value of a closure's upvalue. |
| 3565 | | −Parameters <code>funcindex</code> and <code>n</code> are like in <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> |
| 3629 | +Parameters <code>funcindex</code> and <code>n</code> are as in <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> |
| 3566 | 3630 | (see <a href="#lua_getupvalue"></a>). |
| 3567 | 3631 | It assigns the value at the top of the stack |
| 3568 | 3632 | to the upvalue and returns its name. |
| @@ -3586,17 +3650,17 @@ common tasks. · 17 unmodified lines |
| 3586 | 3650 | are defined in header file <code>lauxlib.h</code> and |
| 3587 | 3651 | have a prefix <code>luaL_</code>. |
| 3588 | 3652 | |
| 3589 | | −<p>All functions in the auxiliary library are build on |
| 3590 | | −top of the basic API, so they provide nothing that cannot |
| 3591 | | −be done with that API. |
| 3653 | +<p>All functions in the auxiliary library are built on |
| 3654 | +top of the basic API, |
| 3655 | +and so they provide nothing that cannot be done with that API. |
| 3592 | 3656 | |
| 3593 | 3657 | <p>Several functions in the auxiliary library are used to |
| 3594 | 3658 | check C function arguments. |
| 3595 | 3659 | Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. |
| 3596 | | −All those functions raise an error if the check is not satisfied. |
| 3660 | +All of these functions raise an error if the check is not satisfied. |
| 3597 | 3661 | Because the error message is formatted for arguments |
| 3598 | 3662 | (e.g., <code>"bad argument #1"</code>), |
| 3599 | | −you should not use those functions for other stack values. |
| 3663 | +you should not use these functions for other stack values. |
| 3600 | 3664 | |
| 3601 | 3665 | <p><a name="4.1"></a><h2>4.1 - Functions and Types</h2> |
| 3602 | 3666 | |
| @@ -3604,7 +3668,7 @@ you should not use those functions for other stack values. · 1 unmodified line |
| 3604 | 3668 | in alphabetical order. |
| 3605 | 3669 | |
| 3606 | 3670 | <p><a name="luaL_addchar"></a> |
| 3607 | | −<hr/><h3><code>luaL_addchar</code></h3> |
| 3671 | +<hr /><h3><code>luaL_addchar</code></h3> |
| 3608 | 3672 | <pre> |
| 3609 | 3673 | void luaL_addchar (luaL_Buffer B, char c); |
| 3610 | 3674 | </pre> |
| @@ -3614,7 +3678,7 @@ in alphabetical order. · 3 unmodified lines |
| 3614 | 3678 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3615 | 3679 | |
| 3616 | 3680 | <p><a name="luaL_addlstring"></a> |
| 3617 | | −<hr/><h3><code>luaL_addlstring</code></h3> |
| 3681 | +<hr /><h3><code>luaL_addlstring</code></h3> |
| 3618 | 3682 | <pre> |
| 3619 | 3683 | void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); |
| 3620 | 3684 | </pre> |
| @@ -3623,9 +3687,10 @@ in alphabetical order. · 2 unmodified lines |
| 3623 | 3687 | <p>Adds the string pointed by <code>s</code> with length <code>l</code> to |
| 3624 | 3688 | the buffer <code>B</code> |
| 3625 | 3689 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3690 | +The string may contain embedded zeros. |
| 3626 | 3691 | |
| 3627 | 3692 | <p><a name="luaL_addsize"></a> |
| 3628 | | −<hr/><h3><code>luaL_addsize</code></h3> |
| 3693 | +<hr /><h3><code>luaL_addsize</code></h3> |
| 3629 | 3694 | <pre> |
| 3630 | 3695 | void luaL_addsize (luaL_Buffer B, size_t n); |
| 3631 | 3696 | </pre> |
| @@ -3636,7 +3701,7 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to · 4 unmodified lines |
| 3636 | 3701 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3637 | 3702 | |
| 3638 | 3703 | <p><a name="luaL_addstring"></a> |
| 3639 | | −<hr/><h3><code>luaL_addstring</code></h3> |
| 3704 | +<hr /><h3><code>luaL_addstring</code></h3> |
| 3640 | 3705 | <pre> |
| 3641 | 3706 | void luaL_addstring (luaL_Buffer *B, const char *s); |
| 3642 | 3707 | </pre> |
| @@ -3645,9 +3710,10 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to · 2 unmodified lines |
| 3645 | 3710 | <p>Adds the zero-terminated string pointed by <code>s</code> |
| 3646 | 3711 | to the buffer <code>B</code> |
| 3647 | 3712 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3713 | +The string may not contain embedded zeros. |
| 3648 | 3714 | |
| 3649 | 3715 | <p><a name="luaL_addvalue"></a> |
| 3650 | | −<hr/><h3><code>luaL_addvalue</code></h3> |
| 3716 | +<hr /><h3><code>luaL_addvalue</code></h3> |
| 3651 | 3717 | <pre> |
| 3652 | 3718 | void luaL_addvalue (luaL_Buffer *B); |
| 3653 | 3719 | </pre> |
| @@ -3663,7 +3729,7 @@ be called with an extra element on the stack, · 9 unmodified lines |
| 3663 | 3729 | which is the value to be added to the buffer. |
| 3664 | 3730 | |
| 3665 | 3731 | <p><a name="luaL_argcheck"></a> |
| 3666 | | −<hr/><h3><code>luaL_argcheck</code></h3> |
| 3732 | +<hr /><h3><code>luaL_argcheck</code></h3> |
| 3667 | 3733 | <pre> |
| 3668 | 3734 | void luaL_argcheck (lua_State *L, int cond, int numarg, |
| 3669 | 3735 | const char *extramsg); |
| @@ -3671,12 +3737,12 @@ which is the value to be added to the buffer. · 1 unmodified line |
| 3671 | 3737 | |
| 3672 | 3738 | |
| 3673 | 3739 | <p>Checks whether <code>cond</code> is true. |
| 3674 | | −If not, raise an error with message |
| 3740 | +If not, raises an error with message |
| 3675 | 3741 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, |
| 3676 | 3742 | where <code>func</code> is retrieved from the call stack. |
| 3677 | 3743 | |
| 3678 | 3744 | <p><a name="luaL_argerror"></a> |
| 3679 | | −<hr/><h3><code>luaL_argerror</code></h3> |
| 3745 | +<hr /><h3><code>luaL_argerror</code></h3> |
| 3680 | 3746 | <pre> |
| 3681 | 3747 | int luaL_argerror (lua_State *L, int numarg, const char *extramsg); |
| 3682 | 3748 | </pre> |
| @@ -3686,10 +3752,12 @@ where <code>func</code> is retrieved from the call stack. · 3 unmodified lines |
| 3686 | 3752 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, |
| 3687 | 3753 | where <code>func</code> is retrieved from the call stack. |
| 3688 | 3754 | |
| 3689 | | −<p>This function never returns. |
| 3755 | +<p>This function never returns, |
| 3756 | +but it is an idiom to use it as <code>return luaL_argerror ...</code> |
| 3757 | +in C functions. |
| 3690 | 3758 | |
| 3691 | 3759 | <p><a name="luaL_Buffer"></a> |
| 3692 | | −<hr/><h3><code>luaL_Buffer</code></h3> |
| 3760 | +<hr /><h3><code>luaL_Buffer</code></h3> |
| 3693 | 3761 | <pre> |
| 3694 | 3762 | typedef struct luaL_Buffer luaL_Buffer; |
| 3695 | 3763 | </pre> |
| @@ -3700,21 +3768,23 @@ where <code>func</code> is retrieved from the call stack. · 4 unmodified lines |
| 3700 | 3768 | <p>A string buffer allows C code to build Lua strings piecemeal. |
| 3701 | 3769 | Its pattern of use is as follows: |
| 3702 | 3770 | <ul> |
| 3703 | | −<li> Fist you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>. |
| 3704 | | −<li> Then you initialize it with a call <code>luaL_buffinit(L, &b);</code>. |
| 3771 | +<li> First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>. |
| 3772 | +<li> Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>. |
| 3705 | 3773 | <li> Then you add string pieces to the buffer calling any of |
| 3706 | 3774 | the <code>luaL_add*</code> functions. |
| 3707 | 3775 | <li> You finish calling <code>luaL_pushresult(&b)</code>. |
| 3708 | 3776 | That call leaves the final string on the top of the stack. |
| 3709 | 3777 | </ul> |
| 3710 | 3778 | |
| 3711 | | −<p>During its normal operation a string buffer uses a |
| 3712 | | −variable number of stack slots. |
| 3779 | +<p>During its normal operation, |
| 3780 | +a string buffer uses a variable number of stack slots. |
| 3713 | 3781 | So, while using a buffer, you cannot assume that you know where |
| 3714 | | −is the top of the stack. |
| 3715 | | −You can use the stack between successive calls to buffer operations, |
| 3716 | | −as long as that use is balanced, that is, |
| 3717 | | −when you call a buffer operation the stack is at the same level |
| 3782 | +the top of the stack is. |
| 3783 | +You can use the stack between successive calls to buffer operations |
| 3784 | +as long as that use is balanced; |
| 3785 | +that is, |
| 3786 | +when you call a buffer operation, |
| 3787 | +the stack is at the same level |
| 3718 | 3788 | it was immediately after the previous buffer operation. |
| 3719 | 3789 | (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) |
| 3720 | 3790 | After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its |
| @@ -3722,7 +3792,7 @@ level when the buffer was initialized, · 1 unmodified line |
| 3722 | 3792 | plus the final string on its top. |
| 3723 | 3793 | |
| 3724 | 3794 | <p><a name="luaL_buffinit"></a> |
| 3725 | | −<hr/><h3><code>luaL_buffinit</code></h3> |
| 3795 | +<hr /><h3><code>luaL_buffinit</code></h3> |
| 3726 | 3796 | <pre> |
| 3727 | 3797 | void luaL_buffinit (lua_State *L, luaL_Buffer *B); |
| 3728 | 3798 | </pre> |
| @@ -3734,7 +3804,7 @@ the buffer must be declared as a variable · 5 unmodified lines |
| 3734 | 3804 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3735 | 3805 | |
| 3736 | 3806 | <p><a name="luaL_callmeta"></a> |
| 3737 | | −<hr/><h3><code>luaL_callmeta</code></h3> |
| 3807 | +<hr /><h3><code>luaL_callmeta</code></h3> |
| 3738 | 3808 | <pre> |
| 3739 | 3809 | int luaL_callmeta (lua_State *L, int obj, const char *e); |
| 3740 | 3810 | </pre> |
| @@ -3744,53 +3814,54 @@ the buffer must be declared as a variable · 3 unmodified lines |
| 3744 | 3814 | |
| 3745 | 3815 | <p>If the object at index <code>obj</code> has a metatable and that |
| 3746 | 3816 | metatable has a field <code>e</code>, |
| 3747 | | −calls that field passing the object as argument. |
| 3748 | | −In that case the function returns 1 and pushes on the |
| 3817 | +this function calls that field and passes the object as its only argument. |
| 3818 | +In that case this function returns 1 and pushes on the |
| 3749 | 3819 | stack the value returned by the call. |
| 3750 | | −If there is no metatable or no metamethod returns 0 |
| 3751 | | −(without pushing any value on the stack). |
| 3820 | +If there is no metatable or no metamethod, |
| 3821 | +this function returns 0 (without pushing any value on the stack). |
| 3752 | 3822 | |
| 3753 | 3823 | <p><a name="luaL_checkany"></a> |
| 3754 | | −<hr/><h3><code>luaL_checkany</code></h3> |
| 3824 | +<hr /><h3><code>luaL_checkany</code></h3> |
| 3755 | 3825 | <pre> |
| 3756 | 3826 | void luaL_checkany (lua_State *L, int narg); |
| 3757 | 3827 | </pre> |
| 3758 | 3828 | |
| 3759 | 3829 | |
| 3760 | | −<p>Checks whether the function has an argument <code>narg</code>. |
| 3830 | +<p>Checks whether the function has an argument |
| 3831 | +of any type (including <b>nil</b>) at position <code>narg</code>. |
| 3761 | 3832 | |
| 3762 | 3833 | <p><a name="luaL_checkint"></a> |
| 3763 | | −<hr/><h3><code>luaL_checkint</code></h3> |
| 3834 | +<hr /><h3><code>luaL_checkint</code></h3> |
| 3764 | 3835 | <pre> |
| 3765 | 3836 | int luaL_checkint (lua_State *L, int narg); |
| 3766 | 3837 | </pre> |
| 3767 | 3838 | |
| 3768 | 3839 | |
| 3769 | 3840 | <p>Checks whether the function argument <code>narg</code> is a number |
| 3770 | | −and returns that number casted to an <code>int</code>. |
| 3841 | +and returns that number cast to an <code>int</code>. |
| 3771 | 3842 | |
| 3772 | 3843 | <p><a name="luaL_checkinteger"></a> |
| 3773 | | −<hr/><h3><code>luaL_checkinteger</code></h3> |
| 3844 | +<hr /><h3><code>luaL_checkinteger</code></h3> |
| 3774 | 3845 | <pre> |
| 3775 | | − lua_Integer luaL_checkinteger (lua_State *L, int numArg); |
| 3846 | + lua_Integer luaL_checkinteger (lua_State *L, int narg); |
| 3776 | 3847 | </pre> |
| 3777 | 3848 | |
| 3778 | 3849 | |
| 3779 | 3850 | <p>Checks whether the function argument <code>narg</code> is a number |
| 3780 | | −and returns that number casted to a <a href="#lua_Integer"><code>lua_Integer</code></a>. |
| 3851 | +and returns that number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. |
| 3781 | 3852 | |
| 3782 | 3853 | <p><a name="luaL_checklong"></a> |
| 3783 | | −<hr/><h3><code>luaL_checklong</code></h3> |
| 3854 | +<hr /><h3><code>luaL_checklong</code></h3> |
| 3784 | 3855 | <pre> |
| 3785 | 3856 | long luaL_checklong (lua_State *L, int narg); |
| 3786 | 3857 | </pre> |
| 3787 | 3858 | |
| 3788 | 3859 | |
| 3789 | 3860 | <p>Checks whether the function argument <code>narg</code> is a number |
| 3790 | | −and returns that number casted to a <code>long</code>. |
| 3861 | +and returns that number cast to a <code>long</code>. |
| 3791 | 3862 | |
| 3792 | 3863 | <p><a name="luaL_checklstring"></a> |
| 3793 | | −<hr/><h3><code>luaL_checklstring</code></h3> |
| 3864 | +<hr /><h3><code>luaL_checklstring</code></h3> |
| 3794 | 3865 | <pre> |
| 3795 | 3866 | const char *luaL_checklstring (lua_State *L, int numArg, size_t *l); |
| 3796 | 3867 | </pre> |
| @@ -3798,11 +3869,11 @@ and returns that number casted to a <code>long</code>. · 1 unmodified line |
| 3798 | 3869 | |
| 3799 | 3870 | <p>Checks whether the function argument <code>narg</code> is a string |
| 3800 | 3871 | and returns that string; |
| 3801 | | −if <code>l</code> is not <code>NULL</code> fills the position <code>*l</code> |
| 3872 | +if <code>l</code> is not <code>NULL</code> fills <code>*l</code> |
| 3802 | 3873 | with the string's length. |
| 3803 | 3874 | |
| 3804 | 3875 | <p><a name="luaL_checknumber"></a> |
| 3805 | | −<hr/><h3><code>luaL_checknumber</code></h3> |
| 3876 | +<hr /><h3><code>luaL_checknumber</code></h3> |
| 3806 | 3877 | <pre> |
| 3807 | 3878 | lua_Number luaL_checknumber (lua_State *L, int numArg); |
| 3808 | 3879 | </pre> |
| @@ -3812,7 +3883,7 @@ with the string's length. · 3 unmodified lines |
| 3812 | 3883 | and returns that number. |
| 3813 | 3884 | |
| 3814 | 3885 | <p><a name="luaL_checkoption"></a> |
| 3815 | | −<hr/><h3><code>luaL_checkoption</code></h3> |
| 3886 | +<hr /><h3><code>luaL_checkoption</code></h3> |
| 3816 | 3887 | <pre> |
| 3817 | 3888 | int luaL_checkoption (lua_State *L, int narg, const char *def, |
| 3818 | 3889 | const char *const lst[]); |
| @@ -3830,8 +3901,12 @@ the function has no argument <code>narg</code> or if that argument is <b>nil</b> · 11 unmodified lines |
| 3830 | 3901 | Raises an error if the argument is not a string or |
| 3831 | 3902 | if the string cannot be found. |
| 3832 | 3903 | |
| 3904 | +<p>This is a useful function for mapping strings to C enums. |
| 3905 | +The usual interfaces in Lua libraries is to use strings instead of numbers |
| 3906 | +to select options. |
| 3907 | + |
| 3833 | 3908 | <p><a name="luaL_checkstack"></a> |
| 3834 | | −<hr/><h3><code>luaL_checkstack</code></h3> |
| 3909 | +<hr /><h3><code>luaL_checkstack</code></h3> |
| 3835 | 3910 | <pre> |
| 3836 | 3911 | void luaL_checkstack (lua_State *L, int sz, const char *msg); |
| 3837 | 3912 | </pre> |
| @@ -3842,7 +3917,7 @@ raising an error if the stack cannot grow to that size. · 4 unmodified lines |
| 3842 | 3917 | <code>msg</code> is an additional text to go into the error message. |
| 3843 | 3918 | |
| 3844 | 3919 | <p><a name="luaL_checkstring"></a> |
| 3845 | | −<hr/><h3><code>luaL_checkstring</code></h3> |
| 3920 | +<hr /><h3><code>luaL_checkstring</code></h3> |
| 3846 | 3921 | <pre> |
| 3847 | 3922 | const char *luaL_checkstring (lua_State *L, int narg); |
| 3848 | 3923 | </pre> |
| @@ -3852,7 +3927,7 @@ raising an error if the stack cannot grow to that size. · 3 unmodified lines |
| 3852 | 3927 | and returns that string. |
| 3853 | 3928 | |
| 3854 | 3929 | <p><a name="luaL_checktype"></a> |
| 3855 | | −<hr/><h3><code>luaL_checktype</code></h3> |
| 3930 | +<hr /><h3><code>luaL_checktype</code></h3> |
| 3856 | 3931 | <pre> |
| 3857 | 3932 | void luaL_checktype (lua_State *L, int narg, int t); |
| 3858 | 3933 | </pre> |
| @@ -3861,7 +3936,7 @@ and returns that string. · 2 unmodified lines |
| 3861 | 3936 | <p>Checks whether the function argument <code>narg</code> has type <code>t</code>. |
| 3862 | 3937 | |
| 3863 | 3938 | <p><a name="luaL_checkudata"></a> |
| 3864 | | −<hr/><h3><code>luaL_checkudata</code></h3> |
| 3939 | +<hr /><h3><code>luaL_checkudata</code></h3> |
| 3865 | 3940 | <pre> |
| 3866 | 3941 | void *luaL_checkudata (lua_State *L, int ud, const char *tname); |
| 3867 | 3942 | </pre> |
| @@ -3871,7 +3946,7 @@ and returns that string. · 3 unmodified lines |
| 3871 | 3946 | of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). |
| 3872 | 3947 | |
| 3873 | 3948 | <p><a name="luaL_error"></a> |
| 3874 | | −<hr/><h3><code>luaL_error</code></h3> |
| 3949 | +<hr /><h3><code>luaL_error</code></h3> |
| 3875 | 3950 | <pre> |
| 3876 | 3951 | int luaL_error (lua_State *L, const char *fmt, ...); |
| 3877 | 3952 | </pre> |
| @@ -3885,10 +3960,12 @@ It also adds at the beginning of the message the file name and · 7 unmodified lines |
| 3885 | 3960 | the line number where the error occurred, |
| 3886 | 3961 | if that information is available. |
| 3887 | 3962 | |
| 3888 | | −<p>This function never returns. |
| 3963 | +<p>This function never returns, |
| 3964 | +but it is an idiom to use it as <code>return luaL_error ...</code> |
| 3965 | +in C functions. |
| 3889 | 3966 | |
| 3890 | 3967 | <p><a name="luaL_getmetafield"></a> |
| 3891 | | −<hr/><h3><code>luaL_getmetafield</code></h3> |
| 3968 | +<hr /><h3><code>luaL_getmetafield</code></h3> |
| 3892 | 3969 | <pre> |
| 3893 | 3970 | int luaL_getmetafield (lua_State *L, int obj, const char *e); |
| 3894 | 3971 | </pre> |
| @@ -3898,10 +3975,10 @@ if that information is available. · 3 unmodified lines |
| 3898 | 3975 | of the object at index <code>obj</code>. |
| 3899 | 3976 | If the object does not have a metatable, |
| 3900 | 3977 | or if the metatable does not have that field, |
| 3901 | | −returns 0 (false) and pushes nothing. |
| 3978 | +returns 0 and pushes nothing. |
| 3902 | 3979 | |
| 3903 | 3980 | <p><a name="luaL_getmetatable"></a> |
| 3904 | | −<hr/><h3><code>luaL_getmetatable</code></h3> |
| 3981 | +<hr /><h3><code>luaL_getmetatable</code></h3> |
| 3905 | 3982 | <pre> |
| 3906 | 3983 | void luaL_getmetatable (lua_State *L, const char *tname); |
| 3907 | 3984 | </pre> |
| @@ -3911,19 +3988,20 @@ returns 0 (false) and pushes nothing. · 3 unmodified lines |
| 3911 | 3988 | in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). |
| 3912 | 3989 | |
| 3913 | 3990 | <p><a name="luaL_gsub"></a> |
| 3914 | | −<hr/><h3><code>luaL_gsub</code></h3> |
| 3991 | +<hr /><h3><code>luaL_gsub</code></h3> |
| 3915 | 3992 | <pre> |
| 3916 | 3993 | const char *luaL_gsub (lua_State *L, const char *s, |
| 3917 | 3994 | const char *p, const char *r); |
| 3918 | 3995 | </pre> |
| 3919 | 3996 | |
| 3920 | 3997 | |
| 3921 | | −<p>Creates a copy of string <code>s</code> changing any occurrence of <code>p</code> |
| 3922 | | −by the string <code>r</code>. |
| 3998 | +<p>Creates a copy of string <code>s</code> by replacing any occurrence |
| 3999 | +any occurrence of the string <code>p</code> |
| 4000 | +wth the string <code>r</code>. |
| 3923 | 4001 | Pushes the resulting string on the stack and returns it. |
| 3924 | 4002 | |
| 3925 | 4003 | <p><a name="luaL_loadbuffer"></a> |
| 3926 | | −<hr/><h3><code>luaL_loadbuffer</code></h3> |
| 4004 | +<hr /><h3><code>luaL_loadbuffer</code></h3> |
| 3927 | 4005 | <pre> |
| 3928 | 4006 | int luaL_loadbuffer (lua_State *L, const char *buff, |
| 3929 | 4007 | size_t sz, const char *name); |
| @@ -3939,7 +4017,7 @@ buffer pointed by <code>buff</code> with size <code>sz</code>. · 9 unmodified lines |
| 3939 | 4017 | used for debug information and error messages. |
| 3940 | 4018 | |
| 3941 | 4019 | <p><a name="luaL_loadfile"></a> |
| 3942 | | −<hr/><h3><code>luaL_loadfile</code></h3> |
| 4020 | +<hr /><h3><code>luaL_loadfile</code></h3> |
| 3943 | 4021 | <pre> |
| 3944 | 4022 | int luaL_loadfile (lua_State *L, const char *filename); |
| 3945 | 4023 | </pre> |
| @@ -3948,14 +4026,16 @@ used for debug information and error messages. · 2 unmodified lines |
| 3948 | 4026 | <p>Loads a file as a Lua chunk. |
| 3949 | 4027 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file |
| 3950 | 4028 | named <code>filename</code>. |
| 3951 | | −If the file's first line starts with a <code>#</code> it is ignored. |
| 4029 | +If <code>filename</code> is <code>NULL</code>, |
| 4030 | +then it loads from the standard input. |
| 4031 | +The first line in the file is ignored if it starts with a <code>#</code>. |
| 3952 | 4032 | |
| 3953 | 4033 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, |
| 3954 | 4034 | but it has an extra error code <code>LUA_ERRFILE</code> |
| 3955 | | −if it cannot open the file. |
| 4035 | +if it cannot open/read the file. |
| 3956 | 4036 | |
| 3957 | 4037 | <p><a name="luaL_loadstring"></a> |
| 3958 | | −<hr/><h3><code>luaL_loadstring</code></h3> |
| 4038 | +<hr /><h3><code>luaL_loadstring</code></h3> |
| 3959 | 4039 | <pre> |
| 3960 | 4040 | int luaL_loadstring (lua_State *L, const char *s); |
| 3961 | 4041 | </pre> |
| @@ -3968,24 +4048,24 @@ the zero-terminated string <code>s</code>. · 6 unmodified lines |
| 3968 | 4048 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. |
| 3969 | 4049 | |
| 3970 | 4050 | <p><a name="luaL_newmetatable"></a> |
| 3971 | | −<hr/><h3><code>luaL_newmetatable</code></h3> |
| 4051 | +<hr /><h3><code>luaL_newmetatable</code></h3> |
| 3972 | 4052 | <pre> |
| 3973 | 4053 | int luaL_newmetatable (lua_State *L, const char *tname); |
| 3974 | 4054 | </pre> |
| 3975 | 4055 | |
| 3976 | 4056 | |
| 3977 | | −<p>If the register already has the key <code>"tname"</code>, |
| 4057 | +<p>If the registry already has the key <code>"tname"</code>, |
| 3978 | 4058 | returns 0. |
| 3979 | 4059 | Otherwise, |
| 3980 | | −creates a new table to be used as metatables for userdata, |
| 3981 | | −adds it to the register with key <code>"tname"</code>, |
| 4060 | +creates a new table to be used as a metatable for userdata, |
| 4061 | +adds it to the registry with key <code>"tname"</code>, |
| 3982 | 4062 | and returns 1. |
| 3983 | 4063 | |
| 3984 | 4064 | <p>In both cases pushes on the stack the final value associated |
| 3985 | 4065 | with <code>"tname"</code> in the registry. |
| 3986 | 4066 | |
| 3987 | 4067 | <p><a name="luaL_newstate"></a> |
| 3988 | | −<hr/><h3><code>luaL_newstate</code></h3> |
| 4068 | +<hr /><h3><code>luaL_newstate</code></h3> |
| 3989 | 4069 | <pre> |
| 3990 | 4070 | lua_State *luaL_newstate (void); |
| 3991 | 4071 | </pre> |
| @@ -3993,7 +4073,7 @@ with <code>"tname"</code> in the registry. · 1 unmodified line |
| 3993 | 4073 | |
| 3994 | 4074 | <p>Creates a new Lua state, calling <a href="#lua_newstate"><code>lua_newstate</code></a> with an |
| 3995 | 4075 | allocation function based on the standard C <code>realloc</code> function |
| 3996 | | −and setting a panic function ((see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)) that prints |
| 4076 | +and setting a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints |
| 3997 | 4077 | an error message to the standard error output in case of fatal |
| 3998 | 4078 | errors. |
| 3999 | 4079 | |
| @@ -4001,46 +4081,46 @@ errors. · 1 unmodified line |
| 4001 | 4081 | or <code>NULL</code> if there is a memory allocation error. |
| 4002 | 4082 | |
| 4003 | 4083 | <p><a name="luaL_optint"></a> |
| 4004 | | −<hr/><h3><code>luaL_optint</code></h3> |
| 4084 | +<hr /><h3><code>luaL_optint</code></h3> |
| 4005 | 4085 | <pre> |
| 4006 | 4086 | int luaL_optint (lua_State *L, int narg, int d); |
| 4007 | 4087 | </pre> |
| 4008 | 4088 | |
| 4009 | 4089 | |
| 4010 | 4090 | <p>If the function argument <code>narg</code> is a number, |
| 4011 | | −returns that number casted to an <code>int</code>. |
| 4091 | +returns that number cast to an <code>int</code>. |
| 4012 | 4092 | If that argument is absent or is <b>nil</b>, |
| 4013 | 4093 | returns <code>d</code>. |
| 4014 | | −Otherwise, raise an error. |
| 4094 | +Otherwise, raises an error. |
| 4015 | 4095 | |
| 4016 | 4096 | <p><a name="luaL_optinteger"></a> |
| 4017 | | −<hr/><h3><code>luaL_optinteger</code></h3> |
| 4097 | +<hr /><h3><code>luaL_optinteger</code></h3> |
| 4018 | 4098 | <pre> |
| 4019 | 4099 | lua_Integer luaL_optinteger (lua_State *L, int nArg, lua_Integer d); |
| 4020 | 4100 | </pre> |
| 4021 | 4101 | |
| 4022 | 4102 | |
| 4023 | 4103 | <p>If the function argument <code>narg</code> is a number, |
| 4024 | | −returns that number casted to a <a href="#lua_Integer"><code>lua_Integer</code></a>. |
| 4104 | +returns that number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. |
| 4025 | 4105 | If that argument is absent or is <b>nil</b>, |
| 4026 | 4106 | returns <code>d</code>. |
| 4027 | | −Otherwise, raise an error. |
| 4107 | +Otherwise, raises an error. |
| 4028 | 4108 | |
| 4029 | 4109 | <p><a name="luaL_optlong"></a> |
| 4030 | | −<hr/><h3><code>luaL_optlong</code></h3> |
| 4110 | +<hr /><h3><code>luaL_optlong</code></h3> |
| 4031 | 4111 | <pre> |
| 4032 | 4112 | long luaL_optlong (lua_State *L, int narg, long d); |
| 4033 | 4113 | </pre> |
| 4034 | 4114 | |
| 4035 | 4115 | |
| 4036 | 4116 | <p>If the function argument <code>narg</code> is a number, |
| 4037 | | −returns that number casted to a <code>long</code>. |
| 4117 | +returns that number cast to a <code>long</code>. |
| 4038 | 4118 | If that argument is absent or is <b>nil</b>, |
| 4039 | 4119 | returns <code>d</code>. |
| 4040 | | −Otherwise, raise an error. |
| 4120 | +Otherwise, raises an error. |
| 4041 | 4121 | |
| 4042 | 4122 | <p><a name="luaL_optlstring"></a> |
| 4043 | | −<hr/><h3><code>luaL_optlstring</code></h3> |
| 4123 | +<hr /><h3><code>luaL_optlstring</code></h3> |
| 4044 | 4124 | <pre> |
| 4045 | 4125 | const char *luaL_optlstring (lua_State *L, int numArg, |
| 4046 | 4126 | const char *d, size_t *l); |
| @@ -4051,13 +4131,13 @@ Otherwise, raise an error. · 4 unmodified lines |
| 4051 | 4131 | returns that string. |
| 4052 | 4132 | If that argument is absent or is <b>nil</b>, |
| 4053 | 4133 | returns <code>d</code>. |
| 4054 | | −Otherwise, raise an error. |
| 4134 | +Otherwise, raises an error. |
| 4055 | 4135 | |
| 4056 | | −<p>If <code>l</code> is not <code>NULL</code> fills the position <code>*l</code> |
| 4057 | | −with the results's length. |
| 4136 | +<p>If <code>l</code> is not <code>NULL</code>, |
| 4137 | +fills the position <code>*l</code> with the results's length. |
| 4058 | 4138 | |
| 4059 | 4139 | <p><a name="luaL_optnumber"></a> |
| 4060 | | −<hr/><h3><code>luaL_optnumber</code></h3> |
| 4140 | +<hr /><h3><code>luaL_optnumber</code></h3> |
| 4061 | 4141 | <pre> |
| 4062 | 4142 | lua_Number luaL_optnumber (lua_State *L, int nArg, lua_Number d); |
| 4063 | 4143 | </pre> |
| @@ -4067,10 +4147,10 @@ with the results's length. · 3 unmodified lines |
| 4067 | 4147 | returns that number. |
| 4068 | 4148 | If that argument is absent or is <b>nil</b>, |
| 4069 | 4149 | returns <code>d</code>. |
| 4070 | | −Otherwise, raise an error. |
| 4150 | +Otherwise, raises an error. |
| 4071 | 4151 | |
| 4072 | 4152 | <p><a name="luaL_optstring"></a> |
| 4073 | | −<hr/><h3><code>luaL_optstring</code></h3> |
| 4153 | +<hr /><h3><code>luaL_optstring</code></h3> |
| 4074 | 4154 | <pre> |
| 4075 | 4155 | const char *luaL_optstring (lua_State *L, int narg, const char *d); |
| 4076 | 4156 | </pre> |
| @@ -4080,24 +4160,24 @@ Otherwise, raise an error. · 3 unmodified lines |
| 4080 | 4160 | returns that string. |
| 4081 | 4161 | If that argument is absent or is <b>nil</b>, |
| 4082 | 4162 | returns <code>d</code>. |
| 4083 | | −Otherwise, raise an error. |
| 4163 | +Otherwise, raises an error. |
| 4084 | 4164 | |
| 4085 | 4165 | <p><a name="luaL_prepbuffer"></a> |
| 4086 | | −<hr/><h3><code>luaL_prepbuffer</code></h3> |
| 4166 | +<hr /><h3><code>luaL_prepbuffer</code></h3> |
| 4087 | 4167 | <pre> |
| 4088 | 4168 | char *luaL_prepbuffer (luaL_Buffer *B); |
| 4089 | 4169 | </pre> |
| 4090 | 4170 | |
| 4091 | 4171 | |
| 4092 | 4172 | <p>Returns an address to a space of size <code>LUAL_BUFFERSIZE</code> |
| 4093 | | −wherein you can copy a string to be added to buffer <code>B</code> |
| 4173 | +where you can copy a string to be added to buffer <code>B</code> |
| 4094 | 4174 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 4095 | 4175 | After copying the string into that space you must call |
| 4096 | 4176 | <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add |
| 4097 | 4177 | it to the buffer. |
| 4098 | 4178 | |
| 4099 | 4179 | <p><a name="luaL_pushresult"></a> |
| 4100 | | −<hr/><h3><code>luaL_pushresult</code></h3> |
| 4180 | +<hr /><h3><code>luaL_pushresult</code></h3> |
| 4101 | 4181 | <pre> |
| 4102 | 4182 | void luaL_pushresult (luaL_Buffer *B); |
| 4103 | 4183 | </pre> |
| @@ -4107,7 +4187,7 @@ it to the buffer. · 3 unmodified lines |
| 4107 | 4187 | the top of the stack. |
| 4108 | 4188 | |
| 4109 | 4189 | <p><a name="luaL_ref"></a> |
| 4110 | | −<hr/><h3><code>luaL_ref</code></h3> |
| 4190 | +<hr /><h3><code>luaL_ref</code></h3> |
| 4111 | 4191 | <pre> |
| 4112 | 4192 | int luaL_ref (lua_State *L, int t); |
| 4113 | 4193 | </pre> |
| @@ -4118,19 +4198,19 @@ in the table at index <code>t</code>, · 4 unmodified lines |
| 4118 | 4198 | for the object at the top of the stack (and pops the object). |
| 4119 | 4199 | |
| 4120 | 4200 | <p>A reference is a unique integer key. |
| 4121 | | −As long as you do not add integer keys into table <code>t</code>, |
| 4201 | +As long as you do not manually add integer keys into table <code>t</code>, |
| 4122 | 4202 | <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. |
| 4123 | 4203 | You can retrieve an object referred by reference <code>r</code> |
| 4124 | | −calling <code>lua_rawgeti(L, t, r)</code>. |
| 4204 | +by calling <code>lua_rawgeti(L, t, r)</code>. |
| 4125 | 4205 | Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. |
| 4126 | 4206 | |
| 4127 | | −<p>Whenever the object at the top of the stack is <b>nil</b>, |
| 4207 | +<p>If the object at the top of the stack is <b>nil</b>, |
| 4128 | 4208 | <a href="#luaL_ref"><code>luaL_ref</code></a> returns the same reference <code>LUA_REFNIL</code>. |
| 4129 | | −The constant <code>LUA_NOREF</code> is garanteed to be different |
| 4209 | +The constant <code>LUA_NOREF</code> is guaranteed to be different |
| 4130 | 4210 | from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. |
| 4131 | 4211 | |
| 4132 | 4212 | <p><a name="luaL_Reg"></a> |
| 4133 | | −<hr/><h3><code>luaL_Reg</code></h3> |
| 4213 | +<hr /><h3><code>luaL_Reg</code></h3> |
| 4134 | 4214 | <pre> |
| 4135 | 4215 | typedef struct luaL_Reg { |
| 4136 | 4216 | const char *name; |
| @@ -4140,15 +4220,15 @@ from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. · 3 unmodified lines |
| 4140 | 4220 | </pre> |
| 4141 | 4221 | |
| 4142 | 4222 | |
| 4143 | | −<p>Format for arrays of functions to be registered by |
| 4223 | +<p>Type for arrays of functions to be registered by |
| 4144 | 4224 | <a href="#luaL_register"><code>luaL_register</code></a>. |
| 4145 | 4225 | <code>name</code> is the function name and <code>func</code> is a pointer to |
| 4146 | 4226 | the function. |
| 4147 | 4227 | Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry |
| 4148 | | −wherein both <code>name</code> and <code>func</code> are <code>NULL</code>. |
| 4228 | +in which both <code>name</code> and <code>func</code> are <code>NULL</code>. |
| 4149 | 4229 | |
| 4150 | 4230 | <p><a name="luaL_register"></a> |
| 4151 | | −<hr/><h3><code>luaL_register</code></h3> |
| 4231 | +<hr /><h3><code>luaL_register</code></h3> |
| 4152 | 4232 | <pre> |
| 4153 | 4233 | void luaL_register (lua_State *L, const char *libname, |
| 4154 | 4234 | const luaL_Reg *l); |
| @@ -4163,7 +4243,7 @@ simply registers all functions in the list <code>l</code> · 8 unmodified lines |
| 4163 | 4243 | |
| 4164 | 4244 | <p>When called with a non-null <code>libname</code>, |
| 4165 | 4245 | creates a new table <code>t</code>, |
| 4166 | | −sets it as the value of the variable <code>libname</code>, |
| 4246 | +sets it as the value of the global variable <code>libname</code>, |
| 4167 | 4247 | sets it as the value of <code>package.loaded[libname]</code>, |
| 4168 | 4248 | and registers on it all functions in the list <code>l</code>. |
| 4169 | 4249 | If there is a table in <code>package.loaded[libname]</code> or in |
| @@ -4174,7 +4254,7 @@ reuses that table instead of creating a new one. · 4 unmodified lines |
| 4174 | 4254 | on the top of the stack. |
| 4175 | 4255 | |
| 4176 | 4256 | <p><a name="luaL_typename"></a> |
| 4177 | | −<hr/><h3><code>luaL_typename</code></h3> |
| 4257 | +<hr /><h3><code>luaL_typename</code></h3> |
| 4178 | 4258 | <pre> |
| 4179 | 4259 | const char *luaL_typename (lua_State *L, int idx); |
| 4180 | 4260 | </pre> |
| @@ -4183,7 +4263,7 @@ on the top of the stack. · 2 unmodified lines |
| 4183 | 4263 | <p>Returns the name of the type of the value at index <code>idx</code>. |
| 4184 | 4264 | |
| 4185 | 4265 | <p><a name="luaL_typerror"></a> |
| 4186 | | −<hr/><h3><code>luaL_typerror</code></h3> |
| 4266 | +<hr /><h3><code>luaL_typerror</code></h3> |
| 4187 | 4267 | <pre> |
| 4188 | 4268 | int luaL_typerror (lua_State *L, int narg, const char *tname); |
| 4189 | 4269 | </pre> |
| @@ -4198,7 +4278,7 @@ where <code><location></code> is produced by <a href="#luaL_where"><code>lu · 8 unmodified lines |
| 4198 | 4278 | and <code><realt></code> is the type name of the actual argument. |
| 4199 | 4279 | |
| 4200 | 4280 | <p><a name="luaL_unref"></a> |
| 4201 | | −<hr/><h3><code>luaL_unref</code></h3> |
| 4281 | +<hr /><h3><code>luaL_unref</code></h3> |
| 4202 | 4282 | <pre> |
| 4203 | 4283 | void luaL_unref (lua_State *L, int t, int ref); |
| 4204 | 4284 | </pre> |
| @@ -4214,7 +4294,7 @@ The reference <code>ref</code> is also freed to be used again. · 9 unmodified lines |
| 4214 | 4294 | <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. |
| 4215 | 4295 | |
| 4216 | 4296 | <p><a name="luaL_where"></a> |
| 4217 | | −<hr/><h3><code>luaL_where</code></h3> |
| 4297 | +<hr /><h3><code>luaL_where</code></h3> |
| 4218 | 4298 | <pre> |
| 4219 | 4299 | void luaL_where (lua_State *L, int lvl); |
| 4220 | 4300 | </pre> |
| @@ -4224,20 +4304,21 @@ The reference <code>ref</code> is also freed to be used again. · 3 unmodified lines |
| 4224 | 4304 | of the control at level <code>lvl</code> in the call stack. |
| 4225 | 4305 | Typically this string has the format <code><chunkname>:<currentline>:</code>. |
| 4226 | 4306 | Level 0 is the running function, |
| 4227 | | −level 1 is the function that called the running function. |
| 4307 | +level 1 is the function that called the running function, |
| 4308 | +etc. |
| 4228 | 4309 | |
| 4229 | 4310 | <p>This function is used to build a prefix for error messages. |
| 4230 | 4311 | |
| 4231 | 4312 | <p> |
| 4232 | 4313 | <a name="libraries"></a><a name="5"></a><h1>5 - Standard Libraries</h1> |
| 4233 | 4314 | |
| 4234 | | −<p>The standard libraries provide useful functions |
| 4315 | +<p>The standard Lua libraries provide useful functions |
| 4235 | 4316 | that are implemented directly through the C API. |
| 4236 | 4317 | Some of these functions provide essential services to the language |
| 4237 | 4318 | (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); |
| 4238 | 4319 | others provide access to "outside" services (e.g., I/O); |
| 4239 | 4320 | and others could be implemented in Lua itself, |
| 4240 | | −but are quite useful or have critical performance to |
| 4321 | +but are quite useful or have critical performance requirements that |
| 4241 | 4322 | deserve an implementation in C (e.g., <code>sort</code>). |
| 4242 | 4323 | |
| 4243 | 4324 | <p>All libraries are implemented through the official C API |
| @@ -4258,9 +4339,11 @@ each library provides all its functions as fields of a global table · 14 unmodified lines |
| 4258 | 4339 | or as methods of its objects. |
| 4259 | 4340 | |
| 4260 | 4341 | <p>To have access to these libraries, |
| 4261 | | −the C host program must first call the function |
| 4262 | | −<code>luaL_openlibs</code>; |
| 4263 | | −or else it can open them individually calling |
| 4342 | +the C host program must call |
| 4343 | +<code>luaL_openlibs</code>, |
| 4344 | +which open all standard libraries. |
| 4345 | +Alternatively, |
| 4346 | +it can open them individually by calling |
| 4264 | 4347 | <code>luaopen_base</code> (for the basic library), |
| 4265 | 4348 | <code>luaopen_package</code> (for the package library), |
| 4266 | 4349 | <code>luaopen_string</code> (for the string library), |
| @@ -4268,86 +4351,90 @@ or else it can open them individually calling · 1 unmodified line |
| 4268 | 4351 | <code>luaopen_math</code> (for the mathematical library), |
| 4269 | 4352 | <code>luaopen_io</code> (for the I/O and the Operating System libraries), |
| 4270 | 4353 | and <code>luaopen_debug</code> (for the debug library). |
| 4271 | | −These functions are declared in <code>lualib.h</code>. |
| 4354 | +These functions are declared in <code>lualib.h</code> |
| 4355 | +and should not be called directly: |
| 4356 | +you must call them like any other Lua C function, |
| 4357 | +e.g., by using <code>lua_call</code>. |
| 4272 | 4358 | |
| 4273 | 4359 | <p><a name="predefined"></a><a name="5.1"></a><h2>5.1 - Basic Functions</h2> |
| 4274 | 4360 | |
| 4275 | 4361 | <p>The basic library provides some core functions to Lua. |
| 4276 | 4362 | If you do not include this library in your application, |
| 4277 | | −you should check carefully whether you need to provide some alternative |
| 4278 | | −implementation for some of its facilities. |
| 4363 | +you should check carefully whether you need to provide |
| 4364 | +implementations for some of its facilities. |
| 4279 | 4365 | |
| 4280 | | −<p><a name="pdf-assert"></a><hr/><h3><code>assert (v [, message])</code></h3> |
| 4366 | +<p><a name="pdf-assert"></a><hr /><h3><code>assert (v [, message])</code></h3> |
| 4281 | 4367 | Issues an error when |
| 4282 | | −the value of its argument <code>v</code> is <b>nil</b> or <b>false</b>; |
| 4368 | +the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); |
| 4283 | 4369 | otherwise, returns all its arguments. |
| 4284 | 4370 | <code>message</code> is an error message; |
| 4285 | 4371 | when absent, it defaults to "assertion failed!" |
| 4286 | 4372 | |
| 4287 | | −<p><a name="pdf-collectgarbage"></a><hr/><h3><code>collectgarbage (opt [, arg])</code></h3> |
| 4373 | +<p><a name="pdf-collectgarbage"></a><hr /><h3><code>collectgarbage (opt [, arg])</code></h3> |
| 4288 | 4374 | |
| 4289 | 4375 | <p>This function is a generic interface to the garbage collector. |
| 4290 | 4376 | It performs different functions according to its first argument, <code>opt</code>: |
| 4291 | 4377 | <ul> |
| 4292 | | −<li><b>"stop"</b> stops the garbage collector. |
| 4293 | | −<li><b>"restart"</b> restarts the garbage collector. |
| 4294 | | −<li><b>"collect"</b> performs a full garbage-collection cycle. |
| 4295 | | −<li><b>"count"</b> returns the total memory in use by Lua (in Kbytes). |
| 4296 | | −<li><b>"step"</b> performs a garbage-collection step. |
| 4378 | +<li><b>"stop"</b> --- stops the garbage collector. |
| 4379 | +<li><b>"restart"</b> --- restarts the garbage collector. |
| 4380 | +<li><b>"collect"</b> --- performs a full garbage-collection cycle. |
| 4381 | +<li><b>"count"</b> --- returns the total memory in use by Lua (in Kbytes). |
| 4382 | +<li><b>"step"</b> --- performs a garbage-collection step. |
| 4297 | 4383 | The step "size" is controlled by <code>arg</code> |
| 4298 | 4384 | (larger values mean more steps) in a non-specified way. |
| 4299 | 4385 | If you want to control the step size |
| 4300 | 4386 | you must tune experimentally the value of <code>arg</code>. |
| 4301 | 4387 | Returns <b>true</b> if that step finished a collection cycle. |
| 4302 | | −<li><b>"steppause"</b> |
| 4303 | | −sets <em><code>arg</code>/100</em> as the new value for the <em>pause</em> of |
| 4388 | +<li><b>"steppause"</b> --- |
| 4389 | +sets <code>arg</code>/100 as the new value for the <em>pause</em> of |
| 4304 | 4390 | the collector (see <a href="#GC">2.10</a>). |
| 4305 | | −<li><b>"setstepmul"</b> |
| 4306 | | −sets <em><code>arg</code>/100</em> as the new value for the <em>step multiplier</em> of |
| 4391 | +<li><b>"setstepmul"</b> --- |
| 4392 | +sets <code>arg</code>/100 as the new value for the <em>step multiplier</em> of |
| 4307 | 4393 | the collector (see <a href="#GC">2.10</a>). |
| 4308 | 4394 | </ul> |
| 4309 | 4395 | |
| 4310 | | −<p><a name="pdf-dofile"></a><hr/><h3><code>dofile (filename)</code></h3> |
| 4396 | +<p><a name="pdf-dofile"></a><hr /><h3><code>dofile (filename)</code></h3> |
| 4311 | 4397 | Opens the named file and executes its contents as a Lua chunk. |
| 4312 | 4398 | When called without arguments, |
| 4313 | | −<a href="#pdf-dofile"><code>dofile</code></a> executes the contents of the standard input (<code>stdin</code>). |
| 4314 | | −Returns any value returned by the chunk. |
| 4315 | | −In case of errors, <a href="#pdf-dofile"><code>dofile</code></a> propagates the error |
| 4316 | | −to its caller (that is, it does not run in protected mode). |
| 4399 | +<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). |
| 4400 | +Returns all values returned by the chunk. |
| 4401 | +In case of errors, <code>dofile</code> propagates the error |
| 4402 | +to its caller (that is, <code>dofile</code> does not run in protected mode). |
| 4317 | 4403 | |
| 4318 | | −<p><a name="pdf-error"></a><hr/><h3><code>error (message [, level])</code></h3> |
| 4404 | +<p><a name="pdf-error"></a><hr /><h3><code>error (message [, level])</code></h3> |
| 4319 | 4405 | Terminates the last protected function called |
| 4320 | 4406 | and returns <code>message</code> as the error message. |
| 4321 | | −Function <a href="#pdf-error"><code>error</code></a> never returns. |
| 4407 | +Function <code>error</code> never returns. |
| 4322 | 4408 | |
| 4323 | | −<p>Usually, <a href="#pdf-error"><code>error</code></a> adds some information about the error position |
| 4409 | +<p>Usually, <code>error</code> adds some information about the error position |
| 4324 | 4410 | at the beginning of the message. |
| 4325 | 4411 | The <code>level</code> argument specifies how to get the error position. |
| 4326 | 4412 | With level 1 (the default), the error position is where the |
| 4327 | | −<a href="#pdf-error"><code>error</code></a> function was called. |
| 4413 | +<code>error</code> function was called. |
| 4328 | 4414 | Level 2 points the error to where the function |
| 4329 | | −that called <a href="#pdf-error"><code>error</code></a> was called; and so on. |
| 4415 | +that called <code>error</code> was called; and so on. |
| 4330 | 4416 | Passing a level 0 avoids the addition of error position information |
| 4331 | 4417 | to the message. |
| 4332 | 4418 | |
| 4333 | | −<p><a name="pdf-_G"></a><hr/><h3><code>_G</code></h3> |
| 4419 | +<p><a name="pdf-_G"></a><hr /><h3><code>_G</code></h3> |
| 4334 | 4420 | A global variable (not a function) that |
| 4335 | 4421 | holds the global environment (that is, <code>_G._G = _G</code>). |
| 4336 | 4422 | Lua itself does not use this variable; |
| 4337 | | −changing its value does not affect any environment. |
| 4423 | +changing its value does not affect any environment, |
| 4424 | +nor vice-versa. |
| 4338 | 4425 | (Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) |
| 4339 | 4426 | |
| 4340 | | −<p><a name="pdf-getfenv"></a><hr/><h3><code>getfenv (f)</code></h3> |
| 4427 | +<p><a name="pdf-getfenv"></a><hr /><h3><code>getfenv (f)</code></h3> |
| 4341 | 4428 | Returns the current environment in use by the function. |
| 4342 | | −<code>f</code> can be a Lua function or a number, |
| 4343 | | −which specifies the function at that stack level: |
| 4344 | | −Level 1 is the function calling <a href="#pdf-getfenv"><code>getfenv</code></a>. |
| 4429 | +<code>f</code> can be a Lua function or a number |
| 4430 | +that specifies the function at that stack level: |
| 4431 | +Level 1 is the function calling <code>getfenv</code>. |
| 4345 | 4432 | If the given function is not a Lua function, |
| 4346 | 4433 | or if <code>f</code> is 0, |
| 4347 | | −<a href="#pdf-getfenv"><code>getfenv</code></a> returns the global environment. |
| 4434 | +<code>getfenv</code> returns the global environment. |
| 4348 | 4435 | The default for <code>f</code> is 1. |
| 4349 | 4436 | |
| 4350 | | −<p><a name="pdf-getmetatable"></a><hr/><h3><code>getmetatable (object)</code></h3> |
| 4437 | +<p><a name="pdf-getmetatable"></a><hr /><h3><code>getmetatable (object)</code></h3> |
| 4351 | 4438 | |
| 4352 | 4439 | <p>If <code>object</code> does not have a metatable, returns <b>nil</b>. |
| 4353 | 4440 | Otherwise, |
| @@ -4355,9 +4442,9 @@ if the object's metatable has a <code>"__metatable"</code> field, · 1 unmodified line |
| 4355 | 4442 | returns the associated value. |
| 4356 | 4443 | Otherwise, returns the metatable of the given object. |
| 4357 | 4444 | |
| 4358 | | −<p><a name="pdf-ipairs"></a><hr/><h3><code>ipairs (t)</code></h3> |
| 4445 | +<p><a name="pdf-ipairs"></a><hr /><h3><code>ipairs (t)</code></h3> |
| 4359 | 4446 | |
| 4360 | | −<p>Returns an iterator function, the table <code>t</code>, and 0, |
| 4447 | +<p>Returns three values: an iterator function, the table <code>t</code>, and 0, |
| 4361 | 4448 | so that the construction |
| 4362 | 4449 | <pre> |
| 4363 | 4450 | for i,v in ipairs(t) do ... end |
| @@ -4365,7 +4452,9 @@ so that the construction · 1 unmodified line |
| 4365 | 4452 | will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., |
| 4366 | 4453 | up to the first integer key with a nil value in the table. |
| 4367 | 4454 | |
| 4368 | | −<p><a name="pdf-load"></a><hr/><h3><code>load (func [, chunkname])</code></h3> |
| 4455 | +<p>See <a href="#pdf-next"><code>next</code></a> for the caveats of modifying the table during its traversal. |
| 4456 | + |
| 4457 | +<p><a name="pdf-load"></a><hr /><h3><code>load (func [, chunkname])</code></h3> |
| 4369 | 4458 | |
| 4370 | 4459 | <p>Loads a chunk using function <code>func</code> to get its pieces. |
| 4371 | 4460 | Each call to <code>func</code> must return a string that concatenates |
| @@ -4380,12 +4469,14 @@ The environment of the returned function is the global environment. · 8 unmodified lines |
| 4380 | 4469 | <p><code>chunkname</code> is used as the chunk name for error messages |
| 4381 | 4470 | and debug information. |
| 4382 | 4471 | |
| 4383 | | −<p><a name="pdf-loadfile"></a><hr/><h3><code>loadfile (filename)</code></h3> |
| 4472 | +<p><a name="pdf-loadfile"></a><hr /><h3><code>loadfile ([filename])</code></h3> |
| 4384 | 4473 | |
| 4385 | 4474 | <p>Similar to <a href="#pdf-load"><code>load</code></a>, |
| 4386 | | −but gets the chunk from file <code>filename</code>. |
| 4475 | +but gets the chunk from file <code>filename</code> |
| 4476 | +or from the standard input, |
| 4477 | +if no file name given. |
| 4387 | 4478 | |
| 4388 | | −<p><a name="pdf-loadstring"></a><hr/><h3><code>loadstring (string [, chunkname])</code></h3> |
| 4479 | +<p><a name="pdf-loadstring"></a><hr /><h3><code>loadstring (string [, chunkname])</code></h3> |
| 4389 | 4480 | |
| 4390 | 4481 | <p>Similar to <a href="#pdf-load"><code>load</code></a>, |
| 4391 | 4482 | but gets the chunk from the given string. |
| @@ -4395,106 +4486,112 @@ but gets the chunk from the given string. · 3 unmodified lines |
| 4395 | 4486 | assert(loadstring(s))() |
| 4396 | 4487 | </pre> |
| 4397 | 4488 | |
| 4398 | | −<p><a name="pdf-next"></a><hr/><h3><code>next (table [, index])</code></h3> |
| 4489 | +<p><a name="pdf-next"></a><hr /><h3><code>next (table [, index])</code></h3> |
| 4399 | 4490 | |
| 4400 | 4491 | <p>Allows a program to traverse all fields of a table. |
| 4401 | 4492 | Its first argument is a table and its second argument |
| 4402 | 4493 | is an index in this table. |
| 4403 | | −<a href="#pdf-next"><code>next</code></a> returns the next index of the table and the |
| 4404 | | −value associated with the index. |
| 4494 | +<code>next</code> returns the next index of the table |
| 4495 | +and its associated value. |
| 4405 | 4496 | When called with <b>nil</b> as its second argument, |
| 4406 | | −<a href="#pdf-next"><code>next</code></a> returns the first index |
| 4407 | | −of the table and its associated value. |
| 4497 | +<code>next</code> returns an initial index |
| 4498 | +and its associated value. |
| 4408 | 4499 | When called with the last index, |
| 4409 | 4500 | or with <b>nil</b> in an empty table, |
| 4410 | | −<a href="#pdf-next"><code>next</code></a> returns <b>nil</b>. |
| 4501 | +<code>next</code> returns <b>nil</b>. |
| 4411 | 4502 | If the second argument is absent, then it is interpreted as <b>nil</b>. |
| 4503 | +In particular, |
| 4504 | +you can use <code>next(t)</code> to check whether a table is empty. |
| 4412 | 4505 | |
| 4413 | | −<p>Lua has no declaration of fields; |
| 4506 | +<p>Lua has no declaration of fields. |
| 4414 | 4507 | There is no difference between a |
| 4415 | 4508 | field not present in a table or a field with value <b>nil</b>. |
| 4416 | | −Therefore, <a href="#pdf-next"><code>next</code></a> only considers fields with non-<b>nil</b> values. |
| 4509 | +Therefore, <code>next</code> only considers fields with non-<b>nil</b> values. |
| 4417 | 4510 | The order in which the indices are enumerated is not specified, |
| 4418 | 4511 | <em>even for numeric indices</em>. |
| 4419 | 4512 | (To traverse a table in numeric order, |
| 4420 | 4513 | use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) |
| 4421 | 4514 | |
| 4422 | | −<p>The behavior of <a href="#pdf-next"><code>next</code></a> is <em>undefined</em> if, |
| 4515 | +<p>The behavior of <code>next</code> is <em>undefined</em> if, |
| 4423 | 4516 | during the traversal, |
| 4424 | 4517 | you assign any value to a non-existent field in the table. |
| 4518 | +You may however modify existing fields. |
| 4519 | +In particular, you may clear existing fields. |
| 4425 | 4520 | |
| 4426 | | −<p><a name="pdf-pairs"></a><hr/><h3><code>pairs (t)</code></h3> |
| 4521 | +<p><a name="pdf-pairs"></a><hr /><h3><code>pairs (t)</code></h3> |
| 4427 | 4522 | |
| 4428 | | −<p>Returns the <a href="#pdf-next"><code>next</code></a> function and the table <code>t</code> (plus a <b>nil</b>), |
| 4523 | +<p>Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, |
| 4429 | 4524 | so that the construction |
| 4430 | 4525 | <pre> |
| 4431 | 4526 | for k,v in pairs(t) do ... end |
| 4432 | 4527 | </pre> |
| 4433 | 4528 | will iterate over all key--value pairs of table <code>t</code>. |
| 4434 | 4529 | |
| 4435 | | −<p><a name="pdf-pcall"></a><hr/><h3><code>pcall (f, arg1, arg2, ...)</code></h3> |
| 4530 | +<p>See <a href="#pdf-next"><code>next</code></a> for the caveats of modifying the table during its traversal. |
| 4531 | + |
| 4532 | +<p><a name="pdf-pcall"></a><hr /><h3><code>pcall (f, arg1, arg2, ...)</code></h3> |
| 4436 | 4533 | |
| 4437 | 4534 | <p>Calls function <code>f</code> with |
| 4438 | 4535 | the given arguments in protected mode. |
| 4439 | 4536 | That means that any error inside <code>f</code> is not propagated; |
| 4440 | | −instead, <a href="#pdf-pcall"><code>pcall</code></a> catches the error |
| 4537 | +instead, <code>pcall</code> catches the error |
| 4441 | 4538 | and returns a status code. |
| 4442 | 4539 | Its first result is the status code (a boolean), |
| 4443 | 4540 | which is true if the call succeeds without errors. |
| 4444 | | −In such case, <a href="#pdf-pcall"><code>pcall</code></a> also returns all results from the call, |
| 4541 | +In such case, <code>pcall</code> also returns all results from the call, |
| 4445 | 4542 | after this first result. |
| 4446 | | −In case of any error, <a href="#pdf-pcall"><code>pcall</code></a> returns <b>false</b> plus the error message. |
| 4543 | +In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. |
| 4447 | 4544 | |
| 4448 | | −<p><a name="pdf-print"></a><hr/><h3><code>print (e1, e2, ...)</code></h3> |
| 4545 | +<p><a name="pdf-print"></a><hr /><h3><code>print (e1, e2, ...)</code></h3> |
| 4449 | 4546 | Receives any number of arguments, |
| 4450 | 4547 | and prints their values in <code>stdout</code>, |
| 4451 | 4548 | using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. |
| 4452 | | −This function is not intended for formatted output, |
| 4549 | +<code>print</code> is not intended for formatted output, |
| 4453 | 4550 | but only as a quick way to show a value, |
| 4454 | 4551 | typically for debugging. |
| 4455 | | −For formatted output, use <code>format</code> (see <a href="#format">5.4</a>). |
| 4552 | +For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. |
| 4456 | 4553 | |
| 4457 | | −<p><a name="pdf-rawequal"></a><hr/><h3><code>rawequal (v1, v2)</code></h3> |
| 4554 | +<p><a name="pdf-rawequal"></a><hr /><h3><code>rawequal (v1, v2)</code></h3> |
| 4458 | 4555 | Checks whether <code>v1</code> is equal to <code>v2</code>, |
| 4459 | 4556 | without invoking any metamethod. |
| 4460 | 4557 | Returns a boolean. |
| 4461 | 4558 | |
| 4462 | | −<p><a name="pdf-rawget"></a><hr/><h3><code>rawget (table, index)</code></h3> |
| 4559 | +<p><a name="pdf-rawget"></a><hr /><h3><code>rawget (table, index)</code></h3> |
| 4463 | 4560 | Gets the real value of <code>table[index]</code>, |
| 4464 | 4561 | without invoking any metamethod. |
| 4465 | | −<code>table</code> must be a table; |
| 4466 | | −<code>index</code> is any value different from <b>nil</b>. |
| 4562 | +<code>table</code> must be a table and |
| 4563 | +<code>index</code> any value different from <b>nil</b>. |
| 4467 | 4564 | |
| 4468 | | −<p><a name="pdf-rawset"></a><hr/><h3><code>rawset (table, index, value)</code></h3> |
| 4565 | +<p><a name="pdf-rawset"></a><hr /><h3><code>rawset (table, index, value)</code></h3> |
| 4469 | 4566 | Sets the real value of <code>table[index]</code> to <code>value</code>, |
| 4470 | 4567 | without invoking any metamethod. |
| 4471 | 4568 | <code>table</code> must be a table, |
| 4472 | | −<code>index</code> is any value different from <b>nil</b>, |
| 4473 | | −and <code>value</code> is any Lua value. |
| 4569 | +<code>index</code> any value different from <b>nil</b>, |
| 4570 | +and <code>value</code> any Lua value. |
| 4474 | 4571 | |
| 4475 | | −<p><a name="pdf-select"></a><hr/><h3><code>select (index, ...)</code></h3> |
| 4572 | +<p><a name="pdf-select"></a><hr /><h3><code>select (index, ...)</code></h3> |
| 4476 | 4573 | |
| 4477 | 4574 | <p>If <code>index</code> is a number, |
| 4478 | | −returns all argument after argument number <code>index</code>. |
| 4575 | +returns all arguments after argument number <code>index</code>. |
| 4479 | 4576 | Otherwise, <code>index</code> must be the string <code>"#"</code>, |
| 4480 | 4577 | and <code>select</code> returns the total number of extra arguments it received. |
| 4481 | 4578 | |
| 4482 | | −<p><a name="setfenv"></a><a name="pdf-setfenv"></a><hr/><h3><code>setfenv (f, table)</code></h3> |
| 4579 | +<p><a name="setfenv"></a><a name="pdf-setfenv"></a><hr /><h3><code>setfenv (f, table)</code></h3> |
| 4483 | 4580 | |
| 4484 | 4581 | <p>Sets the environment to be used by the given function. |
| 4485 | | −<code>f</code> can be a Lua function or a number, |
| 4486 | | −which specifies the function at that stack level: |
| 4487 | | −Level 1 is the function calling <a href="#pdf-setfenv"><code>setfenv</code></a>. |
| 4488 | | −<a href="#pdf-setfenv"><code>setfenv</code></a> returns the given function. |
| 4582 | +<code>f</code> can be a Lua function or a number |
| 4583 | +that specifies the function at that stack level: |
| 4584 | +Level 1 is the function calling <code>setfenv</code>. |
| 4585 | +<code>setfenv</code> returns the given function. |
| 4489 | 4586 | |
| 4490 | | −<p>As a special case, when <code>f</code> is 0 <a href="#pdf-setfenv"><code>setfenv</code></a> changes |
| 4587 | +<p>As a special case, when <code>f</code> is 0 <code>setfenv</code> changes |
| 4491 | 4588 | the environment of the running thread. |
| 4492 | | −In this case, <a href="#pdf-setfenv"><code>setfenv</code></a> returns no values. |
| 4589 | +In this case, <code>setfenv</code> returns no values. |
| 4493 | 4590 | |
| 4494 | | −<p><a name="pdf-setmetatable"></a><hr/><h3><code>setmetatable (table, metatable)</code></h3> |
| 4591 | +<p><a name="pdf-setmetatable"></a><hr /><h3><code>setmetatable (table, metatable)</code></h3> |
| 4495 | 4592 | |
| 4496 | 4593 | <p>Sets the metatable for the given table. |
| 4497 | | −(You cannot change the metatable of other types from Lua.) |
| 4594 | +(You cannot change the metatable of other types from Lua, only from C.) |
| 4498 | 4595 | If <code>metatable</code> is <b>nil</b>, |
| 4499 | 4596 | removes the metatable of the given table. |
| 4500 | 4597 | If the original metatable has a <code>"__metatable"</code> field, |
| @@ -4502,10 +4599,10 @@ raises an error. · 1 unmodified line |
| 4502 | 4599 | |
| 4503 | 4600 | <p>This function returns <code>table</code>. |
| 4504 | 4601 | |
| 4505 | | −<p><a name="pdf-tonumber"></a><hr/><h3><code>tonumber (e [, base])</code></h3> |
| 4602 | +<p><a name="pdf-tonumber"></a><hr /><h3><code>tonumber (e [, base])</code></h3> |
| 4506 | 4603 | Tries to convert its argument to a number. |
| 4507 | 4604 | If the argument is already a number or a string convertible |
| 4508 | | −to a number, then <a href="#pdf-tonumber"><code>tonumber</code></a> returns that number; |
| 4605 | +to a number, then <code>tonumber</code> returns that number; |
| 4509 | 4606 | otherwise, it returns <b>nil</b>. |
| 4510 | 4607 | |
| 4511 | 4608 | <p>An optional argument specifies the base to interpret the numeral. |
| @@ -4514,21 +4611,21 @@ In bases above 10, the letter `<code>A</code>´ (in either upper or lower c · 2 unmodified lines |
| 4514 | 4611 | represents 10, `<code>B</code>´ represents 11, and so forth, |
| 4515 | 4612 | with `<code>Z</code>´ representing 35. |
| 4516 | 4613 | In base 10 (the default), the number may have a decimal part, |
| 4517 | | −as well as an optional exponent part (see <a href="#coercion">2.2.1</a>). |
| 4614 | +as well as an optional exponent part (see <a href="#lexical">2.1</a>). |
| 4518 | 4615 | In other bases, only unsigned integers are accepted. |
| 4519 | 4616 | |
| 4520 | | −<p><a name="pdf-tostring"></a><hr/><h3><code>tostring (e)</code></h3> |
| 4617 | +<p><a name="pdf-tostring"></a><hr /><h3><code>tostring (e)</code></h3> |
| 4521 | 4618 | Receives an argument of any type and |
| 4522 | 4619 | converts it to a string in a reasonable format. |
| 4523 | 4620 | For complete control of how numbers are converted, |
| 4524 | | −use <a href="#pdf-string.format"><code>string.format</code></a> (see <a href="#format">5.4</a>). |
| 4621 | +use <a href="#pdf-string.format"><code>string.format</code></a>. |
| 4525 | 4622 | |
| 4526 | 4623 | <p>If the metatable of <code>e</code> has a <code>"__tostring"</code> field, |
| 4527 | | −<a href="#pdf-tostring"><code>tostring</code></a> calls the corresponding value |
| 4624 | +then <code>tostring</code> calls the corresponding value |
| 4528 | 4625 | with <code>e</code> as argument, |
| 4529 | 4626 | and uses the result of the call as its result. |
| 4530 | 4627 | |
| 4531 | | −<p><a name="pdf-type"></a><hr/><h3><code>type (v)</code></h3> |
| 4628 | +<p><a name="pdf-type"></a><hr /><h3><code>type (v)</code></h3> |
| 4532 | 4629 | Returns the type of its only argument, coded as a string. |
| 4533 | 4630 | The possible results of this function are |
| 4534 | 4631 | <code>"nil"</code> (a string, not the value <b>nil</b>), |
| @@ -4540,8 +4637,8 @@ The possible results of this function are · 5 unmodified lines |
| 4540 | 4637 | <code>"thread"</code>, |
| 4541 | 4638 | and <code>"userdata"</code>. |
| 4542 | 4639 | |
| 4543 | | −<p><a name="pdf-unpack"></a><hr/><h3><code>unpack (list [, i [, j]])</code></h3> |
| 4544 | | −Returns the elements from the given list. |
| 4640 | +<p><a name="pdf-unpack"></a><hr /><h3><code>unpack (list [, i [, j]])</code></h3> |
| 4641 | +Returns the elements from the given table. |
| 4545 | 4642 | This function is equivalent to |
| 4546 | 4643 | <pre> |
| 4547 | 4644 | return list[i], list[i+1], ..., list[j] |
| @@ -4549,30 +4646,30 @@ This function is equivalent to · 1 unmodified line |
| 4549 | 4646 | except that the above code can be written only for a fixed number |
| 4550 | 4647 | of elements. |
| 4551 | 4648 | By default, <code>i</code> is 1 and <code>j</code> is the length of the list, |
| 4552 | | −as defined by the length operator. |
| 4649 | +as defined by the length operator (see <a href="#len-op">2.5.5</a>). |
| 4553 | 4650 | |
| 4554 | | −<p><a name="pdf-_VERSION"></a><hr/><h3><code>_VERSION</code></h3> |
| 4651 | +<p><a name="pdf-_VERSION"></a><hr /><h3><code>_VERSION</code></h3> |
| 4555 | 4652 | A global variable (not a function) that |
| 4556 | 4653 | holds a string containing the current interpreter version. |
| 4557 | 4654 | The current contents of this variable is <code>"Lua 5.1"</code>. |
| 4558 | 4655 | |
| 4559 | | −<p><a name="pdf-xpcall"></a><hr/><h3><code>xpcall (f, err)</code></h3> |
| 4656 | +<p><a name="pdf-xpcall"></a><hr /><h3><code>xpcall (f, err)</code></h3> |
| 4560 | 4657 | |
| 4561 | | −<p>This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, |
| 4658 | +<p>This function is similar to <code>pcall</code>, |
| 4562 | 4659 | except that you can set a new error handler. |
| 4563 | 4660 | |
| 4564 | | −<p><a href="#pdf-xpcall"><code>xpcall</code></a> calls function <code>f</code> in protected mode, |
| 4661 | +<p><code>xpcall</code> calls function <code>f</code> in protected mode, |
| 4565 | 4662 | using <code>err</code> as the error handler. |
| 4566 | 4663 | Any error inside <code>f</code> is not propagated; |
| 4567 | | −instead, <a href="#pdf-xpcall"><code>xpcall</code></a> catches the error, |
| 4664 | +instead, <code>xpcall</code> catches the error, |
| 4568 | 4665 | calls the <code>err</code> function with the original error object, |
| 4569 | 4666 | and returns a status code. |
| 4570 | 4667 | Its first result is the status code (a boolean), |
| 4571 | 4668 | which is true if the call succeeds without errors. |
| 4572 | | −In such case, <a href="#pdf-xpcall"><code>xpcall</code></a> also returns all results from the call, |
| 4669 | +In this case, <code>xpcall</code> also returns all results from the call, |
| 4573 | 4670 | after this first result. |
| 4574 | 4671 | In case of any error, |
| 4575 | | −<a href="#pdf-xpcall"><code>xpcall</code></a> returns false plus the result from <code>err</code>. |
| 4672 | +<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. |
| 4576 | 4673 | |
| 4577 | 4674 | <p><a name="5.2"></a><h2>5.2 - Coroutine Manipulation</h2> |
| 4578 | 4675 | |
| @@ -4580,22 +4677,24 @@ In case of any error, · 1 unmodified line |
| 4580 | 4677 | the basic library and come inside the table <code>coroutine</code>. |
| 4581 | 4678 | See <a href="#coroutine">2.11</a> for a general description of coroutines. |
| 4582 | 4679 | |
| 4583 | | −<p><a name="pdf-coroutine.create"></a><hr/><h3><code>coroutine.create (f)</code></h3> |
| 4680 | +<p><a name="pdf-coroutine.create"></a><hr /><h3><code>coroutine.create (f)</code></h3> |
| 4584 | 4681 | |
| 4585 | 4682 | <p>Creates a new coroutine, with body <code>f</code>. |
| 4586 | 4683 | <code>f</code> must be a Lua function. |
| 4587 | 4684 | Returns this new coroutine, |
| 4588 | 4685 | an object with type <code>"thread"</code>. |
| 4589 | 4686 | |
| 4590 | | −<p><a name="pdf-coroutine.resume"></a><hr/><h3><code>coroutine.resume (co, val1, ...)</code></h3> |
| 4687 | +<p><a name="pdf-coroutine.resume"></a><hr /><h3><code>coroutine.resume (co [, val1, ..., valn])</code></h3> |
| 4591 | 4688 | |
| 4592 | 4689 | <p>Starts or continues the execution of coroutine <code>co</code>. |
| 4593 | 4690 | The first time you resume a coroutine, |
| 4594 | 4691 | it starts running its body. |
| 4595 | | −The arguments <code>val1</code>, ... go as the arguments to the body function. |
| 4692 | +The values <code>val1</code>, ..., <code>valn</code> are passed |
| 4693 | +as the arguments to the body function. |
| 4596 | 4694 | If the coroutine has yielded, |
| 4597 | 4695 | <code>resume</code> restarts it; |
| 4598 | | −the arguments <code>val1</code>, ... go as the results from the yield. |
| 4696 | +the values <code>val1</code>, ..., <code>valn</code> are passed |
| 4697 | +as the results from the yield. |
| 4599 | 4698 | |
| 4600 | 4699 | <p>If the coroutine runs without any errors, |
| 4601 | 4700 | <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> |
| @@ -4604,12 +4703,12 @@ the arguments <code>val1</code>, ... go as the results from the yield. · 2 unmodified lines |
| 4604 | 4703 | If there is any error, |
| 4605 | 4704 | <code>resume</code> returns <b>false</b> plus the error message. |
| 4606 | 4705 | |
| 4607 | | −<p><a name="pdf-coroutine.running"></a><hr/><h3><code>coroutine.running ()</code></h3> |
| 4706 | +<p><a name="pdf-coroutine.running"></a><hr /><h3><code>coroutine.running ()</code></h3> |
| 4608 | 4707 | |
| 4609 | 4708 | <p>Returns the running coroutine, |
| 4610 | 4709 | or <b>nil</b> when called by the main thread. |
| 4611 | 4710 | |
| 4612 | | −<p><a name="pdf-coroutine.status"></a><hr/><h3><code>coroutine.status (co)</code></h3> |
| 4711 | +<p><a name="pdf-coroutine.status"></a><hr /><h3><code>coroutine.status (co)</code></h3> |
| 4613 | 4712 | |
| 4614 | 4713 | <p>Returns the status of coroutine <code>co</code>, as a string: |
| 4615 | 4714 | <code>"running"</code>, |
| @@ -4621,7 +4720,7 @@ or if it has not started running yet; · 5 unmodified lines |
| 4621 | 4720 | and <code>"dead"</code> if the coroutine has finished its body function, |
| 4622 | 4721 | or if it has stopped with an error. |
| 4623 | 4722 | |
| 4624 | | −<p><a name="pdf-coroutine.wrap"></a><hr/><h3><code>coroutine.wrap (f)</code></h3> |
| 4723 | +<p><a name="pdf-coroutine.wrap"></a><hr /><h3><code>coroutine.wrap (f)</code></h3> |
| 4625 | 4724 | |
| 4626 | 4725 | <p>Creates a new coroutine, with body <code>f</code>. |
| 4627 | 4726 | <code>f</code> must be a Lua function. |
| @@ -4632,22 +4731,22 @@ Returns the same values returned by <code>resume</code>, · 4 unmodified lines |
| 4632 | 4731 | except the first boolean. |
| 4633 | 4732 | In case of error, propagates the error. |
| 4634 | 4733 | |
| 4635 | | −<p><a name="pdf-coroutine.yield"></a><hr/><h3><code>coroutine.yield (val1, ...)</code></h3> |
| 4734 | +<p><a name="pdf-coroutine.yield"></a><hr /><h3><code>coroutine.yield ([val1, ..., valn])</code></h3> |
| 4636 | 4735 | |
| 4637 | 4736 | <p>Suspends the execution of the calling coroutine. |
| 4638 | | −The coroutine cannot be running neither a C function, |
| 4737 | +The coroutine can be running neither a C function, |
| 4639 | 4738 | nor a metamethod, nor an iterator. |
| 4640 | | −Any arguments to <code>yield</code> go as extra results to <code>resume</code>. |
| 4739 | +Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. |
| 4641 | 4740 | |
| 4642 | | −<p><a name="5.3"></a><h2>5.3 - Packages and Modules</h2> |
| 4741 | +<p><a name="5.3"></a><h2>5.3 - Modules</h2> |
| 4643 | 4742 | |
| 4644 | 4743 | <p>The package library provides basic |
| 4645 | | −facilities for packages and modules in Lua. |
| 4744 | +facilities for loading and building modules in Lua. |
| 4646 | 4745 | It exports two of its functions directly in the global environment: |
| 4647 | 4746 | <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. |
| 4648 | 4747 | Everything else is exported in a table <code>package</code>. |
| 4649 | 4748 | |
| 4650 | | −<p><a name="pdf-module"></a><hr/><h3><code>module (name [, ...])</code></h3> |
| 4749 | +<p><a name="pdf-module"></a><hr /><h3><code>module (name [, ...])</code></h3> |
| 4651 | 4750 | |
| 4652 | 4751 | <p>Creates a module. |
| 4653 | 4752 | If there is a table in <code>package.loaded[name]</code>, |
| @@ -4666,51 +4765,51 @@ of the current function and the new value of <code>package.loaded[name]</code>, · 12 unmodified lines |
| 4666 | 4765 | so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. |
| 4667 | 4766 | |
| 4668 | 4767 | <p>If <code>name</code> is a compound name |
| 4669 | | −(that is, one with components separated by dots) |
| 4670 | | −<code>module</code> creates (or reuses, if they already exists) |
| 4768 | +(that is, one with components separated by dots), |
| 4769 | +<code>module</code> creates (or reuses, if they already exist) |
| 4671 | 4770 | tables for each component. |
| 4672 | 4771 | For instance, if <code>name</code> is <code>a.b.c</code>, |
| 4673 | | −<code>module</code> stores the module table in field <code>c</code> of |
| 4772 | +then <code>module</code> stores the module table in field <code>c</code> of |
| 4674 | 4773 | field <code>b</code> of global <code>a</code>. |
| 4675 | 4774 | |
| 4676 | 4775 | <p>This function may receive optional <em>options</em> after |
| 4677 | 4776 | the module name, |
| 4678 | 4777 | where each option is a function to be applied over the module. |
| 4679 | 4778 | |
| 4680 | | −<p><a name="pdf-require"></a><hr/><h3><code>require (modname)</code></h3> |
| 4779 | +<p><a name="pdf-require"></a><hr /><h3><code>require (modname)</code></h3> |
| 4681 | 4780 | |
| 4682 | 4781 | <p>Loads the given module. |
| 4683 | 4782 | The function starts by looking into the table <code>package.loaded</code> |
| 4684 | 4783 | to determine whether <code>modname</code> is already loaded. |
| 4685 | | −If it is, then <a href="#pdf-require"><code>require</code></a> returns the value stored |
| 4784 | +If it is, then <code>require</code> returns the value stored |
| 4686 | 4785 | at <code>package.loaded[modname]</code>. |
| 4687 | | −Otherwise, it tries to find a loader for that module. |
| 4786 | +Otherwise, it tries to find a <em>loader</em> for that module. |
| 4688 | 4787 | |
| 4689 | 4788 | <p>To find a loader, |
| 4690 | | −first <a href="#pdf-require"><code>require</code></a> queries <code>package.preload[modname]</code>. |
| 4691 | | −If it is a true value, |
| 4789 | +first <code>require</code> queries <code>package.preload[modname]</code>. |
| 4790 | +If it has a value, |
| 4692 | 4791 | that value (which should be a function) is the loader. |
| 4693 | | −Otherwise <a href="#pdf-require"><code>require</code></a> searches for a Lua loader using the |
| 4792 | +Otherwise <code>require</code> searches for a Lua loader using the |
| 4694 | 4793 | path stored in <code>package.path</code>. |
| 4695 | | −if that also fails, it searches for a C loader using the |
| 4794 | +If that also fails, it searches for a C loader using the |
| 4696 | 4795 | path stored in <code>package.cpath</code>. |
| 4697 | 4796 | If that also fails, |
| 4698 | | −it tries an <em>all-in-one</em> loader. |
| 4797 | +it tries an <em>all-in-one</em> loader (see below). |
| 4699 | 4798 | |
| 4700 | 4799 | <p>When loading a C library, |
| 4701 | | −<a href="#pdf-require"><code>require</code></a> first uses a dynamic link facility to link the |
| 4800 | +<code>require</code> first uses a dynamic link facility to link the |
| 4702 | 4801 | application with the library. |
| 4703 | 4802 | Then it tries to find a C function inside that library to |
| 4704 | 4803 | be used as the loader. |
| 4705 | 4804 | The name of that C function is the string <code>"luaopen_"</code> |
| 4706 | | −concatenated with a copy of the module name wherein each dot |
| 4805 | +concatenated with a copy of the module name where each dot |
| 4707 | 4806 | is replaced by an underscore. |
| 4708 | 4807 | Moreover, if the module name has a hyphen, |
| 4709 | 4808 | its prefix up to (and including) the first hyphen is removed. |
| 4710 | 4809 | For instance, if the module name is <code>a.v1-b.c</code>, |
| 4711 | 4810 | the function name will be <code>luaopen_b_c</code>. |
| 4712 | 4811 | |
| 4713 | | −<p>If <a href="#pdf-require"><code>require</code></a> finds neither a Lua library nor a |
| 4812 | +<p>If <code>require</code> finds neither a Lua library nor a |
| 4714 | 4813 | C library for a module, |
| 4715 | 4814 | it calls the <em>all-in-one loader</em>. |
| 4716 | 4815 | That loader searches the C path for a library for |
| @@ -4725,29 +4824,29 @@ into one single library, · 8 unmodified lines |
| 4725 | 4824 | with each submodule keeping its original open function. |
| 4726 | 4825 | |
| 4727 | 4826 | <p>Once a loader is found, |
| 4728 | | −<a href="#pdf-require"><code>require</code></a> calls the loader with a sinle argument, <code>modname</code>. |
| 4827 | +<code>require</code> calls the loader with a single argument, <code>modname</code>. |
| 4729 | 4828 | If the loader returns any value, |
| 4730 | | −<a href="#pdf-require"><code>require</code></a> assigns it to <code>package.loaded[modname]</code>. |
| 4829 | +<code>require</code> assigns it to <code>package.loaded[modname]</code>. |
| 4731 | 4830 | If the loader returns no value and |
| 4732 | 4831 | has not assigned any value to <code>package.loaded[modname]</code>, |
| 4733 | | −<a href="#pdf-require"><code>require</code></a> assigns <b>true</b> to that entry. |
| 4832 | +then <code>require</code> assigns <b>true</b> to that entry. |
| 4734 | 4833 | In any case, require returns the |
| 4735 | 4834 | final value of <code>package.loaded[modname]</code>. |
| 4736 | 4835 | |
| 4737 | 4836 | <p>If there is any error loading or running the module, |
| 4738 | 4837 | or if it cannot find any loader for that module, |
| 4739 | | −then <a href="#pdf-require"><code>require</code></a> signals an error. |
| 4838 | +then <code>require</code> signals an error. |
| 4740 | 4839 | |
| 4741 | | −<p><a name="pdf-package.cpath"></a><hr/><h3><code>package.cpath</code></h3> |
| 4840 | +<p><a name="pdf-package.cpath"></a><hr /><h3><code>package.cpath</code></h3> |
| 4742 | 4841 | |
| 4743 | 4842 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. |
| 4744 | 4843 | |
| 4745 | 4844 | <p>Lua initializes the C path <code>package.cpath</code> in the same way |
| 4746 | 4845 | it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, |
| 4747 | 4846 | using the environment variable <code>LUA_CPATH</code> |
| 4748 | | −(plus another compiled-defined default path). |
| 4847 | +(plus another default path defined in <code>luaconf.h</code>). |
| 4749 | 4848 | |
| 4750 | | −<p><a name="pdf-package.loaded"></a><hr/><h3><code>package.loaded</code></h3> |
| 4849 | +<p><a name="pdf-package.loaded"></a><hr /><h3><code>package.loaded</code></h3> |
| 4751 | 4850 | |
| 4752 | 4851 | <p>A table used by <a href="#pdf-require"><code>require</code></a> to control which |
| 4753 | 4852 | modules are already loaded. |
| @@ -4755,27 +4854,34 @@ When you require a module <code>modname</code> and · 1 unmodified line |
| 4755 | 4854 | <code>package.loaded[modname]</code> is not false, |
| 4756 | 4855 | <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. |
| 4757 | 4856 | |
| 4758 | | −<p><a name="pdf-package.loadlib"></a><hr/><h3><code>package.loadlib (libname, funcname)</code></h3> |
| 4857 | +<p><a name="pdf-package.loadlib"></a><hr /><h3><code>package.loadlib (libname, funcname)</code></h3> |
| 4759 | 4858 | |
| 4760 | | −<p>Links the program with the dynamic C library <code>libname</code>. |
| 4859 | +<p>Dynamically links the host program with the C library <code>libname</code>. |
| 4761 | 4860 | Inside this library, looks for a function <code>funcname</code> |
| 4762 | 4861 | and returns this function as a C function. |
| 4862 | +(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). |
| 4763 | 4863 | |
| 4764 | | −<p><code>libname</code> must be the complete file name of the C library, |
| 4765 | | −including any eventual path and extension. |
| 4864 | +<p>This is a low-level function. |
| 4865 | +It completely bypasses the package and module system. |
| 4866 | +Unlike <a href="#pdf-require"><code>require</code></a>, |
| 4867 | +it does not perform any path searching or automatically adds extensions. |
| 4868 | +<code>libname</code> must be the complete file name of the C library, |
| 4869 | +including if necessary a path and extension. |
| 4870 | +<code>funcname</code> must be the exact name exported by the C library |
| 4871 | +(which may depend on the C compiler and linker used). |
| 4766 | 4872 | |
| 4767 | 4873 | <p>This function is not supported by ANSI C. |
| 4768 | 4874 | As such, it is only available on some platforms |
| 4769 | | −(Windows, Linux, Solaris, BSD, plus other Unix systems that |
| 4770 | | −support the <code>dlfcn</code> standard). |
| 4875 | +(Windows, Linux, Mac OS X, Solaris, BSD, |
| 4876 | +plus other Unix systems that support the <code>dlfcn</code> standard). |
| 4771 | 4877 | |
| 4772 | | −<p><a name="pdf-package.path"></a><hr/><h3><code>package.path</code></h3> |
| 4878 | +<p><a name="pdf-package.path"></a><hr /><h3><code>package.path</code></h3> |
| 4773 | 4879 | |
| 4774 | 4880 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. |
| 4775 | 4881 | |
| 4776 | 4882 | <p>At start-up, Lua initializes this variable with |
| 4777 | 4883 | the value of the environment variable <code>LUA_PATH</code> or |
| 4778 | | −with a compiled-defined default path, |
| 4884 | +with a default path defined in <code>luaconf.h</code>, |
| 4779 | 4885 | if the environment variable is not defined. |
| 4780 | 4886 | Any <code>";;"</code> in the value of the environment variable |
| 4781 | 4887 | is replaced by the default path. |
| @@ -4790,21 +4896,21 @@ So, for instance, if the Lua path is · 8 unmodified lines |
| 4790 | 4896 | <pre> |
| 4791 | 4897 | "./?.lua;./?.lc;/usr/local/?/init.lua" |
| 4792 | 4898 | </pre> |
| 4793 | | −the search for a Lua loader for module <code>mod</code> |
| 4899 | +the search for a Lua loader for module <code>foo</code> |
| 4794 | 4900 | will try to load the files |
| 4795 | | −<code>./mod.lua</code>, <code>./mod.lc</code>, and |
| 4796 | | −<code>/usr/local/mod/init.lua</code>, in that order. |
| 4901 | +<code>./foo.lua</code>, <code>./foo.lc</code>, and |
| 4902 | +<code>/usr/local/foo/init.lua</code>, in that order. |
| 4797 | 4903 | |
| 4798 | | −<p><a name="pdf-package.preload"></a><hr/><h3><code>package.preload</code></h3> |
| 4904 | +<p><a name="pdf-package.preload"></a><hr /><h3><code>package.preload</code></h3> |
| 4799 | 4905 | |
| 4800 | 4906 | <p>A table to store loaders for specific modules |
| 4801 | 4907 | (see <a href="#pdf-require"><code>require</code></a>). |
| 4802 | 4908 | |
| 4803 | | −<p><a name="pdf-package.seeall"></a><hr/><h3><code>package.seeall (module)</code></h3> |
| 4909 | +<p><a name="pdf-package.seeall"></a><hr /><h3><code>package.seeall (module)</code></h3> |
| 4804 | 4910 | |
| 4805 | 4911 | <p>Sets a metatable for <code>module</code> with |
| 4806 | | −its <code>__index</code> field refering to the global environment, |
| 4807 | | −so that this module inherits undefined values |
| 4912 | +its <code>__index</code> field referring to the global environment, |
| 4913 | +so that this module inherits values |
| 4808 | 4914 | from the global environment. |
| 4809 | 4915 | To be used as an option to function <a href="#pdf-module"><code>module</code></a>. |
| 4810 | 4916 | |
| @@ -4821,12 +4927,12 @@ Thus, the last character is at position <em>-1</em>, and so on. · 10 unmodified lines |
| 4821 | 4927 | <p>The string library provides all its functions inside the table |
| 4822 | 4928 | <code>string</code>. |
| 4823 | 4929 | It also sets a metatable for strings |
| 4824 | | −wherein <code>__index</code> points to itself. |
| 4825 | | −Therefore, you can use the string function is object-oriented style. |
| 4930 | +where the <code>__index</code> field points to the metatable itself. |
| 4931 | +Therefore, you can use the string functions in object-oriented style. |
| 4826 | 4932 | For instance, <code>string.byte(s, i)</code> |
| 4827 | 4933 | can be written as <code>s:byte(i)</code>. |
| 4828 | 4934 | |
| 4829 | | −<p><a name="pdf-string.byte"></a><hr/><h3><code>string.byte (s [, i [, j]])</code></h3> |
| 4935 | +<p><a name="pdf-string.byte"></a><hr /><h3><code>string.byte (s [, i [, j]])</code></h3> |
| 4830 | 4936 | Returns the internal numerical codes of the characters <code>s[i]</code>, |
| 4831 | 4937 | <code>s[i+1]</code>, ..., <code>s[j]</code>. |
| 4832 | 4938 | The default value for <code>i</code> is 1; |
| @@ -4834,25 +4940,25 @@ the default value for <code>j</code> is <code>i</code>. · 1 unmodified line |
| 4834 | 4940 | |
| 4835 | 4941 | <p>Note that numerical codes are not necessarily portable across platforms. |
| 4836 | 4942 | |
| 4837 | | −<p><a name="pdf-string.char"></a><hr/><h3><code>string.char (i1, i2, ...)</code></h3> |
| 4943 | +<p><a name="pdf-string.char"></a><hr /><h3><code>string.char (i1, i2, ...)</code></h3> |
| 4838 | 4944 | Receives 0 or more integers. |
| 4839 | 4945 | Returns a string with length equal to the number of arguments, |
| 4840 | 4946 | in which each character has the internal numerical code equal |
| 4841 | | −to its correspondent argument. |
| 4947 | +to its corresponding argument. |
| 4842 | 4948 | |
| 4843 | 4949 | <p>Note that numerical codes are not necessarily portable across platforms. |
| 4844 | 4950 | |
| 4845 | | −<p><a name="pdf-string.dump"></a><hr/><h3><code>string.dump (function)</code></h3> |
| 4951 | +<p><a name="pdf-string.dump"></a><hr /><h3><code>string.dump (function)</code></h3> |
| 4846 | 4952 | |
| 4847 | | −<p>Returns a binary representation of the given function, |
| 4953 | +<p>Returns a string containing a binary representation of the given function, |
| 4848 | 4954 | so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on that string returns |
| 4849 | 4955 | a copy of the function. |
| 4850 | | −<code>function</code> must be a Lua function. |
| 4956 | +<code>function</code> must be a Lua function without upvalues. |
| 4851 | 4957 | |
| 4852 | | −<p><a name="pdf-string.find"></a><hr/><h3><code>string.find (s, pattern [, init [, plain]])</code></h3> |
| 4853 | | −Looks for the first <em>match</em> of |
| 4958 | +<p><a name="pdf-string.find"></a><hr /><h3><code>string.find (s, pattern [, init [, plain]])</code></h3> |
| 4959 | +Looks for the first match of |
| 4854 | 4960 | <code>pattern</code> in the string <code>s</code>. |
| 4855 | | −If it finds one, then <code>find</code> returns the indices of <code>s</code> |
| 4961 | +If it finds a match, then <code>find</code> returns the indices of <code>s</code> |
| 4856 | 4962 | where this occurrence starts and ends; |
| 4857 | 4963 | otherwise, it returns <b>nil</b>. |
| 4858 | 4964 | A third, optional numerical argument <code>init</code> specifies |
| @@ -4862,26 +4968,27 @@ A value of <b>true</b> as a fourth, optional argument <code>plain</code> · 3 unmodified lines |
| 4862 | 4968 | turns off the pattern matching facilities, |
| 4863 | 4969 | so the function does a plain "find substring" operation, |
| 4864 | 4970 | with no characters in <code>pattern</code> being considered "magic". |
| 4865 | | −Note that if <code>plain</code> is given, then <code>init</code> must be given too. |
| 4971 | +Note that if <code>plain</code> is given, then <code>init</code> must be given as well. |
| 4866 | 4972 | |
| 4867 | 4973 | <p>If the pattern has captures, |
| 4868 | 4974 | then in a successful match |
| 4869 | 4975 | the captured values are also returned, |
| 4870 | 4976 | after the two indices. |
| 4871 | 4977 | |
| 4872 | | −<p><a name="format"></a><a name="pdf-string.format"></a><hr/><h3><code>string.format (formatstring, e1, e2, ...)</code></h3> |
| 4978 | +<p><a name="format"></a><a name="pdf-string.format"></a><hr /><h3><code>string.format (formatstring, e1, e2, ...)</code></h3> |
| 4873 | 4979 | Returns a formatted version of its variable number of arguments |
| 4874 | 4980 | following the description given in its first argument (which must be a string). |
| 4875 | 4981 | The format string follows the same rules as the <code>printf</code> family of |
| 4876 | 4982 | standard C functions. |
| 4877 | 4983 | The only differences are that the options/modifiers |
| 4878 | 4984 | <code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, |
| 4879 | | −and <code>h</code> are not supported, |
| 4880 | | −and there is an extra option, <code>q</code>. |
| 4985 | +and <code>h</code> are not supported |
| 4986 | +and that there is an extra option, <code>q</code>. |
| 4881 | 4987 | The <code>q</code> option formats a string in a form suitable to be safely read |
| 4882 | 4988 | back by the Lua interpreter: |
| 4883 | 4989 | The string is written between double quotes, |
| 4884 | | −and all double quotes, newlines, and backslashes in the string |
| 4990 | +and all double quotes, newlines, embedded zeros, |
| 4991 | +and backslashes in the string |
| 4885 | 4992 | are correctly escaped when written. |
| 4886 | 4993 | For instance, the call |
| 4887 | 4994 | <pre> |
| @@ -4901,12 +5008,12 @@ whereas <code>q</code> and <code>s</code> expect a string. · 13 unmodified lines |
| 4901 | 5008 | <p>This function does not accept string values |
| 4902 | 5009 | containing embedded zeros. |
| 4903 | 5010 | |
| 4904 | | −<p><a name="pdf-string.gmatch"></a><hr/><h3><code>string.gmatch (s, pat)</code></h3> |
| 5011 | +<p><a name="pdf-string.gmatch"></a><hr /><h3><code>string.gmatch (s, pattern)</code></h3> |
| 4905 | 5012 | Returns an iterator function that, |
| 4906 | 5013 | each time it is called, |
| 4907 | | −returns the next captures from pattern <code>pat</code> over string <code>s</code>. |
| 5014 | +returns the next captures from <code>pattern</code> over string <code>s</code>. |
| 4908 | 5015 | |
| 4909 | | −<p>If <code>pat</code> specifies no captures, |
| 5016 | +<p>If <code>pattern</code> specifies no captures, |
| 4910 | 5017 | then the whole match is produced in each call. |
| 4911 | 5018 | |
| 4912 | 5019 | <p>As an example, the following loop |
| @@ -4928,11 +5035,12 @@ given string into a table: · 15 unmodified lines |
| 4928 | 5035 | end |
| 4929 | 5036 | </pre> |
| 4930 | 5037 | |
| 4931 | | −<p><a name="pdf-string.gsub"></a><hr/><h3><code>string.gsub (s, pat, repl [, n])</code></h3> |
| 5038 | +<p><a name="pdf-string.gsub"></a><hr /><h3><code>string.gsub (s, pattern, repl [, n])</code></h3> |
| 4932 | 5039 | Returns a copy of <code>s</code> |
| 4933 | | −in which all occurrences of the pattern <code>pat</code> have been |
| 4934 | | −replaced by a replacement string specified by <code>repl</code>. |
| 4935 | | −<code>gsub</code> also returns, as a second value, |
| 5040 | +in which all occurrences of the <code>pattern</code> have been |
| 5041 | +replaced by a replacement string specified by <code>repl</code>, |
| 5042 | +which may be a string, a table, or a function. |
| 5043 | +<code>gsub</code> also returns, as its second value, |
| 4936 | 5044 | the total number of substitutions made. |
| 4937 | 5045 | |
| 4938 | 5046 | <p>If <code>repl</code> is a string, then its value is used for replacement. |
| @@ -4943,6 +5051,11 @@ stands for the value of the <em>n</em>-th captured substring (see below). · 4 unmodified lines |
| 4943 | 5051 | The sequence <code>%0</code> stands for the whole match. |
| 4944 | 5052 | The sequence <code>%%</code> stands for a single <code>%</code>. |
| 4945 | 5053 | |
| 5054 | +<p>If <code>repl</code> is a table, then the table is queried for every match, |
| 5055 | +using the first capture as the key; |
| 5056 | +if the pattern specifies no captures, |
| 5057 | +then the whole match is used as the key. |
| 5058 | + |
| 4946 | 5059 | <p>If <code>repl</code> is a function, then this function is called every time a |
| 4947 | 5060 | match occurs, with all captured substrings passed as arguments, |
| 4948 | 5061 | in order; |
| @@ -4951,9 +5064,10 @@ then the whole match is passed as a sole argument. · 2 unmodified lines |
| 4951 | 5064 | If <code>repl</code> is a table, then this table is queried with the |
| 4952 | 5065 | value of the first capture or of the whole match, |
| 4953 | 5066 | if the pattern specifies no captures. |
| 4954 | | −In both cases, |
| 4955 | | −if the value returned by the function or resulted by the query |
| 4956 | | −is a string, |
| 5067 | + |
| 5068 | +<p>In both cases, |
| 5069 | +if the value returned by the function or by the table query |
| 5070 | +is a string or a number, |
| 4957 | 5071 | then it is used as the replacement string; |
| 4958 | 5072 | otherwise, if it is <b>false</b> or <b>nil</b>, |
| 4959 | 5073 | then there is no replacement |
| @@ -4962,7 +5076,7 @@ then there is no replacement · 2 unmodified lines |
| 4962 | 5076 | <p>The optional last parameter <code>n</code> limits |
| 4963 | 5077 | the maximum number of substitutions to occur. |
| 4964 | 5078 | For instance, when <code>n</code> is 1 only the first occurrence of |
| 4965 | | −<code>pat</code> is replaced. |
| 5079 | +<code>pattern</code> is replaced. |
| 4966 | 5080 | |
| 4967 | 5081 | <p>Here are some examples: |
| 4968 | 5082 | <pre> |
| @@ -4983,24 +5097,24 @@ For instance, when <code>n</code> is 1 only the first occurrence of · 14 unmodified lines |
| 4983 | 5097 | end) |
| 4984 | 5098 | --> x="4+5 = 9" |
| 4985 | 5099 | |
| 4986 | | − local t = {name="lua", version="5.0"} |
| 4987 | | − x = string.gsub("$name_$version.tar.gz", "%$(%w+)", t) |
| 4988 | | − --> x="lua_5.0.tar.gz" |
| 5100 | + local t = {name="lua", version="5.1"} |
| 5101 | + x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) |
| 5102 | + --> x="lua-5.1.tar.gz" |
| 4989 | 5103 | </pre> |
| 4990 | 5104 | |
| 4991 | | −<p><a name="pdf-string.len"></a><hr/><h3><code>string.len (s)</code></h3> |
| 5105 | +<p><a name="pdf-string.len"></a><hr /><h3><code>string.len (s)</code></h3> |
| 4992 | 5106 | Receives a string and returns its length. |
| 4993 | 5107 | The empty string <code>""</code> has length 0. |
| 4994 | 5108 | Embedded zeros are counted, |
| 4995 | 5109 | so <code>"a\000bc\000"</code> has length 5. |
| 4996 | 5110 | |
| 4997 | | −<p><a name="pdf-string.lower"></a><hr/><h3><code>string.lower (s)</code></h3> |
| 5111 | +<p><a name="pdf-string.lower"></a><hr /><h3><code>string.lower (s)</code></h3> |
| 4998 | 5112 | Receives a string and returns a copy of that string with all |
| 4999 | 5113 | uppercase letters changed to lowercase. |
| 5000 | 5114 | All other characters are left unchanged. |
| 5001 | | −The definition of what is an uppercase letter depends on the current locale. |
| 5115 | +The definition of what an uppercase letter is depends on the current locale. |
| 5002 | 5116 | |
| 5003 | | −<p><a name="pdf-string.match"></a><hr/><h3><code>string.match (s, pattern [, init])</code></h3> |
| 5117 | +<p><a name="pdf-string.match"></a><hr /><h3><code>string.match (s, pattern [, init])</code></h3> |
| 5004 | 5118 | Looks for the first <em>match</em> of |
| 5005 | 5119 | <code>pattern</code> in the string <code>s</code>. |
| 5006 | 5120 | If it finds one, then <code>match</code> returns |
| @@ -5012,14 +5126,14 @@ A third, optional numerical argument <code>init</code> specifies · 5 unmodified lines |
| 5012 | 5126 | where to start the search; |
| 5013 | 5127 | its default value is 1 and may be negative. |
| 5014 | 5128 | |
| 5015 | | −<p><a name="pdf-string.rep"></a><hr/><h3><code>string.rep (s, n)</code></h3> |
| 5129 | +<p><a name="pdf-string.rep"></a><hr /><h3><code>string.rep (s, n)</code></h3> |
| 5016 | 5130 | Returns a string that is the concatenation of <code>n</code> copies of |
| 5017 | 5131 | the string <code>s</code>. |
| 5018 | 5132 | |
| 5019 | | −<p><a name="pdf-string.reverse"></a><hr/><h3><code>string.reverse (s)</code></h3> |
| 5133 | +<p><a name="pdf-string.reverse"></a><hr /><h3><code>string.reverse (s)</code></h3> |
| 5020 | 5134 | Returns a string that is the string <code>s</code> reversed. |
| 5021 | 5135 | |
| 5022 | | −<p><a name="pdf-string.sub"></a><hr/><h3><code>string.sub (s, i [, j])</code></h3> |
| 5136 | +<p><a name="pdf-string.sub"></a><hr /><h3><code>string.sub (s, i [, j])</code></h3> |
| 5023 | 5137 | Returns the substring of <code>s</code> that |
| 5024 | 5138 | starts at <code>i</code> and continues until <code>j</code>; |
| 5025 | 5139 | <code>i</code> and <code>j</code> may be negative. |
| @@ -5031,11 +5145,11 @@ with length <code>j</code>, · 5 unmodified lines |
| 5031 | 5145 | and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> |
| 5032 | 5146 | with length <code>i</code>. |
| 5033 | 5147 | |
| 5034 | | −<p><a name="pdf-string.upper"></a><hr/><h3><code>string.upper (s)</code></h3> |
| 5148 | +<p><a name="pdf-string.upper"></a><hr /><h3><code>string.upper (s)</code></h3> |
| 5035 | 5149 | Receives a string and returns a copy of that string with all |
| 5036 | 5150 | lowercase letters changed to uppercase. |
| 5037 | 5151 | All other characters are left unchanged. |
| 5038 | | −The definition of what is a lowercase letter depends on the current locale. |
| 5152 | +The definition of what a lowercase letter is depends on the current locale. |
| 5039 | 5153 | |
| 5040 | 5154 | <p><a name="pm"></a><h3>Patterns</h3> |
| 5041 | 5155 | |
| @@ -5043,7 +5157,7 @@ The definition of what is a lowercase letter depends on the current locale. · 1 unmodified line |
| 5043 | 5157 | A <em>character class</em> is used to represent a set of characters. |
| 5044 | 5158 | The following combinations are allowed in describing a character class: |
| 5045 | 5159 | <ul> |
| 5046 | | −<li><b><em>x</em></b> (where <em>x</em> is not one of the magic characters |
| 5160 | +<li><b><em>x</em></b> (where <em>x</em> is not one of the <em>magic characters</em> |
| 5047 | 5161 | <code>^$()%.[]*+-?</code>) |
| 5048 | 5162 | --- represents the character <em>x</em> itself. |
| 5049 | 5163 | <li><b><code>.</code></b> --- (a dot) represents all characters. |
| @@ -5117,11 +5231,11 @@ these repetition items will always match the <em>shortest</em> possible sequence · 67 unmodified lines |
| 5117 | 5231 | a single character class followed by `<code>?</code>´, |
| 5118 | 5232 | which matches 0 or 1 occurrence of a character in the class; |
| 5119 | 5233 | <li> |
| 5120 | | −<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; |
| 5234 | +<code>%</code><em>n</em>, for <em>n</em> between 1 and 9; |
| 5121 | 5235 | such item matches a substring equal to the <em>n</em>-th captured string |
| 5122 | 5236 | (see below); |
| 5123 | 5237 | <li> |
| 5124 | | −<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; |
| 5238 | +<code>%b</code><em>xy</em>, where <em>x</em> and <em>y</em> are two distinct characters; |
| 5125 | 5239 | such item matches strings that start with <em>x</em>, end with <em>y</em>, |
| 5126 | 5240 | and where the <em>x</em> and <em>y</em> are <em>balanced</em>. |
| 5127 | 5241 | This means that, if one reads the string from left to right, |
| @@ -5149,8 +5263,8 @@ Captures are numbered according to their left parentheses. · 21 unmodified lines |
| 5149 | 5263 | For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, |
| 5150 | 5264 | the part of the string matching <code>"a*(.)%w(%s*)"</code> is |
| 5151 | 5265 | stored as the first capture (and therefore has number 1); |
| 5152 | | −the character matching <code>.</code> is captured with number 2, |
| 5153 | | −and the part matching <code>%s*</code> has number 3. |
| 5266 | +the character matching <code>"."</code> is captured with number 2, |
| 5267 | +and the part matching <code>"%s*"</code> has number 3. |
| 5154 | 5268 | |
| 5155 | 5269 | <p>As a special case, the empty capture <code>()</code> captures |
| 5156 | 5270 | the current string position (a number). |
| @@ -5168,14 +5282,14 @@ represents an array or a list. · 11 unmodified lines |
| 5168 | 5282 | For those functions, when we talk about "the length" of a table |
| 5169 | 5283 | we mean the result of the length operator. |
| 5170 | 5284 | |
| 5171 | | −<p><a name="pdf-table.concat"></a><hr/><h3><code>table.concat (table [, sep [, i [, j]]])</code></h3> |
| 5285 | +<p><a name="pdf-table.concat"></a><hr /><h3><code>table.concat (table [, sep [, i [, j]]])</code></h3> |
| 5172 | 5286 | Returns <code>table[i]..sep..table[i+1] ... sep..table[j]</code>. |
| 5173 | 5287 | The default value for <code>sep</code> is the empty string, |
| 5174 | 5288 | the default for <code>i</code> is 1, |
| 5175 | 5289 | and the default for <code>j</code> is the length of the table. |
| 5176 | 5290 | If <code>i</code> is greater than <code>j</code>, returns the empty string. |
| 5177 | 5291 | |
| 5178 | | −<p><a name="pdf-table.insert"></a><hr/><h3><code>table.insert (table, [pos,] value)</code></h3> |
| 5292 | +<p><a name="pdf-table.insert"></a><hr /><h3><code>table.insert (table, [pos,] value)</code></h3> |
| 5179 | 5293 | |
| 5180 | 5294 | <p>Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, |
| 5181 | 5295 | shifting up other elements to open space, if necessary. |
| @@ -5184,12 +5298,12 @@ where <code>n</code> is the length of the table (see <a href="#len-op">2.5.5</a> · 2 unmodified lines |
| 5184 | 5298 | so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end |
| 5185 | 5299 | of table <code>t</code>. |
| 5186 | 5300 | |
| 5187 | | −<p><a name="pdf-table.maxn(table)"></a><hr/><h3><code>table.maxn(table)</code></h3> |
| 5301 | +<p><a name="pdf-table.maxn"></a><hr /><h3><code>table.maxn (table)</code></h3> |
| 5188 | 5302 | |
| 5189 | 5303 | <p>Returns the largest positive numerical index of the given table, |
| 5190 | 5304 | or zero if the table has no positive numerical indices. |
| 5191 | 5305 | |
| 5192 | | −<p><a name="pdf-table.remove"></a><hr/><h3><code>table.remove (table [, pos])</code></h3> |
| 5306 | +<p><a name="pdf-table.remove"></a><hr /><h3><code>table.remove (table [, pos])</code></h3> |
| 5193 | 5307 | |
| 5194 | 5308 | <p>Removes from <code>table</code> the element at position <code>pos</code>, |
| 5195 | 5309 | shifting down other elements to close the space, if necessary. |
| @@ -5199,7 +5313,7 @@ where <code>n</code> is the length of the table, · 3 unmodified lines |
| 5199 | 5313 | so that a call <code>table.remove(t)</code> removes the last element |
| 5200 | 5314 | of table <code>t</code>. |
| 5201 | 5315 | |
| 5202 | | −<p><a name="pdf-table.sort"></a><hr/><h3><code>table.sort (table [, comp])</code></h3> |
| 5316 | +<p><a name="pdf-table.sort"></a><hr /><h3><code>table.sort (table [, comp])</code></h3> |
| 5203 | 5317 | Sorts table elements in a given order, <em>in-place</em>, |
| 5204 | 5318 | from <code>table[1]</code> to <code>table[n]</code>, |
| 5205 | 5319 | where <code>n</code> is the length of the table. |
| @@ -5211,7 +5325,7 @@ when the first is less than the second · 5 unmodified lines |
| 5211 | 5325 | If <code>comp</code> is not given, |
| 5212 | 5326 | then the standard Lua operator <code><</code> is used instead. |
| 5213 | 5327 | |
| 5214 | | −<p>The sort algorithm is not stable, |
| 5328 | +<p>The sort algorithm is not stable; |
| 5215 | 5329 | that is, elements considered equal by the given order |
| 5216 | 5330 | may have their relative positions changed by the sort. |
| 5217 | 5331 | |
| @@ -5276,7 +5390,7 @@ Equal seeds produce equal sequences of numbers. · 58 unmodified lines |
| 5276 | 5390 | <p><a name="libio"></a><a name="5.7"></a><h2>5.7 - Input and Output Facilities</h2> |
| 5277 | 5391 | |
| 5278 | 5392 | <p>The I/O library provides two different styles for file manipulation. |
| 5279 | | −The first one uses implicit file descriptors, |
| 5393 | +The first one uses implicit file descriptors; |
| 5280 | 5394 | that is, there are operations to set a default input file and a |
| 5281 | 5395 | default output file, |
| 5282 | 5396 | and all input/output operations are over those default files. |
| @@ -5297,16 +5411,16 @@ all I/O functions return <b>nil</b> on failure · 14 unmodified lines |
| 5297 | 5411 | (plus an error message as a second result) |
| 5298 | 5412 | and some value different from <b>nil</b> on success. |
| 5299 | 5413 | |
| 5300 | | −<p><a name="pdf-io.close"></a><hr/><h3><code>io.close ([file])</code></h3> |
| 5414 | +<p><a name="pdf-io.close"></a><hr /><h3><code>io.close ([file])</code></h3> |
| 5301 | 5415 | |
| 5302 | 5416 | <p>Equivalent to <code>file:close()</code>. |
| 5303 | 5417 | Without a <code>file</code>, closes the default output file. |
| 5304 | 5418 | |
| 5305 | | −<p><a name="pdf-io.flush"></a><hr/><h3><code>io.flush ()</code></h3> |
| 5419 | +<p><a name="pdf-io.flush"></a><hr /><h3><code>io.flush ()</code></h3> |
| 5306 | 5420 | |
| 5307 | 5421 | <p>Equivalent to <code>file:flush</code> over the default output file. |
| 5308 | 5422 | |
| 5309 | | −<p><a name="pdf-io.input"></a><hr/><h3><code>io.input ([file])</code></h3> |
| 5423 | +<p><a name="pdf-io.input"></a><hr /><h3><code>io.input ([file])</code></h3> |
| 5310 | 5424 | |
| 5311 | 5425 | <p>When called with a file name, it opens the named file (in text mode), |
| 5312 | 5426 | and sets its handle as the default input file. |
| @@ -5318,7 +5432,7 @@ it returns the current default input file. · 5 unmodified lines |
| 5318 | 5432 | <p>In case of errors this function raises the error, |
| 5319 | 5433 | instead of returning an error code. |
| 5320 | 5434 | |
| 5321 | | −<p><a name="pdf-io.lines"></a><hr/><h3><code>io.lines ([filename])</code></h3> |
| 5435 | +<p><a name="pdf-io.lines"></a><hr /><h3><code>io.lines ([filename])</code></h3> |
| 5322 | 5436 | |
| 5323 | 5437 | <p>Opens the given file name in read mode |
| 5324 | 5438 | and returns an iterator function that, |
| @@ -5333,11 +5447,11 @@ When the iterator function detects the end of file, · 8 unmodified lines |
| 5333 | 5447 | it returns <b>nil</b> (to finish the loop) and automatically closes the file. |
| 5334 | 5448 | |
| 5335 | 5449 | <p>The call <code>io.lines()</code> (without a file name) is equivalent |
| 5336 | | −to <code>io.input():lines()</code>, that is, it iterates over the |
| 5337 | | −lines of the default input file. |
| 5450 | +to <code>io.input():lines()</code>; |
| 5451 | +that is, it iterates over the lines of the default input file. |
| 5338 | 5452 | In that case it does not close the file when the loop ends. |
| 5339 | 5453 | |
| 5340 | | −<p><a name="pdf-io.open"></a><hr/><h3><code>io.open (filename [, mode])</code></h3> |
| 5454 | +<p><a name="pdf-io.open"></a><hr /><h3><code>io.open (filename [, mode])</code></h3> |
| 5341 | 5455 | |
| 5342 | 5456 | <p>This function opens a file, |
| 5343 | 5457 | in the mode specified in the string <code>mode</code>. |
| @@ -5346,24 +5460,24 @@ or, in case of errors, <b>nil</b> plus an error message. · 2 unmodified lines |
| 5346 | 5460 | |
| 5347 | 5461 | <p>The <code>mode</code> string can be any of the following: |
| 5348 | 5462 | <ul> |
| 5349 | | −<li><b>"r"</b> read mode (the default); |
| 5350 | | −<li><b>"w"</b> write mode; |
| 5351 | | −<li><b>"a"</b> append mode; |
| 5352 | | −<li><b>"r+"</b> update mode, all previous data is preserved; |
| 5353 | | −<li><b>"w+"</b> update mode, all previous data is erased; |
| 5354 | | −<li><b>"a+"</b> append update mode, previous data is preserved, |
| 5463 | +<li><b>"r"</b> --- read mode (the default); |
| 5464 | +<li><b>"w"</b> --- write mode; |
| 5465 | +<li><b>"a"</b> --- append mode; |
| 5466 | +<li><b>"r+"</b> --- update mode, all previous data is preserved; |
| 5467 | +<li><b>"w+"</b> --- update mode, all previous data is erased; |
| 5468 | +<li><b>"a+"</b> --- append update mode, previous data is preserved, |
| 5355 | 5469 | writing is only allowed at the end of file. |
| 5356 | 5470 | </ul> |
| 5357 | | −The <code>mode</code> string may also have a <code>b</code> at the end, |
| 5471 | +The <code>mode</code> string may also have a `<code>b</code>´ at the end, |
| 5358 | 5472 | which is needed in some systems to open the file in binary mode. |
| 5359 | 5473 | This string is exactly what is used in the |
| 5360 | 5474 | standard C function <code>fopen</code>. |
| 5361 | 5475 | |
| 5362 | | −<p><a name="pdf-io.output"></a><hr/><h3><code>io.output ([file])</code></h3> |
| 5476 | +<p><a name="pdf-io.output"></a><hr /><h3><code>io.output ([file])</code></h3> |
| 5363 | 5477 | |
| 5364 | 5478 | <p>Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. |
| 5365 | 5479 | |
| 5366 | | −<p><a name="pdf-io.popen"></a><hr/><h3><code>io.popen ([prog [, mode]])</code></h3> |
| 5480 | +<p><a name="pdf-io.popen"></a><hr /><h3><code>io.popen ([prog [, mode]])</code></h3> |
| 5367 | 5481 | |
| 5368 | 5482 | <p>Starts program <code>prog</code> in a separated process and returns |
| 5369 | 5483 | a file handle that you can use to read data from that program |
| @@ -5372,40 +5486,41 @@ or to write data to that program · 2 unmodified lines |
| 5372 | 5486 | (if <code>mode</code> is <code>"w"</code>). |
| 5373 | 5487 | |
| 5374 | 5488 | <p>This function is system dependent and is not available |
| 5375 | | −in all platforms. |
| 5489 | +on all platforms. |
| 5376 | 5490 | |
| 5377 | | −<p><a name="pdf-io.read"></a><hr/><h3><code>io.read (format1, ...)</code></h3> |
| 5491 | +<p><a name="pdf-io.read"></a><hr /><h3><code>io.read (format1, ...)</code></h3> |
| 5378 | 5492 | |
| 5379 | 5493 | <p>Equivalent to <code>io.input():read</code>. |
| 5380 | 5494 | |
| 5381 | | −<p><a name="pdf-io.tmpfile"></a><hr/><h3><code>io.tmpfile ()</code></h3> |
| 5495 | +<p><a name="pdf-io.tmpfile"></a><hr /><h3><code>io.tmpfile ()</code></h3> |
| 5382 | 5496 | |
| 5383 | 5497 | <p>Returns a handle for a temporary file. |
| 5384 | | −This file is open in update mode |
| 5498 | +This file is opened in update mode |
| 5385 | 5499 | and it is automatically removed when the program ends. |
| 5386 | 5500 | |
| 5387 | | −<p><a name="pdf-io.type"></a><hr/><h3><code>io.type (obj)</code></h3> |
| 5501 | +<p><a name="pdf-io.type"></a><hr /><h3><code>io.type (obj)</code></h3> |
| 5388 | 5502 | |
| 5389 | 5503 | <p>Checks whether <code>obj</code> is a valid file handle. |
| 5390 | 5504 | Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, |
| 5391 | 5505 | <code>"closed file"</code> if <code>obj</code> is a closed file handle, |
| 5392 | 5506 | and <b>nil</b> if <code>obj</code> is not a file handle. |
| 5393 | 5507 | |
| 5394 | | −<p><a name="pdf-io.write"></a><hr/><h3><code>io.write (value1, ...)</code></h3> |
| 5508 | +<p><a name="pdf-io.write"></a><hr /><h3><code>io.write (value1, ...)</code></h3> |
| 5395 | 5509 | |
| 5396 | 5510 | <p>Equivalent to <code>io.output():write</code>. |
| 5397 | 5511 | |
| 5398 | | −<p><a name="pdf-file:close"></a><hr/><h3><code>file:close ()</code></h3> |
| 5512 | +<p><a name="pdf-file:close"></a><hr /><h3><code>file:close ()</code></h3> |
| 5399 | 5513 | |
| 5400 | 5514 | <p>Closes <code>file</code>. |
| 5401 | | −Note that files are automatically closed when garbage collected, |
| 5515 | +Note that files are automatically closed when |
| 5516 | +their handles are garbage collected, |
| 5402 | 5517 | but that takes an unpredictable time to happen. |
| 5403 | 5518 | |
| 5404 | | −<p><a name="flush"></a><a name="pdf-file:flush"></a><hr/><h3><code>file:flush ()</code></h3> |
| 5519 | +<p><a name="flush"></a><a name="pdf-file:flush"></a><hr /><h3><code>file:flush ()</code></h3> |
| 5405 | 5520 | |
| 5406 | 5521 | <p>Saves any written data to <code>file</code>. |
| 5407 | 5522 | |
| 5408 | | −<p><a name="pdf-file:lines"></a><hr/><h3><code>file:lines ()</code></h3> |
| 5523 | +<p><a name="pdf-file:lines"></a><hr /><h3><code>file:lines ()</code></h3> |
| 5409 | 5524 | |
| 5410 | 5525 | <p>Returns an iterator function that, |
| 5411 | 5526 | each time it is called, |
| @@ -5418,7 +5533,7 @@ will iterate over all lines of the file. · 6 unmodified lines |
| 5418 | 5533 | (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file |
| 5419 | 5534 | when the loop ends.) |
| 5420 | 5535 | |
| 5421 | | −<p><a name="pdf-file:read"></a><hr/><h3><code>file:read (format1, ...)</code></h3> |
| 5536 | +<p><a name="pdf-file:read"></a><hr /><h3><code>file:read (format1, ...)</code></h3> |
| 5422 | 5537 | |
| 5423 | 5538 | <p>Reads the file <code>file</code>, |
| 5424 | 5539 | according to the given formats, which specify what to read. |
| @@ -5445,7 +5560,7 @@ it reads nothing and returns an empty string, · 20 unmodified lines |
| 5445 | 5560 | or <b>nil</b> on end of file. |
| 5446 | 5561 | </ul> |
| 5447 | 5562 | |
| 5448 | | −<p><a name="pdf-file:seek"></a><hr/><h3><code>file:seek ([whence] [, offset])</code></h3> |
| 5563 | +<p><a name="pdf-file:seek"></a><hr /><h3><code>file:seek ([whence] [, offset])</code></h3> |
| 5449 | 5564 | |
| 5450 | 5565 | <p>Sets and gets the file position, |
| 5451 | 5566 | measured from the beginning of the file, |
| @@ -5470,26 +5585,29 @@ beginning of the file (and returns 0); · 18 unmodified lines |
| 5470 | 5585 | and the call <code>file:seek("end")</code> sets the position to the |
| 5471 | 5586 | end of the file, and returns its size. |
| 5472 | 5587 | |
| 5473 | | −<p><a name="pdf-file:setvbuf"></a><hr/><h3><code>file:setvbuf (mode [, size])</code></h3> |
| 5588 | +<p><a name="pdf-file:setvbuf"></a><hr /><h3><code>file:setvbuf (mode [, size])</code></h3> |
| 5474 | 5589 | |
| 5475 | 5590 | <p>Sets the buffering mode for an output file. |
| 5476 | 5591 | There are three available modes: |
| 5477 | 5592 | <ul> |
| 5478 | | −<li><b>"no"</b> no buffering; any output operation appear immediately. |
| 5479 | | −<li><b>"full"</b> full buffering; output operation is performed only |
| 5480 | | −when the buffer is full (or when you <code>flush</code> the file (see <a href="#flush">5.7</a>)). |
| 5481 | | −<li><b>"line"</b> line buffering; output is buffered until a newline is |
| 5482 | | −output or there is any input from some special files |
| 5593 | +<li><b>"no"</b> --- |
| 5594 | +no buffering; the result of any output operation appears immediately. |
| 5595 | +<li><b>"full"</b> --- |
| 5596 | +full buffering; output operation is performed only |
| 5597 | +when the buffer is full (or when you explicitly <code>flush</code> the file (see <a href="#flush">5.7</a>)). |
| 5598 | +<li><b>"line"</b> --- |
| 5599 | +line buffering; output is buffered until a newline is output |
| 5600 | +or there is any input from some special files |
| 5483 | 5601 | (such as a terminal device). |
| 5484 | 5602 | </ul> |
| 5485 | 5603 | For the last two cases, <code>sizes</code> |
| 5486 | 5604 | specifies the size of the buffer, in bytes. |
| 5487 | 5605 | The default is an appropriate size. |
| 5488 | 5606 | |
| 5489 | | −<p><a name="pdf-file:write"></a><hr/><h3><code>file:write (value1, ...)</code></h3> |
| 5607 | +<p><a name="pdf-file:write"></a><hr /><h3><code>file:write (value1, ...)</code></h3> |
| 5490 | 5608 | |
| 5491 | 5609 | <p>Writes the value of each of its arguments to |
| 5492 | | −the filehandle <code>file</code>. |
| 5610 | +the <code>file</code>. |
| 5493 | 5611 | The arguments must be strings or numbers. |
| 5494 | 5612 | To write other values, |
| 5495 | 5613 | use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. |
| @@ -5498,12 +5616,12 @@ use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.fo · 2 unmodified lines |
| 5498 | 5616 | |
| 5499 | 5617 | <p>This library is implemented through table <code>os</code>. |
| 5500 | 5618 | |
| 5501 | | −<p><a name="pdf-os.clock"></a><hr/><h3><code>os.clock ()</code></h3> |
| 5619 | +<p><a name="pdf-os.clock"></a><hr /><h3><code>os.clock ()</code></h3> |
| 5502 | 5620 | |
| 5503 | | −<p>Returns an approximation of the amount of CPU time |
| 5504 | | −used by the program, in seconds. |
| 5621 | +<p>Returns an approximation of the amount in seconds of CPU time |
| 5622 | +used by the program. |
| 5505 | 5623 | |
| 5506 | | −<p><a name="pdf-os.date"></a><hr/><h3><code>os.date ([format [, time]])</code></h3> |
| 5624 | +<p><a name="pdf-os.date"></a><hr /><h3><code>os.date ([format [, time]])</code></h3> |
| 5507 | 5625 | |
| 5508 | 5626 | <p>Returns a string or a table containing date and time, |
| 5509 | 5627 | formatted according to the given string <code>format</code>. |
| @@ -5533,43 +5651,46 @@ formatted according to the same rules as the C function <code>strftime</code>. · 23 unmodified lines |
| 5533 | 5651 | the host system and on the current locale |
| 5534 | 5652 | (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). |
| 5535 | 5653 | |
| 5536 | | −<p><a name="pdf-os.difftime"></a><hr/><h3><code>os.difftime (t2, t1)</code></h3> |
| 5654 | +<p><a name="pdf-os.difftime"></a><hr /><h3><code>os.difftime (t2, t1)</code></h3> |
| 5537 | 5655 | |
| 5538 | 5656 | <p>Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. |
| 5539 | 5657 | In Posix, Windows, and some other systems, |
| 5540 | 5658 | this value is exactly <code>t2</code><em>-</em><code>t1</code>. |
| 5541 | 5659 | |
| 5542 | | −<p><a name="pdf-os.execute"></a><hr/><h3><code>os.execute (command)</code></h3> |
| 5660 | +<p><a name="pdf-os.execute"></a><hr /><h3><code>os.execute ([command])</code></h3> |
| 5543 | 5661 | |
| 5544 | 5662 | <p>This function is equivalent to the C function <code>system</code>. |
| 5545 | 5663 | It passes <code>command</code> to be executed by an operating system shell. |
| 5546 | 5664 | It returns a status code, which is system-dependent. |
| 5665 | +If <code>command</code> is absent, then it returns nonzero if a shell is available |
| 5666 | +and zero otherwise. |
| 5547 | 5667 | |
| 5548 | | −<p><a name="pdf-os.exit"></a><hr/><h3><code>os.exit ([code])</code></h3> |
| 5668 | +<p><a name="pdf-os.exit"></a><hr /><h3><code>os.exit ([code])</code></h3> |
| 5549 | 5669 | |
| 5550 | 5670 | <p>Calls the C function <code>exit</code>, |
| 5551 | 5671 | with an optional <code>code</code>, |
| 5552 | 5672 | to terminate the host program. |
| 5553 | 5673 | The default value for <code>code</code> is the success code. |
| 5554 | 5674 | |
| 5555 | | −<p><a name="pdf-os.getenv"></a><hr/><h3><code>os.getenv (varname)</code></h3> |
| 5675 | +<p><a name="pdf-os.getenv"></a><hr /><h3><code>os.getenv (varname)</code></h3> |
| 5556 | 5676 | |
| 5557 | 5677 | <p>Returns the value of the process environment variable <code>varname</code>, |
| 5558 | 5678 | or <b>nil</b> if the variable is not defined. |
| 5559 | 5679 | |
| 5560 | | −<p><a name="pdf-os.remove"></a><hr/><h3><code>os.remove (filename)</code></h3> |
| 5680 | +<p><a name="pdf-os.remove"></a><hr /><h3><code>os.remove (filename)</code></h3> |
| 5561 | 5681 | |
| 5562 | | −<p>Deletes the file with the given name. |
| 5682 | +<p>Deletes the file or directory with the given name. |
| 5683 | +Directories must be empty to be removed. |
| 5563 | 5684 | If this function fails, it returns <b>nil</b>, |
| 5564 | 5685 | plus a string describing the error. |
| 5565 | 5686 | |
| 5566 | | −<p><a name="pdf-os.rename"></a><hr/><h3><code>os.rename (oldname, newname)</code></h3> |
| 5687 | +<p><a name="pdf-os.rename"></a><hr /><h3><code>os.rename (oldname, newname)</code></h3> |
| 5567 | 5688 | |
| 5568 | | −<p>Renames file named <code>oldname</code> to <code>newname</code>. |
| 5689 | +<p>Renames file or directory named <code>oldname</code> to <code>newname</code>. |
| 5569 | 5690 | If this function fails, it returns <b>nil</b>, |
| 5570 | 5691 | plus a string describing the error. |
| 5571 | 5692 | |
| 5572 | | −<p><a name="pdf-os.setlocale"></a><hr/><h3><code>os.setlocale (locale [, category])</code></h3> |
| 5693 | +<p><a name="pdf-os.setlocale"></a><hr /><h3><code>os.setlocale (locale [, category])</code></h3> |
| 5573 | 5694 | |
| 5574 | 5695 | <p>Sets the current locale of the program. |
| 5575 | 5696 | <code>locale</code> is a string specifying a locale; |
| @@ -5580,7 +5701,7 @@ the default category is <code>"all"</code>. · 4 unmodified lines |
| 5580 | 5701 | The function returns the name of the new locale, |
| 5581 | 5702 | or <b>nil</b> if the request cannot be honored. |
| 5582 | 5703 | |
| 5583 | | −<p><a name="pdf-os.time"></a><hr/><h3><code>os.time ([table])</code></h3> |
| 5704 | +<p><a name="pdf-os.time"></a><hr /><h3><code>os.time ([table])</code></h3> |
| 5584 | 5705 | |
| 5585 | 5706 | <p>Returns the current time when called without arguments, |
| 5586 | 5707 | or a time representing the date and time specified by the given table. |
| @@ -5595,16 +5716,16 @@ In other systems, the meaning is not specified, · 8 unmodified lines |
| 5595 | 5716 | and the number returned by <code>time</code> can be used only as an argument to |
| 5596 | 5717 | <code>date</code> and <code>difftime</code>. |
| 5597 | 5718 | |
| 5598 | | −<p><a name="pdf-os.tmpname"></a><hr/><h3><code>os.tmpname ()</code></h3> |
| 5719 | +<p><a name="pdf-os.tmpname"></a><hr /><h3><code>os.tmpname ()</code></h3> |
| 5599 | 5720 | |
| 5600 | 5721 | <p>Returns a string with a file name that can |
| 5601 | 5722 | be used for a temporary file. |
| 5602 | 5723 | The file must be explicitly opened before its use |
| 5603 | | −and removed when no longer needed. |
| 5724 | +and explicitly removed when no longer needed. |
| 5604 | 5725 | |
| 5605 | | −<p><a name="libdebug"></a><a name="5.9"></a><h2>5.9 - The Reflexive Debug Interface</h2> |
| 5726 | +<p><a name="libdebug"></a><a name="5.9"></a><h2>5.9 - The Debug Library</h2> |
| 5606 | 5727 | |
| 5607 | | −<p>The <em>debug library</em> provides |
| 5728 | +<p>This library provides |
| 5608 | 5729 | the functionality of the debug interface to Lua programs. |
| 5609 | 5730 | You should exert care when using this library. |
| 5610 | 5731 | The functions provided here should be used exclusively for debugging |
| @@ -5614,14 +5735,15 @@ usual programming tool: · 3 unmodified lines |
| 5614 | 5735 | They can be very slow. |
| 5615 | 5736 | Moreover, several of its functions |
| 5616 | 5737 | violate some assumptions about Lua code |
| 5617 | | −(e.g., that local variables cannot be accessed from outside or |
| 5738 | +(e.g., that variables local to a function |
| 5739 | +cannot be accessed from outside or |
| 5618 | 5740 | that userdata metatables cannot be changed by Lua code) |
| 5619 | | −and therefore can compromise some otherwise secure code. |
| 5741 | +and therefore can compromise otherwise secure code. |
| 5620 | 5742 | |
| 5621 | 5743 | <p>All functions in this library are provided |
| 5622 | | −inside a <code>debug</code> table. |
| 5744 | +inside the <code>debug</code> table. |
| 5623 | 5745 | |
| 5624 | | −<p><a name="pdf-debug.debug"></a><hr/><h3><code>debug.debug ()</code></h3> |
| 5746 | +<p><a name="pdf-debug.debug"></a><hr /><h3><code>debug.debug ()</code></h3> |
| 5625 | 5747 | |
| 5626 | 5748 | <p>Enters an interactive mode with the user, |
| 5627 | 5749 | running each string that the user enters. |
| @@ -5631,22 +5753,22 @@ change their values, evaluate expressions, and so on. · 3 unmodified lines |
| 5631 | 5753 | A line containing only the word <code>cont</code> finishes this function, |
| 5632 | 5754 | so that the caller continues its execution. |
| 5633 | 5755 | |
| 5634 | | −<p>Note that commands for <a href="#pdf-debug.debug"><code>debug.debug</code></a> are not lexically nested |
| 5635 | | −with any function, so they have no direct access to local variables. |
| 5756 | +<p>Note that commands for <code>debug.debug</code> are not lexically nested |
| 5757 | +within any function, and so have no direct access to local variables. |
| 5636 | 5758 | |
| 5637 | | −<p><a name="pdf-debug.getfenv"></a><hr/><h3><code>debug.getfenv (o)</code></h3> |
| 5759 | +<p><a name="pdf-debug.getfenv"></a><hr /><h3><code>debug.getfenv (o)</code></h3> |
| 5638 | 5760 | Returns the environment of object <code>o</code>. |
| 5639 | 5761 | |
| 5640 | | −<p><a name="pdf-debug.gethook"></a><hr/><h3><code>debug.gethook ()</code></h3> |
| 5762 | +<p><a name="pdf-debug.gethook"></a><hr /><h3><code>debug.gethook ()</code></h3> |
| 5641 | 5763 | |
| 5642 | 5764 | <p>Returns the current hook settings, as three values: |
| 5643 | 5765 | the current hook function, the current hook mask, |
| 5644 | 5766 | and the current hook count |
| 5645 | 5767 | (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). |
| 5646 | 5768 | |
| 5647 | | −<p><a name="pdf-debug.getinfo"></a><hr/><h3><code>debug.getinfo (function [, what])</code></h3> |
| 5769 | +<p><a name="pdf-debug.getinfo"></a><hr /><h3><code>debug.getinfo (function [, what])</code></h3> |
| 5648 | 5770 | |
| 5649 | | −<p>This function returns a table with information about a function. |
| 5771 | +<p>Returns a table with information about a function. |
| 5650 | 5772 | You can give the function directly, |
| 5651 | 5773 | or you can give a number as the value of <code>function</code>, |
| 5652 | 5774 | which means the function running at level <code>function</code> of the call stack: |
| @@ -5664,11 +5786,11 @@ the option `<code>f</code>´ · 11 unmodified lines |
| 5664 | 5786 | adds a field named <code>func</code> with the function itself. |
| 5665 | 5787 | |
| 5666 | 5788 | <p>For instance, the expression <code>debug.getinfo(1,"n").name</code> returns |
| 5667 | | −the name of the current function, if a reasonable name can be found, |
| 5789 | +a name of the current function, if a reasonable name can be found, |
| 5668 | 5790 | and <code>debug.getinfo(print)</code> returns a table with all available information |
| 5669 | 5791 | about the <a href="#pdf-print"><code>print</code></a> function. |
| 5670 | 5792 | |
| 5671 | | −<p><a name="pdf-debug.getlocal"></a><hr/><h3><code>debug.getlocal (level, local)</code></h3> |
| 5793 | +<p><a name="pdf-debug.getlocal"></a><hr /><h3><code>debug.getlocal (level, local)</code></h3> |
| 5672 | 5794 | |
| 5673 | 5795 | <p>This function returns the name and the value of the local variable |
| 5674 | 5796 | with index <code>local</code> of the function at level <code>level</code> of the stack. |
| @@ -5683,26 +5805,26 @@ and raises an error when called with a <code>level</code> out of range. · 8 unmodified lines |
| 5683 | 5805 | represent internal variables |
| 5684 | 5806 | (loop control variables, temporaries, and C function locals). |
| 5685 | 5807 | |
| 5686 | | −<p><a name="pdf-debug.getmetatable"></a><hr/><h3><code>debug.getmetatable (object)</code></h3> |
| 5808 | +<p><a name="pdf-debug.getmetatable"></a><hr /><h3><code>debug.getmetatable (object)</code></h3> |
| 5687 | 5809 | |
| 5688 | | −<p>If <code>object</code> does not have a metatable, returns <b>nil</b>. |
| 5689 | | −Otherwise, returns the metatable of the given object. |
| 5810 | +<p>Returns the metatable of the given <code>object</code> |
| 5811 | +or <b>nil</b> if it does not have a metatable. |
| 5690 | 5812 | |
| 5691 | | −<p><a name="pdf-debug.getregistry"></a><hr/><h3><code>debug.getregistry ()</code></h3> |
| 5813 | +<p><a name="pdf-debug.getregistry"></a><hr /><h3><code>debug.getregistry ()</code></h3> |
| 5692 | 5814 | |
| 5693 | 5815 | <p>Returns the registry table (see <a href="#registry">3.5</a>). |
| 5694 | 5816 | |
| 5695 | | −<p><a name="pdf-debug.getupvalue"></a><hr/><h3><code>debug.getupvalue (func, up)</code></h3> |
| 5817 | +<p><a name="pdf-debug.getupvalue"></a><hr /><h3><code>debug.getupvalue (func, up)</code></h3> |
| 5696 | 5818 | |
| 5697 | 5819 | <p>This function returns the name and the value of the upvalue |
| 5698 | 5820 | with index <code>up</code> of the function <code>func</code>. |
| 5699 | 5821 | The function returns <b>nil</b> if there is no upvalue with the given index. |
| 5700 | 5822 | |
| 5701 | | −<p><a name="pdf-debug.setfenv"></a><hr/><h3><code>debug.setfenv (o, table)</code></h3> |
| 5823 | +<p><a name="pdf-debug.setfenv"></a><hr /><h3><code>debug.setfenv (object, table)</code></h3> |
| 5702 | 5824 | |
| 5703 | | −<p>Sets the environment of the given object. |
| 5825 | +<p>Sets the environment of the given <code>object</code> to the given <code>table</code>. |
| 5704 | 5826 | |
| 5705 | | −<p><a name="pdf-debug.sethook"></a><hr/><h3><code>debug.sethook (hook, mask [, count])</code></h3> |
| 5827 | +<p><a name="pdf-debug.sethook"></a><hr /><h3><code>debug.sethook (hook, mask [, count])</code></h3> |
| 5706 | 5828 | |
| 5707 | 5829 | <p>Sets the given function as a hook. |
| 5708 | 5830 | The string <code>mask</code> and the number <code>count</code> describe |
| @@ -5710,22 +5832,22 @@ when the hook will be called. · 1 unmodified line |
| 5710 | 5832 | The string mask may have the following characters, |
| 5711 | 5833 | with the given meaning: |
| 5712 | 5834 | <ul> |
| 5713 | | −<li><b><code>"c"</code></b> The hook is called every time Lua calls a function; |
| 5714 | | −<li><b><code>"r"</code></b> The hook is called every time Lua returns from a function; |
| 5715 | | −<li><b><code>"l"</code></b> The hook is called every time Lua enters a new line of code. |
| 5835 | +<li><b><code>"c"</code></b> --- The hook is called every time Lua calls a function; |
| 5836 | +<li><b><code>"r"</code></b> --- The hook is called every time Lua returns from a function; |
| 5837 | +<li><b><code>"l"</code></b> --- The hook is called every time Lua enters a new line of code. |
| 5716 | 5838 | </ul> |
| 5717 | 5839 | With a <code>count</code> different from zero, |
| 5718 | 5840 | the hook is called after every <code>count</code> instructions. |
| 5719 | 5841 | |
| 5720 | 5842 | <p>When called without arguments, |
| 5721 | | −the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function turns off the hook. |
| 5843 | +<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. |
| 5722 | 5844 | |
| 5723 | | −<p>When the hook is called, its first parameter is always a string |
| 5724 | | −describing the event that triggered its call: |
| 5845 | +<p>When the hook is called, its first parameter is a string |
| 5846 | +describing the event that has triggered its call: |
| 5725 | 5847 | <code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>), |
| 5726 | 5848 | <code>"line"</code>, and <code>"count"</code>. |
| 5727 | | −Moreover, for line events, |
| 5728 | | −it also gets as its second parameter the new line number. |
| 5849 | +For line events, |
| 5850 | +the hook also gets the new line number as its second parameter. |
| 5729 | 5851 | Inside a hook, |
| 5730 | 5852 | you can call <code>getinfo</code> with level 2 to get more information about |
| 5731 | 5853 | the running function |
| @@ -5735,7 +5857,7 @@ unless the event is <code>"tail return"</code>. · 3 unmodified lines |
| 5735 | 5857 | In this case, Lua is only simulating the return, |
| 5736 | 5858 | and a call to <code>getinfo</code> will return invalid data. |
| 5737 | 5859 | |
| 5738 | | −<p><a name="pdf-debug.setlocal"></a><hr/><h3><code>debug.setlocal (level, local, value)</code></h3> |
| 5860 | +<p><a name="pdf-debug.setlocal"></a><hr /><h3><code>debug.setlocal (level, local, value)</code></h3> |
| 5739 | 5861 | |
| 5740 | 5862 | <p>This function assigns the value <code>value</code> to the local variable |
| 5741 | 5863 | with index <code>local</code> of the function at level <code>level</code> of the stack. |
| @@ -5745,11 +5867,12 @@ and raises an error when called with a <code>level</code> out of range. · 3 unmodified lines |
| 5745 | 5867 | (You can call <code>getinfo</code> to check whether the level is valid.) |
| 5746 | 5868 | Otherwise, it returns the name of the local variable. |
| 5747 | 5869 | |
| 5748 | | −<p><a name="pdf-debug.setmetatable"></a><hr/><h3><code>debug.setmetatable (o, metatable)</code></h3> |
| 5870 | +<p><a name="pdf-debug.setmetatable"></a><hr /><h3><code>debug.setmetatable (object, table)</code></h3> |
| 5749 | 5871 | |
| 5750 | | −<p>Sets the metatable for the given object. |
| 5872 | +<p>Sets the metatable for the given <code>object</code> to the given id@{table} |
| 5873 | +(which can be <b>nil</b>). |
| 5751 | 5874 | |
| 5752 | | −<p><a name="pdf-debug.setupvalue"></a><hr/><h3><code>debug.setupvalue (func, up, value)</code></h3> |
| 5875 | +<p><a name="pdf-debug.setupvalue"></a><hr /><h3><code>debug.setupvalue (func, up, value)</code></h3> |
| 5753 | 5876 | |
| 5754 | 5877 | <p>This function assigns the value <code>value</code> to the upvalue |
| 5755 | 5878 | with index <code>up</code> of the function <code>func</code>. |
| @@ -5757,7 +5880,7 @@ The function returns <b>nil</b> if there is no upvalue · 1 unmodified line |
| 5757 | 5880 | with the given index. |
| 5758 | 5881 | Otherwise, it returns the name of the upvalue. |
| 5759 | 5882 | |
| 5760 | | −<p><a name="pdf-debug.traceback"></a><hr/><h3><code>debug.traceback ([message])</code></h3> |
| 5883 | +<p><a name="pdf-debug.traceback"></a><hr /><h3><code>debug.traceback ([message])</code></h3> |
| 5761 | 5884 | |
| 5762 | 5885 | <p>Returns a string with a traceback of the call stack. |
| 5763 | 5886 | An optional <code>message</code> string is appended |
| @@ -5775,7 +5898,7 @@ An interpreter for Lua as a stand-alone language, · 11 unmodified lines |
| 5775 | 5898 | called simply <code>lua</code>, |
| 5776 | 5899 | is provided with the standard distribution. |
| 5777 | 5900 | The stand-alone interpreter includes |
| 5778 | | −all standard libraries plus the reflexive debug interface. |
| 5901 | +all standard libraries, including the debug library. |
| 5779 | 5902 | Its usage is: |
| 5780 | 5903 | <pre> |
| 5781 | 5904 | lua [options] [script [args]] |
| @@ -5790,30 +5913,31 @@ The options are: · 8 unmodified lines |
| 5790 | 5913 | <li><b><code>-</code> </b> executes <code>stdin</code> as a file and stops handling options. |
| 5791 | 5914 | </ul> |
| 5792 | 5915 | After handling its options, <code>lua</code> runs the given <em>script</em>, |
| 5793 | | −passing to it the given <em>args</em>. |
| 5916 | +passing to it the given <em>args</em> as string arguments. |
| 5794 | 5917 | When called without arguments, |
| 5795 | | −<code>lua</code> behaves as <code>lua -v -i</code> when <code>stdin</code> is a terminal, |
| 5918 | +<code>lua</code> behaves as <code>lua -v -i</code> |
| 5919 | +when the standard input (<code>stdin</code>) is a terminal, |
| 5796 | 5920 | and as <code>lua -</code> otherwise. |
| 5797 | 5921 | |
| 5798 | 5922 | <p>Before running any argument, |
| 5799 | 5923 | the interpreter checks for an environment variable <code>LUA_INIT</code>. |
| 5800 | 5924 | If its format is @<em>filename</em>, |
| 5801 | | −then lua executes the file. |
| 5802 | | −Otherwise, lua executes the string itself. |
| 5925 | +then <code>lua</code> executes the file. |
| 5926 | +Otherwise, <code>lua</code> executes the string itself. |
| 5803 | 5927 | |
| 5804 | 5928 | <p>All options are handled in order, except <code>-i</code>. |
| 5805 | 5929 | For instance, an invocation like |
| 5806 | 5930 | <pre> |
| 5807 | 5931 | $ lua -e'a=1' -e 'print(a)' script.lua |
| 5808 | 5932 | </pre> |
| 5809 | | −will first set <code>a</code> to 1, then print <code>a</code>, |
| 5810 | | −and finally run the file <code>script.lua</code>. |
| 5933 | +will first set <code>a</code> to 1, then print the value of <code>a</code> (which is `<code>1</code>´), |
| 5934 | +and finally run the file <code>script.lua</code> with no arguments. |
| 5811 | 5935 | (Here <code>$</code> is the shell prompt. Your prompt may be different.) |
| 5812 | 5936 | |
| 5813 | 5937 | <p>Before starting to run the script, |
| 5814 | 5938 | <code>lua</code> collects all arguments in the command line |
| 5815 | 5939 | in a global table called <code>arg</code>. |
| 5816 | | −The script name is stored in index 0, |
| 5940 | +The script name is stored at index 0, |
| 5817 | 5941 | the first argument after the script name goes to index 1, |
| 5818 | 5942 | and so on. |
| 5819 | 5943 | Any arguments before the script name |
| @@ -5821,34 +5945,40 @@ Any arguments before the script name · 1 unmodified line |
| 5821 | 5945 | go to negative indices. |
| 5822 | 5946 | For instance, in the call |
| 5823 | 5947 | <pre> |
| 5824 | | − $ lua -la.lua b.lua t1 t2 |
| 5948 | + $ lua -la b.lua t1 t2 |
| 5825 | 5949 | </pre> |
| 5826 | 5950 | the interpreter first runs the file <code>a.lua</code>, |
| 5827 | 5951 | then creates a table |
| 5828 | 5952 | <pre> |
| 5829 | | − arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", |
| 5953 | + arg = { [-2] = "lua", [-1] = "-la", |
| 5954 | + [0] = "b.lua", |
| 5830 | 5955 | [1] = "t1", [2] = "t2" } |
| 5831 | 5956 | </pre> |
| 5832 | 5957 | and finally runs the file <code>b.lua</code>. |
| 5833 | 5958 | The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... |
| 5834 | 5959 | as arguments; |
| 5835 | | −it can access those arguments with the vararg expression <code>...</code>. |
| 5960 | +it can also access those arguments with the vararg expression `<code>...</code>´. |
| 5836 | 5961 | |
| 5837 | 5962 | <p>In interactive mode, |
| 5838 | 5963 | if you write an incomplete statement, |
| 5839 | | −the interpreter waits for its completion. |
| 5964 | +the interpreter waits for its completion |
| 5965 | +by issuing a different prompt. |
| 5840 | 5966 | |
| 5841 | | −<p>If the global variable <code>_PROMPT</code> is defined as a string, |
| 5967 | +<p>If the global variable <code>_PROMPT</code> contains a string, |
| 5842 | 5968 | then its value is used as the prompt. |
| 5843 | | −Therefore, the prompt can be changed directly on the command line: |
| 5969 | +Similarly, if the global variable <code>_PROMPT2</code> contains a string, |
| 5970 | +it its value is used as the secondary prompt |
| 5971 | +(issued during incomplete statements). |
| 5972 | +Therefore, both prompts can be changed directly on the command line. |
| 5973 | +For instance, |
| 5844 | 5974 | <pre> |
| 5845 | 5975 | $ lua -e"_PROMPT='myprompt> '" -i |
| 5846 | 5976 | </pre> |
| 5847 | 5977 | (the outer pair of quotes is for the shell, |
| 5848 | | −the inner is for Lua), |
| 5978 | +the inner pair is for Lua), |
| 5849 | 5979 | or in any Lua programs by assigning to <code>_PROMPT</code>. |
| 5850 | 5980 | Note the use of <code>-i</code> to enter interactive mode; otherwise, |
| 5851 | | −the program would end just after the assignment to <code>_PROMPT</code>. |
| 5981 | +the program would just end silently right after the assignment to <code>_PROMPT</code>. |
| 5852 | 5982 | |
| 5853 | 5983 | <p>To allow the use of Lua as a |
| 5854 | 5984 | script interpreter in Unix systems, |
| @@ -5869,17 +5999,17 @@ then · 14 unmodified lines |
| 5869 | 5999 | </pre> |
| 5870 | 6000 | is a more portable solution.) |
| 5871 | 6001 | |
| 5872 | | −<p><hr/> |
| 6002 | +<p><hr /> |
| 5873 | 6003 | |
| 5874 | | −<p><h1>Incompatibilities with Previous Version</h1> |
| 6004 | +<p><h1>Incompatibilities with the Previous Version</h1> |
| 5875 | 6005 | |
| 5876 | 6006 | |
| 5877 | | −<p>Here we list the incompatibilities when moving a program |
| 6007 | +<p>Here we list the incompatibilities that may be found when moving a program |
| 5878 | 6008 | from Lua 5.0 to Lua 5.1. |
| 5879 | 6009 | You can avoid most of the incompatibilities compiling Lua with |
| 5880 | | −appropriate options. |
| 6010 | +appropriate options (see file <code>luaconf.h</code>). |
| 5881 | 6011 | However, |
| 5882 | | −all those compatibility options will be removed in the next version. |
| 6012 | +all those compatibility options will be removed in the next version of Lua. |
| 5883 | 6013 | |
| 5884 | 6014 | <p><h2>Incompatibilities with version 5.0</h2> |
| 5885 | 6015 | |
| @@ -5888,25 +6018,21 @@ all those compatibility options will be removed in the next version. · 2 unmodified lines |
| 5888 | 6018 | <li> |
| 5889 | 6019 | The vararg system changed from the pseudo-argument <code>arg</code> with a |
| 5890 | 6020 | table with the extra arguments to the vararg expression. |
| 5891 | | −(Option <code>LUA_COMPAT_VARARG</code>) |
| 6021 | +(Option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) |
| 5892 | 6022 | |
| 5893 | 6023 | <p><li> |
| 5894 | 6024 | There was a subtle change in the scope of the implicit |
| 5895 | | −variables of the <b>for</b> constructor. |
| 6025 | +variables of the <b>for</b> statement and for the <b>repeat</b> statement. |
| 5896 | 6026 | |
| 5897 | 6027 | <p><li> |
| 5898 | 6028 | The long string/long comment syntax (<code>[[...]]</code>) does not allow nesting. |
| 5899 | 6029 | You can use the new syntax (<code>[=[...]=]</code>) in those cases. |
| 5900 | | −(Option <code>LUA_COMPAT_LSTR</code>) |
| 6030 | +(Option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) |
| 5901 | 6031 | |
| 5902 | 6032 | <p></ul> |
| 5903 | 6033 | |
| 5904 | 6034 | <p><h3>Changes in the Libraries</h3> |
| 5905 | 6035 | <ul> |
| 5906 | | −<li> |
| 5907 | | −Function <a href="#pdf-string.find"><code>string.find</code></a> does not return its captures. |
| 5908 | | −Use <a href="#pdf-string.match"><code>string.match</code></a> for that. |
| 5909 | | −(Option <code>LUA_COMPAT_FIND</code>) |
| 5910 | 6036 | |
| 5911 | 6037 | <p><li> |
| 5912 | 6038 | Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. |
| @@ -5935,10 +6061,10 @@ Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.f · 22 unmodified lines |
| 5935 | 6061 | (Option <code>LUA_COMPAT_MOD</code>) |
| 5936 | 6062 | |
| 5937 | 6063 | <p><li> |
| 5938 | | −There was substantial changes in function <a href="#pdf-require"><code>require</code></a> due to |
| 6064 | +There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to |
| 5939 | 6065 | the new module system. |
| 5940 | 6066 | However, the new behavior is mostly compatible with the old, |
| 5941 | | −but it gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead |
| 6067 | +but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead |
| 5942 | 6068 | of from <code>LUA_PATH</code>. |
| 5943 | 6069 | |
| 5944 | 6070 | <p><li> |
| @@ -5952,7 +6078,7 @@ use <code>collectgarbage("count")</code> instead. · 7 unmodified lines |
| 5952 | 6078 | <ul> |
| 5953 | 6079 | <li> |
| 5954 | 6080 | Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to |
| 5955 | | −allow the user to set an allocation function. |
| 6081 | +allow the user to set a memory allocation function. |
| 5956 | 6082 | You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to |
| 5957 | 6083 | create a state with a standard allocation function |
| 5958 | 6084 | (based on <code>realloc</code>). |
| @@ -5973,6 +6099,11 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 14 unmodified lines |
| 5973 | 6099 | <a name="BNF"></a><h1>The Complete Syntax of Lua</h1> |
| 5974 | 6100 | |
| 5975 | 6101 | |
| 6102 | +<p>Here is the complete syntax of Lua in extended BNF. |
| 6103 | +It does not describe operator priorities nor some syntactical restrictions, |
| 6104 | +such as <b>return</b> and <b>break</b> statements |
| 6105 | +can only appear as the <em>last</em> statement of a block. |
| 6106 | + |
| 5976 | 6107 | <p> |
| 5977 | 6108 | |
| 5978 | 6109 | <p><pre> |
| @@ -5991,7 +6122,7 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 12 unmodified lines |
| 5991 | 6122 | <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> | |
| 5992 | 6123 | <b>function</b> funcname funcbody | |
| 5993 | 6124 | <b>local</b> <b>function</b> Name funcbody | |
| 5994 | | − <b>local</b> namelist [init] |
| 6125 | + <b>local</b> namelist [`<b>=</b>´ explist1] |
| 5995 | 6126 | |
| 5996 | 6127 | laststat ::= <b>return</b> [explist1] | <b>break</b> |
| 5997 | 6128 | |
| @@ -6003,18 +6134,16 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 5 unmodified lines |
| 6003 | 6134 | |
| 6004 | 6135 | namelist ::= Name {`<b>,</b>´ Name} |
| 6005 | 6136 | |
| 6006 | | − init ::= `<b>=</b>´ explist1 |
| 6007 | | − |
| 6008 | 6137 | explist1 ::= {exp `<b>,</b>´} exp |
| 6009 | 6138 | |
| 6010 | | − exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | Literal | `<b>...</b>´ | |
| 6139 | + exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | |
| 6011 | 6140 | function | prefixexp | tableconstructor | exp binop exp | unop exp |
| 6012 | 6141 | |
| 6013 | 6142 | prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ |
| 6014 | 6143 | |
| 6015 | 6144 | functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args |
| 6016 | 6145 | |
| 6017 | | − args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | tableconstructor | Literal |
| 6146 | + args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | tableconstructor | String |
| 6018 | 6147 | |
| 6019 | 6148 | function ::= <b>function</b> funcbody |
| 6020 | 6149 | |
| @@ -6026,7 +6155,7 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 5 unmodified lines |
| 6026 | 6155 | |
| 6027 | 6156 | fieldlist ::= field {fieldsep field} [fieldsep] |
| 6028 | 6157 | |
| 6029 | | − field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | name `<b>=</b>´ exp | exp |
| 6158 | + field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp |
| 6030 | 6159 | |
| 6031 | 6160 | fieldsep ::= `<b>,</b>´ | `<b>;</b>´ |
| 6032 | 6161 | |
| @@ -6042,10 +6171,5 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 9 unmodified lines |
| 6042 | 6171 | |
| 6043 | 6172 | <p> |
| 6044 | 6173 | |
| 6045 | | −<HR> |
| 6046 | | −<SMALL> |
| 6047 | | −Last update: |
| 6048 | | −Tue Nov 1 15:20:21 BRST 2005 |
| 6049 | | −</SMALL> |
| 6050 | | − |
| 6051 | 6174 | </body></html> |
| 6175 | + |