1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
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">
15 <a href=
"http://www.lua.org/"><img src=
"logo.gif" alt=
"" border=
"0"></a>
16 Lua
5.1 Reference Manual
19 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
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>.
29 <a href=
"contents.html#contents">contents
</A>
31 <a href=
"contents.html#index">index
</A>
33 <!-- ====================================================================== -->
36 <!-- $Id: manual.of,v 1.48 2008/08/18 15:24:20 roberto Exp $ -->
41 <h1>1 -
<a name=
"1">Introduction
</a></h1>
44 Lua is an extension programming language designed to support
45 general procedural programming with data description
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++).
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.
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>.
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>.
87 <h1>2 -
<a name=
"2">The Language
</a></h1>
90 This section describes the lexis, the syntax, and the semantics of Lua.
92 this section describes
93 which tokens are valid,
94 how they can be combined,
95 and what their combinations mean.
99 The language constructs will be explained using the usual extended BNF notation,
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.
111 <h2>2.1 -
<a name=
"2.1">Lexical Conventions
</a></h2>
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.
127 The following
<em>keywords
</em> are reserved
128 and cannot be used as names:
132 and break do else elseif
133 end false for function if
135 repeat return then true until while
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.
148 The following strings denote other tokens:
152 == ~=
<=
>=
< > =
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>'.
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>,
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.
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:
213 a = '\
97lo\
10\
04923"'
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
229 3 3.0 3.1416 314.16e-2 0.31416E1
0xff 0x56
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.
246 <h2>2.2 -
<a name=
"2.2">Values and Types
</a></h2>
249 Lua is a
<em>dynamically typed language
</em>.
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.
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.
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.
281 strings can contain any
8-bit character,
282 including embedded zeros ('
<code>\
0</code>') (see
<a href=
"#2.1">§2.1</a>).
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>).
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.
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.
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>).
331 the value of a table field can be of any type (except
<b>nil
</b>).
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>).
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.
348 The library function
<a href=
"#pdf-type"><code>type
</code></a> returns a string describing the type
353 <h3>2.2.1 -
<a name=
"2.2.1">Coercion
</a></h3>
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>).
372 <h2>2.3 -
<a name=
"2.3">Variables
</a></h2>
375 Variables are places that store values.
377 There are three kinds of variables in Lua:
378 global variables, local variables, and table fields.
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):
389 Name denotes identifiers, as defined in
<a href=
"#2.1">§2.1</a>.
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>).
401 Before the first assignment to a variable, its value is
<b>nil
</b>.
405 Square brackets are used to index a table:
408 var ::= prefixexp `
<b>[
</b>´ exp `
<b>]
</b>´
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.)
421 The syntax
<code>var.Name
</code> is just syntactic sugar for
422 <code>var["Name"]
</code>:
425 var ::= prefixexp `
<b>.
</b>´ Name
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>.
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>).)
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
451 gettable_event(_env, "x")
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.)
464 <h2>2.4 -
<a name=
"2.4">Statements
</a></h2>
467 Lua supports an almost conventional set of statements,
468 similar to those in Pascal or C.
470 assignments, control structures, function calls,
471 and variable declarations.
475 <h3>2.4.1 -
<a name=
"2.4.1">Chunks
</a></h3>
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:
484 chunk ::= {stat [`
<b>;
</b>´]}
486 There are no empty statements and thus '
<code>;;
</code>' is not legal.
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.
498 A chunk can be stored in a file or in a string inside the host program.
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.
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.
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:
525 A block can be explicitly delimited to produce a single statement:
528 stat ::=
<b>do
</b> block
<b>end
</b>
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>).
540 <h3>2.4.3 -
<a name=
"2.4.3">Assignment
</a></h3>
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:
550 stat ::= varlist `
<b>=
</b>´ explist
551 varlist ::= var {`
<b>,
</b>´ var}
552 explist ::= exp {`
<b>,
</b>´ exp}
554 Expressions are discussed in
<a href=
"#2.5">§2.5</a>.
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>).
572 The assignment statement first evaluates all its expressions
573 and only then are the assignments performed.
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.
588 exchanges the values of
<code>x
</code> and
<code>y
</code>,
594 cyclically permutes the values of
<code>x
</code>,
<code>y
</code>, and
<code>z
</code>.
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.)
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
615 settable_event(_env, "x", val)
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.)
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
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>
638 Lua also has a
<b>for
</b> statement, in two flavors (see
<a href=
"#2.4.5">§2.4.5</a>).
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).
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.
658 The
<b>return
</b> statement is used to return values
659 from a function or a chunk (which is just a function).
661 Functions and chunks can return more than one value,
662 and so the syntax for the
<b>return
</b> statement is
665 stat ::=
<b>return
</b> [explist]
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:
675 stat ::=
<b>break
</b>
677 A
<b>break
</b> ends the innermost enclosing loop.
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
685 then an explicit inner block can be used,
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.
695 <h3>2.4.5 -
<a name=
"2.4.5">For Statement
</a></h3>
699 The
<b>for
</b> statement has two forms:
700 one numeric and one generic.
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:
709 stat ::=
<b>for
</b> Name `
<b>=
</b>´ exp `
<b>,
</b>´ exp [`
<b>,
</b>´ exp]
<b>do
</b> block
<b>end
</b>
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
714 More precisely, a
<b>for
</b> statement like
717 for v =
<em>e1
</em>,
<em>e2
</em>,
<em>e3
</em> do
<em>block
</em> end
719 is equivalent to the code:
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>
728 <em>var
</em> =
<em>var
</em> +
<em>step
</em>
737 All three control expressions are evaluated only once,
738 before the loop starts.
739 They must all result in numbers.
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.
748 If the third expression (the step) is absent,
749 then a step of
1 is used.
753 You can use
<b>break
</b> to exit a
<b>for
</b> loop.
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.
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:
773 stat ::=
<b>for
</b> namelist
<b>in
</b> explist
<b>do
</b> block
<b>end
</b>
774 namelist ::= Name {`
<b>,
</b>´ Name}
776 A
<b>for
</b> statement like
779 for
<em>var_1
</em>,
···,
<em>var_n
</em> in
<em>explist
</em> do
<em>block
</em> end
781 is equivalent to the code:
785 local
<em>f
</em>,
<em>s
</em>,
<em>var
</em> =
<em>explist
</em>
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
799 <code><em>explist
</em></code> is evaluated only once.
800 Its results are an
<em>iterator
</em> function,
802 and an initial value for the first
<em>iterator variable
</em>.
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.
811 You can use
<b>break
</b> to exit a
<b>for
</b> loop.
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.
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:
831 stat ::= functioncall
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>.
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:
845 stat ::=
<b>local
</b> namelist [`
<b>=
</b>´ explist]
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>.
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.
859 The visibility rules for local variables are explained in
<a href=
"#2.6">§2.6</a>.
867 <h2>2.5 -
<a name=
"2.5">Expressions
</a></h2>
870 The basic expressions in Lua are the following:
874 exp ::=
<b>nil
</b> |
<b>false
</b> |
<b>true
</b>
878 exp ::= tableconstructor
879 exp ::= `
<b>...
</b>´
880 exp ::= exp binop exp
882 prefixexp ::= var | functioncall | `
<b>(
</b>´ exp `
<b>)
</b>´
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>.
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>.
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>).
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.
922 Here are some examples:
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)
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
944 Any expression enclosed in parentheses always results in only one value.
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.)
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>.
967 a % b == a - math.floor(a/b)*b
969 That is, it is the remainder of a division that rounds
970 the quotient towards minus infinity.
976 <h3>2.5.2 -
<a name=
"2.5.2">Relational Operators
</a></h3><p>
977 The relational operators in Lua are
980 == ~=
< > <=
>=
982 These operators always result in
<b>false
</b> or
<b>true
</b>.
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.
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>).
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
1012 The operator
<code>~=
</code> is exactly the negation of equality (
<code>==
</code>).
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>.
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.
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;
1047 the second operand is evaluated only if necessary.
1048 Here are some examples:
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
1061 <code>--
></code> indicates the result of the preceding expression.)
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>).
1078 <h3>2.5.5 -
<a name=
"2.5.5">The Length Operator
</a></h3>
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).
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
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:
1113 < > <=
>= ~= ==
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.
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
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>´
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,
1152 Fields in the other formats do not affect this counting.
1156 a = { [f(
1)] = g; "x", "y"; x =
1, f(x), [
30] =
23;
45 }
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
1169 t[
4] =
45 --
4th exp
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>).
1180 enclose the function call or the vararg expression
1181 in parentheses (see
<a href=
"#2.5">§2.5</a>).
1185 The field list can have an optional trailing separator,
1186 as a convenience for machine-generated code.
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:
1196 functioncall ::= prefixexp args
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>).
1213 functioncall ::= prefixexp `
<b>:
</b>´ Name args
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.
1222 Arguments have the following syntax:
1225 args ::= `
<b>(
</b>´ [explist] `
<b>)
</b>´
1226 args ::= tableconstructor
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.
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.
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>.
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>):
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
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:
1273 return (f(x)) -- results adjusted to 1
1275 return x, f(x) -- additional results
1276 f(x); return -- results discarded
1277 return x or f(x) -- results adjusted to 1
1283 <h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3>
1286 The syntax for function definition is
1289 function ::= <b>function</b> funcbody
1290 funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b>
1294 The following syntactic sugar simplifies function definitions:
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]
1304 function f () <em>body</em> end
1309 f = function () <em>body</em> end
1314 function t.a.b.c.f () <em>body</em> end
1319 t.a.b.c.f = function () <em>body</em> end
1324 local function f () <em>body</em> end
1329 local f; f = function () <em>body</em> end
1334 local f = function () <em>body</em> end
1336 (This only makes a difference when the body of the function
1337 contains references to <code>f</code>.)
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.
1355 Parameters act as local variables that are
1356 initialized with the argument values:
1359 parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´
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>,
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).
1382 As an example, consider the following definitions:
1385 function f(a, b) end
1386 function g(a, b, ...) end
1387 function r() return 1,2,3 end
1389 Then, we have the following mapping from arguments to parameters and
1390 to the vararg expression:
1398 f(r(), 10) a=1, b=10
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
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.
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>.
1421 function t.a.b.c:f (<em>params</em>) <em>body</em> end
1423 is syntactic sugar for
1426 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
1434 <h2>2.6 - <a name="2.6">Visibility Rules</a></h2>
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:
1445 x = 10 -- global variable
1447 local x = x -- new 'x', with value 10
1451 local x = x+1 -- another 'x'
1456 print(x) --> 10 (the global one)
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.
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.
1475 Notice that each execution of a <b>local</b> statement
1476 defines new local variables.
1477 Consider the following example:
1484 a[i] = function () y=y+1; return x+y end
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>.
1496 <h2>2.7 - <a name="2.7">Error Handling</a></h2>
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).
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.
1518 <h2>2.8 - <a name="2.8">Metatables</a></h2>
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.
1530 Lua calls this function to perform the addition.
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.
1541 You can query the metatable of any value
1542 through the <a href="#pdf-getmetatable
"><code>getmetatable</code></a> function.
1546 You can replace the metatable of tables
1547 through the <a href="#pdf-setmetatable
"><code>setmetatable</code></a>
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.
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.
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.
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.
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
1597 metatable(obj)[event]
1599 This should be read as
1602 rawget(getmetatable(obj) or {}, event)
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>).
1614 the
<code>+
</code> operation.
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.
1626 function getbinhandler (op1, op2, event)
1627 return metatable(op1)[event] or metatable(op2)[event]
1630 By using this function,
1631 the behavior of the
<code>op1 + op2
</code> is
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")
1641 -- call the handler with both operands
1642 return (h(op1, op2))
1643 else -- no handler available: default behavior
1644 error(
···)
1652 the
<code>-
</code> operation.
1654 Behavior similar to the "add" operation.
1658 the
<code>*
</code> operation.
1660 Behavior similar to the "add" operation.
1664 the
<code>/
</code> operation.
1666 Behavior similar to the "add" operation.
1670 the
<code>%
</code> operation.
1672 Behavior similar to the "add" operation,
1674 <code>o1 - floor(o1/o2)*o2
</code> as the primitive operation.
1678 the
<code>^
</code> (exponentiation) operation.
1680 Behavior similar to the "add" operation,
1681 with the function
<code>pow
</code> (from the C
math library)
1682 as the primitive operation.
1686 the unary
<code>-
</code> operation.
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
1698 -- call the handler with the operand
1700 else -- no handler available: default behavior
1701 error(
···)
1708 <li><b>"concat":
</b>
1709 the
<code>..
</code> (concatenation) operation.
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
1718 local h = getbinhandler(op1, op2, "__concat")
1720 return (h(op1, op2))
1722 error(
···)
1730 the
<code>#
</code> operation.
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
1740 local h = metatable(op).__len
1742 -- call the handler with the operand
1744 else -- no handler available: default behavior
1745 error(
···)
1750 See
<a href=
"#2.5.5">§2.5.5</a> for a description of the length of a table.
1754 the
<code>==
</code> operation.
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.
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
1770 The "eq" event is defined as follows:
1773 function eq_event (op1, op2)
1774 if type(op1) ~= type(op2) then -- different types?
1775 return false -- different objects
1777 if op1 == op2 then -- primitive equal?
1778 return true -- objects are equal
1781 local h = getcomphandler(op1, op2, "__eq")
1783 return (h(op1, op2))
1789 <code>a ~= b
</code> is equivalent to
<code>not (a == b)
</code>.
1793 the
<code><</code> operation.
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
1803 local h = getcomphandler(op1, op2, "__lt")
1805 return (h(op1, op2))
1807 error(
···)
1812 <code>a
> b
</code> is equivalent to
<code>b
< a
</code>.
1816 the
<code><=
</code> operation.
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
1826 local h = getcomphandler(op1, op2, "__le")
1828 return (h(op1, op2))
1830 h = getcomphandler(op1, op2, "__lt")
1832 return not h(op2, op1)
1834 error(
···)
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>.
1847 The indexing access
<code>table[key]
</code>.
1851 function gettable_event (table, key)
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
1859 h = metatable(table).__index
1861 error(
···)
1864 if type(h) == "function" then
1865 return (h(table, key)) -- call the handler
1866 else return h[key] -- or repeat operation on it
1872 <li><b>"newindex":
</b>
1873 The indexing assignment
<code>table[key] = value
</code>.
1877 function settable_event (table, key, value)
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
1885 h = metatable(table).__newindex
1887 error(
···)
1890 if type(h) == "function" then
1891 h(table, key,value) -- call the handler
1892 else h[key] = value -- or repeat operation on it
1899 called when Lua calls a value.
1903 function function_event (func, ...)
1904 if type(func) == "function" then
1905 return func(...) -- primitive call
1907 local h = metatable(func).__call
1911 error(
···)
1923 <h2>2.9 -
<a name=
"2.9">Environments
</a></h2>
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.
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.
1946 Environments associated with userdata have no meaning for Lua.
1947 It is only a convenience feature for programmers to associate a table to
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>).
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.
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.
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
1986 <h2>2.10 -
<a name=
"2.10">Garbage Collection
</a></h2>
1989 Lua performs automatic memory management.
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.
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).
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
2016 A value of
200 means that the collector waits for the total memory in use
2017 to double before starting a new cycle.
2022 controls the relative speed of the collector relative to
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.
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).
2040 <h3>2.10.1 -
<a name=
"2.10.1">Garbage-Collection Metamethods
</a></h3>
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).
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:
2061 function gc_event (udata)
2062 local h = metatable(udata).__gc
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.
2082 <h3>2.10.2 -
<a name=
"2.10.2">Weak Tables
</a></h3>
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.
2089 if the only references to an object are weak references,
2090 then the garbage collector will collect this object.
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.
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.
2121 <h2>2.11 -
<a name=
"2.11">Coroutines
</a></h2>
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
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.
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>.
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.
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>.
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.
2195 consider the following code:
2200 return coroutine.yield(
2*a)
2203 co = coroutine.create(function (a,b)
2204 print("co-body", a, b)
2207 local r, s = coroutine.yield(a+b, a-b)
2208 print("co-body", r, s)
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"))
2217 When you run it, it produces the following output:
2228 main false cannot resume dead coroutine
2234 <h1>3 -
<a name=
"3">The Application Program Interface
</a></h1>
2238 This section describes the C
API for Lua, that is,
2239 the set of C
functions available to the host program to communicate
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>.
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.
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>.
2262 <h2>3.1 -
<a name=
"3.1">The Stack
</a></h2>
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.).
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>).
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)
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>).
2304 <h2>3.2 -
<a name=
"3.2">Stack Size
</a></h2>
2307 When you interact with Lua API,
2308 you are responsible for ensuring consistency.
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.
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.
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>
2332 (index
< 0 && abs(index)
<= top) ||
2333 (index
> 0 && index
<= stackspace)
2335 Note that
0 is never an acceptable index.
2341 <h2>3.3 -
<a name=
"3.3">Pseudo-Indices
</a></h2>
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,
2352 and the upvalues of a C
function (see
<a href=
"#3.4">§3.4</a>).
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>.
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
2368 lua_getfield(L, LUA_GLOBALSINDEX, varname);
2374 <h2>3.4 -
<a name=
"3.4">C Closures
</a></h2>
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>).
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.
2401 <h2>3.5 -
<a name=
"3.5">Registry
</a></h2>
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.
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.
2425 <h2>3.6 -
<a name=
"3.6">Error Handling in C
</a></h2>
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,
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.
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.
2449 Inside a C
function you can throw an error by calling
<a href=
"#lua_error"><code>lua_error
</code></a>.
2455 <h2>3.7 -
<a name=
"3.7">Functions and Types
</a></h2>
2458 Here we list all functions and types from the C
API in
2460 Each function has an indicator like this:
2461 <span class=
"apii">[-o, +p,
<em>x
</em>]
</span>
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.
2487 <hr><h3><a name=
"lua_Alloc"><code>lua_Alloc
</code></a></h3>
2488 <pre>typedef void * (*lua_Alloc) (void *ud,
2491 size_t nsize);
</pre>
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.
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>.
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>.
2522 static void *l_alloc (void *ud, void *ptr, size_t osize,
2524 (void)ud; (void)osize; /* not used */
2530 return realloc(ptr, nsize);
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.
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>
2547 Sets a new panic function and returns the old one.
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).
2560 The panic function can access the error message at the top of the stack.
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>
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
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.
2595 Any error inside the called function is propagated upwards
2596 (with a
<code>longjmp
</code>).
2600 The following example shows how the host program can do the
2601 equivalent to this Lua code:
2604 a = f("how", t.x,
14)
2606 Here it is in
C:
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' */
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.
2626 <hr><h3><a name=
"lua_CFunction"><code>lua_CFunction
</code></a></h3>
2627 <pre>typedef int (*lua_CFunction) (lua_State *L);
</pre>
2630 Type for C
functions.
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
2648 Like a Lua function, a C
function called by Lua can also return
2653 As an example, the following function receives a variable number
2654 of numerical arguments and returns their average and sum:
2657 static int foo (lua_State *L) {
2658 int n = lua_gettop(L); /* number of arguments */
2661 for (i =
1; i
<= n; i++) {
2662 if (!lua_isnumber(L, i)) {
2663 lua_pushstring(L, "incorrect argument");
2666 sum += lua_tonumber(L, i);
2668 lua_pushnumber(L, sum/n); /* first result */
2669 lua_pushnumber(L, sum); /* second result */
2670 return
2; /* number of results */
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>
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.
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>
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.
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>
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>).
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>
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>.
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.
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>
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>.
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>
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,
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>
2779 The value returned is the error code returned by the last
2781 0 means no errors.
2785 This function does not pop the Lua function from the stack.
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>
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.
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>
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>).
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>
2828 Controls the garbage collector.
2832 This function performs several tasks,
2833 according to the value of the parameter
<code>what
</code>:
2837 <li><b><code>LUA_GCSTOP
</code>:
</b>
2838 stops the garbage collector.
2841 <li><b><code>LUA_GCRESTART
</code>:
</b>
2842 restarts the garbage collector.
2845 <li><b><code>LUA_GCCOLLECT
</code>:
</b>
2846 performs a full garbage-collection cycle.
2849 <li><b><code>LUA_GCCOUNT
</code>:
</b>
2850 returns the current amount of memory (in Kbytes) in use by Lua.
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.
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.
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.
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.
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>
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>.
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>
2903 Pushes onto the stack the environment table of
2904 the value at the given index.
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>
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>).
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>
2929 Pushes onto the stack the value of the global
<code>name
</code>.
2930 It is defined as a macro:
2933 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
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>
2944 Pushes onto the stack the metatable of the value at the given
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.
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>
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.
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>).
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>
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).
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>
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.
3002 <hr><h3><a name=
"lua_Integer"><code>lua_Integer
</code></a></h3>
3003 <pre>typedef ptrdiff_t lua_Integer;
</pre>
3006 The type used by the Lua API to represent integral values.
3010 By default it is a
<code>ptrdiff_t
</code>,
3011 which is usually the largest signed integral type the machine handles
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>
3023 Returns
1 if the value at the given acceptable index has type boolean,
3024 and
0 otherwise.
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>
3035 Returns
1 if the value at the given acceptable index is a C
function,
3036 and
0 otherwise.
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>
3047 Returns
1 if the value at the given acceptable index is a function
3048 (either C or Lua), and
0 otherwise.
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>
3059 Returns
1 if the value at the given acceptable index is a light userdata,
3060 and
0 otherwise.
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>
3071 Returns
1 if the value at the given acceptable index is
<b>nil
</b>,
3072 and
0 otherwise.
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>
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.
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>
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.
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>
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.
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>
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.
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>
3136 Returns
1 if the value at the given acceptable index is a table,
3137 and
0 otherwise.
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>
3148 Returns
1 if the value at the given acceptable index is a thread,
3149 and
0 otherwise.
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>
3160 Returns
1 if the value at the given acceptable index is a userdata
3161 (either full or light), and
0 otherwise.
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>
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.
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,
3188 const char *chunkname);
</pre>
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:
3200 <li><b>0:
</b> no errors;
</li>
3202 <li><b><a name=
"pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX
</code></a>:
</b>
3203 syntax error during pre-compilation;
</li>
3205 <li><b><a href=
"#pdf-LUA_ERRMEM"><code>LUA_ERRMEM
</code></a>:
</b>
3206 memory allocation error.
</li>
3211 This function only loads a chunk;
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>).
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.
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>).
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>
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.
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>
3256 Creates a new empty table and pushes it onto the stack.
3257 It is equivalent to
<code>lua_createtable(L,
0,
0)
</code>.
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>
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.
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.
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>
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.
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).
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.
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>
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).
3326 A typical traversal looks like this:
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) */
3334 lua_typename(L, lua_type(L, -
2)),
3335 lua_typename(L, lua_type(L, -
1)));
3336 /* removes 'value'; keeps 'key' for next iteration */
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>.
3353 <hr><h3><a name=
"lua_Number"><code>lua_Number
</code></a></h3>
3354 <pre>typedef double lua_Number;
</pre>
3357 The type of numbers in Lua.
3358 By default, it is double, but that can be changed in
<code>luaconf.h
</code>.
3362 Through the configuration file you can change
3363 Lua to operate with another type for numbers (e.g., float or long).
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>
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
3379 for other values, it is
0.
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>
3390 Calls a function in protected mode.
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.
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>.
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.
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>):
3433 <li><b><a name=
"pdf-LUA_ERRRUN"><code>LUA_ERRRUN
</code></a>:
</b>
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.
3442 <li><b><a name=
"pdf-LUA_ERRERR"><code>LUA_ERRERR
</code></a>:
</b>
3443 error while running the error handler function.
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>
3456 Pops
<code>n
</code> elements from the stack.
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>
3467 Pushes a boolean value with value
<code>b
</code> onto the stack.
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>
3478 Pushes a new C
closure onto the stack.
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.
3497 The maximum value for
<code>n
</code> is
255.
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>
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.
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>).
3521 <code>lua_pushcfunction
</code> is defined as a macro:
3524 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,
0)
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>
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:
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).
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).
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>
3570 Pushes a number with value
<code>n
</code> onto the stack.
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>
3581 Pushes a light userdata onto the stack.
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.
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>
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.
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>
3615 Pushes the string pointed to by
<code>s
</code> with size
<code>len
</code>
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.
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>
3631 Pushes a nil value onto the stack.
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>
3642 Pushes a number with value
<code>n
</code> onto the stack.
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>
3653 Pushes the zero-terminated string pointed to by
<code>s
</code>
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.
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>
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.
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>
3682 Pushes a copy of the element at the given valid index
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,
3693 va_list argp);
</pre>
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.
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>
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.
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>
3723 Similar to
<a href=
"#lua_gettable"><code>lua_gettable
</code></a>, but does a raw access
3724 (i.e., without metamethods).
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>
3735 Pushes onto the stack the value
<code>t[n]
</code>,
3736 where
<code>t
</code> is the value at the given valid index.
3738 that is, it does not invoke metamethods.
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>
3749 Similar to
<a href=
"#lua_settable"><code>lua_settable
</code></a>, but does a raw assignment
3750 (i.e., without metamethods).
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>
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.
3767 This function pops the value from the stack.
3768 The assignment is raw;
3769 that is, it does not invoke metamethods.
3775 <hr><h3><a name=
"lua_Reader"><code>lua_Reader
</code></a></h3>
3776 <pre>typedef const char * (*lua_Reader) (lua_State *L,
3778 size_t *size);
</pre>
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.
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,
3801 lua_CFunction f);
</pre>
3804 Sets the C function
<code>f
</code> as the new value of global
<code>name
</code>.
3805 It is defined as a macro:
3808 #define lua_register(L,n,f) \
3809 (lua_pushcfunction(L, f), lua_setglobal(L, n))
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>
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.
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>
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).
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>
3847 Starts and resumes a coroutine in a given thread.
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
3863 or an error code in case of errors (see
<a href=
"#lua_pcall"><code>lua_pcall
</code></a>).
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>.
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>
3881 Changes the allocator function of a given state to
<code>f
</code>
3882 with user data
<code>ud
</code>.
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>
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.
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>
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.
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>).
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>
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:
3933 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
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>
3944 Pops a table from the stack and
3945 sets it as the new metatable for the value at the given
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>
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.
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>).
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>
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.
3987 <hr><h3><a name=
"lua_State"><code>lua_State
</code></a></h3>
3988 <pre>typedef struct lua_State lua_State;
</pre>
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.
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.
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>
4011 Returns the status of the thread
<code>L
</code>.
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.
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>
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.)
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>
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>.
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>
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.
4068 If the number is not an integer,
4069 it is truncated in some non-specified way.
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>
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.)
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.
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>
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.
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>
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.
4135 Typically this function is used only for debug information.
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>
4146 Equivalent to
<a href=
"#lua_tolstring"><code>lua_tolstring
</code></a> with
<code>len
</code> equal to
<code>NULL
</code>.
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>
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>.
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>
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>.
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>
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>,
4200 <code>LUA_TLIGHTUSERDATA
</code>.
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>
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>.
4218 <hr><h3><a name=
"lua_Writer"><code>lua_Writer
</code></a></h3>
4219 <pre>typedef int (*lua_Writer) (lua_State *L,
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>.
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.
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>
4248 Exchange values between different threads of the
<em>same
</em> global state.
4252 This function pops
<code>n
</code> values from the stack
<code>from
</code>,
4253 and pushes them onto the stack
<code>to
</code>.
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>
4268 This function should only be called as the
4269 return expression of a C
function, as follows:
4272 return lua_yield (L, nresults);
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>.
4286 <h2>3.8 -
<a name=
"3.8">The Debug Interface
</a></h2>
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.
4298 <hr><h3><a name=
"lua_Debug"><code>lua_Debug
</code></a></h3>
4299 <pre>typedef struct lua_Debug {
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) */
4311 <em>other fields
</em>
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>.
4324 The fields of
<a href=
"#lua_Debug"><code>lua_Debug
</code></a> have the following meaning:
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.
4335 <li><b><code>short_src
</code>:
</b>
4336 a "printable" version of
<code>source
</code>, to be used in error messages.
4339 <li><b><code>linedefined
</code>:
</b>
4340 the line number where the definition of the function starts.
4343 <li><b><code>lastlinedefined
</code>:
</b>
4344 the line number where the definition of the function ends.
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.
4353 Lua has no other information about the function.
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.
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>.
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.)
4383 <li><b><code>nups
</code>:
</b>
4384 the number of upvalues of the function.
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>
4397 Returns the current hook function.
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>
4408 Returns the current hook count.
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>
4419 Returns the current hook mask.
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>
4430 Returns information about a specific function or function invocation.
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>).
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>'.
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:
4450 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
4451 lua_getinfo(L, "
>S",
&ar);
4452 printf("%d\n", ar.linedefined);
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:
4462 <li><b>'
<code>n
</code>':
</b> fills in the field
<code>name
</code> and
<code>namewhat
</code>;
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>;
4470 <li><b>'
<code>l
</code>':
</b> fills in the field
<code>currentline
</code>;
4473 <li><b>'
<code>u
</code>':
</b> fills in the field
<code>nups
</code>;
4476 <li><b>'
<code>f
</code>':
</b>
4477 pushes onto the stack the function that is
4478 running at the given level;
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.)
4492 This function returns
0 on error
4493 (for instance, an invalid option in
<code>what
</code>).
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>
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.
4516 Variable names starting with '
<code>(
</code>' (open parentheses)
4517 represent internal variables
4518 (loop control variables, temporaries, and C
function locals).
4522 Returns
<code>NULL
</code> (and pushes nothing)
4523 when the index is greater than
4524 the number of active local variables.
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>
4535 Get information about the interpreter runtime stack.
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,
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>
4557 Gets information about a closure's upvalue.
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.)
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.
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>
4584 Type for debugging hook functions.
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>.
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.
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>
4618 Sets the debugging hook function.
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:
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.
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.
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.)
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.)
4659 A hook is disabled by setting
<code>mask
</code> to zero.
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>
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.
4679 Returns
<code>NULL
</code> (and pops nothing)
4680 when the index is greater than
4681 the number of active local variables.
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>
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>).
4701 Returns
<code>NULL
</code> (and pops nothing)
4702 when the index is greater than the number of upvalues.
4710 <h1>4 -
<a name=
"4">The Auxiliary Library
</a></h1>
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
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>.
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.
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.
4745 <h2>4.1 - <a name="4.1">Functions and Types</a></h2>
4748 Here we list all functions and types from the auxiliary library
4749 in alphabetical order.
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>
4758 Adds the character <code>c</code> to the buffer <code>B</code>
4759 (see <a href="#luaL_Buffer
"><code>luaL_Buffer</code></a>).
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>
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.
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>
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>).
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>
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.
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>
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>).
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.
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,
4831 const char *extramsg);</pre>
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:
4839 bad argument #<narg> to <func> (<extramsg>)
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>
4850 Raises an error with the following message,
4851 where <code>func</code> is retrieved from the call stack:
4854 bad argument #<narg> to <func> (<extramsg>)
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>.
4866 <hr><h3><a name="luaL_Buffer
"><code>luaL_Buffer</code></a></h3>
4867 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
4870 Type for a <em>string buffer</em>.
4874 A string buffer allows C code to build Lua strings piecemeal.
4875 Its pattern of use is as follows:
4879 <li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer
"><code>luaL_Buffer</code></a>.</li>
4881 <li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
4884 Then you add string pieces to the buffer calling any of
4885 the <code>luaL_add*</code> functions.
4889 You finish by calling <code>luaL_pushresult(&b)</code>.
4890 This call leaves the final string on the top of the stack.
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;
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.
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>
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>).
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>
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).
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>
4955 Checks whether the function has an argument
4956 of any type (including <b>nil</b>) at position <code>narg</code>.
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>
4967 Checks whether the function argument <code>narg</code> is a number
4968 and returns this number cast to an <code>int</code>.
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>
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>.
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>
4991 Checks whether the function argument <code>narg</code> is a number
4992 and returns this number cast to a <code>long</code>.
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>
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.
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.
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>
5022 Checks whether the function argument <code>narg</code> is a number
5023 and returns this number.
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,
5034 const char *const lst[]);</pre>
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.
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>.
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.)
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>
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.
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>
5078 Checks whether the function argument <code>narg</code> is a string
5079 and returns this string.
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.
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>
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>.
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>
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>).
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>
5119 Loads and runs the given file.
5120 It is defined as the following macro:
5123 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
5125 It returns 0 if there are no errors
5126 or 1 in case of errors.
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>
5137 Loads and runs the given string.
5138 It is defined as the following macro:
5141 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
5143 It returns 0 if there are no errors
5144 or 1 in case of errors.
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>
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.
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>.
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>
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.
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>
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>).
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,
5205 const char *r);</pre>
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.
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,
5222 const char *name);</pre>
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>.
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.
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>
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>.
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.
5259 As <a href="#lua_load
"><code>lua_load</code></a>, this function only loads the chunk;
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>
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>.
5277 This function returns the same results as <a href="#lua_load
"><code>lua_load</code></a>.
5281 Also as <a href="#lua_load
"><code>lua_load</code></a>, this function only loads the chunk;
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>
5293 If the registry already has the key <code>tname</code>,
5296 creates a new table to be used as a metatable for userdata,
5297 adds it to the registry with key <code>tname</code>,
5302 In both cases pushes onto the stack the final value associated
5303 with <code>tname</code> in the registry.
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>
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
5323 Returns the new state,
5324 or <code>NULL</code> if there is a memory allocation error.
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>
5335 Opens all standard Lua libraries into the given state.
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>
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.
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,
5360 lua_Integer d);</pre>
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.
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>
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.
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,
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.
5404 If <code>l</code> is not <code>NULL</code>,
5405 fills the position <code>*l</code> with the results's length.
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>
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.
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,
5430 const char *d);</pre>
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.
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>
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
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>
5464 Finishes the use of buffer <code>B</code> leaving the final string on
5465 the top of the stack.
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>
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).
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.
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>.
5500 <hr><h3><a name="luaL_Reg
"><code>luaL_Reg</code></a></h3>
5501 <pre>typedef struct luaL_Reg {
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
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>.
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>
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.
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.
5546 In any case the function leaves the table
5547 on the top of the stack.
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>
5558 Returns the name of the type of the value at the given index.
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>
5569 Generates an error with a message like the following:
5572 <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>)
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.
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>
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.
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.
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>
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:
5612 <em>chunkname</em>:<em>currentline</em>:
5614 Level 0 is the running function,
5615 level 1 is the function that called the running function,
5620 This function is used to build a prefix for error messages.
5628 <h1>5 - <a name="5">Standard Libraries</a></h1>
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>).
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:
5648 <li>basic library,
</li> which includes the coroutine sub-library;
5650 <li>package library;
</li>
5652 <li>string manipulation;
</li>
5654 <li>table manipulation;
</li>
5656 <li>mathematical functions (sin, log, etc.);
</li>
5658 <li>input and output;
</li>
5660 <li>operating system facilities;
</li>
5662 <li>debug facilities.
</li>
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.
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.
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>.
5691 <h2>5.1 -
<a name=
"5.1">Basic Functions
</a></h2>
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.
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!"
5712 <hr><h3><a name=
"pdf-collectgarbage"><code>collectgarbage (opt [, arg])
</code></a></h3>
5716 This function is a generic interface to the garbage collector.
5717 It performs different functions according to its first argument,
<code>opt
</code>:
5722 stops the garbage collector.
5725 <li><b>"restart":
</b>
5726 restarts the garbage collector.
5729 <li><b>"collect":
</b>
5730 performs a full garbage-collection cycle.
5734 returns the total memory in use by Lua (in Kbytes).
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.
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>.
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>.
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).
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.
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
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,
5802 (Use
<a href=
"#pdf-setfenv"><code>setfenv
</code></a> to change environments.)
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.
5822 <hr><h3><a name=
"pdf-getmetatable"><code>getmetatable (object)
</code></a></h3>
5826 If
<code>object
</code> does not have a metatable, returns
<b>nil
</b>.
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.
5836 <hr><h3><a name=
"pdf-ipairs"><code>ipairs (t)
</code></a></h3>
5840 Returns three values: an iterator function, the table
<code>t
</code>, and
0,
5841 so that the construction
5844 for i,v in ipairs(t) do
<em>body
</em> end
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.
5853 <hr><h3><a name=
"pdf-load"><code>load (func [, chunkname])
</code></a></h3>
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.
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.
5871 <code>chunkname
</code> is used as the chunk name for error messages
5872 and debug information.
5874 it defaults to "
<code>=(load)
</code>".
5880 <hr><h3><a name="pdf-loadfile
"><code>loadfile ([filename])</code></a></h3>
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.
5893 <hr><h3><a name="pdf-loadstring
"><code>loadstring (string [, chunkname])</code></a></h3>
5897 Similar to <a href="#pdf-load
"><code>load</code></a>,
5898 but gets the chunk from the given string.
5902 To load and run a given string, use the idiom
5905 assert(loadstring(s))()
5910 <code>chunkname</code> defaults to the given string.
5916 <hr><h3><a name="pdf-next
"><code>next (table [, index])</code></a></h3>
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>.
5933 you can use <code>next(t)</code> to check whether a table is empty.
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.)
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.
5954 <hr><h3><a name="pdf-pairs
"><code>pairs (t)</code></a></h3>
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
5962 for k,v in pairs(t) do <em>body</em> end
5964 will iterate over all key–value pairs of table <code>t</code>.
5968 See function <a href="#pdf-next
"><code>next</code></a> for the caveats of modifying
5969 the table during its traversal.
5975 <hr><h3><a name="pdf-pcall
"><code>pcall (f, arg1, ···)</code></a></h3>
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.
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>.
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.
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.
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.
6035 This function returns <code>table</code>.
6041 <hr><h3><a name="pdf-select
"><code>select (index, ···)</code></a></h3>
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.
6054 <hr><h3><a name="pdf-setfenv
"><code>setfenv (f, table)</code></a></h3>
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.
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.
6074 <hr><h3><a name="pdf-setmetatable
"><code>setmetatable (table, metatable)</code></a></h3>
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,
6087 This function returns <code>table</code>.
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>.
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.
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>.
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.
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>".
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
6152 return list[i], list[i+1], ···, list[j]
6154 except that the above code can be written only for a fixed number
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>).
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>".
6172 <hr><h3><a name="pdf-xpcall
"><code>xpcall (f, err)</code></a></h3>
6176 This function is similar to <a href="#pdf-pcall
"><code>pcall</code></a>,
6177 except that you can set a new error handler.
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>.
6200 <h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2>
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.
6209 <hr><h3><a name="pdf-coroutine.create
"><code>coroutine.create (f)</code></a></h3>
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>.
6222 <hr><h3><a name="pdf-coroutine.resume
"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
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.
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.
6249 <hr><h3><a name="pdf-coroutine.running
"><code>coroutine.running ()</code></a></h3>
6253 Returns the running coroutine,
6254 or <b>nil</b> when called by the main thread.
6260 <hr><h3><a name="pdf-coroutine.status
"><code>coroutine.status (co)</code></a></h3>
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.
6278 <hr><h3><a name="pdf-coroutine.wrap
"><code>coroutine.wrap (f)</code></a></h3>
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.
6295 <hr><h3><a name="pdf-coroutine.yield
"><code>coroutine.yield (···)</code></a></h3>
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>.
6310 <h2>5.3 - <a name="5.3">Modules</a></h2>
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>.
6321 <hr><h3><a name="pdf-module
"><code>module (name [, ···])</code></a></h3>
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>.
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>.
6353 This function can receive optional <em>options</em> after
6355 where each option is a function to be applied over the module.
6361 <hr><h3><a name="pdf-require
"><code>require (modname)</code></a></h3>
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.
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>.
6383 First <code>require</code> queries <code>package.preload[modname]</code>.
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>.
6391 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders
"><code>package.loaders</code></a>).
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>.
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.
6415 <hr><h3><a name="pdf-package.cpath
"><code>package.cpath</code></a></h3>
6419 The path used by <a href="#pdf-require
"><code>require</code></a> to search for a C loader.
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>.
6433 <hr><h3><a name="pdf-package.loaded
"><code>package.loaded</code></a></h3>
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.
6447 <hr><h3><a name="pdf-package.loaders
"><code>package.loaders</code></a></h3>
6451 A table used by <a href="#pdf-require
"><code>require</code></a> to control how to load modules.
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
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.
6467 The first searcher simply looks for a loader in the
6468 <a href="#pdf-package.preload
"><code>package.preload</code></a> table.
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.
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
6484 "./?.lua;./?.lc;/usr/local/?/init.lua
"
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.
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>.
6496 if the C path is the string
6499 "./?.so;./?.dll;/usr/local/?/init.so
"
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>.
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
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.
6535 <hr><h3><a name="pdf-package.loadlib
"><code>package.loadlib (libname, funcname)</code></a></h3>
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>)).
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).
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).
6567 <hr><h3><a name="pdf-package.path
"><code>package.path</code></a></h3>
6571 The path used by <a href="#pdf-require
"><code>require</code></a> to search for a Lua loader.
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.
6586 <hr><h3><a name="pdf-package.preload
"><code>package.preload</code></a></h3>
6590 A table to store loaders for specific modules
6591 (see <a href="#pdf-require
"><code>require</code></a>).
6597 <hr><h3><a name="pdf-package.seeall
"><code>package.seeall (module)</code></a></h3>
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>.
6613 <h2>5.4 - <a name="5.4">String Manipulation</a></h2>
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.
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>.
6636 The string library assumes one-byte character encodings.
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>.
6648 Note that numerical codes are not necessarily portable across platforms.
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.
6662 Note that numerical codes are not necessarily portable across platforms.
6668 <hr><h3><a name="pdf-string.dump
"><code>string.dump (function)</code></a></h3>
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.
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.
6698 If the pattern has captures,
6699 then in a successful match
6700 the captured values are also returned,
6701 after the two indices.
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
6725 string.format('%q', 'a string with "quotes" and \n new line')
6727 will produce the string:
6730 "a string with \"quotes\" and \
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.
6742 This function does not accept string values
6743 containing embedded zeros,
6744 except as arguments to the
<code>q
</code> option.
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.
6759 As an example, the following loop
6762 s = "hello world from Lua"
6763 for w in string.gmatch(s, "%a+") do
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:
6774 s = "from=world, to=Lua"
6775 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
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.
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.
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>.
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.
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,
6819 if the pattern specifies no captures,
6820 then the whole match is passed as a sole argument.
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).
6833 Here are some examples:
6836 x = string.gsub("hello world", "(%w+)", "%
1 %
1")
6837 --
> x="hello hello world world"
6839 x = string.gsub("hello world", "%w+", "%
0 %
0",
1)
6840 --
> x="hello hello world"
6842 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%
2 %
1")
6843 --
> x="world hello Lua from"
6845 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
6846 --
> x="home = /home/roberto, user = roberto"
6848 x = string.gsub("
4+
5 = $return
4+
5$", "%$(.-)%$", function (s)
6849 return loadstring(s)()
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"
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.
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.
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.
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>.
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.
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).
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>.
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.
6936 <h3>5.4.1 -
<a name=
"5.4.1">Patterns
</a></h3>
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:
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.
6951 <li><b><code>.
</code>:
</b> (a dot) represents all characters.
</li>
6953 <li><b><code>%a
</code>:
</b> represents all letters.
</li>
6955 <li><b><code>%c
</code>:
</b> represents all control characters.
</li>
6957 <li><b><code>%d
</code>:
</b> represents all digits.
</li>
6959 <li><b><code>%l
</code>:
</b> represents all lowercase letters.
</li>
6961 <li><b><code>%p
</code>:
</b> represents all punctuation characters.
</li>
6963 <li><b><code>%s
</code>:
</b> represents all space characters.
</li>
6965 <li><b><code>%u
</code>:
</b> represents all uppercase letters.
</li>
6967 <li><b><code>%w
</code>:
</b> represents all alphanumeric characters.
</li>
6969 <li><b><code>%x
</code>:
</b> represents all hexadecimal digits.
</li>
6971 <li><b><code>%z
</code>:
</b> represents the character with representation
0.
</li>
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.
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.
6997 The interaction between ranges and classes is not defined.
6998 Therefore, patterns like
<code>[%a-z]
</code> or
<code>[a-%%]
</code>
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.
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.
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>.
7022 <h4>Pattern Item:
</h4><p>
7023 A
<em>pattern item
</em> can be
7028 a single character class,
7029 which matches any single character in the class;
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;
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;
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;
7052 a single character class followed by '
<code>?
</code>',
7053 which matches
0 or
1 occurrence of a character in the class;
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
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.
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.
7085 '
<code>^
</code>' and '
<code>$
</code>' have no special meaning and represent themselves.
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.
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.
7112 A pattern cannot contain embedded zeros. Use <code>%z</code> instead.
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>.
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.
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.
7149 <hr><h3><a name=
"pdf-table.insert"><code>table.insert (table, [pos,] value)
</code></a></h3>
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>.
7164 <hr><h3><a name=
"pdf-table.maxn"><code>table.maxn (table)
</code></a></h3>
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
7177 <hr><h3><a name=
"pdf-table.remove"><code>table.remove (table [, pos])
</code></a></h3>
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>.
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,
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.
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.
7217 <h2>5.6 -
<a name=
"5.6">Mathematical Functions
</a></h2>
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>.
7225 <hr><h3><a name=
"pdf-math.abs"><code>math.abs (x)
</code></a></h3>
7229 Returns the absolute value of
<code>x
</code>.
7235 <hr><h3><a name=
"pdf-math.acos"><code>math.acos (x)
</code></a></h3>
7239 Returns the arc cosine of
<code>x
</code> (in radians).
7245 <hr><h3><a name=
"pdf-math.asin"><code>math.asin (x)
</code></a></h3>
7249 Returns the arc sine of
<code>x
</code> (in radians).
7255 <hr><h3><a name=
"pdf-math.atan"><code>math.atan (x)
</code></a></h3>
7259 Returns the arc tangent of
<code>x
</code> (in radians).
7265 <hr><h3><a name=
"pdf-math.atan2"><code>math.atan2 (y, x)
</code></a></h3>
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.)
7278 <hr><h3><a name=
"pdf-math.ceil"><code>math.ceil (x)
</code></a></h3>
7282 Returns the smallest integer larger than or equal to
<code>x
</code>.
7288 <hr><h3><a name=
"pdf-math.cos"><code>math.cos (x)
</code></a></h3>
7292 Returns the cosine of
<code>x
</code> (assumed to be in radians).
7298 <hr><h3><a name=
"pdf-math.cosh"><code>math.cosh (x)
</code></a></h3>
7302 Returns the hyperbolic cosine of
<code>x
</code>.
7308 <hr><h3><a name=
"pdf-math.deg"><code>math.deg (x)
</code></a></h3>
7312 Returns the angle
<code>x
</code> (given in radians) in degrees.
7318 <hr><h3><a name=
"pdf-math.exp"><code>math.exp (x)
</code></a></h3>
7322 Returns the value
<em>e
<sup>x
</sup></em>.
7328 <hr><h3><a name=
"pdf-math.floor"><code>math.floor (x)
</code></a></h3>
7332 Returns the largest integer smaller than or equal to
<code>x
</code>.
7338 <hr><h3><a name=
"pdf-math.fmod"><code>math.fmod (x, y)
</code></a></h3>
7342 Returns the remainder of the division of
<code>x
</code> by
<code>y
</code>
7343 that rounds the quotient towards zero.
7349 <hr><h3><a name=
"pdf-math.frexp"><code>math.frexp (x)
</code></a></h3>
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).
7362 <hr><h3><a name=
"pdf-math.huge"><code>math.huge
</code></a></h3>
7366 The value
<code>HUGE_VAL
</code>,
7367 a value larger than or equal to any other numerical value.
7373 <hr><h3><a name=
"pdf-math.ldexp"><code>math.ldexp (m, e)
</code></a></h3>
7377 Returns
<em>m2
<sup>e
</sup></em> (
<code>e
</code> should be an integer).
7383 <hr><h3><a name=
"pdf-math.log"><code>math.log (x)
</code></a></h3>
7387 Returns the natural logarithm of
<code>x
</code>.
7393 <hr><h3><a name=
"pdf-math.log10"><code>math.log10 (x)
</code></a></h3>
7397 Returns the base-
10 logarithm of
<code>x
</code>.
7403 <hr><h3><a name=
"pdf-math.max"><code>math.max (x,
···)
</code></a></h3>
7407 Returns the maximum value among its arguments.
7413 <hr><h3><a name=
"pdf-math.min"><code>math.min (x,
···)
</code></a></h3>
7417 Returns the minimum value among its arguments.
7423 <hr><h3><a name=
"pdf-math.modf"><code>math.modf (x)
</code></a></h3>
7427 Returns two numbers,
7428 the integral part of
<code>x
</code> and the fractional part of
<code>x
</code>.
7434 <hr><h3><a name=
"pdf-math.pi"><code>math.pi
</code></a></h3>
7438 The value of
<em>pi
</em>.
7444 <hr><h3><a name=
"pdf-math.pow"><code>math.pow (x, y)
</code></a></h3>
7448 Returns
<em>x
<sup>y
</sup></em>.
7449 (You can also use the expression
<code>x^y
</code> to compute this value.)
7455 <hr><h3><a name=
"pdf-math.rad"><code>math.rad (x)
</code></a></h3>
7459 Returns the angle
<code>x
</code> (given in degrees) in radians.
7465 <hr><h3><a name=
"pdf-math.random"><code>math.random ([m [, n]])
</code></a></h3>
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.)
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>.
7489 <hr><h3><a name=
"pdf-math.randomseed"><code>math.randomseed (x)
</code></a></h3>
7493 Sets
<code>x
</code> as the "seed"
7494 for the pseudo-random generator:
7495 equal seeds produce equal sequences of numbers.
7501 <hr><h3><a name=
"pdf-math.sin"><code>math.sin (x)
</code></a></h3>
7505 Returns the sine of
<code>x
</code> (assumed to be in radians).
7511 <hr><h3><a name=
"pdf-math.sinh"><code>math.sinh (x)
</code></a></h3>
7515 Returns the hyperbolic sine of
<code>x
</code>.
7521 <hr><h3><a name=
"pdf-math.sqrt"><code>math.sqrt (x)
</code></a></h3>
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.)
7532 <hr><h3><a name=
"pdf-math.tan"><code>math.tan (x)
</code></a></h3>
7536 Returns the tangent of
<code>x
</code> (assumed to be in radians).
7542 <hr><h3><a name=
"pdf-math.tanh"><code>math.tanh (x)
</code></a></h3>
7546 Returns the hyperbolic tangent of
<code>x
</code>.
7554 <h2>5.7 -
<a name=
"5.7">Input and Output Facilities
</a></h2>
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.
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.
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.
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.
7589 <hr><h3><a name=
"pdf-io.close"><code>io.close ([file])
</code></a></h3>
7593 Equivalent to
<code>file:close()
</code>.
7594 Without a
<code>file
</code>, closes the default output file.
7600 <hr><h3><a name=
"pdf-io.flush"><code>io.flush ()
</code></a></h3>
7604 Equivalent to
<code>file:flush
</code> over the default output file.
7610 <hr><h3><a name=
"pdf-io.input"><code>io.input ([file])
</code></a></h3>
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.
7623 In case of errors this function raises the error,
7624 instead of returning an error code.
7630 <hr><h3><a name=
"pdf-io.lines"><code>io.lines ([filename])
</code></a></h3>
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
7641 for line in io.lines(filename) do
<em>body
</em> end
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.
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.
7658 <hr><h3><a name=
"pdf-io.open"><code>io.open (filename [, mode])
</code></a></h3>
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.
7669 The
<code>mode
</code> string can be any of the following:
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>
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>.
7689 <hr><h3><a name=
"pdf-io.output"><code>io.output ([file])
</code></a></h3>
7693 Similar to
<a href=
"#pdf-io.input"><code>io.input
</code></a>, but operates over the default output file.
7699 <hr><h3><a name=
"pdf-io.popen"><code>io.popen (prog [, mode])
</code></a></h3>
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>).
7711 This function is system dependent and is not available
7718 <hr><h3><a name=
"pdf-io.read"><code>io.read (
···)
</code></a></h3>
7722 Equivalent to
<code>io.input():read
</code>.
7728 <hr><h3><a name=
"pdf-io.tmpfile"><code>io.tmpfile ()
</code></a></h3>
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.
7740 <hr><h3><a name=
"pdf-io.type"><code>io.type (obj)
</code></a></h3>
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.
7753 <hr><h3><a name=
"pdf-io.write"><code>io.write (
···)
</code></a></h3>
7757 Equivalent to
<code>io.output():write
</code>.
7763 <hr><h3><a name=
"pdf-file:close"><code>file:close ()
</code></a></h3>
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.
7776 <hr><h3><a name=
"pdf-file:flush"><code>file:flush ()
</code></a></h3>
7780 Saves any written data to
<code>file
</code>.
7786 <hr><h3><a name=
"pdf-file:lines"><code>file:lines ()
</code></a></h3>
7790 Returns an iterator function that,
7791 each time it is called,
7792 returns a new line from the file.
7793 Therefore, the construction
7796 for line in file:lines() do
<em>body
</em> end
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.)
7806 <hr><h3><a name=
"pdf-file:read"><code>file:read (
···)
</code></a></h3>
7810 Reads the file
<code>file
</code>,
7811 according to the given formats, which specify what to read.
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
7821 The available formats are
7827 this is the only format that returns a number instead of a string.
7831 reads the whole file, starting at the current position.
7832 On end of file, it returns the empty string.
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.
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.
7845 it reads nothing and returns an empty string,
7846 or
<b>nil
</b> on end of file.
7854 <hr><h3><a name=
"pdf-file:seek"><code>file:seek ([whence] [, offset])
</code></a></h3>
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:
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>
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.
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.
7888 <hr><h3><a name=
"pdf-file:setvbuf"><code>file:setvbuf (mode [, size])
</code></a></h3>
7892 Sets the buffering mode for an output file.
7893 There are three available modes:
7898 no buffering; the result of any output operation appears immediately.
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>)).
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).
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.
7922 <hr><h3><a name=
"pdf-file:write"><code>file:write (
···)
</code></a></h3>
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>.
7938 <h2>5.8 -
<a name=
"5.8">Operating System Facilities
</a></h2>
7941 This library is implemented through table
<a name=
"pdf-os"><code>os
</code></a>.
7945 <hr><h3><a name=
"pdf-os.clock"><code>os.clock ()
</code></a></h3>
7949 Returns an approximation of the amount in seconds of CPU time
7950 used by the program.
7956 <hr><h3><a name=
"pdf-os.date"><code>os.date ([format [, time]])
</code></a></h3>
7960 Returns a string or a table containing date and time,
7961 formatted according to the given string
<code>format
</code>.
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.
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).
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>.
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>).
8000 <hr><h3><a name=
"pdf-os.difftime"><code>os.difftime (t2, t1)
</code></a></h3>
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>.
8012 <hr><h3><a name=
"pdf-os.execute"><code>os.execute ([command])
</code></a></h3>
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
8026 <hr><h3><a name=
"pdf-os.exit"><code>os.exit ([code])
</code></a></h3>
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.
8039 <hr><h3><a name=
"pdf-os.getenv"><code>os.getenv (varname)
</code></a></h3>
8043 Returns the value of the process environment variable
<code>varname
</code>,
8044 or
<b>nil
</b> if the variable is not defined.
8050 <hr><h3><a name=
"pdf-os.remove"><code>os.remove (filename)
</code></a></h3>
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.
8063 <hr><h3><a name=
"pdf-os.rename"><code>os.rename (oldname, newname)
</code></a></h3>
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.
8075 <hr><h3><a name=
"pdf-os.setlocale"><code>os.setlocale (locale [, category])
</code></a></h3>
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.
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.
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.
8105 <hr><h3><a name="pdf-os.time
"><code>os.time ([table])</code></a></h3>
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).
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>.
8128 <hr><h3><a name=
"pdf-os.tmpname"><code>os.tmpname ()
</code></a></h3>
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.
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).
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.
8159 <h2>5.9 -
<a name=
"5.9">The Debug Library
</a></h2>
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.
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.
8188 <hr><h3><a name=
"pdf-debug.debug"><code>debug.debug ()
</code></a></h3>
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.
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.
8209 <hr><h3><a name=
"pdf-debug.getfenv"><code>debug.getfenv (o)
</code></a></h3>
8210 Returns the environment of object
<code>o
</code>.
8216 <hr><h3><a name=
"pdf-debug.gethook"><code>debug.gethook ([thread])
</code></a></h3>
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).
8229 <hr><h3><a name=
"pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])
</code></a></h3>
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>;
8241 If
<code>function
</code> is a number larger than the number of active functions,
8242 then
<code>getinfo
</code> returns
<b>nil
</b>.
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.
8251 the option '
<code>f
</code>'
8252 adds a field named
<code>func
</code> with the function itself.
8254 the option '
<code>L
</code>'
8255 adds a field named
<code>activelines
</code> with the table of
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.
8271 <hr><h3><a name=
"pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)
</code></a></h3>
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.)
8286 Variable names starting with '
<code>(
</code>' (open parentheses)
8287 represent internal variables
8288 (loop control variables, temporaries, and C
function locals).
8294 <hr><h3><a name=
"pdf-debug.getmetatable"><code>debug.getmetatable (object)
</code></a></h3>
8298 Returns the metatable of the given
<code>object
</code>
8299 or
<b>nil
</b> if it does not have a metatable.
8305 <hr><h3><a name=
"pdf-debug.getregistry"><code>debug.getregistry ()
</code></a></h3>
8309 Returns the registry table (see
<a href=
"#3.5">§3.5</a>).
8315 <hr><h3><a name=
"pdf-debug.getupvalue"><code>debug.getupvalue (func, up)
</code></a></h3>
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.
8327 <hr><h3><a name=
"pdf-debug.setfenv"><code>debug.setfenv (object, table)
</code></a></h3>
8331 Sets the environment of the given
<code>object
</code> to the given
<code>table
</code>.
8332 Returns
<code>object
</code>.
8338 <hr><h3><a name=
"pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])
</code></a></h3>
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:
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>
8353 With a
<code>count
</code> different from zero,
8354 the hook is called after every
<code>count
</code> instructions.
8358 When called without arguments,
8359 <a href=
"#pdf-debug.sethook"><code>debug.sethook
</code></a> turns off the hook.
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>.
8369 the hook also gets the new line number as its second parameter.
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.
8383 <hr><h3><a name=
"pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)
</code></a></h3>
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.
8399 <hr><h3><a name=
"pdf-debug.setmetatable"><code>debug.setmetatable (object, table)
</code></a></h3>
8403 Sets the metatable for the given
<code>object
</code> to the given
<code>table
</code>
8404 (which can be
<b>nil
</b>).
8410 <hr><h3><a name=
"pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)
</code></a></h3>
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.
8424 <hr><h3><a name=
"pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])
</code></a></h3>
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>).
8441 <h1>6 -
<a name=
"6">Lua Stand-alone
</a></h1>
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.
8455 lua [options] [script [args]]
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>
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.
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.
8484 All options are handled in order, except
<code>-i
</code>.
8485 For instance, an invocation like
8488 $ lua -e'a=
1' -e 'print(a)' script.lua
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.)
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,
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
8508 $ lua -la b.lua t1 t2
8510 the interpreter first runs the file
<code>a.lua
</code>,
8511 then creates a table
8514 arg = { [-
2] = "lua", [-
1] = "-la",
8516 [
1] = "t1", [
2] = "t2" }
8518 and finally runs the file
<code>b.lua
</code>.
8519 The script is called with
<code>arg[
1]
</code>,
<code>arg[
2]
</code>,
···
8521 it can also access these arguments with the vararg expression '
<code>...
</code>'.
8525 In interactive mode,
8526 if you write an incomplete statement,
8527 the interpreter waits for its completion
8528 by issuing a different prompt.
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:
8542 $ lua -e"_PROMPT='myprompt
> '" -i
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;
8548 the program would just end silently
8549 right after the assignment to
<code>_PROMPT
</code>.
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,
8562 #!/usr/local/bin/lua
8565 the location of the Lua interpreter may be different in your machine.
8566 If
<code>lua
</code> is in your
<code>PATH
</code>,
8572 is a more portable solution.)
8576 <h1>7 -
<a name=
"7">Incompatibilities with the Previous Version
</a></h1>
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>).
8584 all these compatibility options will be removed in the next version of Lua.
8588 <h2>7.1 -
<a name=
"7.1">Changes in the Language
</a></h2>
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>.)
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.
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>.)
8614 <h2>7.2 -
<a name=
"7.2">Changes in the Libraries
</a></h2>
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>.)
8623 When
<a href=
"#pdf-string.gsub"><code>string.gsub
</code></a> is called with a function as its
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.
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>.)
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>.)
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>.)
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.
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>.
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.
8672 <h2>7.3 -
<a name=
"7.3">Changes in the API
</a></h2>
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.
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>).
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>.
8699 Function
<code>luaL_openlib
</code> was replaced by
<a href=
"#luaL_register"><code>luaL_register
</code></a>.
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>.)
8713 <h1>8 -
<a name=
"8">The Complete Syntax of Lua
</a></h1>
8716 Here is the complete syntax of Lua in extended BNF.
8717 (It does not describe operator precedences.)
8724 chunk ::= {stat [`
<b>;
</b>´]} [laststat [`
<b>;
</b>´]]
8728 stat ::= varlist `
<b>=
</b>´ explist |
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]
8740 laststat ::=
<b>return
</b> [explist] |
<b>break
</b>
8742 funcname ::= Name {`
<b>.
</b>´ Name} [`
<b>:
</b>´ Name]
8744 varlist ::= var {`
<b>,
</b>´ var}
8746 var ::= Name | prefixexp `
<b>[
</b>´ exp `
<b>]
</b>´ | prefixexp `
<b>.
</b>´ Name
8748 namelist ::= Name {`
<b>,
</b>´ Name}
8750 explist ::= {exp `
<b>,
</b>´} exp
8752 exp ::=
<b>nil
</b> |
<b>false
</b> |
<b>true
</b> | Number | String | `
<b>...
</b>´ | function |
8753 prefixexp | tableconstructor | exp binop exp | unop exp
8755 prefixexp ::= var | functioncall | `
<b>(
</b>´ exp `
<b>)
</b>´
8757 functioncall ::= prefixexp args | prefixexp `
<b>:
</b>´ Name args
8759 args ::= `
<b>(
</b>´ [explist] `
<b>)
</b>´ | tableconstructor | String
8761 function ::=
<b>function
</b> funcbody
8763 funcbody ::= `
<b>(
</b>´ [parlist] `
<b>)
</b>´ block
<b>end
</b>
8765 parlist ::= namelist [`
<b>,
</b>´ `
<b>...
</b>´] | `
<b>...
</b>´
8767 tableconstructor ::= `
<b>{
</b>´ [fieldlist] `
<b>}
</b>´
8769 fieldlist ::= field {fieldsep field} [fieldsep]
8771 field ::= `
<b>[
</b>´ exp `
<b>]
</b>´ `
<b>=
</b>´ exp | Name `
<b>=
</b>´ exp | exp
8773 fieldsep ::= `
<b>,
</b>´ | `
<b>;
</b>´
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>
8779 unop ::= `
<b>-
</b>´ |
<b>not
</b> | `
<b>#
</b>´
8794 Mon Aug
18 13:
25:
46 BRT
2008
8797 Last change: revised for Lua 5.1.4
projects / redis.git / blob