diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/LuaJIT-1.1.7/doc/manual.html | 8801 |
1 files changed, 0 insertions, 8801 deletions
diff --git a/libraries/LuaJIT-1.1.7/doc/manual.html b/libraries/LuaJIT-1.1.7/doc/manual.html deleted file mode 100644 index f46f17c..0000000 --- a/libraries/LuaJIT-1.1.7/doc/manual.html +++ /dev/null | |||
@@ -1,8801 +0,0 @@ | |||
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | ||
2 | <html> | ||
3 | |||
4 | <head> | ||
5 | <title>Lua 5.1 Reference Manual</title> | ||
6 | <link rel="stylesheet" type="text/css" href="lua.css"> | ||
7 | <link rel="stylesheet" type="text/css" href="manual.css"> | ||
8 | <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> | ||
9 | </head> | ||
10 | |||
11 | <body> | ||
12 | |||
13 | <hr> | ||
14 | <h1> | ||
15 | <a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> | ||
16 | Lua 5.1 Reference Manual | ||
17 | </h1> | ||
18 | |||
19 | by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes | ||
20 | <p> | ||
21 | <small> | ||
22 | Copyright © 2006-2008 Lua.org, PUC-Rio. | ||
23 | Freely available under the terms of the | ||
24 | <a href="http://www.lua.org/license.html#5">Lua license</a>. | ||
25 | </small> | ||
26 | <hr> | ||
27 | <p> | ||
28 | |||
29 | <a href="contents.html#contents">contents</A> | ||
30 | · | ||
31 | <a href="contents.html#index">index</A> | ||
32 | |||
33 | <!-- ====================================================================== --> | ||
34 | <p> | ||
35 | |||
36 | <!-- $Id: manual.of,v 1.48 2008/08/18 15:24:20 roberto Exp $ --> | ||
37 | |||
38 | |||
39 | |||
40 | |||
41 | <h1>1 - <a name="1">Introduction</a></h1> | ||
42 | |||
43 | <p> | ||
44 | Lua is an extension programming language designed to support | ||
45 | general procedural programming with data description | ||
46 | facilities. | ||
47 | It also offers good support for object-oriented programming, | ||
48 | functional programming, and data-driven programming. | ||
49 | Lua is intended to be used as a powerful, light-weight | ||
50 | scripting language for any program that needs one. | ||
51 | Lua is implemented as a library, written in <em>clean</em> C | ||
52 | (that is, in the common subset of ANSI C and C++). | ||
53 | |||
54 | |||
55 | <p> | ||
56 | Being an extension language, Lua has no notion of a "main" program: | ||
57 | it only works <em>embedded</em> in a host client, | ||
58 | called the <em>embedding program</em> or simply the <em>host</em>. | ||
59 | This host program can invoke functions to execute a piece of Lua code, | ||
60 | can write and read Lua variables, | ||
61 | and can register C functions to be called by Lua code. | ||
62 | Through the use of C functions, Lua can be augmented to cope with | ||
63 | a wide range of different domains, | ||
64 | thus creating customized programming languages sharing a syntactical framework. | ||
65 | The Lua distribution includes a sample host program called <code>lua</code>, | ||
66 | which uses the Lua library to offer a complete, stand-alone Lua interpreter. | ||
67 | |||
68 | |||
69 | <p> | ||
70 | Lua is free software, | ||
71 | and is provided as usual with no guarantees, | ||
72 | as stated in its license. | ||
73 | The implementation described in this manual is available | ||
74 | at Lua's official web site, <code>www.lua.org</code>. | ||
75 | |||
76 | |||
77 | <p> | ||
78 | Like any other reference manual, | ||
79 | this document is dry in places. | ||
80 | For a discussion of the decisions behind the design of Lua, | ||
81 | see the technical papers available at Lua's web site. | ||
82 | For a detailed introduction to programming in Lua, | ||
83 | see Roberto's book, <em>Programming in Lua (Second Edition)</em>. | ||
84 | |||
85 | |||
86 | |||
87 | <h1>2 - <a name="2">The Language</a></h1> | ||
88 | |||
89 | <p> | ||
90 | This section describes the lexis, the syntax, and the semantics of Lua. | ||
91 | In other words, | ||
92 | this section describes | ||
93 | which tokens are valid, | ||
94 | how they can be combined, | ||
95 | and what their combinations mean. | ||
96 | |||
97 | |||
98 | <p> | ||
99 | The language constructs will be explained using the usual extended BNF notation, | ||
100 | in which | ||
101 | {<em>a</em>} means 0 or more <em>a</em>'s, and | ||
102 | [<em>a</em>] means an optional <em>a</em>. | ||
103 | Non-terminals are shown like non-terminal, | ||
104 | keywords are shown like <b>kword</b>, | ||
105 | and other terminal symbols are shown like `<b>=</b>´. | ||
106 | The complete syntax of Lua can be found in <a href="#8">§8</a> | ||
107 | at the end of this manual. | ||
108 | |||
109 | |||
110 | |||
111 | <h2>2.1 - <a name="2.1">Lexical Conventions</a></h2> | ||
112 | |||
113 | <p> | ||
114 | <em>Names</em> | ||
115 | (also called <em>identifiers</em>) | ||
116 | in Lua can be any string of letters, | ||
117 | digits, and underscores, | ||
118 | not beginning with a digit. | ||
119 | This coincides with the definition of names in most languages. | ||
120 | (The definition of letter depends on the current locale: | ||
121 | any character considered alphabetic by the current locale | ||
122 | can be used in an identifier.) | ||
123 | Identifiers are used to name variables and table fields. | ||
124 | |||
125 | |||
126 | <p> | ||
127 | The following <em>keywords</em> are reserved | ||
128 | and cannot be used as names: | ||
129 | |||
130 | |||
131 | <pre> | ||
132 | and break do else elseif | ||
133 | end false for function if | ||
134 | in local nil not or | ||
135 | repeat return then true until while | ||
136 | </pre> | ||
137 | |||
138 | <p> | ||
139 | Lua is a case-sensitive language: | ||
140 | <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> | ||
141 | are two different, valid names. | ||
142 | As a convention, names starting with an underscore followed by | ||
143 | uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) | ||
144 | are reserved for internal global variables used by Lua. | ||
145 | |||
146 | |||
147 | <p> | ||
148 | The following strings denote other tokens: | ||
149 | |||
150 | <pre> | ||
151 | + - * / % ^ # | ||
152 | == ~= <= >= < > = | ||
153 | ( ) { } [ ] | ||
154 | ; : , . .. ... | ||
155 | </pre> | ||
156 | |||
157 | <p> | ||
158 | <em>Literal strings</em> | ||
159 | can be delimited by matching single or double quotes, | ||
160 | and can contain the following C-like escape sequences: | ||
161 | '<code>\a</code>' (bell), | ||
162 | '<code>\b</code>' (backspace), | ||
163 | '<code>\f</code>' (form feed), | ||
164 | '<code>\n</code>' (newline), | ||
165 | '<code>\r</code>' (carriage return), | ||
166 | '<code>\t</code>' (horizontal tab), | ||
167 | '<code>\v</code>' (vertical tab), | ||
168 | '<code>\\</code>' (backslash), | ||
169 | '<code>\"</code>' (quotation mark [double quote]), | ||
170 | and '<code>\'</code>' (apostrophe [single quote]). | ||
171 | Moreover, a backslash followed by a real newline | ||
172 | results in a newline in the string. | ||
173 | A character in a string can also be specified by its numerical value | ||
174 | using the escape sequence <code>\<em>ddd</em></code>, | ||
175 | where <em>ddd</em> is a sequence of up to three decimal digits. | ||
176 | (Note that if a numerical escape is to be followed by a digit, | ||
177 | it must be expressed using exactly three digits.) | ||
178 | Strings in Lua can contain any 8-bit value, including embedded zeros, | ||
179 | which can be specified as '<code>\0</code>'. | ||
180 | |||
181 | |||
182 | <p> | ||
183 | Literal strings can also be defined using a long format | ||
184 | enclosed by <em>long brackets</em>. | ||
185 | We define an <em>opening long bracket of level <em>n</em></em> as an opening | ||
186 | square bracket followed by <em>n</em> equal signs followed by another | ||
187 | opening square bracket. | ||
188 | So, an opening long bracket of level 0 is written as <code>[[</code>, | ||
189 | an opening long bracket of level 1 is written as <code>[=[</code>, | ||
190 | and so on. | ||
191 | A <em>closing long bracket</em> is defined similarly; | ||
192 | for instance, a closing long bracket of level 4 is written as <code>]====]</code>. | ||
193 | A long string starts with an opening long bracket of any level and | ||
194 | ends at the first closing long bracket of the same level. | ||
195 | Literals in this bracketed form can run for several lines, | ||
196 | do not interpret any escape sequences, | ||
197 | and ignore long brackets of any other level. | ||
198 | They can contain anything except a closing bracket of the proper level. | ||
199 | |||
200 | |||
201 | <p> | ||
202 | For convenience, | ||
203 | when the opening long bracket is immediately followed by a newline, | ||
204 | the newline is not included in the string. | ||
205 | As an example, in a system using ASCII | ||
206 | (in which '<code>a</code>' is coded as 97, | ||
207 | newline is coded as 10, and '<code>1</code>' is coded as 49), | ||
208 | the five literal strings below denote the same string: | ||
209 | |||
210 | <pre> | ||
211 | a = 'alo\n123"' | ||
212 | a = "alo\n123\"" | ||
213 | a = '\97lo\10\04923"' | ||
214 | a = [[alo | ||
215 | 123"]] | ||
216 | a = [==[ | ||
217 | alo | ||
218 | 123"]==] | ||
219 | </pre> | ||
220 | |||
221 | <p> | ||
222 | A <em>numerical constant</em> can be written with an optional decimal part | ||
223 | and an optional decimal exponent. | ||
224 | Lua also accepts integer hexadecimal constants, | ||
225 | by prefixing them with <code>0x</code>. | ||
226 | Examples of valid numerical constants are | ||
227 | |||
228 | <pre> | ||
229 | 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 | ||
230 | </pre> | ||
231 | |||
232 | <p> | ||
233 | A <em>comment</em> starts with a double hyphen (<code>--</code>) | ||
234 | anywhere outside a string. | ||
235 | If the text immediately after <code>--</code> is not an opening long bracket, | ||
236 | the comment is a <em>short comment</em>, | ||
237 | which runs until the end of the line. | ||
238 | Otherwise, it is a <em>long comment</em>, | ||
239 | which runs until the corresponding closing long bracket. | ||
240 | Long comments are frequently used to disable code temporarily. | ||
241 | |||
242 | |||
243 | |||
244 | |||
245 | |||
246 | <h2>2.2 - <a name="2.2">Values and Types</a></h2> | ||
247 | |||
248 | <p> | ||
249 | Lua is a <em>dynamically typed language</em>. | ||
250 | This means that | ||
251 | variables do not have types; only values do. | ||
252 | There are no type definitions in the language. | ||
253 | All values carry their own type. | ||
254 | |||
255 | |||
256 | <p> | ||
257 | All values in Lua are <em>first-class values</em>. | ||
258 | This means that all values can be stored in variables, | ||
259 | passed as arguments to other functions, and returned as results. | ||
260 | |||
261 | |||
262 | <p> | ||
263 | There are eight basic types in Lua: | ||
264 | <em>nil</em>, <em>boolean</em>, <em>number</em>, | ||
265 | <em>string</em>, <em>function</em>, <em>userdata</em>, | ||
266 | <em>thread</em>, and <em>table</em>. | ||
267 | <em>Nil</em> is the type of the value <b>nil</b>, | ||
268 | whose main property is to be different from any other value; | ||
269 | it usually represents the absence of a useful value. | ||
270 | <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. | ||
271 | Both <b>nil</b> and <b>false</b> make a condition false; | ||
272 | any other value makes it true. | ||
273 | <em>Number</em> represents real (double-precision floating-point) numbers. | ||
274 | (It is easy to build Lua interpreters that use other | ||
275 | internal representations for numbers, | ||
276 | such as single-precision float or long integers; | ||
277 | see file <code>luaconf.h</code>.) | ||
278 | <em>String</em> represents arrays of characters. | ||
279 | |||
280 | Lua is 8-bit clean: | ||
281 | strings can contain any 8-bit character, | ||
282 | including embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>). | ||
283 | |||
284 | |||
285 | <p> | ||
286 | Lua can call (and manipulate) functions written in Lua and | ||
287 | functions written in C | ||
288 | (see <a href="#2.5.8">§2.5.8</a>). | ||
289 | |||
290 | |||
291 | <p> | ||
292 | The type <em>userdata</em> is provided to allow arbitrary C data to | ||
293 | be stored in Lua variables. | ||
294 | This type corresponds to a block of raw memory | ||
295 | and has no pre-defined operations in Lua, | ||
296 | except assignment and identity test. | ||
297 | However, by using <em>metatables</em>, | ||
298 | the programmer can define operations for userdata values | ||
299 | (see <a href="#2.8">§2.8</a>). | ||
300 | Userdata values cannot be created or modified in Lua, | ||
301 | only through the C API. | ||
302 | This guarantees the integrity of data owned by the host program. | ||
303 | |||
304 | |||
305 | <p> | ||
306 | The type <em>thread</em> represents independent threads of execution | ||
307 | and it is used to implement coroutines (see <a href="#2.11">§2.11</a>). | ||
308 | Do not confuse Lua threads with operating-system threads. | ||
309 | Lua supports coroutines on all systems, | ||
310 | even those that do not support threads. | ||
311 | |||
312 | |||
313 | <p> | ||
314 | The type <em>table</em> implements associative arrays, | ||
315 | that is, arrays that can be indexed not only with numbers, | ||
316 | but with any value (except <b>nil</b>). | ||
317 | Tables can be <em>heterogeneous</em>; | ||
318 | that is, they can contain values of all types (except <b>nil</b>). | ||
319 | Tables are the sole data structuring mechanism in Lua; | ||
320 | they can be used to represent ordinary arrays, | ||
321 | symbol tables, sets, records, graphs, trees, etc. | ||
322 | To represent records, Lua uses the field name as an index. | ||
323 | The language supports this representation by | ||
324 | providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. | ||
325 | There are several convenient ways to create tables in Lua | ||
326 | (see <a href="#2.5.7">§2.5.7</a>). | ||
327 | |||
328 | |||
329 | <p> | ||
330 | Like indices, | ||
331 | the value of a table field can be of any type (except <b>nil</b>). | ||
332 | In particular, | ||
333 | because functions are first-class values, | ||
334 | table fields can contain functions. | ||
335 | Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>). | ||
336 | |||
337 | |||
338 | <p> | ||
339 | Tables, functions, threads, and (full) userdata values are <em>objects</em>: | ||
340 | variables do not actually <em>contain</em> these values, | ||
341 | only <em>references</em> to them. | ||
342 | Assignment, parameter passing, and function returns | ||
343 | always manipulate references to such values; | ||
344 | these operations do not imply any kind of copy. | ||
345 | |||
346 | |||
347 | <p> | ||
348 | The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type | ||
349 | of a given value. | ||
350 | |||
351 | |||
352 | |||
353 | <h3>2.2.1 - <a name="2.2.1">Coercion</a></h3> | ||
354 | |||
355 | <p> | ||
356 | Lua provides automatic conversion between | ||
357 | string and number values at run time. | ||
358 | Any arithmetic operation applied to a string tries to convert | ||
359 | this string to a number, following the usual conversion rules. | ||
360 | Conversely, whenever a number is used where a string is expected, | ||
361 | the number is converted to a string, in a reasonable format. | ||
362 | For complete control over how numbers are converted to strings, | ||
363 | use the <code>format</code> function from the string library | ||
364 | (see <a href="#pdf-string.format"><code>string.format</code></a>). | ||
365 | |||
366 | |||
367 | |||
368 | |||
369 | |||
370 | |||
371 | |||
372 | <h2>2.3 - <a name="2.3">Variables</a></h2> | ||
373 | |||
374 | <p> | ||
375 | Variables are places that store values. | ||
376 | |||
377 | There are three kinds of variables in Lua: | ||
378 | global variables, local variables, and table fields. | ||
379 | |||
380 | |||
381 | <p> | ||
382 | A single name can denote a global variable or a local variable | ||
383 | (or a function's formal parameter, | ||
384 | which is a particular kind of local variable): | ||
385 | |||
386 | <pre> | ||
387 | var ::= Name | ||
388 | </pre><p> | ||
389 | Name denotes identifiers, as defined in <a href="#2.1">§2.1</a>. | ||
390 | |||
391 | |||
392 | <p> | ||
393 | Any variable is assumed to be global unless explicitly declared | ||
394 | as a local (see <a href="#2.4.7">§2.4.7</a>). | ||
395 | Local variables are <em>lexically scoped</em>: | ||
396 | local variables can be freely accessed by functions | ||
397 | defined inside their scope (see <a href="#2.6">§2.6</a>). | ||
398 | |||
399 | |||
400 | <p> | ||
401 | Before the first assignment to a variable, its value is <b>nil</b>. | ||
402 | |||
403 | |||
404 | <p> | ||
405 | Square brackets are used to index a table: | ||
406 | |||
407 | <pre> | ||
408 | var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´ | ||
409 | </pre><p> | ||
410 | The meaning of accesses to global variables | ||
411 | and table fields can be changed via metatables. | ||
412 | An access to an indexed variable <code>t[i]</code> is equivalent to | ||
413 | a call <code>gettable_event(t,i)</code>. | ||
414 | (See <a href="#2.8">§2.8</a> for a complete description of the | ||
415 | <code>gettable_event</code> function. | ||
416 | This function is not defined or callable in Lua. | ||
417 | We use it here only for explanatory purposes.) | ||
418 | |||
419 | |||
420 | <p> | ||
421 | The syntax <code>var.Name</code> is just syntactic sugar for | ||
422 | <code>var["Name"]</code>: | ||
423 | |||
424 | <pre> | ||
425 | var ::= prefixexp `<b>.</b>´ Name | ||
426 | </pre> | ||
427 | |||
428 | <p> | ||
429 | All global variables live as fields in ordinary Lua tables, | ||
430 | called <em>environment tables</em> or simply | ||
431 | <em>environments</em> (see <a href="#2.9">§2.9</a>). | ||
432 | Each function has its own reference to an environment, | ||
433 | so that all global variables in this function | ||
434 | will refer to this environment table. | ||
435 | When a function is created, | ||
436 | it inherits the environment from the function that created it. | ||
437 | To get the environment table of a Lua function, | ||
438 | you call <a href="#pdf-getfenv"><code>getfenv</code></a>. | ||
439 | To replace it, | ||
440 | you call <a href="#pdf-setfenv"><code>setfenv</code></a>. | ||
441 | (You can only manipulate the environment of C functions | ||
442 | through the debug library; (see <a href="#5.9">§5.9</a>).) | ||
443 | |||
444 | |||
445 | <p> | ||
446 | An access to a global variable <code>x</code> | ||
447 | is equivalent to <code>_env.x</code>, | ||
448 | which in turn is equivalent to | ||
449 | |||
450 | <pre> | ||
451 | gettable_event(_env, "x") | ||
452 | </pre><p> | ||
453 | where <code>_env</code> is the environment of the running function. | ||
454 | (See <a href="#2.8">§2.8</a> for a complete description of the | ||
455 | <code>gettable_event</code> function. | ||
456 | This function is not defined or callable in Lua. | ||
457 | Similarly, the <code>_env</code> variable is not defined in Lua. | ||
458 | We use them here only for explanatory purposes.) | ||
459 | |||
460 | |||
461 | |||
462 | |||
463 | |||
464 | <h2>2.4 - <a name="2.4">Statements</a></h2> | ||
465 | |||
466 | <p> | ||
467 | Lua supports an almost conventional set of statements, | ||
468 | similar to those in Pascal or C. | ||
469 | This set includes | ||
470 | assignments, control structures, function calls, | ||
471 | and variable declarations. | ||
472 | |||
473 | |||
474 | |||
475 | <h3>2.4.1 - <a name="2.4.1">Chunks</a></h3> | ||
476 | |||
477 | <p> | ||
478 | The unit of execution of Lua is called a <em>chunk</em>. | ||
479 | A chunk is simply a sequence of statements, | ||
480 | which are executed sequentially. | ||
481 | Each statement can be optionally followed by a semicolon: | ||
482 | |||
483 | <pre> | ||
484 | chunk ::= {stat [`<b>;</b>´]} | ||
485 | </pre><p> | ||
486 | There are no empty statements and thus '<code>;;</code>' is not legal. | ||
487 | |||
488 | |||
489 | <p> | ||
490 | Lua handles a chunk as the body of an anonymous function | ||
491 | with a variable number of arguments | ||
492 | (see <a href="#2.5.9">§2.5.9</a>). | ||
493 | As such, chunks can define local variables, | ||
494 | receive arguments, and return values. | ||
495 | |||
496 | |||
497 | <p> | ||
498 | A chunk can be stored in a file or in a string inside the host program. | ||
499 | To execute a chunk, | ||
500 | Lua first pre-compiles the chunk into instructions for a virtual machine, | ||
501 | and then it executes the compiled code | ||
502 | with an interpreter for the virtual machine. | ||
503 | |||
504 | |||
505 | <p> | ||
506 | Chunks can also be pre-compiled into binary form; | ||
507 | see program <code>luac</code> for details. | ||
508 | Programs in source and compiled forms are interchangeable; | ||
509 | Lua automatically detects the file type and acts accordingly. | ||
510 | |||
511 | |||
512 | |||
513 | |||
514 | |||
515 | |||
516 | <h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p> | ||
517 | A block is a list of statements; | ||
518 | syntactically, a block is the same as a chunk: | ||
519 | |||
520 | <pre> | ||
521 | block ::= chunk | ||
522 | </pre> | ||
523 | |||
524 | <p> | ||
525 | A block can be explicitly delimited to produce a single statement: | ||
526 | |||
527 | <pre> | ||
528 | stat ::= <b>do</b> block <b>end</b> | ||
529 | </pre><p> | ||
530 | Explicit blocks are useful | ||
531 | to control the scope of variable declarations. | ||
532 | Explicit blocks are also sometimes used to | ||
533 | add a <b>return</b> or <b>break</b> statement in the middle | ||
534 | of another block (see <a href="#2.4.4">§2.4.4</a>). | ||
535 | |||
536 | |||
537 | |||
538 | |||
539 | |||
540 | <h3>2.4.3 - <a name="2.4.3">Assignment</a></h3> | ||
541 | |||
542 | <p> | ||
543 | Lua allows multiple assignments. | ||
544 | Therefore, the syntax for assignment | ||
545 | defines a list of variables on the left side | ||
546 | and a list of expressions on the right side. | ||
547 | The elements in both lists are separated by commas: | ||
548 | |||
549 | <pre> | ||
550 | stat ::= varlist `<b>=</b>´ explist | ||
551 | varlist ::= var {`<b>,</b>´ var} | ||
552 | explist ::= exp {`<b>,</b>´ exp} | ||
553 | </pre><p> | ||
554 | Expressions are discussed in <a href="#2.5">§2.5</a>. | ||
555 | |||
556 | |||
557 | <p> | ||
558 | Before the assignment, | ||
559 | the list of values is <em>adjusted</em> to the length of | ||
560 | the list of variables. | ||
561 | If there are more values than needed, | ||
562 | the excess values are thrown away. | ||
563 | If there are fewer values than needed, | ||
564 | the list is extended with as many <b>nil</b>'s as needed. | ||
565 | If the list of expressions ends with a function call, | ||
566 | then all values returned by that call enter the list of values, | ||
567 | before the adjustment | ||
568 | (except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>). | ||
569 | |||
570 | |||
571 | <p> | ||
572 | The assignment statement first evaluates all its expressions | ||
573 | and only then are the assignments performed. | ||
574 | Thus the code | ||
575 | |||
576 | <pre> | ||
577 | i = 3 | ||
578 | i, a[i] = i+1, 20 | ||
579 | </pre><p> | ||
580 | sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> | ||
581 | because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) | ||
582 | before it is assigned 4. | ||
583 | Similarly, the line | ||
584 | |||
585 | <pre> | ||
586 | x, y = y, x | ||
587 | </pre><p> | ||
588 | exchanges the values of <code>x</code> and <code>y</code>, | ||
589 | and | ||
590 | |||
591 | <pre> | ||
592 | x, y, z = y, z, x | ||
593 | </pre><p> | ||
594 | cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. | ||
595 | |||
596 | |||
597 | <p> | ||
598 | The meaning of assignments to global variables | ||
599 | and table fields can be changed via metatables. | ||
600 | An assignment to an indexed variable <code>t[i] = val</code> is equivalent to | ||
601 | <code>settable_event(t,i,val)</code>. | ||
602 | (See <a href="#2.8">§2.8</a> for a complete description of the | ||
603 | <code>settable_event</code> function. | ||
604 | This function is not defined or callable in Lua. | ||
605 | We use it here only for explanatory purposes.) | ||
606 | |||
607 | |||
608 | <p> | ||
609 | An assignment to a global variable <code>x = val</code> | ||
610 | is equivalent to the assignment | ||
611 | <code>_env.x = val</code>, | ||
612 | which in turn is equivalent to | ||
613 | |||
614 | <pre> | ||
615 | settable_event(_env, "x", val) | ||
616 | </pre><p> | ||
617 | where <code>_env</code> is the environment of the running function. | ||
618 | (The <code>_env</code> variable is not defined in Lua. | ||
619 | We use it here only for explanatory purposes.) | ||
620 | |||
621 | |||
622 | |||
623 | |||
624 | |||
625 | <h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p> | ||
626 | The control structures | ||
627 | <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and | ||
628 | familiar syntax: | ||
629 | |||
630 | |||
631 | |||
632 | |||
633 | <pre> | ||
634 | stat ::= <b>while</b> exp <b>do</b> block <b>end</b> | ||
635 | stat ::= <b>repeat</b> block <b>until</b> exp | ||
636 | stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | ||
637 | </pre><p> | ||
638 | Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>). | ||
639 | |||
640 | |||
641 | <p> | ||
642 | The condition expression of a | ||
643 | control structure can return any value. | ||
644 | Both <b>false</b> and <b>nil</b> are considered false. | ||
645 | All values different from <b>nil</b> and <b>false</b> are considered true | ||
646 | (in particular, the number 0 and the empty string are also true). | ||
647 | |||
648 | |||
649 | <p> | ||
650 | In the <b>repeat</b>–<b>until</b> loop, | ||
651 | the inner block does not end at the <b>until</b> keyword, | ||
652 | but only after the condition. | ||
653 | So, the condition can refer to local variables | ||
654 | declared inside the loop block. | ||
655 | |||
656 | |||
657 | <p> | ||
658 | The <b>return</b> statement is used to return values | ||
659 | from a function or a chunk (which is just a function). | ||
660 | |||
661 | Functions and chunks can return more than one value, | ||
662 | and so the syntax for the <b>return</b> statement is | ||
663 | |||
664 | <pre> | ||
665 | stat ::= <b>return</b> [explist] | ||
666 | </pre> | ||
667 | |||
668 | <p> | ||
669 | The <b>break</b> statement is used to terminate the execution of a | ||
670 | <b>while</b>, <b>repeat</b>, or <b>for</b> loop, | ||
671 | skipping to the next statement after the loop: | ||
672 | |||
673 | |||
674 | <pre> | ||
675 | stat ::= <b>break</b> | ||
676 | </pre><p> | ||
677 | A <b>break</b> ends the innermost enclosing loop. | ||
678 | |||
679 | |||
680 | <p> | ||
681 | The <b>return</b> and <b>break</b> | ||
682 | statements can only be written as the <em>last</em> statement of a block. | ||
683 | If it is really necessary to <b>return</b> or <b>break</b> in the | ||
684 | middle of a block, | ||
685 | then an explicit inner block can be used, | ||
686 | as in the idioms | ||
687 | <code>do return end</code> and <code>do break end</code>, | ||
688 | because now <b>return</b> and <b>break</b> are the last statements in | ||
689 | their (inner) blocks. | ||
690 | |||
691 | |||
692 | |||
693 | |||
694 | |||
695 | <h3>2.4.5 - <a name="2.4.5">For Statement</a></h3> | ||
696 | |||
697 | <p> | ||
698 | |||
699 | The <b>for</b> statement has two forms: | ||
700 | one numeric and one generic. | ||
701 | |||
702 | |||
703 | <p> | ||
704 | The numeric <b>for</b> loop repeats a block of code while a | ||
705 | control variable runs through an arithmetic progression. | ||
706 | It has the following syntax: | ||
707 | |||
708 | <pre> | ||
709 | stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | ||
710 | </pre><p> | ||
711 | The <em>block</em> is repeated for <em>name</em> starting at the value of | ||
712 | the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the | ||
713 | third <em>exp</em>. | ||
714 | More precisely, a <b>for</b> statement like | ||
715 | |||
716 | <pre> | ||
717 | for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end | ||
718 | </pre><p> | ||
719 | is equivalent to the code: | ||
720 | |||
721 | <pre> | ||
722 | do | ||
723 | local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) | ||
724 | if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end | ||
725 | while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do | ||
726 | local v = <em>var</em> | ||
727 | <em>block</em> | ||
728 | <em>var</em> = <em>var</em> + <em>step</em> | ||
729 | end | ||
730 | end | ||
731 | </pre><p> | ||
732 | Note the following: | ||
733 | |||
734 | <ul> | ||
735 | |||
736 | <li> | ||
737 | All three control expressions are evaluated only once, | ||
738 | before the loop starts. | ||
739 | They must all result in numbers. | ||
740 | </li> | ||
741 | |||
742 | <li> | ||
743 | <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. | ||
744 | The names shown here are for explanatory purposes only. | ||
745 | </li> | ||
746 | |||
747 | <li> | ||
748 | If the third expression (the step) is absent, | ||
749 | then a step of 1 is used. | ||
750 | </li> | ||
751 | |||
752 | <li> | ||
753 | You can use <b>break</b> to exit a <b>for</b> loop. | ||
754 | </li> | ||
755 | |||
756 | <li> | ||
757 | The loop variable <code>v</code> is local to the loop; | ||
758 | you cannot use its value after the <b>for</b> ends or is broken. | ||
759 | If you need this value, | ||
760 | assign it to another variable before breaking or exiting the loop. | ||
761 | </li> | ||
762 | |||
763 | </ul> | ||
764 | |||
765 | <p> | ||
766 | The generic <b>for</b> statement works over functions, | ||
767 | called <em>iterators</em>. | ||
768 | On each iteration, the iterator function is called to produce a new value, | ||
769 | stopping when this new value is <b>nil</b>. | ||
770 | The generic <b>for</b> loop has the following syntax: | ||
771 | |||
772 | <pre> | ||
773 | stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | ||
774 | namelist ::= Name {`<b>,</b>´ Name} | ||
775 | </pre><p> | ||
776 | A <b>for</b> statement like | ||
777 | |||
778 | <pre> | ||
779 | for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end | ||
780 | </pre><p> | ||
781 | is equivalent to the code: | ||
782 | |||
783 | <pre> | ||
784 | do | ||
785 | local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> | ||
786 | while true do | ||
787 | local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) | ||
788 | <em>var</em> = <em>var_1</em> | ||
789 | if <em>var</em> == nil then break end | ||
790 | <em>block</em> | ||
791 | end | ||
792 | end | ||
793 | </pre><p> | ||
794 | Note the following: | ||
795 | |||
796 | <ul> | ||
797 | |||
798 | <li> | ||
799 | <code><em>explist</em></code> is evaluated only once. | ||
800 | Its results are an <em>iterator</em> function, | ||
801 | a <em>state</em>, | ||
802 | and an initial value for the first <em>iterator variable</em>. | ||
803 | </li> | ||
804 | |||
805 | <li> | ||
806 | <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. | ||
807 | The names are here for explanatory purposes only. | ||
808 | </li> | ||
809 | |||
810 | <li> | ||
811 | You can use <b>break</b> to exit a <b>for</b> loop. | ||
812 | </li> | ||
813 | |||
814 | <li> | ||
815 | The loop variables <code><em>var_i</em></code> are local to the loop; | ||
816 | you cannot use their values after the <b>for</b> ends. | ||
817 | If you need these values, | ||
818 | then assign them to other variables before breaking or exiting the loop. | ||
819 | </li> | ||
820 | |||
821 | </ul> | ||
822 | |||
823 | |||
824 | |||
825 | |||
826 | <h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p> | ||
827 | To allow possible side-effects, | ||
828 | function calls can be executed as statements: | ||
829 | |||
830 | <pre> | ||
831 | stat ::= functioncall | ||
832 | </pre><p> | ||
833 | In this case, all returned values are thrown away. | ||
834 | Function calls are explained in <a href="#2.5.8">§2.5.8</a>. | ||
835 | |||
836 | |||
837 | |||
838 | |||
839 | |||
840 | <h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p> | ||
841 | Local variables can be declared anywhere inside a block. | ||
842 | The declaration can include an initial assignment: | ||
843 | |||
844 | <pre> | ||
845 | stat ::= <b>local</b> namelist [`<b>=</b>´ explist] | ||
846 | </pre><p> | ||
847 | If present, an initial assignment has the same semantics | ||
848 | of a multiple assignment (see <a href="#2.4.3">§2.4.3</a>). | ||
849 | Otherwise, all variables are initialized with <b>nil</b>. | ||
850 | |||
851 | |||
852 | <p> | ||
853 | A chunk is also a block (see <a href="#2.4.1">§2.4.1</a>), | ||
854 | and so local variables can be declared in a chunk outside any explicit block. | ||
855 | The scope of such local variables extends until the end of the chunk. | ||
856 | |||
857 | |||
858 | <p> | ||
859 | The visibility rules for local variables are explained in <a href="#2.6">§2.6</a>. | ||
860 | |||
861 | |||
862 | |||
863 | |||
864 | |||
865 | |||
866 | |||
867 | <h2>2.5 - <a name="2.5">Expressions</a></h2> | ||
868 | |||
869 | <p> | ||
870 | The basic expressions in Lua are the following: | ||
871 | |||
872 | <pre> | ||
873 | exp ::= prefixexp | ||
874 | exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | ||
875 | exp ::= Number | ||
876 | exp ::= String | ||
877 | exp ::= function | ||
878 | exp ::= tableconstructor | ||
879 | exp ::= `<b>...</b>´ | ||
880 | exp ::= exp binop exp | ||
881 | exp ::= unop exp | ||
882 | prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ | ||
883 | </pre> | ||
884 | |||
885 | <p> | ||
886 | Numbers and literal strings are explained in <a href="#2.1">§2.1</a>; | ||
887 | variables are explained in <a href="#2.3">§2.3</a>; | ||
888 | function definitions are explained in <a href="#2.5.9">§2.5.9</a>; | ||
889 | function calls are explained in <a href="#2.5.8">§2.5.8</a>; | ||
890 | table constructors are explained in <a href="#2.5.7">§2.5.7</a>. | ||
891 | Vararg expressions, | ||
892 | denoted by three dots ('<code>...</code>'), can only be used when | ||
893 | directly inside a vararg function; | ||
894 | they are explained in <a href="#2.5.9">§2.5.9</a>. | ||
895 | |||
896 | |||
897 | <p> | ||
898 | Binary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>), | ||
899 | relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>), | ||
900 | and the concatenation operator (see <a href="#2.5.4">§2.5.4</a>). | ||
901 | Unary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>), | ||
902 | the unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>), | ||
903 | and the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>). | ||
904 | |||
905 | |||
906 | <p> | ||
907 | Both function calls and vararg expressions can result in multiple values. | ||
908 | If an expression is used as a statement | ||
909 | (only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)), | ||
910 | then its return list is adjusted to zero elements, | ||
911 | thus discarding all returned values. | ||
912 | If an expression is used as the last (or the only) element | ||
913 | of a list of expressions, | ||
914 | then no adjustment is made | ||
915 | (unless the call is enclosed in parentheses). | ||
916 | In all other contexts, | ||
917 | Lua adjusts the result list to one element, | ||
918 | discarding all values except the first one. | ||
919 | |||
920 | |||
921 | <p> | ||
922 | Here are some examples: | ||
923 | |||
924 | <pre> | ||
925 | f() -- adjusted to 0 results | ||
926 | g(f(), x) -- f() is adjusted to 1 result | ||
927 | g(x, f()) -- g gets x plus all results from f() | ||
928 | a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) | ||
929 | a,b = ... -- a gets the first vararg parameter, b gets | ||
930 | -- the second (both a and b can get nil if there | ||
931 | -- is no corresponding vararg parameter) | ||
932 | |||
933 | a,b,c = x, f() -- f() is adjusted to 2 results | ||
934 | a,b,c = f() -- f() is adjusted to 3 results | ||
935 | return f() -- returns all results from f() | ||
936 | return ... -- returns all received vararg parameters | ||
937 | return x,y,f() -- returns x, y, and all results from f() | ||
938 | {f()} -- creates a list with all results from f() | ||
939 | {...} -- creates a list with all vararg parameters | ||
940 | {f(), nil} -- f() is adjusted to 1 result | ||
941 | </pre> | ||
942 | |||
943 | <p> | ||
944 | Any expression enclosed in parentheses always results in only one value. | ||
945 | Thus, | ||
946 | <code>(f(x,y,z))</code> is always a single value, | ||
947 | even if <code>f</code> returns several values. | ||
948 | (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> | ||
949 | or <b>nil</b> if <code>f</code> does not return any values.) | ||
950 | |||
951 | |||
952 | |||
953 | <h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p> | ||
954 | Lua supports the usual arithmetic operators: | ||
955 | the binary <code>+</code> (addition), | ||
956 | <code>-</code> (subtraction), <code>*</code> (multiplication), | ||
957 | <code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); | ||
958 | and unary <code>-</code> (negation). | ||
959 | If the operands are numbers, or strings that can be converted to | ||
960 | numbers (see <a href="#2.2.1">§2.2.1</a>), | ||
961 | then all operations have the usual meaning. | ||
962 | Exponentiation works for any exponent. | ||
963 | For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. | ||
964 | Modulo is defined as | ||
965 | |||
966 | <pre> | ||
967 | a % b == a - math.floor(a/b)*b | ||
968 | </pre><p> | ||
969 | That is, it is the remainder of a division that rounds | ||
970 | the quotient towards minus infinity. | ||
971 | |||
972 | |||
973 | |||
974 | |||
975 | |||
976 | <h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p> | ||
977 | The relational operators in Lua are | ||
978 | |||
979 | <pre> | ||
980 | == ~= < > <= >= | ||
981 | </pre><p> | ||
982 | These operators always result in <b>false</b> or <b>true</b>. | ||
983 | |||
984 | |||
985 | <p> | ||
986 | Equality (<code>==</code>) first compares the type of its operands. | ||
987 | If the types are different, then the result is <b>false</b>. | ||
988 | Otherwise, the values of the operands are compared. | ||
989 | Numbers and strings are compared in the usual way. | ||
990 | Objects (tables, userdata, threads, and functions) | ||
991 | are compared by <em>reference</em>: | ||
992 | two objects are considered equal only if they are the <em>same</em> object. | ||
993 | Every time you create a new object | ||
994 | (a table, userdata, thread, or function), | ||
995 | this new object is different from any previously existing object. | ||
996 | |||
997 | |||
998 | <p> | ||
999 | You can change the way that Lua compares tables and userdata | ||
1000 | by using the "eq" metamethod (see <a href="#2.8">§2.8</a>). | ||
1001 | |||
1002 | |||
1003 | <p> | ||
1004 | The conversion rules of <a href="#2.2.1">§2.2.1</a> | ||
1005 | <em>do not</em> apply to equality comparisons. | ||
1006 | Thus, <code>"0"==0</code> evaluates to <b>false</b>, | ||
1007 | and <code>t[0]</code> and <code>t["0"]</code> denote different | ||
1008 | entries in a table. | ||
1009 | |||
1010 | |||
1011 | <p> | ||
1012 | The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). | ||
1013 | |||
1014 | |||
1015 | <p> | ||
1016 | The order operators work as follows. | ||
1017 | If both arguments are numbers, then they are compared as such. | ||
1018 | Otherwise, if both arguments are strings, | ||
1019 | then their values are compared according to the current locale. | ||
1020 | Otherwise, Lua tries to call the "lt" or the "le" | ||
1021 | metamethod (see <a href="#2.8">§2.8</a>). | ||
1022 | A comparison <code>a > b</code> is translated to <code>b < a</code> | ||
1023 | and <code>a >= b</code> is translated to <code>b <= a</code>. | ||
1024 | |||
1025 | |||
1026 | |||
1027 | |||
1028 | |||
1029 | <h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p> | ||
1030 | The logical operators in Lua are | ||
1031 | <b>and</b>, <b>or</b>, and <b>not</b>. | ||
1032 | Like the control structures (see <a href="#2.4.4">§2.4.4</a>), | ||
1033 | all logical operators consider both <b>false</b> and <b>nil</b> as false | ||
1034 | and anything else as true. | ||
1035 | |||
1036 | |||
1037 | <p> | ||
1038 | The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. | ||
1039 | The conjunction operator <b>and</b> returns its first argument | ||
1040 | if this value is <b>false</b> or <b>nil</b>; | ||
1041 | otherwise, <b>and</b> returns its second argument. | ||
1042 | The disjunction operator <b>or</b> returns its first argument | ||
1043 | if this value is different from <b>nil</b> and <b>false</b>; | ||
1044 | otherwise, <b>or</b> returns its second argument. | ||
1045 | Both <b>and</b> and <b>or</b> use short-cut evaluation; | ||
1046 | that is, | ||
1047 | the second operand is evaluated only if necessary. | ||
1048 | Here are some examples: | ||
1049 | |||
1050 | <pre> | ||
1051 | 10 or 20 --> 10 | ||
1052 | 10 or error() --> 10 | ||
1053 | nil or "a" --> "a" | ||
1054 | nil and 10 --> nil | ||
1055 | false and error() --> false | ||
1056 | false and nil --> false | ||
1057 | false or nil --> nil | ||
1058 | 10 and 20 --> 20 | ||
1059 | </pre><p> | ||
1060 | (In this manual, | ||
1061 | <code>--></code> indicates the result of the preceding expression.) | ||
1062 | |||
1063 | |||
1064 | |||
1065 | |||
1066 | |||
1067 | <h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p> | ||
1068 | The string concatenation operator in Lua is | ||
1069 | denoted by two dots ('<code>..</code>'). | ||
1070 | If both operands are strings or numbers, then they are converted to | ||
1071 | strings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>. | ||
1072 | Otherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>). | ||
1073 | |||
1074 | |||
1075 | |||
1076 | |||
1077 | |||
1078 | <h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3> | ||
1079 | |||
1080 | <p> | ||
1081 | The length operator is denoted by the unary operator <code>#</code>. | ||
1082 | The length of a string is its number of bytes | ||
1083 | (that is, the usual meaning of string length when each | ||
1084 | character is one byte). | ||
1085 | |||
1086 | |||
1087 | <p> | ||
1088 | The length of a table <code>t</code> is defined to be any | ||
1089 | integer index <code>n</code> | ||
1090 | such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; | ||
1091 | moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero. | ||
1092 | For a regular array, with non-nil values from 1 to a given <code>n</code>, | ||
1093 | its length is exactly that <code>n</code>, | ||
1094 | the index of its last value. | ||
1095 | If the array has "holes" | ||
1096 | (that is, <b>nil</b> values between other non-nil values), | ||
1097 | then <code>#t</code> can be any of the indices that | ||
1098 | directly precedes a <b>nil</b> value | ||
1099 | (that is, it may consider any such <b>nil</b> value as the end of | ||
1100 | the array). | ||
1101 | |||
1102 | |||
1103 | |||
1104 | |||
1105 | |||
1106 | <h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p> | ||
1107 | Operator precedence in Lua follows the table below, | ||
1108 | from lower to higher priority: | ||
1109 | |||
1110 | <pre> | ||
1111 | or | ||
1112 | and | ||
1113 | < > <= >= ~= == | ||
1114 | .. | ||
1115 | + - | ||
1116 | * / % | ||
1117 | not # - (unary) | ||
1118 | ^ | ||
1119 | </pre><p> | ||
1120 | As usual, | ||
1121 | you can use parentheses to change the precedences of an expression. | ||
1122 | The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') | ||
1123 | operators are right associative. | ||
1124 | All other binary operators are left associative. | ||
1125 | |||
1126 | |||
1127 | |||
1128 | |||
1129 | |||
1130 | <h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p> | ||
1131 | Table constructors are expressions that create tables. | ||
1132 | Every time a constructor is evaluated, a new table is created. | ||
1133 | A constructor can be used to create an empty table | ||
1134 | or to create a table and initialize some of its fields. | ||
1135 | The general syntax for constructors is | ||
1136 | |||
1137 | <pre> | ||
1138 | tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ | ||
1139 | fieldlist ::= field {fieldsep field} [fieldsep] | ||
1140 | field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp | ||
1141 | fieldsep ::= `<b>,</b>´ | `<b>;</b>´ | ||
1142 | </pre> | ||
1143 | |||
1144 | <p> | ||
1145 | Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry | ||
1146 | with key <code>exp1</code> and value <code>exp2</code>. | ||
1147 | A field of the form <code>name = exp</code> is equivalent to | ||
1148 | <code>["name"] = exp</code>. | ||
1149 | Finally, fields of the form <code>exp</code> are equivalent to | ||
1150 | <code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, | ||
1151 | starting with 1. | ||
1152 | Fields in the other formats do not affect this counting. | ||
1153 | For example, | ||
1154 | |||
1155 | <pre> | ||
1156 | a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } | ||
1157 | </pre><p> | ||
1158 | is equivalent to | ||
1159 | |||
1160 | <pre> | ||
1161 | do | ||
1162 | local t = {} | ||
1163 | t[f(1)] = g | ||
1164 | t[1] = "x" -- 1st exp | ||
1165 | t[2] = "y" -- 2nd exp | ||
1166 | t.x = 1 -- t["x"] = 1 | ||
1167 | t[3] = f(x) -- 3rd exp | ||
1168 | t[30] = 23 | ||
1169 | t[4] = 45 -- 4th exp | ||
1170 | a = t | ||
1171 | end | ||
1172 | </pre> | ||
1173 | |||
1174 | <p> | ||
1175 | If the last field in the list has the form <code>exp</code> | ||
1176 | and the expression is a function call or a vararg expression, | ||
1177 | then all values returned by this expression enter the list consecutively | ||
1178 | (see <a href="#2.5.8">§2.5.8</a>). | ||
1179 | To avoid this, | ||
1180 | enclose the function call or the vararg expression | ||
1181 | in parentheses (see <a href="#2.5">§2.5</a>). | ||
1182 | |||
1183 | |||
1184 | <p> | ||
1185 | The field list can have an optional trailing separator, | ||
1186 | as a convenience for machine-generated code. | ||
1187 | |||
1188 | |||
1189 | |||
1190 | |||
1191 | |||
1192 | <h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p> | ||
1193 | A function call in Lua has the following syntax: | ||
1194 | |||
1195 | <pre> | ||
1196 | functioncall ::= prefixexp args | ||
1197 | </pre><p> | ||
1198 | In a function call, | ||
1199 | first prefixexp and args are evaluated. | ||
1200 | If the value of prefixexp has type <em>function</em>, | ||
1201 | then this function is called | ||
1202 | with the given arguments. | ||
1203 | Otherwise, the prefixexp "call" metamethod is called, | ||
1204 | having as first parameter the value of prefixexp, | ||
1205 | followed by the original call arguments | ||
1206 | (see <a href="#2.8">§2.8</a>). | ||
1207 | |||
1208 | |||
1209 | <p> | ||
1210 | The form | ||
1211 | |||
1212 | <pre> | ||
1213 | functioncall ::= prefixexp `<b>:</b>´ Name args | ||
1214 | </pre><p> | ||
1215 | can be used to call "methods". | ||
1216 | A call <code>v:name(<em>args</em>)</code> | ||
1217 | is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, | ||
1218 | except that <code>v</code> is evaluated only once. | ||
1219 | |||
1220 | |||
1221 | <p> | ||
1222 | Arguments have the following syntax: | ||
1223 | |||
1224 | <pre> | ||
1225 | args ::= `<b>(</b>´ [explist] `<b>)</b>´ | ||
1226 | args ::= tableconstructor | ||
1227 | args ::= String | ||
1228 | </pre><p> | ||
1229 | All argument expressions are evaluated before the call. | ||
1230 | A call of the form <code>f{<em>fields</em>}</code> is | ||
1231 | syntactic sugar for <code>f({<em>fields</em>})</code>; | ||
1232 | that is, the argument list is a single new table. | ||
1233 | A call of the form <code>f'<em>string</em>'</code> | ||
1234 | (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) | ||
1235 | is syntactic sugar for <code>f('<em>string</em>')</code>; | ||
1236 | that is, the argument list is a single literal string. | ||
1237 | |||
1238 | |||
1239 | <p> | ||
1240 | As an exception to the free-format syntax of Lua, | ||
1241 | you cannot put a line break before the '<code>(</code>' in a function call. | ||
1242 | This restriction avoids some ambiguities in the language. | ||
1243 | If you write | ||
1244 | |||
1245 | <pre> | ||
1246 | a = f | ||
1247 | (g).x(a) | ||
1248 | </pre><p> | ||
1249 | Lua would see that as a single statement, <code>a = f(g).x(a)</code>. | ||
1250 | So, if you want two statements, you must add a semi-colon between them. | ||
1251 | If you actually want to call <code>f</code>, | ||
1252 | you must remove the line break before <code>(g)</code>. | ||
1253 | |||
1254 | |||
1255 | <p> | ||
1256 | A call of the form <code>return</code> <em>functioncall</em> is called | ||
1257 | a <em>tail call</em>. | ||
1258 | Lua implements <em>proper tail calls</em> | ||
1259 | (or <em>proper tail recursion</em>): | ||
1260 | in a tail call, | ||
1261 | the called function reuses the stack entry of the calling function. | ||
1262 | Therefore, there is no limit on the number of nested tail calls that | ||
1263 | a program can execute. | ||
1264 | However, a tail call erases any debug information about the | ||
1265 | calling function. | ||
1266 | Note that a tail call only happens with a particular syntax, | ||
1267 | where the <b>return</b> has one single function call as argument; | ||
1268 | this syntax makes the calling function return exactly | ||
1269 | the returns of the called function. | ||
1270 | So, none of the following examples are tail calls: | ||
1271 | |||
1272 | <pre> | ||
1273 | return (f(x)) -- results adjusted to 1 | ||
1274 | return 2 * f(x) | ||
1275 | return x, f(x) -- additional results | ||
1276 | f(x); return -- results discarded | ||
1277 | return x or f(x) -- results adjusted to 1 | ||
1278 | </pre> | ||
1279 | |||
1280 | |||
1281 | |||
1282 | |||
1283 | <h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3> | ||
1284 | |||
1285 | <p> | ||
1286 | The syntax for function definition is | ||
1287 | |||
1288 | <pre> | ||
1289 | function ::= <b>function</b> funcbody | ||
1290 | funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> | ||
1291 | </pre> | ||
1292 | |||
1293 | <p> | ||
1294 | The following syntactic sugar simplifies function definitions: | ||
1295 | |||
1296 | <pre> | ||
1297 | stat ::= <b>function</b> funcname funcbody | ||
1298 | stat ::= <b>local</b> <b>function</b> Name funcbody | ||
1299 | funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] | ||
1300 | </pre><p> | ||
1301 | The statement | ||
1302 | |||
1303 | <pre> | ||
1304 | function f () <em>body</em> end | ||
1305 | </pre><p> | ||
1306 | translates to | ||
1307 | |||
1308 | <pre> | ||
1309 | f = function () <em>body</em> end | ||
1310 | </pre><p> | ||
1311 | The statement | ||
1312 | |||
1313 | <pre> | ||
1314 | function t.a.b.c.f () <em>body</em> end | ||
1315 | </pre><p> | ||
1316 | translates to | ||
1317 | |||
1318 | <pre> | ||
1319 | t.a.b.c.f = function () <em>body</em> end | ||
1320 | </pre><p> | ||
1321 | The statement | ||
1322 | |||
1323 | <pre> | ||
1324 | local function f () <em>body</em> end | ||
1325 | </pre><p> | ||
1326 | translates to | ||
1327 | |||
1328 | <pre> | ||
1329 | local f; f = function () <em>body</em> end | ||
1330 | </pre><p> | ||
1331 | <em>not</em> to | ||
1332 | |||
1333 | <pre> | ||
1334 | local f = function () <em>body</em> end | ||
1335 | </pre><p> | ||
1336 | (This only makes a difference when the body of the function | ||
1337 | contains references to <code>f</code>.) | ||
1338 | |||
1339 | |||
1340 | <p> | ||
1341 | A function definition is an executable expression, | ||
1342 | whose value has type <em>function</em>. | ||
1343 | When Lua pre-compiles a chunk, | ||
1344 | all its function bodies are pre-compiled too. | ||
1345 | Then, whenever Lua executes the function definition, | ||
1346 | the function is <em>instantiated</em> (or <em>closed</em>). | ||
1347 | This function instance (or <em>closure</em>) | ||
1348 | is the final value of the expression. | ||
1349 | Different instances of the same function | ||
1350 | can refer to different external local variables | ||
1351 | and can have different environment tables. | ||
1352 | |||
1353 | |||
1354 | <p> | ||
1355 | Parameters act as local variables that are | ||
1356 | initialized with the argument values: | ||
1357 | |||
1358 | <pre> | ||
1359 | parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ | ||
1360 | </pre><p> | ||
1361 | When a function is called, | ||
1362 | the list of arguments is adjusted to | ||
1363 | the length of the list of parameters, | ||
1364 | unless the function is a variadic or <em>vararg function</em>, | ||
1365 | which is | ||
1366 | indicated by three dots ('<code>...</code>') at the end of its parameter list. | ||
1367 | A vararg function does not adjust its argument list; | ||
1368 | instead, it collects all extra arguments and supplies them | ||
1369 | to the function through a <em>vararg expression</em>, | ||
1370 | which is also written as three dots. | ||
1371 | The value of this expression is a list of all actual extra arguments, | ||
1372 | similar to a function with multiple results. | ||
1373 | If a vararg expression is used inside another expression | ||
1374 | or in the middle of a list of expressions, | ||
1375 | then its return list is adjusted to one element. | ||
1376 | If the expression is used as the last element of a list of expressions, | ||
1377 | then no adjustment is made | ||
1378 | (unless that last expression is enclosed in parentheses). | ||
1379 | |||
1380 | |||
1381 | <p> | ||
1382 | As an example, consider the following definitions: | ||
1383 | |||
1384 | <pre> | ||
1385 | function f(a, b) end | ||
1386 | function g(a, b, ...) end | ||
1387 | function r() return 1,2,3 end | ||
1388 | </pre><p> | ||
1389 | Then, we have the following mapping from arguments to parameters and | ||
1390 | to the vararg expression: | ||
1391 | |||
1392 | <pre> | ||
1393 | CALL PARAMETERS | ||
1394 | |||
1395 | f(3) a=3, b=nil | ||
1396 | f(3, 4) a=3, b=4 | ||
1397 | f(3, 4, 5) a=3, b=4 | ||
1398 | f(r(), 10) a=1, b=10 | ||
1399 | f(r()) a=1, b=2 | ||
1400 | |||
1401 | g(3) a=3, b=nil, ... --> (nothing) | ||
1402 | g(3, 4) a=3, b=4, ... --> (nothing) | ||
1403 | g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 | ||
1404 | g(5, r()) a=5, b=1, ... --> 2 3 | ||
1405 | </pre> | ||
1406 | |||
1407 | <p> | ||
1408 | Results are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>). | ||
1409 | If control reaches the end of a function | ||
1410 | without encountering a <b>return</b> statement, | ||
1411 | then the function returns with no results. | ||
1412 | |||
1413 | |||
1414 | <p> | ||
1415 | The <em>colon</em> syntax | ||
1416 | is used for defining <em>methods</em>, | ||
1417 | that is, functions that have an implicit extra parameter <code>self</code>. | ||
1418 | Thus, the statement | ||
1419 | |||
1420 | <pre> | ||
1421 | function t.a.b.c:f (<em>params</em>) <em>body</em> end | ||
1422 | </pre><p> | ||
1423 | is syntactic sugar for | ||
1424 | |||
1425 | <pre> | ||
1426 | t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end | ||
1427 | </pre> | ||
1428 | |||
1429 | |||
1430 | |||
1431 | |||
1432 | |||
1433 | |||
1434 | <h2>2.6 - <a name="2.6">Visibility Rules</a></h2> | ||
1435 | |||
1436 | <p> | ||
1437 | |||
1438 | Lua is a lexically scoped language. | ||
1439 | The scope of variables begins at the first statement <em>after</em> | ||
1440 | their declaration and lasts until the end of the innermost block that | ||
1441 | includes the declaration. | ||
1442 | Consider the following example: | ||
1443 | |||
1444 | <pre> | ||
1445 | x = 10 -- global variable | ||
1446 | do -- new block | ||
1447 | local x = x -- new 'x', with value 10 | ||
1448 | print(x) --> 10 | ||
1449 | x = x+1 | ||
1450 | do -- another block | ||
1451 | local x = x+1 -- another 'x' | ||
1452 | print(x) --> 12 | ||
1453 | end | ||
1454 | print(x) --> 11 | ||
1455 | end | ||
1456 | print(x) --> 10 (the global one) | ||
1457 | </pre> | ||
1458 | |||
1459 | <p> | ||
1460 | Notice that, in a declaration like <code>local x = x</code>, | ||
1461 | the new <code>x</code> being declared is not in scope yet, | ||
1462 | and so the second <code>x</code> refers to the outside variable. | ||
1463 | |||
1464 | |||
1465 | <p> | ||
1466 | Because of the lexical scoping rules, | ||
1467 | local variables can be freely accessed by functions | ||
1468 | defined inside their scope. | ||
1469 | A local variable used by an inner function is called | ||
1470 | an <em>upvalue</em>, or <em>external local variable</em>, | ||
1471 | inside the inner function. | ||
1472 | |||
1473 | |||
1474 | <p> | ||
1475 | Notice that each execution of a <b>local</b> statement | ||
1476 | defines new local variables. | ||
1477 | Consider the following example: | ||
1478 | |||
1479 | <pre> | ||
1480 | a = {} | ||
1481 | local x = 20 | ||
1482 | for i=1,10 do | ||
1483 | local y = 0 | ||
1484 | a[i] = function () y=y+1; return x+y end | ||
1485 | end | ||
1486 | </pre><p> | ||
1487 | The loop creates ten closures | ||
1488 | (that is, ten instances of the anonymous function). | ||
1489 | Each of these closures uses a different <code>y</code> variable, | ||
1490 | while all of them share the same <code>x</code>. | ||
1491 | |||
1492 | |||
1493 | |||
1494 | |||
1495 | |||
1496 | <h2>2.7 - <a name="2.7">Error Handling</a></h2> | ||
1497 | |||
1498 | <p> | ||
1499 | Because Lua is an embedded extension language, | ||
1500 | all Lua actions start from C code in the host program | ||
1501 | calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). | ||
1502 | Whenever an error occurs during Lua compilation or execution, | ||
1503 | control returns to C, | ||
1504 | which can take appropriate measures | ||
1505 | (such as printing an error message). | ||
1506 | |||
1507 | |||
1508 | <p> | ||
1509 | Lua code can explicitly generate an error by calling the | ||
1510 | <a href="#pdf-error"><code>error</code></a> function. | ||
1511 | If you need to catch errors in Lua, | ||
1512 | you can use the <a href="#pdf-pcall"><code>pcall</code></a> function. | ||
1513 | |||
1514 | |||
1515 | |||
1516 | |||
1517 | |||
1518 | <h2>2.8 - <a name="2.8">Metatables</a></h2> | ||
1519 | |||
1520 | <p> | ||
1521 | Every value in Lua can have a <em>metatable</em>. | ||
1522 | This <em>metatable</em> is an ordinary Lua table | ||
1523 | that defines the behavior of the original value | ||
1524 | under certain special operations. | ||
1525 | You can change several aspects of the behavior | ||
1526 | of operations over a value by setting specific fields in its metatable. | ||
1527 | For instance, when a non-numeric value is the operand of an addition, | ||
1528 | Lua checks for a function in the field <code>"__add"</code> in its metatable. | ||
1529 | If it finds one, | ||
1530 | Lua calls this function to perform the addition. | ||
1531 | |||
1532 | |||
1533 | <p> | ||
1534 | We call the keys in a metatable <em>events</em> | ||
1535 | and the values <em>metamethods</em>. | ||
1536 | In the previous example, the event is <code>"add"</code> | ||
1537 | and the metamethod is the function that performs the addition. | ||
1538 | |||
1539 | |||
1540 | <p> | ||
1541 | You can query the metatable of any value | ||
1542 | through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. | ||
1543 | |||
1544 | |||
1545 | <p> | ||
1546 | You can replace the metatable of tables | ||
1547 | through the <a href="#pdf-setmetatable"><code>setmetatable</code></a> | ||
1548 | function. | ||
1549 | You cannot change the metatable of other types from Lua | ||
1550 | (except by using the debug library); | ||
1551 | you must use the C API for that. | ||
1552 | |||
1553 | |||
1554 | <p> | ||
1555 | Tables and full userdata have individual metatables | ||
1556 | (although multiple tables and userdata can share their metatables). | ||
1557 | Values of all other types share one single metatable per type; | ||
1558 | that is, there is one single metatable for all numbers, | ||
1559 | one for all strings, etc. | ||
1560 | |||
1561 | |||
1562 | <p> | ||
1563 | A metatable controls how an object behaves in arithmetic operations, | ||
1564 | order comparisons, concatenation, length operation, and indexing. | ||
1565 | A metatable also can define a function to be called when a userdata | ||
1566 | is garbage collected. | ||
1567 | For each of these operations Lua associates a specific key | ||
1568 | called an <em>event</em>. | ||
1569 | When Lua performs one of these operations over a value, | ||
1570 | it checks whether this value has a metatable with the corresponding event. | ||
1571 | If so, the value associated with that key (the metamethod) | ||
1572 | controls how Lua will perform the operation. | ||
1573 | |||
1574 | |||
1575 | <p> | ||
1576 | Metatables control the operations listed next. | ||
1577 | Each operation is identified by its corresponding name. | ||
1578 | The key for each operation is a string with its name prefixed by | ||
1579 | two underscores, '<code>__</code>'; | ||
1580 | for instance, the key for operation "add" is the | ||
1581 | string <code>"__add"</code>. | ||
1582 | The semantics of these operations is better explained by a Lua function | ||
1583 | describing how the interpreter executes the operation. | ||
1584 | |||
1585 | |||
1586 | <p> | ||
1587 | The code shown here in Lua is only illustrative; | ||
1588 | the real behavior is hard coded in the interpreter | ||
1589 | and it is much more efficient than this simulation. | ||
1590 | All functions used in these descriptions | ||
1591 | (<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.) | ||
1592 | are described in <a href="#5.1">§5.1</a>. | ||
1593 | In particular, to retrieve the metamethod of a given object, | ||
1594 | we use the expression | ||
1595 | |||
1596 | <pre> | ||
1597 | metatable(obj)[event] | ||
1598 | </pre><p> | ||
1599 | This should be read as | ||
1600 | |||
1601 | <pre> | ||
1602 | rawget(getmetatable(obj) or {}, event) | ||
1603 | </pre><p> | ||
1604 | |||
1605 | That is, the access to a metamethod does not invoke other metamethods, | ||
1606 | and the access to objects with no metatables does not fail | ||
1607 | (it simply results in <b>nil</b>). | ||
1608 | |||
1609 | |||
1610 | |||
1611 | <ul> | ||
1612 | |||
1613 | <li><b>"add":</b> | ||
1614 | the <code>+</code> operation. | ||
1615 | |||
1616 | |||
1617 | |||
1618 | <p> | ||
1619 | The function <code>getbinhandler</code> below defines how Lua chooses a handler | ||
1620 | for a binary operation. | ||
1621 | First, Lua tries the first operand. | ||
1622 | If its type does not define a handler for the operation, | ||
1623 | then Lua tries the second operand. | ||
1624 | |||
1625 | <pre> | ||
1626 | function getbinhandler (op1, op2, event) | ||
1627 | return metatable(op1)[event] or metatable(op2)[event] | ||
1628 | end | ||
1629 | </pre><p> | ||
1630 | By using this function, | ||
1631 | the behavior of the <code>op1 + op2</code> is | ||
1632 | |||
1633 | <pre> | ||
1634 | function add_event (op1, op2) | ||
1635 | local o1, o2 = tonumber(op1), tonumber(op2) | ||
1636 | if o1 and o2 then -- both operands are numeric? | ||
1637 | return o1 + o2 -- '+' here is the primitive 'add' | ||
1638 | else -- at least one of the operands is not numeric | ||
1639 | local h = getbinhandler(op1, op2, "__add") | ||
1640 | if h then | ||
1641 | -- call the handler with both operands | ||
1642 | return (h(op1, op2)) | ||
1643 | else -- no handler available: default behavior | ||
1644 | error(···) | ||
1645 | end | ||
1646 | end | ||
1647 | end | ||
1648 | </pre><p> | ||
1649 | </li> | ||
1650 | |||
1651 | <li><b>"sub":</b> | ||
1652 | the <code>-</code> operation. | ||
1653 | |||
1654 | Behavior similar to the "add" operation. | ||
1655 | </li> | ||
1656 | |||
1657 | <li><b>"mul":</b> | ||
1658 | the <code>*</code> operation. | ||
1659 | |||
1660 | Behavior similar to the "add" operation. | ||
1661 | </li> | ||
1662 | |||
1663 | <li><b>"div":</b> | ||
1664 | the <code>/</code> operation. | ||
1665 | |||
1666 | Behavior similar to the "add" operation. | ||
1667 | </li> | ||
1668 | |||
1669 | <li><b>"mod":</b> | ||
1670 | the <code>%</code> operation. | ||
1671 | |||
1672 | Behavior similar to the "add" operation, | ||
1673 | with the operation | ||
1674 | <code>o1 - floor(o1/o2)*o2</code> as the primitive operation. | ||
1675 | </li> | ||
1676 | |||
1677 | <li><b>"pow":</b> | ||
1678 | the <code>^</code> (exponentiation) operation. | ||
1679 | |||
1680 | Behavior similar to the "add" operation, | ||
1681 | with the function <code>pow</code> (from the C math library) | ||
1682 | as the primitive operation. | ||
1683 | </li> | ||
1684 | |||
1685 | <li><b>"unm":</b> | ||
1686 | the unary <code>-</code> operation. | ||
1687 | |||
1688 | |||
1689 | <pre> | ||
1690 | function unm_event (op) | ||
1691 | local o = tonumber(op) | ||
1692 | if o then -- operand is numeric? | ||
1693 | return -o -- '-' here is the primitive 'unm' | ||
1694 | else -- the operand is not numeric. | ||
1695 | -- Try to get a handler from the operand | ||
1696 | local h = metatable(op).__unm | ||
1697 | if h then | ||
1698 | -- call the handler with the operand | ||
1699 | return (h(op)) | ||
1700 | else -- no handler available: default behavior | ||
1701 | error(···) | ||
1702 | end | ||
1703 | end | ||
1704 | end | ||
1705 | </pre><p> | ||
1706 | </li> | ||
1707 | |||
1708 | <li><b>"concat":</b> | ||
1709 | the <code>..</code> (concatenation) operation. | ||
1710 | |||
1711 | |||
1712 | <pre> | ||
1713 | function concat_event (op1, op2) | ||
1714 | if (type(op1) == "string" or type(op1) == "number") and | ||
1715 | (type(op2) == "string" or type(op2) == "number") then | ||
1716 | return op1 .. op2 -- primitive string concatenation | ||
1717 | else | ||
1718 | local h = getbinhandler(op1, op2, "__concat") | ||
1719 | if h then | ||
1720 | return (h(op1, op2)) | ||
1721 | else | ||
1722 | error(···) | ||
1723 | end | ||
1724 | end | ||
1725 | end | ||
1726 | </pre><p> | ||
1727 | </li> | ||
1728 | |||
1729 | <li><b>"len":</b> | ||
1730 | the <code>#</code> operation. | ||
1731 | |||
1732 | |||
1733 | <pre> | ||
1734 | function len_event (op) | ||
1735 | if type(op) == "string" then | ||
1736 | return strlen(op) -- primitive string length | ||
1737 | elseif type(op) == "table" then | ||
1738 | return #op -- primitive table length | ||
1739 | else | ||
1740 | local h = metatable(op).__len | ||
1741 | if h then | ||
1742 | -- call the handler with the operand | ||
1743 | return (h(op)) | ||
1744 | else -- no handler available: default behavior | ||
1745 | error(···) | ||
1746 | end | ||
1747 | end | ||
1748 | end | ||
1749 | </pre><p> | ||
1750 | See <a href="#2.5.5">§2.5.5</a> for a description of the length of a table. | ||
1751 | </li> | ||
1752 | |||
1753 | <li><b>"eq":</b> | ||
1754 | the <code>==</code> operation. | ||
1755 | |||
1756 | The function <code>getcomphandler</code> defines how Lua chooses a metamethod | ||
1757 | for comparison operators. | ||
1758 | A metamethod only is selected when both objects | ||
1759 | being compared have the same type | ||
1760 | and the same metamethod for the selected operation. | ||
1761 | |||
1762 | <pre> | ||
1763 | function getcomphandler (op1, op2, event) | ||
1764 | if type(op1) ~= type(op2) then return nil end | ||
1765 | local mm1 = metatable(op1)[event] | ||
1766 | local mm2 = metatable(op2)[event] | ||
1767 | if mm1 == mm2 then return mm1 else return nil end | ||
1768 | end | ||
1769 | </pre><p> | ||
1770 | The "eq" event is defined as follows: | ||
1771 | |||
1772 | <pre> | ||
1773 | function eq_event (op1, op2) | ||
1774 | if type(op1) ~= type(op2) then -- different types? | ||
1775 | return false -- different objects | ||
1776 | end | ||
1777 | if op1 == op2 then -- primitive equal? | ||
1778 | return true -- objects are equal | ||
1779 | end | ||
1780 | -- try metamethod | ||
1781 | local h = getcomphandler(op1, op2, "__eq") | ||
1782 | if h then | ||
1783 | return (h(op1, op2)) | ||
1784 | else | ||
1785 | return false | ||
1786 | end | ||
1787 | end | ||
1788 | </pre><p> | ||
1789 | <code>a ~= b</code> is equivalent to <code>not (a == b)</code>. | ||
1790 | </li> | ||
1791 | |||
1792 | <li><b>"lt":</b> | ||
1793 | the <code><</code> operation. | ||
1794 | |||
1795 | |||
1796 | <pre> | ||
1797 | function lt_event (op1, op2) | ||
1798 | if type(op1) == "number" and type(op2) == "number" then | ||
1799 | return op1 < op2 -- numeric comparison | ||
1800 | elseif type(op1) == "string" and type(op2) == "string" then | ||
1801 | return op1 < op2 -- lexicographic comparison | ||
1802 | else | ||
1803 | local h = getcomphandler(op1, op2, "__lt") | ||
1804 | if h then | ||
1805 | return (h(op1, op2)) | ||
1806 | else | ||
1807 | error(···) | ||
1808 | end | ||
1809 | end | ||
1810 | end | ||
1811 | </pre><p> | ||
1812 | <code>a > b</code> is equivalent to <code>b < a</code>. | ||
1813 | </li> | ||
1814 | |||
1815 | <li><b>"le":</b> | ||
1816 | the <code><=</code> operation. | ||
1817 | |||
1818 | |||
1819 | <pre> | ||
1820 | function le_event (op1, op2) | ||
1821 | if type(op1) == "number" and type(op2) == "number" then | ||
1822 | return op1 <= op2 -- numeric comparison | ||
1823 | elseif type(op1) == "string" and type(op2) == "string" then | ||
1824 | return op1 <= op2 -- lexicographic comparison | ||
1825 | else | ||
1826 | local h = getcomphandler(op1, op2, "__le") | ||
1827 | if h then | ||
1828 | return (h(op1, op2)) | ||
1829 | else | ||
1830 | h = getcomphandler(op1, op2, "__lt") | ||
1831 | if h then | ||
1832 | return not h(op2, op1) | ||
1833 | else | ||
1834 | error(···) | ||
1835 | end | ||
1836 | end | ||
1837 | end | ||
1838 | end | ||
1839 | </pre><p> | ||
1840 | <code>a >= b</code> is equivalent to <code>b <= a</code>. | ||
1841 | Note that, in the absence of a "le" metamethod, | ||
1842 | Lua tries the "lt", assuming that <code>a <= b</code> is | ||
1843 | equivalent to <code>not (b < a)</code>. | ||
1844 | </li> | ||
1845 | |||
1846 | <li><b>"index":</b> | ||
1847 | The indexing access <code>table[key]</code>. | ||
1848 | |||
1849 | |||
1850 | <pre> | ||
1851 | function gettable_event (table, key) | ||
1852 | local h | ||
1853 | if type(table) == "table" then | ||
1854 | local v = rawget(table, key) | ||
1855 | if v ~= nil then return v end | ||
1856 | h = metatable(table).__index | ||
1857 | if h == nil then return nil end | ||
1858 | else | ||
1859 | h = metatable(table).__index | ||
1860 | if h == nil then | ||
1861 | error(···) | ||
1862 | end | ||
1863 | end | ||
1864 | if type(h) == "function" then | ||
1865 | return (h(table, key)) -- call the handler | ||
1866 | else return h[key] -- or repeat operation on it | ||
1867 | end | ||
1868 | end | ||
1869 | </pre><p> | ||
1870 | </li> | ||
1871 | |||
1872 | <li><b>"newindex":</b> | ||
1873 | The indexing assignment <code>table[key] = value</code>. | ||
1874 | |||
1875 | |||
1876 | <pre> | ||
1877 | function settable_event (table, key, value) | ||
1878 | local h | ||
1879 | if type(table) == "table" then | ||
1880 | local v = rawget(table, key) | ||
1881 | if v ~= nil then rawset(table, key, value); return end | ||
1882 | h = metatable(table).__newindex | ||
1883 | if h == nil then rawset(table, key, value); return end | ||
1884 | else | ||
1885 | h = metatable(table).__newindex | ||
1886 | if h == nil then | ||
1887 | error(···) | ||
1888 | end | ||
1889 | end | ||
1890 | if type(h) == "function" then | ||
1891 | h(table, key,value) -- call the handler | ||
1892 | else h[key] = value -- or repeat operation on it | ||
1893 | end | ||
1894 | end | ||
1895 | </pre><p> | ||
1896 | </li> | ||
1897 | |||
1898 | <li><b>"call":</b> | ||
1899 | called when Lua calls a value. | ||
1900 | |||
1901 | |||
1902 | <pre> | ||
1903 | function function_event (func, ...) | ||
1904 | if type(func) == "function" then | ||
1905 | return func(...) -- primitive call | ||
1906 | else | ||
1907 | local h = metatable(func).__call | ||
1908 | if h then | ||
1909 | return h(func, ...) | ||
1910 | else | ||
1911 | error(···) | ||
1912 | end | ||
1913 | end | ||
1914 | end | ||
1915 | </pre><p> | ||
1916 | </li> | ||
1917 | |||
1918 | </ul> | ||
1919 | |||
1920 | |||
1921 | |||
1922 | |||
1923 | <h2>2.9 - <a name="2.9">Environments</a></h2> | ||
1924 | |||
1925 | <p> | ||
1926 | Besides metatables, | ||
1927 | objects of types thread, function, and userdata | ||
1928 | have another table associated with them, | ||
1929 | called their <em>environment</em>. | ||
1930 | Like metatables, environments are regular tables and | ||
1931 | multiple objects can share the same environment. | ||
1932 | |||
1933 | |||
1934 | <p> | ||
1935 | Threads are created sharing the environment of the creating thread. | ||
1936 | Userdata and C functions are created sharing the environment | ||
1937 | of the creating C function. | ||
1938 | Non-nested Lua functions | ||
1939 | (created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>) | ||
1940 | are created sharing the environment of the creating thread. | ||
1941 | Nested Lua functions are created sharing the environment of | ||
1942 | the creating Lua function. | ||
1943 | |||
1944 | |||
1945 | <p> | ||
1946 | Environments associated with userdata have no meaning for Lua. | ||
1947 | It is only a convenience feature for programmers to associate a table to | ||
1948 | a userdata. | ||
1949 | |||
1950 | |||
1951 | <p> | ||
1952 | Environments associated with threads are called | ||
1953 | <em>global environments</em>. | ||
1954 | They are used as the default environment for threads and | ||
1955 | non-nested Lua functions created by the thread | ||
1956 | and can be directly accessed by C code (see <a href="#3.3">§3.3</a>). | ||
1957 | |||
1958 | |||
1959 | <p> | ||
1960 | The environment associated with a C function can be directly | ||
1961 | accessed by C code (see <a href="#3.3">§3.3</a>). | ||
1962 | It is used as the default environment for other C functions | ||
1963 | and userdata created by the function. | ||
1964 | |||
1965 | |||
1966 | <p> | ||
1967 | Environments associated with Lua functions are used to resolve | ||
1968 | all accesses to global variables within the function (see <a href="#2.3">§2.3</a>). | ||
1969 | They are used as the default environment for nested Lua functions | ||
1970 | created by the function. | ||
1971 | |||
1972 | |||
1973 | <p> | ||
1974 | You can change the environment of a Lua function or the | ||
1975 | running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>. | ||
1976 | You can get the environment of a Lua function or the running thread | ||
1977 | by calling <a href="#pdf-getfenv"><code>getfenv</code></a>. | ||
1978 | To manipulate the environment of other objects | ||
1979 | (userdata, C functions, other threads) you must | ||
1980 | use the C API. | ||
1981 | |||
1982 | |||
1983 | |||
1984 | |||
1985 | |||
1986 | <h2>2.10 - <a name="2.10">Garbage Collection</a></h2> | ||
1987 | |||
1988 | <p> | ||
1989 | Lua performs automatic memory management. | ||
1990 | This means that | ||
1991 | you have to worry neither about allocating memory for new objects | ||
1992 | nor about freeing it when the objects are no longer needed. | ||
1993 | Lua manages memory automatically by running | ||
1994 | a <em>garbage collector</em> from time to time | ||
1995 | to collect all <em>dead objects</em> | ||
1996 | (that is, objects that are no longer accessible from Lua). | ||
1997 | All memory used by Lua is subject to automatic management: | ||
1998 | tables, userdata, functions, threads, strings, etc. | ||
1999 | |||
2000 | |||
2001 | <p> | ||
2002 | Lua implements an incremental mark-and-sweep collector. | ||
2003 | It uses two numbers to control its garbage-collection cycles: | ||
2004 | the <em>garbage-collector pause</em> and | ||
2005 | the <em>garbage-collector step multiplier</em>. | ||
2006 | Both use percentage points as units | ||
2007 | (so that a value of 100 means an internal value of 1). | ||
2008 | |||
2009 | |||
2010 | <p> | ||
2011 | The garbage-collector pause | ||
2012 | controls how long the collector waits before starting a new cycle. | ||
2013 | Larger values make the collector less aggressive. | ||
2014 | Values smaller than 100 mean the collector will not wait to | ||
2015 | start a new cycle. | ||
2016 | A value of 200 means that the collector waits for the total memory in use | ||
2017 | to double before starting a new cycle. | ||
2018 | |||
2019 | |||
2020 | <p> | ||
2021 | The step multiplier | ||
2022 | controls the relative speed of the collector relative to | ||
2023 | memory allocation. | ||
2024 | Larger values make the collector more aggressive but also increase | ||
2025 | the size of each incremental step. | ||
2026 | Values smaller than 100 make the collector too slow and | ||
2027 | can result in the collector never finishing a cycle. | ||
2028 | The default, 200, means that the collector runs at "twice" | ||
2029 | the speed of memory allocation. | ||
2030 | |||
2031 | |||
2032 | <p> | ||
2033 | You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C | ||
2034 | or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. | ||
2035 | With these functions you can also control | ||
2036 | the collector directly (e.g., stop and restart it). | ||
2037 | |||
2038 | |||
2039 | |||
2040 | <h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3> | ||
2041 | |||
2042 | <p> | ||
2043 | Using the C API, | ||
2044 | you can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>). | ||
2045 | These metamethods are also called <em>finalizers</em>. | ||
2046 | Finalizers allow you to coordinate Lua's garbage collection | ||
2047 | with external resource management | ||
2048 | (such as closing files, network or database connections, | ||
2049 | or freeing your own memory). | ||
2050 | |||
2051 | |||
2052 | <p> | ||
2053 | Garbage userdata with a field <code>__gc</code> in their metatables are not | ||
2054 | collected immediately by the garbage collector. | ||
2055 | Instead, Lua puts them in a list. | ||
2056 | After the collection, | ||
2057 | Lua does the equivalent of the following function | ||
2058 | for each userdata in that list: | ||
2059 | |||
2060 | <pre> | ||
2061 | function gc_event (udata) | ||
2062 | local h = metatable(udata).__gc | ||
2063 | if h then | ||
2064 | h(udata) | ||
2065 | end | ||
2066 | end | ||
2067 | </pre> | ||
2068 | |||
2069 | <p> | ||
2070 | At the end of each garbage-collection cycle, | ||
2071 | the finalizers for userdata are called in <em>reverse</em> | ||
2072 | order of their creation, | ||
2073 | among those collected in that cycle. | ||
2074 | That is, the first finalizer to be called is the one associated | ||
2075 | with the userdata created last in the program. | ||
2076 | The userdata itself is freed only in the next garbage-collection cycle. | ||
2077 | |||
2078 | |||
2079 | |||
2080 | |||
2081 | |||
2082 | <h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3> | ||
2083 | |||
2084 | <p> | ||
2085 | A <em>weak table</em> is a table whose elements are | ||
2086 | <em>weak references</em>. | ||
2087 | A weak reference is ignored by the garbage collector. | ||
2088 | In other words, | ||
2089 | if the only references to an object are weak references, | ||
2090 | then the garbage collector will collect this object. | ||
2091 | |||
2092 | |||
2093 | <p> | ||
2094 | A weak table can have weak keys, weak values, or both. | ||
2095 | A table with weak keys allows the collection of its keys, | ||
2096 | but prevents the collection of its values. | ||
2097 | A table with both weak keys and weak values allows the collection of | ||
2098 | both keys and values. | ||
2099 | In any case, if either the key or the value is collected, | ||
2100 | the whole pair is removed from the table. | ||
2101 | The weakness of a table is controlled by the | ||
2102 | <code>__mode</code> field of its metatable. | ||
2103 | If the <code>__mode</code> field is a string containing the character '<code>k</code>', | ||
2104 | the keys in the table are weak. | ||
2105 | If <code>__mode</code> contains '<code>v</code>', | ||
2106 | the values in the table are weak. | ||
2107 | |||
2108 | |||
2109 | <p> | ||
2110 | After you use a table as a metatable, | ||
2111 | you should not change the value of its <code>__mode</code> field. | ||
2112 | Otherwise, the weak behavior of the tables controlled by this | ||
2113 | metatable is undefined. | ||
2114 | |||
2115 | |||
2116 | |||
2117 | |||
2118 | |||
2119 | |||
2120 | |||
2121 | <h2>2.11 - <a name="2.11">Coroutines</a></h2> | ||
2122 | |||
2123 | <p> | ||
2124 | Lua supports coroutines, | ||
2125 | also called <em>collaborative multithreading</em>. | ||
2126 | A coroutine in Lua represents an independent thread of execution. | ||
2127 | Unlike threads in multithread systems, however, | ||
2128 | a coroutine only suspends its execution by explicitly calling | ||
2129 | a yield function. | ||
2130 | |||
2131 | |||
2132 | <p> | ||
2133 | You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. | ||
2134 | Its sole argument is a function | ||
2135 | that is the main function of the coroutine. | ||
2136 | The <code>create</code> function only creates a new coroutine and | ||
2137 | returns a handle to it (an object of type <em>thread</em>); | ||
2138 | it does not start the coroutine execution. | ||
2139 | |||
2140 | |||
2141 | <p> | ||
2142 | When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, | ||
2143 | passing as its first argument | ||
2144 | a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, | ||
2145 | the coroutine starts its execution, | ||
2146 | at the first line of its main function. | ||
2147 | Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on | ||
2148 | to the coroutine main function. | ||
2149 | After the coroutine starts running, | ||
2150 | it runs until it terminates or <em>yields</em>. | ||
2151 | |||
2152 | |||
2153 | <p> | ||
2154 | A coroutine can terminate its execution in two ways: | ||
2155 | normally, when its main function returns | ||
2156 | (explicitly or implicitly, after the last instruction); | ||
2157 | and abnormally, if there is an unprotected error. | ||
2158 | In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, | ||
2159 | plus any values returned by the coroutine main function. | ||
2160 | In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> | ||
2161 | plus an error message. | ||
2162 | |||
2163 | |||
2164 | <p> | ||
2165 | A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. | ||
2166 | When a coroutine yields, | ||
2167 | the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, | ||
2168 | even if the yield happens inside nested function calls | ||
2169 | (that is, not in the main function, | ||
2170 | but in a function directly or indirectly called by the main function). | ||
2171 | In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, | ||
2172 | plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. | ||
2173 | The next time you resume the same coroutine, | ||
2174 | it continues its execution from the point where it yielded, | ||
2175 | with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra | ||
2176 | arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. | ||
2177 | |||
2178 | |||
2179 | <p> | ||
2180 | Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, | ||
2181 | the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, | ||
2182 | but instead of returning the coroutine itself, | ||
2183 | it returns a function that, when called, resumes the coroutine. | ||
2184 | Any arguments passed to this function | ||
2185 | go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. | ||
2186 | <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, | ||
2187 | except the first one (the boolean error code). | ||
2188 | Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, | ||
2189 | <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; | ||
2190 | any error is propagated to the caller. | ||
2191 | |||
2192 | |||
2193 | <p> | ||
2194 | As an example, | ||
2195 | consider the following code: | ||
2196 | |||
2197 | <pre> | ||
2198 | function foo (a) | ||
2199 | print("foo", a) | ||
2200 | return coroutine.yield(2*a) | ||
2201 | end | ||
2202 | |||
2203 | co = coroutine.create(function (a,b) | ||
2204 | print("co-body", a, b) | ||
2205 | local r = foo(a+1) | ||
2206 | print("co-body", r) | ||
2207 | local r, s = coroutine.yield(a+b, a-b) | ||
2208 | print("co-body", r, s) | ||
2209 | return b, "end" | ||
2210 | end) | ||
2211 | |||
2212 | print("main", coroutine.resume(co, 1, 10)) | ||
2213 | print("main", coroutine.resume(co, "r")) | ||
2214 | print("main", coroutine.resume(co, "x", "y")) | ||
2215 | print("main", coroutine.resume(co, "x", "y")) | ||
2216 | </pre><p> | ||
2217 | When you run it, it produces the following output: | ||
2218 | |||
2219 | <pre> | ||
2220 | co-body 1 10 | ||
2221 | foo 2 | ||
2222 | |||
2223 | main true 4 | ||
2224 | co-body r | ||
2225 | main true 11 -9 | ||
2226 | co-body x y | ||
2227 | main true 10 end | ||
2228 | main false cannot resume dead coroutine | ||
2229 | </pre> | ||
2230 | |||
2231 | |||
2232 | |||
2233 | |||
2234 | <h1>3 - <a name="3">The Application Program Interface</a></h1> | ||
2235 | |||
2236 | <p> | ||
2237 | |||
2238 | This section describes the C API for Lua, that is, | ||
2239 | the set of C functions available to the host program to communicate | ||
2240 | with Lua. | ||
2241 | All API functions and related types and constants | ||
2242 | are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. | ||
2243 | |||
2244 | |||
2245 | <p> | ||
2246 | Even when we use the term "function", | ||
2247 | any facility in the API may be provided as a macro instead. | ||
2248 | All such macros use each of their arguments exactly once | ||
2249 | (except for the first argument, which is always a Lua state), | ||
2250 | and so do not generate any hidden side-effects. | ||
2251 | |||
2252 | |||
2253 | <p> | ||
2254 | As in most C libraries, | ||
2255 | the Lua API functions do not check their arguments for validity or consistency. | ||
2256 | However, you can change this behavior by compiling Lua | ||
2257 | with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>, | ||
2258 | in file <code>luaconf.h</code>. | ||
2259 | |||
2260 | |||
2261 | |||
2262 | <h2>3.1 - <a name="3.1">The Stack</a></h2> | ||
2263 | |||
2264 | <p> | ||
2265 | Lua uses a <em>virtual stack</em> to pass values to and from C. | ||
2266 | Each element in this stack represents a Lua value | ||
2267 | (<b>nil</b>, number, string, etc.). | ||
2268 | |||
2269 | |||
2270 | <p> | ||
2271 | Whenever Lua calls C, the called function gets a new stack, | ||
2272 | which is independent of previous stacks and of stacks of | ||
2273 | C functions that are still active. | ||
2274 | This stack initially contains any arguments to the C function | ||
2275 | and it is where the C function pushes its results | ||
2276 | to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). | ||
2277 | |||
2278 | |||
2279 | <p> | ||
2280 | For convenience, | ||
2281 | most query operations in the API do not follow a strict stack discipline. | ||
2282 | Instead, they can refer to any element in the stack | ||
2283 | by using an <em>index</em>: | ||
2284 | A positive index represents an <em>absolute</em> stack position | ||
2285 | (starting at 1); | ||
2286 | a negative index represents an <em>offset</em> relative to the top of the stack. | ||
2287 | More specifically, if the stack has <em>n</em> elements, | ||
2288 | then index 1 represents the first element | ||
2289 | (that is, the element that was pushed onto the stack first) | ||
2290 | and | ||
2291 | index <em>n</em> represents the last element; | ||
2292 | index -1 also represents the last element | ||
2293 | (that is, the element at the top) | ||
2294 | and index <em>-n</em> represents the first element. | ||
2295 | We say that an index is <em>valid</em> | ||
2296 | if it lies between 1 and the stack top | ||
2297 | (that is, if <code>1 ≤ abs(index) ≤ top</code>). | ||
2298 | |||
2299 | |||
2300 | |||
2301 | |||
2302 | |||
2303 | |||
2304 | <h2>3.2 - <a name="3.2">Stack Size</a></h2> | ||
2305 | |||
2306 | <p> | ||
2307 | When you interact with Lua API, | ||
2308 | you are responsible for ensuring consistency. | ||
2309 | In particular, | ||
2310 | <em>you are responsible for controlling stack overflow</em>. | ||
2311 | You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> | ||
2312 | to grow the stack size. | ||
2313 | |||
2314 | |||
2315 | <p> | ||
2316 | Whenever Lua calls C, | ||
2317 | it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available. | ||
2318 | <code>LUA_MINSTACK</code> is defined as 20, | ||
2319 | so that usually you do not have to worry about stack space | ||
2320 | unless your code has loops pushing elements onto the stack. | ||
2321 | |||
2322 | |||
2323 | <p> | ||
2324 | Most query functions accept as indices any value inside the | ||
2325 | available stack space, that is, indices up to the maximum stack size | ||
2326 | you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>. | ||
2327 | Such indices are called <em>acceptable indices</em>. | ||
2328 | More formally, we define an <em>acceptable index</em> | ||
2329 | as follows: | ||
2330 | |||
2331 | <pre> | ||
2332 | (index < 0 && abs(index) <= top) || | ||
2333 | (index > 0 && index <= stackspace) | ||
2334 | </pre><p> | ||
2335 | Note that 0 is never an acceptable index. | ||
2336 | |||
2337 | |||
2338 | |||
2339 | |||
2340 | |||
2341 | <h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2> | ||
2342 | |||
2343 | <p> | ||
2344 | Unless otherwise noted, | ||
2345 | any function that accepts valid indices can also be called with | ||
2346 | <em>pseudo-indices</em>, | ||
2347 | which represent some Lua values that are accessible to C code | ||
2348 | but which are not in the stack. | ||
2349 | Pseudo-indices are used to access the thread environment, | ||
2350 | the function environment, | ||
2351 | the registry, | ||
2352 | and the upvalues of a C function (see <a href="#3.4">§3.4</a>). | ||
2353 | |||
2354 | |||
2355 | <p> | ||
2356 | The thread environment (where global variables live) is | ||
2357 | always at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>. | ||
2358 | The environment of the running C function is always | ||
2359 | at pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>. | ||
2360 | |||
2361 | |||
2362 | <p> | ||
2363 | To access and change the value of global variables, | ||
2364 | you can use regular table operations over an environment table. | ||
2365 | For instance, to access the value of a global variable, do | ||
2366 | |||
2367 | <pre> | ||
2368 | lua_getfield(L, LUA_GLOBALSINDEX, varname); | ||
2369 | </pre> | ||
2370 | |||
2371 | |||
2372 | |||
2373 | |||
2374 | <h2>3.4 - <a name="3.4">C Closures</a></h2> | ||
2375 | |||
2376 | <p> | ||
2377 | When a C function is created, | ||
2378 | it is possible to associate some values with it, | ||
2379 | thus creating a <em>C closure</em>; | ||
2380 | these values are called <em>upvalues</em> and are | ||
2381 | accessible to the function whenever it is called | ||
2382 | (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). | ||
2383 | |||
2384 | |||
2385 | <p> | ||
2386 | Whenever a C function is called, | ||
2387 | its upvalues are located at specific pseudo-indices. | ||
2388 | These pseudo-indices are produced by the macro | ||
2389 | <a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>. | ||
2390 | The first value associated with a function is at position | ||
2391 | <code>lua_upvalueindex(1)</code>, and so on. | ||
2392 | Any access to <code>lua_upvalueindex(<em>n</em>)</code>, | ||
2393 | where <em>n</em> is greater than the number of upvalues of the | ||
2394 | current function (but not greater than 256), | ||
2395 | produces an acceptable (but invalid) index. | ||
2396 | |||
2397 | |||
2398 | |||
2399 | |||
2400 | |||
2401 | <h2>3.5 - <a name="3.5">Registry</a></h2> | ||
2402 | |||
2403 | <p> | ||
2404 | Lua provides a <em>registry</em>, | ||
2405 | a pre-defined table that can be used by any C code to | ||
2406 | store whatever Lua value it needs to store. | ||
2407 | This table is always located at pseudo-index | ||
2408 | <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. | ||
2409 | Any C library can store data into this table, | ||
2410 | but it should take care to choose keys different from those used | ||
2411 | by other libraries, to avoid collisions. | ||
2412 | Typically, you should use as key a string containing your library name | ||
2413 | or a light userdata with the address of a C object in your code. | ||
2414 | |||
2415 | |||
2416 | <p> | ||
2417 | The integer keys in the registry are used by the reference mechanism, | ||
2418 | implemented by the auxiliary library, | ||
2419 | and therefore should not be used for other purposes. | ||
2420 | |||
2421 | |||
2422 | |||
2423 | |||
2424 | |||
2425 | <h2>3.6 - <a name="3.6">Error Handling in C</a></h2> | ||
2426 | |||
2427 | <p> | ||
2428 | Internally, Lua uses the C <code>longjmp</code> facility to handle errors. | ||
2429 | (You can also choose to use exceptions if you use C++; | ||
2430 | see file <code>luaconf.h</code>.) | ||
2431 | When Lua faces any error | ||
2432 | (such as memory allocation errors, type errors, syntax errors, | ||
2433 | and runtime errors) | ||
2434 | it <em>raises</em> an error; | ||
2435 | that is, it does a long jump. | ||
2436 | A <em>protected environment</em> uses <code>setjmp</code> | ||
2437 | to set a recover point; | ||
2438 | any error jumps to the most recent active recover point. | ||
2439 | |||
2440 | |||
2441 | <p> | ||
2442 | Most functions in the API can throw an error, | ||
2443 | for instance due to a memory allocation error. | ||
2444 | The documentation for each function indicates whether | ||
2445 | it can throw errors. | ||
2446 | |||
2447 | |||
2448 | <p> | ||
2449 | Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>. | ||
2450 | |||
2451 | |||
2452 | |||
2453 | |||
2454 | |||
2455 | <h2>3.7 - <a name="3.7">Functions and Types</a></h2> | ||
2456 | |||
2457 | <p> | ||
2458 | Here we list all functions and types from the C API in | ||
2459 | alphabetical order. | ||
2460 | Each function has an indicator like this: | ||
2461 | <span class="apii">[-o, +p, <em>x</em>]</span> | ||
2462 | |||
2463 | |||
2464 | <p> | ||
2465 | The first field, <code>o</code>, | ||
2466 | is how many elements the function pops from the stack. | ||
2467 | The second field, <code>p</code>, | ||
2468 | is how many elements the function pushes onto the stack. | ||
2469 | (Any function always pushes its results after popping its arguments.) | ||
2470 | A field in the form <code>x|y</code> means the function can push (or pop) | ||
2471 | <code>x</code> or <code>y</code> elements, | ||
2472 | depending on the situation; | ||
2473 | an interrogation mark '<code>?</code>' means that | ||
2474 | we cannot know how many elements the function pops/pushes | ||
2475 | by looking only at its arguments | ||
2476 | (e.g., they may depend on what is on the stack). | ||
2477 | The third field, <code>x</code>, | ||
2478 | tells whether the function may throw errors: | ||
2479 | '<code>-</code>' means the function never throws any error; | ||
2480 | '<code>m</code>' means the function may throw an error | ||
2481 | only due to not enough memory; | ||
2482 | '<code>e</code>' means the function may throw other kinds of errors; | ||
2483 | '<code>v</code>' means the function may throw an error on purpose. | ||
2484 | |||
2485 | |||
2486 | |||
2487 | <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> | ||
2488 | <pre>typedef void * (*lua_Alloc) (void *ud, | ||
2489 | void *ptr, | ||
2490 | size_t osize, | ||
2491 | size_t nsize);</pre> | ||
2492 | |||
2493 | <p> | ||
2494 | The type of the memory-allocation function used by Lua states. | ||
2495 | The allocator function must provide a | ||
2496 | functionality similar to <code>realloc</code>, | ||
2497 | but not exactly the same. | ||
2498 | Its arguments are | ||
2499 | <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; | ||
2500 | <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; | ||
2501 | <code>osize</code>, the original size of the block; | ||
2502 | <code>nsize</code>, the new size of the block. | ||
2503 | <code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero. | ||
2504 | When <code>nsize</code> is zero, the allocator must return <code>NULL</code>; | ||
2505 | if <code>osize</code> is not zero, | ||
2506 | it should free the block pointed to by <code>ptr</code>. | ||
2507 | When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> | ||
2508 | if and only if it cannot fill the request. | ||
2509 | When <code>nsize</code> is not zero and <code>osize</code> is zero, | ||
2510 | the allocator should behave like <code>malloc</code>. | ||
2511 | When <code>nsize</code> and <code>osize</code> are not zero, | ||
2512 | the allocator behaves like <code>realloc</code>. | ||
2513 | Lua assumes that the allocator never fails when | ||
2514 | <code>osize >= nsize</code>. | ||
2515 | |||
2516 | |||
2517 | <p> | ||
2518 | Here is a simple implementation for the allocator function. | ||
2519 | It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. | ||
2520 | |||
2521 | <pre> | ||
2522 | static void *l_alloc (void *ud, void *ptr, size_t osize, | ||
2523 | size_t nsize) { | ||
2524 | (void)ud; (void)osize; /* not used */ | ||
2525 | if (nsize == 0) { | ||
2526 | free(ptr); | ||
2527 | return NULL; | ||
2528 | } | ||
2529 | else | ||
2530 | return realloc(ptr, nsize); | ||
2531 | } | ||
2532 | </pre><p> | ||
2533 | This code assumes | ||
2534 | that <code>free(NULL)</code> has no effect and that | ||
2535 | <code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. | ||
2536 | ANSI C ensures both behaviors. | ||
2537 | |||
2538 | |||
2539 | |||
2540 | |||
2541 | |||
2542 | <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> | ||
2543 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
2544 | <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> | ||
2545 | |||
2546 | <p> | ||
2547 | Sets a new panic function and returns the old one. | ||
2548 | |||
2549 | |||
2550 | <p> | ||
2551 | If an error happens outside any protected environment, | ||
2552 | Lua calls a <em>panic function</em> | ||
2553 | and then calls <code>exit(EXIT_FAILURE)</code>, | ||
2554 | thus exiting the host application. | ||
2555 | Your panic function can avoid this exit by | ||
2556 | never returning (e.g., doing a long jump). | ||
2557 | |||
2558 | |||
2559 | <p> | ||
2560 | The panic function can access the error message at the top of the stack. | ||
2561 | |||
2562 | |||
2563 | |||
2564 | |||
2565 | |||
2566 | <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> | ||
2567 | <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> | ||
2568 | <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> | ||
2569 | |||
2570 | <p> | ||
2571 | Calls a function. | ||
2572 | |||
2573 | |||
2574 | <p> | ||
2575 | To call a function you must use the following protocol: | ||
2576 | first, the function to be called is pushed onto the stack; | ||
2577 | then, the arguments to the function are pushed | ||
2578 | in direct order; | ||
2579 | that is, the first argument is pushed first. | ||
2580 | Finally you call <a href="#lua_call"><code>lua_call</code></a>; | ||
2581 | <code>nargs</code> is the number of arguments that you pushed onto the stack. | ||
2582 | All arguments and the function value are popped from the stack | ||
2583 | when the function is called. | ||
2584 | The function results are pushed onto the stack when the function returns. | ||
2585 | The number of results is adjusted to <code>nresults</code>, | ||
2586 | unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. | ||
2587 | In this case, <em>all</em> results from the function are pushed. | ||
2588 | Lua takes care that the returned values fit into the stack space. | ||
2589 | The function results are pushed onto the stack in direct order | ||
2590 | (the first result is pushed first), | ||
2591 | so that after the call the last result is on the top of the stack. | ||
2592 | |||
2593 | |||
2594 | <p> | ||
2595 | Any error inside the called function is propagated upwards | ||
2596 | (with a <code>longjmp</code>). | ||
2597 | |||
2598 | |||
2599 | <p> | ||
2600 | The following example shows how the host program can do the | ||
2601 | equivalent to this Lua code: | ||
2602 | |||
2603 | <pre> | ||
2604 | a = f("how", t.x, 14) | ||
2605 | </pre><p> | ||
2606 | Here it is in C: | ||
2607 | |||
2608 | <pre> | ||
2609 | lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ | ||
2610 | lua_pushstring(L, "how"); /* 1st argument */ | ||
2611 | lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ | ||
2612 | lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ | ||
2613 | lua_remove(L, -2); /* remove 't' from the stack */ | ||
2614 | lua_pushinteger(L, 14); /* 3rd argument */ | ||
2615 | lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ | ||
2616 | lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ | ||
2617 | </pre><p> | ||
2618 | Note that the code above is "balanced": | ||
2619 | at its end, the stack is back to its original configuration. | ||
2620 | This is considered good programming practice. | ||
2621 | |||
2622 | |||
2623 | |||
2624 | |||
2625 | |||
2626 | <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> | ||
2627 | <pre>typedef int (*lua_CFunction) (lua_State *L);</pre> | ||
2628 | |||
2629 | <p> | ||
2630 | Type for C functions. | ||
2631 | |||
2632 | |||
2633 | <p> | ||
2634 | In order to communicate properly with Lua, | ||
2635 | a C function must use the following protocol, | ||
2636 | which defines the way parameters and results are passed: | ||
2637 | a C function receives its arguments from Lua in its stack | ||
2638 | in direct order (the first argument is pushed first). | ||
2639 | So, when the function starts, | ||
2640 | <code>lua_gettop(L)</code> returns the number of arguments received by the function. | ||
2641 | The first argument (if any) is at index 1 | ||
2642 | and its last argument is at index <code>lua_gettop(L)</code>. | ||
2643 | To return values to Lua, a C function just pushes them onto the stack, | ||
2644 | in direct order (the first result is pushed first), | ||
2645 | and returns the number of results. | ||
2646 | Any other value in the stack below the results will be properly | ||
2647 | discarded by Lua. | ||
2648 | Like a Lua function, a C function called by Lua can also return | ||
2649 | many results. | ||
2650 | |||
2651 | |||
2652 | <p> | ||
2653 | As an example, the following function receives a variable number | ||
2654 | of numerical arguments and returns their average and sum: | ||
2655 | |||
2656 | <pre> | ||
2657 | static int foo (lua_State *L) { | ||
2658 | int n = lua_gettop(L); /* number of arguments */ | ||
2659 | lua_Number sum = 0; | ||
2660 | int i; | ||
2661 | for (i = 1; i <= n; i++) { | ||
2662 | if (!lua_isnumber(L, i)) { | ||
2663 | lua_pushstring(L, "incorrect argument"); | ||
2664 | lua_error(L); | ||
2665 | } | ||
2666 | sum += lua_tonumber(L, i); | ||
2667 | } | ||
2668 | lua_pushnumber(L, sum/n); /* first result */ | ||
2669 | lua_pushnumber(L, sum); /* second result */ | ||
2670 | return 2; /* number of results */ | ||
2671 | } | ||
2672 | </pre> | ||
2673 | |||
2674 | |||
2675 | |||
2676 | |||
2677 | <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> | ||
2678 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
2679 | <pre>int lua_checkstack (lua_State *L, int extra);</pre> | ||
2680 | |||
2681 | <p> | ||
2682 | Ensures that there are at least <code>extra</code> free stack slots in the stack. | ||
2683 | It returns false if it cannot grow the stack to that size. | ||
2684 | This function never shrinks the stack; | ||
2685 | if the stack is already larger than the new size, | ||
2686 | it is left unchanged. | ||
2687 | |||
2688 | |||
2689 | |||
2690 | |||
2691 | |||
2692 | <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> | ||
2693 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
2694 | <pre>void lua_close (lua_State *L);</pre> | ||
2695 | |||
2696 | <p> | ||
2697 | Destroys all objects in the given Lua state | ||
2698 | (calling the corresponding garbage-collection metamethods, if any) | ||
2699 | and frees all dynamic memory used by this state. | ||
2700 | On several platforms, you may not need to call this function, | ||
2701 | because all resources are naturally released when the host program ends. | ||
2702 | On the other hand, long-running programs, | ||
2703 | such as a daemon or a web server, | ||
2704 | might need to release states as soon as they are not needed, | ||
2705 | to avoid growing too large. | ||
2706 | |||
2707 | |||
2708 | |||
2709 | |||
2710 | |||
2711 | <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> | ||
2712 | <span class="apii">[-n, +1, <em>e</em>]</span> | ||
2713 | <pre>void lua_concat (lua_State *L, int n);</pre> | ||
2714 | |||
2715 | <p> | ||
2716 | Concatenates the <code>n</code> values at the top of the stack, | ||
2717 | pops them, and leaves the result at the top. | ||
2718 | If <code>n</code> is 1, the result is the single value on the stack | ||
2719 | (that is, the function does nothing); | ||
2720 | if <code>n</code> is 0, the result is the empty string. | ||
2721 | Concatenation is performed following the usual semantics of Lua | ||
2722 | (see <a href="#2.5.4">§2.5.4</a>). | ||
2723 | |||
2724 | |||
2725 | |||
2726 | |||
2727 | |||
2728 | <hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p> | ||
2729 | <span class="apii">[-0, +(0|1), <em>-</em>]</span> | ||
2730 | <pre>int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);</pre> | ||
2731 | |||
2732 | <p> | ||
2733 | Calls the C function <code>func</code> in protected mode. | ||
2734 | <code>func</code> starts with only one element in its stack, | ||
2735 | a light userdata containing <code>ud</code>. | ||
2736 | In case of errors, | ||
2737 | <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, | ||
2738 | plus the error object on the top of the stack; | ||
2739 | otherwise, it returns zero, and does not change the stack. | ||
2740 | All values returned by <code>func</code> are discarded. | ||
2741 | |||
2742 | |||
2743 | |||
2744 | |||
2745 | |||
2746 | <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> | ||
2747 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
2748 | <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> | ||
2749 | |||
2750 | <p> | ||
2751 | Creates a new empty table and pushes it onto the stack. | ||
2752 | The new table has space pre-allocated | ||
2753 | for <code>narr</code> array elements and <code>nrec</code> non-array elements. | ||
2754 | This pre-allocation is useful when you know exactly how many elements | ||
2755 | the table will have. | ||
2756 | Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. | ||
2757 | |||
2758 | |||
2759 | |||
2760 | |||
2761 | |||
2762 | <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> | ||
2763 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
2764 | <pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre> | ||
2765 | |||
2766 | <p> | ||
2767 | Dumps a function as a binary chunk. | ||
2768 | Receives a Lua function on the top of the stack | ||
2769 | and produces a binary chunk that, | ||
2770 | if loaded again, | ||
2771 | results in a function equivalent to the one dumped. | ||
2772 | As it produces parts of the chunk, | ||
2773 | <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) | ||
2774 | with the given <code>data</code> | ||
2775 | to write them. | ||
2776 | |||
2777 | |||
2778 | <p> | ||
2779 | The value returned is the error code returned by the last | ||
2780 | call to the writer; | ||
2781 | 0 means no errors. | ||
2782 | |||
2783 | |||
2784 | <p> | ||
2785 | This function does not pop the Lua function from the stack. | ||
2786 | |||
2787 | |||
2788 | |||
2789 | |||
2790 | |||
2791 | <hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p> | ||
2792 | <span class="apii">[-0, +0, <em>e</em>]</span> | ||
2793 | <pre>int lua_equal (lua_State *L, int index1, int index2);</pre> | ||
2794 | |||
2795 | <p> | ||
2796 | Returns 1 if the two values in acceptable indices <code>index1</code> and | ||
2797 | <code>index2</code> are equal, | ||
2798 | following the semantics of the Lua <code>==</code> operator | ||
2799 | (that is, may call metamethods). | ||
2800 | Otherwise returns 0. | ||
2801 | Also returns 0 if any of the indices is non valid. | ||
2802 | |||
2803 | |||
2804 | |||
2805 | |||
2806 | |||
2807 | <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> | ||
2808 | <span class="apii">[-1, +0, <em>v</em>]</span> | ||
2809 | <pre>int lua_error (lua_State *L);</pre> | ||
2810 | |||
2811 | <p> | ||
2812 | Generates a Lua error. | ||
2813 | The error message (which can actually be a Lua value of any type) | ||
2814 | must be on the stack top. | ||
2815 | This function does a long jump, | ||
2816 | and therefore never returns. | ||
2817 | (see <a href="#luaL_error"><code>luaL_error</code></a>). | ||
2818 | |||
2819 | |||
2820 | |||
2821 | |||
2822 | |||
2823 | <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> | ||
2824 | <span class="apii">[-0, +0, <em>e</em>]</span> | ||
2825 | <pre>int lua_gc (lua_State *L, int what, int data);</pre> | ||
2826 | |||
2827 | <p> | ||
2828 | Controls the garbage collector. | ||
2829 | |||
2830 | |||
2831 | <p> | ||
2832 | This function performs several tasks, | ||
2833 | according to the value of the parameter <code>what</code>: | ||
2834 | |||
2835 | <ul> | ||
2836 | |||
2837 | <li><b><code>LUA_GCSTOP</code>:</b> | ||
2838 | stops the garbage collector. | ||
2839 | </li> | ||
2840 | |||
2841 | <li><b><code>LUA_GCRESTART</code>:</b> | ||
2842 | restarts the garbage collector. | ||
2843 | </li> | ||
2844 | |||
2845 | <li><b><code>LUA_GCCOLLECT</code>:</b> | ||
2846 | performs a full garbage-collection cycle. | ||
2847 | </li> | ||
2848 | |||
2849 | <li><b><code>LUA_GCCOUNT</code>:</b> | ||
2850 | returns the current amount of memory (in Kbytes) in use by Lua. | ||
2851 | </li> | ||
2852 | |||
2853 | <li><b><code>LUA_GCCOUNTB</code>:</b> | ||
2854 | returns the remainder of dividing the current amount of bytes of | ||
2855 | memory in use by Lua by 1024. | ||
2856 | </li> | ||
2857 | |||
2858 | <li><b><code>LUA_GCSTEP</code>:</b> | ||
2859 | performs an incremental step of garbage collection. | ||
2860 | The step "size" is controlled by <code>data</code> | ||
2861 | (larger values mean more steps) in a non-specified way. | ||
2862 | If you want to control the step size | ||
2863 | you must experimentally tune the value of <code>data</code>. | ||
2864 | The function returns 1 if the step finished a | ||
2865 | garbage-collection cycle. | ||
2866 | </li> | ||
2867 | |||
2868 | <li><b><code>LUA_GCSETPAUSE</code>:</b> | ||
2869 | sets <code>data</code> as the new value | ||
2870 | for the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>). | ||
2871 | The function returns the previous value of the pause. | ||
2872 | </li> | ||
2873 | |||
2874 | <li><b><code>LUA_GCSETSTEPMUL</code>:</b> | ||
2875 | sets <code>data</code> as the new value for the <em>step multiplier</em> of | ||
2876 | the collector (see <a href="#2.10">§2.10</a>). | ||
2877 | The function returns the previous value of the step multiplier. | ||
2878 | </li> | ||
2879 | |||
2880 | </ul> | ||
2881 | |||
2882 | |||
2883 | |||
2884 | |||
2885 | <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> | ||
2886 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
2887 | <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> | ||
2888 | |||
2889 | <p> | ||
2890 | Returns the memory-allocation function of a given state. | ||
2891 | If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the | ||
2892 | opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. | ||
2893 | |||
2894 | |||
2895 | |||
2896 | |||
2897 | |||
2898 | <hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p> | ||
2899 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
2900 | <pre>void lua_getfenv (lua_State *L, int index);</pre> | ||
2901 | |||
2902 | <p> | ||
2903 | Pushes onto the stack the environment table of | ||
2904 | the value at the given index. | ||
2905 | |||
2906 | |||
2907 | |||
2908 | |||
2909 | |||
2910 | <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> | ||
2911 | <span class="apii">[-0, +1, <em>e</em>]</span> | ||
2912 | <pre>void lua_getfield (lua_State *L, int index, const char *k);</pre> | ||
2913 | |||
2914 | <p> | ||
2915 | Pushes onto the stack the value <code>t[k]</code>, | ||
2916 | where <code>t</code> is the value at the given valid index. | ||
2917 | As in Lua, this function may trigger a metamethod | ||
2918 | for the "index" event (see <a href="#2.8">§2.8</a>). | ||
2919 | |||
2920 | |||
2921 | |||
2922 | |||
2923 | |||
2924 | <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> | ||
2925 | <span class="apii">[-0, +1, <em>e</em>]</span> | ||
2926 | <pre>void lua_getglobal (lua_State *L, const char *name);</pre> | ||
2927 | |||
2928 | <p> | ||
2929 | Pushes onto the stack the value of the global <code>name</code>. | ||
2930 | It is defined as a macro: | ||
2931 | |||
2932 | <pre> | ||
2933 | #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) | ||
2934 | </pre> | ||
2935 | |||
2936 | |||
2937 | |||
2938 | |||
2939 | <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> | ||
2940 | <span class="apii">[-0, +(0|1), <em>-</em>]</span> | ||
2941 | <pre>int lua_getmetatable (lua_State *L, int index);</pre> | ||
2942 | |||
2943 | <p> | ||
2944 | Pushes onto the stack the metatable of the value at the given | ||
2945 | acceptable index. | ||
2946 | If the index is not valid, | ||
2947 | or if the value does not have a metatable, | ||
2948 | the function returns 0 and pushes nothing on the stack. | ||
2949 | |||
2950 | |||
2951 | |||
2952 | |||
2953 | |||
2954 | <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> | ||
2955 | <span class="apii">[-1, +1, <em>e</em>]</span> | ||
2956 | <pre>void lua_gettable (lua_State *L, int index);</pre> | ||
2957 | |||
2958 | <p> | ||
2959 | Pushes onto the stack the value <code>t[k]</code>, | ||
2960 | where <code>t</code> is the value at the given valid index | ||
2961 | and <code>k</code> is the value at the top of the stack. | ||
2962 | |||
2963 | |||
2964 | <p> | ||
2965 | This function pops the key from the stack | ||
2966 | (putting the resulting value in its place). | ||
2967 | As in Lua, this function may trigger a metamethod | ||
2968 | for the "index" event (see <a href="#2.8">§2.8</a>). | ||
2969 | |||
2970 | |||
2971 | |||
2972 | |||
2973 | |||
2974 | <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> | ||
2975 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
2976 | <pre>int lua_gettop (lua_State *L);</pre> | ||
2977 | |||
2978 | <p> | ||
2979 | Returns the index of the top element in the stack. | ||
2980 | Because indices start at 1, | ||
2981 | this result is equal to the number of elements in the stack | ||
2982 | (and so 0 means an empty stack). | ||
2983 | |||
2984 | |||
2985 | |||
2986 | |||
2987 | |||
2988 | <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> | ||
2989 | <span class="apii">[-1, +1, <em>-</em>]</span> | ||
2990 | <pre>void lua_insert (lua_State *L, int index);</pre> | ||
2991 | |||
2992 | <p> | ||
2993 | Moves the top element into the given valid index, | ||
2994 | shifting up the elements above this index to open space. | ||
2995 | Cannot be called with a pseudo-index, | ||
2996 | because a pseudo-index is not an actual stack position. | ||
2997 | |||
2998 | |||
2999 | |||
3000 | |||
3001 | |||
3002 | <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> | ||
3003 | <pre>typedef ptrdiff_t lua_Integer;</pre> | ||
3004 | |||
3005 | <p> | ||
3006 | The type used by the Lua API to represent integral values. | ||
3007 | |||
3008 | |||
3009 | <p> | ||
3010 | By default it is a <code>ptrdiff_t</code>, | ||
3011 | which is usually the largest signed integral type the machine handles | ||
3012 | "comfortably". | ||
3013 | |||
3014 | |||
3015 | |||
3016 | |||
3017 | |||
3018 | <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> | ||
3019 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3020 | <pre>int lua_isboolean (lua_State *L, int index);</pre> | ||
3021 | |||
3022 | <p> | ||
3023 | Returns 1 if the value at the given acceptable index has type boolean, | ||
3024 | and 0 otherwise. | ||
3025 | |||
3026 | |||
3027 | |||
3028 | |||
3029 | |||
3030 | <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> | ||
3031 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3032 | <pre>int lua_iscfunction (lua_State *L, int index);</pre> | ||
3033 | |||
3034 | <p> | ||
3035 | Returns 1 if the value at the given acceptable index is a C function, | ||
3036 | and 0 otherwise. | ||
3037 | |||
3038 | |||
3039 | |||
3040 | |||
3041 | |||
3042 | <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> | ||
3043 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3044 | <pre>int lua_isfunction (lua_State *L, int index);</pre> | ||
3045 | |||
3046 | <p> | ||
3047 | Returns 1 if the value at the given acceptable index is a function | ||
3048 | (either C or Lua), and 0 otherwise. | ||
3049 | |||
3050 | |||
3051 | |||
3052 | |||
3053 | |||
3054 | <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> | ||
3055 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3056 | <pre>int lua_islightuserdata (lua_State *L, int index);</pre> | ||
3057 | |||
3058 | <p> | ||
3059 | Returns 1 if the value at the given acceptable index is a light userdata, | ||
3060 | and 0 otherwise. | ||
3061 | |||
3062 | |||
3063 | |||
3064 | |||
3065 | |||
3066 | <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> | ||
3067 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3068 | <pre>int lua_isnil (lua_State *L, int index);</pre> | ||
3069 | |||
3070 | <p> | ||
3071 | Returns 1 if the value at the given acceptable index is <b>nil</b>, | ||
3072 | and 0 otherwise. | ||
3073 | |||
3074 | |||
3075 | |||
3076 | |||
3077 | |||
3078 | <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> | ||
3079 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3080 | <pre>int lua_isnone (lua_State *L, int index);</pre> | ||
3081 | |||
3082 | <p> | ||
3083 | Returns 1 if the given acceptable index is not valid | ||
3084 | (that is, it refers to an element outside the current stack), | ||
3085 | and 0 otherwise. | ||
3086 | |||
3087 | |||
3088 | |||
3089 | |||
3090 | |||
3091 | <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> | ||
3092 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3093 | <pre>int lua_isnoneornil (lua_State *L, int index);</pre> | ||
3094 | |||
3095 | <p> | ||
3096 | Returns 1 if the given acceptable index is not valid | ||
3097 | (that is, it refers to an element outside the current stack) | ||
3098 | or if the value at this index is <b>nil</b>, | ||
3099 | and 0 otherwise. | ||
3100 | |||
3101 | |||
3102 | |||
3103 | |||
3104 | |||
3105 | <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> | ||
3106 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3107 | <pre>int lua_isnumber (lua_State *L, int index);</pre> | ||
3108 | |||
3109 | <p> | ||
3110 | Returns 1 if the value at the given acceptable index is a number | ||
3111 | or a string convertible to a number, | ||
3112 | and 0 otherwise. | ||
3113 | |||
3114 | |||
3115 | |||
3116 | |||
3117 | |||
3118 | <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> | ||
3119 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3120 | <pre>int lua_isstring (lua_State *L, int index);</pre> | ||
3121 | |||
3122 | <p> | ||
3123 | Returns 1 if the value at the given acceptable index is a string | ||
3124 | or a number (which is always convertible to a string), | ||
3125 | and 0 otherwise. | ||
3126 | |||
3127 | |||
3128 | |||
3129 | |||
3130 | |||
3131 | <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> | ||
3132 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3133 | <pre>int lua_istable (lua_State *L, int index);</pre> | ||
3134 | |||
3135 | <p> | ||
3136 | Returns 1 if the value at the given acceptable index is a table, | ||
3137 | and 0 otherwise. | ||
3138 | |||
3139 | |||
3140 | |||
3141 | |||
3142 | |||
3143 | <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> | ||
3144 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3145 | <pre>int lua_isthread (lua_State *L, int index);</pre> | ||
3146 | |||
3147 | <p> | ||
3148 | Returns 1 if the value at the given acceptable index is a thread, | ||
3149 | and 0 otherwise. | ||
3150 | |||
3151 | |||
3152 | |||
3153 | |||
3154 | |||
3155 | <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> | ||
3156 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3157 | <pre>int lua_isuserdata (lua_State *L, int index);</pre> | ||
3158 | |||
3159 | <p> | ||
3160 | Returns 1 if the value at the given acceptable index is a userdata | ||
3161 | (either full or light), and 0 otherwise. | ||
3162 | |||
3163 | |||
3164 | |||
3165 | |||
3166 | |||
3167 | <hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p> | ||
3168 | <span class="apii">[-0, +0, <em>e</em>]</span> | ||
3169 | <pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre> | ||
3170 | |||
3171 | <p> | ||
3172 | Returns 1 if the value at acceptable index <code>index1</code> is smaller | ||
3173 | than the value at acceptable index <code>index2</code>, | ||
3174 | following the semantics of the Lua <code><</code> operator | ||
3175 | (that is, may call metamethods). | ||
3176 | Otherwise returns 0. | ||
3177 | Also returns 0 if any of the indices is non valid. | ||
3178 | |||
3179 | |||
3180 | |||
3181 | |||
3182 | |||
3183 | <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> | ||
3184 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3185 | <pre>int lua_load (lua_State *L, | ||
3186 | lua_Reader reader, | ||
3187 | void *data, | ||
3188 | const char *chunkname);</pre> | ||
3189 | |||
3190 | <p> | ||
3191 | Loads a Lua chunk. | ||
3192 | If there are no errors, | ||
3193 | <a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua | ||
3194 | function on top of the stack. | ||
3195 | Otherwise, it pushes an error message. | ||
3196 | The return values of <a href="#lua_load"><code>lua_load</code></a> are: | ||
3197 | |||
3198 | <ul> | ||
3199 | |||
3200 | <li><b>0:</b> no errors;</li> | ||
3201 | |||
3202 | <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b> | ||
3203 | syntax error during pre-compilation;</li> | ||
3204 | |||
3205 | <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> | ||
3206 | memory allocation error.</li> | ||
3207 | |||
3208 | </ul> | ||
3209 | |||
3210 | <p> | ||
3211 | This function only loads a chunk; | ||
3212 | it does not run it. | ||
3213 | |||
3214 | |||
3215 | <p> | ||
3216 | <a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary, | ||
3217 | and loads it accordingly (see program <code>luac</code>). | ||
3218 | |||
3219 | |||
3220 | <p> | ||
3221 | The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function | ||
3222 | to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). | ||
3223 | The <code>data</code> argument is an opaque value passed to the reader function. | ||
3224 | |||
3225 | |||
3226 | <p> | ||
3227 | The <code>chunkname</code> argument gives a name to the chunk, | ||
3228 | which is used for error messages and in debug information (see <a href="#3.8">§3.8</a>). | ||
3229 | |||
3230 | |||
3231 | |||
3232 | |||
3233 | |||
3234 | <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> | ||
3235 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3236 | <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> | ||
3237 | |||
3238 | <p> | ||
3239 | Creates a new, independent state. | ||
3240 | Returns <code>NULL</code> if cannot create the state | ||
3241 | (due to lack of memory). | ||
3242 | The argument <code>f</code> is the allocator function; | ||
3243 | Lua does all memory allocation for this state through this function. | ||
3244 | The second argument, <code>ud</code>, is an opaque pointer that Lua | ||
3245 | simply passes to the allocator in every call. | ||
3246 | |||
3247 | |||
3248 | |||
3249 | |||
3250 | |||
3251 | <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> | ||
3252 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3253 | <pre>void lua_newtable (lua_State *L);</pre> | ||
3254 | |||
3255 | <p> | ||
3256 | Creates a new empty table and pushes it onto the stack. | ||
3257 | It is equivalent to <code>lua_createtable(L, 0, 0)</code>. | ||
3258 | |||
3259 | |||
3260 | |||
3261 | |||
3262 | |||
3263 | <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> | ||
3264 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3265 | <pre>lua_State *lua_newthread (lua_State *L);</pre> | ||
3266 | |||
3267 | <p> | ||
3268 | Creates a new thread, pushes it on the stack, | ||
3269 | and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. | ||
3270 | The new state returned by this function shares with the original state | ||
3271 | all global objects (such as tables), | ||
3272 | but has an independent execution stack. | ||
3273 | |||
3274 | |||
3275 | <p> | ||
3276 | There is no explicit function to close or to destroy a thread. | ||
3277 | Threads are subject to garbage collection, | ||
3278 | like any Lua object. | ||
3279 | |||
3280 | |||
3281 | |||
3282 | |||
3283 | |||
3284 | <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> | ||
3285 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3286 | <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> | ||
3287 | |||
3288 | <p> | ||
3289 | This function allocates a new block of memory with the given size, | ||
3290 | pushes onto the stack a new full userdata with the block address, | ||
3291 | and returns this address. | ||
3292 | |||
3293 | |||
3294 | <p> | ||
3295 | Userdata represent C values in Lua. | ||
3296 | A <em>full userdata</em> represents a block of memory. | ||
3297 | It is an object (like a table): | ||
3298 | you must create it, it can have its own metatable, | ||
3299 | and you can detect when it is being collected. | ||
3300 | A full userdata is only equal to itself (under raw equality). | ||
3301 | |||
3302 | |||
3303 | <p> | ||
3304 | When Lua collects a full userdata with a <code>gc</code> metamethod, | ||
3305 | Lua calls the metamethod and marks the userdata as finalized. | ||
3306 | When this userdata is collected again then | ||
3307 | Lua frees its corresponding memory. | ||
3308 | |||
3309 | |||
3310 | |||
3311 | |||
3312 | |||
3313 | <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> | ||
3314 | <span class="apii">[-1, +(2|0), <em>e</em>]</span> | ||
3315 | <pre>int lua_next (lua_State *L, int index);</pre> | ||
3316 | |||
3317 | <p> | ||
3318 | Pops a key from the stack, | ||
3319 | and pushes a key-value pair from the table at the given index | ||
3320 | (the "next" pair after the given key). | ||
3321 | If there are no more elements in the table, | ||
3322 | then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). | ||
3323 | |||
3324 | |||
3325 | <p> | ||
3326 | A typical traversal looks like this: | ||
3327 | |||
3328 | <pre> | ||
3329 | /* table is in the stack at index 't' */ | ||
3330 | lua_pushnil(L); /* first key */ | ||
3331 | while (lua_next(L, t) != 0) { | ||
3332 | /* uses 'key' (at index -2) and 'value' (at index -1) */ | ||
3333 | printf("%s - %s\n", | ||
3334 | lua_typename(L, lua_type(L, -2)), | ||
3335 | lua_typename(L, lua_type(L, -1))); | ||
3336 | /* removes 'value'; keeps 'key' for next iteration */ | ||
3337 | lua_pop(L, 1); | ||
3338 | } | ||
3339 | </pre> | ||
3340 | |||
3341 | <p> | ||
3342 | While traversing a table, | ||
3343 | do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, | ||
3344 | unless you know that the key is actually a string. | ||
3345 | Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em> | ||
3346 | the value at the given index; | ||
3347 | this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. | ||
3348 | |||
3349 | |||
3350 | |||
3351 | |||
3352 | |||
3353 | <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> | ||
3354 | <pre>typedef double lua_Number;</pre> | ||
3355 | |||
3356 | <p> | ||
3357 | The type of numbers in Lua. | ||
3358 | By default, it is double, but that can be changed in <code>luaconf.h</code>. | ||
3359 | |||
3360 | |||
3361 | <p> | ||
3362 | Through the configuration file you can change | ||
3363 | Lua to operate with another type for numbers (e.g., float or long). | ||
3364 | |||
3365 | |||
3366 | |||
3367 | |||
3368 | |||
3369 | <hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p> | ||
3370 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3371 | <pre>size_t lua_objlen (lua_State *L, int index);</pre> | ||
3372 | |||
3373 | <p> | ||
3374 | Returns the "length" of the value at the given acceptable index: | ||
3375 | for strings, this is the string length; | ||
3376 | for tables, this is the result of the length operator ('<code>#</code>'); | ||
3377 | for userdata, this is the size of the block of memory allocated | ||
3378 | for the userdata; | ||
3379 | for other values, it is 0. | ||
3380 | |||
3381 | |||
3382 | |||
3383 | |||
3384 | |||
3385 | <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> | ||
3386 | <span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> | ||
3387 | <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre> | ||
3388 | |||
3389 | <p> | ||
3390 | Calls a function in protected mode. | ||
3391 | |||
3392 | |||
3393 | <p> | ||
3394 | Both <code>nargs</code> and <code>nresults</code> have the same meaning as | ||
3395 | in <a href="#lua_call"><code>lua_call</code></a>. | ||
3396 | If there are no errors during the call, | ||
3397 | <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. | ||
3398 | However, if there is any error, | ||
3399 | <a href="#lua_pcall"><code>lua_pcall</code></a> catches it, | ||
3400 | pushes a single value on the stack (the error message), | ||
3401 | and returns an error code. | ||
3402 | Like <a href="#lua_call"><code>lua_call</code></a>, | ||
3403 | <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function | ||
3404 | and its arguments from the stack. | ||
3405 | |||
3406 | |||
3407 | <p> | ||
3408 | If <code>errfunc</code> is 0, | ||
3409 | then the error message returned on the stack | ||
3410 | is exactly the original error message. | ||
3411 | Otherwise, <code>errfunc</code> is the stack index of an | ||
3412 | <em>error handler function</em>. | ||
3413 | (In the current implementation, this index cannot be a pseudo-index.) | ||
3414 | In case of runtime errors, | ||
3415 | this function will be called with the error message | ||
3416 | and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. | ||
3417 | |||
3418 | |||
3419 | <p> | ||
3420 | Typically, the error handler function is used to add more debug | ||
3421 | information to the error message, such as a stack traceback. | ||
3422 | Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, | ||
3423 | since by then the stack has unwound. | ||
3424 | |||
3425 | |||
3426 | <p> | ||
3427 | The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success | ||
3428 | or one of the following error codes | ||
3429 | (defined in <code>lua.h</code>): | ||
3430 | |||
3431 | <ul> | ||
3432 | |||
3433 | <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b> | ||
3434 | a runtime error. | ||
3435 | </li> | ||
3436 | |||
3437 | <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> | ||
3438 | memory allocation error. | ||
3439 | For such errors, Lua does not call the error handler function. | ||
3440 | </li> | ||
3441 | |||
3442 | <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b> | ||
3443 | error while running the error handler function. | ||
3444 | </li> | ||
3445 | |||
3446 | </ul> | ||
3447 | |||
3448 | |||
3449 | |||
3450 | |||
3451 | <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> | ||
3452 | <span class="apii">[-n, +0, <em>-</em>]</span> | ||
3453 | <pre>void lua_pop (lua_State *L, int n);</pre> | ||
3454 | |||
3455 | <p> | ||
3456 | Pops <code>n</code> elements from the stack. | ||
3457 | |||
3458 | |||
3459 | |||
3460 | |||
3461 | |||
3462 | <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> | ||
3463 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3464 | <pre>void lua_pushboolean (lua_State *L, int b);</pre> | ||
3465 | |||
3466 | <p> | ||
3467 | Pushes a boolean value with value <code>b</code> onto the stack. | ||
3468 | |||
3469 | |||
3470 | |||
3471 | |||
3472 | |||
3473 | <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> | ||
3474 | <span class="apii">[-n, +1, <em>m</em>]</span> | ||
3475 | <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> | ||
3476 | |||
3477 | <p> | ||
3478 | Pushes a new C closure onto the stack. | ||
3479 | |||
3480 | |||
3481 | <p> | ||
3482 | When a C function is created, | ||
3483 | it is possible to associate some values with it, | ||
3484 | thus creating a C closure (see <a href="#3.4">§3.4</a>); | ||
3485 | these values are then accessible to the function whenever it is called. | ||
3486 | To associate values with a C function, | ||
3487 | first these values should be pushed onto the stack | ||
3488 | (when there are multiple values, the first value is pushed first). | ||
3489 | Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> | ||
3490 | is called to create and push the C function onto the stack, | ||
3491 | with the argument <code>n</code> telling how many values should be | ||
3492 | associated with the function. | ||
3493 | <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. | ||
3494 | |||
3495 | |||
3496 | <p> | ||
3497 | The maximum value for <code>n</code> is 255. | ||
3498 | |||
3499 | |||
3500 | |||
3501 | |||
3502 | |||
3503 | <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> | ||
3504 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3505 | <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> | ||
3506 | |||
3507 | <p> | ||
3508 | Pushes a C function onto the stack. | ||
3509 | This function receives a pointer to a C function | ||
3510 | and pushes onto the stack a Lua value of type <code>function</code> that, | ||
3511 | when called, invokes the corresponding C function. | ||
3512 | |||
3513 | |||
3514 | <p> | ||
3515 | Any function to be registered in Lua must | ||
3516 | follow the correct protocol to receive its parameters | ||
3517 | and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). | ||
3518 | |||
3519 | |||
3520 | <p> | ||
3521 | <code>lua_pushcfunction</code> is defined as a macro: | ||
3522 | |||
3523 | <pre> | ||
3524 | #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) | ||
3525 | </pre> | ||
3526 | |||
3527 | |||
3528 | |||
3529 | |||
3530 | <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> | ||
3531 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3532 | <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> | ||
3533 | |||
3534 | <p> | ||
3535 | Pushes onto the stack a formatted string | ||
3536 | and returns a pointer to this string. | ||
3537 | It is similar to the C function <code>sprintf</code>, | ||
3538 | but has some important differences: | ||
3539 | |||
3540 | <ul> | ||
3541 | |||
3542 | <li> | ||
3543 | You do not have to allocate space for the result: | ||
3544 | the result is a Lua string and Lua takes care of memory allocation | ||
3545 | (and deallocation, through garbage collection). | ||
3546 | </li> | ||
3547 | |||
3548 | <li> | ||
3549 | The conversion specifiers are quite restricted. | ||
3550 | There are no flags, widths, or precisions. | ||
3551 | The conversion specifiers can only be | ||
3552 | '<code>%%</code>' (inserts a '<code>%</code>' in the string), | ||
3553 | '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), | ||
3554 | '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), | ||
3555 | '<code>%p</code>' (inserts a pointer as a hexadecimal numeral), | ||
3556 | '<code>%d</code>' (inserts an <code>int</code>), and | ||
3557 | '<code>%c</code>' (inserts an <code>int</code> as a character). | ||
3558 | </li> | ||
3559 | |||
3560 | </ul> | ||
3561 | |||
3562 | |||
3563 | |||
3564 | |||
3565 | <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> | ||
3566 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3567 | <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> | ||
3568 | |||
3569 | <p> | ||
3570 | Pushes a number with value <code>n</code> onto the stack. | ||
3571 | |||
3572 | |||
3573 | |||
3574 | |||
3575 | |||
3576 | <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> | ||
3577 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3578 | <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> | ||
3579 | |||
3580 | <p> | ||
3581 | Pushes a light userdata onto the stack. | ||
3582 | |||
3583 | |||
3584 | <p> | ||
3585 | Userdata represent C values in Lua. | ||
3586 | A <em>light userdata</em> represents a pointer. | ||
3587 | It is a value (like a number): | ||
3588 | you do not create it, it has no individual metatable, | ||
3589 | and it is not collected (as it was never created). | ||
3590 | A light userdata is equal to "any" | ||
3591 | light userdata with the same C address. | ||
3592 | |||
3593 | |||
3594 | |||
3595 | |||
3596 | |||
3597 | <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> | ||
3598 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3599 | <pre>void lua_pushliteral (lua_State *L, const char *s);</pre> | ||
3600 | |||
3601 | <p> | ||
3602 | This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, | ||
3603 | but can be used only when <code>s</code> is a literal string. | ||
3604 | In these cases, it automatically provides the string length. | ||
3605 | |||
3606 | |||
3607 | |||
3608 | |||
3609 | |||
3610 | <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> | ||
3611 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3612 | <pre>void lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> | ||
3613 | |||
3614 | <p> | ||
3615 | Pushes the string pointed to by <code>s</code> with size <code>len</code> | ||
3616 | onto the stack. | ||
3617 | Lua makes (or reuses) an internal copy of the given string, | ||
3618 | so the memory at <code>s</code> can be freed or reused immediately after | ||
3619 | the function returns. | ||
3620 | The string can contain embedded zeros. | ||
3621 | |||
3622 | |||
3623 | |||
3624 | |||
3625 | |||
3626 | <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> | ||
3627 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3628 | <pre>void lua_pushnil (lua_State *L);</pre> | ||
3629 | |||
3630 | <p> | ||
3631 | Pushes a nil value onto the stack. | ||
3632 | |||
3633 | |||
3634 | |||
3635 | |||
3636 | |||
3637 | <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> | ||
3638 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3639 | <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> | ||
3640 | |||
3641 | <p> | ||
3642 | Pushes a number with value <code>n</code> onto the stack. | ||
3643 | |||
3644 | |||
3645 | |||
3646 | |||
3647 | |||
3648 | <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> | ||
3649 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3650 | <pre>void lua_pushstring (lua_State *L, const char *s);</pre> | ||
3651 | |||
3652 | <p> | ||
3653 | Pushes the zero-terminated string pointed to by <code>s</code> | ||
3654 | onto the stack. | ||
3655 | Lua makes (or reuses) an internal copy of the given string, | ||
3656 | so the memory at <code>s</code> can be freed or reused immediately after | ||
3657 | the function returns. | ||
3658 | The string cannot contain embedded zeros; | ||
3659 | it is assumed to end at the first zero. | ||
3660 | |||
3661 | |||
3662 | |||
3663 | |||
3664 | |||
3665 | <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> | ||
3666 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3667 | <pre>int lua_pushthread (lua_State *L);</pre> | ||
3668 | |||
3669 | <p> | ||
3670 | Pushes the thread represented by <code>L</code> onto the stack. | ||
3671 | Returns 1 if this thread is the main thread of its state. | ||
3672 | |||
3673 | |||
3674 | |||
3675 | |||
3676 | |||
3677 | <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> | ||
3678 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3679 | <pre>void lua_pushvalue (lua_State *L, int index);</pre> | ||
3680 | |||
3681 | <p> | ||
3682 | Pushes a copy of the element at the given valid index | ||
3683 | onto the stack. | ||
3684 | |||
3685 | |||
3686 | |||
3687 | |||
3688 | |||
3689 | <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> | ||
3690 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
3691 | <pre>const char *lua_pushvfstring (lua_State *L, | ||
3692 | const char *fmt, | ||
3693 | va_list argp);</pre> | ||
3694 | |||
3695 | <p> | ||
3696 | Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> | ||
3697 | instead of a variable number of arguments. | ||
3698 | |||
3699 | |||
3700 | |||
3701 | |||
3702 | |||
3703 | <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> | ||
3704 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3705 | <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> | ||
3706 | |||
3707 | <p> | ||
3708 | Returns 1 if the two values in acceptable indices <code>index1</code> and | ||
3709 | <code>index2</code> are primitively equal | ||
3710 | (that is, without calling metamethods). | ||
3711 | Otherwise returns 0. | ||
3712 | Also returns 0 if any of the indices are non valid. | ||
3713 | |||
3714 | |||
3715 | |||
3716 | |||
3717 | |||
3718 | <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> | ||
3719 | <span class="apii">[-1, +1, <em>-</em>]</span> | ||
3720 | <pre>void lua_rawget (lua_State *L, int index);</pre> | ||
3721 | |||
3722 | <p> | ||
3723 | Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access | ||
3724 | (i.e., without metamethods). | ||
3725 | |||
3726 | |||
3727 | |||
3728 | |||
3729 | |||
3730 | <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> | ||
3731 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
3732 | <pre>void lua_rawgeti (lua_State *L, int index, int n);</pre> | ||
3733 | |||
3734 | <p> | ||
3735 | Pushes onto the stack the value <code>t[n]</code>, | ||
3736 | where <code>t</code> is the value at the given valid index. | ||
3737 | The access is raw; | ||
3738 | that is, it does not invoke metamethods. | ||
3739 | |||
3740 | |||
3741 | |||
3742 | |||
3743 | |||
3744 | <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> | ||
3745 | <span class="apii">[-2, +0, <em>m</em>]</span> | ||
3746 | <pre>void lua_rawset (lua_State *L, int index);</pre> | ||
3747 | |||
3748 | <p> | ||
3749 | Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment | ||
3750 | (i.e., without metamethods). | ||
3751 | |||
3752 | |||
3753 | |||
3754 | |||
3755 | |||
3756 | <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> | ||
3757 | <span class="apii">[-1, +0, <em>m</em>]</span> | ||
3758 | <pre>void lua_rawseti (lua_State *L, int index, int n);</pre> | ||
3759 | |||
3760 | <p> | ||
3761 | Does the equivalent of <code>t[n] = v</code>, | ||
3762 | where <code>t</code> is the value at the given valid index | ||
3763 | and <code>v</code> is the value at the top of the stack. | ||
3764 | |||
3765 | |||
3766 | <p> | ||
3767 | This function pops the value from the stack. | ||
3768 | The assignment is raw; | ||
3769 | that is, it does not invoke metamethods. | ||
3770 | |||
3771 | |||
3772 | |||
3773 | |||
3774 | |||
3775 | <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> | ||
3776 | <pre>typedef const char * (*lua_Reader) (lua_State *L, | ||
3777 | void *data, | ||
3778 | size_t *size);</pre> | ||
3779 | |||
3780 | <p> | ||
3781 | The reader function used by <a href="#lua_load"><code>lua_load</code></a>. | ||
3782 | Every time it needs another piece of the chunk, | ||
3783 | <a href="#lua_load"><code>lua_load</code></a> calls the reader, | ||
3784 | passing along its <code>data</code> parameter. | ||
3785 | The reader must return a pointer to a block of memory | ||
3786 | with a new piece of the chunk | ||
3787 | and set <code>size</code> to the block size. | ||
3788 | The block must exist until the reader function is called again. | ||
3789 | To signal the end of the chunk, | ||
3790 | the reader must return <code>NULL</code> or set <code>size</code> to zero. | ||
3791 | The reader function may return pieces of any size greater than zero. | ||
3792 | |||
3793 | |||
3794 | |||
3795 | |||
3796 | |||
3797 | <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> | ||
3798 | <span class="apii">[-0, +0, <em>e</em>]</span> | ||
3799 | <pre>void lua_register (lua_State *L, | ||
3800 | const char *name, | ||
3801 | lua_CFunction f);</pre> | ||
3802 | |||
3803 | <p> | ||
3804 | Sets the C function <code>f</code> as the new value of global <code>name</code>. | ||
3805 | It is defined as a macro: | ||
3806 | |||
3807 | <pre> | ||
3808 | #define lua_register(L,n,f) \ | ||
3809 | (lua_pushcfunction(L, f), lua_setglobal(L, n)) | ||
3810 | </pre> | ||
3811 | |||
3812 | |||
3813 | |||
3814 | |||
3815 | <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> | ||
3816 | <span class="apii">[-1, +0, <em>-</em>]</span> | ||
3817 | <pre>void lua_remove (lua_State *L, int index);</pre> | ||
3818 | |||
3819 | <p> | ||
3820 | Removes the element at the given valid index, | ||
3821 | shifting down the elements above this index to fill the gap. | ||
3822 | Cannot be called with a pseudo-index, | ||
3823 | because a pseudo-index is not an actual stack position. | ||
3824 | |||
3825 | |||
3826 | |||
3827 | |||
3828 | |||
3829 | <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> | ||
3830 | <span class="apii">[-1, +0, <em>-</em>]</span> | ||
3831 | <pre>void lua_replace (lua_State *L, int index);</pre> | ||
3832 | |||
3833 | <p> | ||
3834 | Moves the top element into the given position (and pops it), | ||
3835 | without shifting any element | ||
3836 | (therefore replacing the value at the given position). | ||
3837 | |||
3838 | |||
3839 | |||
3840 | |||
3841 | |||
3842 | <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> | ||
3843 | <span class="apii">[-?, +?, <em>-</em>]</span> | ||
3844 | <pre>int lua_resume (lua_State *L, int narg);</pre> | ||
3845 | |||
3846 | <p> | ||
3847 | Starts and resumes a coroutine in a given thread. | ||
3848 | |||
3849 | |||
3850 | <p> | ||
3851 | To start a coroutine, you first create a new thread | ||
3852 | (see <a href="#lua_newthread"><code>lua_newthread</code></a>); | ||
3853 | then you push onto its stack the main function plus any arguments; | ||
3854 | then you call <a href="#lua_resume"><code>lua_resume</code></a>, | ||
3855 | with <code>narg</code> being the number of arguments. | ||
3856 | This call returns when the coroutine suspends or finishes its execution. | ||
3857 | When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, | ||
3858 | or all values returned by the body function. | ||
3859 | <a href="#lua_resume"><code>lua_resume</code></a> returns | ||
3860 | <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, | ||
3861 | 0 if the coroutine finishes its execution | ||
3862 | without errors, | ||
3863 | or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). | ||
3864 | In case of errors, | ||
3865 | the stack is not unwound, | ||
3866 | so you can use the debug API over it. | ||
3867 | The error message is on the top of the stack. | ||
3868 | To restart a coroutine, you put on its stack only the values to | ||
3869 | be passed as results from <code>yield</code>, | ||
3870 | and then call <a href="#lua_resume"><code>lua_resume</code></a>. | ||
3871 | |||
3872 | |||
3873 | |||
3874 | |||
3875 | |||
3876 | <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> | ||
3877 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
3878 | <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> | ||
3879 | |||
3880 | <p> | ||
3881 | Changes the allocator function of a given state to <code>f</code> | ||
3882 | with user data <code>ud</code>. | ||
3883 | |||
3884 | |||
3885 | |||
3886 | |||
3887 | |||
3888 | <hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p> | ||
3889 | <span class="apii">[-1, +0, <em>-</em>]</span> | ||
3890 | <pre>int lua_setfenv (lua_State *L, int index);</pre> | ||
3891 | |||
3892 | <p> | ||
3893 | Pops a table from the stack and sets it as | ||
3894 | the new environment for the value at the given index. | ||
3895 | If the value at the given index is | ||
3896 | neither a function nor a thread nor a userdata, | ||
3897 | <a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. | ||
3898 | Otherwise it returns 1. | ||
3899 | |||
3900 | |||
3901 | |||
3902 | |||
3903 | |||
3904 | <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> | ||
3905 | <span class="apii">[-1, +0, <em>e</em>]</span> | ||
3906 | <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> | ||
3907 | |||
3908 | <p> | ||
3909 | Does the equivalent to <code>t[k] = v</code>, | ||
3910 | where <code>t</code> is the value at the given valid index | ||
3911 | and <code>v</code> is the value at the top of the stack. | ||
3912 | |||
3913 | |||
3914 | <p> | ||
3915 | This function pops the value from the stack. | ||
3916 | As in Lua, this function may trigger a metamethod | ||
3917 | for the "newindex" event (see <a href="#2.8">§2.8</a>). | ||
3918 | |||
3919 | |||
3920 | |||
3921 | |||
3922 | |||
3923 | <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> | ||
3924 | <span class="apii">[-1, +0, <em>e</em>]</span> | ||
3925 | <pre>void lua_setglobal (lua_State *L, const char *name);</pre> | ||
3926 | |||
3927 | <p> | ||
3928 | Pops a value from the stack and | ||
3929 | sets it as the new value of global <code>name</code>. | ||
3930 | It is defined as a macro: | ||
3931 | |||
3932 | <pre> | ||
3933 | #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) | ||
3934 | </pre> | ||
3935 | |||
3936 | |||
3937 | |||
3938 | |||
3939 | <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> | ||
3940 | <span class="apii">[-1, +0, <em>-</em>]</span> | ||
3941 | <pre>int lua_setmetatable (lua_State *L, int index);</pre> | ||
3942 | |||
3943 | <p> | ||
3944 | Pops a table from the stack and | ||
3945 | sets it as the new metatable for the value at the given | ||
3946 | acceptable index. | ||
3947 | |||
3948 | |||
3949 | |||
3950 | |||
3951 | |||
3952 | <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> | ||
3953 | <span class="apii">[-2, +0, <em>e</em>]</span> | ||
3954 | <pre>void lua_settable (lua_State *L, int index);</pre> | ||
3955 | |||
3956 | <p> | ||
3957 | Does the equivalent to <code>t[k] = v</code>, | ||
3958 | where <code>t</code> is the value at the given valid index, | ||
3959 | <code>v</code> is the value at the top of the stack, | ||
3960 | and <code>k</code> is the value just below the top. | ||
3961 | |||
3962 | |||
3963 | <p> | ||
3964 | This function pops both the key and the value from the stack. | ||
3965 | As in Lua, this function may trigger a metamethod | ||
3966 | for the "newindex" event (see <a href="#2.8">§2.8</a>). | ||
3967 | |||
3968 | |||
3969 | |||
3970 | |||
3971 | |||
3972 | <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> | ||
3973 | <span class="apii">[-?, +?, <em>-</em>]</span> | ||
3974 | <pre>void lua_settop (lua_State *L, int index);</pre> | ||
3975 | |||
3976 | <p> | ||
3977 | Accepts any acceptable index, or 0, | ||
3978 | and sets the stack top to this index. | ||
3979 | If the new top is larger than the old one, | ||
3980 | then the new elements are filled with <b>nil</b>. | ||
3981 | If <code>index</code> is 0, then all stack elements are removed. | ||
3982 | |||
3983 | |||
3984 | |||
3985 | |||
3986 | |||
3987 | <hr><h3><a name="lua_State"><code>lua_State</code></a></h3> | ||
3988 | <pre>typedef struct lua_State lua_State;</pre> | ||
3989 | |||
3990 | <p> | ||
3991 | Opaque structure that keeps the whole state of a Lua interpreter. | ||
3992 | The Lua library is fully reentrant: | ||
3993 | it has no global variables. | ||
3994 | All information about a state is kept in this structure. | ||
3995 | |||
3996 | |||
3997 | <p> | ||
3998 | A pointer to this state must be passed as the first argument to | ||
3999 | every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, | ||
4000 | which creates a Lua state from scratch. | ||
4001 | |||
4002 | |||
4003 | |||
4004 | |||
4005 | |||
4006 | <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> | ||
4007 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4008 | <pre>int lua_status (lua_State *L);</pre> | ||
4009 | |||
4010 | <p> | ||
4011 | Returns the status of the thread <code>L</code>. | ||
4012 | |||
4013 | |||
4014 | <p> | ||
4015 | The status can be 0 for a normal thread, | ||
4016 | an error code if the thread finished its execution with an error, | ||
4017 | or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. | ||
4018 | |||
4019 | |||
4020 | |||
4021 | |||
4022 | |||
4023 | <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> | ||
4024 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4025 | <pre>int lua_toboolean (lua_State *L, int index);</pre> | ||
4026 | |||
4027 | <p> | ||
4028 | Converts the Lua value at the given acceptable index to a C boolean | ||
4029 | value (0 or 1). | ||
4030 | Like all tests in Lua, | ||
4031 | <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value | ||
4032 | different from <b>false</b> and <b>nil</b>; | ||
4033 | otherwise it returns 0. | ||
4034 | It also returns 0 when called with a non-valid index. | ||
4035 | (If you want to accept only actual boolean values, | ||
4036 | use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) | ||
4037 | |||
4038 | |||
4039 | |||
4040 | |||
4041 | |||
4042 | <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> | ||
4043 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4044 | <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> | ||
4045 | |||
4046 | <p> | ||
4047 | Converts a value at the given acceptable index to a C function. | ||
4048 | That value must be a C function; | ||
4049 | otherwise, returns <code>NULL</code>. | ||
4050 | |||
4051 | |||
4052 | |||
4053 | |||
4054 | |||
4055 | <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> | ||
4056 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4057 | <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> | ||
4058 | |||
4059 | <p> | ||
4060 | Converts the Lua value at the given acceptable index | ||
4061 | to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. | ||
4062 | The Lua value must be a number or a string convertible to a number | ||
4063 | (see <a href="#2.2.1">§2.2.1</a>); | ||
4064 | otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. | ||
4065 | |||
4066 | |||
4067 | <p> | ||
4068 | If the number is not an integer, | ||
4069 | it is truncated in some non-specified way. | ||
4070 | |||
4071 | |||
4072 | |||
4073 | |||
4074 | |||
4075 | <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> | ||
4076 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4077 | <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> | ||
4078 | |||
4079 | <p> | ||
4080 | Converts the Lua value at the given acceptable index to a C string. | ||
4081 | If <code>len</code> is not <code>NULL</code>, | ||
4082 | it also sets <code>*len</code> with the string length. | ||
4083 | The Lua value must be a string or a number; | ||
4084 | otherwise, the function returns <code>NULL</code>. | ||
4085 | If the value is a number, | ||
4086 | then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also | ||
4087 | <em>changes the actual value in the stack to a string</em>. | ||
4088 | (This change confuses <a href="#lua_next"><code>lua_next</code></a> | ||
4089 | when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) | ||
4090 | |||
4091 | |||
4092 | <p> | ||
4093 | <a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer | ||
4094 | to a string inside the Lua state. | ||
4095 | This string always has a zero ('<code>\0</code>') | ||
4096 | after its last character (as in C), | ||
4097 | but can contain other zeros in its body. | ||
4098 | Because Lua has garbage collection, | ||
4099 | there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a> | ||
4100 | will be valid after the corresponding value is removed from the stack. | ||
4101 | |||
4102 | |||
4103 | |||
4104 | |||
4105 | |||
4106 | <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> | ||
4107 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4108 | <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> | ||
4109 | |||
4110 | <p> | ||
4111 | Converts the Lua value at the given acceptable index | ||
4112 | to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). | ||
4113 | The Lua value must be a number or a string convertible to a number | ||
4114 | (see <a href="#2.2.1">§2.2.1</a>); | ||
4115 | otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. | ||
4116 | |||
4117 | |||
4118 | |||
4119 | |||
4120 | |||
4121 | <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> | ||
4122 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4123 | <pre>const void *lua_topointer (lua_State *L, int index);</pre> | ||
4124 | |||
4125 | <p> | ||
4126 | Converts the value at the given acceptable index to a generic | ||
4127 | C pointer (<code>void*</code>). | ||
4128 | The value can be a userdata, a table, a thread, or a function; | ||
4129 | otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. | ||
4130 | Different objects will give different pointers. | ||
4131 | There is no way to convert the pointer back to its original value. | ||
4132 | |||
4133 | |||
4134 | <p> | ||
4135 | Typically this function is used only for debug information. | ||
4136 | |||
4137 | |||
4138 | |||
4139 | |||
4140 | |||
4141 | <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> | ||
4142 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4143 | <pre>const char *lua_tostring (lua_State *L, int index);</pre> | ||
4144 | |||
4145 | <p> | ||
4146 | Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. | ||
4147 | |||
4148 | |||
4149 | |||
4150 | |||
4151 | |||
4152 | <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> | ||
4153 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4154 | <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> | ||
4155 | |||
4156 | <p> | ||
4157 | Converts the value at the given acceptable index to a Lua thread | ||
4158 | (represented as <code>lua_State*</code>). | ||
4159 | This value must be a thread; | ||
4160 | otherwise, the function returns <code>NULL</code>. | ||
4161 | |||
4162 | |||
4163 | |||
4164 | |||
4165 | |||
4166 | <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> | ||
4167 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4168 | <pre>void *lua_touserdata (lua_State *L, int index);</pre> | ||
4169 | |||
4170 | <p> | ||
4171 | If the value at the given acceptable index is a full userdata, | ||
4172 | returns its block address. | ||
4173 | If the value is a light userdata, | ||
4174 | returns its pointer. | ||
4175 | Otherwise, returns <code>NULL</code>. | ||
4176 | |||
4177 | |||
4178 | |||
4179 | |||
4180 | |||
4181 | <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> | ||
4182 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4183 | <pre>int lua_type (lua_State *L, int index);</pre> | ||
4184 | |||
4185 | <p> | ||
4186 | Returns the type of the value in the given acceptable index, | ||
4187 | or <code>LUA_TNONE</code> for a non-valid index | ||
4188 | (that is, an index to an "empty" stack position). | ||
4189 | The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants | ||
4190 | defined in <code>lua.h</code>: | ||
4191 | <code>LUA_TNIL</code>, | ||
4192 | <code>LUA_TNUMBER</code>, | ||
4193 | <code>LUA_TBOOLEAN</code>, | ||
4194 | <code>LUA_TSTRING</code>, | ||
4195 | <code>LUA_TTABLE</code>, | ||
4196 | <code>LUA_TFUNCTION</code>, | ||
4197 | <code>LUA_TUSERDATA</code>, | ||
4198 | <code>LUA_TTHREAD</code>, | ||
4199 | and | ||
4200 | <code>LUA_TLIGHTUSERDATA</code>. | ||
4201 | |||
4202 | |||
4203 | |||
4204 | |||
4205 | |||
4206 | <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> | ||
4207 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4208 | <pre>const char *lua_typename (lua_State *L, int tp);</pre> | ||
4209 | |||
4210 | <p> | ||
4211 | Returns the name of the type encoded by the value <code>tp</code>, | ||
4212 | which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. | ||
4213 | |||
4214 | |||
4215 | |||
4216 | |||
4217 | |||
4218 | <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> | ||
4219 | <pre>typedef int (*lua_Writer) (lua_State *L, | ||
4220 | const void* p, | ||
4221 | size_t sz, | ||
4222 | void* ud);</pre> | ||
4223 | |||
4224 | <p> | ||
4225 | The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. | ||
4226 | Every time it produces another piece of chunk, | ||
4227 | <a href="#lua_dump"><code>lua_dump</code></a> calls the writer, | ||
4228 | passing along the buffer to be written (<code>p</code>), | ||
4229 | its size (<code>sz</code>), | ||
4230 | and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. | ||
4231 | |||
4232 | |||
4233 | <p> | ||
4234 | The writer returns an error code: | ||
4235 | 0 means no errors; | ||
4236 | any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from | ||
4237 | calling the writer again. | ||
4238 | |||
4239 | |||
4240 | |||
4241 | |||
4242 | |||
4243 | <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> | ||
4244 | <span class="apii">[-?, +?, <em>-</em>]</span> | ||
4245 | <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> | ||
4246 | |||
4247 | <p> | ||
4248 | Exchange values between different threads of the <em>same</em> global state. | ||
4249 | |||
4250 | |||
4251 | <p> | ||
4252 | This function pops <code>n</code> values from the stack <code>from</code>, | ||
4253 | and pushes them onto the stack <code>to</code>. | ||
4254 | |||
4255 | |||
4256 | |||
4257 | |||
4258 | |||
4259 | <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> | ||
4260 | <span class="apii">[-?, +?, <em>-</em>]</span> | ||
4261 | <pre>int lua_yield (lua_State *L, int nresults);</pre> | ||
4262 | |||
4263 | <p> | ||
4264 | Yields a coroutine. | ||
4265 | |||
4266 | |||
4267 | <p> | ||
4268 | This function should only be called as the | ||
4269 | return expression of a C function, as follows: | ||
4270 | |||
4271 | <pre> | ||
4272 | return lua_yield (L, nresults); | ||
4273 | </pre><p> | ||
4274 | When a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way, | ||
4275 | the running coroutine suspends its execution, | ||
4276 | and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. | ||
4277 | The parameter <code>nresults</code> is the number of values from the stack | ||
4278 | that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. | ||
4279 | |||
4280 | |||
4281 | |||
4282 | |||
4283 | |||
4284 | |||
4285 | |||
4286 | <h2>3.8 - <a name="3.8">The Debug Interface</a></h2> | ||
4287 | |||
4288 | <p> | ||
4289 | Lua has no built-in debugging facilities. | ||
4290 | Instead, it offers a special interface | ||
4291 | by means of functions and <em>hooks</em>. | ||
4292 | This interface allows the construction of different | ||
4293 | kinds of debuggers, profilers, and other tools | ||
4294 | that need "inside information" from the interpreter. | ||
4295 | |||
4296 | |||
4297 | |||
4298 | <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> | ||
4299 | <pre>typedef struct lua_Debug { | ||
4300 | int event; | ||
4301 | const char *name; /* (n) */ | ||
4302 | const char *namewhat; /* (n) */ | ||
4303 | const char *what; /* (S) */ | ||
4304 | const char *source; /* (S) */ | ||
4305 | int currentline; /* (l) */ | ||
4306 | int nups; /* (u) number of upvalues */ | ||
4307 | int linedefined; /* (S) */ | ||
4308 | int lastlinedefined; /* (S) */ | ||
4309 | char short_src[LUA_IDSIZE]; /* (S) */ | ||
4310 | /* private part */ | ||
4311 | <em>other fields</em> | ||
4312 | } lua_Debug;</pre> | ||
4313 | |||
4314 | <p> | ||
4315 | A structure used to carry different pieces of | ||
4316 | information about an active function. | ||
4317 | <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part | ||
4318 | of this structure, for later use. | ||
4319 | To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, | ||
4320 | call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. | ||
4321 | |||
4322 | |||
4323 | <p> | ||
4324 | The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: | ||
4325 | |||
4326 | <ul> | ||
4327 | |||
4328 | <li><b><code>source</code>:</b> | ||
4329 | If the function was defined in a string, | ||
4330 | then <code>source</code> is that string. | ||
4331 | If the function was defined in a file, | ||
4332 | then <code>source</code> starts with a '<code>@</code>' followed by the file name. | ||
4333 | </li> | ||
4334 | |||
4335 | <li><b><code>short_src</code>:</b> | ||
4336 | a "printable" version of <code>source</code>, to be used in error messages. | ||
4337 | </li> | ||
4338 | |||
4339 | <li><b><code>linedefined</code>:</b> | ||
4340 | the line number where the definition of the function starts. | ||
4341 | </li> | ||
4342 | |||
4343 | <li><b><code>lastlinedefined</code>:</b> | ||
4344 | the line number where the definition of the function ends. | ||
4345 | </li> | ||
4346 | |||
4347 | <li><b><code>what</code>:</b> | ||
4348 | the string <code>"Lua"</code> if the function is a Lua function, | ||
4349 | <code>"C"</code> if it is a C function, | ||
4350 | <code>"main"</code> if it is the main part of a chunk, | ||
4351 | and <code>"tail"</code> if it was a function that did a tail call. | ||
4352 | In the latter case, | ||
4353 | Lua has no other information about the function. | ||
4354 | </li> | ||
4355 | |||
4356 | <li><b><code>currentline</code>:</b> | ||
4357 | the current line where the given function is executing. | ||
4358 | When no line information is available, | ||
4359 | <code>currentline</code> is set to -1. | ||
4360 | </li> | ||
4361 | |||
4362 | <li><b><code>name</code>:</b> | ||
4363 | a reasonable name for the given function. | ||
4364 | Because functions in Lua are first-class values, | ||
4365 | they do not have a fixed name: | ||
4366 | some functions can be the value of multiple global variables, | ||
4367 | while others can be stored only in a table field. | ||
4368 | The <code>lua_getinfo</code> function checks how the function was | ||
4369 | called to find a suitable name. | ||
4370 | If it cannot find a name, | ||
4371 | then <code>name</code> is set to <code>NULL</code>. | ||
4372 | </li> | ||
4373 | |||
4374 | <li><b><code>namewhat</code>:</b> | ||
4375 | explains the <code>name</code> field. | ||
4376 | The value of <code>namewhat</code> can be | ||
4377 | <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, | ||
4378 | <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), | ||
4379 | according to how the function was called. | ||
4380 | (Lua uses the empty string when no other option seems to apply.) | ||
4381 | </li> | ||
4382 | |||
4383 | <li><b><code>nups</code>:</b> | ||
4384 | the number of upvalues of the function. | ||
4385 | </li> | ||
4386 | |||
4387 | </ul> | ||
4388 | |||
4389 | |||
4390 | |||
4391 | |||
4392 | <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> | ||
4393 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4394 | <pre>lua_Hook lua_gethook (lua_State *L);</pre> | ||
4395 | |||
4396 | <p> | ||
4397 | Returns the current hook function. | ||
4398 | |||
4399 | |||
4400 | |||
4401 | |||
4402 | |||
4403 | <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> | ||
4404 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4405 | <pre>int lua_gethookcount (lua_State *L);</pre> | ||
4406 | |||
4407 | <p> | ||
4408 | Returns the current hook count. | ||
4409 | |||
4410 | |||
4411 | |||
4412 | |||
4413 | |||
4414 | <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> | ||
4415 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4416 | <pre>int lua_gethookmask (lua_State *L);</pre> | ||
4417 | |||
4418 | <p> | ||
4419 | Returns the current hook mask. | ||
4420 | |||
4421 | |||
4422 | |||
4423 | |||
4424 | |||
4425 | <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> | ||
4426 | <span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> | ||
4427 | <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> | ||
4428 | |||
4429 | <p> | ||
4430 | Returns information about a specific function or function invocation. | ||
4431 | |||
4432 | |||
4433 | <p> | ||
4434 | To get information about a function invocation, | ||
4435 | the parameter <code>ar</code> must be a valid activation record that was | ||
4436 | filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or | ||
4437 | given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). | ||
4438 | |||
4439 | |||
4440 | <p> | ||
4441 | To get information about a function you push it onto the stack | ||
4442 | and start the <code>what</code> string with the character '<code>></code>'. | ||
4443 | (In that case, | ||
4444 | <code>lua_getinfo</code> pops the function in the top of the stack.) | ||
4445 | For instance, to know in which line a function <code>f</code> was defined, | ||
4446 | you can write the following code: | ||
4447 | |||
4448 | <pre> | ||
4449 | lua_Debug ar; | ||
4450 | lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ | ||
4451 | lua_getinfo(L, ">S", &ar); | ||
4452 | printf("%d\n", ar.linedefined); | ||
4453 | </pre> | ||
4454 | |||
4455 | <p> | ||
4456 | Each character in the string <code>what</code> | ||
4457 | selects some fields of the structure <code>ar</code> to be filled or | ||
4458 | a value to be pushed on the stack: | ||
4459 | |||
4460 | <ul> | ||
4461 | |||
4462 | <li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>; | ||
4463 | </li> | ||
4464 | |||
4465 | <li><b>'<code>S</code>':</b> | ||
4466 | fills in the fields <code>source</code>, <code>short_src</code>, | ||
4467 | <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; | ||
4468 | </li> | ||
4469 | |||
4470 | <li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>; | ||
4471 | </li> | ||
4472 | |||
4473 | <li><b>'<code>u</code>':</b> fills in the field <code>nups</code>; | ||
4474 | </li> | ||
4475 | |||
4476 | <li><b>'<code>f</code>':</b> | ||
4477 | pushes onto the stack the function that is | ||
4478 | running at the given level; | ||
4479 | </li> | ||
4480 | |||
4481 | <li><b>'<code>L</code>':</b> | ||
4482 | pushes onto the stack a table whose indices are the | ||
4483 | numbers of the lines that are valid on the function. | ||
4484 | (A <em>valid line</em> is a line with some associated code, | ||
4485 | that is, a line where you can put a break point. | ||
4486 | Non-valid lines include empty lines and comments.) | ||
4487 | </li> | ||
4488 | |||
4489 | </ul> | ||
4490 | |||
4491 | <p> | ||
4492 | This function returns 0 on error | ||
4493 | (for instance, an invalid option in <code>what</code>). | ||
4494 | |||
4495 | |||
4496 | |||
4497 | |||
4498 | |||
4499 | <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> | ||
4500 | <span class="apii">[-0, +(0|1), <em>-</em>]</span> | ||
4501 | <pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> | ||
4502 | |||
4503 | <p> | ||
4504 | Gets information about a local variable of a given activation record. | ||
4505 | The parameter <code>ar</code> must be a valid activation record that was | ||
4506 | filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or | ||
4507 | given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). | ||
4508 | The index <code>n</code> selects which local variable to inspect | ||
4509 | (1 is the first parameter or active local variable, and so on, | ||
4510 | until the last active local variable). | ||
4511 | <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack | ||
4512 | and returns its name. | ||
4513 | |||
4514 | |||
4515 | <p> | ||
4516 | Variable names starting with '<code>(</code>' (open parentheses) | ||
4517 | represent internal variables | ||
4518 | (loop control variables, temporaries, and C function locals). | ||
4519 | |||
4520 | |||
4521 | <p> | ||
4522 | Returns <code>NULL</code> (and pushes nothing) | ||
4523 | when the index is greater than | ||
4524 | the number of active local variables. | ||
4525 | |||
4526 | |||
4527 | |||
4528 | |||
4529 | |||
4530 | <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> | ||
4531 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4532 | <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> | ||
4533 | |||
4534 | <p> | ||
4535 | Get information about the interpreter runtime stack. | ||
4536 | |||
4537 | |||
4538 | <p> | ||
4539 | This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with | ||
4540 | an identification of the <em>activation record</em> | ||
4541 | of the function executing at a given level. | ||
4542 | Level 0 is the current running function, | ||
4543 | whereas level <em>n+1</em> is the function that has called level <em>n</em>. | ||
4544 | When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; | ||
4545 | when called with a level greater than the stack depth, | ||
4546 | it returns 0. | ||
4547 | |||
4548 | |||
4549 | |||
4550 | |||
4551 | |||
4552 | <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> | ||
4553 | <span class="apii">[-0, +(0|1), <em>-</em>]</span> | ||
4554 | <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> | ||
4555 | |||
4556 | <p> | ||
4557 | Gets information about a closure's upvalue. | ||
4558 | (For Lua functions, | ||
4559 | upvalues are the external local variables that the function uses, | ||
4560 | and that are consequently included in its closure.) | ||
4561 | <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, | ||
4562 | pushes the upvalue's value onto the stack, | ||
4563 | and returns its name. | ||
4564 | <code>funcindex</code> points to the closure in the stack. | ||
4565 | (Upvalues have no particular order, | ||
4566 | as they are active through the whole function. | ||
4567 | So, they are numbered in an arbitrary order.) | ||
4568 | |||
4569 | |||
4570 | <p> | ||
4571 | Returns <code>NULL</code> (and pushes nothing) | ||
4572 | when the index is greater than the number of upvalues. | ||
4573 | For C functions, this function uses the empty string <code>""</code> | ||
4574 | as a name for all upvalues. | ||
4575 | |||
4576 | |||
4577 | |||
4578 | |||
4579 | |||
4580 | <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> | ||
4581 | <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> | ||
4582 | |||
4583 | <p> | ||
4584 | Type for debugging hook functions. | ||
4585 | |||
4586 | |||
4587 | <p> | ||
4588 | Whenever a hook is called, its <code>ar</code> argument has its field | ||
4589 | <code>event</code> set to the specific event that triggered the hook. | ||
4590 | Lua identifies these events with the following constants: | ||
4591 | <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, | ||
4592 | <a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, | ||
4593 | and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. | ||
4594 | Moreover, for line events, the field <code>currentline</code> is also set. | ||
4595 | To get the value of any other field in <code>ar</code>, | ||
4596 | the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. | ||
4597 | For return events, <code>event</code> can be <code>LUA_HOOKRET</code>, | ||
4598 | the normal value, or <code>LUA_HOOKTAILRET</code>. | ||
4599 | In the latter case, Lua is simulating a return from | ||
4600 | a function that did a tail call; | ||
4601 | in this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. | ||
4602 | |||
4603 | |||
4604 | <p> | ||
4605 | While Lua is running a hook, it disables other calls to hooks. | ||
4606 | Therefore, if a hook calls back Lua to execute a function or a chunk, | ||
4607 | this execution occurs without any calls to hooks. | ||
4608 | |||
4609 | |||
4610 | |||
4611 | |||
4612 | |||
4613 | <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> | ||
4614 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4615 | <pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> | ||
4616 | |||
4617 | <p> | ||
4618 | Sets the debugging hook function. | ||
4619 | |||
4620 | |||
4621 | <p> | ||
4622 | Argument <code>f</code> is the hook function. | ||
4623 | <code>mask</code> specifies on which events the hook will be called: | ||
4624 | it is formed by a bitwise or of the constants | ||
4625 | <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, | ||
4626 | <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, | ||
4627 | <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, | ||
4628 | and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. | ||
4629 | The <code>count</code> argument is only meaningful when the mask | ||
4630 | includes <code>LUA_MASKCOUNT</code>. | ||
4631 | For each event, the hook is called as explained below: | ||
4632 | |||
4633 | <ul> | ||
4634 | |||
4635 | <li><b>The call hook:</b> is called when the interpreter calls a function. | ||
4636 | The hook is called just after Lua enters the new function, | ||
4637 | before the function gets its arguments. | ||
4638 | </li> | ||
4639 | |||
4640 | <li><b>The return hook:</b> is called when the interpreter returns from a function. | ||
4641 | The hook is called just before Lua leaves the function. | ||
4642 | You have no access to the values to be returned by the function. | ||
4643 | </li> | ||
4644 | |||
4645 | <li><b>The line hook:</b> is called when the interpreter is about to | ||
4646 | start the execution of a new line of code, | ||
4647 | or when it jumps back in the code (even to the same line). | ||
4648 | (This event only happens while Lua is executing a Lua function.) | ||
4649 | </li> | ||
4650 | |||
4651 | <li><b>The count hook:</b> is called after the interpreter executes every | ||
4652 | <code>count</code> instructions. | ||
4653 | (This event only happens while Lua is executing a Lua function.) | ||
4654 | </li> | ||
4655 | |||
4656 | </ul> | ||
4657 | |||
4658 | <p> | ||
4659 | A hook is disabled by setting <code>mask</code> to zero. | ||
4660 | |||
4661 | |||
4662 | |||
4663 | |||
4664 | |||
4665 | <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> | ||
4666 | <span class="apii">[-(0|1), +0, <em>-</em>]</span> | ||
4667 | <pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> | ||
4668 | |||
4669 | <p> | ||
4670 | Sets the value of a local variable of a given activation record. | ||
4671 | Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> | ||
4672 | (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). | ||
4673 | <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack | ||
4674 | to the variable and returns its name. | ||
4675 | It also pops the value from the stack. | ||
4676 | |||
4677 | |||
4678 | <p> | ||
4679 | Returns <code>NULL</code> (and pops nothing) | ||
4680 | when the index is greater than | ||
4681 | the number of active local variables. | ||
4682 | |||
4683 | |||
4684 | |||
4685 | |||
4686 | |||
4687 | <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> | ||
4688 | <span class="apii">[-(0|1), +0, <em>-</em>]</span> | ||
4689 | <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> | ||
4690 | |||
4691 | <p> | ||
4692 | Sets the value of a closure's upvalue. | ||
4693 | It assigns the value at the top of the stack | ||
4694 | to the upvalue and returns its name. | ||
4695 | It also pops the value from the stack. | ||
4696 | Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> | ||
4697 | (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). | ||
4698 | |||
4699 | |||
4700 | <p> | ||
4701 | Returns <code>NULL</code> (and pops nothing) | ||
4702 | when the index is greater than the number of upvalues. | ||
4703 | |||
4704 | |||
4705 | |||
4706 | |||
4707 | |||
4708 | |||
4709 | |||
4710 | <h1>4 - <a name="4">The Auxiliary Library</a></h1> | ||
4711 | |||
4712 | <p> | ||
4713 | |||
4714 | The <em>auxiliary library</em> provides several convenient functions | ||
4715 | to interface C with Lua. | ||
4716 | While the basic API provides the primitive functions for all | ||
4717 | interactions between C and Lua, | ||
4718 | the auxiliary library provides higher-level functions for some | ||
4719 | common tasks. | ||
4720 | |||
4721 | |||
4722 | <p> | ||
4723 | All functions from the auxiliary library | ||
4724 | are defined in header file <code>lauxlib.h</code> and | ||
4725 | have a prefix <code>luaL_</code>. | ||
4726 | |||
4727 | |||
4728 | <p> | ||
4729 | All functions in the auxiliary library are built on | ||
4730 | top of the basic API, | ||
4731 | and so they provide nothing that cannot be done with this API. | ||
4732 | |||
4733 | |||
4734 | <p> | ||
4735 | Several functions in the auxiliary library are used to | ||
4736 | check C function arguments. | ||
4737 | Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. | ||
4738 | All of these functions throw an error if the check is not satisfied. | ||
4739 | Because the error message is formatted for arguments | ||
4740 | (e.g., "<code>bad argument #1</code>"), | ||
4741 | you should not use these functions for other stack values. | ||
4742 | |||
4743 | |||
4744 | |||
4745 | <h2>4.1 - <a name="4.1">Functions and Types</a></h2> | ||
4746 | |||
4747 | <p> | ||
4748 | Here we list all functions and types from the auxiliary library | ||
4749 | in alphabetical order. | ||
4750 | |||
4751 | |||
4752 | |||
4753 | <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> | ||
4754 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4755 | <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> | ||
4756 | |||
4757 | <p> | ||
4758 | Adds the character <code>c</code> to the buffer <code>B</code> | ||
4759 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
4760 | |||
4761 | |||
4762 | |||
4763 | |||
4764 | |||
4765 | <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> | ||
4766 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4767 | <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> | ||
4768 | |||
4769 | <p> | ||
4770 | Adds the string pointed to by <code>s</code> with length <code>l</code> to | ||
4771 | the buffer <code>B</code> | ||
4772 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
4773 | The string may contain embedded zeros. | ||
4774 | |||
4775 | |||
4776 | |||
4777 | |||
4778 | |||
4779 | <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> | ||
4780 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4781 | <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> | ||
4782 | |||
4783 | <p> | ||
4784 | Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) | ||
4785 | a string of length <code>n</code> previously copied to the | ||
4786 | buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). | ||
4787 | |||
4788 | |||
4789 | |||
4790 | |||
4791 | |||
4792 | <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> | ||
4793 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
4794 | <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> | ||
4795 | |||
4796 | <p> | ||
4797 | Adds the zero-terminated string pointed to by <code>s</code> | ||
4798 | to the buffer <code>B</code> | ||
4799 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
4800 | The string may not contain embedded zeros. | ||
4801 | |||
4802 | |||
4803 | |||
4804 | |||
4805 | |||
4806 | <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> | ||
4807 | <span class="apii">[-1, +0, <em>m</em>]</span> | ||
4808 | <pre>void luaL_addvalue (luaL_Buffer *B);</pre> | ||
4809 | |||
4810 | <p> | ||
4811 | Adds the value at the top of the stack | ||
4812 | to the buffer <code>B</code> | ||
4813 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
4814 | Pops the value. | ||
4815 | |||
4816 | |||
4817 | <p> | ||
4818 | This is the only function on string buffers that can (and must) | ||
4819 | be called with an extra element on the stack, | ||
4820 | which is the value to be added to the buffer. | ||
4821 | |||
4822 | |||
4823 | |||
4824 | |||
4825 | |||
4826 | <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> | ||
4827 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4828 | <pre>void luaL_argcheck (lua_State *L, | ||
4829 | int cond, | ||
4830 | int narg, | ||
4831 | const char *extramsg);</pre> | ||
4832 | |||
4833 | <p> | ||
4834 | Checks whether <code>cond</code> is true. | ||
4835 | If not, raises an error with the following message, | ||
4836 | where <code>func</code> is retrieved from the call stack: | ||
4837 | |||
4838 | <pre> | ||
4839 | bad argument #<narg> to <func> (<extramsg>) | ||
4840 | </pre> | ||
4841 | |||
4842 | |||
4843 | |||
4844 | |||
4845 | <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> | ||
4846 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4847 | <pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> | ||
4848 | |||
4849 | <p> | ||
4850 | Raises an error with the following message, | ||
4851 | where <code>func</code> is retrieved from the call stack: | ||
4852 | |||
4853 | <pre> | ||
4854 | bad argument #<narg> to <func> (<extramsg>) | ||
4855 | </pre> | ||
4856 | |||
4857 | <p> | ||
4858 | This function never returns, | ||
4859 | but it is an idiom to use it in C functions | ||
4860 | as <code>return luaL_argerror(<em>args</em>)</code>. | ||
4861 | |||
4862 | |||
4863 | |||
4864 | |||
4865 | |||
4866 | <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> | ||
4867 | <pre>typedef struct luaL_Buffer luaL_Buffer;</pre> | ||
4868 | |||
4869 | <p> | ||
4870 | Type for a <em>string buffer</em>. | ||
4871 | |||
4872 | |||
4873 | <p> | ||
4874 | A string buffer allows C code to build Lua strings piecemeal. | ||
4875 | Its pattern of use is as follows: | ||
4876 | |||
4877 | <ul> | ||
4878 | |||
4879 | <li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> | ||
4880 | |||
4881 | <li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> | ||
4882 | |||
4883 | <li> | ||
4884 | Then you add string pieces to the buffer calling any of | ||
4885 | the <code>luaL_add*</code> functions. | ||
4886 | </li> | ||
4887 | |||
4888 | <li> | ||
4889 | You finish by calling <code>luaL_pushresult(&b)</code>. | ||
4890 | This call leaves the final string on the top of the stack. | ||
4891 | </li> | ||
4892 | |||
4893 | </ul> | ||
4894 | |||
4895 | <p> | ||
4896 | During its normal operation, | ||
4897 | a string buffer uses a variable number of stack slots. | ||
4898 | So, while using a buffer, you cannot assume that you know where | ||
4899 | the top of the stack is. | ||
4900 | You can use the stack between successive calls to buffer operations | ||
4901 | as long as that use is balanced; | ||
4902 | that is, | ||
4903 | when you call a buffer operation, | ||
4904 | the stack is at the same level | ||
4905 | it was immediately after the previous buffer operation. | ||
4906 | (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) | ||
4907 | After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its | ||
4908 | level when the buffer was initialized, | ||
4909 | plus the final string on its top. | ||
4910 | |||
4911 | |||
4912 | |||
4913 | |||
4914 | |||
4915 | <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> | ||
4916 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
4917 | <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> | ||
4918 | |||
4919 | <p> | ||
4920 | Initializes a buffer <code>B</code>. | ||
4921 | This function does not allocate any space; | ||
4922 | the buffer must be declared as a variable | ||
4923 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
4924 | |||
4925 | |||
4926 | |||
4927 | |||
4928 | |||
4929 | <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> | ||
4930 | <span class="apii">[-0, +(0|1), <em>e</em>]</span> | ||
4931 | <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> | ||
4932 | |||
4933 | <p> | ||
4934 | Calls a metamethod. | ||
4935 | |||
4936 | |||
4937 | <p> | ||
4938 | If the object at index <code>obj</code> has a metatable and this | ||
4939 | metatable has a field <code>e</code>, | ||
4940 | this function calls this field and passes the object as its only argument. | ||
4941 | In this case this function returns 1 and pushes onto the | ||
4942 | stack the value returned by the call. | ||
4943 | If there is no metatable or no metamethod, | ||
4944 | this function returns 0 (without pushing any value on the stack). | ||
4945 | |||
4946 | |||
4947 | |||
4948 | |||
4949 | |||
4950 | <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> | ||
4951 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4952 | <pre>void luaL_checkany (lua_State *L, int narg);</pre> | ||
4953 | |||
4954 | <p> | ||
4955 | Checks whether the function has an argument | ||
4956 | of any type (including <b>nil</b>) at position <code>narg</code>. | ||
4957 | |||
4958 | |||
4959 | |||
4960 | |||
4961 | |||
4962 | <hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> | ||
4963 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4964 | <pre>int luaL_checkint (lua_State *L, int narg);</pre> | ||
4965 | |||
4966 | <p> | ||
4967 | Checks whether the function argument <code>narg</code> is a number | ||
4968 | and returns this number cast to an <code>int</code>. | ||
4969 | |||
4970 | |||
4971 | |||
4972 | |||
4973 | |||
4974 | <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> | ||
4975 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4976 | <pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre> | ||
4977 | |||
4978 | <p> | ||
4979 | Checks whether the function argument <code>narg</code> is a number | ||
4980 | and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. | ||
4981 | |||
4982 | |||
4983 | |||
4984 | |||
4985 | |||
4986 | <hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> | ||
4987 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
4988 | <pre>long luaL_checklong (lua_State *L, int narg);</pre> | ||
4989 | |||
4990 | <p> | ||
4991 | Checks whether the function argument <code>narg</code> is a number | ||
4992 | and returns this number cast to a <code>long</code>. | ||
4993 | |||
4994 | |||
4995 | |||
4996 | |||
4997 | |||
4998 | <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> | ||
4999 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5000 | <pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre> | ||
5001 | |||
5002 | <p> | ||
5003 | Checks whether the function argument <code>narg</code> is a string | ||
5004 | and returns this string; | ||
5005 | if <code>l</code> is not <code>NULL</code> fills <code>*l</code> | ||
5006 | with the string's length. | ||
5007 | |||
5008 | |||
5009 | <p> | ||
5010 | This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, | ||
5011 | so all conversions and caveats of that function apply here. | ||
5012 | |||
5013 | |||
5014 | |||
5015 | |||
5016 | |||
5017 | <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> | ||
5018 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5019 | <pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre> | ||
5020 | |||
5021 | <p> | ||
5022 | Checks whether the function argument <code>narg</code> is a number | ||
5023 | and returns this number. | ||
5024 | |||
5025 | |||
5026 | |||
5027 | |||
5028 | |||
5029 | <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> | ||
5030 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5031 | <pre>int luaL_checkoption (lua_State *L, | ||
5032 | int narg, | ||
5033 | const char *def, | ||
5034 | const char *const lst[]);</pre> | ||
5035 | |||
5036 | <p> | ||
5037 | Checks whether the function argument <code>narg</code> is a string and | ||
5038 | searches for this string in the array <code>lst</code> | ||
5039 | (which must be NULL-terminated). | ||
5040 | Returns the index in the array where the string was found. | ||
5041 | Raises an error if the argument is not a string or | ||
5042 | if the string cannot be found. | ||
5043 | |||
5044 | |||
5045 | <p> | ||
5046 | If <code>def</code> is not <code>NULL</code>, | ||
5047 | the function uses <code>def</code> as a default value when | ||
5048 | there is no argument <code>narg</code> or if this argument is <b>nil</b>. | ||
5049 | |||
5050 | |||
5051 | <p> | ||
5052 | This is a useful function for mapping strings to C enums. | ||
5053 | (The usual convention in Lua libraries is | ||
5054 | to use strings instead of numbers to select options.) | ||
5055 | |||
5056 | |||
5057 | |||
5058 | |||
5059 | |||
5060 | <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> | ||
5061 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5062 | <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> | ||
5063 | |||
5064 | <p> | ||
5065 | Grows the stack size to <code>top + sz</code> elements, | ||
5066 | raising an error if the stack cannot grow to that size. | ||
5067 | <code>msg</code> is an additional text to go into the error message. | ||
5068 | |||
5069 | |||
5070 | |||
5071 | |||
5072 | |||
5073 | <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> | ||
5074 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5075 | <pre>const char *luaL_checkstring (lua_State *L, int narg);</pre> | ||
5076 | |||
5077 | <p> | ||
5078 | Checks whether the function argument <code>narg</code> is a string | ||
5079 | and returns this string. | ||
5080 | |||
5081 | |||
5082 | <p> | ||
5083 | This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, | ||
5084 | so all conversions and caveats of that function apply here. | ||
5085 | |||
5086 | |||
5087 | |||
5088 | |||
5089 | |||
5090 | <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> | ||
5091 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5092 | <pre>void luaL_checktype (lua_State *L, int narg, int t);</pre> | ||
5093 | |||
5094 | <p> | ||
5095 | Checks whether the function argument <code>narg</code> has type <code>t</code>. | ||
5096 | See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. | ||
5097 | |||
5098 | |||
5099 | |||
5100 | |||
5101 | |||
5102 | <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> | ||
5103 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5104 | <pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre> | ||
5105 | |||
5106 | <p> | ||
5107 | Checks whether the function argument <code>narg</code> is a userdata | ||
5108 | of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). | ||
5109 | |||
5110 | |||
5111 | |||
5112 | |||
5113 | |||
5114 | <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> | ||
5115 | <span class="apii">[-0, +?, <em>m</em>]</span> | ||
5116 | <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> | ||
5117 | |||
5118 | <p> | ||
5119 | Loads and runs the given file. | ||
5120 | It is defined as the following macro: | ||
5121 | |||
5122 | <pre> | ||
5123 | (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) | ||
5124 | </pre><p> | ||
5125 | It returns 0 if there are no errors | ||
5126 | or 1 in case of errors. | ||
5127 | |||
5128 | |||
5129 | |||
5130 | |||
5131 | |||
5132 | <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> | ||
5133 | <span class="apii">[-0, +?, <em>m</em>]</span> | ||
5134 | <pre>int luaL_dostring (lua_State *L, const char *str);</pre> | ||
5135 | |||
5136 | <p> | ||
5137 | Loads and runs the given string. | ||
5138 | It is defined as the following macro: | ||
5139 | |||
5140 | <pre> | ||
5141 | (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) | ||
5142 | </pre><p> | ||
5143 | It returns 0 if there are no errors | ||
5144 | or 1 in case of errors. | ||
5145 | |||
5146 | |||
5147 | |||
5148 | |||
5149 | |||
5150 | <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> | ||
5151 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5152 | <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> | ||
5153 | |||
5154 | <p> | ||
5155 | Raises an error. | ||
5156 | The error message format is given by <code>fmt</code> | ||
5157 | plus any extra arguments, | ||
5158 | following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. | ||
5159 | It also adds at the beginning of the message the file name and | ||
5160 | the line number where the error occurred, | ||
5161 | if this information is available. | ||
5162 | |||
5163 | |||
5164 | <p> | ||
5165 | This function never returns, | ||
5166 | but it is an idiom to use it in C functions | ||
5167 | as <code>return luaL_error(<em>args</em>)</code>. | ||
5168 | |||
5169 | |||
5170 | |||
5171 | |||
5172 | |||
5173 | <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> | ||
5174 | <span class="apii">[-0, +(0|1), <em>m</em>]</span> | ||
5175 | <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> | ||
5176 | |||
5177 | <p> | ||
5178 | Pushes onto the stack the field <code>e</code> from the metatable | ||
5179 | of the object at index <code>obj</code>. | ||
5180 | If the object does not have a metatable, | ||
5181 | or if the metatable does not have this field, | ||
5182 | returns 0 and pushes nothing. | ||
5183 | |||
5184 | |||
5185 | |||
5186 | |||
5187 | |||
5188 | <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> | ||
5189 | <span class="apii">[-0, +1, <em>-</em>]</span> | ||
5190 | <pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> | ||
5191 | |||
5192 | <p> | ||
5193 | Pushes onto the stack the metatable associated with name <code>tname</code> | ||
5194 | in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). | ||
5195 | |||
5196 | |||
5197 | |||
5198 | |||
5199 | |||
5200 | <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> | ||
5201 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5202 | <pre>const char *luaL_gsub (lua_State *L, | ||
5203 | const char *s, | ||
5204 | const char *p, | ||
5205 | const char *r);</pre> | ||
5206 | |||
5207 | <p> | ||
5208 | Creates a copy of string <code>s</code> by replacing | ||
5209 | any occurrence of the string <code>p</code> | ||
5210 | with the string <code>r</code>. | ||
5211 | Pushes the resulting string on the stack and returns it. | ||
5212 | |||
5213 | |||
5214 | |||
5215 | |||
5216 | |||
5217 | <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> | ||
5218 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5219 | <pre>int luaL_loadbuffer (lua_State *L, | ||
5220 | const char *buff, | ||
5221 | size_t sz, | ||
5222 | const char *name);</pre> | ||
5223 | |||
5224 | <p> | ||
5225 | Loads a buffer as a Lua chunk. | ||
5226 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the | ||
5227 | buffer pointed to by <code>buff</code> with size <code>sz</code>. | ||
5228 | |||
5229 | |||
5230 | <p> | ||
5231 | This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. | ||
5232 | <code>name</code> is the chunk name, | ||
5233 | used for debug information and error messages. | ||
5234 | |||
5235 | |||
5236 | |||
5237 | |||
5238 | |||
5239 | <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> | ||
5240 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5241 | <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> | ||
5242 | |||
5243 | <p> | ||
5244 | Loads a file as a Lua chunk. | ||
5245 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file | ||
5246 | named <code>filename</code>. | ||
5247 | If <code>filename</code> is <code>NULL</code>, | ||
5248 | then it loads from the standard input. | ||
5249 | The first line in the file is ignored if it starts with a <code>#</code>. | ||
5250 | |||
5251 | |||
5252 | <p> | ||
5253 | This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, | ||
5254 | but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> | ||
5255 | if it cannot open/read the file. | ||
5256 | |||
5257 | |||
5258 | <p> | ||
5259 | As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; | ||
5260 | it does not run it. | ||
5261 | |||
5262 | |||
5263 | |||
5264 | |||
5265 | |||
5266 | <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> | ||
5267 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5268 | <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> | ||
5269 | |||
5270 | <p> | ||
5271 | Loads a string as a Lua chunk. | ||
5272 | This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in | ||
5273 | the zero-terminated string <code>s</code>. | ||
5274 | |||
5275 | |||
5276 | <p> | ||
5277 | This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. | ||
5278 | |||
5279 | |||
5280 | <p> | ||
5281 | Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; | ||
5282 | it does not run it. | ||
5283 | |||
5284 | |||
5285 | |||
5286 | |||
5287 | |||
5288 | <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> | ||
5289 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5290 | <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> | ||
5291 | |||
5292 | <p> | ||
5293 | If the registry already has the key <code>tname</code>, | ||
5294 | returns 0. | ||
5295 | Otherwise, | ||
5296 | creates a new table to be used as a metatable for userdata, | ||
5297 | adds it to the registry with key <code>tname</code>, | ||
5298 | and returns 1. | ||
5299 | |||
5300 | |||
5301 | <p> | ||
5302 | In both cases pushes onto the stack the final value associated | ||
5303 | with <code>tname</code> in the registry. | ||
5304 | |||
5305 | |||
5306 | |||
5307 | |||
5308 | |||
5309 | <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> | ||
5310 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
5311 | <pre>lua_State *luaL_newstate (void);</pre> | ||
5312 | |||
5313 | <p> | ||
5314 | Creates a new Lua state. | ||
5315 | It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an | ||
5316 | allocator based on the standard C <code>realloc</code> function | ||
5317 | and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints | ||
5318 | an error message to the standard error output in case of fatal | ||
5319 | errors. | ||
5320 | |||
5321 | |||
5322 | <p> | ||
5323 | Returns the new state, | ||
5324 | or <code>NULL</code> if there is a memory allocation error. | ||
5325 | |||
5326 | |||
5327 | |||
5328 | |||
5329 | |||
5330 | <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> | ||
5331 | <span class="apii">[-0, +0, <em>m</em>]</span> | ||
5332 | <pre>void luaL_openlibs (lua_State *L);</pre> | ||
5333 | |||
5334 | <p> | ||
5335 | Opens all standard Lua libraries into the given state. | ||
5336 | |||
5337 | |||
5338 | |||
5339 | |||
5340 | |||
5341 | <hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> | ||
5342 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5343 | <pre>int luaL_optint (lua_State *L, int narg, int d);</pre> | ||
5344 | |||
5345 | <p> | ||
5346 | If the function argument <code>narg</code> is a number, | ||
5347 | returns this number cast to an <code>int</code>. | ||
5348 | If this argument is absent or is <b>nil</b>, | ||
5349 | returns <code>d</code>. | ||
5350 | Otherwise, raises an error. | ||
5351 | |||
5352 | |||
5353 | |||
5354 | |||
5355 | |||
5356 | <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> | ||
5357 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5358 | <pre>lua_Integer luaL_optinteger (lua_State *L, | ||
5359 | int narg, | ||
5360 | lua_Integer d);</pre> | ||
5361 | |||
5362 | <p> | ||
5363 | If the function argument <code>narg</code> is a number, | ||
5364 | returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. | ||
5365 | If this argument is absent or is <b>nil</b>, | ||
5366 | returns <code>d</code>. | ||
5367 | Otherwise, raises an error. | ||
5368 | |||
5369 | |||
5370 | |||
5371 | |||
5372 | |||
5373 | <hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> | ||
5374 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5375 | <pre>long luaL_optlong (lua_State *L, int narg, long d);</pre> | ||
5376 | |||
5377 | <p> | ||
5378 | If the function argument <code>narg</code> is a number, | ||
5379 | returns this number cast to a <code>long</code>. | ||
5380 | If this argument is absent or is <b>nil</b>, | ||
5381 | returns <code>d</code>. | ||
5382 | Otherwise, raises an error. | ||
5383 | |||
5384 | |||
5385 | |||
5386 | |||
5387 | |||
5388 | <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> | ||
5389 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5390 | <pre>const char *luaL_optlstring (lua_State *L, | ||
5391 | int narg, | ||
5392 | const char *d, | ||
5393 | size_t *l);</pre> | ||
5394 | |||
5395 | <p> | ||
5396 | If the function argument <code>narg</code> is a string, | ||
5397 | returns this string. | ||
5398 | If this argument is absent or is <b>nil</b>, | ||
5399 | returns <code>d</code>. | ||
5400 | Otherwise, raises an error. | ||
5401 | |||
5402 | |||
5403 | <p> | ||
5404 | If <code>l</code> is not <code>NULL</code>, | ||
5405 | fills the position <code>*l</code> with the results's length. | ||
5406 | |||
5407 | |||
5408 | |||
5409 | |||
5410 | |||
5411 | <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> | ||
5412 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5413 | <pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre> | ||
5414 | |||
5415 | <p> | ||
5416 | If the function argument <code>narg</code> is a number, | ||
5417 | returns this number. | ||
5418 | If this argument is absent or is <b>nil</b>, | ||
5419 | returns <code>d</code>. | ||
5420 | Otherwise, raises an error. | ||
5421 | |||
5422 | |||
5423 | |||
5424 | |||
5425 | |||
5426 | <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> | ||
5427 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5428 | <pre>const char *luaL_optstring (lua_State *L, | ||
5429 | int narg, | ||
5430 | const char *d);</pre> | ||
5431 | |||
5432 | <p> | ||
5433 | If the function argument <code>narg</code> is a string, | ||
5434 | returns this string. | ||
5435 | If this argument is absent or is <b>nil</b>, | ||
5436 | returns <code>d</code>. | ||
5437 | Otherwise, raises an error. | ||
5438 | |||
5439 | |||
5440 | |||
5441 | |||
5442 | |||
5443 | <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> | ||
5444 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
5445 | <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> | ||
5446 | |||
5447 | <p> | ||
5448 | Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a> | ||
5449 | where you can copy a string to be added to buffer <code>B</code> | ||
5450 | (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). | ||
5451 | After copying the string into this space you must call | ||
5452 | <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add | ||
5453 | it to the buffer. | ||
5454 | |||
5455 | |||
5456 | |||
5457 | |||
5458 | |||
5459 | <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> | ||
5460 | <span class="apii">[-?, +1, <em>m</em>]</span> | ||
5461 | <pre>void luaL_pushresult (luaL_Buffer *B);</pre> | ||
5462 | |||
5463 | <p> | ||
5464 | Finishes the use of buffer <code>B</code> leaving the final string on | ||
5465 | the top of the stack. | ||
5466 | |||
5467 | |||
5468 | |||
5469 | |||
5470 | |||
5471 | <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> | ||
5472 | <span class="apii">[-1, +0, <em>m</em>]</span> | ||
5473 | <pre>int luaL_ref (lua_State *L, int t);</pre> | ||
5474 | |||
5475 | <p> | ||
5476 | Creates and returns a <em>reference</em>, | ||
5477 | in the table at index <code>t</code>, | ||
5478 | for the object at the top of the stack (and pops the object). | ||
5479 | |||
5480 | |||
5481 | <p> | ||
5482 | A reference is a unique integer key. | ||
5483 | As long as you do not manually add integer keys into table <code>t</code>, | ||
5484 | <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. | ||
5485 | You can retrieve an object referred by reference <code>r</code> | ||
5486 | by calling <code>lua_rawgeti(L, t, r)</code>. | ||
5487 | Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. | ||
5488 | |||
5489 | |||
5490 | <p> | ||
5491 | If the object at the top of the stack is <b>nil</b>, | ||
5492 | <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. | ||
5493 | The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different | ||
5494 | from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. | ||
5495 | |||
5496 | |||
5497 | |||
5498 | |||
5499 | |||
5500 | <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> | ||
5501 | <pre>typedef struct luaL_Reg { | ||
5502 | const char *name; | ||
5503 | lua_CFunction func; | ||
5504 | } luaL_Reg;</pre> | ||
5505 | |||
5506 | <p> | ||
5507 | Type for arrays of functions to be registered by | ||
5508 | <a href="#luaL_register"><code>luaL_register</code></a>. | ||
5509 | <code>name</code> is the function name and <code>func</code> is a pointer to | ||
5510 | the function. | ||
5511 | Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry | ||
5512 | in which both <code>name</code> and <code>func</code> are <code>NULL</code>. | ||
5513 | |||
5514 | |||
5515 | |||
5516 | |||
5517 | |||
5518 | <hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p> | ||
5519 | <span class="apii">[-(0|1), +1, <em>m</em>]</span> | ||
5520 | <pre>void luaL_register (lua_State *L, | ||
5521 | const char *libname, | ||
5522 | const luaL_Reg *l);</pre> | ||
5523 | |||
5524 | <p> | ||
5525 | Opens a library. | ||
5526 | |||
5527 | |||
5528 | <p> | ||
5529 | When called with <code>libname</code> equal to <code>NULL</code>, | ||
5530 | it simply registers all functions in the list <code>l</code> | ||
5531 | (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack. | ||
5532 | |||
5533 | |||
5534 | <p> | ||
5535 | When called with a non-null <code>libname</code>, | ||
5536 | <code>luaL_register</code> creates a new table <code>t</code>, | ||
5537 | sets it as the value of the global variable <code>libname</code>, | ||
5538 | sets it as the value of <code>package.loaded[libname]</code>, | ||
5539 | and registers on it all functions in the list <code>l</code>. | ||
5540 | If there is a table in <code>package.loaded[libname]</code> or in | ||
5541 | variable <code>libname</code>, | ||
5542 | reuses this table instead of creating a new one. | ||
5543 | |||
5544 | |||
5545 | <p> | ||
5546 | In any case the function leaves the table | ||
5547 | on the top of the stack. | ||
5548 | |||
5549 | |||
5550 | |||
5551 | |||
5552 | |||
5553 | <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> | ||
5554 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
5555 | <pre>const char *luaL_typename (lua_State *L, int index);</pre> | ||
5556 | |||
5557 | <p> | ||
5558 | Returns the name of the type of the value at the given index. | ||
5559 | |||
5560 | |||
5561 | |||
5562 | |||
5563 | |||
5564 | <hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p> | ||
5565 | <span class="apii">[-0, +0, <em>v</em>]</span> | ||
5566 | <pre>int luaL_typerror (lua_State *L, int narg, const char *tname);</pre> | ||
5567 | |||
5568 | <p> | ||
5569 | Generates an error with a message like the following: | ||
5570 | |||
5571 | <pre> | ||
5572 | <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>) | ||
5573 | </pre><p> | ||
5574 | where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>, | ||
5575 | <code><em>func</em></code> is the name of the current function, | ||
5576 | and <code><em>rt</em></code> is the type name of the actual argument. | ||
5577 | |||
5578 | |||
5579 | |||
5580 | |||
5581 | |||
5582 | <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> | ||
5583 | <span class="apii">[-0, +0, <em>-</em>]</span> | ||
5584 | <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> | ||
5585 | |||
5586 | <p> | ||
5587 | Releases reference <code>ref</code> from the table at index <code>t</code> | ||
5588 | (see <a href="#luaL_ref"><code>luaL_ref</code></a>). | ||
5589 | The entry is removed from the table, | ||
5590 | so that the referred object can be collected. | ||
5591 | The reference <code>ref</code> is also freed to be used again. | ||
5592 | |||
5593 | |||
5594 | <p> | ||
5595 | If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>, | ||
5596 | <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. | ||
5597 | |||
5598 | |||
5599 | |||
5600 | |||
5601 | |||
5602 | <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> | ||
5603 | <span class="apii">[-0, +1, <em>m</em>]</span> | ||
5604 | <pre>void luaL_where (lua_State *L, int lvl);</pre> | ||
5605 | |||
5606 | <p> | ||
5607 | Pushes onto the stack a string identifying the current position | ||
5608 | of the control at level <code>lvl</code> in the call stack. | ||
5609 | Typically this string has the following format: | ||
5610 | |||
5611 | <pre> | ||
5612 | <em>chunkname</em>:<em>currentline</em>: | ||
5613 | </pre><p> | ||
5614 | Level 0 is the running function, | ||
5615 | level 1 is the function that called the running function, | ||
5616 | etc. | ||
5617 | |||
5618 | |||
5619 | <p> | ||
5620 | This function is used to build a prefix for error messages. | ||
5621 | |||
5622 | |||
5623 | |||
5624 | |||
5625 | |||
5626 | |||
5627 | |||
5628 | <h1>5 - <a name="5">Standard Libraries</a></h1> | ||
5629 | |||
5630 | <p> | ||
5631 | The standard Lua libraries provide useful functions | ||
5632 | that are implemented directly through the C API. | ||
5633 | Some of these functions provide essential services to the language | ||
5634 | (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); | ||
5635 | others provide access to "outside" services (e.g., I/O); | ||
5636 | and others could be implemented in Lua itself, | ||
5637 | but are quite useful or have critical performance requirements that | ||
5638 | deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). | ||
5639 | |||
5640 | |||
5641 | <p> | ||
5642 | All libraries are implemented through the official C API | ||
5643 | and are provided as separate C modules. | ||
5644 | Currently, Lua has the following standard libraries: | ||
5645 | |||
5646 | <ul> | ||
5647 | |||
5648 | <li>basic library,</li> which includes the coroutine sub-library; | ||
5649 | |||
5650 | <li>package library;</li> | ||
5651 | |||
5652 | <li>string manipulation;</li> | ||
5653 | |||
5654 | <li>table manipulation;</li> | ||
5655 | |||
5656 | <li>mathematical functions (sin, log, etc.);</li> | ||
5657 | |||
5658 | <li>input and output;</li> | ||
5659 | |||
5660 | <li>operating system facilities;</li> | ||
5661 | |||
5662 | <li>debug facilities.</li> | ||
5663 | |||
5664 | </ul><p> | ||
5665 | Except for the basic and package libraries, | ||
5666 | each library provides all its functions as fields of a global table | ||
5667 | or as methods of its objects. | ||
5668 | |||
5669 | |||
5670 | <p> | ||
5671 | To have access to these libraries, | ||
5672 | the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, | ||
5673 | which opens all standard libraries. | ||
5674 | Alternatively, | ||
5675 | it can open them individually by calling | ||
5676 | <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), | ||
5677 | <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), | ||
5678 | <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), | ||
5679 | <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), | ||
5680 | <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), | ||
5681 | <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), | ||
5682 | <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), | ||
5683 | and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). | ||
5684 | These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a> | ||
5685 | and should not be called directly: | ||
5686 | you must call them like any other Lua C function, | ||
5687 | e.g., by using <a href="#lua_call"><code>lua_call</code></a>. | ||
5688 | |||
5689 | |||
5690 | |||
5691 | <h2>5.1 - <a name="5.1">Basic Functions</a></h2> | ||
5692 | |||
5693 | <p> | ||
5694 | The basic library provides some core functions to Lua. | ||
5695 | If you do not include this library in your application, | ||
5696 | you should check carefully whether you need to provide | ||
5697 | implementations for some of its facilities. | ||
5698 | |||
5699 | |||
5700 | <p> | ||
5701 | <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> | ||
5702 | Issues an error when | ||
5703 | the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); | ||
5704 | otherwise, returns all its arguments. | ||
5705 | <code>message</code> is an error message; | ||
5706 | when absent, it defaults to "assertion failed!" | ||
5707 | |||
5708 | |||
5709 | |||
5710 | |||
5711 | <p> | ||
5712 | <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage (opt [, arg])</code></a></h3> | ||
5713 | |||
5714 | |||
5715 | <p> | ||
5716 | This function is a generic interface to the garbage collector. | ||
5717 | It performs different functions according to its first argument, <code>opt</code>: | ||
5718 | |||
5719 | <ul> | ||
5720 | |||
5721 | <li><b>"stop":</b> | ||
5722 | stops the garbage collector. | ||
5723 | </li> | ||
5724 | |||
5725 | <li><b>"restart":</b> | ||
5726 | restarts the garbage collector. | ||
5727 | </li> | ||
5728 | |||
5729 | <li><b>"collect":</b> | ||
5730 | performs a full garbage-collection cycle. | ||
5731 | </li> | ||
5732 | |||
5733 | <li><b>"count":</b> | ||
5734 | returns the total memory in use by Lua (in Kbytes). | ||
5735 | </li> | ||
5736 | |||
5737 | <li><b>"step":</b> | ||
5738 | performs a garbage-collection step. | ||
5739 | The step "size" is controlled by <code>arg</code> | ||
5740 | (larger values mean more steps) in a non-specified way. | ||
5741 | If you want to control the step size | ||
5742 | you must experimentally tune the value of <code>arg</code>. | ||
5743 | Returns <b>true</b> if the step finished a collection cycle. | ||
5744 | </li> | ||
5745 | |||
5746 | <li><b>"setpause":</b> | ||
5747 | sets <code>arg</code> as the new value for the <em>pause</em> of | ||
5748 | the collector (see <a href="#2.10">§2.10</a>). | ||
5749 | Returns the previous value for <em>pause</em>. | ||
5750 | </li> | ||
5751 | |||
5752 | <li><b>"setstepmul":</b> | ||
5753 | sets <code>arg</code> as the new value for the <em>step multiplier</em> of | ||
5754 | the collector (see <a href="#2.10">§2.10</a>). | ||
5755 | Returns the previous value for <em>step</em>. | ||
5756 | </li> | ||
5757 | |||
5758 | </ul> | ||
5759 | |||
5760 | |||
5761 | |||
5762 | <p> | ||
5763 | <hr><h3><a name="pdf-dofile"><code>dofile (filename)</code></a></h3> | ||
5764 | Opens the named file and executes its contents as a Lua chunk. | ||
5765 | When called without arguments, | ||
5766 | <code>dofile</code> executes the contents of the standard input (<code>stdin</code>). | ||
5767 | Returns all values returned by the chunk. | ||
5768 | In case of errors, <code>dofile</code> propagates the error | ||
5769 | to its caller (that is, <code>dofile</code> does not run in protected mode). | ||
5770 | |||
5771 | |||
5772 | |||
5773 | |||
5774 | <p> | ||
5775 | <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> | ||
5776 | Terminates the last protected function called | ||
5777 | and returns <code>message</code> as the error message. | ||
5778 | Function <code>error</code> never returns. | ||
5779 | |||
5780 | |||
5781 | <p> | ||
5782 | Usually, <code>error</code> adds some information about the error position | ||
5783 | at the beginning of the message. | ||
5784 | The <code>level</code> argument specifies how to get the error position. | ||
5785 | With level 1 (the default), the error position is where the | ||
5786 | <code>error</code> function was called. | ||
5787 | Level 2 points the error to where the function | ||
5788 | that called <code>error</code> was called; and so on. | ||
5789 | Passing a level 0 avoids the addition of error position information | ||
5790 | to the message. | ||
5791 | |||
5792 | |||
5793 | |||
5794 | |||
5795 | <p> | ||
5796 | <hr><h3><a name="pdf-_G"><code>_G</code></a></h3> | ||
5797 | A global variable (not a function) that | ||
5798 | holds the global environment (that is, <code>_G._G = _G</code>). | ||
5799 | Lua itself does not use this variable; | ||
5800 | changing its value does not affect any environment, | ||
5801 | nor vice-versa. | ||
5802 | (Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) | ||
5803 | |||
5804 | |||
5805 | |||
5806 | |||
5807 | <p> | ||
5808 | <hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3> | ||
5809 | Returns the current environment in use by the function. | ||
5810 | <code>f</code> can be a Lua function or a number | ||
5811 | that specifies the function at that stack level: | ||
5812 | Level 1 is the function calling <code>getfenv</code>. | ||
5813 | If the given function is not a Lua function, | ||
5814 | or if <code>f</code> is 0, | ||
5815 | <code>getfenv</code> returns the global environment. | ||
5816 | The default for <code>f</code> is 1. | ||
5817 | |||
5818 | |||
5819 | |||
5820 | |||
5821 | <p> | ||
5822 | <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> | ||
5823 | |||
5824 | |||
5825 | <p> | ||
5826 | If <code>object</code> does not have a metatable, returns <b>nil</b>. | ||
5827 | Otherwise, | ||
5828 | if the object's metatable has a <code>"__metatable"</code> field, | ||
5829 | returns the associated value. | ||
5830 | Otherwise, returns the metatable of the given object. | ||
5831 | |||
5832 | |||
5833 | |||
5834 | |||
5835 | <p> | ||
5836 | <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> | ||
5837 | |||
5838 | |||
5839 | <p> | ||
5840 | Returns three values: an iterator function, the table <code>t</code>, and 0, | ||
5841 | so that the construction | ||
5842 | |||
5843 | <pre> | ||
5844 | for i,v in ipairs(t) do <em>body</em> end | ||
5845 | </pre><p> | ||
5846 | will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···, | ||
5847 | up to the first integer key absent from the table. | ||
5848 | |||
5849 | |||
5850 | |||
5851 | |||
5852 | <p> | ||
5853 | <hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3> | ||
5854 | |||
5855 | |||
5856 | <p> | ||
5857 | Loads a chunk using function <code>func</code> to get its pieces. | ||
5858 | Each call to <code>func</code> must return a string that concatenates | ||
5859 | with previous results. | ||
5860 | A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. | ||
5861 | |||
5862 | |||
5863 | <p> | ||
5864 | If there are no errors, | ||
5865 | returns the compiled chunk as a function; | ||
5866 | otherwise, returns <b>nil</b> plus the error message. | ||
5867 | The environment of the returned function is the global environment. | ||
5868 | |||
5869 | |||
5870 | <p> | ||
5871 | <code>chunkname</code> is used as the chunk name for error messages | ||
5872 | and debug information. | ||
5873 | When absent, | ||
5874 | it defaults to "<code>=(load)</code>". | ||
5875 | |||
5876 | |||
5877 | |||
5878 | |||
5879 | <p> | ||
5880 | <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> | ||
5881 | |||
5882 | |||
5883 | <p> | ||
5884 | Similar to <a href="#pdf-load"><code>load</code></a>, | ||
5885 | but gets the chunk from file <code>filename</code> | ||
5886 | or from the standard input, | ||
5887 | if no file name is given. | ||
5888 | |||
5889 | |||
5890 | |||
5891 | |||
5892 | <p> | ||
5893 | <hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3> | ||
5894 | |||
5895 | |||
5896 | <p> | ||
5897 | Similar to <a href="#pdf-load"><code>load</code></a>, | ||
5898 | but gets the chunk from the given string. | ||
5899 | |||
5900 | |||
5901 | <p> | ||
5902 | To load and run a given string, use the idiom | ||
5903 | |||
5904 | <pre> | ||
5905 | assert(loadstring(s))() | ||
5906 | </pre> | ||
5907 | |||
5908 | <p> | ||
5909 | When absent, | ||
5910 | <code>chunkname</code> defaults to the given string. | ||
5911 | |||
5912 | |||
5913 | |||
5914 | |||
5915 | <p> | ||
5916 | <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> | ||
5917 | |||
5918 | |||
5919 | <p> | ||
5920 | Allows a program to traverse all fields of a table. | ||
5921 | Its first argument is a table and its second argument | ||
5922 | is an index in this table. | ||
5923 | <code>next</code> returns the next index of the table | ||
5924 | and its associated value. | ||
5925 | When called with <b>nil</b> as its second argument, | ||
5926 | <code>next</code> returns an initial index | ||
5927 | and its associated value. | ||
5928 | When called with the last index, | ||
5929 | or with <b>nil</b> in an empty table, | ||
5930 | <code>next</code> returns <b>nil</b>. | ||
5931 | If the second argument is absent, then it is interpreted as <b>nil</b>. | ||
5932 | In particular, | ||
5933 | you can use <code>next(t)</code> to check whether a table is empty. | ||
5934 | |||
5935 | |||
5936 | <p> | ||
5937 | The order in which the indices are enumerated is not specified, | ||
5938 | <em>even for numeric indices</em>. | ||
5939 | (To traverse a table in numeric order, | ||
5940 | use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) | ||
5941 | |||
5942 | |||
5943 | <p> | ||
5944 | The behavior of <code>next</code> is <em>undefined</em> if, | ||
5945 | during the traversal, | ||
5946 | you assign any value to a non-existent field in the table. | ||
5947 | You may however modify existing fields. | ||
5948 | In particular, you may clear existing fields. | ||
5949 | |||
5950 | |||
5951 | |||
5952 | |||
5953 | <p> | ||
5954 | <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> | ||
5955 | |||
5956 | |||
5957 | <p> | ||
5958 | Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, | ||
5959 | so that the construction | ||
5960 | |||
5961 | <pre> | ||
5962 | for k,v in pairs(t) do <em>body</em> end | ||
5963 | </pre><p> | ||
5964 | will iterate over all key–value pairs of table <code>t</code>. | ||
5965 | |||
5966 | |||
5967 | <p> | ||
5968 | See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying | ||
5969 | the table during its traversal. | ||
5970 | |||
5971 | |||
5972 | |||
5973 | |||
5974 | <p> | ||
5975 | <hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3> | ||
5976 | |||
5977 | |||
5978 | <p> | ||
5979 | Calls function <code>f</code> with | ||
5980 | the given arguments in <em>protected mode</em>. | ||
5981 | This means that any error inside <code>f</code> is not propagated; | ||
5982 | instead, <code>pcall</code> catches the error | ||
5983 | and returns a status code. | ||
5984 | Its first result is the status code (a boolean), | ||
5985 | which is true if the call succeeds without errors. | ||
5986 | In such case, <code>pcall</code> also returns all results from the call, | ||
5987 | after this first result. | ||
5988 | In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. | ||
5989 | |||
5990 | |||
5991 | |||
5992 | |||
5993 | <p> | ||
5994 | <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> | ||
5995 | Receives any number of arguments, | ||
5996 | and prints their values to <code>stdout</code>, | ||
5997 | using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. | ||
5998 | <code>print</code> is not intended for formatted output, | ||
5999 | but only as a quick way to show a value, | ||
6000 | typically for debugging. | ||
6001 | For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. | ||
6002 | |||
6003 | |||
6004 | |||
6005 | |||
6006 | <p> | ||
6007 | <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> | ||
6008 | Checks whether <code>v1</code> is equal to <code>v2</code>, | ||
6009 | without invoking any metamethod. | ||
6010 | Returns a boolean. | ||
6011 | |||
6012 | |||
6013 | |||
6014 | |||
6015 | <p> | ||
6016 | <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> | ||
6017 | Gets the real value of <code>table[index]</code>, | ||
6018 | without invoking any metamethod. | ||
6019 | <code>table</code> must be a table; | ||
6020 | <code>index</code> may be any value. | ||
6021 | |||
6022 | |||
6023 | |||
6024 | |||
6025 | <p> | ||
6026 | <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> | ||
6027 | Sets the real value of <code>table[index]</code> to <code>value</code>, | ||
6028 | without invoking any metamethod. | ||
6029 | <code>table</code> must be a table, | ||
6030 | <code>index</code> any value different from <b>nil</b>, | ||
6031 | and <code>value</code> any Lua value. | ||
6032 | |||
6033 | |||
6034 | <p> | ||
6035 | This function returns <code>table</code>. | ||
6036 | |||
6037 | |||
6038 | |||
6039 | |||
6040 | <p> | ||
6041 | <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> | ||
6042 | |||
6043 | |||
6044 | <p> | ||
6045 | If <code>index</code> is a number, | ||
6046 | returns all arguments after argument number <code>index</code>. | ||
6047 | Otherwise, <code>index</code> must be the string <code>"#"</code>, | ||
6048 | and <code>select</code> returns the total number of extra arguments it received. | ||
6049 | |||
6050 | |||
6051 | |||
6052 | |||
6053 | <p> | ||
6054 | <hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3> | ||
6055 | |||
6056 | |||
6057 | <p> | ||
6058 | Sets the environment to be used by the given function. | ||
6059 | <code>f</code> can be a Lua function or a number | ||
6060 | that specifies the function at that stack level: | ||
6061 | Level 1 is the function calling <code>setfenv</code>. | ||
6062 | <code>setfenv</code> returns the given function. | ||
6063 | |||
6064 | |||
6065 | <p> | ||
6066 | As a special case, when <code>f</code> is 0 <code>setfenv</code> changes | ||
6067 | the environment of the running thread. | ||
6068 | In this case, <code>setfenv</code> returns no values. | ||
6069 | |||
6070 | |||
6071 | |||
6072 | |||
6073 | <p> | ||
6074 | <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> | ||
6075 | |||
6076 | |||
6077 | <p> | ||
6078 | Sets the metatable for the given table. | ||
6079 | (You cannot change the metatable of other types from Lua, only from C.) | ||
6080 | If <code>metatable</code> is <b>nil</b>, | ||
6081 | removes the metatable of the given table. | ||
6082 | If the original metatable has a <code>"__metatable"</code> field, | ||
6083 | raises an error. | ||
6084 | |||
6085 | |||
6086 | <p> | ||
6087 | This function returns <code>table</code>. | ||
6088 | |||
6089 | |||
6090 | |||
6091 | |||
6092 | <p> | ||
6093 | <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> | ||
6094 | Tries to convert its argument to a number. | ||
6095 | If the argument is already a number or a string convertible | ||
6096 | to a number, then <code>tonumber</code> returns this number; | ||
6097 | otherwise, it returns <b>nil</b>. | ||
6098 | |||
6099 | |||
6100 | <p> | ||
6101 | An optional argument specifies the base to interpret the numeral. | ||
6102 | The base may be any integer between 2 and 36, inclusive. | ||
6103 | In bases above 10, the letter '<code>A</code>' (in either upper or lower case) | ||
6104 | represents 10, '<code>B</code>' represents 11, and so forth, | ||
6105 | with '<code>Z</code>' representing 35. | ||
6106 | In base 10 (the default), the number can have a decimal part, | ||
6107 | as well as an optional exponent part (see <a href="#2.1">§2.1</a>). | ||
6108 | In other bases, only unsigned integers are accepted. | ||
6109 | |||
6110 | |||
6111 | |||
6112 | |||
6113 | <p> | ||
6114 | <hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3> | ||
6115 | Receives an argument of any type and | ||
6116 | converts it to a string in a reasonable format. | ||
6117 | For complete control of how numbers are converted, | ||
6118 | use <a href="#pdf-string.format"><code>string.format</code></a>. | ||
6119 | |||
6120 | |||
6121 | <p> | ||
6122 | If the metatable of <code>e</code> has a <code>"__tostring"</code> field, | ||
6123 | then <code>tostring</code> calls the corresponding value | ||
6124 | with <code>e</code> as argument, | ||
6125 | and uses the result of the call as its result. | ||
6126 | |||
6127 | |||
6128 | |||
6129 | |||
6130 | <p> | ||
6131 | <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> | ||
6132 | Returns the type of its only argument, coded as a string. | ||
6133 | The possible results of this function are | ||
6134 | "<code>nil</code>" (a string, not the value <b>nil</b>), | ||
6135 | "<code>number</code>", | ||
6136 | "<code>string</code>", | ||
6137 | "<code>boolean</code>", | ||
6138 | "<code>table</code>", | ||
6139 | "<code>function</code>", | ||
6140 | "<code>thread</code>", | ||
6141 | and "<code>userdata</code>". | ||
6142 | |||
6143 | |||
6144 | |||
6145 | |||
6146 | <p> | ||
6147 | <hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3> | ||
6148 | Returns the elements from the given table. | ||
6149 | This function is equivalent to | ||
6150 | |||
6151 | <pre> | ||
6152 | return list[i], list[i+1], ···, list[j] | ||
6153 | </pre><p> | ||
6154 | except that the above code can be written only for a fixed number | ||
6155 | of elements. | ||
6156 | By default, <code>i</code> is 1 and <code>j</code> is the length of the list, | ||
6157 | as defined by the length operator (see <a href="#2.5.5">§2.5.5</a>). | ||
6158 | |||
6159 | |||
6160 | |||
6161 | |||
6162 | <p> | ||
6163 | <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> | ||
6164 | A global variable (not a function) that | ||
6165 | holds a string containing the current interpreter version. | ||
6166 | The current contents of this variable is "<code>Lua 5.1</code>". | ||
6167 | |||
6168 | |||
6169 | |||
6170 | |||
6171 | <p> | ||
6172 | <hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3> | ||
6173 | |||
6174 | |||
6175 | <p> | ||
6176 | This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, | ||
6177 | except that you can set a new error handler. | ||
6178 | |||
6179 | |||
6180 | <p> | ||
6181 | <code>xpcall</code> calls function <code>f</code> in protected mode, | ||
6182 | using <code>err</code> as the error handler. | ||
6183 | Any error inside <code>f</code> is not propagated; | ||
6184 | instead, <code>xpcall</code> catches the error, | ||
6185 | calls the <code>err</code> function with the original error object, | ||
6186 | and returns a status code. | ||
6187 | Its first result is the status code (a boolean), | ||
6188 | which is true if the call succeeds without errors. | ||
6189 | In this case, <code>xpcall</code> also returns all results from the call, | ||
6190 | after this first result. | ||
6191 | In case of any error, | ||
6192 | <code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. | ||
6193 | |||
6194 | |||
6195 | |||
6196 | |||
6197 | |||
6198 | |||
6199 | |||
6200 | <h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2> | ||
6201 | |||
6202 | <p> | ||
6203 | The operations related to coroutines comprise a sub-library of | ||
6204 | the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. | ||
6205 | See <a href="#2.11">§2.11</a> for a general description of coroutines. | ||
6206 | |||
6207 | |||
6208 | <p> | ||
6209 | <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> | ||
6210 | |||
6211 | |||
6212 | <p> | ||
6213 | Creates a new coroutine, with body <code>f</code>. | ||
6214 | <code>f</code> must be a Lua function. | ||
6215 | Returns this new coroutine, | ||
6216 | an object with type <code>"thread"</code>. | ||
6217 | |||
6218 | |||
6219 | |||
6220 | |||
6221 | <p> | ||
6222 | <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> | ||
6223 | |||
6224 | |||
6225 | <p> | ||
6226 | Starts or continues the execution of coroutine <code>co</code>. | ||
6227 | The first time you resume a coroutine, | ||
6228 | it starts running its body. | ||
6229 | The values <code>val1</code>, ··· are passed | ||
6230 | as the arguments to the body function. | ||
6231 | If the coroutine has yielded, | ||
6232 | <code>resume</code> restarts it; | ||
6233 | the values <code>val1</code>, ··· are passed | ||
6234 | as the results from the yield. | ||
6235 | |||
6236 | |||
6237 | <p> | ||
6238 | If the coroutine runs without any errors, | ||
6239 | <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> | ||
6240 | (if the coroutine yields) or any values returned by the body function | ||
6241 | (if the coroutine terminates). | ||
6242 | If there is any error, | ||
6243 | <code>resume</code> returns <b>false</b> plus the error message. | ||
6244 | |||
6245 | |||
6246 | |||
6247 | |||
6248 | <p> | ||
6249 | <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> | ||
6250 | |||
6251 | |||
6252 | <p> | ||
6253 | Returns the running coroutine, | ||
6254 | or <b>nil</b> when called by the main thread. | ||
6255 | |||
6256 | |||
6257 | |||
6258 | |||
6259 | <p> | ||
6260 | <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> | ||
6261 | |||
6262 | |||
6263 | <p> | ||
6264 | Returns the status of coroutine <code>co</code>, as a string: | ||
6265 | <code>"running"</code>, | ||
6266 | if the coroutine is running (that is, it called <code>status</code>); | ||
6267 | <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, | ||
6268 | or if it has not started running yet; | ||
6269 | <code>"normal"</code> if the coroutine is active but not running | ||
6270 | (that is, it has resumed another coroutine); | ||
6271 | and <code>"dead"</code> if the coroutine has finished its body function, | ||
6272 | or if it has stopped with an error. | ||
6273 | |||
6274 | |||
6275 | |||
6276 | |||
6277 | <p> | ||
6278 | <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> | ||
6279 | |||
6280 | |||
6281 | <p> | ||
6282 | Creates a new coroutine, with body <code>f</code>. | ||
6283 | <code>f</code> must be a Lua function. | ||
6284 | Returns a function that resumes the coroutine each time it is called. | ||
6285 | Any arguments passed to the function behave as the | ||
6286 | extra arguments to <code>resume</code>. | ||
6287 | Returns the same values returned by <code>resume</code>, | ||
6288 | except the first boolean. | ||
6289 | In case of error, propagates the error. | ||
6290 | |||
6291 | |||
6292 | |||
6293 | |||
6294 | <p> | ||
6295 | <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> | ||
6296 | |||
6297 | |||
6298 | <p> | ||
6299 | Suspends the execution of the calling coroutine. | ||
6300 | The coroutine cannot be running a C function, | ||
6301 | a metamethod, or an iterator. | ||
6302 | Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. | ||
6303 | |||
6304 | |||
6305 | |||
6306 | |||
6307 | |||
6308 | |||
6309 | |||
6310 | <h2>5.3 - <a name="5.3">Modules</a></h2> | ||
6311 | |||
6312 | <p> | ||
6313 | The package library provides basic | ||
6314 | facilities for loading and building modules in Lua. | ||
6315 | It exports two of its functions directly in the global environment: | ||
6316 | <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. | ||
6317 | Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. | ||
6318 | |||
6319 | |||
6320 | <p> | ||
6321 | <hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3> | ||
6322 | |||
6323 | |||
6324 | <p> | ||
6325 | Creates a module. | ||
6326 | If there is a table in <code>package.loaded[name]</code>, | ||
6327 | this table is the module. | ||
6328 | Otherwise, if there is a global table <code>t</code> with the given name, | ||
6329 | this table is the module. | ||
6330 | Otherwise creates a new table <code>t</code> and | ||
6331 | sets it as the value of the global <code>name</code> and | ||
6332 | the value of <code>package.loaded[name]</code>. | ||
6333 | This function also initializes <code>t._NAME</code> with the given name, | ||
6334 | <code>t._M</code> with the module (<code>t</code> itself), | ||
6335 | and <code>t._PACKAGE</code> with the package name | ||
6336 | (the full module name minus last component; see below). | ||
6337 | Finally, <code>module</code> sets <code>t</code> as the new environment | ||
6338 | of the current function and the new value of <code>package.loaded[name]</code>, | ||
6339 | so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. | ||
6340 | |||
6341 | |||
6342 | <p> | ||
6343 | If <code>name</code> is a compound name | ||
6344 | (that is, one with components separated by dots), | ||
6345 | <code>module</code> creates (or reuses, if they already exist) | ||
6346 | tables for each component. | ||
6347 | For instance, if <code>name</code> is <code>a.b.c</code>, | ||
6348 | then <code>module</code> stores the module table in field <code>c</code> of | ||
6349 | field <code>b</code> of global <code>a</code>. | ||
6350 | |||
6351 | |||
6352 | <p> | ||
6353 | This function can receive optional <em>options</em> after | ||
6354 | the module name, | ||
6355 | where each option is a function to be applied over the module. | ||
6356 | |||
6357 | |||
6358 | |||
6359 | |||
6360 | <p> | ||
6361 | <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> | ||
6362 | |||
6363 | |||
6364 | <p> | ||
6365 | Loads the given module. | ||
6366 | The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table | ||
6367 | to determine whether <code>modname</code> is already loaded. | ||
6368 | If it is, then <code>require</code> returns the value stored | ||
6369 | at <code>package.loaded[modname]</code>. | ||
6370 | Otherwise, it tries to find a <em>loader</em> for the module. | ||
6371 | |||
6372 | |||
6373 | <p> | ||
6374 | To find a loader, | ||
6375 | <code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array. | ||
6376 | By changing this array, | ||
6377 | we can change how <code>require</code> looks for a module. | ||
6378 | The following explanation is based on the default configuration | ||
6379 | for <a href="#pdf-package.loaders"><code>package.loaders</code></a>. | ||
6380 | |||
6381 | |||
6382 | <p> | ||
6383 | First <code>require</code> queries <code>package.preload[modname]</code>. | ||
6384 | If it has a value, | ||
6385 | this value (which should be a function) is the loader. | ||
6386 | Otherwise <code>require</code> searches for a Lua loader using the | ||
6387 | path stored in <a href="#pdf-package.path"><code>package.path</code></a>. | ||
6388 | If that also fails, it searches for a C loader using the | ||
6389 | path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. | ||
6390 | If that also fails, | ||
6391 | it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>). | ||
6392 | |||
6393 | |||
6394 | <p> | ||
6395 | Once a loader is found, | ||
6396 | <code>require</code> calls the loader with a single argument, <code>modname</code>. | ||
6397 | If the loader returns any value, | ||
6398 | <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. | ||
6399 | If the loader returns no value and | ||
6400 | has not assigned any value to <code>package.loaded[modname]</code>, | ||
6401 | then <code>require</code> assigns <b>true</b> to this entry. | ||
6402 | In any case, <code>require</code> returns the | ||
6403 | final value of <code>package.loaded[modname]</code>. | ||
6404 | |||
6405 | |||
6406 | <p> | ||
6407 | If there is any error loading or running the module, | ||
6408 | or if it cannot find any loader for the module, | ||
6409 | then <code>require</code> signals an error. | ||
6410 | |||
6411 | |||
6412 | |||
6413 | |||
6414 | <p> | ||
6415 | <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> | ||
6416 | |||
6417 | |||
6418 | <p> | ||
6419 | The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. | ||
6420 | |||
6421 | |||
6422 | <p> | ||
6423 | Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way | ||
6424 | it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, | ||
6425 | using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> | ||
6426 | or a default path defined in <code>luaconf.h</code>. | ||
6427 | |||
6428 | |||
6429 | |||
6430 | |||
6431 | <p> | ||
6432 | |||
6433 | <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> | ||
6434 | |||
6435 | |||
6436 | <p> | ||
6437 | A table used by <a href="#pdf-require"><code>require</code></a> to control which | ||
6438 | modules are already loaded. | ||
6439 | When you require a module <code>modname</code> and | ||
6440 | <code>package.loaded[modname]</code> is not false, | ||
6441 | <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. | ||
6442 | |||
6443 | |||
6444 | |||
6445 | |||
6446 | <p> | ||
6447 | <hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3> | ||
6448 | |||
6449 | |||
6450 | <p> | ||
6451 | A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. | ||
6452 | |||
6453 | |||
6454 | <p> | ||
6455 | Each entry in this table is a <em>searcher function</em>. | ||
6456 | When looking for a module, | ||
6457 | <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, | ||
6458 | with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its | ||
6459 | sole parameter. | ||
6460 | The function can return another function (the module <em>loader</em>) | ||
6461 | or a string explaining why it did not find that module | ||
6462 | (or <b>nil</b> if it has nothing to say). | ||
6463 | Lua initializes this table with four functions. | ||
6464 | |||
6465 | |||
6466 | <p> | ||
6467 | The first searcher simply looks for a loader in the | ||
6468 | <a href="#pdf-package.preload"><code>package.preload</code></a> table. | ||
6469 | |||
6470 | |||
6471 | <p> | ||
6472 | The second searcher looks for a loader as a Lua library, | ||
6473 | using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. | ||
6474 | A path is a sequence of <em>templates</em> separated by semicolons. | ||
6475 | For each template, | ||
6476 | the searcher will change each interrogation | ||
6477 | mark in the template by <code>filename</code>, | ||
6478 | which is the module name with each dot replaced by a | ||
6479 | "directory separator" (such as "<code>/</code>" in Unix); | ||
6480 | then it will try to open the resulting file name. | ||
6481 | So, for instance, if the Lua path is the string | ||
6482 | |||
6483 | <pre> | ||
6484 | "./?.lua;./?.lc;/usr/local/?/init.lua" | ||
6485 | </pre><p> | ||
6486 | the search for a Lua file for module <code>foo</code> | ||
6487 | will try to open the files | ||
6488 | <code>./foo.lua</code>, <code>./foo.lc</code>, and | ||
6489 | <code>/usr/local/foo/init.lua</code>, in that order. | ||
6490 | |||
6491 | |||
6492 | <p> | ||
6493 | The third searcher looks for a loader as a C library, | ||
6494 | using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. | ||
6495 | For instance, | ||
6496 | if the C path is the string | ||
6497 | |||
6498 | <pre> | ||
6499 | "./?.so;./?.dll;/usr/local/?/init.so" | ||
6500 | </pre><p> | ||
6501 | the searcher for module <code>foo</code> | ||
6502 | will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, | ||
6503 | and <code>/usr/local/foo/init.so</code>, in that order. | ||
6504 | Once it finds a C library, | ||
6505 | this searcher first uses a dynamic link facility to link the | ||
6506 | application with the library. | ||
6507 | Then it tries to find a C function inside the library to | ||
6508 | be used as the loader. | ||
6509 | The name of this C function is the string "<code>luaopen_</code>" | ||
6510 | concatenated with a copy of the module name where each dot | ||
6511 | is replaced by an underscore. | ||
6512 | Moreover, if the module name has a hyphen, | ||
6513 | its prefix up to (and including) the first hyphen is removed. | ||
6514 | For instance, if the module name is <code>a.v1-b.c</code>, | ||
6515 | the function name will be <code>luaopen_b_c</code>. | ||
6516 | |||
6517 | |||
6518 | <p> | ||
6519 | The fourth searcher tries an <em>all-in-one loader</em>. | ||
6520 | It searches the C path for a library for | ||
6521 | the root name of the given module. | ||
6522 | For instance, when requiring <code>a.b.c</code>, | ||
6523 | it will search for a C library for <code>a</code>. | ||
6524 | If found, it looks into it for an open function for | ||
6525 | the submodule; | ||
6526 | in our example, that would be <code>luaopen_a_b_c</code>. | ||
6527 | With this facility, a package can pack several C submodules | ||
6528 | into one single library, | ||
6529 | with each submodule keeping its original open function. | ||
6530 | |||
6531 | |||
6532 | |||
6533 | |||
6534 | <p> | ||
6535 | <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> | ||
6536 | |||
6537 | |||
6538 | <p> | ||
6539 | Dynamically links the host program with the C library <code>libname</code>. | ||
6540 | Inside this library, looks for a function <code>funcname</code> | ||
6541 | and returns this function as a C function. | ||
6542 | (So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). | ||
6543 | |||
6544 | |||
6545 | <p> | ||
6546 | This is a low-level function. | ||
6547 | It completely bypasses the package and module system. | ||
6548 | Unlike <a href="#pdf-require"><code>require</code></a>, | ||
6549 | it does not perform any path searching and | ||
6550 | does not automatically adds extensions. | ||
6551 | <code>libname</code> must be the complete file name of the C library, | ||
6552 | including if necessary a path and extension. | ||
6553 | <code>funcname</code> must be the exact name exported by the C library | ||
6554 | (which may depend on the C compiler and linker used). | ||
6555 | |||
6556 | |||
6557 | <p> | ||
6558 | This function is not supported by ANSI C. | ||
6559 | As such, it is only available on some platforms | ||
6560 | (Windows, Linux, Mac OS X, Solaris, BSD, | ||
6561 | plus other Unix systems that support the <code>dlfcn</code> standard). | ||
6562 | |||
6563 | |||
6564 | |||
6565 | |||
6566 | <p> | ||
6567 | <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> | ||
6568 | |||
6569 | |||
6570 | <p> | ||
6571 | The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. | ||
6572 | |||
6573 | |||
6574 | <p> | ||
6575 | At start-up, Lua initializes this variable with | ||
6576 | the value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or | ||
6577 | with a default path defined in <code>luaconf.h</code>, | ||
6578 | if the environment variable is not defined. | ||
6579 | Any "<code>;;</code>" in the value of the environment variable | ||
6580 | is replaced by the default path. | ||
6581 | |||
6582 | |||
6583 | |||
6584 | |||
6585 | <p> | ||
6586 | <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> | ||
6587 | |||
6588 | |||
6589 | <p> | ||
6590 | A table to store loaders for specific modules | ||
6591 | (see <a href="#pdf-require"><code>require</code></a>). | ||
6592 | |||
6593 | |||
6594 | |||
6595 | |||
6596 | <p> | ||
6597 | <hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3> | ||
6598 | |||
6599 | |||
6600 | <p> | ||
6601 | Sets a metatable for <code>module</code> with | ||
6602 | its <code>__index</code> field referring to the global environment, | ||
6603 | so that this module inherits values | ||
6604 | from the global environment. | ||
6605 | To be used as an option to function <a href="#pdf-module"><code>module</code></a>. | ||
6606 | |||
6607 | |||
6608 | |||
6609 | |||
6610 | |||
6611 | |||
6612 | |||
6613 | <h2>5.4 - <a name="5.4">String Manipulation</a></h2> | ||
6614 | |||
6615 | <p> | ||
6616 | This library provides generic functions for string manipulation, | ||
6617 | such as finding and extracting substrings, and pattern matching. | ||
6618 | When indexing a string in Lua, the first character is at position 1 | ||
6619 | (not at 0, as in C). | ||
6620 | Indices are allowed to be negative and are interpreted as indexing backwards, | ||
6621 | from the end of the string. | ||
6622 | Thus, the last character is at position -1, and so on. | ||
6623 | |||
6624 | |||
6625 | <p> | ||
6626 | The string library provides all its functions inside the table | ||
6627 | <a name="pdf-string"><code>string</code></a>. | ||
6628 | It also sets a metatable for strings | ||
6629 | where the <code>__index</code> field points to the <code>string</code> table. | ||
6630 | Therefore, you can use the string functions in object-oriented style. | ||
6631 | For instance, <code>string.byte(s, i)</code> | ||
6632 | can be written as <code>s:byte(i)</code>. | ||
6633 | |||
6634 | |||
6635 | <p> | ||
6636 | The string library assumes one-byte character encodings. | ||
6637 | |||
6638 | |||
6639 | <p> | ||
6640 | <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> | ||
6641 | Returns the internal numerical codes of the characters <code>s[i]</code>, | ||
6642 | <code>s[i+1]</code>, ···, <code>s[j]</code>. | ||
6643 | The default value for <code>i</code> is 1; | ||
6644 | the default value for <code>j</code> is <code>i</code>. | ||
6645 | |||
6646 | |||
6647 | <p> | ||
6648 | Note that numerical codes are not necessarily portable across platforms. | ||
6649 | |||
6650 | |||
6651 | |||
6652 | |||
6653 | <p> | ||
6654 | <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> | ||
6655 | Receives zero or more integers. | ||
6656 | Returns a string with length equal to the number of arguments, | ||
6657 | in which each character has the internal numerical code equal | ||
6658 | to its corresponding argument. | ||
6659 | |||
6660 | |||
6661 | <p> | ||
6662 | Note that numerical codes are not necessarily portable across platforms. | ||
6663 | |||
6664 | |||
6665 | |||
6666 | |||
6667 | <p> | ||
6668 | <hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> | ||
6669 | |||
6670 | |||
6671 | <p> | ||
6672 | Returns a string containing a binary representation of the given function, | ||
6673 | so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns | ||
6674 | a copy of the function. | ||
6675 | <code>function</code> must be a Lua function without upvalues. | ||
6676 | |||
6677 | |||
6678 | |||
6679 | |||
6680 | <p> | ||
6681 | <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> | ||
6682 | Looks for the first match of | ||
6683 | <code>pattern</code> in the string <code>s</code>. | ||
6684 | If it finds a match, then <code>find</code> returns the indices of <code>s</code> | ||
6685 | where this occurrence starts and ends; | ||
6686 | otherwise, it returns <b>nil</b>. | ||
6687 | A third, optional numerical argument <code>init</code> specifies | ||
6688 | where to start the search; | ||
6689 | its default value is 1 and can be negative. | ||
6690 | A value of <b>true</b> as a fourth, optional argument <code>plain</code> | ||
6691 | turns off the pattern matching facilities, | ||
6692 | so the function does a plain "find substring" operation, | ||
6693 | with no characters in <code>pattern</code> being considered "magic". | ||
6694 | Note that if <code>plain</code> is given, then <code>init</code> must be given as well. | ||
6695 | |||
6696 | |||
6697 | <p> | ||
6698 | If the pattern has captures, | ||
6699 | then in a successful match | ||
6700 | the captured values are also returned, | ||
6701 | after the two indices. | ||
6702 | |||
6703 | |||
6704 | |||
6705 | |||
6706 | <p> | ||
6707 | <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> | ||
6708 | Returns a formatted version of its variable number of arguments | ||
6709 | following the description given in its first argument (which must be a string). | ||
6710 | The format string follows the same rules as the <code>printf</code> family of | ||
6711 | standard C functions. | ||
6712 | The only differences are that the options/modifiers | ||
6713 | <code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, | ||
6714 | and <code>h</code> are not supported | ||
6715 | and that there is an extra option, <code>q</code>. | ||
6716 | The <code>q</code> option formats a string in a form suitable to be safely read | ||
6717 | back by the Lua interpreter: | ||
6718 | the string is written between double quotes, | ||
6719 | and all double quotes, newlines, embedded zeros, | ||
6720 | and backslashes in the string | ||
6721 | are correctly escaped when written. | ||
6722 | For instance, the call | ||
6723 | |||
6724 | <pre> | ||
6725 | string.format('%q', 'a string with "quotes" and \n new line') | ||
6726 | </pre><p> | ||
6727 | will produce the string: | ||
6728 | |||
6729 | <pre> | ||
6730 | "a string with \"quotes\" and \ | ||
6731 | new line" | ||
6732 | </pre> | ||
6733 | |||
6734 | <p> | ||
6735 | The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>, | ||
6736 | <code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all | ||
6737 | expect a number as argument, | ||
6738 | whereas <code>q</code> and <code>s</code> expect a string. | ||
6739 | |||
6740 | |||
6741 | <p> | ||
6742 | This function does not accept string values | ||
6743 | containing embedded zeros, | ||
6744 | except as arguments to the <code>q</code> option. | ||
6745 | |||
6746 | |||
6747 | |||
6748 | |||
6749 | <p> | ||
6750 | <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> | ||
6751 | Returns an iterator function that, | ||
6752 | each time it is called, | ||
6753 | returns the next captures from <code>pattern</code> over string <code>s</code>. | ||
6754 | If <code>pattern</code> specifies no captures, | ||
6755 | then the whole match is produced in each call. | ||
6756 | |||
6757 | |||
6758 | <p> | ||
6759 | As an example, the following loop | ||
6760 | |||
6761 | <pre> | ||
6762 | s = "hello world from Lua" | ||
6763 | for w in string.gmatch(s, "%a+") do | ||
6764 | print(w) | ||
6765 | end | ||
6766 | </pre><p> | ||
6767 | will iterate over all the words from string <code>s</code>, | ||
6768 | printing one per line. | ||
6769 | The next example collects all pairs <code>key=value</code> from the | ||
6770 | given string into a table: | ||
6771 | |||
6772 | <pre> | ||
6773 | t = {} | ||
6774 | s = "from=world, to=Lua" | ||
6775 | for k, v in string.gmatch(s, "(%w+)=(%w+)") do | ||
6776 | t[k] = v | ||
6777 | end | ||
6778 | </pre> | ||
6779 | |||
6780 | <p> | ||
6781 | For this function, a '<code>^</code>' at the start of a pattern does not | ||
6782 | work as an anchor, as this would prevent the iteration. | ||
6783 | |||
6784 | |||
6785 | |||
6786 | |||
6787 | <p> | ||
6788 | <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> | ||
6789 | Returns a copy of <code>s</code> | ||
6790 | in which all (or the first <code>n</code>, if given) | ||
6791 | occurrences of the <code>pattern</code> have been | ||
6792 | replaced by a replacement string specified by <code>repl</code>, | ||
6793 | which can be a string, a table, or a function. | ||
6794 | <code>gsub</code> also returns, as its second value, | ||
6795 | the total number of matches that occurred. | ||
6796 | |||
6797 | |||
6798 | <p> | ||
6799 | If <code>repl</code> is a string, then its value is used for replacement. | ||
6800 | The character <code>%</code> works as an escape character: | ||
6801 | any sequence in <code>repl</code> of the form <code>%<em>n</em></code>, | ||
6802 | with <em>n</em> between 1 and 9, | ||
6803 | stands for the value of the <em>n</em>-th captured substring (see below). | ||
6804 | The sequence <code>%0</code> stands for the whole match. | ||
6805 | The sequence <code>%%</code> stands for a single <code>%</code>. | ||
6806 | |||
6807 | |||
6808 | <p> | ||
6809 | If <code>repl</code> is a table, then the table is queried for every match, | ||
6810 | using the first capture as the key; | ||
6811 | if the pattern specifies no captures, | ||
6812 | then the whole match is used as the key. | ||
6813 | |||
6814 | |||
6815 | <p> | ||
6816 | If <code>repl</code> is a function, then this function is called every time a | ||
6817 | match occurs, with all captured substrings passed as arguments, | ||
6818 | in order; | ||
6819 | if the pattern specifies no captures, | ||
6820 | then the whole match is passed as a sole argument. | ||
6821 | |||
6822 | |||
6823 | <p> | ||
6824 | If the value returned by the table query or by the function call | ||
6825 | is a string or a number, | ||
6826 | then it is used as the replacement string; | ||
6827 | otherwise, if it is <b>false</b> or <b>nil</b>, | ||
6828 | then there is no replacement | ||
6829 | (that is, the original match is kept in the string). | ||
6830 | |||
6831 | |||
6832 | <p> | ||
6833 | Here are some examples: | ||
6834 | |||
6835 | <pre> | ||
6836 | x = string.gsub("hello world", "(%w+)", "%1 %1") | ||
6837 | --> x="hello hello world world" | ||
6838 | |||
6839 | x = string.gsub("hello world", "%w+", "%0 %0", 1) | ||
6840 | --> x="hello hello world" | ||
6841 | |||
6842 | x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") | ||
6843 | --> x="world hello Lua from" | ||
6844 | |||
6845 | x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) | ||
6846 | --> x="home = /home/roberto, user = roberto" | ||
6847 | |||
6848 | x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) | ||
6849 | return loadstring(s)() | ||
6850 | end) | ||
6851 | --> x="4+5 = 9" | ||
6852 | |||
6853 | local t = {name="lua", version="5.1"} | ||
6854 | x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) | ||
6855 | --> x="lua-5.1.tar.gz" | ||
6856 | </pre> | ||
6857 | |||
6858 | |||
6859 | |||
6860 | <p> | ||
6861 | <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> | ||
6862 | Receives a string and returns its length. | ||
6863 | The empty string <code>""</code> has length 0. | ||
6864 | Embedded zeros are counted, | ||
6865 | so <code>"a\000bc\000"</code> has length 5. | ||
6866 | |||
6867 | |||
6868 | |||
6869 | |||
6870 | <p> | ||
6871 | <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> | ||
6872 | Receives a string and returns a copy of this string with all | ||
6873 | uppercase letters changed to lowercase. | ||
6874 | All other characters are left unchanged. | ||
6875 | The definition of what an uppercase letter is depends on the current locale. | ||
6876 | |||
6877 | |||
6878 | |||
6879 | |||
6880 | <p> | ||
6881 | <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> | ||
6882 | Looks for the first <em>match</em> of | ||
6883 | <code>pattern</code> in the string <code>s</code>. | ||
6884 | If it finds one, then <code>match</code> returns | ||
6885 | the captures from the pattern; | ||
6886 | otherwise it returns <b>nil</b>. | ||
6887 | If <code>pattern</code> specifies no captures, | ||
6888 | then the whole match is returned. | ||
6889 | A third, optional numerical argument <code>init</code> specifies | ||
6890 | where to start the search; | ||
6891 | its default value is 1 and can be negative. | ||
6892 | |||
6893 | |||
6894 | |||
6895 | |||
6896 | <p> | ||
6897 | <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3> | ||
6898 | Returns a string that is the concatenation of <code>n</code> copies of | ||
6899 | the string <code>s</code>. | ||
6900 | |||
6901 | |||
6902 | |||
6903 | |||
6904 | <p> | ||
6905 | <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> | ||
6906 | Returns a string that is the string <code>s</code> reversed. | ||
6907 | |||
6908 | |||
6909 | |||
6910 | |||
6911 | <p> | ||
6912 | <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> | ||
6913 | Returns the substring of <code>s</code> that | ||
6914 | starts at <code>i</code> and continues until <code>j</code>; | ||
6915 | <code>i</code> and <code>j</code> can be negative. | ||
6916 | If <code>j</code> is absent, then it is assumed to be equal to -1 | ||
6917 | (which is the same as the string length). | ||
6918 | In particular, | ||
6919 | the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> | ||
6920 | with length <code>j</code>, | ||
6921 | and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> | ||
6922 | with length <code>i</code>. | ||
6923 | |||
6924 | |||
6925 | |||
6926 | |||
6927 | <p> | ||
6928 | <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> | ||
6929 | Receives a string and returns a copy of this string with all | ||
6930 | lowercase letters changed to uppercase. | ||
6931 | All other characters are left unchanged. | ||
6932 | The definition of what a lowercase letter is depends on the current locale. | ||
6933 | |||
6934 | |||
6935 | |||
6936 | <h3>5.4.1 - <a name="5.4.1">Patterns</a></h3> | ||
6937 | |||
6938 | |||
6939 | <h4>Character Class:</h4><p> | ||
6940 | A <em>character class</em> is used to represent a set of characters. | ||
6941 | The following combinations are allowed in describing a character class: | ||
6942 | |||
6943 | <ul> | ||
6944 | |||
6945 | <li><b><em>x</em>:</b> | ||
6946 | (where <em>x</em> is not one of the <em>magic characters</em> | ||
6947 | <code>^$()%.[]*+-?</code>) | ||
6948 | represents the character <em>x</em> itself. | ||
6949 | </li> | ||
6950 | |||
6951 | <li><b><code>.</code>:</b> (a dot) represents all characters.</li> | ||
6952 | |||
6953 | <li><b><code>%a</code>:</b> represents all letters.</li> | ||
6954 | |||
6955 | <li><b><code>%c</code>:</b> represents all control characters.</li> | ||
6956 | |||
6957 | <li><b><code>%d</code>:</b> represents all digits.</li> | ||
6958 | |||
6959 | <li><b><code>%l</code>:</b> represents all lowercase letters.</li> | ||
6960 | |||
6961 | <li><b><code>%p</code>:</b> represents all punctuation characters.</li> | ||
6962 | |||
6963 | <li><b><code>%s</code>:</b> represents all space characters.</li> | ||
6964 | |||
6965 | <li><b><code>%u</code>:</b> represents all uppercase letters.</li> | ||
6966 | |||
6967 | <li><b><code>%w</code>:</b> represents all alphanumeric characters.</li> | ||
6968 | |||
6969 | <li><b><code>%x</code>:</b> represents all hexadecimal digits.</li> | ||
6970 | |||
6971 | <li><b><code>%z</code>:</b> represents the character with representation 0.</li> | ||
6972 | |||
6973 | <li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character) | ||
6974 | represents the character <em>x</em>. | ||
6975 | This is the standard way to escape the magic characters. | ||
6976 | Any punctuation character (even the non magic) | ||
6977 | can be preceded by a '<code>%</code>' | ||
6978 | when used to represent itself in a pattern. | ||
6979 | </li> | ||
6980 | |||
6981 | <li><b><code>[<em>set</em>]</code>:</b> | ||
6982 | represents the class which is the union of all | ||
6983 | characters in <em>set</em>. | ||
6984 | A range of characters can be specified by | ||
6985 | separating the end characters of the range with a '<code>-</code>'. | ||
6986 | All classes <code>%</code><em>x</em> described above can also be used as | ||
6987 | components in <em>set</em>. | ||
6988 | All other characters in <em>set</em> represent themselves. | ||
6989 | For example, <code>[%w_]</code> (or <code>[_%w]</code>) | ||
6990 | represents all alphanumeric characters plus the underscore, | ||
6991 | <code>[0-7]</code> represents the octal digits, | ||
6992 | and <code>[0-7%l%-]</code> represents the octal digits plus | ||
6993 | the lowercase letters plus the '<code>-</code>' character. | ||
6994 | |||
6995 | |||
6996 | <p> | ||
6997 | The interaction between ranges and classes is not defined. | ||
6998 | Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> | ||
6999 | have no meaning. | ||
7000 | </li> | ||
7001 | |||
7002 | <li><b><code>[^<em>set</em>]</code>:</b> | ||
7003 | represents the complement of <em>set</em>, | ||
7004 | where <em>set</em> is interpreted as above. | ||
7005 | </li> | ||
7006 | |||
7007 | </ul><p> | ||
7008 | For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), | ||
7009 | the corresponding uppercase letter represents the complement of the class. | ||
7010 | For instance, <code>%S</code> represents all non-space characters. | ||
7011 | |||
7012 | |||
7013 | <p> | ||
7014 | The definitions of letter, space, and other character groups | ||
7015 | depend on the current locale. | ||
7016 | In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. | ||
7017 | |||
7018 | |||
7019 | |||
7020 | |||
7021 | |||
7022 | <h4>Pattern Item:</h4><p> | ||
7023 | A <em>pattern item</em> can be | ||
7024 | |||
7025 | <ul> | ||
7026 | |||
7027 | <li> | ||
7028 | a single character class, | ||
7029 | which matches any single character in the class; | ||
7030 | </li> | ||
7031 | |||
7032 | <li> | ||
7033 | a single character class followed by '<code>*</code>', | ||
7034 | which matches 0 or more repetitions of characters in the class. | ||
7035 | These repetition items will always match the longest possible sequence; | ||
7036 | </li> | ||
7037 | |||
7038 | <li> | ||
7039 | a single character class followed by '<code>+</code>', | ||
7040 | which matches 1 or more repetitions of characters in the class. | ||
7041 | These repetition items will always match the longest possible sequence; | ||
7042 | </li> | ||
7043 | |||
7044 | <li> | ||
7045 | a single character class followed by '<code>-</code>', | ||
7046 | which also matches 0 or more repetitions of characters in the class. | ||
7047 | Unlike '<code>*</code>', | ||
7048 | these repetition items will always match the <em>shortest</em> possible sequence; | ||
7049 | </li> | ||
7050 | |||
7051 | <li> | ||
7052 | a single character class followed by '<code>?</code>', | ||
7053 | which matches 0 or 1 occurrence of a character in the class; | ||
7054 | </li> | ||
7055 | |||
7056 | <li> | ||
7057 | <code>%<em>n</em></code>, for <em>n</em> between 1 and 9; | ||
7058 | such item matches a substring equal to the <em>n</em>-th captured string | ||
7059 | (see below); | ||
7060 | </li> | ||
7061 | |||
7062 | <li> | ||
7063 | <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; | ||
7064 | such item matches strings that start with <em>x</em>, end with <em>y</em>, | ||
7065 | and where the <em>x</em> and <em>y</em> are <em>balanced</em>. | ||
7066 | This means that, if one reads the string from left to right, | ||
7067 | counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, | ||
7068 | the ending <em>y</em> is the first <em>y</em> where the count reaches 0. | ||
7069 | For instance, the item <code>%b()</code> matches expressions with | ||
7070 | balanced parentheses. | ||
7071 | </li> | ||
7072 | |||
7073 | </ul> | ||
7074 | |||
7075 | |||
7076 | |||
7077 | |||
7078 | <h4>Pattern:</h4><p> | ||
7079 | A <em>pattern</em> is a sequence of pattern items. | ||
7080 | A '<code>^</code>' at the beginning of a pattern anchors the match at the | ||
7081 | beginning of the subject string. | ||
7082 | A '<code>$</code>' at the end of a pattern anchors the match at the | ||
7083 | end of the subject string. | ||
7084 | At other positions, | ||
7085 | '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. | ||
7086 | |||
7087 | |||
7088 | |||
7089 | |||
7090 | |||
7091 | <h4>Captures:</h4><p> | ||
7092 | A pattern can contain sub-patterns enclosed in parentheses; | ||
7093 | they describe <em>captures</em>. | ||
7094 | When a match succeeds, the substrings of the subject string | ||
7095 | that match captures are stored (<em>captured</em>) for future use. | ||
7096 | Captures are numbered according to their left parentheses. | ||
7097 | For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, | ||
7098 | the part of the string matching <code>"a*(.)%w(%s*)"</code> is | ||
7099 | stored as the first capture (and therefore has number 1); | ||
7100 | the character matching "<code>.</code>" is captured with number 2, | ||
7101 | and the part matching "<code>%s*</code>" has number 3. | ||
7102 | |||
7103 | |||
7104 | <p> | ||
7105 | As a special case, the empty capture <code>()</code> captures | ||
7106 | the current string position (a number). | ||
7107 | For instance, if we apply the pattern <code>"()aa()"</code> on the | ||
7108 | string <code>"flaaap"</code>, there will be two captures: 3 and 5. | ||
7109 | |||
7110 | |||
7111 | <p> | ||
7112 | A pattern cannot contain embedded zeros. Use <code>%z</code> instead. | ||
7113 | |||
7114 | |||
7115 | |||
7116 | |||
7117 | |||
7118 | |||
7119 | |||
7120 | |||
7121 | |||
7122 | |||
7123 | |||
7124 | <h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p> | ||
7125 | This library provides generic functions for table manipulation. | ||
7126 | It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. | ||
7127 | |||
7128 | |||
7129 | <p> | ||
7130 | Most functions in the table library assume that the table | ||
7131 | represents an array or a list. | ||
7132 | For these functions, when we talk about the "length" of a table | ||
7133 | we mean the result of the length operator. | ||
7134 | |||
7135 | |||
7136 | <p> | ||
7137 | <hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3> | ||
7138 | Given an array where all elements are strings or numbers, | ||
7139 | returns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>. | ||
7140 | The default value for <code>sep</code> is the empty string, | ||
7141 | the default for <code>i</code> is 1, | ||
7142 | and the default for <code>j</code> is the length of the table. | ||
7143 | If <code>i</code> is greater than <code>j</code>, returns the empty string. | ||
7144 | |||
7145 | |||
7146 | |||
7147 | |||
7148 | <p> | ||
7149 | <hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3> | ||
7150 | |||
7151 | |||
7152 | <p> | ||
7153 | Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, | ||
7154 | shifting up other elements to open space, if necessary. | ||
7155 | The default value for <code>pos</code> is <code>n+1</code>, | ||
7156 | where <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>), | ||
7157 | so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end | ||
7158 | of table <code>t</code>. | ||
7159 | |||
7160 | |||
7161 | |||
7162 | |||
7163 | <p> | ||
7164 | <hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3> | ||
7165 | |||
7166 | |||
7167 | <p> | ||
7168 | Returns the largest positive numerical index of the given table, | ||
7169 | or zero if the table has no positive numerical indices. | ||
7170 | (To do its job this function does a linear traversal of | ||
7171 | the whole table.) | ||
7172 | |||
7173 | |||
7174 | |||
7175 | |||
7176 | <p> | ||
7177 | <hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3> | ||
7178 | |||
7179 | |||
7180 | <p> | ||
7181 | Removes from <code>table</code> the element at position <code>pos</code>, | ||
7182 | shifting down other elements to close the space, if necessary. | ||
7183 | Returns the value of the removed element. | ||
7184 | The default value for <code>pos</code> is <code>n</code>, | ||
7185 | where <code>n</code> is the length of the table, | ||
7186 | so that a call <code>table.remove(t)</code> removes the last element | ||
7187 | of table <code>t</code>. | ||
7188 | |||
7189 | |||
7190 | |||
7191 | |||
7192 | <p> | ||
7193 | <hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3> | ||
7194 | Sorts table elements in a given order, <em>in-place</em>, | ||
7195 | from <code>table[1]</code> to <code>table[n]</code>, | ||
7196 | where <code>n</code> is the length of the table. | ||
7197 | If <code>comp</code> is given, | ||
7198 | then it must be a function that receives two table elements, | ||
7199 | and returns true | ||
7200 | when the first is less than the second | ||
7201 | (so that <code>not comp(a[i+1],a[i])</code> will be true after the sort). | ||
7202 | If <code>comp</code> is not given, | ||
7203 | then the standard Lua operator <code><</code> is used instead. | ||
7204 | |||
7205 | |||
7206 | <p> | ||
7207 | The sort algorithm is not stable; | ||
7208 | that is, elements considered equal by the given order | ||
7209 | may have their relative positions changed by the sort. | ||
7210 | |||
7211 | |||
7212 | |||
7213 | |||
7214 | |||
7215 | |||
7216 | |||
7217 | <h2>5.6 - <a name="5.6">Mathematical Functions</a></h2> | ||
7218 | |||
7219 | <p> | ||
7220 | This library is an interface to the standard C math library. | ||
7221 | It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>. | ||
7222 | |||
7223 | |||
7224 | <p> | ||
7225 | <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> | ||
7226 | |||
7227 | |||
7228 | <p> | ||
7229 | Returns the absolute value of <code>x</code>. | ||
7230 | |||
7231 | |||
7232 | |||
7233 | |||
7234 | <p> | ||
7235 | <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> | ||
7236 | |||
7237 | |||
7238 | <p> | ||
7239 | Returns the arc cosine of <code>x</code> (in radians). | ||
7240 | |||
7241 | |||
7242 | |||
7243 | |||
7244 | <p> | ||
7245 | <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> | ||
7246 | |||
7247 | |||
7248 | <p> | ||
7249 | Returns the arc sine of <code>x</code> (in radians). | ||
7250 | |||
7251 | |||
7252 | |||
7253 | |||
7254 | <p> | ||
7255 | <hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3> | ||
7256 | |||
7257 | |||
7258 | <p> | ||
7259 | Returns the arc tangent of <code>x</code> (in radians). | ||
7260 | |||
7261 | |||
7262 | |||
7263 | |||
7264 | <p> | ||
7265 | <hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3> | ||
7266 | |||
7267 | |||
7268 | <p> | ||
7269 | Returns the arc tangent of <code>y/x</code> (in radians), | ||
7270 | but uses the signs of both parameters to find the | ||
7271 | quadrant of the result. | ||
7272 | (It also handles correctly the case of <code>x</code> being zero.) | ||
7273 | |||
7274 | |||
7275 | |||
7276 | |||
7277 | <p> | ||
7278 | <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> | ||
7279 | |||
7280 | |||
7281 | <p> | ||
7282 | Returns the smallest integer larger than or equal to <code>x</code>. | ||
7283 | |||
7284 | |||
7285 | |||
7286 | |||
7287 | <p> | ||
7288 | <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> | ||
7289 | |||
7290 | |||
7291 | <p> | ||
7292 | Returns the cosine of <code>x</code> (assumed to be in radians). | ||
7293 | |||
7294 | |||
7295 | |||
7296 | |||
7297 | <p> | ||
7298 | <hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3> | ||
7299 | |||
7300 | |||
7301 | <p> | ||
7302 | Returns the hyperbolic cosine of <code>x</code>. | ||
7303 | |||
7304 | |||
7305 | |||
7306 | |||
7307 | <p> | ||
7308 | <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> | ||
7309 | |||
7310 | |||
7311 | <p> | ||
7312 | Returns the angle <code>x</code> (given in radians) in degrees. | ||
7313 | |||
7314 | |||
7315 | |||
7316 | |||
7317 | <p> | ||
7318 | <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> | ||
7319 | |||
7320 | |||
7321 | <p> | ||
7322 | Returns the value <em>e<sup>x</sup></em>. | ||
7323 | |||
7324 | |||
7325 | |||
7326 | |||
7327 | <p> | ||
7328 | <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> | ||
7329 | |||
7330 | |||
7331 | <p> | ||
7332 | Returns the largest integer smaller than or equal to <code>x</code>. | ||
7333 | |||
7334 | |||
7335 | |||
7336 | |||
7337 | <p> | ||
7338 | <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> | ||
7339 | |||
7340 | |||
7341 | <p> | ||
7342 | Returns the remainder of the division of <code>x</code> by <code>y</code> | ||
7343 | that rounds the quotient towards zero. | ||
7344 | |||
7345 | |||
7346 | |||
7347 | |||
7348 | <p> | ||
7349 | <hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3> | ||
7350 | |||
7351 | |||
7352 | <p> | ||
7353 | Returns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>, | ||
7354 | <code>e</code> is an integer and the absolute value of <code>m</code> is | ||
7355 | in the range <em>[0.5, 1)</em> | ||
7356 | (or zero when <code>x</code> is zero). | ||
7357 | |||
7358 | |||
7359 | |||
7360 | |||
7361 | <p> | ||
7362 | <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> | ||
7363 | |||
7364 | |||
7365 | <p> | ||
7366 | The value <code>HUGE_VAL</code>, | ||
7367 | a value larger than or equal to any other numerical value. | ||
7368 | |||
7369 | |||
7370 | |||
7371 | |||
7372 | <p> | ||
7373 | <hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3> | ||
7374 | |||
7375 | |||
7376 | <p> | ||
7377 | Returns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer). | ||
7378 | |||
7379 | |||
7380 | |||
7381 | |||
7382 | <p> | ||
7383 | <hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3> | ||
7384 | |||
7385 | |||
7386 | <p> | ||
7387 | Returns the natural logarithm of <code>x</code>. | ||
7388 | |||
7389 | |||
7390 | |||
7391 | |||
7392 | <p> | ||
7393 | <hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3> | ||
7394 | |||
7395 | |||
7396 | <p> | ||
7397 | Returns the base-10 logarithm of <code>x</code>. | ||
7398 | |||
7399 | |||
7400 | |||
7401 | |||
7402 | <p> | ||
7403 | <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> | ||
7404 | |||
7405 | |||
7406 | <p> | ||
7407 | Returns the maximum value among its arguments. | ||
7408 | |||
7409 | |||
7410 | |||
7411 | |||
7412 | <p> | ||
7413 | <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> | ||
7414 | |||
7415 | |||
7416 | <p> | ||
7417 | Returns the minimum value among its arguments. | ||
7418 | |||
7419 | |||
7420 | |||
7421 | |||
7422 | <p> | ||
7423 | <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> | ||
7424 | |||
7425 | |||
7426 | <p> | ||
7427 | Returns two numbers, | ||
7428 | the integral part of <code>x</code> and the fractional part of <code>x</code>. | ||
7429 | |||
7430 | |||
7431 | |||
7432 | |||
7433 | <p> | ||
7434 | <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> | ||
7435 | |||
7436 | |||
7437 | <p> | ||
7438 | The value of <em>pi</em>. | ||
7439 | |||
7440 | |||
7441 | |||
7442 | |||
7443 | <p> | ||
7444 | <hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3> | ||
7445 | |||
7446 | |||
7447 | <p> | ||
7448 | Returns <em>x<sup>y</sup></em>. | ||
7449 | (You can also use the expression <code>x^y</code> to compute this value.) | ||
7450 | |||
7451 | |||
7452 | |||
7453 | |||
7454 | <p> | ||
7455 | <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> | ||
7456 | |||
7457 | |||
7458 | <p> | ||
7459 | Returns the angle <code>x</code> (given in degrees) in radians. | ||
7460 | |||
7461 | |||
7462 | |||
7463 | |||
7464 | <p> | ||
7465 | <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> | ||
7466 | |||
7467 | |||
7468 | <p> | ||
7469 | This function is an interface to the simple | ||
7470 | pseudo-random generator function <code>rand</code> provided by ANSI C. | ||
7471 | (No guarantees can be given for its statistical properties.) | ||
7472 | |||
7473 | |||
7474 | <p> | ||
7475 | When called without arguments, | ||
7476 | returns a uniform pseudo-random real number | ||
7477 | in the range <em>[0,1)</em>. | ||
7478 | When called with an integer number <code>m</code>, | ||
7479 | <code>math.random</code> returns | ||
7480 | a uniform pseudo-random integer in the range <em>[1, m]</em>. | ||
7481 | When called with two integer numbers <code>m</code> and <code>n</code>, | ||
7482 | <code>math.random</code> returns a uniform pseudo-random | ||
7483 | integer in the range <em>[m, n]</em>. | ||
7484 | |||
7485 | |||
7486 | |||
7487 | |||
7488 | <p> | ||
7489 | <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> | ||
7490 | |||
7491 | |||
7492 | <p> | ||
7493 | Sets <code>x</code> as the "seed" | ||
7494 | for the pseudo-random generator: | ||
7495 | equal seeds produce equal sequences of numbers. | ||
7496 | |||
7497 | |||
7498 | |||
7499 | |||
7500 | <p> | ||
7501 | <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> | ||
7502 | |||
7503 | |||
7504 | <p> | ||
7505 | Returns the sine of <code>x</code> (assumed to be in radians). | ||
7506 | |||
7507 | |||
7508 | |||
7509 | |||
7510 | <p> | ||
7511 | <hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3> | ||
7512 | |||
7513 | |||
7514 | <p> | ||
7515 | Returns the hyperbolic sine of <code>x</code>. | ||
7516 | |||
7517 | |||
7518 | |||
7519 | |||
7520 | <p> | ||
7521 | <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> | ||
7522 | |||
7523 | |||
7524 | <p> | ||
7525 | Returns the square root of <code>x</code>. | ||
7526 | (You can also use the expression <code>x^0.5</code> to compute this value.) | ||
7527 | |||
7528 | |||
7529 | |||
7530 | |||
7531 | <p> | ||
7532 | <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> | ||
7533 | |||
7534 | |||
7535 | <p> | ||
7536 | Returns the tangent of <code>x</code> (assumed to be in radians). | ||
7537 | |||
7538 | |||
7539 | |||
7540 | |||
7541 | <p> | ||
7542 | <hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3> | ||
7543 | |||
7544 | |||
7545 | <p> | ||
7546 | Returns the hyperbolic tangent of <code>x</code>. | ||
7547 | |||
7548 | |||
7549 | |||
7550 | |||
7551 | |||
7552 | |||
7553 | |||
7554 | <h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2> | ||
7555 | |||
7556 | <p> | ||
7557 | The I/O library provides two different styles for file manipulation. | ||
7558 | The first one uses implicit file descriptors; | ||
7559 | that is, there are operations to set a default input file and a | ||
7560 | default output file, | ||
7561 | and all input/output operations are over these default files. | ||
7562 | The second style uses explicit file descriptors. | ||
7563 | |||
7564 | |||
7565 | <p> | ||
7566 | When using implicit file descriptors, | ||
7567 | all operations are supplied by table <a name="pdf-io"><code>io</code></a>. | ||
7568 | When using explicit file descriptors, | ||
7569 | the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor | ||
7570 | and then all operations are supplied as methods of the file descriptor. | ||
7571 | |||
7572 | |||
7573 | <p> | ||
7574 | The table <code>io</code> also provides | ||
7575 | three predefined file descriptors with their usual meanings from C: | ||
7576 | <a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. | ||
7577 | The I/O library never closes these files. | ||
7578 | |||
7579 | |||
7580 | <p> | ||
7581 | Unless otherwise stated, | ||
7582 | all I/O functions return <b>nil</b> on failure | ||
7583 | (plus an error message as a second result and | ||
7584 | a system-dependent error code as a third result) | ||
7585 | and some value different from <b>nil</b> on success. | ||
7586 | |||
7587 | |||
7588 | <p> | ||
7589 | <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> | ||
7590 | |||
7591 | |||
7592 | <p> | ||
7593 | Equivalent to <code>file:close()</code>. | ||
7594 | Without a <code>file</code>, closes the default output file. | ||
7595 | |||
7596 | |||
7597 | |||
7598 | |||
7599 | <p> | ||
7600 | <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> | ||
7601 | |||
7602 | |||
7603 | <p> | ||
7604 | Equivalent to <code>file:flush</code> over the default output file. | ||
7605 | |||
7606 | |||
7607 | |||
7608 | |||
7609 | <p> | ||
7610 | <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> | ||
7611 | |||
7612 | |||
7613 | <p> | ||
7614 | When called with a file name, it opens the named file (in text mode), | ||
7615 | and sets its handle as the default input file. | ||
7616 | When called with a file handle, | ||
7617 | it simply sets this file handle as the default input file. | ||
7618 | When called without parameters, | ||
7619 | it returns the current default input file. | ||
7620 | |||
7621 | |||
7622 | <p> | ||
7623 | In case of errors this function raises the error, | ||
7624 | instead of returning an error code. | ||
7625 | |||
7626 | |||
7627 | |||
7628 | |||
7629 | <p> | ||
7630 | <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3> | ||
7631 | |||
7632 | |||
7633 | <p> | ||
7634 | Opens the given file name in read mode | ||
7635 | and returns an iterator function that, | ||
7636 | each time it is called, | ||
7637 | returns a new line from the file. | ||
7638 | Therefore, the construction | ||
7639 | |||
7640 | <pre> | ||
7641 | for line in io.lines(filename) do <em>body</em> end | ||
7642 | </pre><p> | ||
7643 | will iterate over all lines of the file. | ||
7644 | When the iterator function detects the end of file, | ||
7645 | it returns <b>nil</b> (to finish the loop) and automatically closes the file. | ||
7646 | |||
7647 | |||
7648 | <p> | ||
7649 | The call <code>io.lines()</code> (with no file name) is equivalent | ||
7650 | to <code>io.input():lines()</code>; | ||
7651 | that is, it iterates over the lines of the default input file. | ||
7652 | In this case it does not close the file when the loop ends. | ||
7653 | |||
7654 | |||
7655 | |||
7656 | |||
7657 | <p> | ||
7658 | <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> | ||
7659 | |||
7660 | |||
7661 | <p> | ||
7662 | This function opens a file, | ||
7663 | in the mode specified in the string <code>mode</code>. | ||
7664 | It returns a new file handle, | ||
7665 | or, in case of errors, <b>nil</b> plus an error message. | ||
7666 | |||
7667 | |||
7668 | <p> | ||
7669 | The <code>mode</code> string can be any of the following: | ||
7670 | |||
7671 | <ul> | ||
7672 | <li><b>"r":</b> read mode (the default);</li> | ||
7673 | <li><b>"w":</b> write mode;</li> | ||
7674 | <li><b>"a":</b> append mode;</li> | ||
7675 | <li><b>"r+":</b> update mode, all previous data is preserved;</li> | ||
7676 | <li><b>"w+":</b> update mode, all previous data is erased;</li> | ||
7677 | <li><b>"a+":</b> append update mode, previous data is preserved, | ||
7678 | writing is only allowed at the end of file.</li> | ||
7679 | </ul><p> | ||
7680 | The <code>mode</code> string can also have a '<code>b</code>' at the end, | ||
7681 | which is needed in some systems to open the file in binary mode. | ||
7682 | This string is exactly what is used in the | ||
7683 | standard C function <code>fopen</code>. | ||
7684 | |||
7685 | |||
7686 | |||
7687 | |||
7688 | <p> | ||
7689 | <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> | ||
7690 | |||
7691 | |||
7692 | <p> | ||
7693 | Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. | ||
7694 | |||
7695 | |||
7696 | |||
7697 | |||
7698 | <p> | ||
7699 | <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> | ||
7700 | |||
7701 | |||
7702 | <p> | ||
7703 | Starts program <code>prog</code> in a separated process and returns | ||
7704 | a file handle that you can use to read data from this program | ||
7705 | (if <code>mode</code> is <code>"r"</code>, the default) | ||
7706 | or to write data to this program | ||
7707 | (if <code>mode</code> is <code>"w"</code>). | ||
7708 | |||
7709 | |||
7710 | <p> | ||
7711 | This function is system dependent and is not available | ||
7712 | on all platforms. | ||
7713 | |||
7714 | |||
7715 | |||
7716 | |||
7717 | <p> | ||
7718 | <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> | ||
7719 | |||
7720 | |||
7721 | <p> | ||
7722 | Equivalent to <code>io.input():read</code>. | ||
7723 | |||
7724 | |||
7725 | |||
7726 | |||
7727 | <p> | ||
7728 | <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> | ||
7729 | |||
7730 | |||
7731 | <p> | ||
7732 | Returns a handle for a temporary file. | ||
7733 | This file is opened in update mode | ||
7734 | and it is automatically removed when the program ends. | ||
7735 | |||
7736 | |||
7737 | |||
7738 | |||
7739 | <p> | ||
7740 | <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> | ||
7741 | |||
7742 | |||
7743 | <p> | ||
7744 | Checks whether <code>obj</code> is a valid file handle. | ||
7745 | Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, | ||
7746 | <code>"closed file"</code> if <code>obj</code> is a closed file handle, | ||
7747 | or <b>nil</b> if <code>obj</code> is not a file handle. | ||
7748 | |||
7749 | |||
7750 | |||
7751 | |||
7752 | <p> | ||
7753 | <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> | ||
7754 | |||
7755 | |||
7756 | <p> | ||
7757 | Equivalent to <code>io.output():write</code>. | ||
7758 | |||
7759 | |||
7760 | |||
7761 | |||
7762 | <p> | ||
7763 | <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> | ||
7764 | |||
7765 | |||
7766 | <p> | ||
7767 | Closes <code>file</code>. | ||
7768 | Note that files are automatically closed when | ||
7769 | their handles are garbage collected, | ||
7770 | but that takes an unpredictable amount of time to happen. | ||
7771 | |||
7772 | |||
7773 | |||
7774 | |||
7775 | <p> | ||
7776 | <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> | ||
7777 | |||
7778 | |||
7779 | <p> | ||
7780 | Saves any written data to <code>file</code>. | ||
7781 | |||
7782 | |||
7783 | |||
7784 | |||
7785 | <p> | ||
7786 | <hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3> | ||
7787 | |||
7788 | |||
7789 | <p> | ||
7790 | Returns an iterator function that, | ||
7791 | each time it is called, | ||
7792 | returns a new line from the file. | ||
7793 | Therefore, the construction | ||
7794 | |||
7795 | <pre> | ||
7796 | for line in file:lines() do <em>body</em> end | ||
7797 | </pre><p> | ||
7798 | will iterate over all lines of the file. | ||
7799 | (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file | ||
7800 | when the loop ends.) | ||
7801 | |||
7802 | |||
7803 | |||
7804 | |||
7805 | <p> | ||
7806 | <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> | ||
7807 | |||
7808 | |||
7809 | <p> | ||
7810 | Reads the file <code>file</code>, | ||
7811 | according to the given formats, which specify what to read. | ||
7812 | For each format, | ||
7813 | the function returns a string (or a number) with the characters read, | ||
7814 | or <b>nil</b> if it cannot read data with the specified format. | ||
7815 | When called without formats, | ||
7816 | it uses a default format that reads the entire next line | ||
7817 | (see below). | ||
7818 | |||
7819 | |||
7820 | <p> | ||
7821 | The available formats are | ||
7822 | |||
7823 | <ul> | ||
7824 | |||
7825 | <li><b>"*n":</b> | ||
7826 | reads a number; | ||
7827 | this is the only format that returns a number instead of a string. | ||
7828 | </li> | ||
7829 | |||
7830 | <li><b>"*a":</b> | ||
7831 | reads the whole file, starting at the current position. | ||
7832 | On end of file, it returns the empty string. | ||
7833 | </li> | ||
7834 | |||
7835 | <li><b>"*l":</b> | ||
7836 | reads the next line (skipping the end of line), | ||
7837 | returning <b>nil</b> on end of file. | ||
7838 | This is the default format. | ||
7839 | </li> | ||
7840 | |||
7841 | <li><b><em>number</em>:</b> | ||
7842 | reads a string with up to this number of characters, | ||
7843 | returning <b>nil</b> on end of file. | ||
7844 | If number is zero, | ||
7845 | it reads nothing and returns an empty string, | ||
7846 | or <b>nil</b> on end of file. | ||
7847 | </li> | ||
7848 | |||
7849 | </ul> | ||
7850 | |||
7851 | |||
7852 | |||
7853 | <p> | ||
7854 | <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3> | ||
7855 | |||
7856 | |||
7857 | <p> | ||
7858 | Sets and gets the file position, | ||
7859 | measured from the beginning of the file, | ||
7860 | to the position given by <code>offset</code> plus a base | ||
7861 | specified by the string <code>whence</code>, as follows: | ||
7862 | |||
7863 | <ul> | ||
7864 | <li><b>"set":</b> base is position 0 (beginning of the file);</li> | ||
7865 | <li><b>"cur":</b> base is current position;</li> | ||
7866 | <li><b>"end":</b> base is end of file;</li> | ||
7867 | </ul><p> | ||
7868 | In case of success, function <code>seek</code> returns the final file position, | ||
7869 | measured in bytes from the beginning of the file. | ||
7870 | If this function fails, it returns <b>nil</b>, | ||
7871 | plus a string describing the error. | ||
7872 | |||
7873 | |||
7874 | <p> | ||
7875 | The default value for <code>whence</code> is <code>"cur"</code>, | ||
7876 | and for <code>offset</code> is 0. | ||
7877 | Therefore, the call <code>file:seek()</code> returns the current | ||
7878 | file position, without changing it; | ||
7879 | the call <code>file:seek("set")</code> sets the position to the | ||
7880 | beginning of the file (and returns 0); | ||
7881 | and the call <code>file:seek("end")</code> sets the position to the | ||
7882 | end of the file, and returns its size. | ||
7883 | |||
7884 | |||
7885 | |||
7886 | |||
7887 | <p> | ||
7888 | <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> | ||
7889 | |||
7890 | |||
7891 | <p> | ||
7892 | Sets the buffering mode for an output file. | ||
7893 | There are three available modes: | ||
7894 | |||
7895 | <ul> | ||
7896 | |||
7897 | <li><b>"no":</b> | ||
7898 | no buffering; the result of any output operation appears immediately. | ||
7899 | </li> | ||
7900 | |||
7901 | <li><b>"full":</b> | ||
7902 | full buffering; output operation is performed only | ||
7903 | when the buffer is full (or when you explicitly <code>flush</code> the file | ||
7904 | (see <a href="#pdf-io.flush"><code>io.flush</code></a>)). | ||
7905 | </li> | ||
7906 | |||
7907 | <li><b>"line":</b> | ||
7908 | line buffering; output is buffered until a newline is output | ||
7909 | or there is any input from some special files | ||
7910 | (such as a terminal device). | ||
7911 | </li> | ||
7912 | |||
7913 | </ul><p> | ||
7914 | For the last two cases, <code>size</code> | ||
7915 | specifies the size of the buffer, in bytes. | ||
7916 | The default is an appropriate size. | ||
7917 | |||
7918 | |||
7919 | |||
7920 | |||
7921 | <p> | ||
7922 | <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> | ||
7923 | |||
7924 | |||
7925 | <p> | ||
7926 | Writes the value of each of its arguments to | ||
7927 | the <code>file</code>. | ||
7928 | The arguments must be strings or numbers. | ||
7929 | To write other values, | ||
7930 | use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. | ||
7931 | |||
7932 | |||
7933 | |||
7934 | |||
7935 | |||
7936 | |||
7937 | |||
7938 | <h2>5.8 - <a name="5.8">Operating System Facilities</a></h2> | ||
7939 | |||
7940 | <p> | ||
7941 | This library is implemented through table <a name="pdf-os"><code>os</code></a>. | ||
7942 | |||
7943 | |||
7944 | <p> | ||
7945 | <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> | ||
7946 | |||
7947 | |||
7948 | <p> | ||
7949 | Returns an approximation of the amount in seconds of CPU time | ||
7950 | used by the program. | ||
7951 | |||
7952 | |||
7953 | |||
7954 | |||
7955 | <p> | ||
7956 | <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> | ||
7957 | |||
7958 | |||
7959 | <p> | ||
7960 | Returns a string or a table containing date and time, | ||
7961 | formatted according to the given string <code>format</code>. | ||
7962 | |||
7963 | |||
7964 | <p> | ||
7965 | If the <code>time</code> argument is present, | ||
7966 | this is the time to be formatted | ||
7967 | (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). | ||
7968 | Otherwise, <code>date</code> formats the current time. | ||
7969 | |||
7970 | |||
7971 | <p> | ||
7972 | If <code>format</code> starts with '<code>!</code>', | ||
7973 | then the date is formatted in Coordinated Universal Time. | ||
7974 | After this optional character, | ||
7975 | if <code>format</code> is the string "<code>*t</code>", | ||
7976 | then <code>date</code> returns a table with the following fields: | ||
7977 | <code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), | ||
7978 | <code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), | ||
7979 | <code>wday</code> (weekday, Sunday is 1), | ||
7980 | <code>yday</code> (day of the year), | ||
7981 | and <code>isdst</code> (daylight saving flag, a boolean). | ||
7982 | |||
7983 | |||
7984 | <p> | ||
7985 | If <code>format</code> is not "<code>*t</code>", | ||
7986 | then <code>date</code> returns the date as a string, | ||
7987 | formatted according to the same rules as the C function <code>strftime</code>. | ||
7988 | |||
7989 | |||
7990 | <p> | ||
7991 | When called without arguments, | ||
7992 | <code>date</code> returns a reasonable date and time representation that depends on | ||
7993 | the host system and on the current locale | ||
7994 | (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). | ||
7995 | |||
7996 | |||
7997 | |||
7998 | |||
7999 | <p> | ||
8000 | <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> | ||
8001 | |||
8002 | |||
8003 | <p> | ||
8004 | Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. | ||
8005 | In POSIX, Windows, and some other systems, | ||
8006 | this value is exactly <code>t2</code><em>-</em><code>t1</code>. | ||
8007 | |||
8008 | |||
8009 | |||
8010 | |||
8011 | <p> | ||
8012 | <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> | ||
8013 | |||
8014 | |||
8015 | <p> | ||
8016 | This function is equivalent to the C function <code>system</code>. | ||
8017 | It passes <code>command</code> to be executed by an operating system shell. | ||
8018 | It returns a status code, which is system-dependent. | ||
8019 | If <code>command</code> is absent, then it returns nonzero if a shell is available | ||
8020 | and zero otherwise. | ||
8021 | |||
8022 | |||
8023 | |||
8024 | |||
8025 | <p> | ||
8026 | <hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3> | ||
8027 | |||
8028 | |||
8029 | <p> | ||
8030 | Calls the C function <code>exit</code>, | ||
8031 | with an optional <code>code</code>, | ||
8032 | to terminate the host program. | ||
8033 | The default value for <code>code</code> is the success code. | ||
8034 | |||
8035 | |||
8036 | |||
8037 | |||
8038 | <p> | ||
8039 | <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> | ||
8040 | |||
8041 | |||
8042 | <p> | ||
8043 | Returns the value of the process environment variable <code>varname</code>, | ||
8044 | or <b>nil</b> if the variable is not defined. | ||
8045 | |||
8046 | |||
8047 | |||
8048 | |||
8049 | <p> | ||
8050 | <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> | ||
8051 | |||
8052 | |||
8053 | <p> | ||
8054 | Deletes the file or directory with the given name. | ||
8055 | Directories must be empty to be removed. | ||
8056 | If this function fails, it returns <b>nil</b>, | ||
8057 | plus a string describing the error. | ||
8058 | |||
8059 | |||
8060 | |||
8061 | |||
8062 | <p> | ||
8063 | <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> | ||
8064 | |||
8065 | |||
8066 | <p> | ||
8067 | Renames file or directory named <code>oldname</code> to <code>newname</code>. | ||
8068 | If this function fails, it returns <b>nil</b>, | ||
8069 | plus a string describing the error. | ||
8070 | |||
8071 | |||
8072 | |||
8073 | |||
8074 | <p> | ||
8075 | <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> | ||
8076 | |||
8077 | |||
8078 | <p> | ||
8079 | Sets the current locale of the program. | ||
8080 | <code>locale</code> is a string specifying a locale; | ||
8081 | <code>category</code> is an optional string describing which category to change: | ||
8082 | <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, | ||
8083 | <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; | ||
8084 | the default category is <code>"all"</code>. | ||
8085 | The function returns the name of the new locale, | ||
8086 | or <b>nil</b> if the request cannot be honored. | ||
8087 | |||
8088 | |||
8089 | <p> | ||
8090 | If <code>locale</code> is the empty string, | ||
8091 | the current locale is set to an implementation-defined native locale. | ||
8092 | If <code>locale</code> is the string "<code>C</code>", | ||
8093 | the current locale is set to the standard C locale. | ||
8094 | |||
8095 | |||
8096 | <p> | ||
8097 | When called with <b>nil</b> as the first argument, | ||
8098 | this function only returns the name of the current locale | ||
8099 | for the given category. | ||
8100 | |||
8101 | |||
8102 | |||
8103 | |||
8104 | <p> | ||
8105 | <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> | ||
8106 | |||
8107 | |||
8108 | <p> | ||
8109 | Returns the current time when called without arguments, | ||
8110 | or a time representing the date and time specified by the given table. | ||
8111 | This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, | ||
8112 | and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> | ||
8113 | (for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function). | ||
8114 | |||
8115 | |||
8116 | <p> | ||
8117 | The returned value is a number, whose meaning depends on your system. | ||
8118 | In POSIX, Windows, and some other systems, this number counts the number | ||
8119 | of seconds since some given start time (the "epoch"). | ||
8120 | In other systems, the meaning is not specified, | ||
8121 | and the number returned by <code>time</code> can be used only as an argument to | ||
8122 | <code>date</code> and <code>difftime</code>. | ||
8123 | |||
8124 | |||
8125 | |||
8126 | |||
8127 | <p> | ||
8128 | <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> | ||
8129 | |||
8130 | |||
8131 | <p> | ||
8132 | Returns a string with a file name that can | ||
8133 | be used for a temporary file. | ||
8134 | The file must be explicitly opened before its use | ||
8135 | and explicitly removed when no longer needed. | ||
8136 | |||
8137 | |||
8138 | <p> | ||
8139 | On some systems (POSIX), | ||
8140 | this function also creates a file with that name, | ||
8141 | to avoid security risks. | ||
8142 | (Someone else might create the file with wrong permissions | ||
8143 | in the time between getting the name and creating the file.) | ||
8144 | You still have to open the file to use it | ||
8145 | and to remove it (even if you do not use it). | ||
8146 | |||
8147 | |||
8148 | <p> | ||
8149 | When possible, | ||
8150 | you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, | ||
8151 | which automatically removes the file when the program ends. | ||
8152 | |||
8153 | |||
8154 | |||
8155 | |||
8156 | |||
8157 | |||
8158 | |||
8159 | <h2>5.9 - <a name="5.9">The Debug Library</a></h2> | ||
8160 | |||
8161 | <p> | ||
8162 | This library provides | ||
8163 | the functionality of the debug interface to Lua programs. | ||
8164 | You should exert care when using this library. | ||
8165 | The functions provided here should be used exclusively for debugging | ||
8166 | and similar tasks, such as profiling. | ||
8167 | Please resist the temptation to use them as a | ||
8168 | usual programming tool: | ||
8169 | they can be very slow. | ||
8170 | Moreover, several of these functions | ||
8171 | violate some assumptions about Lua code | ||
8172 | (e.g., that variables local to a function | ||
8173 | cannot be accessed from outside or | ||
8174 | that userdata metatables cannot be changed by Lua code) | ||
8175 | and therefore can compromise otherwise secure code. | ||
8176 | |||
8177 | |||
8178 | <p> | ||
8179 | All functions in this library are provided | ||
8180 | inside the <a name="pdf-debug"><code>debug</code></a> table. | ||
8181 | All functions that operate over a thread | ||
8182 | have an optional first argument which is the | ||
8183 | thread to operate over. | ||
8184 | The default is always the current thread. | ||
8185 | |||
8186 | |||
8187 | <p> | ||
8188 | <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> | ||
8189 | |||
8190 | |||
8191 | <p> | ||
8192 | Enters an interactive mode with the user, | ||
8193 | running each string that the user enters. | ||
8194 | Using simple commands and other debug facilities, | ||
8195 | the user can inspect global and local variables, | ||
8196 | change their values, evaluate expressions, and so on. | ||
8197 | A line containing only the word <code>cont</code> finishes this function, | ||
8198 | so that the caller continues its execution. | ||
8199 | |||
8200 | |||
8201 | <p> | ||
8202 | Note that commands for <code>debug.debug</code> are not lexically nested | ||
8203 | within any function, and so have no direct access to local variables. | ||
8204 | |||
8205 | |||
8206 | |||
8207 | |||
8208 | <p> | ||
8209 | <hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3> | ||
8210 | Returns the environment of object <code>o</code>. | ||
8211 | |||
8212 | |||
8213 | |||
8214 | |||
8215 | <p> | ||
8216 | <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> | ||
8217 | |||
8218 | |||
8219 | <p> | ||
8220 | Returns the current hook settings of the thread, as three values: | ||
8221 | the current hook function, the current hook mask, | ||
8222 | and the current hook count | ||
8223 | (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). | ||
8224 | |||
8225 | |||
8226 | |||
8227 | |||
8228 | <p> | ||
8229 | <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3> | ||
8230 | |||
8231 | |||
8232 | <p> | ||
8233 | Returns a table with information about a function. | ||
8234 | You can give the function directly, | ||
8235 | or you can give a number as the value of <code>function</code>, | ||
8236 | which means the function running at level <code>function</code> of the call stack | ||
8237 | of the given thread: | ||
8238 | level 0 is the current function (<code>getinfo</code> itself); | ||
8239 | level 1 is the function that called <code>getinfo</code>; | ||
8240 | and so on. | ||
8241 | If <code>function</code> is a number larger than the number of active functions, | ||
8242 | then <code>getinfo</code> returns <b>nil</b>. | ||
8243 | |||
8244 | |||
8245 | <p> | ||
8246 | The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, | ||
8247 | with the string <code>what</code> describing which fields to fill in. | ||
8248 | The default for <code>what</code> is to get all information available, | ||
8249 | except the table of valid lines. | ||
8250 | If present, | ||
8251 | the option '<code>f</code>' | ||
8252 | adds a field named <code>func</code> with the function itself. | ||
8253 | If present, | ||
8254 | the option '<code>L</code>' | ||
8255 | adds a field named <code>activelines</code> with the table of | ||
8256 | valid lines. | ||
8257 | |||
8258 | |||
8259 | <p> | ||
8260 | For instance, the expression <code>debug.getinfo(1,"n").name</code> returns | ||
8261 | a table with a name for the current function, | ||
8262 | if a reasonable name can be found, | ||
8263 | and the expression <code>debug.getinfo(print)</code> | ||
8264 | returns a table with all available information | ||
8265 | about the <a href="#pdf-print"><code>print</code></a> function. | ||
8266 | |||
8267 | |||
8268 | |||
8269 | |||
8270 | <p> | ||
8271 | <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3> | ||
8272 | |||
8273 | |||
8274 | <p> | ||
8275 | This function returns the name and the value of the local variable | ||
8276 | with index <code>local</code> of the function at level <code>level</code> of the stack. | ||
8277 | (The first parameter or local variable has index 1, and so on, | ||
8278 | until the last active local variable.) | ||
8279 | The function returns <b>nil</b> if there is no local | ||
8280 | variable with the given index, | ||
8281 | and raises an error when called with a <code>level</code> out of range. | ||
8282 | (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) | ||
8283 | |||
8284 | |||
8285 | <p> | ||
8286 | Variable names starting with '<code>(</code>' (open parentheses) | ||
8287 | represent internal variables | ||
8288 | (loop control variables, temporaries, and C function locals). | ||
8289 | |||
8290 | |||
8291 | |||
8292 | |||
8293 | <p> | ||
8294 | <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3> | ||
8295 | |||
8296 | |||
8297 | <p> | ||
8298 | Returns the metatable of the given <code>object</code> | ||
8299 | or <b>nil</b> if it does not have a metatable. | ||
8300 | |||
8301 | |||
8302 | |||
8303 | |||
8304 | <p> | ||
8305 | <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> | ||
8306 | |||
8307 | |||
8308 | <p> | ||
8309 | Returns the registry table (see <a href="#3.5">§3.5</a>). | ||
8310 | |||
8311 | |||
8312 | |||
8313 | |||
8314 | <p> | ||
8315 | <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3> | ||
8316 | |||
8317 | |||
8318 | <p> | ||
8319 | This function returns the name and the value of the upvalue | ||
8320 | with index <code>up</code> of the function <code>func</code>. | ||
8321 | The function returns <b>nil</b> if there is no upvalue with the given index. | ||
8322 | |||
8323 | |||
8324 | |||
8325 | |||
8326 | <p> | ||
8327 | <hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3> | ||
8328 | |||
8329 | |||
8330 | <p> | ||
8331 | Sets the environment of the given <code>object</code> to the given <code>table</code>. | ||
8332 | Returns <code>object</code>. | ||
8333 | |||
8334 | |||
8335 | |||
8336 | |||
8337 | <p> | ||
8338 | <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> | ||
8339 | |||
8340 | |||
8341 | <p> | ||
8342 | Sets the given function as a hook. | ||
8343 | The string <code>mask</code> and the number <code>count</code> describe | ||
8344 | when the hook will be called. | ||
8345 | The string mask may have the following characters, | ||
8346 | with the given meaning: | ||
8347 | |||
8348 | <ul> | ||
8349 | <li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li> | ||
8350 | <li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li> | ||
8351 | <li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li> | ||
8352 | </ul><p> | ||
8353 | With a <code>count</code> different from zero, | ||
8354 | the hook is called after every <code>count</code> instructions. | ||
8355 | |||
8356 | |||
8357 | <p> | ||
8358 | When called without arguments, | ||
8359 | <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. | ||
8360 | |||
8361 | |||
8362 | <p> | ||
8363 | When the hook is called, its first parameter is a string | ||
8364 | describing the event that has triggered its call: | ||
8365 | <code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>, | ||
8366 | when simulating a return from a tail call), | ||
8367 | <code>"line"</code>, and <code>"count"</code>. | ||
8368 | For line events, | ||
8369 | the hook also gets the new line number as its second parameter. | ||
8370 | Inside a hook, | ||
8371 | you can call <code>getinfo</code> with level 2 to get more information about | ||
8372 | the running function | ||
8373 | (level 0 is the <code>getinfo</code> function, | ||
8374 | and level 1 is the hook function), | ||
8375 | unless the event is <code>"tail return"</code>. | ||
8376 | In this case, Lua is only simulating the return, | ||
8377 | and a call to <code>getinfo</code> will return invalid data. | ||
8378 | |||
8379 | |||
8380 | |||
8381 | |||
8382 | <p> | ||
8383 | <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> | ||
8384 | |||
8385 | |||
8386 | <p> | ||
8387 | This function assigns the value <code>value</code> to the local variable | ||
8388 | with index <code>local</code> of the function at level <code>level</code> of the stack. | ||
8389 | The function returns <b>nil</b> if there is no local | ||
8390 | variable with the given index, | ||
8391 | and raises an error when called with a <code>level</code> out of range. | ||
8392 | (You can call <code>getinfo</code> to check whether the level is valid.) | ||
8393 | Otherwise, it returns the name of the local variable. | ||
8394 | |||
8395 | |||
8396 | |||
8397 | |||
8398 | <p> | ||
8399 | <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3> | ||
8400 | |||
8401 | |||
8402 | <p> | ||
8403 | Sets the metatable for the given <code>object</code> to the given <code>table</code> | ||
8404 | (which can be <b>nil</b>). | ||
8405 | |||
8406 | |||
8407 | |||
8408 | |||
8409 | <p> | ||
8410 | <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3> | ||
8411 | |||
8412 | |||
8413 | <p> | ||
8414 | This function assigns the value <code>value</code> to the upvalue | ||
8415 | with index <code>up</code> of the function <code>func</code>. | ||
8416 | The function returns <b>nil</b> if there is no upvalue | ||
8417 | with the given index. | ||
8418 | Otherwise, it returns the name of the upvalue. | ||
8419 | |||
8420 | |||
8421 | |||
8422 | |||
8423 | <p> | ||
8424 | <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3> | ||
8425 | |||
8426 | |||
8427 | <p> | ||
8428 | Returns a string with a traceback of the call stack. | ||
8429 | An optional <code>message</code> string is appended | ||
8430 | at the beginning of the traceback. | ||
8431 | An optional <code>level</code> number tells at which level | ||
8432 | to start the traceback | ||
8433 | (default is 1, the function calling <code>traceback</code>). | ||
8434 | |||
8435 | |||
8436 | |||
8437 | |||
8438 | |||
8439 | |||
8440 | |||
8441 | <h1>6 - <a name="6">Lua Stand-alone</a></h1> | ||
8442 | |||
8443 | <p> | ||
8444 | Although Lua has been designed as an extension language, | ||
8445 | to be embedded in a host C program, | ||
8446 | it is also frequently used as a stand-alone language. | ||
8447 | An interpreter for Lua as a stand-alone language, | ||
8448 | called simply <code>lua</code>, | ||
8449 | is provided with the standard distribution. | ||
8450 | The stand-alone interpreter includes | ||
8451 | all standard libraries, including the debug library. | ||
8452 | Its usage is: | ||
8453 | |||
8454 | <pre> | ||
8455 | lua [options] [script [args]] | ||
8456 | </pre><p> | ||
8457 | The options are: | ||
8458 | |||
8459 | <ul> | ||
8460 | <li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li> | ||
8461 | <li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li> | ||
8462 | <li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li> | ||
8463 | <li><b><code>-v</code>:</b> prints version information;</li> | ||
8464 | <li><b><code>--</code>:</b> stops handling options;</li> | ||
8465 | <li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li> | ||
8466 | </ul><p> | ||
8467 | After handling its options, <code>lua</code> runs the given <em>script</em>, | ||
8468 | passing to it the given <em>args</em> as string arguments. | ||
8469 | When called without arguments, | ||
8470 | <code>lua</code> behaves as <code>lua -v -i</code> | ||
8471 | when the standard input (<code>stdin</code>) is a terminal, | ||
8472 | and as <code>lua -</code> otherwise. | ||
8473 | |||
8474 | |||
8475 | <p> | ||
8476 | Before running any argument, | ||
8477 | the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>. | ||
8478 | If its format is <code>@<em>filename</em></code>, | ||
8479 | then <code>lua</code> executes the file. | ||
8480 | Otherwise, <code>lua</code> executes the string itself. | ||
8481 | |||
8482 | |||
8483 | <p> | ||
8484 | All options are handled in order, except <code>-i</code>. | ||
8485 | For instance, an invocation like | ||
8486 | |||
8487 | <pre> | ||
8488 | $ lua -e'a=1' -e 'print(a)' script.lua | ||
8489 | </pre><p> | ||
8490 | will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'), | ||
8491 | and finally run the file <code>script.lua</code> with no arguments. | ||
8492 | (Here <code>$</code> is the shell prompt. Your prompt may be different.) | ||
8493 | |||
8494 | |||
8495 | <p> | ||
8496 | Before starting to run the script, | ||
8497 | <code>lua</code> collects all arguments in the command line | ||
8498 | in a global table called <code>arg</code>. | ||
8499 | The script name is stored at index 0, | ||
8500 | the first argument after the script name goes to index 1, | ||
8501 | and so on. | ||
8502 | Any arguments before the script name | ||
8503 | (that is, the interpreter name plus the options) | ||
8504 | go to negative indices. | ||
8505 | For instance, in the call | ||
8506 | |||
8507 | <pre> | ||
8508 | $ lua -la b.lua t1 t2 | ||
8509 | </pre><p> | ||
8510 | the interpreter first runs the file <code>a.lua</code>, | ||
8511 | then creates a table | ||
8512 | |||
8513 | <pre> | ||
8514 | arg = { [-2] = "lua", [-1] = "-la", | ||
8515 | [0] = "b.lua", | ||
8516 | [1] = "t1", [2] = "t2" } | ||
8517 | </pre><p> | ||
8518 | and finally runs the file <code>b.lua</code>. | ||
8519 | The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ··· | ||
8520 | as arguments; | ||
8521 | it can also access these arguments with the vararg expression '<code>...</code>'. | ||
8522 | |||
8523 | |||
8524 | <p> | ||
8525 | In interactive mode, | ||
8526 | if you write an incomplete statement, | ||
8527 | the interpreter waits for its completion | ||
8528 | by issuing a different prompt. | ||
8529 | |||
8530 | |||
8531 | <p> | ||
8532 | If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, | ||
8533 | then its value is used as the prompt. | ||
8534 | Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, | ||
8535 | its value is used as the secondary prompt | ||
8536 | (issued during incomplete statements). | ||
8537 | Therefore, both prompts can be changed directly on the command line | ||
8538 | or in any Lua programs by assigning to <code>_PROMPT</code>. | ||
8539 | See the next example: | ||
8540 | |||
8541 | <pre> | ||
8542 | $ lua -e"_PROMPT='myprompt> '" -i | ||
8543 | </pre><p> | ||
8544 | (The outer pair of quotes is for the shell, | ||
8545 | the inner pair is for Lua.) | ||
8546 | Note the use of <code>-i</code> to enter interactive mode; | ||
8547 | otherwise, | ||
8548 | the program would just end silently | ||
8549 | right after the assignment to <code>_PROMPT</code>. | ||
8550 | |||
8551 | |||
8552 | <p> | ||
8553 | To allow the use of Lua as a | ||
8554 | script interpreter in Unix systems, | ||
8555 | the stand-alone interpreter skips | ||
8556 | the first line of a chunk if it starts with <code>#</code>. | ||
8557 | Therefore, Lua scripts can be made into executable programs | ||
8558 | by using <code>chmod +x</code> and the <code>#!</code> form, | ||
8559 | as in | ||
8560 | |||
8561 | <pre> | ||
8562 | #!/usr/local/bin/lua | ||
8563 | </pre><p> | ||
8564 | (Of course, | ||
8565 | the location of the Lua interpreter may be different in your machine. | ||
8566 | If <code>lua</code> is in your <code>PATH</code>, | ||
8567 | then | ||
8568 | |||
8569 | <pre> | ||
8570 | #!/usr/bin/env lua | ||
8571 | </pre><p> | ||
8572 | is a more portable solution.) | ||
8573 | |||
8574 | |||
8575 | |||
8576 | <h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1> | ||
8577 | |||
8578 | <p> | ||
8579 | Here we list the incompatibilities that you may find when moving a program | ||
8580 | from Lua 5.0 to Lua 5.1. | ||
8581 | You can avoid most of the incompatibilities compiling Lua with | ||
8582 | appropriate options (see file <code>luaconf.h</code>). | ||
8583 | However, | ||
8584 | all these compatibility options will be removed in the next version of Lua. | ||
8585 | |||
8586 | |||
8587 | |||
8588 | <h2>7.1 - <a name="7.1">Changes in the Language</a></h2> | ||
8589 | <ul> | ||
8590 | |||
8591 | <li> | ||
8592 | The vararg system changed from the pseudo-argument <code>arg</code> with a | ||
8593 | table with the extra arguments to the vararg expression. | ||
8594 | (See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) | ||
8595 | </li> | ||
8596 | |||
8597 | <li> | ||
8598 | There was a subtle change in the scope of the implicit | ||
8599 | variables of the <b>for</b> statement and for the <b>repeat</b> statement. | ||
8600 | </li> | ||
8601 | |||
8602 | <li> | ||
8603 | The long string/long comment syntax (<code>[[<em>string</em>]]</code>) | ||
8604 | does not allow nesting. | ||
8605 | You can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases. | ||
8606 | (See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) | ||
8607 | </li> | ||
8608 | |||
8609 | </ul> | ||
8610 | |||
8611 | |||
8612 | |||
8613 | |||
8614 | <h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2> | ||
8615 | <ul> | ||
8616 | |||
8617 | <li> | ||
8618 | Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. | ||
8619 | (See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.) | ||
8620 | </li> | ||
8621 | |||
8622 | <li> | ||
8623 | When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its | ||
8624 | third argument, | ||
8625 | whenever this function returns <b>nil</b> or <b>false</b> the | ||
8626 | replacement string is the whole match, | ||
8627 | instead of the empty string. | ||
8628 | </li> | ||
8629 | |||
8630 | <li> | ||
8631 | Function <code>table.setn</code> was deprecated. | ||
8632 | Function <code>table.getn</code> corresponds | ||
8633 | to the new length operator (<code>#</code>); | ||
8634 | use the operator instead of the function. | ||
8635 | (See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.) | ||
8636 | </li> | ||
8637 | |||
8638 | <li> | ||
8639 | Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>. | ||
8640 | (See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.) | ||
8641 | </li> | ||
8642 | |||
8643 | <li> | ||
8644 | Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>. | ||
8645 | (See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.) | ||
8646 | </li> | ||
8647 | |||
8648 | <li> | ||
8649 | Functions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated. | ||
8650 | You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead. | ||
8651 | </li> | ||
8652 | |||
8653 | <li> | ||
8654 | There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to | ||
8655 | the new module system. | ||
8656 | However, the new behavior is mostly compatible with the old, | ||
8657 | but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead | ||
8658 | of from <code>LUA_PATH</code>. | ||
8659 | </li> | ||
8660 | |||
8661 | <li> | ||
8662 | Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments. | ||
8663 | Function <code>gcinfo</code> is deprecated; | ||
8664 | use <code>collectgarbage("count")</code> instead. | ||
8665 | </li> | ||
8666 | |||
8667 | </ul> | ||
8668 | |||
8669 | |||
8670 | |||
8671 | |||
8672 | <h2>7.3 - <a name="7.3">Changes in the API</a></h2> | ||
8673 | <ul> | ||
8674 | |||
8675 | <li> | ||
8676 | The <code>luaopen_*</code> functions (to open libraries) | ||
8677 | cannot be called directly, | ||
8678 | like a regular C function. | ||
8679 | They must be called through Lua, | ||
8680 | like a Lua function. | ||
8681 | </li> | ||
8682 | |||
8683 | <li> | ||
8684 | Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to | ||
8685 | allow the user to set a memory-allocation function. | ||
8686 | You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to | ||
8687 | create a state with a standard allocation function | ||
8688 | (based on <code>realloc</code>). | ||
8689 | </li> | ||
8690 | |||
8691 | <li> | ||
8692 | Functions <code>luaL_getn</code> and <code>luaL_setn</code> | ||
8693 | (from the auxiliary library) are deprecated. | ||
8694 | Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code> | ||
8695 | and nothing instead of <code>luaL_setn</code>. | ||
8696 | </li> | ||
8697 | |||
8698 | <li> | ||
8699 | Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>. | ||
8700 | </li> | ||
8701 | |||
8702 | <li> | ||
8703 | Function <code>luaL_checkudata</code> now throws an error when the given value | ||
8704 | is not a userdata of the expected type. | ||
8705 | (In Lua 5.0 it returned <code>NULL</code>.) | ||
8706 | </li> | ||
8707 | |||
8708 | </ul> | ||
8709 | |||
8710 | |||
8711 | |||
8712 | |||
8713 | <h1>8 - <a name="8">The Complete Syntax of Lua</a></h1> | ||
8714 | |||
8715 | <p> | ||
8716 | Here is the complete syntax of Lua in extended BNF. | ||
8717 | (It does not describe operator precedences.) | ||
8718 | |||
8719 | |||
8720 | |||
8721 | |||
8722 | <pre> | ||
8723 | |||
8724 | chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]] | ||
8725 | |||
8726 | block ::= chunk | ||
8727 | |||
8728 | stat ::= varlist `<b>=</b>´ explist | | ||
8729 | functioncall | | ||
8730 | <b>do</b> block <b>end</b> | | ||
8731 | <b>while</b> exp <b>do</b> block <b>end</b> | | ||
8732 | <b>repeat</b> block <b>until</b> exp | | ||
8733 | <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | | ||
8734 | <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | | ||
8735 | <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | | ||
8736 | <b>function</b> funcname funcbody | | ||
8737 | <b>local</b> <b>function</b> Name funcbody | | ||
8738 | <b>local</b> namelist [`<b>=</b>´ explist] | ||
8739 | |||
8740 | laststat ::= <b>return</b> [explist] | <b>break</b> | ||
8741 | |||
8742 | funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] | ||
8743 | |||
8744 | varlist ::= var {`<b>,</b>´ var} | ||
8745 | |||
8746 | var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name | ||
8747 | |||
8748 | namelist ::= Name {`<b>,</b>´ Name} | ||
8749 | |||
8750 | explist ::= {exp `<b>,</b>´} exp | ||
8751 | |||
8752 | exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function | | ||
8753 | prefixexp | tableconstructor | exp binop exp | unop exp | ||
8754 | |||
8755 | prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ | ||
8756 | |||
8757 | functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args | ||
8758 | |||
8759 | args ::= `<b>(</b>´ [explist] `<b>)</b>´ | tableconstructor | String | ||
8760 | |||
8761 | function ::= <b>function</b> funcbody | ||
8762 | |||
8763 | funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> | ||
8764 | |||
8765 | parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ | ||
8766 | |||
8767 | tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ | ||
8768 | |||
8769 | fieldlist ::= field {fieldsep field} [fieldsep] | ||
8770 | |||
8771 | field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp | ||
8772 | |||
8773 | fieldsep ::= `<b>,</b>´ | `<b>;</b>´ | ||
8774 | |||
8775 | binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ | | ||
8776 | `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ | | ||
8777 | <b>and</b> | <b>or</b> | ||
8778 | |||
8779 | unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´ | ||
8780 | |||
8781 | </pre> | ||
8782 | |||
8783 | <p> | ||
8784 | |||
8785 | |||
8786 | |||
8787 | |||
8788 | |||
8789 | |||
8790 | |||
8791 | <HR> | ||
8792 | <SMALL> | ||
8793 | Last update: | ||
8794 | Mon Aug 18 13:25:46 BRT 2008 | ||
8795 | </SMALL> | ||
8796 | <!-- | ||
8797 | Last change: revised for Lua 5.1.4 | ||
8798 | --> | ||
8799 | |||
8800 | </body></html> | ||
8801 | |||