From 2369d00d467b6a8c97a74e8ac3f42ead3653daf6 Mon Sep 17 00:00:00 2001 From: "Yichun Zhang (agentzh)" Date: Wed, 29 Jun 2016 13:05:36 -0700 Subject: [PATCH] feature: added the Lua 5.1 reference manual from lua 5.1.5 to our restydoc indexes. --- doc/lua-5.1.5/README.pod | 5878 ++++++++++++++++++++++++++++++++++++++ util/mirror-tarballs | 3 + 2 files changed, 5881 insertions(+) create mode 100644 doc/lua-5.1.5/README.pod diff --git a/doc/lua-5.1.5/README.pod b/doc/lua-5.1.5/README.pod new file mode 100644 index 0000000..e3be730 --- /dev/null +++ b/doc/lua-5.1.5/README.pod @@ -0,0 +1,5878 @@ +=pod + +=encoding utf8 + + +=head1 Lua 5.1 Reference Manual + +by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes + +Copyright E 2006E2012 Lua.org, PUC-Rio. Freely available +under the terms of the Lua license. + + +contents E index E other versions + +=head1 1 - Introduction + +Lua is an extension programming language designed to support general +procedural programming with data description facilities. It also offers +good support for object-oriented programming, functional programming, +and data-driven programming. Lua is intended to be used as a powerful, +light-weight scripting language for any program that needs one. Lua is +implemented as a library, written in I C (that is, in the common +subset of ANSI C and C++). + +Being an extension language, Lua has no notion of a "main" program: it +only works I in a host client, called the I or simply the I. This host program can invoke functions +to execute a piece of Lua code, can write and read Lua variables, and +can register C functions to be called by Lua code. Through the use of C +functions, Lua can be augmented to cope with a wide range of different +domains, thus creating customized programming languages sharing a +syntactical framework. The Lua distribution includes a sample host +program called C, which uses the Lua library to offer a complete, +stand-alone Lua interpreter. + +Lua is free software, and is provided as usual with no guarantees, as +stated in its license. The implementation described in this manual is +available at Lua's official web site, C. + +Like any other reference manual, this document is dry in places. For a +discussion of the decisions behind the design of Lua, see the technical +papers available at Lua's web site. For a detailed introduction to +programming in Lua, see Roberto's book, I. + +=head1 2 - The Language + +This section describes the lexis, the syntax, and the semantics of Lua. +In other words, this section describes which tokens are valid, how they +can be combined, and what their combinations mean. + +The language constructs will be explained using the usual extended BNF +notation, in which {I} means 0 or more I's, and [I] means an +optional I. Non-terminals are shown like non-terminal, keywords are +shown like B, and other terminal symbols are shown like +`B<=>E. The complete syntax of Lua can be found in E8 at +the end of this manual. + +=head2 2.1 - Lexical Conventions + +I (also called I) in Lua can be any string of +letters, digits, and underscores, not beginning with a digit. This +coincides with the definition of names in most languages. (The +definition of letter depends on the current locale: any character +considered alphabetic by the current locale can be used in an +identifier.) Identifiers are used to name variables and table fields. + +The following I are reserved and cannot be used as names: + + and break do else elseif + end false for function if + in local nil not or + repeat return then true until while + +Lua is a case-sensitive language: C is a reserved word, but C +and C are two different, valid names. As a convention, names +starting with an underscore followed by uppercase letters (such as +C<_VERSION>) are reserved for internal global variables used by Lua. + +The following strings denote other tokens: + + + - * / % ^ # + == ~= <= >= < > = + ( ) { } [ ] + ; : , . .. ... + +I can be delimited by matching single or double +quotes, and can contain the following C-like escape sequences: 'C<\a>' +(bell), 'C<\b>' (backspace), 'C<\f>' (form feed), 'C<\n>' (newline), +'C<\r>' (carriage return), 'C<\t>' (horizontal tab), 'C<\v>' (vertical +tab), 'C<\\>' (backslash), 'C<\">' (quotation mark [double quote]), and +'C<\'>' (apostrophe [single quote]). Moreover, a backslash followed by +a real newline results in a newline in the string. A character in a +string can also be specified by its numerical value using the escape +sequence C<\I>, where I is a sequence of up to three decimal +digits. (Note that if a numerical escape is to be followed by a digit, +it must be expressed using exactly three digits.) Strings in Lua can +contain any 8-bit value, including embedded zeros, which can be +specified as 'C<\0>'. + +Literal strings can also be defined using a long format enclosed by +I. We define an I> as +an opening square bracket followed by I equal signs followed by +another opening square bracket. So, an opening long bracket of level 0 +is written as C<[[>, an opening long bracket of level 1 is written as +C<[=[>, and so on. A I is defined similarly; for +instance, a closing long bracket of level 4 is written as C<]====]>. A +long string starts with an opening long bracket of any level and ends +at the first closing long bracket of the same level. Literals in this +bracketed form can run for several lines, do not interpret any escape +sequences, and ignore long brackets of any other level. They can +contain anything except a closing bracket of the proper level. + +For convenience, when the opening long bracket is immediately followed +by a newline, the newline is not included in the string. As an example, +in a system using ASCII (in which 'C' is coded as 97, newline is +coded as 10, and 'C<1>' is coded as 49), the five literal strings below +denote the same string: + + a = 'alo\n123"' + a = "alo\n123\"" + a = '\97lo\10\04923"' + a = [[alo + 123"]] + a = [==[ + alo + 123"]==] + +A I can be written with an optional decimal part +and an optional decimal exponent. Lua also accepts integer hexadecimal +constants, by prefixing them with C<0x>. Examples of valid numerical +constants are + + 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 + +A I starts with a double hyphen (C<-->) anywhere outside a +string. If the text immediately after C<--> is not an opening long +bracket, the comment is a I, which runs until the end of +the line. Otherwise, it is a I, which runs until the +corresponding closing long bracket. Long comments are frequently used +to disable code temporarily. + +=head2 2.2 - Values and Types + +Lua is a I. This means that variables do +not have types; only values do. There are no type definitions in the +language. All values carry their own type. + +All values in Lua are I. This means that all values +can be stored in variables, passed as arguments to other functions, and +returned as results. + +There are eight basic types in Lua: I, I, I, +I, I, I, I, and I. I is +the type of the value B, whose main property is to be different +from any other value; it usually represents the absence of a useful +value. I is the type of the values B and B. Both +B and B make a condition false; any other value makes it +true. I represents real (double-precision floating-point) +numbers. (It is easy to build Lua interpreters that use other internal +representations for numbers, such as single-precision float or long +integers; see file C.) I represents arrays of +characters. Lua is 8-bit clean: strings can contain any 8-bit +character, including embedded zeros ('C<\0>') (see E2.1). + +Lua can call (and manipulate) functions written in Lua and functions +written in C (see E2.5.8). + +The type I is provided to allow arbitrary C data to be stored +in Lua variables. This type corresponds to a block of raw memory and +has no pre-defined operations in Lua, except assignment and identity +test. However, by using I, the programmer can define +operations for userdata values (see E2.8). Userdata values cannot +be created or modified in Lua, only through the C API. This guarantees +the integrity of data owned by the host program. + +The type I represents independent threads of execution and it +is used to implement coroutines (see E2.11). Do not confuse Lua +threads with operating-system threads. Lua supports coroutines on all +systems, even those that do not support threads. + +The type I
implements associative arrays, that is, arrays that +can be indexed not only with numbers, but with any value (except +B). Tables can be I; that is, they can contain +values of all types (except B). Tables are the sole data +structuring mechanism in Lua; they can be used to represent ordinary +arrays, symbol tables, sets, records, graphs, trees, etc. To represent +records, Lua uses the field name as an index. The language supports +this representation by providing C as syntactic sugar for +C. There are several convenient ways to create tables in Lua +(see E2.5.7). + +Like indices, the value of a table field can be of any type (except +B). In particular, because functions are first-class values, table +fields can contain functions. Thus tables can also carry I +(see E2.5.9). + +Tables, functions, threads, and (full) userdata values are I: +variables do not actually I these values, only I +to them. Assignment, parameter passing, and function returns always +manipulate references to such values; these operations do not imply any +kind of copy. + +The library function C returns a string describing the type of a +given value. + +=head2 2.2.1 - Coercion + +Lua provides automatic conversion between string and number values at +run time. Any arithmetic operation applied to a string tries to convert +this string to a number, following the usual conversion rules. +Conversely, whenever a number is used where a string is expected, the +number is converted to a string, in a reasonable format. For complete +control over how numbers are converted to strings, use the C +function from the string library (see C). + +=head2 2.3 - Variables + +Variables are places that store values. There are three kinds of +variables in Lua: global variables, local variables, and table fields. + +A single name can denote a global variable or a local variable (or a +function's formal parameter, which is a particular kind of local +variable): + + var ::= Name + +Name denotes identifiers, as defined in E2.1. + +Any variable is assumed to be global unless explicitly declared as a +local (see E2.4.7). Local variables are I: +local variables can be freely accessed by functions defined inside +their scope (see E2.6). + +Before the first assignment to a variable, its value is B. + +Square brackets are used to index a table: + + var ::= prefixexp `[´ exp `]´ + +The meaning of accesses to global variables and table fields can be +changed via metatables. An access to an indexed variable C is +equivalent to a call C. (See E2.8 for a +complete description of the C function. This function +is not defined or callable in Lua. We use it here only for explanatory +purposes.) + +The syntax C is just syntactic sugar for C: + + var ::= prefixexp `.´ Name + +All global variables live as fields in ordinary Lua tables, called +I or simply I (see E2.9). Each +function has its own reference to an environment, so that all global +variables in this function will refer to this environment table. When a +function is created, it inherits the environment from the function that +created it. To get the environment table of a Lua function, you call +C. To replace it, you call C. (You can only +manipulate the environment of C functions through the debug library; +(see E5.9).) + +An access to a global variable C is equivalent to C<_env.x>, which +in turn is equivalent to + + gettable_event(_env, "x") + +where C<_env> is the environment of the running function. (See +E2.8 for a complete description of the C +function. This function is not defined or callable in Lua. Similarly, +the C<_env> variable is not defined in Lua. We use them here only for +explanatory purposes.) + +=head2 2.4 - Statements + +Lua supports an almost conventional set of statements, similar to those +in Pascal or C. This set includes assignments, control structures, +function calls, and variable declarations. + +=head2 2.4.1 - Chunks + +The unit of execution of Lua is called a I. A chunk is simply a +sequence of statements, which are executed sequentially. Each statement +can be optionally followed by a semicolon: + + chunk ::= {stat [`;´]} + +There are no empty statements and thus 'C<;;>' is not legal. + +Lua handles a chunk as the body of an anonymous function with a +variable number of arguments (see E2.5.9). As such, chunks can +define local variables, receive arguments, and return values. + +A chunk can be stored in a file or in a string inside the host program. +To execute a chunk, Lua first pre-compiles the chunk into instructions +for a virtual machine, and then it executes the compiled code with an +interpreter for the virtual machine. + +Chunks can also be pre-compiled into binary form; see program C +for details. Programs in source and compiled forms are interchangeable; +Lua automatically detects the file type and acts accordingly. + +=head2 2.4.2 - Blocks + +A block is a list of statements; syntactically, a block is the same as +a chunk: + + block ::= chunk + +A block can be explicitly delimited to produce a single statement: + + stat ::= do block end + +Explicit blocks are useful to control the scope of variable +declarations. Explicit blocks are also sometimes used to add a +B or B statement in the middle of another block (see +E2.4.4). + +=head2 2.4.3 - Assignment + +Lua allows multiple assignments. Therefore, the syntax for assignment +defines a list of variables on the left side and a list of expressions +on the right side. The elements in both lists are separated by commas: + + stat ::= varlist `=´ explist + varlist ::= var {`,´ var} + explist ::= exp {`,´ exp} + +Expressions are discussed in E2.5. + +Before the assignment, the list of values is I to the length +of the list of variables. If there are more values than needed, the +excess values are thrown away. If there are fewer values than needed, +the list is extended with as many B's as needed. If the list of +expressions ends with a function call, then all values returned by that +call enter the list of values, before the adjustment (except when the +call is enclosed in parentheses; see E2.5). + +The assignment statement first evaluates all its expressions and only +then are the assignments performed. Thus the code + + i = 3 + i, a[i] = i+1, 20 + +sets C to 20, without affecting C because the C in +C is evaluated (to 3) before it is assigned 4. Similarly, the +line + + x, y = y, x + +exchanges the values of C and C, and + + x, y, z = y, z, x + +cyclically permutes the values of C, C, and C. + +The meaning of assignments to global variables and table fields can be +changed via metatables. An assignment to an indexed variable C is equivalent to C. (See E2.8 for a +complete description of the C function. This function +is not defined or callable in Lua. We use it here only for explanatory +purposes.) + +An assignment to a global variable C is equivalent to the +assignment C<_env.x = val>, which in turn is equivalent to + + settable_event(_env, "x", val) + +where C<_env> is the environment of the running function. (The C<_env> +variable is not defined in Lua. We use it here only for explanatory +purposes.) + +=head2 2.4.4 - Control Structures + +The control structures B, B, and B have the usual +meaning and familiar syntax: + + stat ::= while exp do block end + stat ::= repeat block until exp + stat ::= if exp then block {elseif exp then block} [else block] end + +Lua also has a B statement, in two flavors (see E2.4.5). + +The condition expression of a control structure can return any value. +Both B and B are considered false. All values different +from B and B are considered true (in particular, the number +0 and the empty string are also true). + +In the BEB loop, the inner block does not end at +the B keyword, but only after the condition. So, the condition +can refer to local variables declared inside the loop block. + +The B statement is used to return values from a function or a +chunk (which is just a function). Functions and chunks can return more +than one value, and so the syntax for the B statement is + + stat ::= return [explist] + +The B statement is used to terminate the execution of a +B, B, or B loop, skipping to the next statement +after the loop: + + stat ::= break + +A B ends the innermost enclosing loop. + +The B and B statements can only be written as the +I statement of a block. If it is really necessary to B or +B in the middle of a block, then an explicit inner block can be +used, as in the idioms C and C, because +now B and B are the last statements in their (inner) +blocks. + +=head2 2.4.5 - For Statement + +The B statement has two forms: one numeric and one generic. + +The numeric B loop repeats a block of code while a control +variable runs through an arithmetic progression. It has the following +syntax: + + stat ::= for Name `=´ exp `,´ exp [`,´ exp] do block end + +The I is repeated for I starting at the value of the first +I, until it passes the second I by steps of the third I. +More precisely, a B statement like + + for v = e1, e2, e3 do block end + +is equivalent to the code: + + do + local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3) + if not (var and limit and step) then error() end + while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do + local v = var + block + var = var + step + end + end + +Note the following: + +=over + +=item * All three control expressions are evaluated only once, before +the loop starts. They must all result in numbers. + +=item * C>, C>, and C> are invisible variables. +The names shown here are for explanatory purposes only. + +=item * If the third expression (the step) is absent, then a step of 1 +is used. + +=item * You can use B to exit a B loop. + +=item * The loop variable C is local to the loop; you cannot use its +value after the B ends or is broken. If you need this value, +assign it to another variable before breaking or exiting the loop. + +=back + +The generic B statement works over functions, called I. +On each iteration, the iterator function is called to produce a new +value, stopping when this new value is B. The generic B loop +has the following syntax: + + stat ::= for namelist in explist do block end + namelist ::= Name {`,´ Name} + +A B statement like + + for var_1, ···, var_n in explist do block end + +is equivalent to the code: + + do + local f, s, var = explist + while true do + local var_1, ···, var_n = f(s, var) + var = var_1 + if var == nil then break end + block + end + end + +Note the following: + +=over + +=item * C> is evaluated only once. Its results are an +I function, a I, and an initial value for the first +I. + +=item * C>, C>, and C> are invisible variables. The +names are here for explanatory purposes only. + +=item * You can use B to exit a B loop. + +=item * The loop variables C> are local to the loop; you +cannot use their values after the B ends. If you need these +values, then assign them to other variables before breaking or exiting +the loop. + +=back + +=head2 2.4.6 - Function Calls as Statements + +To allow possible side-effects, function calls can be executed as +statements: + + stat ::= functioncall + +In this case, all returned values are thrown away. Function calls are +explained in E2.5.8. + +=head2 2.4.7 - Local Declarations + +Local variables can be declared anywhere inside a block. The +declaration can include an initial assignment: + + stat ::= local namelist [`=´ explist] + +If present, an initial assignment has the same semantics of a multiple +assignment (see E2.4.3). Otherwise, all variables are initialized +with B. + +A chunk is also a block (see E2.4.1), and so local variables can +be declared in a chunk outside any explicit block. The scope of such +local variables extends until the end of the chunk. + +The visibility rules for local variables are explained in E2.6. + +=head2 2.5 - Expressions + +The basic expressions in Lua are the following: + + exp ::= prefixexp + exp ::= nil | false | true + exp ::= Number + exp ::= String + exp ::= function + exp ::= tableconstructor + exp ::= `...´ + exp ::= exp binop exp + exp ::= unop exp + prefixexp ::= var | functioncall | `(´ exp `)´ + +Numbers and literal strings are explained in E2.1; variables are +explained in E2.3; function definitions are explained in +E2.5.9; function calls are explained in E2.5.8; table +constructors are explained in E2.5.7. Vararg expressions, denoted +by three dots ('C<...>'), can only be used when directly inside a +vararg function; they are explained in E2.5.9. + +Binary operators comprise arithmetic operators (see E2.5.1), +relational operators (see E2.5.2), logical operators (see +E2.5.3), and the concatenation operator (see E2.5.4). Unary +operators comprise the unary minus (see E2.5.1), the unary B +(see E2.5.3), and the unary I (see +E2.5.5). + +Both function calls and vararg expressions can result in multiple +values. If an expression is used as a statement (only possible for +function calls (see E2.4.6)), then its return list is adjusted to +zero elements, thus discarding all returned values. If an expression is +used as the last (or the only) element of a list of expressions, then +no adjustment is made (unless the call is enclosed in parentheses). In +all other contexts, Lua adjusts the result list to one element, +discarding all values except the first one. + +Here are some examples: + + f() -- adjusted to 0 results + g(f(), x) -- f() is adjusted to 1 result + g(x, f()) -- g gets x plus all results from f() + a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) + a,b = ... -- a gets the first vararg parameter, b gets + -- the second (both a and b can get nil if there + -- is no corresponding vararg parameter) + + a,b,c = x, f() -- f() is adjusted to 2 results + a,b,c = f() -- f() is adjusted to 3 results + return f() -- returns all results from f() + return ... -- returns all received vararg parameters + return x,y,f() -- returns x, y, and all results from f() + {f()} -- creates a list with all results from f() + {...} -- creates a list with all vararg parameters + {f(), nil} -- f() is adjusted to 1 result + +Any expression enclosed in parentheses always results in only one +value. Thus, C<(f(x,y,z))> is always a single value, even if C +returns several values. (The value of C<(f(x,y,z))> is the first value +returned by C or B if C does not return any values.) + +=head2 2.5.1 - Arithmetic Operators + +Lua supports the usual arithmetic operators: the binary C<+> +(addition), C<-> (subtraction), C<*> (multiplication), C (division), +C<%> (modulo), and C<^> (exponentiation); and unary C<-> (negation). If +the operands are numbers, or strings that can be converted to numbers +(see E2.2.1), then all operations have the usual meaning. +Exponentiation works for any exponent. For instance, C +computes the inverse of the square root of C. Modulo is defined as + + a % b == a - math.floor(a/b)*b + +That is, it is the remainder of a division that rounds the quotient +towards minus infinity. + +=head2 2.5.2 - Relational Operators + +The relational operators in Lua are + + == ~= < > <= >= + +These operators always result in B or B. + +Equality (C<==>) first compares the type of its operands. If the types +are different, then the result is B. Otherwise, the values of +the operands are compared. Numbers and strings are compared in the +usual way. Objects (tables, userdata, threads, and functions) are +compared by I: two objects are considered equal only if they +are the I object. Every time you create a new object (a table, +userdata, thread, or function), this new object is different from any +previously existing object. + +You can change the way that Lua compares tables and userdata by using +the "eq" metamethod (see E2.8). + +The conversion rules of E2.2.1 I apply to equality +comparisons. Thus, C<"0"==0> evaluates to B, and C and +C denote different entries in a table. + +The operator C<~=> is exactly the negation of equality (C<==>). + +The order operators work as follows. If both arguments are numbers, +then they are compared as such. Otherwise, if both arguments are +strings, then their values are compared according to the current +locale. Otherwise, Lua tries to call the "lt" or the "le" metamethod +(see E2.8). A comparison C b> is translated to C +a> and C= b> is translated to C= a>. + +=head2 2.5.3 - Logical Operators + +The logical operators in Lua are B, B, and B. Like the +control structures (see E2.4.4), all logical operators consider +both B and B as false and anything else as true. + +The negation operator B always returns B or B. The +conjunction operator B returns its first argument if this value is +B or B; otherwise, B returns its second argument. The +disjunction operator B returns its first argument if this value is +different from B and B; otherwise, B returns its second +argument. Both B and B use short-cut evaluation; that is, the +second operand is evaluated only if necessary. Here are some examples: + + 10 or 20 --> 10 + 10 or error() --> 10 + nil or "a" --> "a" + nil and 10 --> nil + false and error() --> false + false and nil --> false + false or nil --> nil + 10 and 20 --> 20 + +(In this manual, C<--E> indicates the result of the preceding +expression.) + +=head2 2.5.4 - Concatenation + +The string concatenation operator in Lua is denoted by two dots +('C<..>'). If both operands are strings or numbers, then they are +converted to strings according to the rules mentioned in E2.2.1. +Otherwise, the "concat" metamethod is called (see E2.8). + +=head2 2.5.5 - The Length Operator + +The length operator is denoted by the unary operator C<#>. The length +of a string is its number of bytes (that is, the usual meaning of +string length when each character is one byte). + +The length of a table C is defined to be any integer index C such +that C is not B and C is B; moreover, if +C is B, C can be zero. For a regular array, with non-nil +values from 1 to a given C, its length is exactly that C, the +index of its last value. If the array has "holes" (that is, B +values between other non-nil values), then C<#t> can be any of the +indices that directly precedes a B value (that is, it may consider +any such B value as the end of the array). + +=head2 2.5.6 - Precedence + +Operator precedence in Lua follows the table below, from lower to +higher priority: + + or + and + < > <= >= ~= == + .. + + - + * / % + not # - (unary) + ^ + +As usual, you can use parentheses to change the precedences of an +expression. The concatenation ('C<..>') and exponentiation ('C<^>') +operators are right associative. All other binary operators are left +associative. + +=head2 2.5.7 - Table Constructors + +Table constructors are expressions that create tables. Every time a +constructor is evaluated, a new table is created. A constructor can be +used to create an empty table or to create a table and initialize some +of its fields. The general syntax for constructors is + + tableconstructor ::= `{´ [fieldlist] `}´ + fieldlist ::= field {fieldsep field} [fieldsep] + field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp + fieldsep ::= `,´ | `;´ + +Each field of the form C<[exp1] = exp2> adds to the new table an entry +with key C and value C. A field of the form C +is equivalent to C<["name"] = exp>. Finally, fields of the form C +are equivalent to C<[i] = exp>, where C are consecutive numerical +integers, starting with 1. Fields in the other formats do not affect +this counting. For example, + + a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } + +is equivalent to + + do + local t = {} + t[f(1)] = g + t[1] = "x" -- 1st exp + t[2] = "y" -- 2nd exp + t.x = 1 -- t["x"] = 1 + t[3] = f(x) -- 3rd exp + t[30] = 23 + t[4] = 45 -- 4th exp + a = t + end + +If the last field in the list has the form C and the expression is +a function call or a vararg expression, then all values returned by +this expression enter the list consecutively (see E2.5.8). To +avoid this, enclose the function call or the vararg expression in +parentheses (see E2.5). + +The field list can have an optional trailing separator, as a +convenience for machine-generated code. + +=head2 2.5.8 - Function Calls + +A function call in Lua has the following syntax: + + functioncall ::= prefixexp args + +In a function call, first prefixexp and args are evaluated. If the +value of prefixexp has type I, then this function is called +with the given arguments. Otherwise, the prefixexp "call" metamethod is +called, having as first parameter the value of prefixexp, followed by +the original call arguments (see E2.8). + +The form + + functioncall ::= prefixexp `:´ Name args + +can be used to call "methods". A call C)> is syntactic +sugar for C)>, except that C is evaluated only +once. + +Arguments have the following syntax: + + args ::= `(´ [explist] `)´ + args ::= tableconstructor + args ::= String + +All argument expressions are evaluated before the call. A call of the +form C}> is syntactic sugar for C})>; that is, +the argument list is a single new table. A call of the form +C'> (or C"> or C]]>) is syntactic +sugar for C')>; that is, the argument list is a single +literal string. + +As an exception to the free-format syntax of Lua, you cannot put a line +break before the 'C<(>' in a function call. This restriction avoids +some ambiguities in the language. If you write + + a = f + (g).x(a) + +Lua would see that as a single statement, C. So, if you +want two statements, you must add a semi-colon between them. If you +actually want to call C, you must remove the line break before +C<(g)>. + +A call of the form C I is called a I. +Lua implements I (or I): in a +tail call, the called function reuses the stack entry of the calling +function. Therefore, there is no limit on the number of nested tail +calls that a program can execute. However, a tail call erases any debug +information about the calling function. Note that a tail call only +happens with a particular syntax, where the B has one single +function call as argument; this syntax makes the calling function +return exactly the returns of the called function. So, none of the +following examples are tail calls: + + return (f(x)) -- results adjusted to 1 + return 2 * f(x) + return x, f(x) -- additional results + f(x); return -- results discarded + return x or f(x) -- results adjusted to 1 + +=head2 2.5.9 - Function Definitions + +The syntax for function definition is + + function ::= function funcbody + funcbody ::= `(´ [parlist] `)´ block end + +The following syntactic sugar simplifies function definitions: + + stat ::= function funcname funcbody + stat ::= local function Name funcbody + funcname ::= Name {`.´ Name} [`:´ Name] + +The statement + + function f () body end + +translates to + + f = function () body end + +The statement + + function t.a.b.c.f () body end + +translates to + + t.a.b.c.f = function () body end + +The statement + + local function f () body end + +translates to + + local f; f = function () body end + +I to + + local f = function () body end + +(This only makes a difference when the body of the function contains +references to C.) + +A function definition is an executable expression, whose value has type +I. When Lua pre-compiles a chunk, all its function bodies are +pre-compiled too. Then, whenever Lua executes the function definition, +the function is I (or I). This function instance +(or I) is the final value of the expression. Different +instances of the same function can refer to different external local +variables and can have different environment tables. + +Parameters act as local variables that are initialized with the +argument values: + + parlist ::= namelist [`,´ `...´] | `...´ + +When a function is called, the list of arguments is adjusted to the +length of the list of parameters, unless the function is a variadic or +I, which is indicated by three dots ('C<...>') at the +end of its parameter list. A vararg function does not adjust its +argument list; instead, it collects all extra arguments and supplies +them to the function through a I, which is also +written as three dots. The value of this expression is a list of all +actual extra arguments, similar to a function with multiple results. If +a vararg expression is used inside another expression or in the middle +of a list of expressions, then its return list is adjusted to one +element. If the expression is used as the last element of a list of +expressions, then no adjustment is made (unless that last expression is +enclosed in parentheses). + +As an example, consider the following definitions: + + function f(a, b) end + function g(a, b, ...) end + function r() return 1,2,3 end + +Then, we have the following mapping from arguments to parameters and to +the vararg expression: + + CALL PARAMETERS + + f(3) a=3, b=nil + f(3, 4) a=3, b=4 + f(3, 4, 5) a=3, b=4 + f(r(), 10) a=1, b=10 + f(r()) a=1, b=2 + + g(3) a=3, b=nil, ... --> (nothing) + g(3, 4) a=3, b=4, ... --> (nothing) + g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 + g(5, r()) a=5, b=1, ... --> 2 3 + +Results are returned using the B statement (see E2.4.4). +If control reaches the end of a function without encountering a +B statement, then the function returns with no results. + +The I syntax is used for defining I, that is, functions +that have an implicit extra parameter C. Thus, the statement + + function t.a.b.c:f (params) body end + +is syntactic sugar for + + t.a.b.c.f = function (self, params) body end + +=head2 2.6 - Visibility Rules + +Lua is a lexically scoped language. The scope of variables begins at +the first statement I their declaration and lasts until the end +of the innermost block that includes the declaration. Consider the +following example: + + x = 10 -- global variable + do -- new block + local x = x -- new 'x', with value 10 + print(x) --> 10 + x = x+1 + do -- another block + local x = x+1 -- another 'x' + print(x) --> 12 + end + print(x) --> 11 + end + print(x) --> 10 (the global one) + +Notice that, in a declaration like C, the new C being +declared is not in scope yet, and so the second C refers to the +outside variable. + +Because of the lexical scoping rules, local variables can be freely +accessed by functions defined inside their scope. A local variable used +by an inner function is called an I, or I, inside the inner function. + +Notice that each execution of a B statement defines new local +variables. Consider the following example: + + a = {} + local x = 20 + for i=1,10 do + local y = 0 + a[i] = function () y=y+1; return x+y end + end + +The loop creates ten closures (that is, ten instances of the anonymous +function). Each of these closures uses a different C variable, while +all of them share the same C. + +=head2 2.7 - Error Handling + +Because Lua is an embedded extension language, all Lua actions start +from C code in the host program calling a function from the Lua library +(see C). Whenever an error occurs during Lua compilation or +execution, control returns to C, which can take appropriate measures +(such as printing an error message). + +Lua code can explicitly generate an error by calling the C +function. If you need to catch errors in Lua, you can use the C +function. + +=head2 2.8 - Metatables + +Every value in Lua can have a I. This I is an +ordinary Lua table that defines the behavior of the original value +under certain special operations. You can change several aspects of the +behavior of operations over a value by setting specific fields in its +metatable. For instance, when a non-numeric value is the operand of an +addition, Lua checks for a function in the field C<"__add"> in its +metatable. If it finds one, Lua calls this function to perform the +addition. + +We call the keys in a metatable I and the values +I. In the previous example, the event is C<"add"> and the +metamethod is the function that performs the addition. + +You can query the metatable of any value through the C +function. + +You can replace the metatable of tables through the C +function. You cannot change the metatable of other types from Lua +(except by using the debug library); you must use the C API for that. + +Tables and full userdata have individual metatables (although multiple +tables and userdata can share their metatables). Values of all other +types share one single metatable per type; that is, there is one single +metatable for all numbers, one for all strings, etc. + +A metatable controls how an object behaves in arithmetic operations, +order comparisons, concatenation, length operation, and indexing. A +metatable also can define a function to be called when a userdata is +garbage collected. For each of these operations Lua associates a +specific key called an I. When Lua performs one of these +operations over a value, it checks whether this value has a metatable +with the corresponding event. If so, the value associated with that key +(the metamethod) controls how Lua will perform the operation. + +Metatables control the operations listed next. Each operation is +identified by its corresponding name. The key for each operation is a +string with its name prefixed by two underscores, 'C<__>'; for +instance, the key for operation "add" is the string C<"__add">. The +semantics of these operations is better explained by a Lua function +describing how the interpreter executes the operation. + +The code shown here in Lua is only illustrative; the real behavior is +hard coded in the interpreter and it is much more efficient than this +simulation. All functions used in these descriptions (C, +C, etc.) are described in E5.1. In particular, to +retrieve the metamethod of a given object, we use the expression + + metatable(obj)[event] + +This should be read as + + rawget(getmetatable(obj) or {}, event) + +That is, the access to a metamethod does not invoke other metamethods, +and the access to objects with no metatables does not fail (it simply +results in B). + +=over + +=item * B<"add":> the C<+> operation. + +The function C below defines how Lua chooses a handler +for a binary operation. First, Lua tries the first operand. If its type +does not define a handler for the operation, then Lua tries the second +operand. + + function getbinhandler (op1, op2, event) + return metatable(op1)[event] or metatable(op2)[event] + end + +By using this function, the behavior of the C is + + function add_event (op1, op2) + local o1, o2 = tonumber(op1), tonumber(op2) + if o1 and o2 then -- both operands are numeric? + return o1 + o2 -- '+' here is the primitive 'add' + else -- at least one of the operands is not numeric + local h = getbinhandler(op1, op2, "__add") + if h then + -- call the handler with both operands + return (h(op1, op2)) + else -- no handler available: default behavior + error(···) + end + end + end + +=item * B<"sub":> the C<-> operation. Behavior similar to the "add" +operation. + +=item * B<"mul":> the C<*> operation. Behavior similar to the "add" +operation. + +=item * B<"div":> the C operation. Behavior similar to the "add" +operation. + +=item * B<"mod":> the C<%> operation. Behavior similar to the "add" +operation, with the operation C as the primitive +operation. + +=item * B<"pow":> the C<^> (exponentiation) operation. Behavior similar +to the "add" operation, with the function C (from the C math +library) as the primitive operation. + +=item * B<"unm":> the unary C<-> operation. + + function unm_event (op) + local o = tonumber(op) + if o then -- operand is numeric? + return -o -- '-' here is the primitive 'unm' + else -- the operand is not numeric. + -- Try to get a handler from the operand + local h = metatable(op).__unm + if h then + -- call the handler with the operand + return (h(op)) + else -- no handler available: default behavior + error(···) + end + end + end + +=item * B<"concat":> the C<..> (concatenation) operation. + + function concat_event (op1, op2) + if (type(op1) == "string" or type(op1) == "number") and + (type(op2) == "string" or type(op2) == "number") then + return op1 .. op2 -- primitive string concatenation + else + local h = getbinhandler(op1, op2, "__concat") + if h then + return (h(op1, op2)) + else + error(···) + end + end + end + +=item * B<"len":> the C<#> operation. + + function len_event (op) + if type(op) == "string" then + return strlen(op) -- primitive string length + elseif type(op) == "table" then + return #op -- primitive table length + else + local h = metatable(op).__len + if h then + -- call the handler with the operand + return (h(op)) + else -- no handler available: default behavior + error(···) + end + end + end + +See E2.5.5 for a description of the length of a table. + +=item * B<"eq":> the C<==> operation. The function C +defines how Lua chooses a metamethod for comparison operators. A +metamethod only is selected when both objects being compared have the +same type and the same metamethod for the selected operation. + + function getcomphandler (op1, op2, event) + if type(op1) ~= type(op2) then return nil end + local mm1 = metatable(op1)[event] + local mm2 = metatable(op2)[event] + if mm1 == mm2 then return mm1 else return nil end + end + +The "eq" event is defined as follows: + + function eq_event (op1, op2) + if type(op1) ~= type(op2) then -- different types? + return false -- different objects + end + if op1 == op2 then -- primitive equal? + return true -- objects are equal + end + -- try metamethod + local h = getcomphandler(op1, op2, "__eq") + if h then + return (h(op1, op2)) + else + return false + end + end + +C is equivalent to C. + +=item * B<"lt":> the C> operation. + + function lt_event (op1, op2) + if type(op1) == "number" and type(op2) == "number" then + return op1 < op2 -- numeric comparison + elseif type(op1) == "string" and type(op2) == "string" then + return op1 < op2 -- lexicographic comparison + else + local h = getcomphandler(op1, op2, "__lt") + if h then + return (h(op1, op2)) + else + error(···) + end + end + end + +C b> is equivalent to C a>. + +=item * B<"le":> the C=> operation. + + function le_event (op1, op2) + if type(op1) == "number" and type(op2) == "number" then + return op1 <= op2 -- numeric comparison + elseif type(op1) == "string" and type(op2) == "string" then + return op1 <= op2 -- lexicographic comparison + else + local h = getcomphandler(op1, op2, "__le") + if h then + return (h(op1, op2)) + else + h = getcomphandler(op1, op2, "__lt") + if h then + return not h(op2, op1) + else + error(···) + end + end + end + end + +C= b> is equivalent to C= a>. Note that, in the absence +of a "le" metamethod, Lua tries the "lt", assuming that C= b> +is equivalent to C a)>. + +=item * B<"index":> The indexing access C. + + function gettable_event (table, key) + local h + if type(table) == "table" then + local v = rawget(table, key) + if v ~= nil then return v end + h = metatable(table).__index + if h == nil then return nil end + else + h = metatable(table).__index + if h == nil then + error(···) + end + end + if type(h) == "function" then + return (h(table, key)) -- call the handler + else return h[key] -- or repeat operation on it + end + end + +=item * B<"newindex":> The indexing assignment C. + + function settable_event (table, key, value) + local h + if type(table) == "table" then + local v = rawget(table, key) + if v ~= nil then rawset(table, key, value); return end + h = metatable(table).__newindex + if h == nil then rawset(table, key, value); return end + else + h = metatable(table).__newindex + if h == nil then + error(···) + end + end + if type(h) == "function" then + h(table, key,value) -- call the handler + else h[key] = value -- or repeat operation on it + end + end + +=item * B<"call":> called when Lua calls a value. + + function function_event (func, ...) + if type(func) == "function" then + return func(...) -- primitive call + else + local h = metatable(func).__call + if h then + return h(func, ...) + else + error(···) + end + end + end + +=back + +=head2 2.9 - Environments + +Besides metatables, objects of types thread, function, and userdata +have another table associated with them, called their I. +Like metatables, environments are regular tables and multiple objects +can share the same environment. + +Threads are created sharing the environment of the creating thread. +Userdata and C functions are created sharing the environment of the +creating C function. Non-nested Lua functions (created by C, +C or C) are created sharing the environment of the +creating thread. Nested Lua functions are created sharing the +environment of the creating Lua function. + +Environments associated with userdata have no meaning for Lua. It is +only a convenience feature for programmers to associate a table to a +userdata. + +Environments associated with threads are called I. +They are used as the default environment for threads and non-nested Lua +functions created by the thread and can be directly accessed by C code +(see E3.3). + +The environment associated with a C function can be directly accessed +by C code (see E3.3). It is used as the default environment for +other C functions and userdata created by the function. + +Environments associated with Lua functions are used to resolve all +accesses to global variables within the function (see E2.3). They +are used as the default environment for nested Lua functions created by +the function. + +You can change the environment of a Lua function or the running thread +by calling C. You can get the environment of a Lua function or +the running thread by calling C. To manipulate the environment +of other objects (userdata, C functions, other threads) you must use +the C API. + +=head2 2.10 - Garbage Collection + +Lua performs automatic memory management. This means that you have to +worry neither about allocating memory for new objects nor about freeing +it when the objects are no longer needed. Lua manages memory +automatically by running a I from time to time to +collect all I (that is, objects that are no longer +accessible from Lua). All memory used by Lua is subject to automatic +management: tables, userdata, functions, threads, strings, etc. + +Lua implements an incremental mark-and-sweep collector. It uses two +numbers to control its garbage-collection cycles: the +I and the I. Both use percentage points as units (so that a value of +100 means an internal value of 1). + +The garbage-collector pause controls how long the collector waits +before starting a new cycle. Larger values make the collector less +aggressive. Values smaller than 100 mean the collector will not wait to +start a new cycle. A value of 200 means that the collector waits for +the total memory in use to double before starting a new cycle. + +The step multiplier controls the relative speed of the collector +relative to memory allocation. Larger values make the collector more +aggressive but also increase the size of each incremental step. Values +smaller than 100 make the collector too slow and can result in the +collector never finishing a cycle. The default, 200, means that the +collector runs at "twice" the speed of memory allocation. + +You can change these numbers by calling C in C or +C in Lua. With these functions you can also control the +collector directly (e.g., stop and restart it). + +=head2 2.10.1 - Garbage-Collection Metamethods + +Using the C API, you can set garbage-collector metamethods for userdata +(see E2.8). These metamethods are also called I. +Finalizers allow you to coordinate Lua's garbage collection with +external resource management (such as closing files, network or +database connections, or freeing your own memory). + +Garbage userdata with a field C<__gc> in their metatables are not +collected immediately by the garbage collector. Instead, Lua puts them +in a list. After the collection, Lua does the equivalent of the +following function for each userdata in that list: + + function gc_event (udata) + local h = metatable(udata).__gc + if h then + h(udata) + end + end + +At the end of each garbage-collection cycle, the finalizers for +userdata are called in I order of their creation, among those +collected in that cycle. That is, the first finalizer to be called is +the one associated with the userdata created last in the program. The +userdata itself is freed only in the next garbage-collection cycle. + +=head2 2.10.2 - Weak Tables + +A I is a table whose elements are I. A +weak reference is ignored by the garbage collector. In other words, if +the only references to an object are weak references, then the garbage +collector will collect this object. + +A weak table can have weak keys, weak values, or both. A table with +weak keys allows the collection of its keys, but prevents the +collection of its values. A table with both weak keys and weak values +allows the collection of both keys and values. In any case, if either +the key or the value is collected, the whole pair is removed from the +table. The weakness of a table is controlled by the C<__mode> field of +its metatable. If the C<__mode> field is a string containing the +character 'C', the keys in the table are weak. If C<__mode> contains +'C', the values in the table are weak. + +After you use a table as a metatable, you should not change the value +of its C<__mode> field. Otherwise, the weak behavior of the tables +controlled by this metatable is undefined. + +=head2 2.11 - Coroutines + +Lua supports coroutines, also called I. A +coroutine in Lua represents an independent thread of execution. Unlike +threads in multithread systems, however, a coroutine only suspends its +execution by explicitly calling a yield function. + +You create a coroutine with a call to C. Its sole +argument is a function that is the main function of the coroutine. The +C function only creates a new coroutine and returns a handle to +it (an object of type I); it does not start the coroutine +execution. + +When you first call C, passing as its first argument +a thread returned by C, the coroutine starts its +execution, at the first line of its main function. Extra arguments +passed to C are passed on to the coroutine main +function. After the coroutine starts running, it runs until it +terminates or I. + +A coroutine can terminate its execution in two ways: normally, when its +main function returns (explicitly or implicitly, after the last +instruction); and abnormally, if there is an unprotected error. In the +first case, C returns B, plus any values +returned by the coroutine main function. In case of errors, +C returns B plus an error message. + +A coroutine yields by calling C. When a coroutine +yields, the corresponding C returns immediately, even +if the yield happens inside nested function calls (that is, not in the +main function, but in a function directly or indirectly called by the +main function). In the case of a yield, C also +returns B, plus any values passed to C. The next +time you resume the same coroutine, it continues its execution from the +point where it yielded, with the call to C returning +any extra arguments passed to C. + +Like C, the C function also creates a +coroutine, but instead of returning the coroutine itself, it returns a +function that, when called, resumes the coroutine. Any arguments passed +to this function go as extra arguments to C. +C returns all the values returned by +C, except the first one (the boolean error code). +Unlike C, C does not catch errors; +any error is propagated to the caller. + +As an example, consider the following code: + + function foo (a) + print("foo", a) + return coroutine.yield(2*a) + end + + co = coroutine.create(function (a,b) + print("co-body", a, b) + local r = foo(a+1) + print("co-body", r) + local r, s = coroutine.yield(a+b, a-b) + print("co-body", r, s) + return b, "end" + end) + + print("main", coroutine.resume(co, 1, 10)) + print("main", coroutine.resume(co, "r")) + print("main", coroutine.resume(co, "x", "y")) + print("main", coroutine.resume(co, "x", "y")) + +When you run it, it produces the following output: + + co-body 1 10 + foo 2 + + main true 4 + co-body r + main true 11 -9 + co-body x y + main true 10 end + main false cannot resume dead coroutine + +=head1 3 - The Application Program Interface + +This section describes the C API for Lua, that is, the set of C +functions available to the host program to communicate with Lua. All +API functions and related types and constants are declared in the +header file C. + +Even when we use the term "function", any facility in the API may be +provided as a macro instead. All such macros use each of their +arguments exactly once (except for the first argument, which is always +a Lua state), and so do not generate any hidden side-effects. + +As in most C libraries, the Lua API functions do not check their +arguments for validity or consistency. However, you can change this +behavior by compiling Lua with a proper definition for the macro +C, in file C. + +=head2 3.1 - The Stack + +Lua uses a I to pass values to and from C. Each element +in this stack represents a Lua value (B, number, string, etc.). + +Whenever Lua calls C, the called function gets a new stack, which is +independent of previous stacks and of stacks of C functions that are +still active. This stack initially contains any arguments to the C +function and it is where the C function pushes its results to be +returned to the caller (see C). + +For convenience, most query operations in the API do not follow a +strict stack discipline. Instead, they can refer to any element in the +stack by using an I: A positive index represents an I +stack position (starting at 1); a negative index represents an +I relative to the top of the stack. More specifically, if the +stack has I elements, then index 1 represents the first element +(that is, the element that was pushed onto the stack first) and index +I represents the last element; index -1 also represents the last +element (that is, the element at the top) and index I<-n> represents +the first element. We say that an index is I if it lies between +1 and the stack top (that is, if C<1 E abs(index) E top>). + +=head2 3.2 - Stack Size + +When you interact with Lua API, you are responsible for ensuring +consistency. In particular, I. You can use the function C to grow the stack +size. + +Whenever Lua calls C, it ensures that at least C stack +positions are available. C is defined as 20, so that +usually you do not have to worry about stack space unless your code has +loops pushing elements onto the stack. + +Most query functions accept as indices any value inside the available +stack space, that is, indices up to the maximum stack size you have set +through C. Such indices are called I. More formally, we define an I as follows: + + (index < 0 && abs(index) <= top) || + (index > 0 && index <= stackspace) + +Note that 0 is never an acceptable index. + +=head2 3.3 - Pseudo-Indices + +Unless otherwise noted, any function that accepts valid indices can +also be called with I, which represent some Lua values +that are accessible to C code but which are not in the stack. +Pseudo-indices are used to access the thread environment, the function +environment, the registry, and the upvalues of a C function (see +E3.4). + +The thread environment (where global variables live) is always at +pseudo-index C. The environment of the running C +function is always at pseudo-index C. + +To access and change the value of global variables, you can use regular +table operations over an environment table. For instance, to access the +value of a global variable, do + + lua_getfield(L, LUA_GLOBALSINDEX, varname); + +=head2 3.4 - C Closures + +When a C function is created, it is possible to associate some values +with it, thus creating a I; these values are called +I and are accessible to the function whenever it is called +(see C). + +Whenever a C function is called, its upvalues are located at specific +pseudo-indices. These pseudo-indices are produced by the macro +C. The first value associated with a function is at +position C, and so on. Any access to +C)>, where I is greater than the number of +upvalues of the current function (but not greater than 256), produces +an acceptable (but invalid) index. + +=head2 3.5 - Registry + +Lua provides a I, a pre-defined table that can be used by any +C code to store whatever Lua value it needs to store. This table is +always located at pseudo-index C. Any C library can +store data into this table, but it should take care to choose keys +different from those used by other libraries, to avoid collisions. +Typically, you should use as key a string containing your library name +or a light userdata with the address of a C object in your code. + +The integer keys in the registry are used by the reference mechanism, +implemented by the auxiliary library, and therefore should not be used +for other purposes. + +=head2 3.6 - Error Handling in C + +Internally, Lua uses the C C facility to handle errors. (You +can also choose to use exceptions if you use C++; see file +C.) When Lua faces any error (such as memory allocation +errors, type errors, syntax errors, and runtime errors) it I an +error; that is, it does a long jump. A I uses +C to set a recover point; any error jumps to the most recent +active recover point. + +Most functions in the API can throw an error, for instance due to a +memory allocation error. The documentation for each function indicates +whether it can throw errors. + +Inside a C function you can throw an error by calling C. + +=head2 3.7 - Functions and Types + +Here we list all functions and types from the C API in alphabetical +order. Each function has an indicator like this: [-o, +p, I] + +The first field, C, is how many elements the function pops from the +stack. The second field, C

, is how many elements the function pushes +onto the stack. (Any function always pushes its results after popping +its arguments.) A field in the form C means the function can push +(or pop) C or C elements, depending on the situation; an +interrogation mark 'C' means that we cannot know how many elements +the function pops/pushes by looking only at its arguments (e.g., they +may depend on what is on the stack). The third field, C, tells +whether the function may throw errors: 'C<->' means the function never +throws any error; 'C' means the function may throw an error only due +to not enough memory; 'C' means the function may throw other kinds +of errors; 'C' means the function may throw an error on purpose. + + +=head2 C + + typedef void * (*lua_Alloc) (void *ud, + void *ptr, + size_t osize, + size_t nsize); + +The type of the memory-allocation function used by Lua states. The +allocator function must provide a functionality similar to C, +but not exactly the same. Its arguments are C, an opaque pointer +passed to C; C, a pointer to the block being +allocated/reallocated/freed; C, the original size of the block; +C, the new size of the block. C is C if and only if +C is zero. When C is zero, the allocator must return +C; if C is not zero, it should free the block pointed to +by C. When C is not zero, the allocator returns C if +and only if it cannot fill the request. When C is not zero and +C is zero, the allocator should behave like C. When +C and C are not zero, the allocator behaves like +C. Lua assumes that the allocator never fails when C= nsize>. + +Here is a simple implementation for the allocator function. It is used +in the auxiliary library by C. + + static void *l_alloc (void *ud, void *ptr, size_t osize, + size_t nsize) { + (void)ud; (void)osize; /* not used */ + if (nsize == 0) { + free(ptr); + return NULL; + } + else + return realloc(ptr, nsize); + } + +This code assumes that C has no effect and that +C is equivalent to C. ANSI C ensures +both behaviors. + + +=head2 C + +[-0, +0, I<->] + + lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); + +Sets a new panic function and returns the old one. + +If an error happens outside any protected environment, Lua calls a +I and then calls C, thus exiting +the host application. Your panic function can avoid this exit by never +returning (e.g., doing a long jump). + +The panic function can access the error message at the top of the +stack. + + +=head2 C + +[-(nargs + 1), +nresults, I] + + void lua_call (lua_State *L, int nargs, int nresults); + +Calls a function. + +To call a function you must use the following protocol: first, the +function to be called is pushed onto the stack; then, the arguments to +the function are pushed in direct order; that is, the first argument is +pushed first. Finally you call C; C is the number of +arguments that you pushed onto the stack. All arguments and the +function value are popped from the stack when the function is called. +The function results are pushed onto the stack when the function +returns. The number of results is adjusted to C, unless +C is C. In this case, I results from the +function are pushed. Lua takes care that the returned values fit into +the stack space. The function results are pushed onto the stack in +direct order (the first result is pushed first), so that after the call +the last result is on the top of the stack. + +Any error inside the called function is propagated upwards (with a +C). + +The following example shows how the host program can do the equivalent +to this Lua code: + + a = f("how", t.x, 14) + +Here it is in C: + + lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ + lua_pushstring(L, "how"); /* 1st argument */ + lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ + lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ + lua_remove(L, -2); /* remove 't' from the stack */ + lua_pushinteger(L, 14); /* 3rd argument */ + lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ + lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ + +Note that the code above is "balanced": at its end, the stack is back +to its original configuration. This is considered good programming +practice. + + +=head2 C + + typedef int (*lua_CFunction) (lua_State *L); + +Type for C functions. + +In order to communicate properly with Lua, a C function must use the +following protocol, which defines the way parameters and results are +passed: a C function receives its arguments from Lua in its stack in +direct order (the first argument is pushed first). So, when the +function starts, C returns the number of arguments +received by the function. The first argument (if any) is at index 1 and +its last argument is at index C. To return values to +Lua, a C function just pushes them onto the stack, in direct order (the +first result is pushed first), and returns the number of results. Any +other value in the stack below the results will be properly discarded +by Lua. Like a Lua function, a C function called by Lua can also return +many results. + +As an example, the following function receives a variable number of +numerical arguments and returns their average and sum: + + static int foo (lua_State *L) { + int n = lua_gettop(L); /* number of arguments */ + lua_Number sum = 0; + int i; + for (i = 1; i <= n; i++) { + if (!lua_isnumber(L, i)) { + lua_pushstring(L, "incorrect argument"); + lua_error(L); + } + sum += lua_tonumber(L, i); + } + lua_pushnumber(L, sum/n); /* first result */ + lua_pushnumber(L, sum); /* second result */ + return 2; /* number of results */ + } + + +=head2 C + +[-0, +0, I] + + int lua_checkstack (lua_State *L, int extra); + +Ensures that there are at least C free stack slots in the stack. +It returns false if it cannot grow the stack to that size. This +function never shrinks the stack; if the stack is already larger than +the new size, it is left unchanged. + + +=head2 C + +[-0, +0, I<->] + + void lua_close (lua_State *L); + +Destroys all objects in the given Lua state (calling the corresponding +garbage-collection metamethods, if any) and frees all dynamic memory +used by this state. On several platforms, you may not need to call this +function, because all resources are naturally released when the host +program ends. On the other hand, long-running programs, such as a +daemon or a web server, might need to release states as soon as they +are not needed, to avoid growing too large. + + +=head2 C + +[-n, +1, I] + + void lua_concat (lua_State *L, int n); + +Concatenates the C values at the top of the stack, pops them, and +leaves the result at the top. If C is 1, the result is the single +value on the stack (that is, the function does nothing); if C is 0, +the result is the empty string. Concatenation is performed following +the usual semantics of Lua (see E2.5.4). + + +=head2 C + +[-0, +(0|1), I<->] + + int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); + +Calls the C function C in protected mode. C starts with +only one element in its stack, a light userdata containing C. In +case of errors, C returns the same error codes as +C, plus the error object on the top of the stack; otherwise, +it returns zero, and does not change the stack. All values returned by +C are discarded. + + +=head2 C + +[-0, +1, I] + + void lua_createtable (lua_State *L, int narr, int nrec); + +Creates a new empty table and pushes it onto the stack. The new table +has space pre-allocated for C array elements and C +non-array elements. This pre-allocation is useful when you know exactly +how many elements the table will have. Otherwise you can use the +function C. + + +=head2 C + +[-0, +0, I] + + int lua_dump (lua_State *L, lua_Writer writer, void *data); + +Dumps a function as a binary chunk. Receives a Lua function on the top +of the stack and produces a binary chunk that, if loaded again, results +in a function equivalent to the one dumped. As it produces parts of the +chunk, C calls function C (see C) with +the given C to write them. + +The value returned is the error code returned by the last call to the +writer; 0 means no errors. + +This function does not pop the Lua function from the stack. + + +=head2 C + +[-0, +0, I] + + int lua_equal (lua_State *L, int index1, int index2); + +Returns 1 if the two values in acceptable indices C and +C are equal, following the semantics of the Lua C<==> operator +(that is, may call metamethods). Otherwise returns 0. Also returns 0 if +any of the indices is non valid. + + +=head2 C + +[-1, +0, I] + + int lua_error (lua_State *L); + +Generates a Lua error. The error message (which can actually be a Lua +value of any type) must be on the stack top. This function does a long +jump, and therefore never returns. (see C). + + +=head2 C + +[-0, +0, I] + + int lua_gc (lua_State *L, int what, int data); + +Controls the garbage collector. + +This function performs several tasks, according to the value of the +parameter C: + +=over + +=item * B:> stops the garbage collector. + +=item * B:> restarts the garbage collector. + +=item * B:> performs a full garbage-collection cycle. + +=item * B:> returns the current amount of memory (in +Kbytes) in use by Lua. + +=item * B:> returns the remainder of dividing the +current amount of bytes of memory in use by Lua by 1024. + +=item * B:> performs an incremental step of garbage +collection. The step "size" is controlled by C (larger values +mean more steps) in a non-specified way. If you want to control the +step size you must experimentally tune the value of C. The +function returns 1 if the step finished a garbage-collection cycle. + +=item * B:> sets C as the new value for the +I of the collector (see E2.10). The function returns the +previous value of the pause. + +=item * B:> sets C as the new value for the +I of the collector (see E2.10). The function +returns the previous value of the step multiplier. + +=back + + +=head2 C + +[-0, +0, I<->] + + lua_Alloc lua_getallocf (lua_State *L, void **ud); + +Returns the memory-allocation function of a given state. If C is +not C, Lua stores in C<*ud> the opaque pointer passed to +C. + + +=head2 C + +[-0, +1, I<->] + + void lua_getfenv (lua_State *L, int index); + +Pushes onto the stack the environment table of the value at the given +index. + + +=head2 C + +[-0, +1, I] + + void lua_getfield (lua_State *L, int index, const char *k); + +Pushes onto the stack the value C, where C is the value at the +given valid index. As in Lua, this function may trigger a metamethod +for the "index" event (see E2.8). + + +=head2 C + +[-0, +1, I] + + void lua_getglobal (lua_State *L, const char *name); + +Pushes onto the stack the value of the global C. It is defined as +a macro: + + #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) + + +=head2 C + +[-0, +(0|1), I<->] + + int lua_getmetatable (lua_State *L, int index); + +Pushes onto the stack the metatable of the value at the given +acceptable index. If the index is not valid, or if the value does not +have a metatable, the function returns 0 and pushes nothing on the +stack. + + +=head2 C + +[-1, +1, I] + + void lua_gettable (lua_State *L, int index); + +Pushes onto the stack the value C, where C is the value at the +given valid index and C is the value at the top of the stack. + +This function pops the key from the stack (putting the resulting value +in its place). As in Lua, this function may trigger a metamethod for +the "index" event (see E2.8). + + +=head2 C + +[-0, +0, I<->] + + int lua_gettop (lua_State *L); + +Returns the index of the top element in the stack. Because indices +start at 1, this result is equal to the number of elements in the stack +(and so 0 means an empty stack). + + +=head2 C + +[-1, +1, I<->] + + void lua_insert (lua_State *L, int index); + +Moves the top element into the given valid index, shifting up the +elements above this index to open space. Cannot be called with a +pseudo-index, because a pseudo-index is not an actual stack position. + + +=head2 C + + typedef ptrdiff_t lua_Integer; + +The type used by the Lua API to represent integral values. + +By default it is a C, which is usually the largest signed +integral type the machine handles "comfortably". + + +=head2 C + +[-0, +0, I<->] + + int lua_isboolean (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index has type boolean, +and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_iscfunction (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a C function, +and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isfunction (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a function +(either C or Lua), and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_islightuserdata (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a light +userdata, and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isnil (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is B, and 0 +otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isnone (lua_State *L, int index); + +Returns 1 if the given acceptable index is not valid (that is, it +refers to an element outside the current stack), and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isnoneornil (lua_State *L, int index); + +Returns 1 if the given acceptable index is not valid (that is, it +refers to an element outside the current stack) or if the value at this +index is B, and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isnumber (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a number or a +string convertible to a number, and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isstring (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a string or a +number (which is always convertible to a string), and 0 otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_istable (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a table, and 0 +otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isthread (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a thread, and 0 +otherwise. + + +=head2 C + +[-0, +0, I<->] + + int lua_isuserdata (lua_State *L, int index); + +Returns 1 if the value at the given acceptable index is a userdata +(either full or light), and 0 otherwise. + + +=head2 C + +[-0, +0, I] + + int lua_lessthan (lua_State *L, int index1, int index2); + +Returns 1 if the value at acceptable index C is smaller than +the value at acceptable index C, following the semantics of the +Lua C> operator (that is, may call metamethods). Otherwise +returns 0. Also returns 0 if any of the indices is non valid. + + +=head2 C + +[-0, +1, I<->] + + int lua_load (lua_State *L, + lua_Reader reader, + void *data, + const char *chunkname); + +Loads a Lua chunk. If there are no errors, C pushes the +compiled chunk as a Lua function on top of the stack. Otherwise, it +pushes an error message. The return values of C are: + +=over + +=item * B<0:> no errors; + +=item * B:> syntax error during pre-compilation; + +=item * B:> memory allocation error. + +=back + +This function only loads a chunk; it does not run it. + +C automatically detects whether the chunk is text or binary, +and loads it accordingly (see program C). + +The C function uses a user-supplied C function to +read the chunk (see C). The C argument is an opaque +value passed to the reader function. + +The C argument gives a name to the chunk, which is used for +error messages and in debug information (see E3.8). + + +=head2 C + +[-0, +0, I<->] + + lua_State *lua_newstate (lua_Alloc f, void *ud); + +Creates a new, independent state. Returns C if cannot create the +state (due to lack of memory). The argument C is the allocator +function; Lua does all memory allocation for this state through this +function. The second argument, C, is an opaque pointer that Lua +simply passes to the allocator in every call. + + +=head2 C + +[-0, +1, I] + + void lua_newtable (lua_State *L); + +Creates a new empty table and pushes it onto the stack. It is +equivalent to C. + + +=head2 C + +[-0, +1, I] + + lua_State *lua_newthread (lua_State *L); + +Creates a new thread, pushes it on the stack, and returns a pointer to +a C that represents this new thread. The new state returned +by this function shares with the original state all global objects +(such as tables), but has an independent execution stack. + +There is no explicit function to close or to destroy a thread. Threads +are subject to garbage collection, like any Lua object. + + +=head2 C + +[-0, +1, I] + + void *lua_newuserdata (lua_State *L, size_t size); + +This function allocates a new block of memory with the given size, +pushes onto the stack a new full userdata with the block address, and +returns this address. + +Userdata represent C values in Lua. A I represents a +block of memory. It is an object (like a table): you must create it, it +can have its own metatable, and you can detect when it is being +collected. A full userdata is only equal to itself (under raw +equality). + +When Lua collects a full userdata with a C metamethod, Lua calls +the metamethod and marks the userdata as finalized. When this userdata +is collected again then Lua frees its corresponding memory. + + +=head2 C + +[-1, +(2|0), I] + + int lua_next (lua_State *L, int index); + +Pops a key from the stack, and pushes a key-value pair from the table +at the given index (the "next" pair after the given key). If there are +no more elements in the table, then C returns 0 (and pushes +nothing). + +A typical traversal looks like this: + + /* table is in the stack at index 't' */ + lua_pushnil(L); /* first key */ + while (lua_next(L, t) != 0) { + /* uses 'key' (at index -2) and 'value' (at index -1) */ + printf("%s - %s\n", + lua_typename(L, lua_type(L, -2)), + lua_typename(L, lua_type(L, -1))); + /* removes 'value'; keeps 'key' for next iteration */ + lua_pop(L, 1); + } + +While traversing a table, do not call C directly on a +key, unless you know that the key is actually a string. Recall that +C I the value at the given index; this confuses +the next call to C. + + +=head2 C + + typedef double lua_Number; + +The type of numbers in Lua. By default, it is double, but that can be +changed in C. + +Through the configuration file you can change Lua to operate with +another type for numbers (e.g., float or long). + + +=head2 C + +[-0, +0, I<->] + + size_t lua_objlen (lua_State *L, int index); + +Returns the "length" of the value at the given acceptable index: for +strings, this is the string length; for tables, this is the result of +the length operator ('C<#>'); for userdata, this is the size of the +block of memory allocated for the userdata; for other values, it is 0. + + +=head2 C + +[-(nargs + 1), +(nresults|1), I<->] + + int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); + +Calls a function in protected mode. + +Both C and C have the same meaning as in C. +If there are no errors during the call, C behaves exactly +like C. However, if there is any error, C catches +it, pushes a single value on the stack (the error message), and returns +an error code. Like C, C always removes the +function and its arguments from the stack. + +If C is 0, then the error message returned on the stack is +exactly the original error message. Otherwise, C is the stack +index of an I. (In the current implementation, +this index cannot be a pseudo-index.) In case of runtime errors, this +function will be called with the error message and its return value +will be the message returned on the stack by C. + +Typically, the error handler function is used to add more debug +information to the error message, such as a stack traceback. Such +information cannot be gathered after the return of C, since +by then the stack has unwound. + +The C function returns 0 in case of success or one of the +following error codes (defined in C): + +=over + +=item * B:> a runtime error. + +=item * B:> memory allocation error. For such errors, Lua +does not call the error handler function. + +=item * B:> error while running the error handler +function. + +=back + + +=head2 C + +[-n, +0, I<->] + + void lua_pop (lua_State *L, int n); + +Pops C elements from the stack. + + +=head2 C + +[-0, +1, I<->] + + void lua_pushboolean (lua_State *L, int b); + +Pushes a boolean value with value C onto the stack. + + +=head2 C + +[-n, +1, I] + + void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); + +Pushes a new C closure onto the stack. + +When a C function is created, it is possible to associate some values +with it, thus creating a C closure (see E3.4); these values are +then accessible to the function whenever it is called. To associate +values with a C function, first these values should be pushed onto the +stack (when there are multiple values, the first value is pushed +first). Then C is called to create and push the C +function onto the stack, with the argument C telling how many values +should be associated with the function. C also pops +these values from the stack. + +The maximum value for C is 255. + + +=head2 C + +[-0, +1, I] + + void lua_pushcfunction (lua_State *L, lua_CFunction f); + +Pushes a C function onto the stack. This function receives a pointer to +a C function and pushes onto the stack a Lua value of type C +that, when called, invokes the corresponding C function. + +Any function to be registered in Lua must follow the correct protocol +to receive its parameters and return its results (see +C). + +C is defined as a macro: + + #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) + + +=head2 C + +[-0, +1, I] + + const char *lua_pushfstring (lua_State *L, const char *fmt, ...); + +Pushes onto the stack a formatted string and returns a pointer to this +string. It is similar to the C function C, but has some +important differences: + +=over + +=item * You do not have to allocate space for the result: the result is +a Lua string and Lua takes care of memory allocation (and deallocation, +through garbage collection). + +=item * The conversion specifiers are quite restricted. There are no +flags, widths, or precisions. The conversion specifiers can only be +'C<%%>' (inserts a 'C<%>' in the string), 'C<%s>' (inserts a +zero-terminated string, with no size restrictions), 'C<%f>' (inserts a +C), 'C<%p>' (inserts a pointer as a hexadecimal numeral), +'C<%d>' (inserts an C), and 'C<%c>' (inserts an C as a +character). + +=back + + +=head2 C + +[-0, +1, I<->] + + void lua_pushinteger (lua_State *L, lua_Integer n); + +Pushes a number with value C onto the stack. + + +=head2 C + +[-0, +1, I<->] + + void lua_pushlightuserdata (lua_State *L, void *p); + +Pushes a light userdata onto the stack. + +Userdata represent C values in Lua. A I represents a +pointer. It is a value (like a number): you do not create it, it has no +individual metatable, and it is not collected (as it was never +created). A light userdata is equal to "any" light userdata with the +same C address. + + +=head2 C + +[-0, +1, I] + + void lua_pushliteral (lua_State *L, const char *s); + +This macro is equivalent to C, but can be used only +when C is a literal string. In these cases, it automatically +provides the string length. + + +=head2 C + +[-0, +1, I] + + void lua_pushlstring (lua_State *L, const char *s, size_t len); + +Pushes the string pointed to by C with size C onto the stack. +Lua makes (or reuses) an internal copy of the given string, so the +memory at C can be freed or reused immediately after the function +returns. The string can contain embedded zeros. + + +=head2 C + +[-0, +1, I<->] + + void lua_pushnil (lua_State *L); + +Pushes a nil value onto the stack. + + +=head2 C + +[-0, +1, I<->] + + void lua_pushnumber (lua_State *L, lua_Number n); + +Pushes a number with value C onto the stack. + + +=head2 C + +[-0, +1, I] + + void lua_pushstring (lua_State *L, const char *s); + +Pushes the zero-terminated string pointed to by C onto the stack. +Lua makes (or reuses) an internal copy of the given string, so the +memory at C can be freed or reused immediately after the function +returns. The string cannot contain embedded zeros; it is assumed to end +at the first zero. + + +=head2 C + +[-0, +1, I<->] + + int lua_pushthread (lua_State *L); + +Pushes the thread represented by C onto the stack. Returns 1 if this +thread is the main thread of its state. + + +=head2 C + +[-0, +1, I<->] + + void lua_pushvalue (lua_State *L, int index); + +Pushes a copy of the element at the given valid index onto the stack. + + +=head2 C + +[-0, +1, I] + + const char *lua_pushvfstring (lua_State *L, + const char *fmt, + va_list argp); + +Equivalent to C, except that it receives a C +instead of a variable number of arguments. + + +=head2 C + +[-0, +0, I<->] + + int lua_rawequal (lua_State *L, int index1, int index2); + +Returns 1 if the two values in acceptable indices C and +C are primitively equal (that is, without calling metamethods). +Otherwise returns 0. Also returns 0 if any of the indices are non +valid. + + +=head2 C + +[-1, +1, I<->] + + void lua_rawget (lua_State *L, int index); + +Similar to C, but does a raw access (i.e., without +metamethods). + + +=head2 C + +[-0, +1, I<->] + + void lua_rawgeti (lua_State *L, int index, int n); + +Pushes onto the stack the value C, where C is the value at the +given valid index. The access is raw; that is, it does not invoke +metamethods. + + +=head2 C + +[-2, +0, I] + + void lua_rawset (lua_State *L, int index); + +Similar to C, but does a raw assignment (i.e., without +metamethods). + + +=head2 C + +[-1, +0, I] + + void lua_rawseti (lua_State *L, int index, int n); + +Does the equivalent of C, where C is the value at the +given valid index and C is the value at the top of the stack. + +This function pops the value from the stack. The assignment is raw; +that is, it does not invoke metamethods. + + +=head2 C + + typedef const char * (*lua_Reader) (lua_State *L, + void *data, + size_t *size); + +The reader function used by C. Every time it needs another +piece of the chunk, C calls the reader, passing along its +C parameter. The reader must return a pointer to a block of +memory with a new piece of the chunk and set C to the block size. +The block must exist until the reader function is called again. To +signal the end of the chunk, the reader must return C or set +C to zero. The reader function may return pieces of any size +greater than zero. + + +=head2 C + +[-0, +0, I] + + void lua_register (lua_State *L, + const char *name, + lua_CFunction f); + +Sets the C function C as the new value of global C. It is +defined as a macro: + + #define lua_register(L,n,f) \ + (lua_pushcfunction(L, f), lua_setglobal(L, n)) + + +=head2 C + +[-1, +0, I<->] + + void lua_remove (lua_State *L, int index); + +Removes the element at the given valid index, shifting down the +elements above this index to fill the gap. Cannot be called with a +pseudo-index, because a pseudo-index is not an actual stack position. + + +=head2 C + +[-1, +0, I<->] + + void lua_replace (lua_State *L, int index); + +Moves the top element into the given position (and pops it), without +shifting any element (therefore replacing the value at the given +position). + + +=head2 C + +[-?, +?, I<->] + + int lua_resume (lua_State *L, int narg); + +Starts and resumes a coroutine in a given thread. + +To start a coroutine, you first create a new thread (see +C); then you push onto its stack the main function plus +any arguments; then you call C, with C being the +number of arguments. This call returns when the coroutine suspends or +finishes its execution. When it returns, the stack contains all values +passed to C, or all values returned by the body function. +C returns C if the coroutine yields, 0 if the +coroutine finishes its execution without errors, or an error code in +case of errors (see C). In case of errors, the stack is not +unwound, so you can use the debug API over it. The error message is on +the top of the stack. To restart a coroutine, you put on its stack only +the values to be passed as results from C, and then call +C. + + +=head2 C + +[-0, +0, I<->] + + void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); + +Changes the allocator function of a given state to C with user data +C. + + +=head2 C + +[-1, +0, I<->] + + int lua_setfenv (lua_State *L, int index); + +Pops a table from the stack and sets it as the new environment for the +value at the given index. If the value at the given index is neither a +function nor a thread nor a userdata, C returns 0. +Otherwise it returns 1. + + +=head2 C + +[-1, +0, I] + + void lua_setfield (lua_State *L, int index, const char *k); + +Does the equivalent to C, where C is the value at the +given valid index and C is the value at the top of the stack. + +This function pops the value from the stack. As in Lua, this function +may trigger a metamethod for the "newindex" event (see E2.8). + + +=head2 C + +[-1, +0, I] + + void lua_setglobal (lua_State *L, const char *name); + +Pops a value from the stack and sets it as the new value of global +C. It is defined as a macro: + + #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) + + +=head2 C + +[-1, +0, I<->] + + int lua_setmetatable (lua_State *L, int index); + +Pops a table from the stack and sets it as the new metatable for the +value at the given acceptable index. + + +=head2 C + +[-2, +0, I] + + void lua_settable (lua_State *L, int index); + +Does the equivalent to C, where C is the value at the +given valid index, C is the value at the top of the stack, and C +is the value just below the top. + +This function pops both the key and the value from the stack. As in +Lua, this function may trigger a metamethod for the "newindex" event +(see E2.8). + + +=head2 C + +[-?, +?, I<->] + + void lua_settop (lua_State *L, int index); + +Accepts any acceptable index, or 0, and sets the stack top to this +index. If the new top is larger than the old one, then the new elements +are filled with B. If C is 0, then all stack elements are +removed. + + +=head2 C + + typedef struct lua_State lua_State; + +Opaque structure that keeps the whole state of a Lua interpreter. The +Lua library is fully reentrant: it has no global variables. All +information about a state is kept in this structure. + +A pointer to this state must be passed as the first argument to every +function in the library, except to C, which creates a Lua +state from scratch. + + +=head2 C + +[-0, +0, I<->] + + int lua_status (lua_State *L); + +Returns the status of the thread C. + +The status can be 0 for a normal thread, an error code if the thread +finished its execution with an error, or C if the thread is +suspended. + + +=head2 C + +[-0, +0, I<->] + + int lua_toboolean (lua_State *L, int index); + +Converts the Lua value at the given acceptable index to a C boolean +value (0 or 1). Like all tests in Lua, C returns 1 for +any Lua value different from B and B; otherwise it returns +0. It also returns 0 when called with a non-valid index. (If you want +to accept only actual boolean values, use C to test the +value's type.) + + +=head2 C + +[-0, +0, I<->] + + lua_CFunction lua_tocfunction (lua_State *L, int index); + +Converts a value at the given acceptable index to a C function. That +value must be a C function; otherwise, returns C. + + +=head2 C + +[-0, +0, I<->] + + lua_Integer lua_tointeger (lua_State *L, int index); + +Converts the Lua value at the given acceptable index to the signed +integral type C. The Lua value must be a number or a +string convertible to a number (see E2.2.1); otherwise, +C returns 0. + +If the number is not an integer, it is truncated in some non-specified +way. + + +=head2 C + +[-0, +0, I] + + const char *lua_tolstring (lua_State *L, int index, size_t *len); + +Converts the Lua value at the given acceptable index to a C string. If +C is not C, it also sets C<*len> with the string length. The +Lua value must be a string or a number; otherwise, the function returns +C. If the value is a number, then C also I. (This change confuses +C when C is applied to keys during a table +traversal.) + +C returns a fully aligned pointer to a string inside the +Lua state. This string always has a zero ('C<\0>') after its last +character (as in C), but can contain other zeros in its body. Because +Lua has garbage collection, there is no guarantee that the pointer +returned by C will be valid after the corresponding +value is removed from the stack. + + +=head2 C + +[-0, +0, I<->] + + lua_Number lua_tonumber (lua_State *L, int index); + +Converts the Lua value at the given acceptable index to the C type +C (see C). The Lua value must be a number or a +string convertible to a number (see E2.2.1); otherwise, +C returns 0. + + +=head2 C + +[-0, +0, I<->] + + const void *lua_topointer (lua_State *L, int index); + +Converts the value at the given acceptable index to a generic C pointer +(C). The value can be a userdata, a table, a thread, or a +function; otherwise, C returns C. Different +objects will give different pointers. There is no way to convert the +pointer back to its original value. + +Typically this function is used only for debug information. + + +=head2 C + +[-0, +0, I] + + const char *lua_tostring (lua_State *L, int index); + +Equivalent to C with C equal to C. + + +=head2 C + +[-0, +0, I<->] + + lua_State *lua_tothread (lua_State *L, int index); + +Converts the value at the given acceptable index to a Lua thread +(represented as C). This value must be a thread; otherwise, +the function returns C. + + +=head2 C + +[-0, +0, I<->] + + void *lua_touserdata (lua_State *L, int index); + +If the value at the given acceptable index is a full userdata, returns +its block address. If the value is a light userdata, returns its +pointer. Otherwise, returns C. + + +=head2 C + +[-0, +0, I<->] + + int lua_type (lua_State *L, int index); + +Returns the type of the value in the given acceptable index, or +C for a non-valid index (that is, an index to an "empty" +stack position). The types returned by C are coded by the +following constants defined in C: C, C, +C, C, C, C, +C, C, and C. + + +=head2 C + +[-0, +0, I<->] + + const char *lua_typename (lua_State *L, int tp); + +Returns the name of the type encoded by the value C, which must be +one the values returned by C. + + +=head2 C + + typedef int (*lua_Writer) (lua_State *L, + const void* p, + size_t sz, + void* ud); + +The type of the writer function used by C. Every time it +produces another piece of chunk, C calls the writer, passing +along the buffer to be written (C

), its size (C), and the +C parameter supplied to C. + +The writer returns an error code: 0 means no errors; any other value +means an error and stops C from calling the writer again. + + +=head2 C + +[-?, +?, I<->] + + void lua_xmove (lua_State *from, lua_State *to, int n); + +Exchange values between different threads of the I global state. + +This function pops C values from the stack C, and pushes them +onto the stack C. + + +=head2 C + +[-?, +?, I<->] + + int lua_yield (lua_State *L, int nresults); + +Yields a coroutine. + +This function should only be called as the return expression of a C +function, as follows: + + return lua_yield (L, nresults); + +When a C function calls C in that way, the running coroutine +suspends its execution, and the call to C that started this +coroutine returns. The parameter C is the number of values +from the stack that are passed as results to C. + +=head2 3.8 - The Debug Interface + +Lua has no built-in debugging facilities. Instead, it offers a special +interface by means of functions and I. This interface allows the +construction of different kinds of debuggers, profilers, and other +tools that need "inside information" from the interpreter. + + +=head2 C + + typedef struct lua_Debug { + int event; + const char *name; /* (n) */ + const char *namewhat; /* (n) */ + const char *what; /* (S) */ + const char *source; /* (S) */ + int currentline; /* (l) */ + int nups; /* (u) number of upvalues */ + int linedefined; /* (S) */ + int lastlinedefined; /* (S) */ + char short_src[LUA_IDSIZE]; /* (S) */ + /* private part */ + other fields + } lua_Debug; + +A structure used to carry different pieces of information about an +active function. C fills only the private part of this +structure, for later use. To fill the other fields of C with +useful information, call C. + +The fields of C have the following meaning: + +=over + +=item * B:> If the function was defined in a string, then +C is that string. If the function was defined in a file, then +C starts with a 'C<@>' followed by the file name. + +=item * B:> a "printable" version of C, to be used +in error messages. + +=item * B:> the line number where the definition of the +function starts. + +=item * B:> the line number where the definition of +the function ends. + +=item * B:> the string C<"Lua"> if the function is a Lua +function, C<"C"> if it is a C function, C<"main"> if it is the main +part of a chunk, and C<"tail"> if it was a function that did a tail +call. In the latter case, Lua has no other information about the +function. + +=item * B:> the current line where the given function is +executing. When no line information is available, C is set +to -1. + +=item * B:> a reasonable name for the given function. Because +functions in Lua are first-class values, they do not have a fixed name: +some functions can be the value of multiple global variables, while +others can be stored only in a table field. The C function +checks how the function was called to find a suitable name. If it +cannot find a name, then C is set to C. + +=item * B:> explains the C field. The value of +C can be C<"global">, C<"local">, C<"method">, C<"field">, +C<"upvalue">, or C<""> (the empty string), according to how the +function was called. (Lua uses the empty string when no other option +seems to apply.) + +=item * B:> the number of upvalues of the function. + +=back + + +=head2 C + +[-0, +0, I<->] + + lua_Hook lua_gethook (lua_State *L); + +Returns the current hook function. + + +=head2 C + +[-0, +0, I<->] + + int lua_gethookcount (lua_State *L); + +Returns the current hook count. + + +=head2 C + +[-0, +0, I<->] + + int lua_gethookmask (lua_State *L); + +Returns the current hook mask. + + +=head2 C + +[-(0|1), +(0|1|2), I] + + int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); + +Returns information about a specific function or function invocation. + +To get information about a function invocation, the parameter C +must be a valid activation record that was filled by a previous call to +C or given as argument to a hook (see C). + +To get information about a function you push it onto the stack and +start the C string with the character 'C>'. (In that case, +C pops the function in the top of the stack.) For +instance, to know in which line a function C was defined, you can +write the following code: + + lua_Debug ar; + lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ + lua_getinfo(L, ">S", &ar); + printf("%d\n", ar.linedefined); + +Each character in the string C selects some fields of the +structure C to be filled or a value to be pushed on the stack: + +=over + +=item * B<'C':> fills in the field C and C; + +=item * B<'C':> fills in the fields C, C, +C, C, and C; + +=item * B<'C':> fills in the field C; + +=item * B<'C':> fills in the field C; + +=item * B<'C':> pushes onto the stack the function that is running +at the given level; + +=item * B<'C':> pushes onto the stack a table whose indices are the +numbers of the lines that are valid on the function. (A I +is a line with some associated code, that is, a line where you can put +a break point. Non-valid lines include empty lines and comments.) + +=back + +This function returns 0 on error (for instance, an invalid option in +C). + + +=head2 C + +[-0, +(0|1), I<->] + + const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n); + +Gets information about a local variable of a given activation record. +The parameter C must be a valid activation record that was filled +by a previous call to C or given as argument to a hook +(see C). The index C selects which local variable to +inspect (1 is the first parameter or active local variable, and so on, +until the last active local variable). C pushes the +variable's value onto the stack and returns its name. + +Variable names starting with 'C<(>' (open parentheses) represent +internal variables (loop control variables, temporaries, and C function +locals). + +Returns C (and pushes nothing) when the index is greater than the +number of active local variables. + + +=head2 C + +[-0, +0, I<->] + + int lua_getstack (lua_State *L, int level, lua_Debug *ar); + +Get information about the interpreter runtime stack. + +This function fills parts of a C structure with an +identification of the I of the function executing at +a given level. Level 0 is the current running function, whereas level +I is the function that has called level I. When there are no +errors, C returns 1; when called with a level greater +than the stack depth, it returns 0. + + +=head2 C + +[-0, +(0|1), I<->] + + const char *lua_getupvalue (lua_State *L, int funcindex, int n); + +Gets information about a closure's upvalue. (For Lua functions, +upvalues are the external local variables that the function uses, and +that are consequently included in its closure.) C gets +the index C of an upvalue, pushes the upvalue's value onto the +stack, and returns its name. C points to the closure in the +stack. (Upvalues have no particular order, as they are active through +the whole function. So, they are numbered in an arbitrary order.) + +Returns C (and pushes nothing) when the index is greater than the +number of upvalues. For C functions, this function uses the empty +string C<""> as a name for all upvalues. + + +=head2 C + + typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); + +Type for debugging hook functions. + +Whenever a hook is called, its C argument has its field C +set to the specific event that triggered the hook. Lua identifies these +events with the following constants: C, C, +C, C, and C. Moreover, +for line events, the field C is also set. To get the value +of any other field in C, the hook must call C. For +return events, C can be C, the normal value, or +C. In the latter case, Lua is simulating a return from +a function that did a tail call; in this case, it is useless to call +C. + +While Lua is running a hook, it disables other calls to hooks. +Therefore, if a hook calls back Lua to execute a function or a chunk, +this execution occurs without any calls to hooks. + + +=head2 C + +[-0, +0, I<->] + + int lua_sethook (lua_State *L, lua_Hook f, int mask, int count); + +Sets the debugging hook function. + +Argument C is the hook function. C specifies on which events +the hook will be called: it is formed by a bitwise or of the constants +C, C, C, and C. +The C argument is only meaningful when the mask includes +C. For each event, the hook is called as explained +below: + +=over + +=item * B is called when the interpreter calls a +function. The hook is called just after Lua enters the new function, +before the function gets its arguments. + +=item * B is called when the interpreter returns from +a function. The hook is called just before Lua leaves the function. You +have no access to the values to be returned by the function. + +=item * B is called when the interpreter is about to +start the execution of a new line of code, or when it jumps back in the +code (even to the same line). (This event only happens while Lua is +executing a Lua function.) + +=item * B is called after the interpreter executes +every C instructions. (This event only happens while Lua is +executing a Lua function.) + +=back + +A hook is disabled by setting C to zero. + + +=head2 C + +[-(0|1), +0, I<->] + + const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n); + +Sets the value of a local variable of a given activation record. +Parameters C and C are as in C (see +C). C assigns the value at the top of the +stack to the variable and returns its name. It also pops the value from +the stack. + +Returns C (and pops nothing) when the index is greater than the +number of active local variables. + + +=head2 C + +[-(0|1), +0, I<->] + + const char *lua_setupvalue (lua_State *L, int funcindex, int n); + +Sets the value of a closure's upvalue. It assigns the value at the top +of the stack to the upvalue and returns its name. It also pops the +value from the stack. Parameters C and C are as in the +C (see C). + +Returns C (and pops nothing) when the index is greater than the +number of upvalues. + +=head1 4 - The Auxiliary Library + +The I provides several convenient functions to +interface C with Lua. While the basic API provides the primitive +functions for all interactions between C and Lua, the auxiliary library +provides higher-level functions for some common tasks. + +All functions from the auxiliary library are defined in header file +C and have a prefix C. + +All functions in the auxiliary library are built on top of the basic +API, and so they provide nothing that cannot be done with this API. + +Several functions in the auxiliary library are used to check C function +arguments. Their names are always C or C. All +of these functions throw an error if the check is not satisfied. +Because the error message is formatted for arguments (e.g., "C"), you should not use these functions for other stack +values. + +=head2 4.1 - Functions and Types + +Here we list all functions and types from the auxiliary library in +alphabetical order. + + +=head2 C + +[-0, +0, I] + + void luaL_addchar (luaL_Buffer *B, char c); + +Adds the character C to the buffer C (see C). + + +=head2 C + +[-0, +0, I] + + void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); + +Adds the string pointed to by C with length C to the buffer C +(see C). The string may contain embedded zeros. + + +=head2 C + +[-0, +0, I] + + void luaL_addsize (luaL_Buffer *B, size_t n); + +Adds to the buffer C (see C) a string of length C +previously copied to the buffer area (see C). + + +=head2 C + +[-0, +0, I] + + void luaL_addstring (luaL_Buffer *B, const char *s); + +Adds the zero-terminated string pointed to by C to the buffer C +(see C). The string may not contain embedded zeros. + + +=head2 C + +[-1, +0, I] + + void luaL_addvalue (luaL_Buffer *B); + +Adds the value at the top of the stack to the buffer C (see +C). Pops the value. + +This is the only function on string buffers that can (and must) be +called with an extra element on the stack, which is the value to be +added to the buffer. + + +=head2 C + +[-0, +0, I] + + void luaL_argcheck (lua_State *L, + int cond, + int narg, + const char *extramsg); + +Checks whether C is true. If not, raises an error with the +following message, where C is retrieved from the call stack: + + bad argument # to () + + +=head2 C + +[-0, +0, I] + + int luaL_argerror (lua_State *L, int narg, const char *extramsg); + +Raises an error with the following message, where C is retrieved +from the call stack: + + bad argument # to () + +This function never returns, but it is an idiom to use it in C +functions as C)>. + + +=head2 C + + typedef struct luaL_Buffer luaL_Buffer; + +Type for a I. + +A string buffer allows C code to build Lua strings piecemeal. Its +pattern of use is as follows: + +=over + +=item * First you declare a variable C of type C. + +=item * Then you initialize it with a call C. + +=item * Then you add string pieces to the buffer calling any of the +C functions. + +=item * You finish by calling C. This call leaves +the final string on the top of the stack. + +=back + +During its normal operation, a string buffer uses a variable number of +stack slots. So, while using a buffer, you cannot assume that you know +where the top of the stack is. You can use the stack between successive +calls to buffer operations as long as that use is balanced; that is, +when you call a buffer operation, the stack is at the same level it was +immediately after the previous buffer operation. (The only exception to +this rule is C.) After calling C the +stack is back to its level when the buffer was initialized, plus the +final string on its top. + + +=head2 C + +[-0, +0, I<->] + + void luaL_buffinit (lua_State *L, luaL_Buffer *B); + +Initializes a buffer C. This function does not allocate any space; +the buffer must be declared as a variable (see C). + + +=head2 C + +[-0, +(0|1), I] + + int luaL_callmeta (lua_State *L, int obj, const char *e); + +Calls a metamethod. + +If the object at index C has a metatable and this metatable has a +field C, this function calls this field and passes the object as its +only argument. In this case this function returns 1 and pushes onto the +stack the value returned by the call. If there is no metatable or no +metamethod, this function returns 0 (without pushing any value on the +stack). + + +=head2 C + +[-0, +0, I] + + void luaL_checkany (lua_State *L, int narg); + +Checks whether the function has an argument of any type (including +B) at position C. + + +=head2 C + +[-0, +0, I] + + int luaL_checkint (lua_State *L, int narg); + +Checks whether the function argument C is a number and returns +this number cast to an C. + + +=head2 C + +[-0, +0, I] + + lua_Integer luaL_checkinteger (lua_State *L, int narg); + +Checks whether the function argument C is a number and returns +this number cast to a C. + + +=head2 C + +[-0, +0, I] + + long luaL_checklong (lua_State *L, int narg); + +Checks whether the function argument C is a number and returns +this number cast to a C. + + +=head2 C + +[-0, +0, I] + + const char *luaL_checklstring (lua_State *L, int narg, size_t *l); + +Checks whether the function argument C is a string and returns +this string; if C is not C fills C<*l> with the string's +length. + +This function uses C to get its result, so all +conversions and caveats of that function apply here. + + +=head2 C + +[-0, +0, I] + + lua_Number luaL_checknumber (lua_State *L, int narg); + +Checks whether the function argument C is a number and returns +this number. + + +=head2 C + +[-0, +0, I] + + int luaL_checkoption (lua_State *L, + int narg, + const char *def, + const char *const lst[]); + +Checks whether the function argument C is a string and searches +for this string in the array C (which must be NULL-terminated). +Returns the index in the array where the string was found. Raises an +error if the argument is not a string or if the string cannot be found. + +If C is not C, the function uses C as a default value +when there is no argument C or if this argument is B. + +This is a useful function for mapping strings to C enums. (The usual +convention in Lua libraries is to use strings instead of numbers to +select options.) + + +=head2 C + +[-0, +0, I] + + void luaL_checkstack (lua_State *L, int sz, const char *msg); + +Grows the stack size to C elements, raising an error if the +stack cannot grow to that size. C is an additional text to go into +the error message. + + +=head2 C + +[-0, +0, I] + + const char *luaL_checkstring (lua_State *L, int narg); + +Checks whether the function argument C is a string and returns +this string. + +This function uses C to get its result, so all +conversions and caveats of that function apply here. + + +=head2 C + +[-0, +0, I] + + void luaL_checktype (lua_State *L, int narg, int t); + +Checks whether the function argument C has type C. See +C for the encoding of types for C. + + +=head2 C + +[-0, +0, I] + + void *luaL_checkudata (lua_State *L, int narg, const char *tname); + +Checks whether the function argument C is a userdata of the type +C (see C). + + +=head2 C + +[-0, +?, I] + + int luaL_dofile (lua_State *L, const char *filename); + +Loads and runs the given file. It is defined as the following macro: + + (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) + +It returns 0 if there are no errors or 1 in case of errors. + + +=head2 C + +[-0, +?, I] + + int luaL_dostring (lua_State *L, const char *str); + +Loads and runs the given string. It is defined as the following macro: + + (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) + +It returns 0 if there are no errors or 1 in case of errors. + + +=head2 C + +[-0, +0, I] + + int luaL_error (lua_State *L, const char *fmt, ...); + +Raises an error. The error message format is given by C plus any +extra arguments, following the same rules of C. It +also adds at the beginning of the message the file name and the line +number where the error occurred, if this information is available. + +This function never returns, but it is an idiom to use it in C +functions as C)>. + + +=head2 C + +[-0, +(0|1), I] + + int luaL_getmetafield (lua_State *L, int obj, const char *e); + +Pushes onto the stack the field C from the metatable of the object +at index C. If the object does not have a metatable, or if the +metatable does not have this field, returns 0 and pushes nothing. + + +=head2 C + +[-0, +1, I<->] + + void luaL_getmetatable (lua_State *L, const char *tname); + +Pushes onto the stack the metatable associated with name C in +the registry (see C). + + +=head2 C + +[-0, +1, I] + + const char *luaL_gsub (lua_State *L, + const char *s, + const char *p, + const char *r); + +Creates a copy of string C by replacing any occurrence of the string +C

with the string C. Pushes the resulting string on the stack and +returns it. + + +=head2 C + +[-0, +1, I] + + int luaL_loadbuffer (lua_State *L, + const char *buff, + size_t sz, + const char *name); + +Loads a buffer as a Lua chunk. This function uses C to load +the chunk in the buffer pointed to by C with size C. + +This function returns the same results as C. C is the +chunk name, used for debug information and error messages. + + +=head2 C + +[-0, +1, I] + + int luaL_loadfile (lua_State *L, const char *filename); + +Loads a file as a Lua chunk. This function uses C to load the +chunk in the file named C. If C is C, then it +loads from the standard input. The first line in the file is ignored if +it starts with a C<#>. + +This function returns the same results as C, but it has an +extra error code C if it cannot open/read the file. + +As C, this function only loads the chunk; it does not run it. + + +=head2 C + +[-0, +1, I] + + int luaL_loadstring (lua_State *L, const char *s); + +Loads a string as a Lua chunk. This function uses C to load +the chunk in the zero-terminated string C. + +This function returns the same results as C. + +Also as C, this function only loads the chunk; it does not +run it. + + +=head2 C + +[-0, +1, I] + + int luaL_newmetatable (lua_State *L, const char *tname); + +If the registry already has the key C, returns 0. Otherwise, +creates a new table to be used as a metatable for userdata, adds it to +the registry with key C, and returns 1. + +In both cases pushes onto the stack the final value associated with +C in the registry. + + +=head2 C + +[-0, +0, I<->] + + lua_State *luaL_newstate (void); + +Creates a new Lua state. It calls C with an allocator +based on the standard C C function and then sets a panic +function (see C) that prints an error message to the +standard error output in case of fatal errors. + +Returns the new state, or C if there is a memory allocation +error. + + +=head2 C + +[-0, +0, I] + + void luaL_openlibs (lua_State *L); + +Opens all standard Lua libraries into the given state. + + +=head2 C + +[-0, +0, I] + + int luaL_optint (lua_State *L, int narg, int d); + +If the function argument C is a number, returns this number cast +to an C. If this argument is absent or is B, returns C. +Otherwise, raises an error. + + +=head2 C + +[-0, +0, I] + + lua_Integer luaL_optinteger (lua_State *L, + int narg, + lua_Integer d); + +If the function argument C is a number, returns this number cast +to a C. If this argument is absent or is B, returns +C. Otherwise, raises an error. + + +=head2 C + +[-0, +0, I] + + long luaL_optlong (lua_State *L, int narg, long d); + +If the function argument C is a number, returns this number cast +to a C. If this argument is absent or is B, returns C. +Otherwise, raises an error. + + +=head2 C + +[-0, +0, I] + + const char *luaL_optlstring (lua_State *L, + int narg, + const char *d, + size_t *l); + +If the function argument C is a string, returns this string. If +this argument is absent or is B, returns C. Otherwise, raises +an error. + +If C is not C, fills the position C<*l> with the results's +length. + + +=head2 C + +[-0, +0, I] + + lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d); + +If the function argument C is a number, returns this number. If +this argument is absent or is B, returns C. Otherwise, raises +an error. + + +=head2 C + +[-0, +0, I] + + const char *luaL_optstring (lua_State *L, + int narg, + const char *d); + +If the function argument C is a string, returns this string. If +this argument is absent or is B, returns C. Otherwise, raises +an error. + + +=head2 C + +[-0, +0, I<->] + + char *luaL_prepbuffer (luaL_Buffer *B); + +Returns an address to a space of size C where you can +copy a string to be added to buffer C (see C). After +copying the string into this space you must call C with +the size of the string to actually add it to the buffer. + + +=head2 C + +[-?, +1, I] + + void luaL_pushresult (luaL_Buffer *B); + +Finishes the use of buffer C leaving the final string on the top of +the stack. + + +=head2 C + +[-1, +0, I] + + int luaL_ref (lua_State *L, int t); + +Creates and returns a I, in the table at index C, for the +object at the top of the stack (and pops the object). + +A reference is a unique integer key. As long as you do not manually add +integer keys into table C, C ensures the uniqueness of the +key it returns. You can retrieve an object referred by reference C +by calling C. Function C frees a +reference and its associated object. + +If the object at the top of the stack is B, C returns +the constant C. The constant C is guaranteed to +be different from any reference returned by C. + + +=head2 C + + typedef struct luaL_Reg { + const char *name; + lua_CFunction func; + } luaL_Reg; + +Type for arrays of functions to be registered by C. +C is the function name and C is a pointer to the function. +Any array of C must end with an sentinel entry in which both +C and C are C. + + +=head2 C + +[-(0|1), +1, I] + + void luaL_register (lua_State *L, + const char *libname, + const luaL_Reg *l); + +Opens a library. + +When called with C equal to C, it simply registers all +functions in the list C (see C) into the table on the top +of the stack. + +When called with a non-null C, C creates a new +table C, sets it as the value of the global variable C, +sets it as the value of C, and registers on it +all functions in the list C. If there is a table in +C or in variable C, reuses this table +instead of creating a new one. + +In any case the function leaves the table on the top of the stack. + + +=head2 C + +[-0, +0, I<->] + + const char *luaL_typename (lua_State *L, int index); + +Returns the name of the type of the value at the given index. + + +=head2 C + +[-0, +0, I] + + int luaL_typerror (lua_State *L, int narg, const char *tname); + +Generates an error with a message like the following: + + location: bad argument narg to 'func' (tname expected, got rt) + +where C> is produced by C, C> is the +name of the current function, and C> is the type name of the +actual argument. + + +=head2 C + +[-0, +0, I<->] + + void luaL_unref (lua_State *L, int t, int ref); + +Releases reference C from the table at index C (see +C). The entry is removed from the table, so that the referred +object can be collected. The reference C is also freed to be used +again. + +If C is C or C, C does nothing. + + +=head2 C + +[-0, +1, I] + + void luaL_where (lua_State *L, int lvl); + +Pushes onto the stack a string identifying the current position of the +control at level C in the call stack. Typically this string has +the following format: + + chunkname:currentline: + +Level 0 is the running function, level 1 is the function that called +the running function, etc. + +This function is used to build a prefix for error messages. + +=head1 5 - Standard Libraries + +The standard Lua libraries provide useful functions that are +implemented directly through the C API. Some of these functions provide +essential services to the language (e.g., C and C); +others provide access to "outside" services (e.g., I/O); and others +could be implemented in Lua itself, but are quite useful or have +critical performance requirements that deserve an implementation in C +(e.g., C). + +All libraries are implemented through the official C API and are +provided as separate C modules. Currently, Lua has the following +standard libraries: + +=over + +=item * basic library, which includes the coroutine sub-library; + +=item * package library; + +=item * string manipulation; + +=item * table manipulation; + +=item * mathematical functions (sin, log, etc.); + +=item * input and output; + +=item * operating system facilities; + +=item * debug facilities. + +=back + +Except for the basic and package libraries, each library provides all +its functions as fields of a global table or as methods of its objects. + +To have access to these libraries, the C host program should call the +C function, which opens all standard libraries. +Alternatively, it can open them individually by calling C +(for the basic library), C (for the package library), +C (for the string library), C (for the +table library), C (for the mathematical library), +C (for the I/O library), C (for the Operating +System library), and C (for the debug library). These +functions are declared in C and should not be called +directly: you must call them like any other Lua C function, e.g., by +using C. + +=head2 5.1 - Basic Functions + +The basic library provides some core functions to Lua. If you do not +include this library in your application, you should check carefully +whether you need to provide implementations for some of its facilities. + + +=head2 C + +Issues an error when the value of its argument C is false (i.e., +B or B); otherwise, returns all its arguments. C +is an error message; when absent, it defaults to "assertion failed!" + + +=head2 C + +This function is a generic interface to the garbage collector. It +performs different functions according to its first argument, C: + +=over + +=item * B<"collect":> performs a full garbage-collection cycle. This is +the default option. + +=item * B<"stop":> stops the garbage collector. + +=item * B<"restart":> restarts the garbage collector. + +=item * B<"count":> returns the total memory in use by Lua (in Kbytes). + +=item * B<"step":> performs a garbage-collection step. The step "size" +is controlled by C (larger values mean more steps) in a +non-specified way. If you want to control the step size you must +experimentally tune the value of C. Returns B if the step +finished a collection cycle. + +=item * B<"setpause":> sets C as the new value for the I of +the collector (see E2.10). Returns the previous value for +I. + +=item * B<"setstepmul":> sets C as the new value for the I of the collector (see E2.10). Returns the previous +value for I. + +=back + + +=head2 C + +Opens the named file and executes its contents as a Lua chunk. When +called without arguments, C executes the contents of the +standard input (C). Returns all values returned by the chunk. In +case of errors, C propagates the error to its caller (that is, +C does not run in protected mode). + + +=head2 C + +Terminates the last protected function called and returns C as +the error message. Function C never returns. + +Usually, C adds some information about the error position at the +beginning of the message. The C argument specifies how to get +the error position. With level 1 (the default), the error position is +where the C function was called. Level 2 points the error to +where the function that called C was called; and so on. Passing +a level 0 avoids the addition of error position information to the +message. + + +=head2 C<_G> + +A global variable (not a function) that holds the global environment +(that is, C<_G._G = _G>). Lua itself does not use this variable; +changing its value does not affect any environment, nor vice-versa. +(Use C to change environments.) + + +=head2 C + +Returns the current environment in use by the function. C can be a +Lua function or a number that specifies the function at that stack +level: Level 1 is the function calling C. If the given +function is not a Lua function, or if C is 0, C returns the +global environment. The default for C is 1. + + +=head2 C + +If C does not have a metatable, returns B. Otherwise, if +the object's metatable has a C<"__metatable"> field, returns the +associated value. Otherwise, returns the metatable of the given object. + + +=head2 C + +Returns three values: an iterator function, the table C, and 0, so +that the construction + + for i,v in ipairs(t) do body end + +will iterate over the pairs (C<1,t[1]>), (C<2,t[2]>), +EEE, up to the first integer key absent from +the table. + + +=head2 C + +Loads a chunk using function C to get its pieces. Each call to +C must return a string that concatenates with previous results. A +return of an empty string, B, or no value signals the end of the +chunk. + +If there are no errors, returns the compiled chunk as a function; +otherwise, returns B plus the error message. The environment of +the returned function is the global environment. + +C is used as the chunk name for error messages and debug +information. When absent, it defaults to "C<=(load)>". + + +=head2 C + +Similar to C, but gets the chunk from file C or from +the standard input, if no file name is given. + + +=head2 C + +Similar to C, but gets the chunk from the given string. + +To load and run a given string, use the idiom + + assert(loadstring(s))() + +When absent, C defaults to the given string. + + +=head2 C + +Allows a program to traverse all fields of a table. Its first argument +is a table and its second argument is an index in this table. C +returns the next index of the table and its associated value. When +called with B as its second argument, C returns an initial +index and its associated value. When called with the last index, or +with B in an empty table, C returns B. If the second +argument is absent, then it is interpreted as B. In particular, +you can use C to check whether a table is empty. + +The order in which the indices are enumerated is not specified, I. (To traverse a table in numeric order, use a +numerical B or the C function.) + +The behavior of C is I if, during the traversal, you +assign any value to a non-existent field in the table. You may however +modify existing fields. In particular, you may clear existing fields. + + +=head2 C + +Returns three values: the C function, the table C, and B, +so that the construction + + for k,v in pairs(t) do body end + +will iterate over all keyEvalue pairs of table C. + +See function C for the caveats of modifying the table during its +traversal. + + +=head2 CEE)> + +Calls function C with the given arguments in I. This +means that any error inside C is not propagated; instead, C +catches the error and returns a status code. Its first result is the +status code (a boolean), which is true if the call succeeds without +errors. In such case, C also returns all results from the call, +after this first result. In case of any error, C returns +B plus the error message. + + +=head2 CEE)> + +Receives any number of arguments, and prints their values to C, +using the C function to convert them to strings. C is +not intended for formatted output, but only as a quick way to show a +value, typically for debugging. For formatted output, use +C. + + +=head2 C + +Checks whether C is equal to C, without invoking any +metamethod. Returns a boolean. + + +=head2 C + +Gets the real value of C, without invoking any +metamethod. C

must be a table; C may be any value. + + +=head2 C + +Sets the real value of C to C, without invoking +any metamethod. C
must be a table, C any value different +from B, and C any Lua value. + +This function returns C
. + + +=head2 C +returns the total number of extra arguments it received. + + +=head2 C + +Sets the environment to be used by the given function. C can be a +Lua function or a number that specifies the function at that stack +level: Level 1 is the function calling C. C returns +the given function. + +As a special case, when C is 0 C changes the environment of +the running thread. In this case, C returns no values. + + +=head2 C + +Sets the metatable for the given table. (You cannot change the +metatable of other types from Lua, only from C.) If C is +B, removes the metatable of the given table. If the original +metatable has a C<"__metatable"> field, raises an error. + +This function returns C
. + + +=head2 C + +Tries to convert its argument to a number. If the argument is already a +number or a string convertible to a number, then C returns +this number; otherwise, it returns B. + +An optional argument specifies the base to interpret the numeral. The +base may be any integer between 2 and 36, inclusive. In bases above 10, +the letter 'C' (in either upper or lower case) represents 10, 'C' +represents 11, and so forth, with 'C' representing 35. In base 10 +(the default), the number can have a decimal part, as well as an +optional exponent part (see E2.1). In other bases, only unsigned +integers are accepted. + + +=head2 C + +Receives an argument of any type and converts it to a string in a +reasonable format. For complete control of how numbers are converted, +use C. + +If the metatable of C has a C<"__tostring"> field, then C +calls the corresponding value with C as argument, and uses the +result of the call as its result. + + +=head2 C + +Returns the type of its only argument, coded as a string. The possible +results of this function are "C" (a string, not the value B), +"C", "C", "C", "C
", "C", +"C", and "C". + + +=head2 C + +Returns the elements from the given table. This function is equivalent +to + + return list[i], list[i+1], ···, list[j] + +except that the above code can be written only for a fixed number of +elements. By default, C is 1 and C is the length of the list, as +defined by the length operator (see E2.5.5). + + +=head2 C<_VERSION> + +A global variable (not a function) that holds a string containing the +current interpreter version. The current contents of this variable is +"C". + + +=head2 C + +This function is similar to C, except that you can set a new +error handler. + +C calls function C in protected mode, using C as the +error handler. Any error inside C is not propagated; instead, +C catches the error, calls the C function with the +original error object, and returns a status code. Its first result is +the status code (a boolean), which is true if the call succeeds without +errors. In this case, C also returns all results from the call, +after this first result. In case of any error, C returns +B plus the result from C. + +=head2 5.2 - Coroutine Manipulation + +The operations related to coroutines comprise a sub-library of the +basic library and come inside the table C. See E2.11 +for a general description of coroutines. + + +=head2 C + +Creates a new coroutine, with body C. C must be a Lua function. +Returns this new coroutine, an object with type C<"thread">. + + +=head2 CEE])> + +Starts or continues the execution of coroutine C. The first time +you resume a coroutine, it starts running its body. The values C, +EEE are passed as the arguments to the body +function. If the coroutine has yielded, C restarts it; the +values C, EEE are passed as the results +from the yield. + +If the coroutine runs without any errors, C returns B +plus any values passed to C (if the coroutine yields) or any +values returned by the body function (if the coroutine terminates). If +there is any error, C returns B plus the error message. + + +=head2 C + +Returns the running coroutine, or B when called by the main +thread. + + +=head2 C + +Returns the status of coroutine C, as a string: C<"running">, if +the coroutine is running (that is, it called C); +C<"suspended">, if the coroutine is suspended in a call to C, or +if it has not started running yet; C<"normal"> if the coroutine is +active but not running (that is, it has resumed another coroutine); and +C<"dead"> if the coroutine has finished its body function, or if it has +stopped with an error. + + +=head2 C + +Creates a new coroutine, with body C. C must be a Lua function. +Returns a function that resumes the coroutine each time it is called. +Any arguments passed to the function behave as the extra arguments to +C. Returns the same values returned by C, except the +first boolean. In case of error, propagates the error. + + +=head2 CEE)> + +Suspends the execution of the calling coroutine. The coroutine cannot +be running a C function, a metamethod, or an iterator. Any arguments to +C are passed as extra results to C. + +=head2 5.3 - Modules + +The package library provides basic facilities for loading and building +modules in Lua. It exports two of its functions directly in the global +environment: C and C. Everything else is exported in a +table C. + + +=head2 CEE])> + +Creates a module. If there is a table in C, this +table is the module. Otherwise, if there is a global table C with +the given name, this table is the module. Otherwise creates a new table +C and sets it as the value of the global C and the value of +C. This function also initializes C with +the given name, C with the module (C itself), and +C with the package name (the full module name minus last +component; see below). Finally, C sets C as the new +environment of the current function and the new value of +C, so that C returns C. + +If C is a compound name (that is, one with components separated +by dots), C creates (or reuses, if they already exist) tables +for each component. For instance, if C is C, then +C stores the module table in field C of field C of global +C. + +This function can receive optional I after the module name, +where each option is a function to be applied over the module. + + +=head2 C + +Loads the given module. The function starts by looking into the +C table to determine whether C is already +loaded. If it is, then C returns the value stored at +C. Otherwise, it tries to find a I for +the module. + +To find a loader, C is guided by the C array. +By changing this array, we can change how C looks for a +module. The following explanation is based on the default configuration +for C. + +First C queries C. If it has a +value, this value (which should be a function) is the loader. Otherwise +C searches for a Lua loader using the path stored in +C. If that also fails, it searches for a C loader using +the path stored in C. If that also fails, it tries an +I loader (see C). + +Once a loader is found, C calls the loader with a single +argument, C. If the loader returns any value, C +assigns the returned value to C. If the loader +returns no value and has not assigned any value to +C, then C assigns B to this +entry. In any case, C returns the final value of +C. + +If there is any error loading or running the module, or if it cannot +find any loader for the module, then C signals an error. + + +=head2 C + +The path used by C to search for a C loader. + +Lua initializes the C path C in the same way it +initializes the Lua path C, using the environment +variable C or a default path defined in C. + + +=head2 C + +A table used by C to control which modules are already loaded. +When you require a module C and C is +not false, C simply returns the value stored there. + + +=head2 C + +A table used by C to control how to load modules. + +Each entry in this table is a I. When looking for a +module, C calls each of these searchers in ascending order, +with the module name (the argument given to C) as its sole +parameter. The function can return another function (the module +I) or a string explaining why it did not find that module (or +B if it has nothing to say). Lua initializes this table with four +functions. + +The first searcher simply looks for a loader in the C +table. + +The second searcher looks for a loader as a Lua library, using the path +stored at C. A path is a sequence of I +separated by semicolons. For each template, the searcher will change +each interrogation mark in the template by C, which is the +module name with each dot replaced by a "directory separator" (such as +"C" in Unix); then it will try to open the resulting file name. So, +for instance, if the Lua path is the string + + "./?.lua;./?.lc;/usr/local/?/init.lua" + +the search for a Lua file for module C will try to open the files +C<./foo.lua>, C<./foo.lc>, and C, in that +order. + +The third searcher looks for a loader as a C library, using the path +given by the variable C. For instance, if the C path is +the string + + "./?.so;./?.dll;/usr/local/?/init.so" + +the searcher for module C will try to open the files C<./foo.so>, +C<./foo.dll>, and C, in that order. Once it +finds a C library, this searcher first uses a dynamic link facility to +link the application with the library. Then it tries to find a C +function inside the library to be used as the loader. The name of this +C function is the string "C" concatenated with a copy of the +module name where each dot is replaced by an underscore. Moreover, if +the module name has a hyphen, its prefix up to (and including) the +first hyphen is removed. For instance, if the module name is +C, the function name will be C. + +The fourth searcher tries an I. It searches the C +path for a library for the root name of the given module. For instance, +when requiring C, it will search for a C library for C. If +found, it looks into it for an open function for the submodule; in our +example, that would be C. With this facility, a package +can pack several C submodules into one single library, with each +submodule keeping its original open function. + + +=head2 C + +Dynamically links the host program with the C library C. +Inside this library, looks for a function C and returns this +function as a C function. (So, C must follow the protocol +(see C)). + +This is a low-level function. It completely bypasses the package and +module system. Unlike C, it does not perform any path +searching and does not automatically adds extensions. C must +be the complete file name of the C library, including if necessary a +path and extension. C must be the exact name exported by the +C library (which may depend on the C compiler and linker used). + +This function is not supported by ANSI C. As such, it is only available +on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other +Unix systems that support the C standard). + + +=head2 C + +The path used by C to search for a Lua loader. + +At start-up, Lua initializes this variable with the value of the +environment variable C or with a default path defined in +C, if the environment variable is not defined. Any "C<;;>" +in the value of the environment variable is replaced by the default +path. + + +=head2 C + +A table to store loaders for specific modules (see C). + + +=head2 C + +Sets a metatable for C with its C<__index> field referring to +the global environment, so that this module inherits values from the +global environment. To be used as an option to function C. + +=head2 5.4 - String Manipulation + +This library provides generic functions for string manipulation, such +as finding and extracting substrings, and pattern matching. When +indexing a string in Lua, the first character is at position 1 (not at +0, as in C). Indices are allowed to be negative and are interpreted as +indexing backwards, from the end of the string. Thus, the last +character is at position -1, and so on. + +The string library provides all its functions inside the table +C. It also sets a metatable for strings where the C<__index> +field points to the C table. Therefore, you can use the string +functions in object-oriented style. For instance, C +can be written as C. + +The string library assumes one-byte character encodings. + + +=head2 C + +Returns the internal numerical codes of the characters C, +C, EEE, C. The default value for +C is 1; the default value for C is C. + +Note that numerical codes are not necessarily portable across +platforms. + + +=head2 CEE)> + +Receives zero or more integers. Returns a string with length equal to +the number of arguments, in which each character has the internal +numerical code equal to its corresponding argument. + +Note that numerical codes are not necessarily portable across +platforms. + + +=head2 C + +Returns a string containing a binary representation of the given +function, so that a later C on this string returns a copy +of the function. C must be a Lua function without upvalues. + + +=head2 C + +Looks for the first match of C in the string C. If it finds +a match, then C returns the indices of C where this occurrence +starts and ends; otherwise, it returns B. A third, optional +numerical argument C specifies where to start the search; its +default value is 1 and can be negative. A value of B as a fourth, +optional argument C turns off the pattern matching facilities, +so the function does a plain "find substring" operation, with no +characters in C being considered "magic". Note that if +C is given, then C must be given as well. + +If the pattern has captures, then in a successful match the captured +values are also returned, after the two indices. + + +=head2 CEE)> + +Returns a formatted version of its variable number of arguments +following the description given in its first argument (which must be a +string). The format string follows the same rules as the C +family of standard C functions. The only differences are that the +options/modifiers C<*>, C, C, C, C

, and C are not +supported and that there is an extra option, C. The C option +formats a string in a form suitable to be safely read back by the Lua +interpreter: the string is written between double quotes, and all +double quotes, newlines, embedded zeros, and backslashes in the string +are correctly escaped when written. For instance, the call + + string.format('%q', 'a string with "quotes" and \n new line') + +will produce the string: + + "a string with \"quotes\" and \ + new line" + +The options C, C, C, C, C, C, C, C, C, C, +C, and C all expect a number as argument, whereas C and C +expect a string. + +This function does not accept string values containing embedded zeros, +except as arguments to the C option. + + +=head2 C + +Returns an iterator function that, each time it is called, returns the +next captures from C over string C. If C specifies +no captures, then the whole match is produced in each call. + +As an example, the following loop + + s = "hello world from Lua" + for w in string.gmatch(s, "%a+") do + print(w) + end + +will iterate over all the words from string C, printing one per +line. The next example collects all pairs C from the given +string into a table: + + t = {} + s = "from=world, to=Lua" + for k, v in string.gmatch(s, "(%w+)=(%w+)") do + t[k] = v + end + +For this function, a 'C<^>' at the start of a pattern does not work as +an anchor, as this would prevent the iteration. + + +=head2 C + +Returns a copy of C in which all (or the first C, if given) +occurrences of the C have been replaced by a replacement +string specified by C, which can be a string, a table, or a +function. C also returns, as its second value, the total number +of matches that occurred. + +If C is a string, then its value is used for replacement. The +character C<%> works as an escape character: any sequence in C of +the form C<%I>, with I between 1 and 9, stands for the value of +the I-th captured substring (see below). The sequence C<%0> stands +for the whole match. The sequence C<%%> stands for a single C<%>. + +If C is a table, then the table is queried for every match, using +the first capture as the key; if the pattern specifies no captures, +then the whole match is used as the key. + +If C is a function, then this function is called every time a +match occurs, with all captured substrings passed as arguments, in +order; if the pattern specifies no captures, then the whole match is +passed as a sole argument. + +If the value returned by the table query or by the function call is a +string or a number, then it is used as the replacement string; +otherwise, if it is B or B, then there is no replacement +(that is, the original match is kept in the string). + +Here are some examples: + + x = string.gsub("hello world", "(%w+)", "%1 %1") + --> x="hello hello world world" + + x = string.gsub("hello world", "%w+", "%0 %0", 1) + --> x="hello hello world" + + x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") + --> x="world hello Lua from" + + x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) + --> x="home = /home/roberto, user = roberto" + + x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) + return loadstring(s)() + end) + --> x="4+5 = 9" + + local t = {name="lua", version="5.1"} + x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) + --> x="lua-5.1.tar.gz" + + +=head2 C + +Receives a string and returns its length. The empty string C<""> has +length 0. Embedded zeros are counted, so C<"a\000bc\000"> has length 5. + + +=head2 C + +Receives a string and returns a copy of this string with all uppercase +letters changed to lowercase. All other characters are left unchanged. +The definition of what an uppercase letter is depends on the current +locale. + + +=head2 C + +Looks for the first I of C in the string C. If it +finds one, then C returns the captures from the pattern; +otherwise it returns B. If C specifies no captures, then +the whole match is returned. A third, optional numerical argument +C specifies where to start the search; its default value is 1 and +can be negative. + + +=head2 C + +Returns a string that is the concatenation of C copies of the string +C. + + +=head2 C + +Returns a string that is the string C reversed. + + +=head2 C + +Returns the substring of C that starts at C and continues until +C; C and C can be negative. If C is absent, then it is +assumed to be equal to -1 (which is the same as the string length). In +particular, the call C returns a prefix of C with +length C, and C returns a suffix of C with +length C. + + +=head2 C + +Receives a string and returns a copy of this string with all lowercase +letters changed to uppercase. All other characters are left unchanged. +The definition of what a lowercase letter is depends on the current +locale. + +=head2 5.4.1 - Patterns + +=head2 Character Class: + +A I is used to represent a set of characters. The +following combinations are allowed in describing a character class: + +=over + +=item * B:> (where I is not one of the I +C<^$()%.[]*+-?>) represents the character I itself. + +=item * B:> (a dot) represents all characters. + +=item * B:> represents all letters. + +=item * B:> represents all control characters. + +=item * B:> represents all digits. + +=item * B:> represents all lowercase letters. + +=item * B:> represents all punctuation characters. + +=item * B:> represents all space characters. + +=item * B:> represents all uppercase letters. + +=item * B:> represents all alphanumeric characters. + +=item * B:> represents all hexadecimal digits. + +=item * B:> represents the character with representation 0. + +=item * B>:> (where I is any non-alphanumeric character) +represents the character I. This is the standard way to escape the +magic characters. Any punctuation character (even the non magic) can be +preceded by a 'C<%>' when used to represent itself in a pattern. + +=item * B]>:> represents the class which is the union of all +characters in I. A range of characters can be specified by +separating the end characters of the range with a 'C<->'. All classes +C<%>I described above can also be used as components in I. All +other characters in I represent themselves. For example, C<[%w_]> +(or C<[_%w]>) represents all alphanumeric characters plus the +underscore, C<[0-7]> represents the octal digits, and C<[0-7%l%-]> +represents the octal digits plus the lowercase letters plus the 'C<->' +character. + +The interaction between ranges and classes is not defined. Therefore, +patterns like C<[%a-z]> or C<[a-%%]> have no meaning. + +=item * B]>:> represents the complement of I, where +I is interpreted as above. + +=back + +For all classes represented by single letters (C<%a>, C<%c>, etc.), the +corresponding uppercase letter represents the complement of the class. +For instance, C<%S> represents all non-space characters. + +The definitions of letter, space, and other character groups depend on +the current locale. In particular, the class C<[a-z]> may not be +equivalent to C<%l>. + +=head2 Pattern Item: + +A I can be + +=over + +=item * a single character class, which matches any single character in +the class; + +=item * a single character class followed by 'C<*>', which matches 0 or +more repetitions of characters in the class. These repetition items +will always match the longest possible sequence; + +=item * a single character class followed by 'C<+>', which matches 1 or +more repetitions of characters in the class. These repetition items +will always match the longest possible sequence; + +=item * a single character class followed by 'C<->', which also matches +0 or more repetitions of characters in the class. Unlike 'C<*>', these +repetition items will always match the I possible sequence; + +=item * a single character class followed by 'C', which matches 0 or +1 occurrence of a character in the class; + +=item * C<%I>, for I between 1 and 9; such item matches a +substring equal to the I-th captured string (see below); + +=item * C<%bI>, where I and I are two distinct characters; +such item matches strings that start with I, end with I, and +where the I and I are I. This means that, if one reads +the string from left to right, counting I<+1> for an I and I<-1> for +a I, the ending I is the first I where the count reaches 0. +For instance, the item C<%b()> matches expressions with balanced +parentheses. + +=back + +=head2 Pattern: + +A I is a sequence of pattern items. A 'C<^>' at the beginning +of a pattern anchors the match at the beginning of the subject string. +A 'C<$>' at the end of a pattern anchors the match at the end of the +subject string. At other positions, 'C<^>' and 'C<$>' have no special +meaning and represent themselves. + +=head2 Captures: + +A pattern can contain sub-patterns enclosed in parentheses; they +describe I. When a match succeeds, the substrings of the +subject string that match captures are stored (I) for future +use. Captures are numbered according to their left parentheses. For +instance, in the pattern C<"(a*(.)%w(%s*))">, the part of the string +matching C<"a*(.)%w(%s*)"> is stored as the first capture (and +therefore has number 1); the character matching "C<.>" is captured with +number 2, and the part matching "C<%s*>" has number 3. + +As a special case, the empty capture C<()> captures the current string +position (a number). For instance, if we apply the pattern C<"()aa()"> +on the string C<"flaaap">, there will be two captures: 3 and 5. + +A pattern cannot contain embedded zeros. Use C<%z> instead. + +=head2 5.5 - Table Manipulation + +This library provides generic functions for table manipulation. It +provides all its functions inside the table C

. + +Most functions in the table library assume that the table represents an +array or a list. For these functions, when we talk about the "length" +of a table we mean the result of the length operator. + + +=head2 C + +Given an array where all elements are strings or numbers, returns +CEE sep..table[j]>. +The default value for C is the empty string, the default for C +is 1, and the default for C is the length of the table. If C is +greater than C, returns the empty string. + + +=head2 C + +Inserts element C at position C in C
, shifting up +other elements to open space, if necessary. The default value for +C is C, where C is the length of the table (see +E2.5.5), so that a call C inserts C at the +end of table C. + + +=head2 C + +Returns the largest positive numerical index of the given table, or +zero if the table has no positive numerical indices. (To do its job +this function does a linear traversal of the whole table.) + + +=head2 C + +Removes from C
the element at position C, shifting down +other elements to close the space, if necessary. Returns the value of +the removed element. The default value for C is C, where C +is the length of the table, so that a call C removes +the last element of table C. + + +=head2 C + +Sorts table elements in a given order, I, from C to +C, where C is the length of the table. If C is +given, then it must be a function that receives two table elements, and +returns true when the first is less than the second (so that C will be true after the sort). If C is not +given, then the standard Lua operator C> is used instead. + +The sort algorithm is not stable; that is, elements considered equal by +the given order may have their relative positions changed by the sort. + +=head2 5.6 - Mathematical Functions + +This library is an interface to the standard C math library. It +provides all its functions inside the table C. + + +=head2 C + +Returns the absolute value of C. + + +=head2 C + +Returns the arc cosine of C (in radians). + + +=head2 C + +Returns the arc sine of C (in radians). + + +=head2 C + +Returns the arc tangent of C (in radians). + + +=head2 C + +Returns the arc tangent of C (in radians), but uses the signs of +both parameters to find the quadrant of the result. (It also handles +correctly the case of C being zero.) + + +=head2 C + +Returns the smallest integer larger than or equal to C. + + +=head2 C + +Returns the cosine of C (assumed to be in radians). + + +=head2 C + +Returns the hyperbolic cosine of C. + + +=head2 C + +Returns the angle C (given in radians) in degrees. + + +=head2 C + +Returns the value I. + + +=head2 C + +Returns the largest integer smaller than or equal to C. + + +=head2 C + +Returns the remainder of the division of C by C that rounds the +quotient towards zero. + + +=head2 C + +Returns C and C such that I, C is an integer and the +absolute value of C is in the range I<[0.5, 1)> (or zero when C +is zero). + + +=head2 C + +The value C, a value larger than or equal to any other +numerical value. + + +=head2 C + +Returns I (C should be an integer). + + +=head2 C + +Returns the natural logarithm of C. + + +=head2 C + +Returns the base-10 logarithm of C. + + +=head2 CEE)> + +Returns the maximum value among its arguments. + + +=head2 CEE)> + +Returns the minimum value among its arguments. + + +=head2 C + +Returns two numbers, the integral part of C and the fractional part +of C. + + +=head2 C + +The value of I. + + +=head2 C + +Returns I. (You can also use the expression C to compute this +value.) + + +=head2 C + +Returns the angle C (given in degrees) in radians. + + +=head2 C + +This function is an interface to the simple pseudo-random generator +function C provided by ANSI C. (No guarantees can be given for +its statistical properties.) + +When called without arguments, returns a uniform pseudo-random real +number in the range I<[0,1)>. When called with an integer number C, +C returns a uniform pseudo-random integer in the range +I<[1, m]>. When called with two integer numbers C and C, +C returns a uniform pseudo-random integer in the range +I<[m, n]>. + + +=head2 C + +Sets C as the "seed" for the pseudo-random generator: equal seeds +produce equal sequences of numbers. + + +=head2 C + +Returns the sine of C (assumed to be in radians). + + +=head2 C + +Returns the hyperbolic sine of C. + + +=head2 C + +Returns the square root of C. (You can also use the expression +C to compute this value.) + + +=head2 C + +Returns the tangent of C (assumed to be in radians). + + +=head2 C + +Returns the hyperbolic tangent of C. + +=head2 5.7 - Input and Output Facilities + +The I/O library provides two different styles for file manipulation. +The first one uses implicit file descriptors; that is, there are +operations to set a default input file and a default output file, and +all input/output operations are over these default files. The second +style uses explicit file descriptors. + +When using implicit file descriptors, all operations are supplied by +table C. When using explicit file descriptors, the operation +C returns a file descriptor and then all operations are +supplied as methods of the file descriptor. + +The table C also provides three predefined file descriptors with +their usual meanings from C: C, C, and +C. The I/O library never closes these files. + +Unless otherwise stated, all I/O functions return B on failure +(plus an error message as a second result and a system-dependent error +code as a third result) and some value different from B on +success. + + +=head2 C + +Equivalent to C. Without a C, closes the default +output file. + + +=head2 C + +Equivalent to C over the default output file. + + +=head2 C + +When called with a file name, it opens the named file (in text mode), +and sets its handle as the default input file. When called with a file +handle, it simply sets this file handle as the default input file. When +called without parameters, it returns the current default input file. + +In case of errors this function raises the error, instead of returning +an error code. + + +=head2 C + +Opens the given file name in read mode and returns an iterator function +that, each time it is called, returns a new line from the file. +Therefore, the construction + + for line in io.lines(filename) do body end + +will iterate over all lines of the file. When the iterator function +detects the end of file, it returns B (to finish the loop) and +automatically closes the file. + +The call C (with no file name) is equivalent to +C; that is, it iterates over the lines of the +default input file. In this case it does not close the file when the +loop ends. + + +=head2 C + +This function opens a file, in the mode specified in the string +C. It returns a new file handle, or, in case of errors, B +plus an error message. + +The C string can be any of the following: + +=over + +=item * B<"r":> read mode (the default); + +=item * B<"w":> write mode; + +=item * B<"a":> append mode; + +=item * B<"r+":> update mode, all previous data is preserved; + +=item * B<"w+":> update mode, all previous data is erased; + +=item * B<"a+":> append update mode, previous data is preserved, +writing is only allowed at the end of file. + +=back + +The C string can also have a 'C' at the end, which is needed +in some systems to open the file in binary mode. This string is exactly +what is used in the standard C function C. + + +=head2 C + +Similar to C, but operates over the default output file. + + +=head2 C + +Starts program C in a separated process and returns a file handle +that you can use to read data from this program (if C is C<"r">, +the default) or to write data to this program (if C is C<"w">). + +This function is system dependent and is not available on all +platforms. + + +=head2 CEE)> + +Equivalent to C. + + +=head2 C + +Returns a handle for a temporary file. This file is opened in update +mode and it is automatically removed when the program ends. + + +=head2 C + +Checks whether C is a valid file handle. Returns the string +C<"file"> if C is an open file handle, C<"closed file"> if C +is a closed file handle, or B if C is not a file handle. + + +=head2 CEE)> + +Equivalent to C. + + +=head2 C + +Closes C. Note that files are automatically closed when their +handles are garbage collected, but that takes an unpredictable amount +of time to happen. + + +=head2 C + +Saves any written data to C. + + +=head2 C + +Returns an iterator function that, each time it is called, returns a +new line from the file. Therefore, the construction + + for line in file:lines() do body end + +will iterate over all lines of the file. (Unlike C, this +function does not close the file when the loop ends.) + + +=head2 CEE)> + +Reads the file C, according to the given formats, which specify +what to read. For each format, the function returns a string (or a +number) with the characters read, or B if it cannot read data with +the specified format. When called without formats, it uses a default +format that reads the entire next line (see below). + +The available formats are + +=over + +=item * B<"*n":> reads a number; this is the only format that returns a +number instead of a string. + +=item * B<"*a":> reads the whole file, starting at the current +position. On end of file, it returns the empty string. + +=item * B<"*l":> reads the next line (skipping the end of line), +returning B on end of file. This is the default format. + +=item * B:> reads a string with up to this number of +characters, returning B on end of file. If number is zero, it +reads nothing and returns an empty string, or B on end of file. + +=back + + +=head2 C + +Sets and gets the file position, measured from the beginning of the +file, to the position given by C plus a base specified by the +string C, as follows: + +=over + +=item * B<"set":> base is position 0 (beginning of the file); + +=item * B<"cur":> base is current position; + +=item * B<"end":> base is end of file; + +=back + +In case of success, function C returns the final file position, +measured in bytes from the beginning of the file. If this function +fails, it returns B, plus a string describing the error. + +The default value for C is C<"cur">, and for C is 0. +Therefore, the call C returns the current file position, +without changing it; the call C sets the position to +the beginning of the file (and returns 0); and the call +C sets the position to the end of the file, and +returns its size. + + +=head2 C + +Sets the buffering mode for an output file. There are three available +modes: + +=over + +=item * B<"no":> no buffering; the result of any output operation +appears immediately. + +=item * B<"full":> full buffering; output operation is performed only +when the buffer is full (or when you explicitly C the file (see +C)). + +=item * B<"line":> line buffering; output is buffered until a newline +is output or there is any input from some special files (such as a +terminal device). + +=back + +For the last two cases, C specifies the size of the buffer, in +bytes. The default is an appropriate size. + + +=head2 CEE)> + +Writes the value of each of its arguments to the C. The arguments +must be strings or numbers. To write other values, use C or +C before C. + +=head2 5.8 - Operating System Facilities + +This library is implemented through table C. + + +=head2 C + +Returns an approximation of the amount in seconds of CPU time used by +the program. + + +=head2 C + +Returns a string or a table containing date and time, formatted +according to the given string C. + +If the C
. +Returns C. + + +=head2 C + +Sets the given function as a hook. The string C and the number +C describe when the hook will be called. The string mask may +have the following characters, with the given meaning: + +=over + +=item * B:> the hook is called every time Lua calls a function; + +=item * B:> the hook is called every time Lua returns from a +function; + +=item * B:> the hook is called every time Lua enters a new line +of code. + +=back + +With a C different from zero, the hook is called after every +C instructions. + +When called without arguments, C turns off the hook. + +When the hook is called, its first parameter is a string describing the +event that has triggered its call: C<"call">, C<"return"> (or C<"tail +return">, when simulating a return from a tail call), C<"line">, and +C<"count">. For line events, the hook also gets the new line number as +its second parameter. Inside a hook, you can call C with level +2 to get more information about the running function (level 0 is the +C function, and level 1 is the hook function), unless the +event is C<"tail return">. In this case, Lua is only simulating the +return, and a call to C will return invalid data. + + +=head2 C + +This function assigns the value C to the local variable with +index C of the function at level C of the stack. The +function returns B if there is no local variable with the given +index, and raises an error when called with a C out of range. +(You can call C to check whether the level is valid.) +Otherwise, it returns the name of the local variable. + + +=head2 C + +Sets the metatable for the given C to the given C
(which +can be B). + + +=head2 C + +This function assigns the value C to the upvalue with index +C of the function C. The function returns B if there is +no upvalue with the given index. Otherwise, it returns the name of the +upvalue. + + +=head2 C + +Returns a string with a traceback of the call stack. An optional +C string is appended at the beginning of the traceback. An +optional C number tells at which level to start the traceback +(default is 1, the function calling C). + +=head1 6 - Lua Stand-alone + +Although Lua has been designed as an extension language, to be embedded +in a host C program, it is also frequently used as a stand-alone +language. An interpreter for Lua as a stand-alone language, called +simply C, is provided with the standard distribution. The +stand-alone interpreter includes all standard libraries, including the +debug library. Its usage is: + + lua [options] [script [args]] + +The options are: + +=over + +=item * B>:> executes string I; + +=item * B>:> "requires" I; + +=item * B:> enters interactive mode after running I