| @@ -8,9 +8,9 @@ · 7 unmodified lines |
| 8 | | 8 | |
| 9 | <body bgcolor="#FFFFFF"> | 9 | <body bgcolor="#FFFFFF"> |
| 10 | | 10 | |
| 11 | <hr/> | 11 | <hr /> |
| 12 | <h1> | 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 | Lua 5.1 Reference Manual | 14 | Lua 5.1 Reference Manual |
| 15 | </h1> | 15 | </h1> |
| 16 | | 16 | |
| @@ -18,16 +18,15 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes · 1 unmodified line |
| 18 | <p> | 18 | <p> |
| 19 | <small> | 19 | <small> |
| 20 | <a href="http://www.lua.org/copyright.html">Copyright</a> | 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 | </small> | 22 | </small> |
| 23 | <hr/> | 23 | <hr /> |
| 24 | | 24 | |
| 25 | <p> | 25 | <p> |
| 26 | <p> | 26 | <p> |
| 27 | <!-- ====================================================================== --> | 27 | <!-- ====================================================================== --> |
| 28 | | 28 | |
| 29 | | 29 | |
| 30 | | | |
| 31 | <a name="1"></a><h1>1 - Introduction</h1> | 30 | <a name="1"></a><h1>1 - Introduction</h1> |
| 32 | | 31 | |
| 33 | <p>Lua is an extension programming language designed to support | 32 | <p>Lua is an extension programming language designed to support |
| @@ -36,7 +35,7 @@ facilities. · 2 unmodified lines |
| 36 | It also offers good support for object-oriented programming, | 35 | It also offers good support for object-oriented programming, |
| 37 | functional programming, and data-driven programming. | 36 | functional programming, and data-driven programming. |
| 38 | Lua is intended to be used as a powerful, light-weight | 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 | Lua is implemented as a library, written in <em>clean</em> C | 39 | Lua is implemented as a library, written in <em>clean</em> C |
| 41 | (that is, in the common subset of ANSI C and C++). | 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 | Through the use of C functions, Lua can be augmented to cope with | 48 | Through the use of C functions, Lua can be augmented to cope with |
| 50 | a wide range of different domains, | 49 | a wide range of different domains, |
| 51 | thus creating customized programming languages sharing a syntactical framework. | 50 | thus creating customized programming languages sharing a syntactical framework. |
| 52 | | 51 | The Lua distribution includes a sample host program called <code>lua</code>, |
| 53 | <p>The Lua distribution includes a stand-alone embedding program, | 52 | which uses the Lua library to offer a complete, stand-alone Lua interpreter. |
| 54 | <code>lua</code>, that uses the Lua library to offer a complete Lua interpreter. | | |
| 55 | | 53 | |
| 56 | <p>Lua is free software, | 54 | <p>Lua is free software, |
| 57 | and is provided as usual with no guarantees, | 55 | and is provided as usual with no guarantees, |
| 58 | as stated in its copyright notice. | 56 | as stated in its license. |
| 59 | The implementation described in this manual is available | 57 | The implementation described in this manual is available |
| 60 | at Lua's official web site, <code>www.lua.org</code>. | 58 | at Lua's official web site, <code>www.lua.org</code>. |
| 61 | | 59 | |
| 62 | <p>Like any other reference manual, | 60 | <p>Like any other reference manual, |
| 63 | this document is dry in places. | 61 | this document is dry in places. |
| 64 | For a discussion of the decisions behind the design of Lua, | 62 | For a discussion of the decisions behind the design of Lua, |
| 65 | see the papers below, | 63 | see the technical papers available at Lua's web site. |
| 66 | which are available at Lua's web site. | 64 | For a detailed introduction to programming in Lua, |
| 67 | <ul> | 65 | see Roberto's book, <em>Programming in Lua</em>. |
| 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. | | |
| 88 | | 66 | |
| 89 | <p> | 67 | <p> |
| 90 | <a name="language"></a><a name="2"></a><h1>2 - The Language</h1> | 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 | how they can be combined, | 74 | how they can be combined, |
| 97 | and what their combinations mean. | 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 | in which | 78 | in which |
| 101 | {<em>a</em>} means 0 or more <em>a</em>'s, and | 79 | {<em>a</em>} means 0 or more <em>a</em>'s, and |
| 102 | [<em>a</em>] means an optional <em>a</em>. | 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 | keywords are shown in <b>bold</b>, | 82 | keywords are shown in <b>bold</b>, |
| 105 | and other terminal symbols are shown in <code>typewriter</code> font, | 83 | and other terminal symbols are shown in <code>typewriter</code> font, |
| 106 | enclosed in single quotes. | 84 | enclosed in single quotes. |
| | 85 | The complete syntax of Lua can be found at the end of this manual. |
| 107 | | 86 | |
| 108 | <p><a name="lexical"></a><a name="2.1"></a><h2>2.1 - Lexical Conventions</h2> | 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 | digits, and underscores, | 92 | digits, and underscores, |
| 112 | not beginning with a digit. | 93 | not beginning with a digit. |
| 113 | This coincides with the definition of names in most languages. | 94 | This coincides with the definition of names in most languages. |
| 114 | (The definition of letter depends on the current locale: | 95 | (The definition of letter depends on the current locale: |
| 115 | any character considered alphabetic by the current locale | 96 | any character considered alphabetic by the current locale |
| 116 | can be used in an identifier.) | 97 | can be used in an identifier.) |
| | 98 | Identifiers are used to name variables and table fields. |
| 117 | | 99 | |
| 118 | <p>The following <em>keywords</em> are reserved | 100 | <p>The following <em>keywords</em> are reserved |
| 119 | and cannot be used as names: | 101 | and cannot be used as names: |
| @@ -130,7 +112,7 @@ and cannot be used as names: · 10 unmodified lines |
| 130 | are two different, valid names. | 112 | are two different, valid names. |
| 131 | As a convention, names starting with an underscore followed by | 113 | As a convention, names starting with an underscore followed by |
| 132 | uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) | 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 | <p>The following strings denote other tokens: | 117 | <p>The following strings denote other tokens: |
| 136 | <pre> | 118 | <pre> |
| @@ -152,8 +134,8 @@ and can contain the following C-like escape sequences: · 15 unmodified lines |
| 152 | <li><b><code>\t</code></b> --- horizontal tab | 134 | <li><b><code>\t</code></b> --- horizontal tab |
| 153 | <li><b><code>\v</code></b> --- vertical tab | 135 | <li><b><code>\v</code></b> --- vertical tab |
| 154 | <li><b><code>\\</code></b> --- backslash | 136 | <li><b><code>\\</code></b> --- backslash |
| 155 | <li><b><code>\"</code></b> --- quotation mark | 137 | <li><b><code>\"</code></b> --- quotation mark (double quote) |
| 156 | <li><b><code>\'</code></b> --- apostrophe | 138 | <li><b><code>\'</code></b> --- apostrophe (single quote) |
| 157 | </ul> | 139 | </ul> |
| 158 | Moreover, a `<code>\</code><em>newline</em>´ | 140 | Moreover, a `<code>\</code><em>newline</em>´ |
| 159 | (that is, a backslash followed by a real newline) | 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 | A character in a string may also be specified by its numerical value | 143 | A character in a string may also be specified by its numerical value |
| 162 | using the escape sequence `<code>\</code><em>ddd</em>´, | 144 | using the escape sequence `<code>\</code><em>ddd</em>´, |
| 163 | where <em>ddd</em> is a sequence of up to three decimal digits. | 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 | Strings in Lua may contain any 8-bit value, including embedded zeros, | 148 | Strings in Lua may contain any 8-bit value, including embedded zeros, |
| 165 | which can be specified as `<code>\0</code>´. | 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 | <p>Literal strings can also be defined using a long format | 159 | <p>Literal strings can also be defined using a long format |
| 168 | enclosed by <em>l-brackets</em> (long brackets). | 160 | enclosed by <em>long brackets</em>. |
| 169 | We define an <em>opening l-bracket of level <em>n</em></em> as an opening | 161 | We define an <em>opening long bracket of level <em>n</em></em> as an opening |
| 170 | square bracket followed by <em>n</em> equal signs followed by another | 162 | square bracket followed by <em>n</em> equal signs followed by another |
| 171 | opening square bracket. | 163 | opening square bracket. |
| 172 | So, an opening l-bracket of level 0 is written as <code>[[</code>, | 164 | So, an opening long bracket of level 0 is written as <code>[[</code>, |
| 173 | an opening l-bracket of level 1 is written as <code>[=[</code>, | 165 | an opening long bracket of level 1 is written as <code>[=[</code>, |
| 174 | and so on. | 166 | and so on. |
| 175 | A <em>closing l-bracket</em> is defined similarly; | 167 | A <em>closing long bracket</em> is defined similarly; |
| 176 | for instance, a closing l-bracket of level 4 is written as <code>]====]</code>. | 168 | for instance, a closing long bracket of level 4 is written as <code>]====]</code>. |
| 177 | A long string starts with an opening l-bracket of any level and | 169 | A long string starts with an opening long bracket of any level and |
| 178 | ends at the first closing l-bracket of the same level. | 170 | ends at the first closing long bracket of the same level. |
| 179 | Literals in this bracketed form may run for several lines, | 171 | Literals in this bracketed form may run for several lines, |
| 180 | do not interpret any escape sequences, | 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 | <p>For convenience, | 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 | the newline is not included in the string. | 179 | the newline is not included in the string. |
| 186 | As an example, in a system using ASCII | 180 | As an example, in a system using ASCII |
| 187 | (in which `<code>a</code>´ is coded as 97, | 181 | (in which `<code>a</code>´ is coded as 97, |
| 188 | newline is coded as 10, and `<code>1</code>´ is coded as 49), | 182 | newline is coded as 10, and `<code>1</code>´ is coded as 49), |
| 189 | the four literals below denote the same string: | 183 | the four literals below denote the same string: |
| 190 | <pre> | 184 | <pre> |
| 191 | (1) "alo\n123\"" | 185 | (1) 'alo\n123"' |
| 192 | (2) '\97lo\10\04923"' | 186 | (2) "alo\n123\"" |
| 193 | (3) [[alo | 187 | (3) '\97lo\10\04923"' |
| | 188 | (4) [[alo |
| 194 | 123"]] | 189 | 123"]] |
| 195 | (4) [==[ | 190 | (5) [==[ |
| 196 | alo | 191 | alo |
| 197 | 123"]==] | 192 | 123"]==] |
| 198 | </pre> | 193 | </pre> |
| @@ -204,13 +199,14 @@ Examples of valid numerical constants are · 5 unmodified lines |
| 204 | 3 3.0 3.1416 314.16e-2 0.31416E1 | 199 | 3 3.0 3.1416 314.16e-2 0.31416E1 |
| 205 | </pre> | 200 | </pre> |
| 206 | | 201 | |
| 207 | <p><em>Comments</em> start anywhere outside a string with a | 202 | <p><em>Comments</em> start with a double hyphen (<code>--</code>) |
| 208 | double hyphen (<code>--</code>). | 203 | anywhere outside a string. |
| 209 | If the text immediately after <code>--</code> is not an opening l-bracket, | 204 | If the text immediately after <code>--</code> is not an opening long bracket, |
| 210 | the comment is a <em>short comment</em>, | 205 | the comment is a <em>short comment</em>, |
| 211 | which runs until the end of the line. | 206 | which runs until the end of the line. |
| 212 | Otherwise, it is a <em>long comment</em>, | 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 | <p><a name="TypesSec"></a><a name="2.2"></a><h2>2.2 - Values and Types</h2> | 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 | There are no type definitions in the language. | 216 | There are no type definitions in the language. |
| 221 | All values carry their own type. | 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 | <p>There are eight basic types in Lua: | 223 | <p>There are eight basic types in Lua: |
| 224 | <em>nil</em>, <em>boolean</em>, <em>number</em>, | 224 | <em>nil</em>, <em>boolean</em>, <em>number</em>, |
| 225 | <em>string</em>, <em>function</em>, <em>userdata</em>, | 225 | <em>string</em>, <em>function</em>, <em>userdata</em>, |
| 226 | <em>thread</em>, and <em>table</em>. | 226 | <em>thread</em>, and <em>table</em>. |
| 227 | <em>Nil</em> is the type of the value <b>nil</b>, | 227 | <em>Nil</em> is the type of the value <b>nil</b>, |
| 228 | whose main property is to be different from any other value; | 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 | <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. | 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 | any other value makes it true. | 232 | any other value makes it true. |
| 233 | <em>Number</em> represents real (double-precision floating-point) numbers. | 233 | <em>Number</em> represents real (double-precision floating-point) numbers. |
| 234 | (It is easy to build Lua interpreters that use other | 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 | Lua is 8-bit clean: | 240 | Lua is 8-bit clean: |
| 241 | Strings may contain any 8-bit character, | 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. | 244 | <p>Lua can call (and manipulate) functions written in Lua and |
| 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 | | |
| 248 | functions written in C | 245 | functions written in C |
| 249 | (see <a href="#functioncall">2.5.8</a>). | 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 | <p>The type <em>thread</em> represents independent threads of execution | 260 | <p>The type <em>thread</em> represents independent threads of execution |
| 264 | and it is used to implement coroutines (see <a href="#coroutine">2.11</a>). | 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 | <p>The type <em>table</em> implements associative arrays, | 266 | <p>The type <em>table</em> implements associative arrays, |
| 267 | that is, arrays that can be indexed not only with numbers, | 267 | that is, arrays that can be indexed not only with numbers, |
| 268 | but with any value (except <b>nil</b>). | 268 | but with any value (except <b>nil</b>). |
| 269 | Moreover, | 269 | Tables can be <em>heterogeneous</em>; |
| 270 | tables can be <em>heterogeneous</em>, | | |
| 271 | that is, they can contain values of all types (except <b>nil</b>). | 270 | that is, they can contain values of all types (except <b>nil</b>). |
| 272 | Tables are the sole data structuring mechanism in Lua; | 271 | Tables are the sole data structuring mechanism in Lua; |
| 273 | they may be used to represent ordinary arrays, | 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 | <p>Like indices, | 280 | <p>Like indices, |
| 282 | the value of a table field can be of any type (except <b>nil</b>). | 281 | the value of a table field can be of any type (except <b>nil</b>). |
| 283 | In particular, | 282 | In particular, |
| 284 | because functions are first class values, | 283 | because functions are first-class values, |
| 285 | table fields may contain functions. | 284 | table fields may contain functions. |
| 286 | Thus tables may also carry <em>methods</em> (see <a href="#func-def">2.5.9</a>). | 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 | variables do not actually <em>contain</em> these values, | 288 | variables do not actually <em>contain</em> these values, |
| 290 | only <em>references</em> to them. | 289 | only <em>references</em> to them. |
| 291 | Assignment, parameter passing, and function returns | 290 | Assignment, parameter passing, and function returns |
| @@ -300,7 +299,7 @@ of a given value. · 8 unmodified lines |
| 300 | <p>Lua provides automatic conversion between | 299 | <p>Lua provides automatic conversion between |
| 301 | string and number values at run time. | 300 | string and number values at run time. |
| 302 | Any arithmetic operation applied to a string tries to convert | 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 | Conversely, whenever a number is used where a string is expected, | 303 | Conversely, whenever a number is used where a string is expected, |
| 305 | the number is converted to a string, in a reasonable format. | 304 | the number is converted to a string, in a reasonable format. |
| 306 | For complete control of how numbers are converted to strings, | 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 | global variables, local variables, and table fields. | 314 | global variables, local variables, and table fields. |
| 316 | | 315 | |
| 317 | <p>A single name can denote a global variable or a local variable | 316 | <p>A single name can denote a global variable or a local variable |
| 318 | (or a formal parameter of a function, | 317 | (or a function formal parameter, |
| 319 | which is a particular form of local variable): | 318 | which is a particular kind of local variable): |
| 320 | <pre> | 319 | <pre> |
| 321 | var ::= Name | 320 | var ::= Name |
| 322 | </pre> | 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 | (see <a href="#localvar">2.4.7</a>). | 325 | (see <a href="#localvar">2.4.7</a>). |
| 325 | Local variables are <em>lexically scoped</em>: | 326 | Local variables are <em>lexically scoped</em>: |
| 326 | Local variables can be freely accessed by functions | 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 | </pre> | 335 | </pre> |
| 335 | The first expression (<em>prefixexp</em>) should result in a table value; | 336 | The first expression (<em>prefixexp</em>) should result in a table value; |
| 336 | the second expression (<em>exp</em>) | 337 | the second expression (<em>exp</em>) |
| 337 | identifies a specific entry inside that table. | 338 | identifies a specific entry in that table. |
| 338 | The expression denoting the table to be indexed has a restricted syntax; | 339 | The expression denoting the table to be indexed has a restricted syntax; |
| 339 | see <a href="#expressions">2.5</a> for details. | 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 | <p>The syntax <code>var.Name</code> is just syntactic sugar for |
| 342 | <code>var["NAME"]</code>: | 343 | <code>var["Name"]</code> and is used to denote table fields: |
| 343 | <pre> | 344 | <pre> |
| 344 | var ::= prefixexp `<b>.</b>´ Name | 345 | var ::= prefixexp `<b>.</b>´ Name |
| 345 | </pre> | 346 | </pre> |
| @@ -361,8 +362,10 @@ so that all global variables in that function · 15 unmodified lines |
| 361 | will refer to that environment table. | 362 | will refer to that environment table. |
| 362 | When a function is created, | 363 | When a function is created, |
| 363 | it inherits the environment from the function that created it. | 364 | it inherits the environment from the function that created it. |
| 364 | To replace or get the environment table of a Lua function, | 365 | To 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>. | 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 | (You can only manipulate the environment of C functions | 369 | (You can only manipulate the environment of C functions |
| 367 | through the debug library; (see <a href="#libdebug">5.9</a>).) | 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 | <p>Lua supports an almost conventional set of statements, | 387 | <p>Lua supports an almost conventional set of statements, |
| 385 | similar to those in Pascal or C. | 388 | similar to those in Pascal or C. |
| 386 | This set includes | 389 | This set includes |
| 387 | assignment, control structures, procedure calls, | 390 | assignment, control structures, function calls, |
| 388 | table constructors, and variable declarations. | 391 | table constructors, and variable declarations. |
| 389 | | 392 | |
| 390 | <p><a name="chunks"></a><a name="2.4.1"></a><h3>2.4.1 - Chunks</h3> | 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 | <pre> | 399 | <pre> |
| 397 | chunk ::= {stat [`<b>;</b>´]} | 400 | chunk ::= {stat [`<b>;</b>´]} |
| 398 | </pre> | 401 | </pre> |
| | 402 | There are no empty statements and thus `<code>;;</code>´ is not legal. |
| 399 | | 403 | |
| 400 | <p>Lua handles a chunk as the body of an anonymous function | 404 | <p>Lua handles a chunk as the body of an anonymous function |
| 401 | with a variable number of arguments | 405 | with a variable number of arguments |
| @@ -404,7 +408,7 @@ As such, chunks can define local variables, · 2 unmodified lines |
| 404 | receive arguments, and return values. | 408 | receive arguments, and return values. |
| 405 | | 409 | |
| 406 | <p>A chunk may be stored in a file or in a string inside the host program. | 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 | a virtual machine, | 412 | a virtual machine, |
| 409 | and then the compiled code is executed | 413 | and then the compiled code is executed |
| 410 | by an interpreter for the virtual machine. | 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 | <p><a name="2.4.2"></a><h3>2.4.2 - Blocks</h3> | 422 | <p><a name="2.4.2"></a><h3>2.4.2 - Blocks</h3> |
| 419 | A block is a list of statements; | 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 | <pre> | 425 | <pre> |
| 422 | block ::= chunk | 426 | block ::= chunk |
| 423 | </pre> | 427 | </pre> |
| @@ -455,7 +459,7 @@ the excess values are thrown away. · 31 unmodified lines |
| 455 | If there are fewer values than needed, | 459 | If there are fewer values than needed, |
| 456 | the list is extended with as many <b>nil</b>'s as needed. | 460 | the list is extended with as many <b>nil</b>'s as needed. |
| 457 | If the list of expressions ends with a function call, | 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 | before the adjustment | 463 | before the adjustment |
| 460 | (except when the call is enclosed in parentheses; see <a href="#expressions">2.5</a>). | 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 | </pre> | 513 | </pre> |
| 510 | Lua also has a <b>for</b> statement, in two flavors (see <a href="#for">2.4.5</a>). | 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 | control structure may return any value. | 517 | control structure may return any value. |
| 514 | Both <b>false</b> and <b>nil</b> are considered false. | 518 | Both <b>false</b> and <b>nil</b> are considered false. |
| 515 | All values different from <b>nil</b> and <b>false</b> are considered true | 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 | <p>In the <b>repeat</b>--<b>until</b> loop, | 522 | <p>In the <b>repeat</b>--<b>until</b> loop, |
| 519 | the inner block does not end at the <b>until</b> keyword, | 523 | the inner block does not end at the <b>until</b> keyword, |
| 520 | but only after the condition. | 524 | but only after the condition. |
| 521 | That means the condition can refer to local variables | 525 | So, the condition can refer to local variables |
| 522 | declared inside the loop. | 526 | declared inside the loop block. |
| 523 | | 527 | |
| 524 | <p>The <b>return</b> statement is used to return values | 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 | Functions and chunks may return more than one value, | 531 | Functions and chunks may return more than one value, |
| 528 | so the syntax for the <b>return</b> statement is | 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 | stat ::= <b>return</b> [explist1] | 534 | stat ::= <b>return</b> [explist1] |
| 531 | </pre> | 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 | <b>while</b>, <b>repeat</b>, or <b>for</b> loop, | 538 | <b>while</b>, <b>repeat</b>, or <b>for</b> loop, |
| 535 | skipping to the next statement after the loop: | 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 | </pre> | 543 | </pre> |
| 540 | A <b>break</b> ends the innermost enclosing loop. | 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 | statements can only be written as the <em>last</em> statement of a block. | 547 | statements can only be written as the <em>last</em> statement of a block. |
| 544 | If it is really necessary to <b>return</b> or <b>break</b> in the | 548 | If it is really necessary to <b>return</b> or <b>break</b> in the |
| 545 | middle of a block, | 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 | <p>The generic <b>for</b> statement works over functions, | 604 | <p>The generic <b>for</b> statement works over functions, |
| 601 | called <em>iterators</em>. | 605 | called <em>iterators</em>. |
| 602 | For each iteration, it calls its iterator function to produce a new value, | 606 | On each iteration, the iterator function is called to produce a new value, |
| 603 | stopping when the new value is <b>nil</b>. | 607 | stopping when this new value is <b>nil</b>. |
| 604 | The generic <b>for</b> loop has the following syntax: | 608 | The generic <b>for</b> loop has the following syntax: |
| 605 | <pre> | 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 | </pre> | 612 | </pre> |
| 608 | A <b>for</b> statement like | 613 | A <b>for</b> statement like |
| 609 | <pre> | 614 | <pre> |
| @@ -649,14 +654,13 @@ Local variables may be declared anywhere inside a block. · 39 unmodified lines |
| 649 | The declaration may include an initial assignment: | 654 | The declaration may include an initial assignment: |
| 650 | <pre> | 655 | <pre> |
| 651 | stat ::= <b>local</b> namelist [`<b>=</b>´ explist1] | 656 | stat ::= <b>local</b> namelist [`<b>=</b>´ explist1] |
| 652 | namelist ::= Name {`<b>,</b>´ Name} | | |
| 653 | </pre> | 657 | </pre> |
| 654 | If present, an initial assignment has the same semantics | 658 | If present, an initial assignment has the same semantics |
| 655 | of a multiple assignment (see <a href="#assignment">2.4.3</a>). | 659 | of a multiple assignment (see <a href="#assignment">2.4.3</a>). |
| 656 | Otherwise, all variables are initialized with <b>nil</b>. | 660 | Otherwise, all variables are initialized with <b>nil</b>. |
| 657 | | 661 | |
| 658 | <p>A chunk is also a block (see <a href="#chunks">2.4.1</a>), | 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 | The scope of such local variables extends until the end of the chunk. | 664 | The scope of such local variables extends until the end of the chunk. |
| 661 | | 665 | |
| 662 | <p>The visibility rules for local variables are explained in <a href="#visibility">2.6</a>. | 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 | exp ::= prefixexp | 673 | exp ::= prefixexp |
| 670 | exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | 674 | exp ::= <b>nil</b> | <b>false</b> | <b>true</b> |
| 671 | exp ::= Number | 675 | exp ::= Number |
| 672 | exp ::= Literal | 676 | exp ::= String |
| 673 | exp ::= function | 677 | exp ::= function |
| 674 | exp ::= tableconstructor | 678 | exp ::= tableconstructor |
| 675 | exp ::= `<b>...</b>´ | 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 | function calls are explained in <a href="#functioncall">2.5.8</a>; | 688 | function calls are explained in <a href="#functioncall">2.5.8</a>; |
| 685 | table constructors are explained in <a href="#tableconstructor">2.5.7</a>. | 689 | table constructors are explained in <a href="#tableconstructor">2.5.7</a>. |
| 686 | Vararg expressions, | 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 | vararg functions; | 692 | vararg functions; |
| 689 | they are explained in <a href="#func-def">2.5.9</a>. | 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 | Lua supports the usual arithmetic operators: | 742 | Lua supports the usual arithmetic operators: |
| 739 | the binary <code>+</code> (addition), | 743 | the binary <code>+</code> (addition), |
| 740 | <code>-</code> (subtraction), <code>*</code> (multiplication), | 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 | and unary <code>-</code> (negation). | 746 | and unary <code>-</code> (negation). |
| 743 | If the operands are numbers, or strings that can be converted to | 747 | If the operands are numbers, or strings that can be converted to |
| 744 | numbers (see <a href="#coercion">2.2.1</a>), | 748 | numbers (see <a href="#coercion">2.2.1</a>), |
| 745 | then all operations have the usual meaning. | 749 | then all operations have the usual meaning. |
| 746 | Exponentiation works for any exponent. | 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 | Modulus is defined as | 752 | Modulus is defined as |
| 749 | <pre> | 753 | <pre> |
| 750 | a % b == a - math.floor(a/b)*b | 754 | a % b == a - math.floor(a/b)*b |
| 751 | </pre> | 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 | the quotient towards minus infinity. | 757 | the quotient towards minus infinity. |
| 754 | | 758 | |
| 755 | <p><a name="rel-ops"></a><a name="2.5.2"></a><h3>2.5.2 - Relational Operators</h3> | 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 | Objects (tables, userdata, threads, and functions) | 770 | Objects (tables, userdata, threads, and functions) |
| 767 | are compared by <em>reference</em>: | 771 | are compared by <em>reference</em>: |
| 768 | Two objects are considered equal only if they are the <em>same</em> object. | 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 | this new object is different from any previously existing object. | 775 | this new object is different from any previously existing object. |
| 771 | | 776 | |
| 772 | <p>You can change the way that Lua compares tables and userdata | 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 | <p>The conversion rules of <a href="#coercion">2.2.1</a> | 780 | <p>The conversion rules of <a href="#coercion">2.2.1</a> |
| 776 | <em>do not</em> apply to equality comparisons. | 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 | and anything else as true. | 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>. | 807 | <p>The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. |
| 803 | | 808 | The conjunction operator <b>and</b> returns its first argument |
| 804 | <p>The conjunction operator <b>and</b> returns its first argument | | |
| 805 | if this value is <b>false</b> or <b>nil</b>; | 809 | if this value is <b>false</b> or <b>nil</b>; |
| 806 | otherwise, <b>and</b> returns its second argument. | 810 | otherwise, <b>and</b> returns its second argument. |
| 807 | The disjunction operator <b>or</b> returns its first argument | 811 | The disjunction operator <b>or</b> returns its first argument |
| 808 | if this value is different from <b>nil</b> and <b>false</b>; | 812 | if this value is different from <b>nil</b> and <b>false</b>; |
| 809 | otherwise, <b>or</b> returns its second argument. | 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 | that is, | 815 | that is, |
| 812 | the second operand is evaluated only if necessary. | 816 | the second operand is evaluated only if necessary. |
| 813 | For example, | 817 | Here are some examples: |
| 814 | <pre> | 818 | <pre> |
| 815 | 10 or error() -> 10 | 819 | 10 or 20 --> 10 |
| 816 | nil or "a" -> "a" | 820 | 10 or error() --> 10 |
| 817 | nil and 10 -> nil | 821 | nil or "a" --> "a" |
| 818 | false and error() -> false | 822 | nil and 10 --> nil |
| 819 | false and nil -> false | 823 | false and error() --> false |
| 820 | false or nil -> nil | 824 | false and nil --> false |
| 821 | 10 and 20 -> 20 | 825 | false or nil --> nil |
| | 826 | 10 and 20 --> 20 |
| 822 | </pre> | 827 | </pre> |
| | 828 | (Here and in the sequel, |
| | 829 | `<code>--></code>´ indicates the result of the preceding expression.) |
| 823 | | 830 | |
| 824 | <p><a name="concat"></a><a name="2.5.4"></a><h3>2.5.4 - Concatenation</h3> | 831 | <p><a name="concat"></a><a name="2.5.4"></a><h3>2.5.4 - Concatenation</h3> |
| 825 | The string concatenation operator in Lua is | 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 | <p><a name="len-op"></a><a name="2.5.5"></a><h3>2.5.5 - The Length Operator</h3> | 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 | The length of a string is its number of bytes | 841 | The length of a string is its number of bytes |
| 835 | (that is, the usual meaning of string length when each | 842 | (that is, the usual meaning of string length when each |
| 836 | character is one byte). | 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 | integer index <code>n</code> | 846 | integer index <code>n</code> |
| 839 | such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; | 847 | such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; |
| 840 | moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> may be zero. | 848 | moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> may be zero. |
| 841 | | 849 | For a regular array, with non-nil values from 1 to a given <code>n</code>, |
| 842 | <p>For a regular array, with non-nil values from 1 to a given <code>n</code>, | | |
| 843 | its length is exactly that <code>n</code>, | 850 | its length is exactly that <code>n</code>, |
| 844 | the index of its last value. | 851 | the index of its last value. |
| 845 | If the array has "holes" | 852 | If the array has "holes" |
| 846 | (that is, <b>nil</b> values between other non-nil values), | 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 | (that is, it may consider any such <b>nil</b> value as the end of | 856 | (that is, it may consider any such <b>nil</b> value as the end of |
| 849 | the array). | 857 | the array). |
| 850 | | 858 | |
| @@ -861,7 +869,8 @@ from lower to higher priority: · 10 unmodified lines |
| 861 | not # - (unary) | 869 | not # - (unary) |
| 862 | ^ | 870 | ^ |
| 863 | </pre> | 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 | The concatenation (`<code>..</code>´) and exponentiation (`<code>^</code>´) | 874 | The concatenation (`<code>..</code>´) and exponentiation (`<code>^</code>´) |
| 866 | operators are right associative. | 875 | operators are right associative. |
| 867 | All other binary operators are left associative. | 876 | All other binary operators are left associative. |
| @@ -889,20 +898,20 @@ starting with 1. · 21 unmodified lines |
| 889 | Fields in the other formats do not affect this counting. | 898 | Fields in the other formats do not affect this counting. |
| 890 | For example, | 899 | For example, |
| 891 | <pre> | 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 | </pre> | 902 | </pre> |
| 894 | is equivalent to | 903 | is equivalent to |
| 895 | <pre> | 904 | <pre> |
| 896 | do | 905 | do |
| 897 | local temp = {} | 906 | local t = {} |
| 898 | temp[f(1)] = g | 907 | t[f(1)] = g |
| 899 | temp[1] = "x" -- 1st exp | 908 | t[1] = "x" -- 1st exp |
| 900 | temp[2] = "y" -- 2nd exp | 909 | t[2] = "y" -- 2nd exp |
| 901 | temp.x = 1 -- temp["x"] = 1 | 910 | t.x = 1 -- t["x"] = 1 |
| 902 | temp[3] = f(x) -- 3rd exp | 911 | t[3] = f(x) -- 3rd exp |
| 903 | temp[30] = 23 | 912 | t[30] = 23 |
| 904 | temp[4] = 45 -- 4th exp | 913 | t[4] = 45 -- 4th exp |
| 905 | a = temp | 914 | a = t |
| 906 | end | 915 | end |
| 907 | </pre> | 916 | </pre> |
| 908 | | 917 | |
| @@ -927,7 +936,7 @@ first <em>prefixexp</em> and <em>args</em> are evaluated. · 18 unmodified lines |
| 927 | If the value of <em>prefixexp</em> has type <em>function</em>, | 936 | If the value of <em>prefixexp</em> has type <em>function</em>, |
| 928 | then that function is called | 937 | then that function is called |
| 929 | with the given arguments. | 938 | with the given arguments. |
| 930 | Otherwise, its "call" metamethod is called, | 939 | Otherwise, the <em>prefixexp</em> "call" metamethod is called, |
| 931 | having as first parameter the value of <em>prefixexp</em>, | 940 | having as first parameter the value of <em>prefixexp</em>, |
| 932 | followed by the original call arguments | 941 | followed by the original call arguments |
| 933 | (see <a href="#metatable">2.8</a>). | 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 | <pre> | 954 | <pre> |
| 946 | args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | 955 | args ::= `<b>(</b>´ [explist1] `<b>)</b>´ |
| 947 | args ::= tableconstructor | 956 | args ::= tableconstructor |
| 948 | args ::= Literal | 957 | args ::= String |
| 949 | </pre> | 958 | </pre> |
| 950 | All argument expressions are evaluated before the call. | 959 | All argument expressions are evaluated before the call. |
| 951 | A call of the form <code>f{...}</code> is syntactic sugar for | 960 | A call of the form <code>f{...}</code> is syntactic sugar for <code>f({...})</code>; |
| 952 | <code>f({...})</code>, that is, | 961 | that is, the argument list is a single new table. |
| 953 | the argument list is a single new table. | | |
| 954 | A call of the form <code>f'...'</code> | 962 | A call of the form <code>f'...'</code> |
| 955 | (or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for | 963 | (or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for <code>f('...')</code>; |
| 956 | <code>f('...')</code>, that is, | 964 | that is, the argument list is a single literal string. |
| 957 | the argument list is a single literal string. | | |
| 958 | | 965 | |
| 959 | <p>As an exception to the free-format syntax of Lua, | 966 | <p>As an exception to the free-format syntax of Lua, |
| 960 | you cannot put a line break before the `<code>(</code>´ in a function call. | 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 | a = f | 971 | a = f |
| 965 | (g).x(a) | 972 | (g).x(a) |
| 966 | </pre> | 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 | So, if you want two statements, you must add a semi-colon between them. | 975 | So, if you want two statements, you must add a semi-colon between them. |
| 969 | If you actually want to call <code>f</code>, | 976 | If you actually want to call <code>f</code>, |
| 970 | you must remove the line break before <code>(g)</code>. | 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 | calling function. | 988 | calling function. |
| 982 | Note that a tail call only happens with a particular syntax, | 989 | Note that a tail call only happens with a particular syntax, |
| 983 | where the <b>return</b> has one single function call as argument; | 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 | the returns of the called function. | 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 | <pre> | 994 | <pre> |
| 988 | return (f(x)) -- results adjusted to 1 | 995 | return (f(x)) -- results adjusted to 1 |
| 989 | return 2 * f(x) | 996 | return 2 * f(x) |
| 990 | return x, f(x) -- additional results | 997 | return x, f(x) -- additional results |
| 991 | f(x); return -- results discarded | 998 | f(x); return -- results discarded |
| 992 | return x or f(x) -- results adjusted to 1 | 999 | return x or f(x) -- results adjusted to 1 |
| 993 | </pre> | 1000 | </pre> |
| 994 | | 1001 | |
| 995 | <p><a name="func-def"></a><a name="2.5.9"></a><h3>2.5.9 - Function Definitions</h3> | 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 | <pre> | 1037 | <pre> |
| 1031 | local f; f = function () ... end | 1038 | local f; f = function () ... end |
| 1032 | </pre> | 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 | <p>A function definition is an executable expression, | 1047 | <p>A function definition is an executable expression, |
| 1035 | whose value has type <em>function</em>. | 1048 | whose value has type <em>function</em>. |
| @@ -1084,10 +1097,10 @@ to the vararg expression: · 48 unmodified lines |
| 1084 | f(r(), 10) a=1, b=10 | 1097 | f(r(), 10) a=1, b=10 |
| 1085 | f(r()) a=1, b=2 | 1098 | f(r()) a=1, b=2 |
| 1086 | | 1099 | |
| 1087 | g(3) a=3, b=nil, ... -> (nothing) | 1100 | g(3) a=3, b=nil, ... --> (nothing) |
| 1088 | g(3, 4) a=3, b=4, ... -> (nothing) | 1101 | g(3, 4) a=3, b=4, ... --> (nothing) |
| 1089 | g(3, 4, 5, 8) a=3, b=4, ... -> 5 8 | 1102 | g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 |
| 1090 | g(5, r()) a=5, b=1, ... -> 2 3 | 1103 | g(5, r()) a=5, b=1, ... --> 2 3 |
| 1091 | </pre> | 1104 | </pre> |
| 1092 | | 1105 | |
| 1093 | <p>Results are returned using the <b>return</b> statement (see <a href="#control">2.4.4</a>). | 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 | The scope of variables begins at the first statement <em>after</em> | 1127 | The scope of variables begins at the first statement <em>after</em> |
| 1115 | their declaration and lasts until the end of the innermost block that | 1128 | their declaration and lasts until the end of the innermost block that |
| 1116 | includes the declaration. | 1129 | includes the declaration. |
| 1117 | For instance: | 1130 | Consider the following example: |
| 1118 | <pre> | 1131 | <pre> |
| 1119 | x = 10 -- global variable | 1132 | x = 10 -- global variable |
| 1120 | do -- new block | 1133 | do -- new block |
| 1121 | local x = x -- new `x', with value 10 | 1134 | local x = x -- new `x', with value 10 |
| 1122 | print(x) --> 10 | 1135 | print(x) --> 10 |
| 1123 | x = x+1 | 1136 | x = x+1 |
| 1124 | do -- another block | 1137 | do -- another block |
| 1125 | local x = x+1 -- another `x' | 1138 | local x = x+1 -- another `x' |
| 1126 | print(x) --> 12 | 1139 | print(x) --> 12 |
| 1127 | end | 1140 | end |
| 1128 | print(x) --> 11 | 1141 | print(x) --> 11 |
| 1129 | end | 1142 | end |
| 1130 | print(x) --> 10 (the global one) | 1143 | print(x) --> 10 (the global one) |
| 1131 | </pre> | 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 | the new <code>x</code> being declared is not in scope yet, | 1147 | the new <code>x</code> being declared is not in scope yet, |
| 1134 | and so the second <code>x</code> refers to the outside variable. | 1148 | and so the second <code>x</code> refers to the outside variable. |
| 1135 | | 1149 | |
| 1136 | <p>Because of the lexical scoping rules, | 1150 | <p>Because of the lexical scoping rules, |
| 1137 | local variables can be freely accessed by functions | 1151 | local variables can be freely accessed by functions |
| 1138 | defined inside their scope. | 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 | A local variable used by an inner function is called | 1153 | A local variable used by an inner function is called |
| 1148 | an <em>upvalue</em>, or <em>external local variable</em>, | 1154 | an <em>upvalue</em>, or <em>external local variable</em>, |
| 1149 | inside the inner function. | 1155 | inside the inner function. |
| @@ -1152,12 +1158,12 @@ inside the inner function. · 2 unmodified lines |
| 1152 | defines new local variables. | 1158 | defines new local variables. |
| 1153 | Consider the following example: | 1159 | Consider the following example: |
| 1154 | <pre> | 1160 | <pre> |
| 1155 | a = {} | 1161 | a = {} |
| 1156 | local x = 20 | 1162 | local x = 20 |
| 1157 | for i=1,10 do | 1163 | for i=1,10 do |
| 1158 | local y = 0 | 1164 | local y = 0 |
| 1159 | a[i] = function () y=y+1; return x+y end | 1165 | a[i] = function () y=y+1; return x+y end |
| 1160 | end | 1166 | end |
| 1161 | </pre> | 1167 | </pre> |
| 1162 | The loop creates ten closures | 1168 | The loop creates ten closures |
| 1163 | (that is, ten instances of the anonymous function). | 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 | <p><a name="error"></a><a name="2.7"></a><h2>2.7 - Error Handling</h2> | 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 | all Lua actions start from C code in the host program | 1176 | all Lua actions start from C code in the host program |
| 1171 | calling a function from the Lua library (see <a href="#lua_pcall"></a>). | 1177 | calling a function from the Lua library (see <a href="#lua_pcall"></a>). |
| 1172 | Whenever an error occurs during Lua compilation or execution, | 1178 | Whenever an error occurs during Lua compilation or execution, |
| 1173 | control returns to C, | 1179 | control returns to C, |
| 1174 | which can take appropriate measures | 1180 | which can take appropriate measures |
| 1175 | (such as print an error message). | 1181 | (such as printing an error message). |
| 1176 | | 1182 | |
| 1177 | <p>Lua code can explicitly generate an error by calling the | 1183 | <p>Lua code can explicitly generate an error by calling the |
| 1178 | <a href="#pdf-error"><code>error</code></a> function. | 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 | and for all strings, etc. | 1221 | and for all strings, etc. |
| 1216 | | 1222 | |
| 1217 | <p>A metatable may control how an object behaves in arithmetic operations, | 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 | A metatable can also define a function to be called when a userdata | 1225 | A metatable can also define a function to be called when a userdata |
| 1220 | is garbage collected. | 1226 | is garbage collected. |
| 1221 | For each of those operations Lua associates a specific key | 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 | <p>Metatables control the operations listed next. | 1234 | <p>Metatables control the operations listed next. |
| 1229 | Each operation is identified by its corresponding name. | 1235 | Each operation is identified by its corresponding name. |
| 1230 | The key for each operation is a string with its name prefixed by | 1236 | The key for each operation is a string with its name prefixed by |
| 1231 | two underscores; | 1237 | two underscores, `<code>__</code>´; |
| 1232 | for instance, the key for operation "add" is the | 1238 | for instance, the key for operation "add" is the |
| 1233 | string <code>"__add"</code>. | 1239 | string <code>"__add"</code>. |
| 1234 | The semantics of these operations is better explained by a Lua function | 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 | In particular, to retrieve the metamethod of a given object, | 1249 | In particular, to retrieve the metamethod of a given object, |
| 1244 | we use the expression | 1250 | we use the expression |
| 1245 | <pre> | 1251 | <pre> |
| 1246 | metatable(obj)[event] | 1252 | metatable(obj)[event] |
| 1247 | </pre> | 1253 | </pre> |
| 1248 | This should be read as | 1254 | This should be read as |
| 1249 | <pre> | 1255 | <pre> |
| 1250 | rawget(metatable(obj) or {}, event) | 1256 | rawget(getmetatable(obj) or {}, event) |
| 1251 | </pre> | 1257 | </pre> |
| 1252 | That is, the access to a metamethod does not invoke other metamethods, | 1258 | That is, the access to a metamethod does not invoke other metamethods, |
| 1253 | and the access to objects with no metatables does not fail | 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 | <p>Besides metatables, | 1528 | <p>Besides metatables, |
| 1523 | objects of types thread, function, and userdata | 1529 | objects of types thread, function, and userdata |
| 1524 | have another table associated with them, | 1530 | have another table associated with them, |
| 1525 | called <em>environment</em>. | 1531 | called their <em>environment</em>. |
| 1526 | Like metatables, environments are regular tables and | 1532 | Like metatables, environments are regular tables and |
| 1527 | multiple objects can share the same environment. | 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 | It is only a feature for programmers to associate a table to | 1536 | It is only a feature for programmers to associate a table to |
| 1531 | a userdata. | 1537 | a userdata. |
| 1532 | | 1538 | |
| @@ -1557,10 +1563,10 @@ use the C API. · 24 unmodified lines |
| 1557 | | 1563 | |
| 1558 | <p><a name="GC"></a><a name="2.10"></a><h2>2.10 - Garbage Collection</h2> | 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 | That means that | 1567 | That means that |
| 1562 | you do not have to worry about allocating memory for new objects | 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 | Lua manages memory automatically by running | 1570 | Lua manages memory automatically by running |
| 1565 | a <em>garbage collector</em> from time to time | 1571 | a <em>garbage collector</em> from time to time |
| 1566 | to collect all <em>dead objects</em> | 1572 | to collect all <em>dead objects</em> |
| @@ -1568,9 +1574,12 @@ to collect all <em>dead objects</em> · 1 unmodified line |
| 1568 | All objects in Lua are subject to automatic management: | 1574 | All objects in Lua are subject to automatic management: |
| 1569 | tables, userdata, functions, threads, and strings. | 1575 | tables, userdata, functions, threads, and strings. |
| 1570 | | 1576 | |
| 1571 | <p>Lua 5.1 implements an incremental mark-and-sweep collector. | 1577 | <p>Lua implements an incremental mark-and-sweep collector. |
| 1572 | It uses two numbers to control its garbage-collection cycles. | 1578 | It uses two numbers to control its garbage-collection cycles: |
| 1573 | One number, the <em>garbage-collector pause</em>, | 1579 | the <em>garbage-collector pause</em> and |
| | 1580 | the <em>garbage-collector multiplier</em>. |
| | 1581 | |
| | 1582 | <p>The garbage-collector pause |
| 1574 | controls how long the collector waits before starting a new cycle. | 1583 | controls how long the collector waits before starting a new cycle. |
| 1575 | Larger values make the collector less aggressive. | 1584 | Larger values make the collector less aggressive. |
| 1576 | Values smaller than 1 mean the collector will not wait to | 1585 | Values smaller than 1 mean the collector will not wait to |
| @@ -1578,7 +1587,7 @@ start a new cycle. · 1 unmodified line |
| 1578 | A value of 2 means that the collector waits more or less to double | 1587 | A value of 2 means that the collector waits more or less to double |
| 1579 | the total memory in use before starting a new cycle. | 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 | controls the relative speed of the collector relative to | 1591 | controls the relative speed of the collector relative to |
| 1583 | memory allocation. | 1592 | memory allocation. |
| 1584 | Larger values make the collector more aggressive but also increases | 1593 | Larger values make the collector more aggressive but also increases |
| @@ -1605,7 +1614,7 @@ with external resource management · 20 unmodified lines |
| 1605 | (such as closing files, network or database connections, | 1614 | (such as closing files, network or database connections, |
| 1606 | or freeing your own memory). | 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 | collected immediately by the garbage collector. | 1618 | collected immediately by the garbage collector. |
| 1610 | Instead, Lua puts them in a list. | 1619 | Instead, Lua puts them in a list. |
| 1611 | After the collection, | 1620 | After the collection, |
| @@ -1676,8 +1685,8 @@ passing as its first argument · 64 unmodified lines |
| 1676 | the thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, | 1685 | the thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, |
| 1677 | the coroutine starts its execution, | 1686 | the coroutine starts its execution, |
| 1678 | at the first line of its main function. | 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 | 1688 | Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on |
| 1680 | parameters for the coroutine main function. | 1689 | to the coroutine main function. |
| 1681 | After the coroutine starts running, | 1690 | After the coroutine starts running, |
| 1682 | it runs until it terminates or <em>yields</em>. | 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 | with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra | 1712 | with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra |
| 1704 | arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. | 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 | 1715 | <p>The <code>coroutine.wrap</code> function creates a coroutine, |
| 1707 | like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, | 1716 | just like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, |
| 1708 | but instead of returning the coroutine itself, | 1717 | but instead of returning the coroutine itself, |
| 1709 | it returns a function that, when called, resumes the coroutine. | 1718 | it returns a function that, when called, resumes the coroutine. |
| 1710 | Any arguments passed to that function | 1719 | Any arguments passed to that function |
| 1711 | go as extra arguments to resume. | 1720 | go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. |
| 1712 | The function returns all the values returned by resume, | 1721 | <code>coroutine.wrap</code> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, |
| 1713 | except the first one (the boolean error code). | 1722 | except the first one (the boolean error code). |
| 1714 | Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, | 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 | any error is propagated to the caller. | 1725 | any error is propagated to the caller. |
| 1717 | | 1726 | |
| 1718 | <p>As an example, | 1727 | <p>As an example, |
| 1719 | consider the next code: | 1728 | consider the next code: |
| 1720 | <pre> | 1729 | <pre> |
| 1721 | function foo1 (a) | 1730 | function foo (a) |
| 1722 | print("foo", a) | 1731 | print("foo", a) |
| 1723 | return coroutine.yield(2*a) | 1732 | return coroutine.yield(2*a) |
| 1724 | end | 1733 | end |
| 1725 | | 1734 | |
| 1726 | co = coroutine.create(function (a,b) | 1735 | co = coroutine.create(function (a,b) |
| 1727 | print("co-body", a, b) | 1736 | print("co-body", a, b) |
| 1728 | local r = foo1(a+1) | 1737 | local r = foo(a+1) |
| 1729 | print("co-body", r) | 1738 | print("co-body", r) |
| 1730 | local r, s = coroutine.yield(a+b, a-b) | 1739 | local r, s = coroutine.yield(a+b, a-b) |
| 1731 | print("co-body", r, s) | 1740 | print("co-body", r, s) |
| 1732 | return b, "end" | 1741 | return b, "end" |
| 1733 | end) | 1742 | end) |
| 1734 | | 1743 | |
| 1735 | a, b = coroutine.resume(co, 1, 10) | 1744 | print("main", coroutine.resume(co, 1, 10)) |
| 1736 | print("main", a, b) | 1745 | print("main", coroutine.resume(co, "r")) |
| 1737 | a, b, c = coroutine.resume(co, "r") | 1746 | print("main", coroutine.resume(co, "x", "y")) |
| 1738 | print("main", a, b, c) | 1747 | print("main", coroutine.resume(co, "x", "y")) |
| 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) | | |
| 1743 | </pre> | 1748 | </pre> |
| 1744 | When you run it, it produces the following output: | 1749 | When you run it, it produces the following output: |
| 1745 | <pre> | 1750 | <pre> |
| @@ -1767,10 +1772,10 @@ are declared in the header file <code>lua.h</code>. · 21 unmodified lines |
| 1767 | any facility in the API may be provided as a macro instead. | 1772 | any facility in the API may be provided as a macro instead. |
| 1768 | All such macros use each of its arguments exactly once | 1773 | All such macros use each of its arguments exactly once |
| 1769 | (except for the first argument, which is always a Lua state), | 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, | 1777 | <p>As in most C libraries, |
| 1773 | the Lua API functions do not check their arguments. | 1778 | the Lua API functions do not check their arguments for validity or consistency. |
| 1774 | However, you can change this behavior by compiling Lua | 1779 | However, you can change this behavior by compiling Lua |
| 1775 | with a proper definition for the macro <code>luai_apicheck</code>, | 1780 | with a proper definition for the macro <code>luai_apicheck</code>, |
| 1776 | in file <code>luaconf.h</code>. | 1781 | in file <code>luaconf.h</code>. |
| @@ -1784,7 +1789,7 @@ Each element in this stack represents a Lua value · 7 unmodified lines |
| 1784 | <p>Whenever Lua calls C, the called function gets a new stack, | 1789 | <p>Whenever Lua calls C, the called function gets a new stack, |
| 1785 | which is independent of previous stacks and of stacks of | 1790 | which is independent of previous stacks and of stacks of |
| 1786 | C functions that are still active. | 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 | and it is where the C function pushes its results | 1793 | and it is where the C function pushes its results |
| 1789 | to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). | 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 | by using an <em>index</em>: | 1799 | by using an <em>index</em>: |
| 1795 | A positive index represents an <em>absolute</em> stack position | 1800 | A positive index represents an <em>absolute</em> stack position |
| 1796 | (starting at 1); | 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 | More specifically, if the stack has <em>n</em> elements, | 1803 | More specifically, if the stack has <em>n</em> elements, |
| 1799 | then index 1 represents the first element | 1804 | then index 1 represents the first element |
| 1800 | (that is, the element that was pushed onto the stack first) | 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 | <p><a name="3.2"></a><h2>3.2 - Stack Size</h2> | 1816 | <p><a name="3.2"></a><h2>3.2 - Stack Size</h2> |
| 1812 | | 1817 | |
| 1813 | <p>When you interact with Lua API, | 1818 | <p>When you interact with Lua API, |
| | 1819 | you are responsible for ensuring consistency. |
| | 1820 | In particular, |
| 1814 | <em>you are responsible for controlling stack overflow</em>. | 1821 | <em>you are responsible for controlling stack overflow</em>. |
| 1815 | You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> | 1822 | You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> |
| 1816 | to grow the stack size. | 1823 | to grow the stack size. |
| @@ -1828,7 +1835,7 @@ Such indices are called <em>acceptable indices</em>. · 11 unmodified lines |
| 1828 | More formally, we define an <em>acceptable index</em> | 1835 | More formally, we define an <em>acceptable index</em> |
| 1829 | as follows: | 1836 | as follows: |
| 1830 | <pre> | 1837 | <pre> |
| 1831 | (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) | 1838 | (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) |
| 1832 | </pre> | 1839 | </pre> |
| 1833 | Note that 0 is never an acceptable index. | 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 | <p>Unless otherwise noted, | 1844 | <p>Unless otherwise noted, |
| 1838 | any function that accepts valid indices can also be called with | 1845 | any function that accepts valid indices can also be called with |
| 1839 | <em>pseudo-indices</em>, | 1846 | <em>pseudo-indices</em>, |
| 1840 | which represent some Lua values that are accessible to the C code | 1847 | which represent some Lua values that are accessible to C code |
| 1841 | but are not in the stack. | 1848 | but which are not in the stack. |
| 1842 | Pseudo-indices are used to access the thread environment, | 1849 | Pseudo-indices are used to access the thread environment, |
| 1843 | the function environment, | 1850 | the function environment, |
| 1844 | the registry, | 1851 | the registry, |
| @@ -1861,11 +1868,12 @@ For instance, to access the value of a global variable, do · 16 unmodified lines |
| 1861 | <p>When a C function is created, | 1868 | <p>When a C function is created, |
| 1862 | it is possible to associate some values with it, | 1869 | it is possible to associate some values with it, |
| 1863 | thus creating a <em>C closure</em>; | 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 | (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). | 1873 | (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). |
| 1866 | | 1874 | |
| 1867 | <p>Whenever a C function is called, | 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 | Those pseudo-indices are produced by the macro | 1877 | Those pseudo-indices are produced by the macro |
| 1870 | <code>lua_upvalueindex</code>. | 1878 | <code>lua_upvalueindex</code>. |
| 1871 | The first value associated with a function is at position | 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 | <p><a name="registry"></a><a name="3.5"></a><h2>3.5 - Registry</h2> | 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 | a pre-defined table that can be used by any C code to | 1889 | a pre-defined table that can be used by any C code to |
| 1882 | store whatever Lua value it needs to store. | 1890 | store whatever Lua value it needs to store. |
| 1883 | This table is always located at pseudo-index | 1891 | This table is always located at pseudo-index |
| 1884 | <code>LUA_REGISTRYINDEX</code>. | 1892 | <code>LUA_REGISTRYINDEX</code>. |
| 1885 | Any C library can store data into this table, | 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 | Typically, you should use as key a string containing your library name | 1896 | Typically, you should use as key a string containing your library name |
| 1888 | or a light userdata with the address of a C object in your code. | 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 | <p><a name="3.6"></a><h2>3.6 - Error Handling in C</h2> | 1903 | <p><a name="3.6"></a><h2>3.6 - Error Handling in C</h2> |
| 1895 | | 1904 | |
| 1896 | <p>Internally, Lua uses the C <code>longjmp</code> facility to handle errors. | 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 | When Lua faces any error | 1908 | When Lua faces any error |
| 1898 | (such as memory allocation errors, type errors, syntax errors) | 1909 | (such as memory allocation errors, type errors, syntax errors, |
| 1899 | it <em>raises</em> an error, that is, it does a long jump. | 1910 | and runtime errors) |
| | 1911 | it <em>raises</em> an error; |
| | 1912 | that is, it does a long jump. |
| 1900 | A <em>protected environment</em> uses <code>setjmp</code> | 1913 | A <em>protected environment</em> uses <code>setjmp</code> |
| 1901 | to set a recover point; | 1914 | to set a recover point; |
| 1902 | any error jumps to the most recent active recover point. | 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 | <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>, | 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 | <a href="#lua_pcall"><code>lua_pcall</code></a>, and <a href="#lua_cpcall"><code>lua_cpcall</code></a>. | 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 | <p><a name="3.7"></a><h2>3.7 - Functions and Types</h2> | 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 | alphabetical order. | 1930 | alphabetical order. |
| 1918 | | 1931 | |
| 1919 | <p><a name="lua_Alloc"></a> | 1932 | <p><a name="lua_Alloc"></a> |
| 1920 | <hr/><h3><code>lua_Alloc</code></h3> | 1933 | <hr /><h3><code>lua_Alloc</code></h3> |
| 1921 | <pre> | 1934 | <pre> |
| 1922 | typedef void * (*lua_Alloc) (void *ud, | 1935 | typedef void * (*lua_Alloc) (void *ud, |
| 1923 | void *ptr, | 1936 | void *ptr, |
| @@ -1927,12 +1940,12 @@ alphabetical order. · 3 unmodified lines |
| 1927 | </pre> | 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 | The allocator function must provide a | 1944 | The allocator function must provide a |
| 1932 | functionality similar to <code>realloc</code>, | 1945 | functionality similar to <code>realloc</code>, |
| 1933 | but not exactly the same. | 1946 | but not exactly the same. |
| 1934 | Its arguments are <code>ud</code>, | 1947 | Its arguments are |
| 1935 | the opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; | 1948 | <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; |
| 1936 | <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; | 1949 | <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; |
| 1937 | <code>osize</code>, the original size of the block; | 1950 | <code>osize</code>, the original size of the block; |
| 1938 | <code>nsize</code>, the new size of the block. | 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 | When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> | 1956 | When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> |
| 1944 | if and only if it cannot fill the request. | 1957 | if and only if it cannot fill the request. |
| 1945 | When <code>nsize</code> is not zero and <code>osize</code> is zero, | 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 | When <code>nsize</code> and <code>osize</code> are not zero, | 1960 | When <code>nsize</code> and <code>osize</code> are not zero, |
| 1948 | the allocator behaves like <code>realloc</code>. | 1961 | the allocator behaves like <code>realloc</code>. |
| 1949 | Lua assumes that the allocator never fails when | 1962 | Lua assumes that the allocator never fails when |
| 1950 | <code>osize >= nsize</code>. | 1963 | <code>osize >= nsize</code>. |
| 1951 | | 1964 | |
| 1952 | <p>A simple implementation for the allocator function | 1965 | <p>Here is a simple implementation for the allocator function. |
| 1953 | could be like this: | 1966 | It is used in the auxiliary library by <a href="#lua_newstate"><code>lua_newstate</code></a>. |
| 1954 | <pre> | 1967 | <pre> |
| 1955 | static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { | 1968 | static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { |
| 1956 | (void)ud; /* not used */ | 1969 | (void)ud; /* not used */ |
| 1957 | (void)osize; /* not used */ | 1970 | (void)osize; /* not used */ |
| 1958 | if (nsize == 0) { | 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 | return NULL; | 1973 | return NULL; |
| 1961 | } | 1974 | } |
| 1962 | else | 1975 | else |
| 1963 | /* ANSI ensures that realloc(NULL, size) == malloc(size) */ | 1976 | /* ANSI requires that realloc(NULL, size) == malloc(size) */ |
| 1964 | return realloc(ptr, nsize); | 1977 | return realloc(ptr, nsize); |
| 1965 | } | 1978 | } |
| 1966 | </pre> | 1979 | </pre> |
| 1967 | | 1980 | |
| 1968 | <p><a name="lua_atpanic"></a> | 1981 | <p><a name="lua_atpanic"></a> |
| 1969 | <hr/><h3><code>lua_atpanic</code></h3> | 1982 | <hr /><h3><code>lua_atpanic</code></h3> |
| 1970 | <pre> | 1983 | <pre> |
| 1971 | lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); | 1984 | lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); |
| 1972 | </pre> | 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 | <p>If an error happens outside any protected environment, | 1990 | <p>If an error happens outside any protected environment, |
| 1978 | Lua calls a <em>panic function</em> | 1991 | Lua calls a <em>panic function</em> |
| 1979 | and then calls <code>exit(EXIT_FAILURE)</code>. | 1992 | and then calls <code>exit(EXIT_FAILURE)</code>, |
| 1980 | Your new panic function may avoid the application exit by | 1993 | thus exiting the host application. |
| | 1994 | Your panic function may avoid this exit by |
| 1981 | never returning (e.g., doing a long jump). | 1995 | never returning (e.g., doing a long jump). |
| 1982 | | 1996 | |
| 1983 | <p>The panic function can access the error message at the top of the stack. | 1997 | <p>The panic function can access the error message at the top of the stack. |
| 1984 | | 1998 | |
| 1985 | <p><a name="lua_call"></a> | 1999 | <p><a name="lua_call"></a> |
| 1986 | <hr/><h3><code>lua_call</code></h3> | 2000 | <hr /><h3><code>lua_call</code></h3> |
| 1987 | <pre> | 2001 | <pre> |
| 1988 | void lua_call (lua_State *L, int nargs, int nresults); | 2002 | void lua_call (lua_State *L, int nargs, int nresults); |
| 1989 | </pre> | 2003 | </pre> |
| @@ -1994,18 +2008,20 @@ never returning (e.g., doing a long jump). · 4 unmodified lines |
| 1994 | <p>To call a function you must use the following protocol: | 2008 | <p>To call a function you must use the following protocol: |
| 1995 | First, the function to be called is pushed onto the stack; | 2009 | First, the function to be called is pushed onto the stack; |
| 1996 | then, the arguments to the function are pushed | 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 | Finally you call <a href="#lua_call"><code>lua_call</code></a>; | 2013 | Finally you call <a href="#lua_call"><code>lua_call</code></a>; |
| 1999 | <code>nargs</code> is the number of arguments that you pushed onto the stack. | 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, | 2015 | All arguments and the function value are popped from the stack |
| 2001 | and the function results are pushed. | 2016 | when the function is called. |
| 2002 | The number of results are adjusted to <code>nresults</code>, | 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 | unless <code>nresults</code> is <code>LUA_MULTRET</code>. | 2019 | unless <code>nresults</code> is <code>LUA_MULTRET</code>. |
| 2004 | In that case, <em>all</em> results from the function are pushed. | 2020 | In that case, <em>all</em> results from the function are pushed. |
| 2005 | Lua takes care that the returned values fit into the stack space. | 2021 | Lua takes care that the returned values fit into the stack space. |
| 2006 | The function results are pushed onto the stack in direct order | 2022 | The function results are pushed onto the stack in direct order |
| 2007 | (the first result is pushed first), | 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 | <p>Any error inside the called function is propagated upwards | 2026 | <p>Any error inside the called function is propagated upwards |
| 2011 | (with a <code>longjmp</code>). | 2027 | (with a <code>longjmp</code>). |
| @@ -2017,21 +2033,21 @@ equivalent to this Lua code: · 5 unmodified lines |
| 2017 | </pre> | 2033 | </pre> |
| 2018 | Here it is in C: | 2034 | Here it is in C: |
| 2019 | <pre> | 2035 | <pre> |
| 2020 | lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* global `t' (for later use) */ | | |
| 2021 | lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ | 2036 | lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ |
| 2022 | lua_pushstring(L, "how"); /* 1st argument */ | 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 | lua_pushinteger(L, 14); /* 3rd argument */ | 2041 | lua_pushinteger(L, 14); /* 3rd argument */ |
| 2025 | lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ | 2042 | lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ |
| 2026 | lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global variable `a' */ | 2043 | lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global variable `a' */ |
| 2027 | lua_pop(L, 1); /* remove `t' from the stack */ | | |
| 2028 | </pre> | 2044 | </pre> |
| 2029 | Note that the code above is "balanced": | 2045 | Note that the code above is "balanced": |
| 2030 | at its end, the stack is back to its original configuration. | 2046 | at its end, the stack is back to its original configuration. |
| 2031 | This is considered good programming practice. | 2047 | This is considered good programming practice. |
| 2032 | | 2048 | |
| 2033 | <p><a name="lua_CFunction"></a> | 2049 | <p><a name="lua_CFunction"></a> |
| 2034 | <hr/><h3><code>lua_CFunction</code></h3> | 2050 | <hr /><h3><code>lua_CFunction</code></h3> |
| 2035 | <pre> | 2051 | <pre> |
| 2036 | typedef int (*lua_CFunction) (lua_State *L); | 2052 | typedef int (*lua_CFunction) (lua_State *L); |
| 2037 | </pre> | 2053 | </pre> |
| @@ -2040,17 +2056,19 @@ This is considered good programming practice. · 2 unmodified lines |
| 2040 | <p>Type for C functions. | 2056 | <p>Type for C functions. |
| 2041 | | 2057 | |
| 2042 | <p>In order to communicate properly with Lua, | 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 | which defines the way parameters and results are passed: | 2060 | which defines the way parameters and results are passed: |
| 2045 | A C function receives its arguments from Lua in its stack | 2061 | A C function receives its arguments from Lua in its stack |
| 2046 | in direct order (the first argument is pushed first). | 2062 | in direct order (the first argument is pushed first). |
| 2047 | So, when the function starts, | 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 | To return values to Lua, a C function just pushes them onto the stack, | 2067 | To return values to Lua, a C function just pushes them onto the stack, |
| 2050 | in direct order (the first result is pushed first), | 2068 | in direct order (the first result is pushed first), |
| 2051 | and returns the number of results. | 2069 | and returns the number of results. |
| 2052 | Any other value in the stack below the results will be properly | 2070 | Any other value in the stack below the results will be properly |
| 2053 | discharged by Lua. | 2071 | discarded by Lua. |
| 2054 | Like a Lua function, a C function called by Lua can also return | 2072 | Like a Lua function, a C function called by Lua can also return |
| 2055 | many results. | 2073 | many results. |
| 2056 | | 2074 | |
| @@ -2075,20 +2093,20 @@ of numerical arguments and returns their average and sum: · 18 unmodified lines |
| 2075 | </pre> | 2093 | </pre> |
| 2076 | | 2094 | |
| 2077 | <p><a name="lua_checkstack"></a> | 2095 | <p><a name="lua_checkstack"></a> |
| 2078 | <hr/><h3><code>lua_checkstack</code></h3> | 2096 | <hr /><h3><code>lua_checkstack</code></h3> |
| 2079 | <pre> | 2097 | <pre> |
| 2080 | int lua_checkstack (lua_State *L, int extra); | 2098 | int lua_checkstack (lua_State *L, int extra); |
| 2081 | </pre> | 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 | it returns false if it cannot grow the stack to that size. | 2103 | it returns false if it cannot grow the stack to that size. |
| 2086 | This function never shrinks the stack; | 2104 | This function never shrinks the stack; |
| 2087 | if the stack is already larger than the new size, | 2105 | if the stack is already larger than the new size, |
| 2088 | it is left unchanged. | 2106 | it is left unchanged. |
| 2089 | | 2107 | |
| 2090 | <p><a name="lua_close"></a> | 2108 | <p><a name="lua_close"></a> |
| 2091 | <hr/><h3><code>lua_close</code></h3> | 2109 | <hr /><h3><code>lua_close</code></h3> |
| 2092 | <pre> | 2110 | <pre> |
| 2093 | void lua_close (lua_State *L); | 2111 | void lua_close (lua_State *L); |
| 2094 | </pre> | 2112 | </pre> |
| @@ -2105,7 +2123,7 @@ might need to release states as soon as they are not needed, · 10 unmodified lines |
| 2105 | to avoid growing too large. | 2123 | to avoid growing too large. |
| 2106 | | 2124 | |
| 2107 | <p><a name="lua_concat"></a> | 2125 | <p><a name="lua_concat"></a> |
| 2108 | <hr/><h3><code>lua_concat</code></h3> | 2126 | <hr /><h3><code>lua_concat</code></h3> |
| 2109 | <pre> | 2127 | <pre> |
| 2110 | void lua_concat (lua_State *L, int n); | 2128 | void lua_concat (lua_State *L, int n); |
| 2111 | </pre> | 2129 | </pre> |
| @@ -2120,7 +2138,7 @@ Concatenation is done following the usual semantics of Lua · 8 unmodified lines |
| 2120 | (see <a href="#concat">2.5.4</a>). | 2138 | (see <a href="#concat">2.5.4</a>). |
| 2121 | | 2139 | |
| 2122 | <p><a name="lua_cpcall"></a> | 2140 | <p><a name="lua_cpcall"></a> |
| 2123 | <hr/><h3><code>lua_cpcall</code></h3> | 2141 | <hr /><h3><code>lua_cpcall</code></h3> |
| 2124 | <pre> | 2142 | <pre> |
| 2125 | int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); | 2143 | int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); |
| 2126 | </pre> | 2144 | </pre> |
| @@ -2133,10 +2151,10 @@ In case of errors, · 6 unmodified lines |
| 2133 | <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, | 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 | plus the error object on the top of the stack; | 2152 | plus the error object on the top of the stack; |
| 2135 | otherwise, it returns zero, and does not change the stack. | 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 | <p><a name="lua_createtable"></a> | 2156 | <p><a name="lua_createtable"></a> |
| 2139 | <hr/><h3><code>lua_createtable</code></h3> | 2157 | <hr /><h3><code>lua_createtable</code></h3> |
| 2140 | <pre> | 2158 | <pre> |
| 2141 | void lua_createtable (lua_State *L, int narr, int nrec); | 2159 | void lua_createtable (lua_State *L, int narr, int nrec); |
| 2142 | </pre> | 2160 | </pre> |
| @@ -2144,25 +2162,26 @@ Any value returned by <code>func</code> is discarded. · 1 unmodified line |
| 2144 | | 2162 | |
| 2145 | <p>Creates a new empty table and pushes it onto the stack. | 2163 | <p>Creates a new empty table and pushes it onto the stack. |
| 2146 | The new table has space pre-allocated | 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 | This pre-allocation is useful when you know exactly how many elements | 2166 | This pre-allocation is useful when you know exactly how many elements |
| 2149 | the table will have. | 2167 | the table will have. |
| 2150 | Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. | 2168 | Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. |
| 2151 | | 2169 | |
| 2152 | <p><a name="lua_dump"></a> | 2170 | <p><a name="lua_dump"></a> |
| 2153 | <hr/><h3><code>lua_dump</code></h3> | 2171 | <hr /><h3><code>lua_dump</code></h3> |
| 2154 | <pre> | 2172 | <pre> |
| 2155 | int lua_dump (lua_State *L, lua_Writer writer, void *data); | 2173 | int lua_dump (lua_State *L, lua_Writer writer, void *data); |
| 2156 | </pre> | 2174 | </pre> |
| 2157 | | 2175 | |
| 2158 | | 2176 | |
| 2159 | <p>Dumps a function as a binary chunk. | 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 | and produces a binary chunk that, | 2179 | and produces a binary chunk that, |
| 2162 | if loaded again, | 2180 | if loaded again, |
| 2163 | results in a function equivalent to the one dumped. | 2181 | results in a function equivalent to the one dumped. |
| 2164 | As it produces parts of the chunk, | 2182 | As it produces parts of the chunk, |
| 2165 | <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) | 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 | to write them. | 2185 | to write them. |
| 2167 | | 2186 | |
| 2168 | <p>The value returned is the error code returned by the last | 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 | <p>This function does not pop the function from the stack. | 2191 | <p>This function does not pop the function from the stack. |
| 2173 | | 2192 | |
| 2174 | <p><a name="lua_equal"></a> | 2193 | <p><a name="lua_equal"></a> |
| 2175 | <hr/><h3><code>lua_equal</code></h3> | 2194 | <hr /><h3><code>lua_equal</code></h3> |
| 2176 | <pre> | 2195 | <pre> |
| 2177 | int lua_equal (lua_State *L, int index1, int index2); | 2196 | int lua_equal (lua_State *L, int index1, int index2); |
| 2178 | </pre> | 2197 | </pre> |
| @@ -2183,23 +2202,24 @@ call to the writer; · 4 unmodified lines |
| 2183 | following the semantics of the Lua <code>==</code> operator | 2202 | following the semantics of the Lua <code>==</code> operator |
| 2184 | (that is, may call metamethods). | 2203 | (that is, may call metamethods). |
| 2185 | Otherwise returns 0. | 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 | <p><a name="lua_error"></a> | 2207 | <p><a name="lua_error"></a> |
| 2189 | <hr/><h3><code>lua_error</code></h3> | 2208 | <hr /><h3><code>lua_error</code></h3> |
| 2190 | <pre> | 2209 | <pre> |
| 2191 | int lua_error (lua_State *L); | 2210 | int lua_error (lua_State *L); |
| 2192 | </pre> | 2211 | </pre> |
| 2193 | | 2212 | |
| 2194 | | 2213 | |
| 2195 | <p>Generates a Lua error. | 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 | must be on the stack top. | 2216 | must be on the stack top. |
| 2198 | This function does a long jump, | 2217 | This function does a long jump, |
| 2199 | and therefore never returns. | 2218 | and therefore never returns. |
| | 2219 | (see <a href="#pdf-luaL_error"><code>luaL_error</code></a>). |
| 2200 | | 2220 | |
| 2201 | <p><a name="lua_gc"></a> | 2221 | <p><a name="lua_gc"></a> |
| 2202 | <hr/><h3><code>lua_gc</code></h3> | 2222 | <hr /><h3><code>lua_gc</code></h3> |
| 2203 | <pre> | 2223 | <pre> |
| 2204 | int lua_gc (lua_State *L, int what, int data); | 2224 | int lua_gc (lua_State *L, int what, int data); |
| 2205 | </pre> | 2225 | </pre> |
| @@ -2227,28 +2247,28 @@ you must tune experimentally the value of <code>data</code>. · 21 unmodified lines |
| 2227 | The function returns 1 if that step finished a | 2247 | The function returns 1 if that step finished a |
| 2228 | garbage-collection cycle. | 2248 | garbage-collection cycle. |
| 2229 | <li> <code>LUA_GCSETPAUSE</code>--- | 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 | for the <em>pause</em> of the collector (see <a href="#GC">2.10</a>). | 2251 | for the <em>pause</em> of the collector (see <a href="#GC">2.10</a>). |
| 2232 | The function returns the previous value of the pause. | 2252 | The function returns the previous value of the pause. |
| 2233 | <li> <code>LUA_GCSETSTEPMUL</code>--- | 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 | the collector (see <a href="#GC">2.10</a>). | 2255 | the collector (see <a href="#GC">2.10</a>). |
| 2236 | The function returns the previous value of the step multiplier. | 2256 | The function returns the previous value of the step multiplier. |
| 2237 | </ul> | 2257 | </ul> |
| 2238 | | 2258 | |
| 2239 | <p><a name="lua_getallocf"></a> | 2259 | <p><a name="lua_getallocf"></a> |
| 2240 | <hr/><h3><code>lua_getallocf</code></h3> | 2260 | <hr /><h3><code>lua_getallocf</code></h3> |
| 2241 | <pre> | 2261 | <pre> |
| 2242 | lua_Alloc lua_getallocf (lua_State *L, void **ud); | 2262 | lua_Alloc lua_getallocf (lua_State *L, void **ud); |
| 2243 | </pre> | 2263 | </pre> |
| 2244 | | 2264 | |
| 2245 | | 2265 | |
| 2246 | <p>Returns the allocator function of a given state. | 2266 | <p>Returns the memory allocator function of a given state. |
| 2247 | If <code>ud</code> is not <code>NULL</code> Lua stores in <code>*ud</code> the | 2267 | If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the |
| 2248 | opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. | 2268 | opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. |
| 2249 | | 2269 | |
| 2250 | <p><a name="lua_getfenv"></a> | 2270 | <p><a name="lua_getfenv"></a> |
| 2251 | <hr/><h3><code>lua_getfenv</code></h3> | 2271 | <hr /><h3><code>lua_getfenv</code></h3> |
| 2252 | <pre> | 2272 | <pre> |
| 2253 | void lua_getfenv (lua_State *L, int index); | 2273 | void lua_getfenv (lua_State *L, int index); |
| 2254 | </pre> | 2274 | </pre> |
| @@ -2258,7 +2278,7 @@ opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. · 3 unmodified lines |
| 2258 | the value at the given index. | 2278 | the value at the given index. |
| 2259 | | 2279 | |
| 2260 | <p><a name="lua_getfield"></a> | 2280 | <p><a name="lua_getfield"></a> |
| 2261 | <hr/><h3><code>lua_getfield</code></h3> | 2281 | <hr /><h3><code>lua_getfield</code></h3> |
| 2262 | <pre> | 2282 | <pre> |
| 2263 | void lua_getfield (lua_State *L, int index, const char *k); | 2283 | void lua_getfield (lua_State *L, int index, const char *k); |
| 2264 | </pre> | 2284 | </pre> |
| @@ -2270,7 +2290,7 @@ As in Lua, this function may trigger a metamethod · 5 unmodified lines |
| 2270 | for the "index" event (see <a href="#metatable">2.8</a>). | 2290 | for the "index" event (see <a href="#metatable">2.8</a>). |
| 2271 | | 2291 | |
| 2272 | <p><a name="lua_getmetatable"></a> | 2292 | <p><a name="lua_getmetatable"></a> |
| 2273 | <hr/><h3><code>lua_getmetatable</code></h3> | 2293 | <hr /><h3><code>lua_getmetatable</code></h3> |
| 2274 | <pre> | 2294 | <pre> |
| 2275 | int lua_getmetatable (lua_State *L, int index); | 2295 | int lua_getmetatable (lua_State *L, int index); |
| 2276 | </pre> | 2296 | </pre> |
| @@ -2283,7 +2303,7 @@ or if the value does not have a metatable, · 6 unmodified lines |
| 2283 | returns 0 and pushes nothing on the stack. | 2303 | returns 0 and pushes nothing on the stack. |
| 2284 | | 2304 | |
| 2285 | <p><a name="lua_gettable"></a> | 2305 | <p><a name="lua_gettable"></a> |
| 2286 | <hr/><h3><code>lua_gettable</code></h3> | 2306 | <hr /><h3><code>lua_gettable</code></h3> |
| 2287 | <pre> | 2307 | <pre> |
| 2288 | void lua_gettable (lua_State *L, int index); | 2308 | void lua_gettable (lua_State *L, int index); |
| 2289 | </pre> | 2309 | </pre> |
| @@ -2299,7 +2319,7 @@ As in Lua, this function may trigger a metamethod · 9 unmodified lines |
| 2299 | for the "index" event (see <a href="#metatable">2.8</a>). | 2319 | for the "index" event (see <a href="#metatable">2.8</a>). |
| 2300 | | 2320 | |
| 2301 | <p><a name="lua_gettop"></a> | 2321 | <p><a name="lua_gettop"></a> |
| 2302 | <hr/><h3><code>lua_gettop</code></h3> | 2322 | <hr /><h3><code>lua_gettop</code></h3> |
| 2303 | <pre> | 2323 | <pre> |
| 2304 | int lua_gettop (lua_State *L); | 2324 | int lua_gettop (lua_State *L); |
| 2305 | </pre> | 2325 | </pre> |
| @@ -2311,7 +2331,7 @@ that result is equal to the number of elements in the stack · 5 unmodified lines |
| 2311 | (and so 0 means an empty stack). | 2331 | (and so 0 means an empty stack). |
| 2312 | | 2332 | |
| 2313 | <p><a name="lua_insert"></a> | 2333 | <p><a name="lua_insert"></a> |
| 2314 | <hr/><h3><code>lua_insert</code></h3> | 2334 | <hr /><h3><code>lua_insert</code></h3> |
| 2315 | <pre> | 2335 | <pre> |
| 2316 | void lua_insert (lua_State *L, int index); | 2336 | void lua_insert (lua_State *L, int index); |
| 2317 | </pre> | 2337 | </pre> |
| @@ -2323,7 +2343,7 @@ Cannot be called with a pseudo-index, · 5 unmodified lines |
| 2323 | because a pseudo-index is not an actual stack position. | 2343 | because a pseudo-index is not an actual stack position. |
| 2324 | | 2344 | |
| 2325 | <p><a name="lua_Integer"></a> | 2345 | <p><a name="lua_Integer"></a> |
| 2326 | <hr/><h3><code>lua_Integer</code></h3> | 2346 | <hr /><h3><code>lua_Integer</code></h3> |
| 2327 | <pre> | 2347 | <pre> |
| 2328 | typedef ptrdiff_t lua_Integer; | 2348 | typedef ptrdiff_t lua_Integer; |
| 2329 | </pre> | 2349 | </pre> |
| @@ -2332,11 +2352,11 @@ because a pseudo-index is not an actual stack position. · 2 unmodified lines |
| 2332 | <p>The type used by the Lua API to represent integral values. | 2352 | <p>The type used by the Lua API to represent integral values. |
| 2333 | | 2353 | |
| 2334 | <p>By default it is a <code>ptrdiff_t</code>, | 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 | "comfortably". | 2356 | "comfortably". |
| 2337 | | 2357 | |
| 2338 | <p><a name="lua_isboolean"></a> | 2358 | <p><a name="lua_isboolean"></a> |
| 2339 | <hr/><h3><code>lua_isboolean</code></h3> | 2359 | <hr /><h3><code>lua_isboolean</code></h3> |
| 2340 | <pre> | 2360 | <pre> |
| 2341 | int lua_isboolean (lua_State *L, int index); | 2361 | int lua_isboolean (lua_State *L, int index); |
| 2342 | </pre> | 2362 | </pre> |
| @@ -2346,7 +2366,7 @@ which is usually the largest type the machine handles · 3 unmodified lines |
| 2346 | and 0 otherwise. | 2366 | and 0 otherwise. |
| 2347 | | 2367 | |
| 2348 | <p><a name="lua_iscfunction"></a> | 2368 | <p><a name="lua_iscfunction"></a> |
| 2349 | <hr/><h3><code>lua_iscfunction</code></h3> | 2369 | <hr /><h3><code>lua_iscfunction</code></h3> |
| 2350 | <pre> | 2370 | <pre> |
| 2351 | int lua_iscfunction (lua_State *L, int index); | 2371 | int lua_iscfunction (lua_State *L, int index); |
| 2352 | </pre> | 2372 | </pre> |
| @@ -2356,7 +2376,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2356 | and 0 otherwise. | 2376 | and 0 otherwise. |
| 2357 | | 2377 | |
| 2358 | <p><a name="lua_isfunction"></a> | 2378 | <p><a name="lua_isfunction"></a> |
| 2359 | <hr/><h3><code>lua_isfunction</code></h3> | 2379 | <hr /><h3><code>lua_isfunction</code></h3> |
| 2360 | <pre> | 2380 | <pre> |
| 2361 | int lua_isfunction (lua_State *L, int index); | 2381 | int lua_isfunction (lua_State *L, int index); |
| 2362 | </pre> | 2382 | </pre> |
| @@ -2366,7 +2386,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2366 | (either C or Lua), and 0 otherwise. | 2386 | (either C or Lua), and 0 otherwise. |
| 2367 | | 2387 | |
| 2368 | <p><a name="lua_islightuserdata"></a> | 2388 | <p><a name="lua_islightuserdata"></a> |
| 2369 | <hr/><h3><code>lua_islightuserdata</code></h3> | 2389 | <hr /><h3><code>lua_islightuserdata</code></h3> |
| 2370 | <pre> | 2390 | <pre> |
| 2371 | int lua_islightuserdata (lua_State *L, int index); | 2391 | int lua_islightuserdata (lua_State *L, int index); |
| 2372 | </pre> | 2392 | </pre> |
| @@ -2376,7 +2396,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2376 | and 0 otherwise. | 2396 | and 0 otherwise. |
| 2377 | | 2397 | |
| 2378 | <p><a name="lua_isnil"></a> | 2398 | <p><a name="lua_isnil"></a> |
| 2379 | <hr/><h3><code>lua_isnil</code></h3> | 2399 | <hr /><h3><code>lua_isnil</code></h3> |
| 2380 | <pre> | 2400 | <pre> |
| 2381 | int lua_isnil (lua_State *L, int index); | 2401 | int lua_isnil (lua_State *L, int index); |
| 2382 | </pre> | 2402 | </pre> |
| @@ -2386,7 +2406,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2386 | and 0 otherwise. | 2406 | and 0 otherwise. |
| 2387 | | 2407 | |
| 2388 | <p><a name="lua_isnumber"></a> | 2408 | <p><a name="lua_isnumber"></a> |
| 2389 | <hr/><h3><code>lua_isnumber</code></h3> | 2409 | <hr /><h3><code>lua_isnumber</code></h3> |
| 2390 | <pre> | 2410 | <pre> |
| 2391 | int lua_isnumber (lua_State *L, int index); | 2411 | int lua_isnumber (lua_State *L, int index); |
| 2392 | </pre> | 2412 | </pre> |
| @@ -2397,7 +2417,7 @@ or a string convertible to a number, · 4 unmodified lines |
| 2397 | and 0 otherwise. | 2417 | and 0 otherwise. |
| 2398 | | 2418 | |
| 2399 | <p><a name="lua_isstring"></a> | 2419 | <p><a name="lua_isstring"></a> |
| 2400 | <hr/><h3><code>lua_isstring</code></h3> | 2420 | <hr /><h3><code>lua_isstring</code></h3> |
| 2401 | <pre> | 2421 | <pre> |
| 2402 | int lua_isstring (lua_State *L, int index); | 2422 | int lua_isstring (lua_State *L, int index); |
| 2403 | </pre> | 2423 | </pre> |
| @@ -2408,7 +2428,7 @@ or a number (which is always convertible to a string), · 4 unmodified lines |
| 2408 | and 0 otherwise. | 2428 | and 0 otherwise. |
| 2409 | | 2429 | |
| 2410 | <p><a name="lua_istable"></a> | 2430 | <p><a name="lua_istable"></a> |
| 2411 | <hr/><h3><code>lua_istable</code></h3> | 2431 | <hr /><h3><code>lua_istable</code></h3> |
| 2412 | <pre> | 2432 | <pre> |
| 2413 | int lua_istable (lua_State *L, int index); | 2433 | int lua_istable (lua_State *L, int index); |
| 2414 | </pre> | 2434 | </pre> |
| @@ -2418,7 +2438,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2418 | and 0 otherwise. | 2438 | and 0 otherwise. |
| 2419 | | 2439 | |
| 2420 | <p><a name="lua_isthread"></a> | 2440 | <p><a name="lua_isthread"></a> |
| 2421 | <hr/><h3><code>lua_isthread</code></h3> | 2441 | <hr /><h3><code>lua_isthread</code></h3> |
| 2422 | <pre> | 2442 | <pre> |
| 2423 | int lua_isthread (lua_State *L, int index); | 2443 | int lua_isthread (lua_State *L, int index); |
| 2424 | </pre> | 2444 | </pre> |
| @@ -2428,7 +2448,7 @@ and 0 otherwise. · 3 unmodified lines |
| 2428 | and 0 otherwise. | 2448 | and 0 otherwise. |
| 2429 | | 2449 | |
| 2430 | <p><a name="lua_isuserdata"></a> | 2450 | <p><a name="lua_isuserdata"></a> |
| 2431 | <hr/><h3><code>lua_isuserdata</code></h3> | 2451 | <hr /><h3><code>lua_isuserdata</code></h3> |
| 2432 | <pre> | 2452 | <pre> |
| 2433 | int lua_isuserdata (lua_State *L, int index); | 2453 | int lua_isuserdata (lua_State *L, int index); |
| 2434 | </pre> | 2454 | </pre> |
| @@ -2438,21 +2458,21 @@ and 0 otherwise. · 3 unmodified lines |
| 2438 | (either full or light), and 0 otherwise. | 2458 | (either full or light), and 0 otherwise. |
| 2439 | | 2459 | |
| 2440 | <p><a name="lua_lessthan"></a> | 2460 | <p><a name="lua_lessthan"></a> |
| 2441 | <hr/><h3><code>lua_lessthan</code></h3> | 2461 | <hr /><h3><code>lua_lessthan</code></h3> |
| 2442 | <pre> | 2462 | <pre> |
| 2443 | int lua_lessthan (lua_State *L, int index1, int index2); | 2463 | int lua_lessthan (lua_State *L, int index1, int index2); |
| 2444 | </pre> | 2464 | </pre> |
| 2445 | | 2465 | |
| 2446 | | 2466 | |
| 2447 | <p>Returns 1 if the value in acceptable index <code>index1</code> is smaller | 2467 | <p>Returns 1 if the value at acceptable index <code>index1</code> is smaller |
| 2448 | than the value in acceptable index <code>index2</code>, | 2468 | than the value at acceptable index <code>index2</code>, |
| 2449 | following the semantics of the Lua <code><</code> operator | 2469 | following the semantics of the Lua <code><</code> operator |
| 2450 | (that is, may call metamethods). | 2470 | (that is, may call metamethods). |
| 2451 | Otherwise returns 0. | 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 | <p><a name="lua_load"></a> | 2474 | <p><a name="lua_load"></a> |
| 2455 | <hr/><h3><code>lua_load</code></h3> | 2475 | <hr /><h3><code>lua_load</code></h3> |
| 2456 | <pre> | 2476 | <pre> |
| 2457 | int lua_load (lua_State *L, lua_Reader reader, void *data, | 2477 | int lua_load (lua_State *L, lua_Reader reader, void *data, |
| 2458 | const char *chunkname); | 2478 | const char *chunkname); |
| @@ -2481,11 +2501,11 @@ and loads it accordingly (see program <code>luac</code>). · 22 unmodified lines |
| 2481 | (see <a href="#lua_Reader"><code>lua_Reader</code></a>). | 2501 | (see <a href="#lua_Reader"><code>lua_Reader</code></a>). |
| 2482 | The <code>data</code> argument is an opaque value passed to the reader function. | 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. | 2504 | <p>The <code>chunkname</code> argument gives a name to the chunk, |
| 2485 | It is used for error messages and debug information (see <a href="#debugI">3.8</a>). | 2505 | which is used for error messages and in debug information (see <a href="#debugI">3.8</a>). |
| 2486 | | 2506 | |
| 2487 | <p><a name="lua_newstate"></a> | 2507 | <p><a name="lua_newstate"></a> |
| 2488 | <hr/><h3><code>lua_newstate</code></h3> | 2508 | <hr /><h3><code>lua_newstate</code></h3> |
| 2489 | <pre> | 2509 | <pre> |
| 2490 | lua_State *lua_newstate (lua_Alloc f, void *ud); | 2510 | lua_State *lua_newstate (lua_Alloc f, void *ud); |
| 2491 | </pre> | 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 | <p>Creates a new, independent state. | 2514 | <p>Creates a new, independent state. |
| 2495 | Returns <code>NULL</code> if cannot create the state | 2515 | Returns <code>NULL</code> if cannot create the state |
| 2496 | (not enough memory). | 2516 | (due to lack of memory). |
| 2497 | The argument <code>f</code> is the allocator function; | 2517 | The argument <code>f</code> is the allocator function; |
| 2498 | Lua does all memory allocation for that state through that function. | 2518 | Lua does all memory allocation for that state through that function. |
| 2499 | The second argument, <code>ud</code>, is an opaque pointer that Lua | 2519 | The second argument, <code>ud</code>, is an opaque pointer that Lua |
| 2500 | simply passes to the allocator in every call. | 2520 | simply passes to the allocator in every call. |
| 2501 | | 2521 | |
| 2502 | <p><a name="lua_newtable"></a> | 2522 | <p><a name="lua_newtable"></a> |
| 2503 | <hr/><h3><code>lua_newtable</code></h3> | 2523 | <hr /><h3><code>lua_newtable</code></h3> |
| 2504 | <pre> | 2524 | <pre> |
| 2505 | void lua_newtable (lua_State *L); | 2525 | void lua_newtable (lua_State *L); |
| 2506 | </pre> | 2526 | </pre> |
| @@ -2510,7 +2530,7 @@ simply passes to the allocator in every call. · 3 unmodified lines |
| 2510 | Equivalent to <code>lua_createtable(L, 0, 0)</code>. | 2530 | Equivalent to <code>lua_createtable(L, 0, 0)</code>. |
| 2511 | | 2531 | |
| 2512 | <p><a name="lua_newthread"></a> | 2532 | <p><a name="lua_newthread"></a> |
| 2513 | <hr/><h3><code>lua_newthread</code></h3> | 2533 | <hr /><h3><code>lua_newthread</code></h3> |
| 2514 | <pre> | 2534 | <pre> |
| 2515 | lua_State *lua_newthread (lua_State *L); | 2535 | lua_State *lua_newthread (lua_State *L); |
| 2516 | </pre> | 2536 | </pre> |
| @@ -2520,14 +2540,14 @@ Equivalent to <code>lua_createtable(L, 0, 0)</code>. · 3 unmodified lines |
| 2520 | and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. | 2540 | and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. |
| 2521 | The new state returned by this function shares with the original state | 2541 | The new state returned by this function shares with the original state |
| 2522 | all global objects (such as tables), | 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 | <p>There is no explicit function to close or to destroy a thread. | 2545 | <p>There is no explicit function to close or to destroy a thread. |
| 2526 | Threads are subject to garbage collection, | 2546 | Threads are subject to garbage collection, |
| 2527 | like any Lua object. | 2547 | like any Lua object. |
| 2528 | | 2548 | |
| 2529 | <p><a name="lua_newuserdata"></a> | 2549 | <p><a name="lua_newuserdata"></a> |
| 2530 | <hr/><h3><code>lua_newuserdata</code></h3> | 2550 | <hr /><h3><code>lua_newuserdata</code></h3> |
| 2531 | <pre> | 2551 | <pre> |
| 2532 | void *lua_newuserdata (lua_State *L, size_t size); | 2552 | void *lua_newuserdata (lua_State *L, size_t size); |
| 2533 | </pre> | 2553 | </pre> |
| @@ -2544,21 +2564,22 @@ You must create it, it can have its own metatable, · 10 unmodified lines |
| 2544 | and you can detect when it is being collected. | 2564 | and you can detect when it is being collected. |
| 2545 | A full userdata is only equal to itself (under raw equality). | 2565 | A full userdata is only equal to itself (under raw equality). |
| 2546 | | 2566 | |
| 2547 | <p>When Lua collects a full userdata, | 2567 | <p>When Lua collects a full userdata with a <code>gc</code> metamethod, |
| 2548 | it calls the userdata's <code>gc</code> metamethod, if any, | 2568 | Lua calls the metamethod and marks the userdata as finalized. |
| 2549 | and then it frees the userdata's corresponding memory. | 2569 | When that userdata is collected again then |
| | 2570 | Lua frees its corresponding memory. |
| 2550 | | 2571 | |
| 2551 | <p><a name="lua_next"></a> | 2572 | <p><a name="lua_next"></a> |
| 2552 | <hr/><h3><code>lua_next</code></h3> | 2573 | <hr /><h3><code>lua_next</code></h3> |
| 2553 | <pre> | 2574 | <pre> |
| 2554 | int lua_next (lua_State *L, int index); | 2575 | int lua_next (lua_State *L, int index); |
| 2555 | </pre> | 2576 | </pre> |
| 2556 | | 2577 | |
| 2557 | | 2578 | |
| 2558 | <p>Pops a key from the stack, | 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 | (the "next" pair after the given key). | 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 | then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). | 2583 | then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). |
| 2563 | | 2584 | |
| 2564 | <p>A typical traversal looks like this: | 2585 | <p>A typical traversal looks like this: |
| @@ -2581,33 +2602,34 @@ the value at the given index; · 16 unmodified lines |
| 2581 | this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. | 2602 | this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. |
| 2582 | | 2603 | |
| 2583 | <p><a name="lua_Number"></a> | 2604 | <p><a name="lua_Number"></a> |
| 2584 | <hr/><h3><code>lua_Number</code></h3> | 2605 | <hr /><h3><code>lua_Number</code></h3> |
| 2585 | <pre> | 2606 | <pre> |
| 2586 | typedef double lua_Number; | 2607 | typedef double lua_Number; |
| 2587 | </pre> | 2608 | </pre> |
| 2588 | | 2609 | |
| 2589 | | 2610 | |
| 2590 | <p>The type of numbers in Lua. | 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 | <p>Through the configuration file you can change | 2614 | <p>Through the configuration file you can change |
| 2593 | Lua to operate with other type for numbers (e.g., float or long). | 2615 | Lua to operate with other type for numbers (e.g., float or long). |
| 2594 | | 2616 | |
| 2595 | <p><a name="lua_objlen"></a> | 2617 | <p><a name="lua_objlen"></a> |
| 2596 | <hr/><h3><code>lua_objlen</code></h3> | 2618 | <hr /><h3><code>lua_objlen</code></h3> |
| 2597 | <pre> | 2619 | <pre> |
| 2598 | size_t lua_objlen (lua_State *L, int index); | 2620 | size_t lua_objlen (lua_State *L, int index); |
| 2599 | </pre> | 2621 | </pre> |
| 2600 | | 2622 | |
| 2601 | | 2623 | |
| 2602 | <p>Returns the "length" of the value at the given acceptable index: | 2624 | <p>Returns the "length" of the value at the given acceptable index: |
| 2603 | For strings, this is the string length; | 2625 | for strings, this is the string length; |
| 2604 | for tables, this is the result of the length operator (`<code>#</code>´). | 2626 | for tables, this is the result of the length operator (`<code>#</code>´); |
| 2605 | for userdata, this is the size of the block of memory allocated | 2627 | for userdata, this is the size of the block of memory allocated |
| 2606 | for the userdatum. | 2628 | for the userdata; |
| 2607 | For other values, returns 0. | 2629 | for other values, it is 0. |
| 2608 | | 2630 | |
| 2609 | <p><a name="lua_pcall"></a> | 2631 | <p><a name="lua_pcall"></a> |
| 2610 | <hr/><h3><code>lua_pcall</code></h3> | 2632 | <hr /><h3><code>lua_pcall</code></h3> |
| 2611 | <pre> | 2633 | <pre> |
| 2612 | lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); | 2634 | lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); |
| 2613 | </pre> | 2635 | </pre> |
| @@ -2628,13 +2650,14 @@ Like <a href="#lua_call"><code>lua_call</code></a>, · 14 unmodified lines |
| 2628 | and its arguments from the stack. | 2650 | and its arguments from the stack. |
| 2629 | | 2651 | |
| 2630 | <p>If <code>errfunc</code> is 0, | 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 | Otherwise, <code>errfunc</code> is the stack index of an | 2655 | Otherwise, <code>errfunc</code> is the stack index of an |
| 2633 | <em>error handler function</em>. | 2656 | <em>error handler function</em>. |
| 2634 | (In the current implementation, that index cannot be a pseudo-index.) | 2657 | (In the current implementation, that index cannot be a pseudo-index.) |
| 2635 | In case of runtime errors, | 2658 | In case of runtime errors, |
| 2636 | that function will be called with the error message | 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 | <p>Typically, the error handler function is used to add more debug | 2662 | <p>Typically, the error handler function is used to add more debug |
| 2640 | information to the error message, such as a stack traceback. | 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 | </ul> | 2676 | </ul> |
| 2654 | | 2677 | |
| 2655 | <p><a name="lua_pop"></a> | 2678 | <p><a name="lua_pop"></a> |
| 2656 | <hr/><h3><code>lua_pop</code></h3> | 2679 | <hr /><h3><code>lua_pop</code></h3> |
| 2657 | <pre> | 2680 | <pre> |
| 2658 | void lua_pop (lua_State *L, int n); | 2681 | void lua_pop (lua_State *L, int n); |
| 2659 | </pre> | 2682 | </pre> |
| @@ -2662,7 +2685,7 @@ error while running the error handler function. · 2 unmodified lines |
| 2662 | <p>Pops <code>n</code> elements from the stack. | 2685 | <p>Pops <code>n</code> elements from the stack. |
| 2663 | | 2686 | |
| 2664 | <p><a name="lua_pushboolean"></a> | 2687 | <p><a name="lua_pushboolean"></a> |
| 2665 | <hr/><h3><code>lua_pushboolean</code></h3> | 2688 | <hr /><h3><code>lua_pushboolean</code></h3> |
| 2666 | <pre> | 2689 | <pre> |
| 2667 | void lua_pushboolean (lua_State *L, int b); | 2690 | void lua_pushboolean (lua_State *L, int b); |
| 2668 | </pre> | 2691 | </pre> |
| @@ -2671,7 +2694,7 @@ error while running the error handler function. · 2 unmodified lines |
| 2671 | <p>Pushes a boolean value with value <code>b</code> onto the stack. | 2694 | <p>Pushes a boolean value with value <code>b</code> onto the stack. |
| 2672 | | 2695 | |
| 2673 | <p><a name="lua_pushcclosure"></a> | 2696 | <p><a name="lua_pushcclosure"></a> |
| 2674 | <hr/><h3><code>lua_pushcclosure</code></h3> | 2697 | <hr /><h3><code>lua_pushcclosure</code></h3> |
| 2675 | <pre> | 2698 | <pre> |
| 2676 | void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); | 2699 | void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); |
| 2677 | </pre> | 2700 | </pre> |
| @@ -2686,14 +2709,14 @@ these values are then accessible to the function whenever it is called. · 8 unmodified lines |
| 2686 | To associate values with a C function, | 2709 | To associate values with a C function, |
| 2687 | first these values should be pushed onto the stack | 2710 | first these values should be pushed onto the stack |
| 2688 | (when there are multiple values, the first value is pushed first). | 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> | 2712 | Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> |
| 2690 | is used to create and push the C function onto the stack, | 2713 | is called to create and push the C function onto the stack, |
| 2691 | with the argument <code>n</code> telling how many values should be | 2714 | with the argument <code>n</code> telling how many values should be |
| 2692 | associated with the function. | 2715 | associated with the function. |
| 2693 | <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. | 2716 | <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. |
| 2694 | | 2717 | |
| 2695 | <p><a name="lua_pushcfunction"></a> | 2718 | <p><a name="lua_pushcfunction"></a> |
| 2696 | <hr/><h3><code>lua_pushcfunction</code></h3> | 2719 | <hr /><h3><code>lua_pushcfunction</code></h3> |
| 2697 | <pre> | 2720 | <pre> |
| 2698 | void lua_pushcfunction (lua_State *L, lua_CFunction f); | 2721 | void lua_pushcfunction (lua_State *L, lua_CFunction f); |
| 2699 | </pre> | 2722 | </pre> |
| @@ -2703,7 +2726,7 @@ associated with the function. · 3 unmodified lines |
| 2703 | This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. | 2726 | This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. |
| 2704 | | 2727 | |
| 2705 | <p><a name="lua_pushfstring"></a> | 2728 | <p><a name="lua_pushfstring"></a> |
| 2706 | <hr/><h3><code>lua_pushfstring</code></h3> | 2729 | <hr /><h3><code>lua_pushfstring</code></h3> |
| 2707 | <pre> | 2730 | <pre> |
| 2708 | const char *lua_pushfstring (lua_State *L, const char *fmt, ...); | 2731 | const char *lua_pushfstring (lua_State *L, const char *fmt, ...); |
| 2709 | </pre> | 2732 | </pre> |
| @@ -2711,15 +2734,15 @@ This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. · 1 unmodified line |
| 2711 | | 2734 | |
| 2712 | <p>Pushes onto the stack a formatted string | 2735 | <p>Pushes onto the stack a formatted string |
| 2713 | and returns a pointer to that string. | 2736 | and returns a pointer to that string. |
| 2714 | It is similar to the C function <code>sprintf</code> | 2737 | It is similar to the C function <code>sprintf</code>, |
| 2715 | but with some important differences: | 2738 | but has some important differences: |
| 2716 | <ul> | 2739 | <ul> |
| 2717 | <li> You do not have to allocate the space for the result: | 2740 | <li> You do not have to allocate the space for the result: |
| 2718 | The result is a Lua string and Lua takes care of memory allocation | 2741 | The result is a Lua string and Lua takes care of memory allocation |
| 2719 | (and deallocation, through garbage collection). | 2742 | (and deallocation, through garbage collection). |
| 2720 | <li> The conversion specifiers are quite restricted. | 2743 | <li> The conversion specifiers are quite restricted. |
| 2721 | There are no flags, widths, or precisions. | 2744 | There are no flags, widths, or precisions. |
| 2722 | The conversion specifiers can be simply | 2745 | The conversion specifiers can only be |
| 2723 | `<code>%%</code>´ (inserts a `<code>%</code>´ in the string), | 2746 | `<code>%%</code>´ (inserts a `<code>%</code>´ in the string), |
| 2724 | `<code>%s</code>´ (inserts a zero-terminated string, with no size restrictions), | 2747 | `<code>%s</code>´ (inserts a zero-terminated string, with no size restrictions), |
| 2725 | `<code>%f</code>´ (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), | 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 | </ul> | 2752 | </ul> |
| 2730 | | 2753 | |
| 2731 | <p><a name="lua_pushinteger"></a> | 2754 | <p><a name="lua_pushinteger"></a> |
| 2732 | <hr/><h3><code>lua_pushinteger</code></h3> | 2755 | <hr /><h3><code>lua_pushinteger</code></h3> |
| 2733 | <pre> | 2756 | <pre> |
| 2734 | void lua_pushinteger (lua_State *L, lua_Integer n); | 2757 | void lua_pushinteger (lua_State *L, lua_Integer n); |
| 2735 | </pre> | 2758 | </pre> |
| @@ -2738,7 +2761,7 @@ The conversion specifiers can be simply · 2 unmodified lines |
| 2738 | <p>Pushes a number with value <code>n</code> onto the stack. | 2761 | <p>Pushes a number with value <code>n</code> onto the stack. |
| 2739 | | 2762 | |
| 2740 | <p><a name="lua_pushlightuserdata"></a> | 2763 | <p><a name="lua_pushlightuserdata"></a> |
| 2741 | <hr/><h3><code>lua_pushlightuserdata</code></h3> | 2764 | <hr /><h3><code>lua_pushlightuserdata</code></h3> |
| 2742 | <pre> | 2765 | <pre> |
| 2743 | void lua_pushlightuserdata (lua_State *L, void *p); | 2766 | void lua_pushlightuserdata (lua_State *L, void *p); |
| 2744 | </pre> | 2767 | </pre> |
| @@ -2755,7 +2778,7 @@ A light userdata is equal to "any" · 10 unmodified lines |
| 2755 | light userdata with the same C address. | 2778 | light userdata with the same C address. |
| 2756 | | 2779 | |
| 2757 | <p><a name="lua_pushlstring"></a> | 2780 | <p><a name="lua_pushlstring"></a> |
| 2758 | <hr/><h3><code>lua_pushlstring</code></h3> | 2781 | <hr /><h3><code>lua_pushlstring</code></h3> |
| 2759 | <pre> | 2782 | <pre> |
| 2760 | void lua_pushlstring (lua_State *L, const char *s, size_t len); | 2783 | void lua_pushlstring (lua_State *L, const char *s, size_t len); |
| 2761 | </pre> | 2784 | </pre> |
| @@ -2766,9 +2789,10 @@ onto the stack. · 4 unmodified lines |
| 2766 | Lua makes (or reuses) an internal copy of the given string, | 2789 | Lua makes (or reuses) an internal copy of the given string, |
| 2767 | so the memory at <code>s</code> can be freed or reused immediately after | 2790 | so the memory at <code>s</code> can be freed or reused immediately after |
| 2768 | the function returns. | 2791 | the function returns. |
| | 2792 | The string can contain embedded zeros. |
| 2769 | | 2793 | |
| 2770 | <p><a name="lua_pushnil"></a> | 2794 | <p><a name="lua_pushnil"></a> |
| 2771 | <hr/><h3><code>lua_pushnil</code></h3> | 2795 | <hr /><h3><code>lua_pushnil</code></h3> |
| 2772 | <pre> | 2796 | <pre> |
| 2773 | void lua_pushnil (lua_State *L); | 2797 | void lua_pushnil (lua_State *L); |
| 2774 | </pre> | 2798 | </pre> |
| @@ -2777,7 +2801,7 @@ the function returns. · 2 unmodified lines |
| 2777 | <p>Pushes a nil value onto the stack. | 2801 | <p>Pushes a nil value onto the stack. |
| 2778 | | 2802 | |
| 2779 | <p><a name="lua_pushnumber"></a> | 2803 | <p><a name="lua_pushnumber"></a> |
| 2780 | <hr/><h3><code>lua_pushnumber</code></h3> | 2804 | <hr /><h3><code>lua_pushnumber</code></h3> |
| 2781 | <pre> | 2805 | <pre> |
| 2782 | void lua_pushnumber (lua_State *L, lua_Number n); | 2806 | void lua_pushnumber (lua_State *L, lua_Number n); |
| 2783 | </pre> | 2807 | </pre> |
| @@ -2786,7 +2810,7 @@ the function returns. · 2 unmodified lines |
| 2786 | <p>Pushes a number with value <code>n</code> onto the stack. | 2810 | <p>Pushes a number with value <code>n</code> onto the stack. |
| 2787 | | 2811 | |
| 2788 | <p><a name="lua_pushstring"></a> | 2812 | <p><a name="lua_pushstring"></a> |
| 2789 | <hr/><h3><code>lua_pushstring</code></h3> | 2813 | <hr /><h3><code>lua_pushstring</code></h3> |
| 2790 | <pre> | 2814 | <pre> |
| 2791 | void lua_pushstring (lua_State *L, const char *s); | 2815 | void lua_pushstring (lua_State *L, const char *s); |
| 2792 | </pre> | 2816 | </pre> |
| @@ -2797,9 +2821,20 @@ onto the stack. · 4 unmodified lines |
| 2797 | Lua makes (or reuses) an internal copy of the given string, | 2821 | Lua makes (or reuses) an internal copy of the given string, |
| 2798 | so the memory at <code>s</code> can be freed or reused immediately after | 2822 | so the memory at <code>s</code> can be freed or reused immediately after |
| 2799 | the function returns. | 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 | <p><a name="lua_pushvalue"></a> | 2836 | <p><a name="lua_pushvalue"></a> |
| 2802 | <hr/><h3><code>lua_pushvalue</code></h3> | 2837 | <hr /><h3><code>lua_pushvalue</code></h3> |
| 2803 | <pre> | 2838 | <pre> |
| 2804 | void lua_pushvalue (lua_State *L, int index); | 2839 | void lua_pushvalue (lua_State *L, int index); |
| 2805 | </pre> | 2840 | </pre> |
| @@ -2809,7 +2844,7 @@ the function returns. · 3 unmodified lines |
| 2809 | onto the stack. | 2844 | onto the stack. |
| 2810 | | 2845 | |
| 2811 | <p><a name="lua_pushvfstring"></a> | 2846 | <p><a name="lua_pushvfstring"></a> |
| 2812 | <hr/><h3><code>lua_pushvfstring</code></h3> | 2847 | <hr /><h3><code>lua_pushvfstring</code></h3> |
| 2813 | <pre> | 2848 | <pre> |
| 2814 | const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); | 2849 | const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); |
| 2815 | </pre> | 2850 | </pre> |
| @@ -2819,7 +2854,7 @@ onto the stack. · 3 unmodified lines |
| 2819 | instead of a variable number of arguments. | 2854 | instead of a variable number of arguments. |
| 2820 | | 2855 | |
| 2821 | <p><a name="lua_rawequal"></a> | 2856 | <p><a name="lua_rawequal"></a> |
| 2822 | <hr/><h3><code>lua_rawequal</code></h3> | 2857 | <hr /><h3><code>lua_rawequal</code></h3> |
| 2823 | <pre> | 2858 | <pre> |
| 2824 | int lua_rawequal (lua_State *L, int index1, int index2); | 2859 | int lua_rawequal (lua_State *L, int index1, int index2); |
| 2825 | </pre> | 2860 | </pre> |
| @@ -2832,17 +2867,17 @@ Otherwise returns 0. · 6 unmodified lines |
| 2832 | Also returns 0 if any of the indices are non valid. | 2867 | Also returns 0 if any of the indices are non valid. |
| 2833 | | 2868 | |
| 2834 | <p><a name="lua_rawget"></a> | 2869 | <p><a name="lua_rawget"></a> |
| 2835 | <hr/><h3><code>lua_rawget</code></h3> | 2870 | <hr /><h3><code>lua_rawget</code></h3> |
| 2836 | <pre> | 2871 | <pre> |
| 2837 | void lua_rawget (lua_State *L, int index); | 2872 | void lua_rawget (lua_State *L, int index); |
| 2838 | </pre> | 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 | (i.e., without metamethods). | 2877 | (i.e., without metamethods). |
| 2843 | | 2878 | |
| 2844 | <p><a name="lua_rawgeti"></a> | 2879 | <p><a name="lua_rawgeti"></a> |
| 2845 | <hr/><h3><code>lua_rawgeti</code></h3> | 2880 | <hr /><h3><code>lua_rawgeti</code></h3> |
| 2846 | <pre> | 2881 | <pre> |
| 2847 | void lua_rawgeti (lua_State *L, int index, int n); | 2882 | void lua_rawgeti (lua_State *L, int index, int n); |
| 2848 | </pre> | 2883 | </pre> |
| @@ -2850,36 +2885,36 @@ Also returns 0 if any of the indices are non valid. · 1 unmodified line |
| 2850 | | 2885 | |
| 2851 | <p>Pushes onto the stack the value <code>t[n]</code>, | 2886 | <p>Pushes onto the stack the value <code>t[n]</code>, |
| 2852 | where <code>t</code> is the value at the given valid index <code>index</code>. | 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 | that is, it does not invoke metamethods. | 2889 | that is, it does not invoke metamethods. |
| 2855 | | 2890 | |
| 2856 | <p><a name="lua_rawset"></a> | 2891 | <p><a name="lua_rawset"></a> |
| 2857 | <hr/><h3><code>lua_rawset</code></h3> | 2892 | <hr /><h3><code>lua_rawset</code></h3> |
| 2858 | <pre> | 2893 | <pre> |
| 2859 | void lua_rawset (lua_State *L, int index); | 2894 | void lua_rawset (lua_State *L, int index); |
| 2860 | </pre> | 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 | (i.e., without metamethods). | 2899 | (i.e., without metamethods). |
| 2865 | | 2900 | |
| 2866 | <p><a name="lua_rawseti"></a> | 2901 | <p><a name="lua_rawseti"></a> |
| 2867 | <hr/><h3><code>lua_rawseti</code></h3> | 2902 | <hr /><h3><code>lua_rawseti</code></h3> |
| 2868 | <pre> | 2903 | <pre> |
| 2869 | void lua_rawseti (lua_State *L, int index, int n); | 2904 | void lua_rawseti (lua_State *L, int index, int n); |
| 2870 | </pre> | 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 | where <code>t</code> is the value at the given valid index <code>index</code> | 2909 | where <code>t</code> is the value at the given valid index <code>index</code> |
| 2875 | and <code>v</code> is the value at the top of the stack, | 2910 | and <code>v</code> is the value at the top of the stack, |
| 2876 | | 2911 | |
| 2877 | <p>This function pops the value from the stack. | 2912 | <p>This function pops the value from the stack. |
| 2878 | The assignment is raw, | 2913 | The assignment is raw; |
| 2879 | that is, it does not invoke metamethods. | 2914 | that is, it does not invoke metamethods. |
| 2880 | | 2915 | |
| 2881 | <p><a name="lua_Reader"></a> | 2916 | <p><a name="lua_Reader"></a> |
| 2882 | <hr/><h3><code>lua_Reader</code></h3> | 2917 | <hr /><h3><code>lua_Reader</code></h3> |
| 2883 | <pre> | 2918 | <pre> |
| 2884 | typedef const char * (*lua_Reader) | 2919 | typedef const char * (*lua_Reader) |
| 2885 | (lua_State *L, void *data, size_t *size); | 2920 | (lua_State *L, void *data, size_t *size); |
| @@ -2894,11 +2929,12 @@ passing along its <code>data</code> parameter. · 8 unmodified lines |
| 2894 | The reader must return a pointer to a block of memory | 2929 | The reader must return a pointer to a block of memory |
| 2895 | with a new piece of the chunk | 2930 | with a new piece of the chunk |
| 2896 | and set <code>size</code> to the block size. | 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 | The reader function may return pieces of any size greater than zero. | 2934 | The reader function may return pieces of any size greater than zero. |
| 2899 | | 2935 | |
| 2900 | <p><a name="lua_remove"></a> | 2936 | <p><a name="lua_remove"></a> |
| 2901 | <hr/><h3><code>lua_remove</code></h3> | 2937 | <hr /><h3><code>lua_remove</code></h3> |
| 2902 | <pre> | 2938 | <pre> |
| 2903 | void lua_remove (lua_State *L, int index); | 2939 | void lua_remove (lua_State *L, int index); |
| 2904 | </pre> | 2940 | </pre> |
| @@ -2910,7 +2946,7 @@ Cannot be called with a pseudo-index, · 5 unmodified lines |
| 2910 | because a pseudo-index is not an actual stack position. | 2946 | because a pseudo-index is not an actual stack position. |
| 2911 | | 2947 | |
| 2912 | <p><a name="lua_replace"></a> | 2948 | <p><a name="lua_replace"></a> |
| 2913 | <hr/><h3><code>lua_replace</code></h3> | 2949 | <hr /><h3><code>lua_replace</code></h3> |
| 2914 | <pre> | 2950 | <pre> |
| 2915 | void lua_replace (lua_State *L, int index); | 2951 | void lua_replace (lua_State *L, int index); |
| 2916 | </pre> | 2952 | </pre> |
| @@ -2921,7 +2957,7 @@ without shifting any element · 4 unmodified lines |
| 2921 | (therefore replacing the value at the given position). | 2957 | (therefore replacing the value at the given position). |
| 2922 | | 2958 | |
| 2923 | <p><a name="lua_resume"></a> | 2959 | <p><a name="lua_resume"></a> |
| 2924 | <hr/><h3><code>lua_resume</code></h3> | 2960 | <hr /><h3><code>lua_resume</code></h3> |
| 2925 | <pre> | 2961 | <pre> |
| 2926 | int lua_resume (lua_State *L, int narg); | 2962 | int lua_resume (lua_State *L, int narg); |
| 2927 | </pre> | 2963 | </pre> |
| @@ -2931,7 +2967,7 @@ without shifting any element · 3 unmodified lines |
| 2931 | | 2967 | |
| 2932 | <p>To start a coroutine, you first create a new thread | 2968 | <p>To start a coroutine, you first create a new thread |
| 2933 | (see <a href="#lua_newthread"><code>lua_newthread</code></a>); | 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 | then you call <a href="#lua_resume"><code>lua_resume</code></a>, | 2971 | then you call <a href="#lua_resume"><code>lua_resume</code></a>, |
| 2936 | with <code>narg</code> being the number of arguments. | 2972 | with <code>narg</code> being the number of arguments. |
| 2937 | This call returns when the coroutine suspends or finishes its execution. | 2973 | This call returns when the coroutine suspends or finishes its execution. |
| @@ -2944,14 +2980,14 @@ without errors, · 6 unmodified lines |
| 2944 | or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). | 2980 | or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). |
| 2945 | In case of errors, | 2981 | In case of errors, |
| 2946 | the stack is not unwound, | 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 | The error message is on the top of the stack. | 2984 | The error message is on the top of the stack. |
| 2949 | To restart a coroutine, you put on its stack only the values to | 2985 | To restart a coroutine, you put on its stack only the values to |
| 2950 | be passed as results from <code>yield</code>, | 2986 | be passed as results from <code>yield</code>, |
| 2951 | and then call <a href="#lua_resume"><code>lua_resume</code></a>. | 2987 | and then call <a href="#lua_resume"><code>lua_resume</code></a>. |
| 2952 | | 2988 | |
| 2953 | <p><a name="lua_setallocf"></a> | 2989 | <p><a name="lua_setallocf"></a> |
| 2954 | <hr/><h3><code>lua_setallocf</code></h3> | 2990 | <hr /><h3><code>lua_setallocf</code></h3> |
| 2955 | <pre> | 2991 | <pre> |
| 2956 | void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); | 2992 | void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); |
| 2957 | </pre> | 2993 | </pre> |
| @@ -2961,7 +2997,7 @@ and then call <a href="#lua_resume"><code>lua_resume</code></a>. · 3 unmodified lines |
| 2961 | with user data <code>ud</code>. | 2997 | with user data <code>ud</code>. |
| 2962 | | 2998 | |
| 2963 | <p><a name="lua_setfenv"></a> | 2999 | <p><a name="lua_setfenv"></a> |
| 2964 | <hr/><h3><code>lua_setfenv</code></h3> | 3000 | <hr /><h3><code>lua_setfenv</code></h3> |
| 2965 | <pre> | 3001 | <pre> |
| 2966 | int lua_setfenv (lua_State *L, int index); | 3002 | int lua_setfenv (lua_State *L, int index); |
| 2967 | </pre> | 3003 | </pre> |
| @@ -2971,10 +3007,11 @@ with user data <code>ud</code>. · 3 unmodified lines |
| 2971 | the new environment for the value at the given index. | 3007 | the new environment for the value at the given index. |
| 2972 | If the value at the given index is | 3008 | If the value at the given index is |
| 2973 | neither a function nor a thread nor a userdata, | 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 | <p><a name="lua_setfield"></a> | 3013 | <p><a name="lua_setfield"></a> |
| 2977 | <hr/><h3><code>lua_setfield</code></h3> | 3014 | <hr /><h3><code>lua_setfield</code></h3> |
| 2978 | <pre> | 3015 | <pre> |
| 2979 | void lua_setfield (lua_State *L, int index, const char *k); | 3016 | void lua_setfield (lua_State *L, int index, const char *k); |
| 2980 | </pre> | 3017 | </pre> |
| @@ -2989,7 +3026,7 @@ As in Lua, this function may trigger a metamethod · 8 unmodified lines |
| 2989 | for the "newindex" event (see <a href="#metatable">2.8</a>). | 3026 | for the "newindex" event (see <a href="#metatable">2.8</a>). |
| 2990 | | 3027 | |
| 2991 | <p><a name="lua_setmetatable"></a> | 3028 | <p><a name="lua_setmetatable"></a> |
| 2992 | <hr/><h3><code>lua_setmetatable</code></h3> | 3029 | <hr /><h3><code>lua_setmetatable</code></h3> |
| 2993 | <pre> | 3030 | <pre> |
| 2994 | int lua_setmetatable (lua_State *L, int index); | 3031 | int lua_setmetatable (lua_State *L, int index); |
| 2995 | </pre> | 3032 | </pre> |
| @@ -3000,7 +3037,7 @@ sets it as the new metatable for the value at the given · 4 unmodified lines |
| 3000 | acceptable index. | 3037 | acceptable index. |
| 3001 | | 3038 | |
| 3002 | <p><a name="lua_settable"></a> | 3039 | <p><a name="lua_settable"></a> |
| 3003 | <hr/><h3><code>lua_settable</code></h3> | 3040 | <hr /><h3><code>lua_settable</code></h3> |
| 3004 | <pre> | 3041 | <pre> |
| 3005 | void lua_settable (lua_State *L, int index); | 3042 | void lua_settable (lua_State *L, int index); |
| 3006 | </pre> | 3043 | </pre> |
| @@ -3016,7 +3053,7 @@ As in Lua, this function may trigger a metamethod · 9 unmodified lines |
| 3016 | for the "newindex" event (see <a href="#metatable">2.8</a>). | 3053 | for the "newindex" event (see <a href="#metatable">2.8</a>). |
| 3017 | | 3054 | |
| 3018 | <p><a name="lua_settop"></a> | 3055 | <p><a name="lua_settop"></a> |
| 3019 | <hr/><h3><code>lua_settop</code></h3> | 3056 | <hr /><h3><code>lua_settop</code></h3> |
| 3020 | <pre> | 3057 | <pre> |
| 3021 | void lua_settop (lua_State *L, int index); | 3058 | void lua_settop (lua_State *L, int index); |
| 3022 | </pre> | 3059 | </pre> |
| @@ -3029,7 +3066,7 @@ then the new elements are filled with <b>nil</b>. · 6 unmodified lines |
| 3029 | If <code>index</code> is 0, then all stack elements are removed. | 3066 | If <code>index</code> is 0, then all stack elements are removed. |
| 3030 | | 3067 | |
| 3031 | <p><a name="lua_State"></a> | 3068 | <p><a name="lua_State"></a> |
| 3032 | <hr/><h3><code>lua_State</code></h3> | 3069 | <hr /><h3><code>lua_State</code></h3> |
| 3033 | <pre> | 3070 | <pre> |
| 3034 | typedef struct lua_State lua_State; | 3071 | typedef struct lua_State lua_State; |
| 3035 | </pre> | 3072 | </pre> |
| @@ -3044,8 +3081,21 @@ All information about a state is kept in this structure. · 8 unmodified lines |
| 3044 | every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, | 3081 | every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, |
| 3045 | which creates a Lua state from scratch. | 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 | <p><a name="lua_toboolean"></a> | 3097 | <p><a name="lua_toboolean"></a> |
| 3048 | <hr/><h3><code>lua_toboolean</code></h3> | 3098 | <hr /><h3><code>lua_toboolean</code></h3> |
| 3049 | <pre> | 3099 | <pre> |
| 3050 | int lua_toboolean (lua_State *L, int index); | 3100 | int lua_toboolean (lua_State *L, int index); |
| 3051 | </pre> | 3101 | </pre> |
| @@ -3058,11 +3108,11 @@ Like all tests in Lua, · 6 unmodified lines |
| 3058 | different from <b>false</b> and <b>nil</b>; | 3108 | different from <b>false</b> and <b>nil</b>; |
| 3059 | otherwise it returns 0. | 3109 | otherwise it returns 0. |
| 3060 | It also returns 0 when called with a non-valid index. | 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 | use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) | 3112 | use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) |
| 3063 | | 3113 | |
| 3064 | <p><a name="lua_tocfunction"></a> | 3114 | <p><a name="lua_tocfunction"></a> |
| 3065 | <hr/><h3><code>lua_tocfunction</code></h3> | 3115 | <hr /><h3><code>lua_tocfunction</code></h3> |
| 3066 | <pre> | 3116 | <pre> |
| 3067 | lua_CFunction lua_tocfunction (lua_State *L, int index); | 3117 | lua_CFunction lua_tocfunction (lua_State *L, int index); |
| 3068 | </pre> | 3118 | </pre> |
| @@ -3073,7 +3123,7 @@ That value must be a C function; · 4 unmodified lines |
| 3073 | otherwise, returns <code>NULL</code>. | 3123 | otherwise, returns <code>NULL</code>. |
| 3074 | | 3124 | |
| 3075 | <p><a name="lua_tointeger"></a> | 3125 | <p><a name="lua_tointeger"></a> |
| 3076 | <hr/><h3><code>lua_tointeger</code></h3> | 3126 | <hr /><h3><code>lua_tointeger</code></h3> |
| 3077 | <pre> | 3127 | <pre> |
| 3078 | lua_Integer lua_tointeger (lua_State *L, int idx); | 3128 | lua_Integer lua_tointeger (lua_State *L, int idx); |
| 3079 | </pre> | 3129 | </pre> |
| @@ -3089,7 +3139,7 @@ otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. · 9 unmodified lines |
| 3089 | it is truncated in some non-specified way. | 3139 | it is truncated in some non-specified way. |
| 3090 | | 3140 | |
| 3091 | <p><a name="lua_tolstring"></a> | 3141 | <p><a name="lua_tolstring"></a> |
| 3092 | <hr/><h3><code>lua_tolstring</code></h3> | 3142 | <hr /><h3><code>lua_tolstring</code></h3> |
| 3093 | <pre> | 3143 | <pre> |
| 3094 | const char *lua_tolstring (lua_State *L, int index, size_t *len); | 3144 | const char *lua_tolstring (lua_State *L, int index, size_t *len); |
| 3095 | </pre> | 3145 | </pre> |
| @@ -3105,11 +3155,11 @@ If the value is a number, · 9 unmodified lines |
| 3105 | then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also | 3155 | then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also |
| 3106 | <em>changes the actual value in the stack to a string</em>. | 3156 | <em>changes the actual value in the stack to a string</em>. |
| 3107 | (This change confuses <a href="#lua_next"><code>lua_next</code></a> | 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 | <p><a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer | 3160 | <p><a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer |
| 3111 | to a string inside the Lua state. | 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 | after its last character (as in C), | 3163 | after its last character (as in C), |
| 3114 | but may contain other zeros in its body. | 3164 | but may contain other zeros in its body. |
| 3115 | Because Lua has garbage collection, | 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 | will be valid after the corresponding value is removed from the stack. | 3167 | will be valid after the corresponding value is removed from the stack. |
| 3118 | | 3168 | |
| 3119 | <p><a name="lua_tonumber"></a> | 3169 | <p><a name="lua_tonumber"></a> |
| 3120 | <hr/><h3><code>lua_tonumber</code></h3> | 3170 | <hr /><h3><code>lua_tonumber</code></h3> |
| 3121 | <pre> | 3171 | <pre> |
| 3122 | lua_Number lua_tonumber (lua_State *L, int index); | 3172 | lua_Number lua_tonumber (lua_State *L, int index); |
| 3123 | </pre> | 3173 | </pre> |
| @@ -3130,23 +3180,23 @@ The Lua value must be a number or a string convertible to number · 6 unmodified lines |
| 3130 | otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. | 3180 | otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. |
| 3131 | | 3181 | |
| 3132 | <p><a name="lua_topointer"></a> | 3182 | <p><a name="lua_topointer"></a> |
| 3133 | <hr/><h3><code>lua_topointer</code></h3> | 3183 | <hr /><h3><code>lua_topointer</code></h3> |
| 3134 | <pre> | 3184 | <pre> |
| 3135 | const void *lua_topointer (lua_State *L, int index); | 3185 | const void *lua_topointer (lua_State *L, int index); |
| 3136 | </pre> | 3186 | </pre> |
| 3137 | | 3187 | |
| 3138 | | 3188 | |
| 3139 | <p>Converts the value at the given acceptable index to a generic | 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 | The value may be a userdata, a table, a thread, or a function; | 3191 | The value may be a userdata, a table, a thread, or a function; |
| 3142 | otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. | 3192 | otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. |
| 3143 | Lua ensures that different objects return different pointers. | 3193 | Lua ensures that different objects return different pointers. |
| 3144 | There is no direct way to convert the pointer back to its original value. | 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 | <p><a name="lua_tostring"></a> | 3198 | <p><a name="lua_tostring"></a> |
| 3149 | <hr/><h3><code>lua_tostring</code></h3> | 3199 | <hr /><h3><code>lua_tostring</code></h3> |
| 3150 | <pre> | 3200 | <pre> |
| 3151 | const char *lua_tostring (lua_State *L, int index); | 3201 | const char *lua_tostring (lua_State *L, int index); |
| 3152 | </pre> | 3202 | </pre> |
| @@ -3155,19 +3205,19 @@ There is no direct way to convert the pointer back to its original value. · 2 unmodified lines |
| 3155 | <p>Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. | 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 | <p><a name="lua_tothread"></a> | 3207 | <p><a name="lua_tothread"></a> |
| 3158 | <hr/><h3><code>lua_tothread</code></h3> | 3208 | <hr /><h3><code>lua_tothread</code></h3> |
| 3159 | <pre> | 3209 | <pre> |
| 3160 | lua_State *lua_tothread (lua_State *L, int index); | 3210 | lua_State *lua_tothread (lua_State *L, int index); |
| 3161 | </pre> | 3211 | </pre> |
| 3162 | | 3212 | |
| 3163 | | 3213 | |
| 3164 | <p>Converts the value at the given acceptable index to a Lua thread | 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 | This value must be a thread; | 3216 | This value must be a thread; |
| 3167 | otherwise, the function returns <code>NULL</code>. | 3217 | otherwise, the function returns <code>NULL</code>. |
| 3168 | | 3218 | |
| 3169 | <p><a name="lua_touserdata"></a> | 3219 | <p><a name="lua_touserdata"></a> |
| 3170 | <hr/><h3><code>lua_touserdata</code></h3> | 3220 | <hr /><h3><code>lua_touserdata</code></h3> |
| 3171 | <pre> | 3221 | <pre> |
| 3172 | void *lua_touserdata (lua_State *L, int index); | 3222 | void *lua_touserdata (lua_State *L, int index); |
| 3173 | </pre> | 3223 | </pre> |
| @@ -3180,7 +3230,7 @@ returns its pointer. · 6 unmodified lines |
| 3180 | Otherwise, returns <code>NULL</code>. | 3230 | Otherwise, returns <code>NULL</code>. |
| 3181 | | 3231 | |
| 3182 | <p><a name="lua_type"></a> | 3232 | <p><a name="lua_type"></a> |
| 3183 | <hr/><h3><code>lua_type</code></h3> | 3233 | <hr /><h3><code>lua_type</code></h3> |
| 3184 | <pre> | 3234 | <pre> |
| 3185 | int lua_type (lua_State *L, int index); | 3235 | int lua_type (lua_State *L, int index); |
| 3186 | </pre> | 3236 | </pre> |
| @@ -3199,10 +3249,21 @@ defined in <code>lua.h</code>: · 12 unmodified lines |
| 3199 | <code>LUA_TFUNCTION</code>, | 3249 | <code>LUA_TFUNCTION</code>, |
| 3200 | <code>LUA_TUSERDATA</code>, | 3250 | <code>LUA_TUSERDATA</code>, |
| 3201 | <code>LUA_TTHREAD</code>, | 3251 | <code>LUA_TTHREAD</code>, |
| | 3252 | and |
| 3202 | <code>LUA_TLIGHTUSERDATA</code>. | 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 | <p><a name="lua_Writer"></a> | 3265 | <p><a name="lua_Writer"></a> |
| 3205 | <hr/><h3><code>lua_Writer</code></h3> | 3266 | <hr /><h3><code>lua_Writer</code></h3> |
| 3206 | <pre> | 3267 | <pre> |
| 3207 | typedef int (*lua_Writer) | 3268 | typedef int (*lua_Writer) |
| 3208 | (lua_State *L, const void* p, size_t sz, void* ud); | 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 | calling the writer again. | 3284 | calling the writer again. |
| 3224 | | 3285 | |
| 3225 | <p><a name="lua_xmove"></a> | 3286 | <p><a name="lua_xmove"></a> |
| 3226 | <hr/><h3><code>lua_xmove</code></h3> | 3287 | <hr /><h3><code>lua_xmove</code></h3> |
| 3227 | <pre> | 3288 | <pre> |
| 3228 | void lua_xmove (lua_State *from, lua_State *to, int n); | 3289 | void lua_xmove (lua_State *from, lua_State *to, int n); |
| 3229 | </pre> | 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 | <p>This function pops <code>n</code> values from the stack <code>from</code>, | 3295 | <p>This function pops <code>n</code> values from the stack <code>from</code>, |
| 3235 | and pushes them into the stack <code>to</code>. | 3296 | and pushes them into the stack <code>to</code>. |
| 3236 | | 3297 | |
| 3237 | <p><a name="lua_yield"></a> | 3298 | <p><a name="lua_yield"></a> |
| 3238 | <hr/><h3><code>lua_yield</code></h3> | 3299 | <hr /><h3><code>lua_yield</code></h3> |
| 3239 | <pre> | 3300 | <pre> |
| 3240 | int lua_yield (lua_State *L, int nresults); | 3301 | int lua_yield (lua_State *L, int nresults); |
| 3241 | </pre> | 3302 | </pre> |
| @@ -3243,7 +3304,7 @@ and pushes them into the stack <code>to</code>. · 1 unmodified line |
| 3243 | | 3304 | |
| 3244 | <p>Yields a coroutine. | 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 | return expression of a C function, as follows: | 3308 | return expression of a C function, as follows: |
| 3248 | <pre> | 3309 | <pre> |
| 3249 | return lua_yield (L, nresults); | 3310 | return lua_yield (L, nresults); |
| @@ -3265,20 +3326,19 @@ kinds of debuggers, profilers, and other tools · 15 unmodified lines |
| 3265 | that need "inside information" from the interpreter. | 3326 | that need "inside information" from the interpreter. |
| 3266 | | 3327 | |
| 3267 | <p><a name="lua_Debug"></a> | 3328 | <p><a name="lua_Debug"></a> |
| 3268 | <hr/><h3><code>lua_Debug</code></h3> | 3329 | <hr /><h3><code>lua_Debug</code></h3> |
| 3269 | <pre> | 3330 | <pre> |
| 3270 | typedef struct lua_Debug { | 3331 | typedef struct lua_Debug { |
| 3271 | int event; | 3332 | int event; |
| 3272 | const char *name; /* (n) */ | 3333 | const char *name; /* (n) */ |
| 3273 | const char *namewhat; /* (n) */ | 3334 | const char *namewhat; /* (n) */ |
| 3274 | const char *what; /* (S) */ | 3335 | const char *what; /* (S) */ |
| 3275 | const char *source; /* (S) */ | 3336 | const char *source; /* (S) */ |
| 3276 | int currentline; /* (l) */ | 3337 | int currentline; /* (l) */ |
| 3277 | int nups; /* (u) number of upvalues */ | 3338 | int nups; /* (u) number of upvalues */ |
| 3278 | int linedefined; /* (S) */ | 3339 | int linedefined; /* (S) */ |
| 3279 | int lastlinedefined; /* (S) */ | 3340 | int lastlinedefined; /* (S) */ |
| 3280 | char short_src[LUA_IDSIZE]; /* (S) */ | 3341 | char short_src[LUA_IDSIZE]; /* (S) */ |
| 3281 | | | |
| 3282 | /* private part */ | 3342 | /* private part */ |
| 3283 | ... | 3343 | ... |
| 3284 | } lua_Debug; | 3344 | } lua_Debug; |
| @@ -3295,36 +3355,37 @@ call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. · 10 unmodified lines |
| 3295 | | 3355 | |
| 3296 | <p>The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: | 3356 | <p>The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: |
| 3297 | <ul> | 3357 | <ul> |
| 3298 | <li><b><code>source</code></b> | 3358 | <li><b><code>source</code></b> --- |
| 3299 | If the function was defined in a string, | 3359 | If the function was defined in a string, |
| 3300 | then <code>source</code> is that string. | 3360 | then <code>source</code> is that string. |
| 3301 | If the function was defined in a file, | 3361 | If the function was defined in a file, |
| 3302 | then <code>source</code> starts with a `<code>@</code>´ followed by the file name. | 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> | 3364 | <p><li><b><code>short_src</code></b> --- |
| 3305 | A "printable" version of <code>source</code>, to be used in error messages. | 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 | the line number where the definition of the function starts. | 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 | the line number where the definition of the function ends. | 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, | 3373 | <p><li><b><code>what</code></b> --- |
| 3314 | <code>"C"</code> if this is a C function, | 3374 | the string <code>"Lua"</code> if the function is a Lua function, |
| 3315 | <code>"main"</code> if this is the main part of a chunk, | 3375 | <code>"C"</code> if it is a C function, |
| 3316 | and <code>"tail"</code> if this was a function that did a tail call. | 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 | In the latter case, | 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 | the current line where the given function is executing. | 3382 | the current line where the given function is executing. |
| 3322 | When no line information is available, | 3383 | When no line information is available, |
| 3323 | <code>currentline</code> is set to <em>-1</em>. | 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 | a reasonable name for the given function. | 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 | they do not have a fixed name: | 3389 | they do not have a fixed name: |
| 3329 | Some functions may be the value of multiple global variables, | 3390 | Some functions may be the value of multiple global variables, |
| 3330 | while others may be stored only in a table field. | 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 | If it cannot find a name, | 3394 | If it cannot find a name, |
| 3334 | then <code>name</code> is set to <code>NULL</code>. | 3395 | then <code>name</code> is set to <code>NULL</code>. |
| 3335 | | 3396 | |
| 3336 | <p><li><b><code>namewhat</code></b> | 3397 | <p><li><b><code>namewhat</code></b> --- |
| 3337 | Explains the <code>name</code> field. | 3398 | explains the <code>name</code> field. |
| 3338 | The value of <code>namewhat</code> can be | 3399 | The value of <code>namewhat</code> can be |
| 3339 | <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, | 3400 | <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, |
| 3340 | <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), | 3401 | <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), |
| 3341 | according to how the function was called. | 3402 | according to how the function was called. |
| 3342 | (Lua uses the empty string when no other option seems to apply.) | 3403 | (Lua uses the empty string when no other option seems to apply.) |
| 3343 | | 3404 | |
| 3344 | <p><li><b><code>nups</code></b> | 3405 | <p><li><b><code>nups</code></b> --- |
| 3345 | The number of upvalues of the function. | 3406 | the number of upvalues of the function. |
| 3346 | | 3407 | |
| 3347 | <p></ul> | 3408 | <p></ul> |
| 3348 | | 3409 | |
| 3349 | <p><a name="lua_gethook"></a> | 3410 | <p><a name="lua_gethook"></a> |
| 3350 | <hr/><h3><code>lua_gethook</code></h3> | 3411 | <hr /><h3><code>lua_gethook</code></h3> |
| 3351 | <pre> | 3412 | <pre> |
| 3352 | lua_Hook lua_gethook (lua_State *L); | 3413 | lua_Hook lua_gethook (lua_State *L); |
| 3353 | </pre> | 3414 | </pre> |
| @@ -3356,7 +3417,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3356 | <p>Returns the current hook function. | 3417 | <p>Returns the current hook function. |
| 3357 | | 3418 | |
| 3358 | <p><a name="lua_gethookcount"></a> | 3419 | <p><a name="lua_gethookcount"></a> |
| 3359 | <hr/><h3><code>lua_gethookcount</code></h3> | 3420 | <hr /><h3><code>lua_gethookcount</code></h3> |
| 3360 | <pre> | 3421 | <pre> |
| 3361 | int lua_gethookcount (lua_State *L); | 3422 | int lua_gethookcount (lua_State *L); |
| 3362 | </pre> | 3423 | </pre> |
| @@ -3365,7 +3426,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3365 | <p>Returns the current hook count. | 3426 | <p>Returns the current hook count. |
| 3366 | | 3427 | |
| 3367 | <p><a name="lua_gethookmask"></a> | 3428 | <p><a name="lua_gethookmask"></a> |
| 3368 | <hr/><h3><code>lua_gethookmask</code></h3> | 3429 | <hr /><h3><code>lua_gethookmask</code></h3> |
| 3369 | <pre> | 3430 | <pre> |
| 3370 | int lua_gethookmask (lua_State *L); | 3431 | int lua_gethookmask (lua_State *L); |
| 3371 | </pre> | 3432 | </pre> |
| @@ -3374,7 +3435,7 @@ The number of upvalues of the function. · 2 unmodified lines |
| 3374 | <p>Returns the current hook mask. | 3435 | <p>Returns the current hook mask. |
| 3375 | | 3436 | |
| 3376 | <p><a name="lua_getinfo"></a> | 3437 | <p><a name="lua_getinfo"></a> |
| 3377 | <hr/><h3><code>lua_getinfo</code></h3> | 3438 | <hr /><h3><code>lua_getinfo</code></h3> |
| 3378 | <pre> | 3439 | <pre> |
| 3379 | int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); | 3440 | int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); |
| 3380 | </pre> | 3441 | </pre> |
| @@ -3408,7 +3469,7 @@ you can write the following code: · 27 unmodified lines |
| 3408 | </pre> | 3469 | </pre> |
| 3409 | | 3470 | |
| 3410 | <p><a name="lua_getlocal"></a> | 3471 | <p><a name="lua_getlocal"></a> |
| 3411 | <hr/><h3><code>lua_getlocal</code></h3> | 3472 | <hr /><h3><code>lua_getlocal</code></h3> |
| 3412 | <pre> | 3473 | <pre> |
| 3413 | const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); | 3474 | const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); |
| 3414 | </pre> | 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 | The index <code>n</code> selects which local variable to inspect | 3482 | The index <code>n</code> selects which local variable to inspect |
| 3422 | (1 is the first parameter or active local variable, and so on, | 3483 | (1 is the first parameter or active local variable, and so on, |
| 3423 | until the last active local variable). | 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 | and returns its name. | 3486 | and returns its name. |
| 3426 | | 3487 | |
| 3427 | <p>Variable names starting with `<code>(</code>´ (open parentheses) | 3488 | <p>Variable names starting with `<code>(</code>´ (open parentheses) |
| @@ -3433,7 +3494,7 @@ when the index is greater than · 5 unmodified lines |
| 3433 | the number of active local variables. | 3494 | the number of active local variables. |
| 3434 | | 3495 | |
| 3435 | <p><a name="lua_getstack"></a> | 3496 | <p><a name="lua_getstack"></a> |
| 3436 | <hr/><h3><code>lua_getstack</code></h3> | 3497 | <hr /><h3><code>lua_getstack</code></h3> |
| 3437 | <pre> | 3498 | <pre> |
| 3438 | int lua_getstack (lua_State *L, int level, lua_Debug *ar); | 3499 | int lua_getstack (lua_State *L, int level, lua_Debug *ar); |
| 3439 | </pre> | 3500 | </pre> |
| @@ -3451,7 +3512,7 @@ when called with a level greater than the stack depth, · 11 unmodified lines |
| 3451 | it returns 0. | 3512 | it returns 0. |
| 3452 | | 3513 | |
| 3453 | <p><a name="lua_getupvalue"></a> | 3514 | <p><a name="lua_getupvalue"></a> |
| 3454 | <hr/><h3><code>lua_getupvalue</code></h3> | 3515 | <hr /><h3><code>lua_getupvalue</code></h3> |
| 3455 | <pre> | 3516 | <pre> |
| 3456 | const char *lua_getupvalue (lua_State *L, int funcindex, int n); | 3517 | const char *lua_getupvalue (lua_State *L, int funcindex, int n); |
| 3457 | </pre> | 3518 | </pre> |
| @@ -3466,7 +3527,8 @@ pushes the upvalue's value onto the stack, · 8 unmodified lines |
| 3466 | and returns its name. | 3527 | and returns its name. |
| 3467 | <code>funcindex</code> points to the closure in the stack. | 3528 | <code>funcindex</code> points to the closure in the stack. |
| 3468 | (Upvalues have no particular order, | 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 | <p>Returns <code>NULL</code> (and pushes nothing) | 3533 | <p>Returns <code>NULL</code> (and pushes nothing) |
| 3472 | when the index is greater than the number of upvalues. | 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 | as a name for all upvalues. | 3536 | as a name for all upvalues. |
| 3475 | | 3537 | |
| 3476 | <p><a name="lua_Hook"></a> | 3538 | <p><a name="lua_Hook"></a> |
| 3477 | <hr/><h3><code>lua_Hook</code></h3> | 3539 | <hr /><h3><code>lua_Hook</code></h3> |
| 3478 | <pre> | 3540 | <pre> |
| 3479 | typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); | 3541 | typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); |
| 3480 | </pre> | 3542 | </pre> |
| @@ -3502,7 +3564,7 @@ Therefore, if a hook calls back Lua to execute a function or a chunk, · 21 unmodified lines |
| 3502 | that execution occurs without any calls to hooks. | 3564 | that execution occurs without any calls to hooks. |
| 3503 | | 3565 | |
| 3504 | <p><a name="lua_sethook"></a> | 3566 | <p><a name="lua_sethook"></a> |
| 3505 | <hr/><h3><code>lua_sethook</code></h3> | 3567 | <hr /><h3><code>lua_sethook</code></h3> |
| 3506 | <pre> | 3568 | <pre> |
| 3507 | int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); | 3569 | int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); |
| 3508 | </pre> | 3570 | </pre> |
| @@ -3512,7 +3574,7 @@ that execution occurs without any calls to hooks. · 3 unmodified lines |
| 3512 | | 3574 | |
| 3513 | <p><code>func</code> is the hook function. | 3575 | <p><code>func</code> is the hook function. |
| 3514 | <code>mask</code> specifies on which events the hook will be called: | 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 | <code>LUA_MASKCALL</code>, | 3578 | <code>LUA_MASKCALL</code>, |
| 3517 | <code>LUA_MASKRET</code>, | 3579 | <code>LUA_MASKRET</code>, |
| 3518 | <code>LUA_MASKLINE</code>, | 3580 | <code>LUA_MASKLINE</code>, |
| @@ -3522,9 +3584,11 @@ includes <code>LUA_MASKCOUNT</code>. · 3 unmodified lines |
| 3522 | For each event, the hook is called as explained below: | 3584 | For each event, the hook is called as explained below: |
| 3523 | <ul> | 3585 | <ul> |
| 3524 | <li><b>The call hook</b> is called when the interpreter calls a function. | 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 | <li><b>The return hook</b> is called when the interpreter returns from a function. | 3589 | <li><b>The return hook</b> is called when the interpreter returns from a function. |
| 3527 | The hook is called just before Lua leaves the function. | 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 | <li><b>The line hook</b> is called when the interpreter is about to | 3592 | <li><b>The line hook</b> is called when the interpreter is about to |
| 3529 | start the execution of a new line of code, | 3593 | start the execution of a new line of code, |
| 3530 | or when it jumps back in the code (even to the same line). | 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 | <p>A hook is disabled by setting <code>mask</code> to zero. | 3601 | <p>A hook is disabled by setting <code>mask</code> to zero. |
| 3538 | | 3602 | |
| 3539 | <p><a name="lua_setlocal"></a> | 3603 | <p><a name="lua_setlocal"></a> |
| 3540 | <hr/><h3><code>lua_setlocal</code></h3> | 3604 | <hr /><h3><code>lua_setlocal</code></h3> |
| 3541 | <pre> | 3605 | <pre> |
| 3542 | const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); | 3606 | const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); |
| 3543 | </pre> | 3607 | </pre> |
| 3544 | | 3608 | |
| 3545 | | 3609 | |
| 3546 | <p>Sets the value of a local variable of a given activation record. | 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 | (see <a href="#lua_getlocal"></a>). | 3612 | (see <a href="#lua_getlocal"></a>). |
| 3549 | <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack | 3613 | <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack |
| 3550 | to the variable and returns its name. | 3614 | to the variable and returns its name. |
| @@ -3555,14 +3619,14 @@ when the index is greater than · 4 unmodified lines |
| 3555 | the number of active local variables. | 3619 | the number of active local variables. |
| 3556 | | 3620 | |
| 3557 | <p><a name="lua_setupvalue"></a> | 3621 | <p><a name="lua_setupvalue"></a> |
| 3558 | <hr/><h3><code>lua_setupvalue</code></h3> | 3622 | <hr /><h3><code>lua_setupvalue</code></h3> |
| 3559 | <pre> | 3623 | <pre> |
| 3560 | const char *lua_setupvalue (lua_State *L, int funcindex, int n); | 3624 | const char *lua_setupvalue (lua_State *L, int funcindex, int n); |
| 3561 | </pre> | 3625 | </pre> |
| 3562 | | 3626 | |
| 3563 | | 3627 | |
| 3564 | <p>Sets the value of a closure's upvalue. | 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 | (see <a href="#lua_getupvalue"></a>). | 3630 | (see <a href="#lua_getupvalue"></a>). |
| 3567 | It assigns the value at the top of the stack | 3631 | It assigns the value at the top of the stack |
| 3568 | to the upvalue and returns its name. | 3632 | to the upvalue and returns its name. |
| @@ -3586,17 +3650,17 @@ common tasks. · 17 unmodified lines |
| 3586 | are defined in header file <code>lauxlib.h</code> and | 3650 | are defined in header file <code>lauxlib.h</code> and |
| 3587 | have a prefix <code>luaL_</code>. | 3651 | have a prefix <code>luaL_</code>. |
| 3588 | | 3652 | |
| 3589 | <p>All functions in the auxiliary library are build on | 3653 | <p>All functions in the auxiliary library are built on |
| 3590 | top of the basic API, so they provide nothing that cannot | 3654 | top of the basic API, |
| 3591 | be done with that API. | 3655 | and so they provide nothing that cannot be done with that API. |
| 3592 | | 3656 | |
| 3593 | <p>Several functions in the auxiliary library are used to | 3657 | <p>Several functions in the auxiliary library are used to |
| 3594 | check C function arguments. | 3658 | check C function arguments. |
| 3595 | Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. | 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 | Because the error message is formatted for arguments | 3661 | Because the error message is formatted for arguments |
| 3598 | (e.g., <code>"bad argument #1"</code>), | 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 | <p><a name="4.1"></a><h2>4.1 - Functions and Types</h2> | 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 | in alphabetical order. | 3668 | in alphabetical order. |
| 3605 | | 3669 | |
| 3606 | <p><a name="luaL_addchar"></a> | 3670 | <p><a name="luaL_addchar"></a> |
| 3607 | <hr/><h3><code>luaL_addchar</code></h3> | 3671 | <hr /><h3><code>luaL_addchar</code></h3> |
| 3608 | <pre> | 3672 | <pre> |
| 3609 | void luaL_addchar (luaL_Buffer B, char c); | 3673 | void luaL_addchar (luaL_Buffer B, char c); |
| 3610 | </pre> | 3674 | </pre> |
| @@ -3614,7 +3678,7 @@ in alphabetical order. · 3 unmodified lines |
| 3614 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 3678 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3615 | | 3679 | |
| 3616 | <p><a name="luaL_addlstring"></a> | 3680 | <p><a name="luaL_addlstring"></a> |
| 3617 | <hr/><h3><code>luaL_addlstring</code></h3> | 3681 | <hr /><h3><code>luaL_addlstring</code></h3> |
| 3618 | <pre> | 3682 | <pre> |
| 3619 | void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); | 3683 | void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); |
| 3620 | </pre> | 3684 | </pre> |
| @@ -3623,9 +3687,10 @@ in alphabetical order. · 2 unmodified lines |
| 3623 | <p>Adds the string pointed by <code>s</code> with length <code>l</code> to | 3687 | <p>Adds the string pointed by <code>s</code> with length <code>l</code> to |
| 3624 | the buffer <code>B</code> | 3688 | the buffer <code>B</code> |
| 3625 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 3689 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| | 3690 | The string may contain embedded zeros. |
| 3626 | | 3691 | |
| 3627 | <p><a name="luaL_addsize"></a> | 3692 | <p><a name="luaL_addsize"></a> |
| 3628 | <hr/><h3><code>luaL_addsize</code></h3> | 3693 | <hr /><h3><code>luaL_addsize</code></h3> |
| 3629 | <pre> | 3694 | <pre> |
| 3630 | void luaL_addsize (luaL_Buffer B, size_t n); | 3695 | void luaL_addsize (luaL_Buffer B, size_t n); |
| 3631 | </pre> | 3696 | </pre> |
| @@ -3636,7 +3701,7 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to · 4 unmodified lines |
| 3636 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 3701 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3637 | | 3702 | |
| 3638 | <p><a name="luaL_addstring"></a> | 3703 | <p><a name="luaL_addstring"></a> |
| 3639 | <hr/><h3><code>luaL_addstring</code></h3> | 3704 | <hr /><h3><code>luaL_addstring</code></h3> |
| 3640 | <pre> | 3705 | <pre> |
| 3641 | void luaL_addstring (luaL_Buffer *B, const char *s); | 3706 | void luaL_addstring (luaL_Buffer *B, const char *s); |
| 3642 | </pre> | 3707 | </pre> |
| @@ -3645,9 +3710,10 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to · 2 unmodified lines |
| 3645 | <p>Adds the zero-terminated string pointed by <code>s</code> | 3710 | <p>Adds the zero-terminated string pointed by <code>s</code> |
| 3646 | to the buffer <code>B</code> | 3711 | to the buffer <code>B</code> |
| 3647 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 3712 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| | 3713 | The string may not contain embedded zeros. |
| 3648 | | 3714 | |
| 3649 | <p><a name="luaL_addvalue"></a> | 3715 | <p><a name="luaL_addvalue"></a> |
| 3650 | <hr/><h3><code>luaL_addvalue</code></h3> | 3716 | <hr /><h3><code>luaL_addvalue</code></h3> |
| 3651 | <pre> | 3717 | <pre> |
| 3652 | void luaL_addvalue (luaL_Buffer *B); | 3718 | void luaL_addvalue (luaL_Buffer *B); |
| 3653 | </pre> | 3719 | </pre> |
| @@ -3663,7 +3729,7 @@ be called with an extra element on the stack, · 9 unmodified lines |
| 3663 | which is the value to be added to the buffer. | 3729 | which is the value to be added to the buffer. |
| 3664 | | 3730 | |
| 3665 | <p><a name="luaL_argcheck"></a> | 3731 | <p><a name="luaL_argcheck"></a> |
| 3666 | <hr/><h3><code>luaL_argcheck</code></h3> | 3732 | <hr /><h3><code>luaL_argcheck</code></h3> |
| 3667 | <pre> | 3733 | <pre> |
| 3668 | void luaL_argcheck (lua_State *L, int cond, int numarg, | 3734 | void luaL_argcheck (lua_State *L, int cond, int numarg, |
| 3669 | const char *extramsg); | 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 | <p>Checks whether <code>cond</code> is true. | 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 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, | 3741 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, |
| 3676 | where <code>func</code> is retrieved from the call stack. | 3742 | where <code>func</code> is retrieved from the call stack. |
| 3677 | | 3743 | |
| 3678 | <p><a name="luaL_argerror"></a> | 3744 | <p><a name="luaL_argerror"></a> |
| 3679 | <hr/><h3><code>luaL_argerror</code></h3> | 3745 | <hr /><h3><code>luaL_argerror</code></h3> |
| 3680 | <pre> | 3746 | <pre> |
| 3681 | int luaL_argerror (lua_State *L, int numarg, const char *extramsg); | 3747 | int luaL_argerror (lua_State *L, int numarg, const char *extramsg); |
| 3682 | </pre> | 3748 | </pre> |
| @@ -3686,10 +3752,12 @@ where <code>func</code> is retrieved from the call stack. · 3 unmodified lines |
| 3686 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, | 3752 | <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, |
| 3687 | where <code>func</code> is retrieved from the call stack. | 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 | <p><a name="luaL_Buffer"></a> | 3759 | <p><a name="luaL_Buffer"></a> |
| 3692 | <hr/><h3><code>luaL_Buffer</code></h3> | 3760 | <hr /><h3><code>luaL_Buffer</code></h3> |
| 3693 | <pre> | 3761 | <pre> |
| 3694 | typedef struct luaL_Buffer luaL_Buffer; | 3762 | typedef struct luaL_Buffer luaL_Buffer; |
| 3695 | </pre> | 3763 | </pre> |
| @@ -3700,21 +3768,23 @@ where <code>func</code> is retrieved from the call stack. · 4 unmodified lines |
| 3700 | <p>A string buffer allows C code to build Lua strings piecemeal. | 3768 | <p>A string buffer allows C code to build Lua strings piecemeal. |
| 3701 | Its pattern of use is as follows: | 3769 | Its pattern of use is as follows: |
| 3702 | <ul> | 3770 | <ul> |
| 3703 | <li> Fist you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>. | 3771 | <li> First 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>. | 3772 | <li> Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>. |
| 3705 | <li> Then you add string pieces to the buffer calling any of | 3773 | <li> Then you add string pieces to the buffer calling any of |
| 3706 | the <code>luaL_add*</code> functions. | 3774 | the <code>luaL_add*</code> functions. |
| 3707 | <li> You finish calling <code>luaL_pushresult(&b)</code>. | 3775 | <li> You finish calling <code>luaL_pushresult(&b)</code>. |
| 3708 | That call leaves the final string on the top of the stack. | 3776 | That call leaves the final string on the top of the stack. |
| 3709 | </ul> | 3777 | </ul> |
| 3710 | | 3778 | |
| 3711 | <p>During its normal operation a string buffer uses a | 3779 | <p>During its normal operation, |
| 3712 | variable number of stack slots. | 3780 | a string buffer uses a variable number of stack slots. |
| 3713 | So, while using a buffer, you cannot assume that you know where | 3781 | So, while using a buffer, you cannot assume that you know where |
| 3714 | is the top of the stack. | 3782 | the top of the stack is. |
| 3715 | You can use the stack between successive calls to buffer operations, | 3783 | You can use the stack between successive calls to buffer operations |
| 3716 | as long as that use is balanced, that is, | 3784 | as long as that use is balanced; |
| 3717 | when you call a buffer operation the stack is at the same level | 3785 | that is, |
| | 3786 | when you call a buffer operation, |
| | 3787 | the stack is at the same level |
| 3718 | it was immediately after the previous buffer operation. | 3788 | it was immediately after the previous buffer operation. |
| 3719 | (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) | 3789 | (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) |
| 3720 | After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its | 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 | plus the final string on its top. | 3792 | plus the final string on its top. |
| 3723 | | 3793 | |
| 3724 | <p><a name="luaL_buffinit"></a> | 3794 | <p><a name="luaL_buffinit"></a> |
| 3725 | <hr/><h3><code>luaL_buffinit</code></h3> | 3795 | <hr /><h3><code>luaL_buffinit</code></h3> |
| 3726 | <pre> | 3796 | <pre> |
| 3727 | void luaL_buffinit (lua_State *L, luaL_Buffer *B); | 3797 | void luaL_buffinit (lua_State *L, luaL_Buffer *B); |
| 3728 | </pre> | 3798 | </pre> |
| @@ -3734,7 +3804,7 @@ the buffer must be declared as a variable · 5 unmodified lines |
| 3734 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 3804 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 3735 | | 3805 | |
| 3736 | <p><a name="luaL_callmeta"></a> | 3806 | <p><a name="luaL_callmeta"></a> |
| 3737 | <hr/><h3><code>luaL_callmeta</code></h3> | 3807 | <hr /><h3><code>luaL_callmeta</code></h3> |
| 3738 | <pre> | 3808 | <pre> |
| 3739 | int luaL_callmeta (lua_State *L, int obj, const char *e); | 3809 | int luaL_callmeta (lua_State *L, int obj, const char *e); |
| 3740 | </pre> | 3810 | </pre> |
| @@ -3744,53 +3814,54 @@ the buffer must be declared as a variable · 3 unmodified lines |
| 3744 | | 3814 | |
| 3745 | <p>If the object at index <code>obj</code> has a metatable and that | 3815 | <p>If the object at index <code>obj</code> has a metatable and that |
| 3746 | metatable has a field <code>e</code>, | 3816 | metatable has a field <code>e</code>, |
| 3747 | calls that field passing the object as argument. | 3817 | this function calls that field and passes the object as its only argument. |
| 3748 | In that case the function returns 1 and pushes on the | 3818 | In that case this function returns 1 and pushes on the |
| 3749 | stack the value returned by the call. | 3819 | stack the value returned by the call. |
| 3750 | If there is no metatable or no metamethod returns 0 | 3820 | If there is no metatable or no metamethod, |
| 3751 | (without pushing any value on the stack). | 3821 | this function returns 0 (without pushing any value on the stack). |
| 3752 | | 3822 | |
| 3753 | <p><a name="luaL_checkany"></a> | 3823 | <p><a name="luaL_checkany"></a> |
| 3754 | <hr/><h3><code>luaL_checkany</code></h3> | 3824 | <hr /><h3><code>luaL_checkany</code></h3> |
| 3755 | <pre> | 3825 | <pre> |
| 3756 | void luaL_checkany (lua_State *L, int narg); | 3826 | void luaL_checkany (lua_State *L, int narg); |
| 3757 | </pre> | 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 | <p><a name="luaL_checkint"></a> | 3833 | <p><a name="luaL_checkint"></a> |
| 3763 | <hr/><h3><code>luaL_checkint</code></h3> | 3834 | <hr /><h3><code>luaL_checkint</code></h3> |
| 3764 | <pre> | 3835 | <pre> |
| 3765 | int luaL_checkint (lua_State *L, int narg); | 3836 | int luaL_checkint (lua_State *L, int narg); |
| 3766 | </pre> | 3837 | </pre> |
| 3767 | | 3838 | |
| 3768 | | 3839 | |
| 3769 | <p>Checks whether the function argument <code>narg</code> is a number | 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 | <p><a name="luaL_checkinteger"></a> | 3843 | <p><a name="luaL_checkinteger"></a> |
| 3773 | <hr/><h3><code>luaL_checkinteger</code></h3> | 3844 | <hr /><h3><code>luaL_checkinteger</code></h3> |
| 3774 | <pre> | 3845 | <pre> |
| 3775 | lua_Integer luaL_checkinteger (lua_State *L, int numArg); | 3846 | lua_Integer luaL_checkinteger (lua_State *L, int narg); |
| 3776 | </pre> | 3847 | </pre> |
| 3777 | | 3848 | |
| 3778 | | 3849 | |
| 3779 | <p>Checks whether the function argument <code>narg</code> is a number | 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 | <p><a name="luaL_checklong"></a> | 3853 | <p><a name="luaL_checklong"></a> |
| 3783 | <hr/><h3><code>luaL_checklong</code></h3> | 3854 | <hr /><h3><code>luaL_checklong</code></h3> |
| 3784 | <pre> | 3855 | <pre> |
| 3785 | long luaL_checklong (lua_State *L, int narg); | 3856 | long luaL_checklong (lua_State *L, int narg); |
| 3786 | </pre> | 3857 | </pre> |
| 3787 | | 3858 | |
| 3788 | | 3859 | |
| 3789 | <p>Checks whether the function argument <code>narg</code> is a number | 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 | <p><a name="luaL_checklstring"></a> | 3863 | <p><a name="luaL_checklstring"></a> |
| 3793 | <hr/><h3><code>luaL_checklstring</code></h3> | 3864 | <hr /><h3><code>luaL_checklstring</code></h3> |
| 3794 | <pre> | 3865 | <pre> |
| 3795 | const char *luaL_checklstring (lua_State *L, int numArg, size_t *l); | 3866 | const char *luaL_checklstring (lua_State *L, int numArg, size_t *l); |
| 3796 | </pre> | 3867 | </pre> |
| @@ -3798,11 +3869,11 @@ and returns that number casted to a <code>long</code>. · 1 unmodified line |
| 3798 | | 3869 | |
| 3799 | <p>Checks whether the function argument <code>narg</code> is a string | 3870 | <p>Checks whether the function argument <code>narg</code> is a string |
| 3800 | and returns that string; | 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 | with the string's length. | 3873 | with the string's length. |
| 3803 | | 3874 | |
| 3804 | <p><a name="luaL_checknumber"></a> | 3875 | <p><a name="luaL_checknumber"></a> |
| 3805 | <hr/><h3><code>luaL_checknumber</code></h3> | 3876 | <hr /><h3><code>luaL_checknumber</code></h3> |
| 3806 | <pre> | 3877 | <pre> |
| 3807 | lua_Number luaL_checknumber (lua_State *L, int numArg); | 3878 | lua_Number luaL_checknumber (lua_State *L, int numArg); |
| 3808 | </pre> | 3879 | </pre> |
| @@ -3812,7 +3883,7 @@ with the string's length. · 3 unmodified lines |
| 3812 | and returns that number. | 3883 | and returns that number. |
| 3813 | | 3884 | |
| 3814 | <p><a name="luaL_checkoption"></a> | 3885 | <p><a name="luaL_checkoption"></a> |
| 3815 | <hr/><h3><code>luaL_checkoption</code></h3> | 3886 | <hr /><h3><code>luaL_checkoption</code></h3> |
| 3816 | <pre> | 3887 | <pre> |
| 3817 | int luaL_checkoption (lua_State *L, int narg, const char *def, | 3888 | int luaL_checkoption (lua_State *L, int narg, const char *def, |
| 3818 | const char *const lst[]); | 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 | Raises an error if the argument is not a string or | 3901 | Raises an error if the argument is not a string or |
| 3831 | if the string cannot be found. | 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 | <p><a name="luaL_checkstack"></a> | 3908 | <p><a name="luaL_checkstack"></a> |
| 3834 | <hr/><h3><code>luaL_checkstack</code></h3> | 3909 | <hr /><h3><code>luaL_checkstack</code></h3> |
| 3835 | <pre> | 3910 | <pre> |
| 3836 | void luaL_checkstack (lua_State *L, int sz, const char *msg); | 3911 | void luaL_checkstack (lua_State *L, int sz, const char *msg); |
| 3837 | </pre> | 3912 | </pre> |
| @@ -3842,7 +3917,7 @@ raising an error if the stack cannot grow to that size. · 4 unmodified lines |
| 3842 | <code>msg</code> is an additional text to go into the error message. | 3917 | <code>msg</code> is an additional text to go into the error message. |
| 3843 | | 3918 | |
| 3844 | <p><a name="luaL_checkstring"></a> | 3919 | <p><a name="luaL_checkstring"></a> |
| 3845 | <hr/><h3><code>luaL_checkstring</code></h3> | 3920 | <hr /><h3><code>luaL_checkstring</code></h3> |
| 3846 | <pre> | 3921 | <pre> |
| 3847 | const char *luaL_checkstring (lua_State *L, int narg); | 3922 | const char *luaL_checkstring (lua_State *L, int narg); |
| 3848 | </pre> | 3923 | </pre> |
| @@ -3852,7 +3927,7 @@ raising an error if the stack cannot grow to that size. · 3 unmodified lines |
| 3852 | and returns that string. | 3927 | and returns that string. |
| 3853 | | 3928 | |
| 3854 | <p><a name="luaL_checktype"></a> | 3929 | <p><a name="luaL_checktype"></a> |
| 3855 | <hr/><h3><code>luaL_checktype</code></h3> | 3930 | <hr /><h3><code>luaL_checktype</code></h3> |
| 3856 | <pre> | 3931 | <pre> |
| 3857 | void luaL_checktype (lua_State *L, int narg, int t); | 3932 | void luaL_checktype (lua_State *L, int narg, int t); |
| 3858 | </pre> | 3933 | </pre> |
| @@ -3861,7 +3936,7 @@ and returns that string. · 2 unmodified lines |
| 3861 | <p>Checks whether the function argument <code>narg</code> has type <code>t</code>. | 3936 | <p>Checks whether the function argument <code>narg</code> has type <code>t</code>. |
| 3862 | | 3937 | |
| 3863 | <p><a name="luaL_checkudata"></a> | 3938 | <p><a name="luaL_checkudata"></a> |
| 3864 | <hr/><h3><code>luaL_checkudata</code></h3> | 3939 | <hr /><h3><code>luaL_checkudata</code></h3> |
| 3865 | <pre> | 3940 | <pre> |
| 3866 | void *luaL_checkudata (lua_State *L, int ud, const char *tname); | 3941 | void *luaL_checkudata (lua_State *L, int ud, const char *tname); |
| 3867 | </pre> | 3942 | </pre> |
| @@ -3871,7 +3946,7 @@ and returns that string. · 3 unmodified lines |
| 3871 | of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). | 3946 | of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). |
| 3872 | | 3947 | |
| 3873 | <p><a name="luaL_error"></a> | 3948 | <p><a name="luaL_error"></a> |
| 3874 | <hr/><h3><code>luaL_error</code></h3> | 3949 | <hr /><h3><code>luaL_error</code></h3> |
| 3875 | <pre> | 3950 | <pre> |
| 3876 | int luaL_error (lua_State *L, const char *fmt, ...); | 3951 | int luaL_error (lua_State *L, const char *fmt, ...); |
| 3877 | </pre> | 3952 | </pre> |
| @@ -3885,10 +3960,12 @@ It also adds at the beginning of the message the file name and · 7 unmodified lines |
| 3885 | the line number where the error occurred, | 3960 | the line number where the error occurred, |
| 3886 | if that information is available. | 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 | <p><a name="luaL_getmetafield"></a> | 3967 | <p><a name="luaL_getmetafield"></a> |
| 3891 | <hr/><h3><code>luaL_getmetafield</code></h3> | 3968 | <hr /><h3><code>luaL_getmetafield</code></h3> |
| 3892 | <pre> | 3969 | <pre> |
| 3893 | int luaL_getmetafield (lua_State *L, int obj, const char *e); | 3970 | int luaL_getmetafield (lua_State *L, int obj, const char *e); |
| 3894 | </pre> | 3971 | </pre> |
| @@ -3898,10 +3975,10 @@ if that information is available. · 3 unmodified lines |
| 3898 | of the object at index <code>obj</code>. | 3975 | of the object at index <code>obj</code>. |
| 3899 | If the object does not have a metatable, | 3976 | If the object does not have a metatable, |
| 3900 | or if the metatable does not have that field, | 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 | <p><a name="luaL_getmetatable"></a> | 3980 | <p><a name="luaL_getmetatable"></a> |
| 3904 | <hr/><h3><code>luaL_getmetatable</code></h3> | 3981 | <hr /><h3><code>luaL_getmetatable</code></h3> |
| 3905 | <pre> | 3982 | <pre> |
| 3906 | void luaL_getmetatable (lua_State *L, const char *tname); | 3983 | void luaL_getmetatable (lua_State *L, const char *tname); |
| 3907 | </pre> | 3984 | </pre> |
| @@ -3911,19 +3988,20 @@ returns 0 (false) and pushes nothing. · 3 unmodified lines |
| 3911 | in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). | 3988 | in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). |
| 3912 | | 3989 | |
| 3913 | <p><a name="luaL_gsub"></a> | 3990 | <p><a name="luaL_gsub"></a> |
| 3914 | <hr/><h3><code>luaL_gsub</code></h3> | 3991 | <hr /><h3><code>luaL_gsub</code></h3> |
| 3915 | <pre> | 3992 | <pre> |
| 3916 | const char *luaL_gsub (lua_State *L, const char *s, | 3993 | const char *luaL_gsub (lua_State *L, const char *s, |
| 3917 | const char *p, const char *r); | 3994 | const char *p, const char *r); |
| 3918 | </pre> | 3995 | </pre> |
| 3919 | | 3996 | |
| 3920 | | 3997 | |
| 3921 | <p>Creates a copy of string <code>s</code> changing any occurrence of <code>p</code> | 3998 | <p>Creates a copy of string <code>s</code> by replacing any occurrence |
| 3922 | by the string <code>r</code>. | 3999 | any occurrence of the string <code>p</code> |
| | 4000 | wth the string <code>r</code>. |
| 3923 | Pushes the resulting string on the stack and returns it. | 4001 | Pushes the resulting string on the stack and returns it. |
| 3924 | | 4002 | |
| 3925 | <p><a name="luaL_loadbuffer"></a> | 4003 | <p><a name="luaL_loadbuffer"></a> |
| 3926 | <hr/><h3><code>luaL_loadbuffer</code></h3> | 4004 | <hr /><h3><code>luaL_loadbuffer</code></h3> |
| 3927 | <pre> | 4005 | <pre> |
| 3928 | int luaL_loadbuffer (lua_State *L, const char *buff, | 4006 | int luaL_loadbuffer (lua_State *L, const char *buff, |
| 3929 | size_t sz, const char *name); | 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 | used for debug information and error messages. | 4017 | used for debug information and error messages. |
| 3940 | | 4018 | |
| 3941 | <p><a name="luaL_loadfile"></a> | 4019 | <p><a name="luaL_loadfile"></a> |
| 3942 | <hr/><h3><code>luaL_loadfile</code></h3> | 4020 | <hr /><h3><code>luaL_loadfile</code></h3> |
| 3943 | <pre> | 4021 | <pre> |
| 3944 | int luaL_loadfile (lua_State *L, const char *filename); | 4022 | int luaL_loadfile (lua_State *L, const char *filename); |
| 3945 | </pre> | 4023 | </pre> |
| @@ -3948,14 +4026,16 @@ used for debug information and error messages. · 2 unmodified lines |
| 3948 | <p>Loads a file as a Lua chunk. | 4026 | <p>Loads a file as a Lua chunk. |
| 3949 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file | 4027 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file |
| 3950 | named <code>filename</code>. | 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 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, | 4033 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, |
| 3954 | but it has an extra error code <code>LUA_ERRFILE</code> | 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 | <p><a name="luaL_loadstring"></a> | 4037 | <p><a name="luaL_loadstring"></a> |
| 3958 | <hr/><h3><code>luaL_loadstring</code></h3> | 4038 | <hr /><h3><code>luaL_loadstring</code></h3> |
| 3959 | <pre> | 4039 | <pre> |
| 3960 | int luaL_loadstring (lua_State *L, const char *s); | 4040 | int luaL_loadstring (lua_State *L, const char *s); |
| 3961 | </pre> | 4041 | </pre> |
| @@ -3968,24 +4048,24 @@ the zero-terminated string <code>s</code>. · 6 unmodified lines |
| 3968 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. | 4048 | <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. |
| 3969 | | 4049 | |
| 3970 | <p><a name="luaL_newmetatable"></a> | 4050 | <p><a name="luaL_newmetatable"></a> |
| 3971 | <hr/><h3><code>luaL_newmetatable</code></h3> | 4051 | <hr /><h3><code>luaL_newmetatable</code></h3> |
| 3972 | <pre> | 4052 | <pre> |
| 3973 | int luaL_newmetatable (lua_State *L, const char *tname); | 4053 | int luaL_newmetatable (lua_State *L, const char *tname); |
| 3974 | </pre> | 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 | returns 0. | 4058 | returns 0. |
| 3979 | Otherwise, | 4059 | Otherwise, |
| 3980 | creates a new table to be used as metatables for userdata, | 4060 | creates a new table to be used as a metatable for userdata, |
| 3981 | adds it to the register with key <code>"tname"</code>, | 4061 | adds it to the registry with key <code>"tname"</code>, |
| 3982 | and returns 1. | 4062 | and returns 1. |
| 3983 | | 4063 | |
| 3984 | <p>In both cases pushes on the stack the final value associated | 4064 | <p>In both cases pushes on the stack the final value associated |
| 3985 | with <code>"tname"</code> in the registry. | 4065 | with <code>"tname"</code> in the registry. |
| 3986 | | 4066 | |
| 3987 | <p><a name="luaL_newstate"></a> | 4067 | <p><a name="luaL_newstate"></a> |
| 3988 | <hr/><h3><code>luaL_newstate</code></h3> | 4068 | <hr /><h3><code>luaL_newstate</code></h3> |
| 3989 | <pre> | 4069 | <pre> |
| 3990 | lua_State *luaL_newstate (void); | 4070 | lua_State *luaL_newstate (void); |
| 3991 | </pre> | 4071 | </pre> |
| @@ -3993,7 +4073,7 @@ with <code>"tname"</code> in the registry. · 1 unmodified line |
| 3993 | | 4073 | |
| 3994 | <p>Creates a new Lua state, calling <a href="#lua_newstate"><code>lua_newstate</code></a> with an | 4074 | <p>Creates a new Lua state, calling <a href="#lua_newstate"><code>lua_newstate</code></a> with an |
| 3995 | allocation function based on the standard C <code>realloc</code> function | 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 | an error message to the standard error output in case of fatal | 4077 | an error message to the standard error output in case of fatal |
| 3998 | errors. | 4078 | errors. |
| 3999 | | 4079 | |
| @@ -4001,46 +4081,46 @@ errors. · 1 unmodified line |
| 4001 | or <code>NULL</code> if there is a memory allocation error. | 4081 | or <code>NULL</code> if there is a memory allocation error. |
| 4002 | | 4082 | |
| 4003 | <p><a name="luaL_optint"></a> | 4083 | <p><a name="luaL_optint"></a> |
| 4004 | <hr/><h3><code>luaL_optint</code></h3> | 4084 | <hr /><h3><code>luaL_optint</code></h3> |
| 4005 | <pre> | 4085 | <pre> |
| 4006 | int luaL_optint (lua_State *L, int narg, int d); | 4086 | int luaL_optint (lua_State *L, int narg, int d); |
| 4007 | </pre> | 4087 | </pre> |
| 4008 | | 4088 | |
| 4009 | | 4089 | |
| 4010 | <p>If the function argument <code>narg</code> is a number, | 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 | If that argument is absent or is <b>nil</b>, | 4092 | If that argument is absent or is <b>nil</b>, |
| 4013 | returns <code>d</code>. | 4093 | returns <code>d</code>. |
| 4014 | Otherwise, raise an error. | 4094 | Otherwise, raises an error. |
| 4015 | | 4095 | |
| 4016 | <p><a name="luaL_optinteger"></a> | 4096 | <p><a name="luaL_optinteger"></a> |
| 4017 | <hr/><h3><code>luaL_optinteger</code></h3> | 4097 | <hr /><h3><code>luaL_optinteger</code></h3> |
| 4018 | <pre> | 4098 | <pre> |
| 4019 | lua_Integer luaL_optinteger (lua_State *L, int nArg, lua_Integer d); | 4099 | lua_Integer luaL_optinteger (lua_State *L, int nArg, lua_Integer d); |
| 4020 | </pre> | 4100 | </pre> |
| 4021 | | 4101 | |
| 4022 | | 4102 | |
| 4023 | <p>If the function argument <code>narg</code> is a number, | 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 | If that argument is absent or is <b>nil</b>, | 4105 | If that argument is absent or is <b>nil</b>, |
| 4026 | returns <code>d</code>. | 4106 | returns <code>d</code>. |
| 4027 | Otherwise, raise an error. | 4107 | Otherwise, raises an error. |
| 4028 | | 4108 | |
| 4029 | <p><a name="luaL_optlong"></a> | 4109 | <p><a name="luaL_optlong"></a> |
| 4030 | <hr/><h3><code>luaL_optlong</code></h3> | 4110 | <hr /><h3><code>luaL_optlong</code></h3> |
| 4031 | <pre> | 4111 | <pre> |
| 4032 | long luaL_optlong (lua_State *L, int narg, long d); | 4112 | long luaL_optlong (lua_State *L, int narg, long d); |
| 4033 | </pre> | 4113 | </pre> |
| 4034 | | 4114 | |
| 4035 | | 4115 | |
| 4036 | <p>If the function argument <code>narg</code> is a number, | 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 | If that argument is absent or is <b>nil</b>, | 4118 | If that argument is absent or is <b>nil</b>, |
| 4039 | returns <code>d</code>. | 4119 | returns <code>d</code>. |
| 4040 | Otherwise, raise an error. | 4120 | Otherwise, raises an error. |
| 4041 | | 4121 | |
| 4042 | <p><a name="luaL_optlstring"></a> | 4122 | <p><a name="luaL_optlstring"></a> |
| 4043 | <hr/><h3><code>luaL_optlstring</code></h3> | 4123 | <hr /><h3><code>luaL_optlstring</code></h3> |
| 4044 | <pre> | 4124 | <pre> |
| 4045 | const char *luaL_optlstring (lua_State *L, int numArg, | 4125 | const char *luaL_optlstring (lua_State *L, int numArg, |
| 4046 | const char *d, size_t *l); | 4126 | const char *d, size_t *l); |
| @@ -4051,13 +4131,13 @@ Otherwise, raise an error. · 4 unmodified lines |
| 4051 | returns that string. | 4131 | returns that string. |
| 4052 | If that argument is absent or is <b>nil</b>, | 4132 | If that argument is absent or is <b>nil</b>, |
| 4053 | returns <code>d</code>. | 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> | 4136 | <p>If <code>l</code> is not <code>NULL</code>, |
| 4057 | with the results's length. | 4137 | fills the position <code>*l</code> with the results's length. |
| 4058 | | 4138 | |
| 4059 | <p><a name="luaL_optnumber"></a> | 4139 | <p><a name="luaL_optnumber"></a> |
| 4060 | <hr/><h3><code>luaL_optnumber</code></h3> | 4140 | <hr /><h3><code>luaL_optnumber</code></h3> |
| 4061 | <pre> | 4141 | <pre> |
| 4062 | lua_Number luaL_optnumber (lua_State *L, int nArg, lua_Number d); | 4142 | lua_Number luaL_optnumber (lua_State *L, int nArg, lua_Number d); |
| 4063 | </pre> | 4143 | </pre> |
| @@ -4067,10 +4147,10 @@ with the results's length. · 3 unmodified lines |
| 4067 | returns that number. | 4147 | returns that number. |
| 4068 | If that argument is absent or is <b>nil</b>, | 4148 | If that argument is absent or is <b>nil</b>, |
| 4069 | returns <code>d</code>. | 4149 | returns <code>d</code>. |
| 4070 | Otherwise, raise an error. | 4150 | Otherwise, raises an error. |
| 4071 | | 4151 | |
| 4072 | <p><a name="luaL_optstring"></a> | 4152 | <p><a name="luaL_optstring"></a> |
| 4073 | <hr/><h3><code>luaL_optstring</code></h3> | 4153 | <hr /><h3><code>luaL_optstring</code></h3> |
| 4074 | <pre> | 4154 | <pre> |
| 4075 | const char *luaL_optstring (lua_State *L, int narg, const char *d); | 4155 | const char *luaL_optstring (lua_State *L, int narg, const char *d); |
| 4076 | </pre> | 4156 | </pre> |
| @@ -4080,24 +4160,24 @@ Otherwise, raise an error. · 3 unmodified lines |
| 4080 | returns that string. | 4160 | returns that string. |
| 4081 | If that argument is absent or is <b>nil</b>, | 4161 | If that argument is absent or is <b>nil</b>, |
| 4082 | returns <code>d</code>. | 4162 | returns <code>d</code>. |
| 4083 | Otherwise, raise an error. | 4163 | Otherwise, raises an error. |
| 4084 | | 4164 | |
| 4085 | <p><a name="luaL_prepbuffer"></a> | 4165 | <p><a name="luaL_prepbuffer"></a> |
| 4086 | <hr/><h3><code>luaL_prepbuffer</code></h3> | 4166 | <hr /><h3><code>luaL_prepbuffer</code></h3> |
| 4087 | <pre> | 4167 | <pre> |
| 4088 | char *luaL_prepbuffer (luaL_Buffer *B); | 4168 | char *luaL_prepbuffer (luaL_Buffer *B); |
| 4089 | </pre> | 4169 | </pre> |
| 4090 | | 4170 | |
| 4091 | | 4171 | |
| 4092 | <p>Returns an address to a space of size <code>LUAL_BUFFERSIZE</code> | 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 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | 4174 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). |
| 4095 | After copying the string into that space you must call | 4175 | After copying the string into that space you must call |
| 4096 | <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add | 4176 | <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add |
| 4097 | it to the buffer. | 4177 | it to the buffer. |
| 4098 | | 4178 | |
| 4099 | <p><a name="luaL_pushresult"></a> | 4179 | <p><a name="luaL_pushresult"></a> |
| 4100 | <hr/><h3><code>luaL_pushresult</code></h3> | 4180 | <hr /><h3><code>luaL_pushresult</code></h3> |
| 4101 | <pre> | 4181 | <pre> |
| 4102 | void luaL_pushresult (luaL_Buffer *B); | 4182 | void luaL_pushresult (luaL_Buffer *B); |
| 4103 | </pre> | 4183 | </pre> |
| @@ -4107,7 +4187,7 @@ it to the buffer. · 3 unmodified lines |
| 4107 | the top of the stack. | 4187 | the top of the stack. |
| 4108 | | 4188 | |
| 4109 | <p><a name="luaL_ref"></a> | 4189 | <p><a name="luaL_ref"></a> |
| 4110 | <hr/><h3><code>luaL_ref</code></h3> | 4190 | <hr /><h3><code>luaL_ref</code></h3> |
| 4111 | <pre> | 4191 | <pre> |
| 4112 | int luaL_ref (lua_State *L, int t); | 4192 | int luaL_ref (lua_State *L, int t); |
| 4113 | </pre> | 4193 | </pre> |
| @@ -4118,19 +4198,19 @@ in the table at index <code>t</code>, · 4 unmodified lines |
| 4118 | for the object at the top of the stack (and pops the object). | 4198 | for the object at the top of the stack (and pops the object). |
| 4119 | | 4199 | |
| 4120 | <p>A reference is a unique integer key. | 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 | <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. | 4202 | <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. |
| 4123 | You can retrieve an object referred by reference <code>r</code> | 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 | Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. | 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 | <a href="#luaL_ref"><code>luaL_ref</code></a> returns the same reference <code>LUA_REFNIL</code>. | 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 | from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. | 4210 | from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. |
| 4131 | | 4211 | |
| 4132 | <p><a name="luaL_Reg"></a> | 4212 | <p><a name="luaL_Reg"></a> |
| 4133 | <hr/><h3><code>luaL_Reg</code></h3> | 4213 | <hr /><h3><code>luaL_Reg</code></h3> |
| 4134 | <pre> | 4214 | <pre> |
| 4135 | typedef struct luaL_Reg { | 4215 | typedef struct luaL_Reg { |
| 4136 | const char *name; | 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 | </pre> | 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 | <a href="#luaL_register"><code>luaL_register</code></a>. | 4224 | <a href="#luaL_register"><code>luaL_register</code></a>. |
| 4145 | <code>name</code> is the function name and <code>func</code> is a pointer to | 4225 | <code>name</code> is the function name and <code>func</code> is a pointer to |
| 4146 | the function. | 4226 | the function. |
| 4147 | Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry | 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 | <p><a name="luaL_register"></a> | 4230 | <p><a name="luaL_register"></a> |
| 4151 | <hr/><h3><code>luaL_register</code></h3> | 4231 | <hr /><h3><code>luaL_register</code></h3> |
| 4152 | <pre> | 4232 | <pre> |
| 4153 | void luaL_register (lua_State *L, const char *libname, | 4233 | void luaL_register (lua_State *L, const char *libname, |
| 4154 | const luaL_Reg *l); | 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 | <p>When called with a non-null <code>libname</code>, | 4244 | <p>When called with a non-null <code>libname</code>, |
| 4165 | creates a new table <code>t</code>, | 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 | sets it as the value of <code>package.loaded[libname]</code>, | 4247 | sets it as the value of <code>package.loaded[libname]</code>, |
| 4168 | and registers on it all functions in the list <code>l</code>. | 4248 | and registers on it all functions in the list <code>l</code>. |
| 4169 | If there is a table in <code>package.loaded[libname]</code> or in | 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 | on the top of the stack. | 4254 | on the top of the stack. |
| 4175 | | 4255 | |
| 4176 | <p><a name="luaL_typename"></a> | 4256 | <p><a name="luaL_typename"></a> |
| 4177 | <hr/><h3><code>luaL_typename</code></h3> | 4257 | <hr /><h3><code>luaL_typename</code></h3> |
| 4178 | <pre> | 4258 | <pre> |
| 4179 | const char *luaL_typename (lua_State *L, int idx); | 4259 | const char *luaL_typename (lua_State *L, int idx); |
| 4180 | </pre> | 4260 | </pre> |
| @@ -4183,7 +4263,7 @@ on the top of the stack. · 2 unmodified lines |
| 4183 | <p>Returns the name of the type of the value at index <code>idx</code>. | 4263 | <p>Returns the name of the type of the value at index <code>idx</code>. |
| 4184 | | 4264 | |
| 4185 | <p><a name="luaL_typerror"></a> | 4265 | <p><a name="luaL_typerror"></a> |
| 4186 | <hr/><h3><code>luaL_typerror</code></h3> | 4266 | <hr /><h3><code>luaL_typerror</code></h3> |
| 4187 | <pre> | 4267 | <pre> |
| 4188 | int luaL_typerror (lua_State *L, int narg, const char *tname); | 4268 | int luaL_typerror (lua_State *L, int narg, const char *tname); |
| 4189 | </pre> | 4269 | </pre> |
| @@ -4198,7 +4278,7 @@ where <code><location></code> is produced by <a href="#luaL_where"><code>lu · 8 unmodified lines |
| 4198 | and <code><realt></code> is the type name of the actual argument. | 4278 | and <code><realt></code> is the type name of the actual argument. |
| 4199 | | 4279 | |
| 4200 | <p><a name="luaL_unref"></a> | 4280 | <p><a name="luaL_unref"></a> |
| 4201 | <hr/><h3><code>luaL_unref</code></h3> | 4281 | <hr /><h3><code>luaL_unref</code></h3> |
| 4202 | <pre> | 4282 | <pre> |
| 4203 | void luaL_unref (lua_State *L, int t, int ref); | 4283 | void luaL_unref (lua_State *L, int t, int ref); |
| 4204 | </pre> | 4284 | </pre> |
| @@ -4214,7 +4294,7 @@ The reference <code>ref</code> is also freed to be used again. · 9 unmodified lines |
| 4214 | <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. | 4294 | <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. |
| 4215 | | 4295 | |
| 4216 | <p><a name="luaL_where"></a> | 4296 | <p><a name="luaL_where"></a> |
| 4217 | <hr/><h3><code>luaL_where</code></h3> | 4297 | <hr /><h3><code>luaL_where</code></h3> |
| 4218 | <pre> | 4298 | <pre> |
| 4219 | void luaL_where (lua_State *L, int lvl); | 4299 | void luaL_where (lua_State *L, int lvl); |
| 4220 | </pre> | 4300 | </pre> |
| @@ -4224,20 +4304,21 @@ The reference <code>ref</code> is also freed to be used again. · 3 unmodified lines |
| 4224 | of the control at level <code>lvl</code> in the call stack. | 4304 | of the control at level <code>lvl</code> in the call stack. |
| 4225 | Typically this string has the format <code><chunkname>:<currentline>:</code>. | 4305 | Typically this string has the format <code><chunkname>:<currentline>:</code>. |
| 4226 | Level 0 is the running function, | 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 | <p>This function is used to build a prefix for error messages. | 4310 | <p>This function is used to build a prefix for error messages. |
| 4230 | | 4311 | |
| 4231 | <p> | 4312 | <p> |
| 4232 | <a name="libraries"></a><a name="5"></a><h1>5 - Standard Libraries</h1> | 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 | that are implemented directly through the C API. | 4316 | that are implemented directly through the C API. |
| 4236 | Some of these functions provide essential services to the language | 4317 | Some of these functions provide essential services to the language |
| 4237 | (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); | 4318 | (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); |
| 4238 | others provide access to "outside" services (e.g., I/O); | 4319 | others provide access to "outside" services (e.g., I/O); |
| 4239 | and others could be implemented in Lua itself, | 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 | deserve an implementation in C (e.g., <code>sort</code>). | 4322 | deserve an implementation in C (e.g., <code>sort</code>). |
| 4242 | | 4323 | |
| 4243 | <p>All libraries are implemented through the official C API | 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 | or as methods of its objects. | 4339 | or as methods of its objects. |
| 4259 | | 4340 | |
| 4260 | <p>To have access to these libraries, | 4341 | <p>To have access to these libraries, |
| 4261 | the C host program must first call the function | 4342 | the C host program must call |
| 4262 | <code>luaL_openlibs</code>; | 4343 | <code>luaL_openlibs</code>, |
| 4263 | or else it can open them individually calling | 4344 | which open all standard libraries. |
| | 4345 | Alternatively, |
| | 4346 | it can open them individually by calling |
| 4264 | <code>luaopen_base</code> (for the basic library), | 4347 | <code>luaopen_base</code> (for the basic library), |
| 4265 | <code>luaopen_package</code> (for the package library), | 4348 | <code>luaopen_package</code> (for the package library), |
| 4266 | <code>luaopen_string</code> (for the string library), | 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 | <code>luaopen_math</code> (for the mathematical library), | 4351 | <code>luaopen_math</code> (for the mathematical library), |
| 4269 | <code>luaopen_io</code> (for the I/O and the Operating System libraries), | 4352 | <code>luaopen_io</code> (for the I/O and the Operating System libraries), |
| 4270 | and <code>luaopen_debug</code> (for the debug library). | 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 | <p><a name="predefined"></a><a name="5.1"></a><h2>5.1 - Basic Functions</h2> | 4359 | <p><a name="predefined"></a><a name="5.1"></a><h2>5.1 - Basic Functions</h2> |
| 4274 | | 4360 | |
| 4275 | <p>The basic library provides some core functions to Lua. | 4361 | <p>The basic library provides some core functions to Lua. |
| 4276 | If you do not include this library in your application, | 4362 | If you do not include this library in your application, |
| 4277 | you should check carefully whether you need to provide some alternative | 4363 | you should check carefully whether you need to provide |
| 4278 | implementation for some of its facilities. | 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 | Issues an error when | 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 | otherwise, returns all its arguments. | 4369 | otherwise, returns all its arguments. |
| 4284 | <code>message</code> is an error message; | 4370 | <code>message</code> is an error message; |
| 4285 | when absent, it defaults to "assertion failed!" | 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 | <p>This function is a generic interface to the garbage collector. | 4375 | <p>This function is a generic interface to the garbage collector. |
| 4290 | It performs different functions according to its first argument, <code>opt</code>: | 4376 | It performs different functions according to its first argument, <code>opt</code>: |
| 4291 | <ul> | 4377 | <ul> |
| 4292 | <li><b>"stop"</b> stops the garbage collector. | 4378 | <li><b>"stop"</b> --- stops the garbage collector. |
| 4293 | <li><b>"restart"</b> restarts the garbage collector. | 4379 | <li><b>"restart"</b> --- restarts the garbage collector. |
| 4294 | <li><b>"collect"</b> performs a full garbage-collection cycle. | 4380 | <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). | 4381 | <li><b>"count"</b> --- returns the total memory in use by Lua (in Kbytes). |
| 4296 | <li><b>"step"</b> performs a garbage-collection step. | 4382 | <li><b>"step"</b> --- performs a garbage-collection step. |
| 4297 | The step "size" is controlled by <code>arg</code> | 4383 | The step "size" is controlled by <code>arg</code> |
| 4298 | (larger values mean more steps) in a non-specified way. | 4384 | (larger values mean more steps) in a non-specified way. |
| 4299 | If you want to control the step size | 4385 | If you want to control the step size |
| 4300 | you must tune experimentally the value of <code>arg</code>. | 4386 | you must tune experimentally the value of <code>arg</code>. |
| 4301 | Returns <b>true</b> if that step finished a collection cycle. | 4387 | Returns <b>true</b> if that step finished a collection cycle. |
| 4302 | <li><b>"steppause"</b> | 4388 | <li><b>"steppause"</b> --- |
| 4303 | sets <em><code>arg</code>/100</em> as the new value for the <em>pause</em> of | 4389 | sets <code>arg</code>/100 as the new value for the <em>pause</em> of |
| 4304 | the collector (see <a href="#GC">2.10</a>). | 4390 | the collector (see <a href="#GC">2.10</a>). |
| 4305 | <li><b>"setstepmul"</b> | 4391 | <li><b>"setstepmul"</b> --- |
| 4306 | sets <em><code>arg</code>/100</em> as the new value for the <em>step multiplier</em> of | 4392 | sets <code>arg</code>/100 as the new value for the <em>step multiplier</em> of |
| 4307 | the collector (see <a href="#GC">2.10</a>). | 4393 | the collector (see <a href="#GC">2.10</a>). |
| 4308 | </ul> | 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 | Opens the named file and executes its contents as a Lua chunk. | 4397 | Opens the named file and executes its contents as a Lua chunk. |
| 4312 | When called without arguments, | 4398 | When called without arguments, |
| 4313 | <a href="#pdf-dofile"><code>dofile</code></a> executes the contents of the standard input (<code>stdin</code>). | 4399 | <code>dofile</code> executes the contents of the standard input (<code>stdin</code>). |
| 4314 | Returns any value returned by the chunk. | 4400 | Returns all values returned by the chunk. |
| 4315 | In case of errors, <a href="#pdf-dofile"><code>dofile</code></a> propagates the error | 4401 | In case of errors, <code>dofile</code> propagates the error |
| 4316 | to its caller (that is, it does not run in protected mode). | 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 | Terminates the last protected function called | 4405 | Terminates the last protected function called |
| 4320 | and returns <code>message</code> as the error message. | 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 | at the beginning of the message. | 4410 | at the beginning of the message. |
| 4325 | The <code>level</code> argument specifies how to get the error position. | 4411 | The <code>level</code> argument specifies how to get the error position. |
| 4326 | With level 1 (the default), the error position is where the | 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 | Level 2 points the error to where the function | 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 | Passing a level 0 avoids the addition of error position information | 4416 | Passing a level 0 avoids the addition of error position information |
| 4331 | to the message. | 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 | A global variable (not a function) that | 4420 | A global variable (not a function) that |
| 4335 | holds the global environment (that is, <code>_G._G = _G</code>). | 4421 | holds the global environment (that is, <code>_G._G = _G</code>). |
| 4336 | Lua itself does not use this variable; | 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 | (Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) | 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 | Returns the current environment in use by the function. | 4428 | Returns the current environment in use by the function. |
| 4342 | <code>f</code> can be a Lua function or a number, | 4429 | <code>f</code> can be a Lua function or a number |
| 4343 | which specifies the function at that stack level: | 4430 | that specifies the function at that stack level: |
| 4344 | Level 1 is the function calling <a href="#pdf-getfenv"><code>getfenv</code></a>. | 4431 | Level 1 is the function calling <code>getfenv</code>. |
| 4345 | If the given function is not a Lua function, | 4432 | If the given function is not a Lua function, |
| 4346 | or if <code>f</code> is 0, | 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 | The default for <code>f</code> is 1. | 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 | <p>If <code>object</code> does not have a metatable, returns <b>nil</b>. | 4439 | <p>If <code>object</code> does not have a metatable, returns <b>nil</b>. |
| 4353 | Otherwise, | 4440 | Otherwise, |
| @@ -4355,9 +4442,9 @@ if the object's metatable has a <code>"__metatable"</code> field, · 1 unmodified line |
| 4355 | returns the associated value. | 4442 | returns the associated value. |
| 4356 | Otherwise, returns the metatable of the given object. | 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 | so that the construction | 4448 | so that the construction |
| 4362 | <pre> | 4449 | <pre> |
| 4363 | for i,v in ipairs(t) do ... end | 4450 | for i,v in ipairs(t) do ... end |
| @@ -4365,7 +4452,9 @@ so that the construction · 1 unmodified line |
| 4365 | will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., | 4452 | will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., |
| 4366 | up to the first integer key with a nil value in the table. | 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 | <p>Loads a chunk using function <code>func</code> to get its pieces. | 4459 | <p>Loads a chunk using function <code>func</code> to get its pieces. |
| 4371 | Each call to <code>func</code> must return a string that concatenates | 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 | <p><code>chunkname</code> is used as the chunk name for error messages | 4469 | <p><code>chunkname</code> is used as the chunk name for error messages |
| 4381 | and debug information. | 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 | <p>Similar to <a href="#pdf-load"><code>load</code></a>, | 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 | <p>Similar to <a href="#pdf-load"><code>load</code></a>, | 4481 | <p>Similar to <a href="#pdf-load"><code>load</code></a>, |
| 4391 | but gets the chunk from the given string. | 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 | assert(loadstring(s))() | 4486 | assert(loadstring(s))() |
| 4396 | </pre> | 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 | <p>Allows a program to traverse all fields of a table. | 4491 | <p>Allows a program to traverse all fields of a table. |
| 4401 | Its first argument is a table and its second argument | 4492 | Its first argument is a table and its second argument |
| 4402 | is an index in this table. | 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 | 4494 | <code>next</code> returns the next index of the table |
| 4404 | value associated with the index. | 4495 | and its associated value. |
| 4405 | When called with <b>nil</b> as its second argument, | 4496 | When called with <b>nil</b> as its second argument, |
| 4406 | <a href="#pdf-next"><code>next</code></a> returns the first index | 4497 | <code>next</code> returns an initial index |
| 4407 | of the table and its associated value. | 4498 | and its associated value. |
| 4408 | When called with the last index, | 4499 | When called with the last index, |
| 4409 | or with <b>nil</b> in an empty table, | 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 | If the second argument is absent, then it is interpreted as <b>nil</b>. | 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 | There is no difference between a | 4507 | There is no difference between a |
| 4415 | field not present in a table or a field with value <b>nil</b>. | 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 | The order in which the indices are enumerated is not specified, | 4510 | The order in which the indices are enumerated is not specified, |
| 4418 | <em>even for numeric indices</em>. | 4511 | <em>even for numeric indices</em>. |
| 4419 | (To traverse a table in numeric order, | 4512 | (To traverse a table in numeric order, |
| 4420 | use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) | 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 | during the traversal, | 4516 | during the traversal, |
| 4424 | you assign any value to a non-existent field in the table. | 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 | so that the construction | 4524 | so that the construction |
| 4430 | <pre> | 4525 | <pre> |
| 4431 | for k,v in pairs(t) do ... end | 4526 | for k,v in pairs(t) do ... end |
| 4432 | </pre> | 4527 | </pre> |
| 4433 | will iterate over all key--value pairs of table <code>t</code>. | 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 | <p>Calls function <code>f</code> with | 4534 | <p>Calls function <code>f</code> with |
| 4438 | the given arguments in protected mode. | 4535 | the given arguments in protected mode. |
| 4439 | That means that any error inside <code>f</code> is not propagated; | 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 | and returns a status code. | 4538 | and returns a status code. |
| 4442 | Its first result is the status code (a boolean), | 4539 | Its first result is the status code (a boolean), |
| 4443 | which is true if the call succeeds without errors. | 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 | after this first result. | 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 | Receives any number of arguments, | 4546 | Receives any number of arguments, |
| 4450 | and prints their values in <code>stdout</code>, | 4547 | and prints their values in <code>stdout</code>, |
| 4451 | using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. | 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 | but only as a quick way to show a value, | 4550 | but only as a quick way to show a value, |
| 4454 | typically for debugging. | 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 | Checks whether <code>v1</code> is equal to <code>v2</code>, | 4555 | Checks whether <code>v1</code> is equal to <code>v2</code>, |
| 4459 | without invoking any metamethod. | 4556 | without invoking any metamethod. |
| 4460 | Returns a boolean. | 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 | Gets the real value of <code>table[index]</code>, | 4560 | Gets the real value of <code>table[index]</code>, |
| 4464 | without invoking any metamethod. | 4561 | without invoking any metamethod. |
| 4465 | <code>table</code> must be a table; | 4562 | <code>table</code> must be a table and |
| 4466 | <code>index</code> is any value different from <b>nil</b>. | 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 | Sets the real value of <code>table[index]</code> to <code>value</code>, | 4566 | Sets the real value of <code>table[index]</code> to <code>value</code>, |
| 4470 | without invoking any metamethod. | 4567 | without invoking any metamethod. |
| 4471 | <code>table</code> must be a table, | 4568 | <code>table</code> must be a table, |
| 4472 | <code>index</code> is any value different from <b>nil</b>, | 4569 | <code>index</code> any value different from <b>nil</b>, |
| 4473 | and <code>value</code> is any Lua value. | 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 | <p>If <code>index</code> is a number, | 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 | Otherwise, <code>index</code> must be the string <code>"#"</code>, | 4576 | Otherwise, <code>index</code> must be the string <code>"#"</code>, |
| 4480 | and <code>select</code> returns the total number of extra arguments it received. | 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 | <p>Sets the environment to be used by the given function. | 4581 | <p>Sets the environment to be used by the given function. |
| 4485 | <code>f</code> can be a Lua function or a number, | 4582 | <code>f</code> can be a Lua function or a number |
| 4486 | which specifies the function at that stack level: | 4583 | that specifies the function at that stack level: |
| 4487 | Level 1 is the function calling <a href="#pdf-setfenv"><code>setfenv</code></a>. | 4584 | Level 1 is the function calling <code>setfenv</code>. |
| 4488 | <a href="#pdf-setfenv"><code>setfenv</code></a> returns the given function. | 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 | the environment of the running thread. | 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 | <p>Sets the metatable for the given table. | 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 | If <code>metatable</code> is <b>nil</b>, | 4595 | If <code>metatable</code> is <b>nil</b>, |
| 4499 | removes the metatable of the given table. | 4596 | removes the metatable of the given table. |
| 4500 | If the original metatable has a <code>"__metatable"</code> field, | 4597 | If the original metatable has a <code>"__metatable"</code> field, |
| @@ -4502,10 +4599,10 @@ raises an error. · 1 unmodified line |
| 4502 | | 4599 | |
| 4503 | <p>This function returns <code>table</code>. | 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 | Tries to convert its argument to a number. | 4603 | Tries to convert its argument to a number. |
| 4507 | If the argument is already a number or a string convertible | 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 | otherwise, it returns <b>nil</b>. | 4606 | otherwise, it returns <b>nil</b>. |
| 4510 | | 4607 | |
| 4511 | <p>An optional argument specifies the base to interpret the numeral. | 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 | represents 10, `<code>B</code>´ represents 11, and so forth, | 4611 | represents 10, `<code>B</code>´ represents 11, and so forth, |
| 4515 | with `<code>Z</code>´ representing 35. | 4612 | with `<code>Z</code>´ representing 35. |
| 4516 | In base 10 (the default), the number may have a decimal part, | 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 | In other bases, only unsigned integers are accepted. | 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 | Receives an argument of any type and | 4618 | Receives an argument of any type and |
| 4522 | converts it to a string in a reasonable format. | 4619 | converts it to a string in a reasonable format. |
| 4523 | For complete control of how numbers are converted, | 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 | <p>If the metatable of <code>e</code> has a <code>"__tostring"</code> field, | 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 | with <code>e</code> as argument, | 4625 | with <code>e</code> as argument, |
| 4529 | and uses the result of the call as its result. | 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 | Returns the type of its only argument, coded as a string. | 4629 | Returns the type of its only argument, coded as a string. |
| 4533 | The possible results of this function are | 4630 | The possible results of this function are |
| 4534 | <code>"nil"</code> (a string, not the value <b>nil</b>), | 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 | <code>"thread"</code>, | 4637 | <code>"thread"</code>, |
| 4541 | and <code>"userdata"</code>. | 4638 | and <code>"userdata"</code>. |
| 4542 | | 4639 | |
| 4543 | <p><a name="pdf-unpack"></a><hr/><h3><code>unpack (list [, i [, j]])</code></h3> | 4640 | <p><a name="pdf-unpack"></a><hr /><h3><code>unpack (list [, i [, j]])</code></h3> |
| 4544 | Returns the elements from the given list. | 4641 | Returns the elements from the given table. |
| 4545 | This function is equivalent to | 4642 | This function is equivalent to |
| 4546 | <pre> | 4643 | <pre> |
| 4547 | return list[i], list[i+1], ..., list[j] | 4644 | return list[i], list[i+1], ..., list[j] |
| @@ -4549,30 +4646,30 @@ This function is equivalent to · 1 unmodified line |
| 4549 | except that the above code can be written only for a fixed number | 4646 | except that the above code can be written only for a fixed number |
| 4550 | of elements. | 4647 | of elements. |
| 4551 | By default, <code>i</code> is 1 and <code>j</code> is the length of the list, | 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 | A global variable (not a function) that | 4652 | A global variable (not a function) that |
| 4556 | holds a string containing the current interpreter version. | 4653 | holds a string containing the current interpreter version. |
| 4557 | The current contents of this variable is <code>"Lua 5.1"</code>. | 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 | except that you can set a new error handler. | 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 | using <code>err</code> as the error handler. | 4662 | using <code>err</code> as the error handler. |
| 4566 | Any error inside <code>f</code> is not propagated; | 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 | calls the <code>err</code> function with the original error object, | 4665 | calls the <code>err</code> function with the original error object, |
| 4569 | and returns a status code. | 4666 | and returns a status code. |
| 4570 | Its first result is the status code (a boolean), | 4667 | Its first result is the status code (a boolean), |
| 4571 | which is true if the call succeeds without errors. | 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 | after this first result. | 4670 | after this first result. |
| 4574 | In case of any error, | 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 | <p><a name="5.2"></a><h2>5.2 - Coroutine Manipulation</h2> | 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 | the basic library and come inside the table <code>coroutine</code>. | 4677 | the basic library and come inside the table <code>coroutine</code>. |
| 4581 | See <a href="#coroutine">2.11</a> for a general description of coroutines. | 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 | <p>Creates a new coroutine, with body <code>f</code>. | 4682 | <p>Creates a new coroutine, with body <code>f</code>. |
| 4586 | <code>f</code> must be a Lua function. | 4683 | <code>f</code> must be a Lua function. |
| 4587 | Returns this new coroutine, | 4684 | Returns this new coroutine, |
| 4588 | an object with type <code>"thread"</code>. | 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 | <p>Starts or continues the execution of coroutine <code>co</code>. | 4689 | <p>Starts or continues the execution of coroutine <code>co</code>. |
| 4593 | The first time you resume a coroutine, | 4690 | The first time you resume a coroutine, |
| 4594 | it starts running its body. | 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 | If the coroutine has yielded, | 4694 | If the coroutine has yielded, |
| 4597 | <code>resume</code> restarts it; | 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 | <p>If the coroutine runs without any errors, | 4699 | <p>If the coroutine runs without any errors, |
| 4601 | <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> | 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 | If there is any error, | 4703 | If there is any error, |
| 4605 | <code>resume</code> returns <b>false</b> plus the error message. | 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 | <p>Returns the running coroutine, | 4708 | <p>Returns the running coroutine, |
| 4610 | or <b>nil</b> when called by the main thread. | 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 | <p>Returns the status of coroutine <code>co</code>, as a string: | 4713 | <p>Returns the status of coroutine <code>co</code>, as a string: |
| 4615 | <code>"running"</code>, | 4714 | <code>"running"</code>, |
| @@ -4621,7 +4720,7 @@ or if it has not started running yet; · 5 unmodified lines |
| 4621 | and <code>"dead"</code> if the coroutine has finished its body function, | 4720 | and <code>"dead"</code> if the coroutine has finished its body function, |
| 4622 | or if it has stopped with an error. | 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 | <p>Creates a new coroutine, with body <code>f</code>. | 4725 | <p>Creates a new coroutine, with body <code>f</code>. |
| 4627 | <code>f</code> must be a Lua function. | 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 | except the first boolean. | 4731 | except the first boolean. |
| 4633 | In case of error, propagates the error. | 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 | <p>Suspends the execution of the calling coroutine. | 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 | nor a metamethod, nor an iterator. | 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 | <p>The package library provides basic | 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 | It exports two of its functions directly in the global environment: | 4745 | It exports two of its functions directly in the global environment: |
| 4647 | <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. | 4746 | <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. |
| 4648 | Everything else is exported in a table <code>package</code>. | 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 | <p>Creates a module. | 4751 | <p>Creates a module. |
| 4653 | If there is a table in <code>package.loaded[name]</code>, | 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 | so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. | 4765 | so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. |
| 4667 | | 4766 | |
| 4668 | <p>If <code>name</code> is a compound name | 4767 | <p>If <code>name</code> is a compound name |
| 4669 | (that is, one with components separated by dots) | 4768 | (that is, one with components separated by dots), |
| 4670 | <code>module</code> creates (or reuses, if they already exists) | 4769 | <code>module</code> creates (or reuses, if they already exist) |
| 4671 | tables for each component. | 4770 | tables for each component. |
| 4672 | For instance, if <code>name</code> is <code>a.b.c</code>, | 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 | field <code>b</code> of global <code>a</code>. | 4773 | field <code>b</code> of global <code>a</code>. |
| 4675 | | 4774 | |
| 4676 | <p>This function may receive optional <em>options</em> after | 4775 | <p>This function may receive optional <em>options</em> after |
| 4677 | the module name, | 4776 | the module name, |
| 4678 | where each option is a function to be applied over the module. | 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 | <p>Loads the given module. | 4781 | <p>Loads the given module. |
| 4683 | The function starts by looking into the table <code>package.loaded</code> | 4782 | The function starts by looking into the table <code>package.loaded</code> |
| 4684 | to determine whether <code>modname</code> is already loaded. | 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 | at <code>package.loaded[modname]</code>. | 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 | <p>To find a loader, | 4788 | <p>To find a loader, |
| 4690 | first <a href="#pdf-require"><code>require</code></a> queries <code>package.preload[modname]</code>. | 4789 | first <code>require</code> queries <code>package.preload[modname]</code>. |
| 4691 | If it is a true value, | 4790 | If it has a value, |
| 4692 | that value (which should be a function) is the loader. | 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 | path stored in <code>package.path</code>. | 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 | path stored in <code>package.cpath</code>. | 4795 | path stored in <code>package.cpath</code>. |
| 4697 | If that also fails, | 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 | <p>When loading a C library, | 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 | application with the library. | 4801 | application with the library. |
| 4703 | Then it tries to find a C function inside that library to | 4802 | Then it tries to find a C function inside that library to |
| 4704 | be used as the loader. | 4803 | be used as the loader. |
| 4705 | The name of that C function is the string <code>"luaopen_"</code> | 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 | is replaced by an underscore. | 4806 | is replaced by an underscore. |
| 4708 | Moreover, if the module name has a hyphen, | 4807 | Moreover, if the module name has a hyphen, |
| 4709 | its prefix up to (and including) the first hyphen is removed. | 4808 | its prefix up to (and including) the first hyphen is removed. |
| 4710 | For instance, if the module name is <code>a.v1-b.c</code>, | 4809 | For instance, if the module name is <code>a.v1-b.c</code>, |
| 4711 | the function name will be <code>luaopen_b_c</code>. | 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 | C library for a module, | 4813 | C library for a module, |
| 4715 | it calls the <em>all-in-one loader</em>. | 4814 | it calls the <em>all-in-one loader</em>. |
| 4716 | That loader searches the C path for a library for | 4815 | That loader searches the C path for a library for |
| @@ -4725,29 +4824,29 @@ into one single library, · 8 unmodified lines |
| 4725 | with each submodule keeping its original open function. | 4824 | with each submodule keeping its original open function. |
| 4726 | | 4825 | |
| 4727 | <p>Once a loader is found, | 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 | If the loader returns any value, | 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 | If the loader returns no value and | 4830 | If the loader returns no value and |
| 4732 | has not assigned any value to <code>package.loaded[modname]</code>, | 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 | In any case, require returns the | 4833 | In any case, require returns the |
| 4735 | final value of <code>package.loaded[modname]</code>. | 4834 | final value of <code>package.loaded[modname]</code>. |
| 4736 | | 4835 | |
| 4737 | <p>If there is any error loading or running the module, | 4836 | <p>If there is any error loading or running the module, |
| 4738 | or if it cannot find any loader for that module, | 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 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. | 4842 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. |
| 4744 | | 4843 | |
| 4745 | <p>Lua initializes the C path <code>package.cpath</code> in the same way | 4844 | <p>Lua initializes the C path <code>package.cpath</code> in the same way |
| 4746 | it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, | 4845 | it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, |
| 4747 | using the environment variable <code>LUA_CPATH</code> | 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 | <p>A table used by <a href="#pdf-require"><code>require</code></a> to control which | 4851 | <p>A table used by <a href="#pdf-require"><code>require</code></a> to control which |
| 4753 | modules are already loaded. | 4852 | modules are already loaded. |
| @@ -4755,27 +4854,34 @@ When you require a module <code>modname</code> and · 1 unmodified line |
| 4755 | <code>package.loaded[modname]</code> is not false, | 4854 | <code>package.loaded[modname]</code> is not false, |
| 4756 | <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. | 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 | Inside this library, looks for a function <code>funcname</code> | 4860 | Inside this library, looks for a function <code>funcname</code> |
| 4762 | and returns this function as a C function. | 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, | 4864 | <p>This is a low-level function. |
| 4765 | including any eventual path and extension. | 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 | <p>This function is not supported by ANSI C. | 4873 | <p>This function is not supported by ANSI C. |
| 4768 | As such, it is only available on some platforms | 4874 | As such, it is only available on some platforms |
| 4769 | (Windows, Linux, Solaris, BSD, plus other Unix systems that | 4875 | (Windows, Linux, Mac OS X, Solaris, BSD, |
| 4770 | support the <code>dlfcn</code> standard). | 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 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. | 4880 | <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. |
| 4775 | | 4881 | |
| 4776 | <p>At start-up, Lua initializes this variable with | 4882 | <p>At start-up, Lua initializes this variable with |
| 4777 | the value of the environment variable <code>LUA_PATH</code> or | 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 | if the environment variable is not defined. | 4885 | if the environment variable is not defined. |
| 4780 | Any <code>";;"</code> in the value of the environment variable | 4886 | Any <code>";;"</code> in the value of the environment variable |
| 4781 | is replaced by the default path. | 4887 | is replaced by the default path. |
| @@ -4790,21 +4896,21 @@ So, for instance, if the Lua path is · 8 unmodified lines |
| 4790 | <pre> | 4896 | <pre> |
| 4791 | "./?.lua;./?.lc;/usr/local/?/init.lua" | 4897 | "./?.lua;./?.lc;/usr/local/?/init.lua" |
| 4792 | </pre> | 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 | will try to load the files | 4900 | will try to load the files |
| 4795 | <code>./mod.lua</code>, <code>./mod.lc</code>, and | 4901 | <code>./foo.lua</code>, <code>./foo.lc</code>, and |
| 4796 | <code>/usr/local/mod/init.lua</code>, in that order. | 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 | <p>A table to store loaders for specific modules | 4906 | <p>A table to store loaders for specific modules |
| 4801 | (see <a href="#pdf-require"><code>require</code></a>). | 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 | <p>Sets a metatable for <code>module</code> with | 4911 | <p>Sets a metatable for <code>module</code> with |
| 4806 | its <code>__index</code> field refering to the global environment, | 4912 | its <code>__index</code> field referring to the global environment, |
| 4807 | so that this module inherits undefined values | 4913 | so that this module inherits values |
| 4808 | from the global environment. | 4914 | from the global environment. |
| 4809 | To be used as an option to function <a href="#pdf-module"><code>module</code></a>. | 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 | <p>The string library provides all its functions inside the table | 4927 | <p>The string library provides all its functions inside the table |
| 4822 | <code>string</code>. | 4928 | <code>string</code>. |
| 4823 | It also sets a metatable for strings | 4929 | It also sets a metatable for strings |
| 4824 | wherein <code>__index</code> points to itself. | 4930 | where the <code>__index</code> field points to the metatable itself. |
| 4825 | Therefore, you can use the string function is object-oriented style. | 4931 | Therefore, you can use the string functions in object-oriented style. |
| 4826 | For instance, <code>string.byte(s, i)</code> | 4932 | For instance, <code>string.byte(s, i)</code> |
| 4827 | can be written as <code>s:byte(i)</code>. | 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 | Returns the internal numerical codes of the characters <code>s[i]</code>, | 4936 | Returns the internal numerical codes of the characters <code>s[i]</code>, |
| 4831 | <code>s[i+1]</code>, ..., <code>s[j]</code>. | 4937 | <code>s[i+1]</code>, ..., <code>s[j]</code>. |
| 4832 | The default value for <code>i</code> is 1; | 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 | <p>Note that numerical codes are not necessarily portable across platforms. | 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 | Receives 0 or more integers. | 4944 | Receives 0 or more integers. |
| 4839 | Returns a string with length equal to the number of arguments, | 4945 | Returns a string with length equal to the number of arguments, |
| 4840 | in which each character has the internal numerical code equal | 4946 | in which each character has the internal numerical code equal |
| 4841 | to its correspondent argument. | 4947 | to its corresponding argument. |
| 4842 | | 4948 | |
| 4843 | <p>Note that numerical codes are not necessarily portable across platforms. | 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 | so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on that string returns | 4954 | so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on that string returns |
| 4849 | a copy of the function. | 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> | 4958 | <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 | 4959 | Looks for the first match of |
| 4854 | <code>pattern</code> in the string <code>s</code>. | 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 | where this occurrence starts and ends; | 4962 | where this occurrence starts and ends; |
| 4857 | otherwise, it returns <b>nil</b>. | 4963 | otherwise, it returns <b>nil</b>. |
| 4858 | A third, optional numerical argument <code>init</code> specifies | 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 | turns off the pattern matching facilities, | 4968 | turns off the pattern matching facilities, |
| 4863 | so the function does a plain "find substring" operation, | 4969 | so the function does a plain "find substring" operation, |
| 4864 | with no characters in <code>pattern</code> being considered "magic". | 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 | <p>If the pattern has captures, | 4973 | <p>If the pattern has captures, |
| 4868 | then in a successful match | 4974 | then in a successful match |
| 4869 | the captured values are also returned, | 4975 | the captured values are also returned, |
| 4870 | after the two indices. | 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 | Returns a formatted version of its variable number of arguments | 4979 | Returns a formatted version of its variable number of arguments |
| 4874 | following the description given in its first argument (which must be a string). | 4980 | following the description given in its first argument (which must be a string). |
| 4875 | The format string follows the same rules as the <code>printf</code> family of | 4981 | The format string follows the same rules as the <code>printf</code> family of |
| 4876 | standard C functions. | 4982 | standard C functions. |
| 4877 | The only differences are that the options/modifiers | 4983 | The only differences are that the options/modifiers |
| 4878 | <code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, | 4984 | <code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, |
| 4879 | and <code>h</code> are not supported, | 4985 | and <code>h</code> are not supported |
| 4880 | and there is an extra option, <code>q</code>. | 4986 | and that there is an extra option, <code>q</code>. |
| 4881 | The <code>q</code> option formats a string in a form suitable to be safely read | 4987 | The <code>q</code> option formats a string in a form suitable to be safely read |
| 4882 | back by the Lua interpreter: | 4988 | back by the Lua interpreter: |
| 4883 | The string is written between double quotes, | 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 | are correctly escaped when written. | 4992 | are correctly escaped when written. |
| 4886 | For instance, the call | 4993 | For instance, the call |
| 4887 | <pre> | 4994 | <pre> |
| @@ -4901,12 +5008,12 @@ whereas <code>q</code> and <code>s</code> expect a string. · 13 unmodified lines |
| 4901 | <p>This function does not accept string values | 5008 | <p>This function does not accept string values |
| 4902 | containing embedded zeros. | 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 | Returns an iterator function that, | 5012 | Returns an iterator function that, |
| 4906 | each time it is called, | 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 | then the whole match is produced in each call. | 5017 | then the whole match is produced in each call. |
| 4911 | | 5018 | |
| 4912 | <p>As an example, the following loop | 5019 | <p>As an example, the following loop |
| @@ -4928,11 +5035,12 @@ given string into a table: · 15 unmodified lines |
| 4928 | end | 5035 | end |
| 4929 | </pre> | 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 | Returns a copy of <code>s</code> | 5039 | Returns a copy of <code>s</code> |
| 4933 | in which all occurrences of the pattern <code>pat</code> have been | 5040 | in which all occurrences of the <code>pattern</code> have been |
| 4934 | replaced by a replacement string specified by <code>repl</code>. | 5041 | replaced by a replacement string specified by <code>repl</code>, |
| 4935 | <code>gsub</code> also returns, as a second value, | 5042 | which may be a string, a table, or a function. |
| | 5043 | <code>gsub</code> also returns, as its second value, |
| 4936 | the total number of substitutions made. | 5044 | the total number of substitutions made. |
| 4937 | | 5045 | |
| 4938 | <p>If <code>repl</code> is a string, then its value is used for replacement. | 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 | The sequence <code>%0</code> stands for the whole match. | 5051 | The sequence <code>%0</code> stands for the whole match. |
| 4944 | The sequence <code>%%</code> stands for a single <code>%</code>. | 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 | <p>If <code>repl</code> is a function, then this function is called every time a | 5059 | <p>If <code>repl</code> is a function, then this function is called every time a |
| 4947 | match occurs, with all captured substrings passed as arguments, | 5060 | match occurs, with all captured substrings passed as arguments, |
| 4948 | in order; | 5061 | in order; |
| @@ -4951,9 +5064,10 @@ then the whole match is passed as a sole argument. · 2 unmodified lines |
| 4951 | If <code>repl</code> is a table, then this table is queried with the | 5064 | If <code>repl</code> is a table, then this table is queried with the |
| 4952 | value of the first capture or of the whole match, | 5065 | value of the first capture or of the whole match, |
| 4953 | if the pattern specifies no captures. | 5066 | if the pattern specifies no captures. |
| 4954 | In both cases, | 5067 | |
| 4955 | if the value returned by the function or resulted by the query | 5068 | <p>In both cases, |
| 4956 | is a string, | 5069 | if the value returned by the function or by the table query |
| | 5070 | is a string or a number, |
| 4957 | then it is used as the replacement string; | 5071 | then it is used as the replacement string; |
| 4958 | otherwise, if it is <b>false</b> or <b>nil</b>, | 5072 | otherwise, if it is <b>false</b> or <b>nil</b>, |
| 4959 | then there is no replacement | 5073 | then there is no replacement |
| @@ -4962,7 +5076,7 @@ then there is no replacement · 2 unmodified lines |
| 4962 | <p>The optional last parameter <code>n</code> limits | 5076 | <p>The optional last parameter <code>n</code> limits |
| 4963 | the maximum number of substitutions to occur. | 5077 | the maximum number of substitutions to occur. |
| 4964 | For instance, when <code>n</code> is 1 only the first occurrence of | 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 | <p>Here are some examples: | 5081 | <p>Here are some examples: |
| 4968 | <pre> | 5082 | <pre> |
| @@ -4983,24 +5097,24 @@ For instance, when <code>n</code> is 1 only the first occurrence of · 14 unmodified lines |
| 4983 | end) | 5097 | end) |
| 4984 | --> x="4+5 = 9" | 5098 | --> x="4+5 = 9" |
| 4985 | | 5099 | |
| 4986 | local t = {name="lua", version="5.0"} | 5100 | local t = {name="lua", version="5.1"} |
| 4987 | x = string.gsub("$name_$version.tar.gz", "%$(%w+)", t) | 5101 | x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) |
| 4988 | --> x="lua_5.0.tar.gz" | 5102 | --> x="lua-5.1.tar.gz" |
| 4989 | </pre> | 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 | Receives a string and returns its length. | 5106 | Receives a string and returns its length. |
| 4993 | The empty string <code>""</code> has length 0. | 5107 | The empty string <code>""</code> has length 0. |
| 4994 | Embedded zeros are counted, | 5108 | Embedded zeros are counted, |
| 4995 | so <code>"a\000bc\000"</code> has length 5. | 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 | Receives a string and returns a copy of that string with all | 5112 | Receives a string and returns a copy of that string with all |
| 4999 | uppercase letters changed to lowercase. | 5113 | uppercase letters changed to lowercase. |
| 5000 | All other characters are left unchanged. | 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 | Looks for the first <em>match</em> of | 5118 | Looks for the first <em>match</em> of |
| 5005 | <code>pattern</code> in the string <code>s</code>. | 5119 | <code>pattern</code> in the string <code>s</code>. |
| 5006 | If it finds one, then <code>match</code> returns | 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 | where to start the search; | 5126 | where to start the search; |
| 5013 | its default value is 1 and may be negative. | 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 | Returns a string that is the concatenation of <code>n</code> copies of | 5130 | Returns a string that is the concatenation of <code>n</code> copies of |
| 5017 | the string <code>s</code>. | 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 | Returns a string that is the string <code>s</code> reversed. | 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 | Returns the substring of <code>s</code> that | 5137 | Returns the substring of <code>s</code> that |
| 5024 | starts at <code>i</code> and continues until <code>j</code>; | 5138 | starts at <code>i</code> and continues until <code>j</code>; |
| 5025 | <code>i</code> and <code>j</code> may be negative. | 5139 | <code>i</code> and <code>j</code> may be negative. |
| @@ -5031,11 +5145,11 @@ with length <code>j</code>, · 5 unmodified lines |
| 5031 | and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> | 5145 | and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> |
| 5032 | with length <code>i</code>. | 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 | Receives a string and returns a copy of that string with all | 5149 | Receives a string and returns a copy of that string with all |
| 5036 | lowercase letters changed to uppercase. | 5150 | lowercase letters changed to uppercase. |
| 5037 | All other characters are left unchanged. | 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 | <p><a name="pm"></a><h3>Patterns</h3> | 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 | A <em>character class</em> is used to represent a set of characters. | 5157 | A <em>character class</em> is used to represent a set of characters. |
| 5044 | The following combinations are allowed in describing a character class: | 5158 | The following combinations are allowed in describing a character class: |
| 5045 | <ul> | 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 | <code>^$()%.[]*+-?</code>) | 5161 | <code>^$()%.[]*+-?</code>) |
| 5048 | --- represents the character <em>x</em> itself. | 5162 | --- represents the character <em>x</em> itself. |
| 5049 | <li><b><code>.</code></b> --- (a dot) represents all characters. | 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 | a single character class followed by `<code>?</code>´, | 5231 | a single character class followed by `<code>?</code>´, |
| 5118 | which matches 0 or 1 occurrence of a character in the class; | 5232 | which matches 0 or 1 occurrence of a character in the class; |
| 5119 | <li> | 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 | such item matches a substring equal to the <em>n</em>-th captured string | 5235 | such item matches a substring equal to the <em>n</em>-th captured string |
| 5122 | (see below); | 5236 | (see below); |
| 5123 | <li> | 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 | such item matches strings that start with <em>x</em>, end with <em>y</em>, | 5239 | such item matches strings that start with <em>x</em>, end with <em>y</em>, |
| 5126 | and where the <em>x</em> and <em>y</em> are <em>balanced</em>. | 5240 | and where the <em>x</em> and <em>y</em> are <em>balanced</em>. |
| 5127 | This means that, if one reads the string from left to right, | 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 | For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, | 5263 | For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, |
| 5150 | the part of the string matching <code>"a*(.)%w(%s*)"</code> is | 5264 | the part of the string matching <code>"a*(.)%w(%s*)"</code> is |
| 5151 | stored as the first capture (and therefore has number 1); | 5265 | stored as the first capture (and therefore has number 1); |
| 5152 | the character matching <code>.</code> is captured with number 2, | 5266 | the character matching <code>"."</code> is captured with number 2, |
| 5153 | and the part matching <code>%s*</code> has number 3. | 5267 | and the part matching <code>"%s*"</code> has number 3. |
| 5154 | | 5268 | |
| 5155 | <p>As a special case, the empty capture <code>()</code> captures | 5269 | <p>As a special case, the empty capture <code>()</code> captures |
| 5156 | the current string position (a number). | 5270 | the current string position (a number). |
| @@ -5168,14 +5282,14 @@ represents an array or a list. · 11 unmodified lines |
| 5168 | For those functions, when we talk about "the length" of a table | 5282 | For those functions, when we talk about "the length" of a table |
| 5169 | we mean the result of the length operator. | 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 | Returns <code>table[i]..sep..table[i+1] ... sep..table[j]</code>. | 5286 | Returns <code>table[i]..sep..table[i+1] ... sep..table[j]</code>. |
| 5173 | The default value for <code>sep</code> is the empty string, | 5287 | The default value for <code>sep</code> is the empty string, |
| 5174 | the default for <code>i</code> is 1, | 5288 | the default for <code>i</code> is 1, |
| 5175 | and the default for <code>j</code> is the length of the table. | 5289 | and the default for <code>j</code> is the length of the table. |
| 5176 | If <code>i</code> is greater than <code>j</code>, returns the empty string. | 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 | <p>Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, | 5294 | <p>Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, |
| 5181 | shifting up other elements to open space, if necessary. | 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 | so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end | 5298 | so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end |
| 5185 | of table <code>t</code>. | 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 | <p>Returns the largest positive numerical index of the given table, | 5303 | <p>Returns the largest positive numerical index of the given table, |
| 5190 | or zero if the table has no positive numerical indices. | 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 | <p>Removes from <code>table</code> the element at position <code>pos</code>, | 5308 | <p>Removes from <code>table</code> the element at position <code>pos</code>, |
| 5195 | shifting down other elements to close the space, if necessary. | 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 | so that a call <code>table.remove(t)</code> removes the last element | 5313 | so that a call <code>table.remove(t)</code> removes the last element |
| 5200 | of table <code>t</code>. | 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 | Sorts table elements in a given order, <em>in-place</em>, | 5317 | Sorts table elements in a given order, <em>in-place</em>, |
| 5204 | from <code>table[1]</code> to <code>table[n]</code>, | 5318 | from <code>table[1]</code> to <code>table[n]</code>, |
| 5205 | where <code>n</code> is the length of the table. | 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 | If <code>comp</code> is not given, | 5325 | If <code>comp</code> is not given, |
| 5212 | then the standard Lua operator <code><</code> is used instead. | 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 | that is, elements considered equal by the given order | 5329 | that is, elements considered equal by the given order |
| 5216 | may have their relative positions changed by the sort. | 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 | <p><a name="libio"></a><a name="5.7"></a><h2>5.7 - Input and Output Facilities</h2> | 5390 | <p><a name="libio"></a><a name="5.7"></a><h2>5.7 - Input and Output Facilities</h2> |
| 5277 | | 5391 | |
| 5278 | <p>The I/O library provides two different styles for file manipulation. | 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 | that is, there are operations to set a default input file and a | 5394 | that is, there are operations to set a default input file and a |
| 5281 | default output file, | 5395 | default output file, |
| 5282 | and all input/output operations are over those default files. | 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 | (plus an error message as a second result) | 5411 | (plus an error message as a second result) |
| 5298 | and some value different from <b>nil</b> on success. | 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 | <p>Equivalent to <code>file:close()</code>. | 5416 | <p>Equivalent to <code>file:close()</code>. |
| 5303 | Without a <code>file</code>, closes the default output file. | 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 | <p>Equivalent to <code>file:flush</code> over the default output file. | 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 | <p>When called with a file name, it opens the named file (in text mode), | 5425 | <p>When called with a file name, it opens the named file (in text mode), |
| 5312 | and sets its handle as the default input file. | 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 | <p>In case of errors this function raises the error, | 5432 | <p>In case of errors this function raises the error, |
| 5319 | instead of returning an error code. | 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 | <p>Opens the given file name in read mode | 5437 | <p>Opens the given file name in read mode |
| 5324 | and returns an iterator function that, | 5438 | and returns an iterator function that, |
| @@ -5333,11 +5447,11 @@ When the iterator function detects the end of file, · 8 unmodified lines |
| 5333 | it returns <b>nil</b> (to finish the loop) and automatically closes the file. | 5447 | it returns <b>nil</b> (to finish the loop) and automatically closes the file. |
| 5334 | | 5448 | |
| 5335 | <p>The call <code>io.lines()</code> (without a file name) is equivalent | 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 | 5450 | to <code>io.input():lines()</code>; |
| 5337 | lines of the default input file. | 5451 | that is, it iterates over the lines of the default input file. |
| 5338 | In that case it does not close the file when the loop ends. | 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 | <p>This function opens a file, | 5456 | <p>This function opens a file, |
| 5343 | in the mode specified in the string <code>mode</code>. | 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 | <p>The <code>mode</code> string can be any of the following: | 5461 | <p>The <code>mode</code> string can be any of the following: |
| 5348 | <ul> | 5462 | <ul> |
| 5349 | <li><b>"r"</b> read mode (the default); | 5463 | <li><b>"r"</b> --- read mode (the default); |
| 5350 | <li><b>"w"</b> write mode; | 5464 | <li><b>"w"</b> --- write mode; |
| 5351 | <li><b>"a"</b> append mode; | 5465 | <li><b>"a"</b> --- append mode; |
| 5352 | <li><b>"r+"</b> update mode, all previous data is preserved; | 5466 | <li><b>"r+"</b> --- update mode, all previous data is preserved; |
| 5353 | <li><b>"w+"</b> update mode, all previous data is erased; | 5467 | <li><b>"w+"</b> --- update mode, all previous data is erased; |
| 5354 | <li><b>"a+"</b> append update mode, previous data is preserved, | 5468 | <li><b>"a+"</b> --- append update mode, previous data is preserved, |
| 5355 | writing is only allowed at the end of file. | 5469 | writing is only allowed at the end of file. |
| 5356 | </ul> | 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 | which is needed in some systems to open the file in binary mode. | 5472 | which is needed in some systems to open the file in binary mode. |
| 5359 | This string is exactly what is used in the | 5473 | This string is exactly what is used in the |
| 5360 | standard C function <code>fopen</code>. | 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 | <p>Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. | 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 | <p>Starts program <code>prog</code> in a separated process and returns | 5482 | <p>Starts program <code>prog</code> in a separated process and returns |
| 5369 | a file handle that you can use to read data from that program | 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 | (if <code>mode</code> is <code>"w"</code>). | 5486 | (if <code>mode</code> is <code>"w"</code>). |
| 5373 | | 5487 | |
| 5374 | <p>This function is system dependent and is not available | 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 | <p>Equivalent to <code>io.input():read</code>. | 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 | <p>Returns a handle for a temporary file. | 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 | and it is automatically removed when the program ends. | 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 | <p>Checks whether <code>obj</code> is a valid file handle. | 5503 | <p>Checks whether <code>obj</code> is a valid file handle. |
| 5390 | Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, | 5504 | Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, |
| 5391 | <code>"closed file"</code> if <code>obj</code> is a closed file handle, | 5505 | <code>"closed file"</code> if <code>obj</code> is a closed file handle, |
| 5392 | and <b>nil</b> if <code>obj</code> is not a file handle. | 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 | <p>Equivalent to <code>io.output():write</code>. | 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 | <p>Closes <code>file</code>. | 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 | but that takes an unpredictable time to happen. | 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 | <p>Saves any written data to <code>file</code>. | 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 | <p>Returns an iterator function that, | 5525 | <p>Returns an iterator function that, |
| 5411 | each time it is called, | 5526 | each time it is called, |
| @@ -5418,7 +5533,7 @@ will iterate over all lines of the file. · 6 unmodified lines |
| 5418 | (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file | 5533 | (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file |
| 5419 | when the loop ends.) | 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 | <p>Reads the file <code>file</code>, | 5538 | <p>Reads the file <code>file</code>, |
| 5424 | according to the given formats, which specify what to read. | 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 | or <b>nil</b> on end of file. | 5560 | or <b>nil</b> on end of file. |
| 5446 | </ul> | 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 | <p>Sets and gets the file position, | 5565 | <p>Sets and gets the file position, |
| 5451 | measured from the beginning of the file, | 5566 | measured from the beginning of the file, |
| @@ -5470,26 +5585,29 @@ beginning of the file (and returns 0); · 18 unmodified lines |
| 5470 | and the call <code>file:seek("end")</code> sets the position to the | 5585 | and the call <code>file:seek("end")</code> sets the position to the |
| 5471 | end of the file, and returns its size. | 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 | <p>Sets the buffering mode for an output file. | 5590 | <p>Sets the buffering mode for an output file. |
| 5476 | There are three available modes: | 5591 | There are three available modes: |
| 5477 | <ul> | 5592 | <ul> |
| 5478 | <li><b>"no"</b> no buffering; any output operation appear immediately. | 5593 | <li><b>"no"</b> --- |
| 5479 | <li><b>"full"</b> full buffering; output operation is performed only | 5594 | no buffering; the result of any output operation appears immediately. |
| 5480 | when the buffer is full (or when you <code>flush</code> the file (see <a href="#flush">5.7</a>)). | 5595 | <li><b>"full"</b> --- |
| 5481 | <li><b>"line"</b> line buffering; output is buffered until a newline is | 5596 | full buffering; output operation is performed only |
| 5482 | output or there is any input from some special files | 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 | (such as a terminal device). | 5601 | (such as a terminal device). |
| 5484 | </ul> | 5602 | </ul> |
| 5485 | For the last two cases, <code>sizes</code> | 5603 | For the last two cases, <code>sizes</code> |
| 5486 | specifies the size of the buffer, in bytes. | 5604 | specifies the size of the buffer, in bytes. |
| 5487 | The default is an appropriate size. | 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 | <p>Writes the value of each of its arguments to | 5609 | <p>Writes the value of each of its arguments to |
| 5492 | the filehandle <code>file</code>. | 5610 | the <code>file</code>. |
| 5493 | The arguments must be strings or numbers. | 5611 | The arguments must be strings or numbers. |
| 5494 | To write other values, | 5612 | To write other values, |
| 5495 | use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. | 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 | <p>This library is implemented through table <code>os</code>. | 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 | 5621 | <p>Returns an approximation of the amount in seconds of CPU time |
| 5504 | used by the program, in seconds. | 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 | <p>Returns a string or a table containing date and time, | 5626 | <p>Returns a string or a table containing date and time, |
| 5509 | formatted according to the given string <code>format</code>. | 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 | the host system and on the current locale | 5651 | the host system and on the current locale |
| 5534 | (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). | 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 | <p>Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. | 5656 | <p>Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. |
| 5539 | In Posix, Windows, and some other systems, | 5657 | In Posix, Windows, and some other systems, |
| 5540 | this value is exactly <code>t2</code><em>-</em><code>t1</code>. | 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 | <p>This function is equivalent to the C function <code>system</code>. | 5662 | <p>This function is equivalent to the C function <code>system</code>. |
| 5545 | It passes <code>command</code> to be executed by an operating system shell. | 5663 | It passes <code>command</code> to be executed by an operating system shell. |
| 5546 | It returns a status code, which is system-dependent. | 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 | <p>Calls the C function <code>exit</code>, | 5670 | <p>Calls the C function <code>exit</code>, |
| 5551 | with an optional <code>code</code>, | 5671 | with an optional <code>code</code>, |
| 5552 | to terminate the host program. | 5672 | to terminate the host program. |
| 5553 | The default value for <code>code</code> is the success code. | 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 | <p>Returns the value of the process environment variable <code>varname</code>, | 5677 | <p>Returns the value of the process environment variable <code>varname</code>, |
| 5558 | or <b>nil</b> if the variable is not defined. | 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 | If this function fails, it returns <b>nil</b>, | 5684 | If this function fails, it returns <b>nil</b>, |
| 5564 | plus a string describing the error. | 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 | If this function fails, it returns <b>nil</b>, | 5690 | If this function fails, it returns <b>nil</b>, |
| 5570 | plus a string describing the error. | 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 | <p>Sets the current locale of the program. | 5695 | <p>Sets the current locale of the program. |
| 5575 | <code>locale</code> is a string specifying a locale; | 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 | The function returns the name of the new locale, | 5701 | The function returns the name of the new locale, |
| 5581 | or <b>nil</b> if the request cannot be honored. | 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 | <p>Returns the current time when called without arguments, | 5706 | <p>Returns the current time when called without arguments, |
| 5586 | or a time representing the date and time specified by the given table. | 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 | and the number returned by <code>time</code> can be used only as an argument to | 5716 | and the number returned by <code>time</code> can be used only as an argument to |
| 5596 | <code>date</code> and <code>difftime</code>. | 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 | <p>Returns a string with a file name that can | 5721 | <p>Returns a string with a file name that can |
| 5601 | be used for a temporary file. | 5722 | be used for a temporary file. |
| 5602 | The file must be explicitly opened before its use | 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 | the functionality of the debug interface to Lua programs. | 5729 | the functionality of the debug interface to Lua programs. |
| 5609 | You should exert care when using this library. | 5730 | You should exert care when using this library. |
| 5610 | The functions provided here should be used exclusively for debugging | 5731 | The functions provided here should be used exclusively for debugging |
| @@ -5614,14 +5735,15 @@ usual programming tool: · 3 unmodified lines |
| 5614 | They can be very slow. | 5735 | They can be very slow. |
| 5615 | Moreover, several of its functions | 5736 | Moreover, several of its functions |
| 5616 | violate some assumptions about Lua code | 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 | that userdata metatables cannot be changed by Lua code) | 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 | <p>All functions in this library are provided | 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 | <p>Enters an interactive mode with the user, | 5748 | <p>Enters an interactive mode with the user, |
| 5627 | running each string that the user enters. | 5749 | running each string that the user enters. |
| @@ -5631,22 +5753,22 @@ change their values, evaluate expressions, and so on. · 3 unmodified lines |
| 5631 | A line containing only the word <code>cont</code> finishes this function, | 5753 | A line containing only the word <code>cont</code> finishes this function, |
| 5632 | so that the caller continues its execution. | 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 | 5756 | <p>Note that commands for <code>debug.debug</code> are not lexically nested |
| 5635 | with any function, so they have no direct access to local variables. | 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 | Returns the environment of object <code>o</code>. | 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 | <p>Returns the current hook settings, as three values: | 5764 | <p>Returns the current hook settings, as three values: |
| 5643 | the current hook function, the current hook mask, | 5765 | the current hook function, the current hook mask, |
| 5644 | and the current hook count | 5766 | and the current hook count |
| 5645 | (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). | 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 | You can give the function directly, | 5772 | You can give the function directly, |
| 5651 | or you can give a number as the value of <code>function</code>, | 5773 | or you can give a number as the value of <code>function</code>, |
| 5652 | which means the function running at level <code>function</code> of the call stack: | 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 | adds a field named <code>func</code> with the function itself. | 5786 | adds a field named <code>func</code> with the function itself. |
| 5665 | | 5787 | |
| 5666 | <p>For instance, the expression <code>debug.getinfo(1,"n").name</code> returns | 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 | and <code>debug.getinfo(print)</code> returns a table with all available information | 5790 | and <code>debug.getinfo(print)</code> returns a table with all available information |
| 5669 | about the <a href="#pdf-print"><code>print</code></a> function. | 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 | <p>This function returns the name and the value of the local variable | 5795 | <p>This function returns the name and the value of the local variable |
| 5674 | with index <code>local</code> of the function at level <code>level</code> of the stack. | 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 | represent internal variables | 5805 | represent internal variables |
| 5684 | (loop control variables, temporaries, and C function locals). | 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>. | 5810 | <p>Returns the metatable of the given <code>object</code> |
| 5689 | Otherwise, returns the metatable of the given object. | 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 | <p>Returns the registry table (see <a href="#registry">3.5</a>). | 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 | <p>This function returns the name and the value of the upvalue | 5819 | <p>This function returns the name and the value of the upvalue |
| 5698 | with index <code>up</code> of the function <code>func</code>. | 5820 | with index <code>up</code> of the function <code>func</code>. |
| 5699 | The function returns <b>nil</b> if there is no upvalue with the given index. | 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 | <p>Sets the given function as a hook. | 5829 | <p>Sets the given function as a hook. |
| 5708 | The string <code>mask</code> and the number <code>count</code> describe | 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 | The string mask may have the following characters, | 5832 | The string mask may have the following characters, |
| 5711 | with the given meaning: | 5833 | with the given meaning: |
| 5712 | <ul> | 5834 | <ul> |
| 5713 | <li><b><code>"c"</code></b> The hook is called every time Lua calls a function; | 5835 | <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; | 5836 | <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. | 5837 | <li><b><code>"l"</code></b> --- The hook is called every time Lua enters a new line of code. |
| 5716 | </ul> | 5838 | </ul> |
| 5717 | With a <code>count</code> different from zero, | 5839 | With a <code>count</code> different from zero, |
| 5718 | the hook is called after every <code>count</code> instructions. | 5840 | the hook is called after every <code>count</code> instructions. |
| 5719 | | 5841 | |
| 5720 | <p>When called without arguments, | 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 | 5845 | <p>When the hook is called, its first parameter is a string |
| 5724 | describing the event that triggered its call: | 5846 | describing the event that has triggered its call: |
| 5725 | <code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>), | 5847 | <code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>), |
| 5726 | <code>"line"</code>, and <code>"count"</code>. | 5848 | <code>"line"</code>, and <code>"count"</code>. |
| 5727 | Moreover, for line events, | 5849 | For line events, |
| 5728 | it also gets as its second parameter the new line number. | 5850 | the hook also gets the new line number as its second parameter. |
| 5729 | Inside a hook, | 5851 | Inside a hook, |
| 5730 | you can call <code>getinfo</code> with level 2 to get more information about | 5852 | you can call <code>getinfo</code> with level 2 to get more information about |
| 5731 | the running function | 5853 | the running function |
| @@ -5735,7 +5857,7 @@ unless the event is <code>"tail return"</code>. · 3 unmodified lines |
| 5735 | In this case, Lua is only simulating the return, | 5857 | In this case, Lua is only simulating the return, |
| 5736 | and a call to <code>getinfo</code> will return invalid data. | 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 | <p>This function assigns the value <code>value</code> to the local variable | 5862 | <p>This function assigns the value <code>value</code> to the local variable |
| 5741 | with index <code>local</code> of the function at level <code>level</code> of the stack. | 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 | (You can call <code>getinfo</code> to check whether the level is valid.) | 5867 | (You can call <code>getinfo</code> to check whether the level is valid.) |
| 5746 | Otherwise, it returns the name of the local variable. | 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 | <p>This function assigns the value <code>value</code> to the upvalue | 5877 | <p>This function assigns the value <code>value</code> to the upvalue |
| 5755 | with index <code>up</code> of the function <code>func</code>. | 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 | with the given index. | 5880 | with the given index. |
| 5758 | Otherwise, it returns the name of the upvalue. | 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 | <p>Returns a string with a traceback of the call stack. | 5885 | <p>Returns a string with a traceback of the call stack. |
| 5763 | An optional <code>message</code> string is appended | 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 | called simply <code>lua</code>, | 5898 | called simply <code>lua</code>, |
| 5776 | is provided with the standard distribution. | 5899 | is provided with the standard distribution. |
| 5777 | The stand-alone interpreter includes | 5900 | The stand-alone interpreter includes |
| 5778 | all standard libraries plus the reflexive debug interface. | 5901 | all standard libraries, including the debug library. |
| 5779 | Its usage is: | 5902 | Its usage is: |
| 5780 | <pre> | 5903 | <pre> |
| 5781 | lua [options] [script [args]] | 5904 | lua [options] [script [args]] |
| @@ -5790,30 +5913,31 @@ The options are: · 8 unmodified lines |
| 5790 | <li><b><code>-</code> </b> executes <code>stdin</code> as a file and stops handling options. | 5913 | <li><b><code>-</code> </b> executes <code>stdin</code> as a file and stops handling options. |
| 5791 | </ul> | 5914 | </ul> |
| 5792 | After handling its options, <code>lua</code> runs the given <em>script</em>, | 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 | When called without arguments, | 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 | and as <code>lua -</code> otherwise. | 5920 | and as <code>lua -</code> otherwise. |
| 5797 | | 5921 | |
| 5798 | <p>Before running any argument, | 5922 | <p>Before running any argument, |
| 5799 | the interpreter checks for an environment variable <code>LUA_INIT</code>. | 5923 | the interpreter checks for an environment variable <code>LUA_INIT</code>. |
| 5800 | If its format is @<em>filename</em>, | 5924 | If its format is @<em>filename</em>, |
| 5801 | then lua executes the file. | 5925 | then <code>lua</code> executes the file. |
| 5802 | Otherwise, lua executes the string itself. | 5926 | Otherwise, <code>lua</code> executes the string itself. |
| 5803 | | 5927 | |
| 5804 | <p>All options are handled in order, except <code>-i</code>. | 5928 | <p>All options are handled in order, except <code>-i</code>. |
| 5805 | For instance, an invocation like | 5929 | For instance, an invocation like |
| 5806 | <pre> | 5930 | <pre> |
| 5807 | $ lua -e'a=1' -e 'print(a)' script.lua | 5931 | $ lua -e'a=1' -e 'print(a)' script.lua |
| 5808 | </pre> | 5932 | </pre> |
| 5809 | will first set <code>a</code> to 1, then print <code>a</code>, | 5933 | will first set <code>a</code> to 1, then print the value of <code>a</code> (which is `<code>1</code>´), |
| 5810 | and finally run the file <code>script.lua</code>. | 5934 | and finally run the file <code>script.lua</code> with no arguments. |
| 5811 | (Here <code>$</code> is the shell prompt. Your prompt may be different.) | 5935 | (Here <code>$</code> is the shell prompt. Your prompt may be different.) |
| 5812 | | 5936 | |
| 5813 | <p>Before starting to run the script, | 5937 | <p>Before starting to run the script, |
| 5814 | <code>lua</code> collects all arguments in the command line | 5938 | <code>lua</code> collects all arguments in the command line |
| 5815 | in a global table called <code>arg</code>. | 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 | the first argument after the script name goes to index 1, | 5941 | the first argument after the script name goes to index 1, |
| 5818 | and so on. | 5942 | and so on. |
| 5819 | Any arguments before the script name | 5943 | Any arguments before the script name |
| @@ -5821,34 +5945,40 @@ Any arguments before the script name · 1 unmodified line |
| 5821 | go to negative indices. | 5945 | go to negative indices. |
| 5822 | For instance, in the call | 5946 | For instance, in the call |
| 5823 | <pre> | 5947 | <pre> |
| 5824 | $ lua -la.lua b.lua t1 t2 | 5948 | $ lua -la b.lua t1 t2 |
| 5825 | </pre> | 5949 | </pre> |
| 5826 | the interpreter first runs the file <code>a.lua</code>, | 5950 | the interpreter first runs the file <code>a.lua</code>, |
| 5827 | then creates a table | 5951 | then creates a table |
| 5828 | <pre> | 5952 | <pre> |
| 5829 | arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", | 5953 | arg = { [-2] = "lua", [-1] = "-la", |
| | 5954 | [0] = "b.lua", |
| 5830 | [1] = "t1", [2] = "t2" } | 5955 | [1] = "t1", [2] = "t2" } |
| 5831 | </pre> | 5956 | </pre> |
| 5832 | and finally runs the file <code>b.lua</code>. | 5957 | and finally runs the file <code>b.lua</code>. |
| 5833 | The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... | 5958 | The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... |
| 5834 | as arguments; | 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 | <p>In interactive mode, | 5962 | <p>In interactive mode, |
| 5838 | if you write an incomplete statement, | 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 | then its value is used as the prompt. | 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 | <pre> | 5974 | <pre> |
| 5845 | $ lua -e"_PROMPT='myprompt> '" -i | 5975 | $ lua -e"_PROMPT='myprompt> '" -i |
| 5846 | </pre> | 5976 | </pre> |
| 5847 | (the outer pair of quotes is for the shell, | 5977 | (the outer pair of quotes is for the shell, |
| 5848 | the inner is for Lua), | 5978 | the inner pair is for Lua), |
| 5849 | or in any Lua programs by assigning to <code>_PROMPT</code>. | 5979 | or in any Lua programs by assigning to <code>_PROMPT</code>. |
| 5850 | Note the use of <code>-i</code> to enter interactive mode; otherwise, | 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 | <p>To allow the use of Lua as a | 5983 | <p>To allow the use of Lua as a |
| 5854 | script interpreter in Unix systems, | 5984 | script interpreter in Unix systems, |
| @@ -5869,17 +5999,17 @@ then · 14 unmodified lines |
| 5869 | </pre> | 5999 | </pre> |
| 5870 | is a more portable solution.) | 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 | from Lua 5.0 to Lua 5.1. | 6008 | from Lua 5.0 to Lua 5.1. |
| 5879 | You can avoid most of the incompatibilities compiling Lua with | 6009 | You can avoid most of the incompatibilities compiling Lua with |
| 5880 | appropriate options. | 6010 | appropriate options (see file <code>luaconf.h</code>). |
| 5881 | However, | 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 | <p><h2>Incompatibilities with version 5.0</h2> | 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 | <li> | 6018 | <li> |
| 5889 | The vararg system changed from the pseudo-argument <code>arg</code> with a | 6019 | The vararg system changed from the pseudo-argument <code>arg</code> with a |
| 5890 | table with the extra arguments to the vararg expression. | 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 | <p><li> | 6023 | <p><li> |
| 5894 | There was a subtle change in the scope of the implicit | 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 | <p><li> | 6027 | <p><li> |
| 5898 | The long string/long comment syntax (<code>[[...]]</code>) does not allow nesting. | 6028 | The long string/long comment syntax (<code>[[...]]</code>) does not allow nesting. |
| 5899 | You can use the new syntax (<code>[=[...]=]</code>) in those cases. | 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 | <p></ul> | 6032 | <p></ul> |
| 5903 | | 6033 | |
| 5904 | <p><h3>Changes in the Libraries</h3> | 6034 | <p><h3>Changes in the Libraries</h3> |
| 5905 | <ul> | 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 | <p><li> | 6037 | <p><li> |
| 5912 | Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. | 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 | (Option <code>LUA_COMPAT_MOD</code>) | 6061 | (Option <code>LUA_COMPAT_MOD</code>) |
| 5936 | | 6062 | |
| 5937 | <p><li> | 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 | the new module system. | 6065 | the new module system. |
| 5940 | However, the new behavior is mostly compatible with the old, | 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 | of from <code>LUA_PATH</code>. | 6068 | of from <code>LUA_PATH</code>. |
| 5943 | | 6069 | |
| 5944 | <p><li> | 6070 | <p><li> |
| @@ -5952,7 +6078,7 @@ use <code>collectgarbage("count")</code> instead. · 7 unmodified lines |
| 5952 | <ul> | 6078 | <ul> |
| 5953 | <li> | 6079 | <li> |
| 5954 | Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to | 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 | You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to | 6082 | You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to |
| 5957 | create a state with a standard allocation function | 6083 | create a state with a standard allocation function |
| 5958 | (based on <code>realloc</code>). | 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 | <a name="BNF"></a><h1>The Complete Syntax of Lua</h1> | 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 | <p> | 6107 | <p> |
| 5977 | | 6108 | |
| 5978 | <p><pre> | 6109 | <p><pre> |
| @@ -5991,7 +6122,7 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod · 12 unmodified lines |
| 5991 | <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> | | 6122 | <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> | |
| 5992 | <b>function</b> funcname funcbody | | 6123 | <b>function</b> funcname funcbody | |
| 5993 | <b>local</b> <b>function</b> Name funcbody | | 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 | laststat ::= <b>return</b> [explist1] | <b>break</b> | 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 | namelist ::= Name {`<b>,</b>´ Name} | 6135 | namelist ::= Name {`<b>,</b>´ Name} |
| 6005 | | 6136 | |
| 6006 | init ::= `<b>=</b>´ explist1 | | |
| 6007 | | | |
| 6008 | explist1 ::= {exp `<b>,</b>´} exp | 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 | function | prefixexp | tableconstructor | exp binop exp | unop exp | 6140 | function | prefixexp | tableconstructor | exp binop exp | unop exp |
| 6012 | | 6141 | |
| 6013 | prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ | 6142 | prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ |
| 6014 | | 6143 | |
| 6015 | functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args | 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 | function ::= <b>function</b> funcbody | 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 | fieldlist ::= field {fieldsep field} [fieldsep] | 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 | fieldsep ::= `<b>,</b>´ | `<b>;</b>´ | 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 | <p> | 6172 | <p> |
| 6044 | | 6173 | |
| 6045 | <HR> | | |
| 6046 | <SMALL> | | |
| 6047 | Last update: | | |
| 6048 | Tue Nov 1 15:20:21 BRST 2005 | | |
| 6049 | </SMALL> | | |
| 6050 | | | |
| 6051 | </body></html> | 6174 | </body></html> |
| | 6175 | |