User:Anomie/Lua reference manual

Introduction
This manual documents Lua as it is used in MediaWiki with the Scribunto extension. Some parts are derived from the Lua 5.1 reference manual, which is available under an MIT-style license.

This derivative manual may also be copied under the terms of the same license.

Getting started
On a MediaWiki wiki with Lua enabled, create a page with a title starting with "Module:", for example "Module:Bananas". Into this new page, copy the following text:

Save that, then on another (non-module) page, write:

Except that you should replace "Bananas" with whatever you called your module. This will call the "hello" function exported from that module. The will be replaced with the text that the function returned, in this case, "Hello, world!"

Tokens
Names (also called identifiers) in Lua can be any string of letters, digits, and underscores, not beginning with a digit. Names are case-sensitive; "foo", "Foo", and "FOO" are all different names.

The following keywords are reserved, and may not be used as names:  Names starting with an underscore followed by uppercase letters are reserved for internal Lua global variables.
 * and
 * break
 * do
 * else
 * elseif
 * end
 * false
 * for
 * function
 * if
 * in
 * local
 * nil
 * not
 * or
 * repeat
 * return
 * then
 * true
 * until
 * while

Other tokens are: 
 * &#x25;
 * &#3a;
 * &#3b;
 * ]
 * }
 * &#3a;
 * &#3b;
 * ]
 * }
 * &#3a;
 * &#3b;
 * ]
 * }
 * &#3b;
 * ]
 * }
 * ]
 * }
 * ]
 * }
 * ]
 * }
 * }
 * }
 * }

Comments
A comment starts with a  anywhere outside a string. If the  is immediately followed by an opening long bracket, the comment continues to the corresponding closing long bracket; otherwise the comment runs to the end of the current line.

Data types
Lua is a dynamically-typed language, which means that varibles and function arguments have no type, only the values assigned to them. All values carry a type.

Lua has eight basic data types, however only six are relevant to the Scribunto extension. The  function will return the type of a value.

The  function will convert a value to a string. The  function will convert a value to a number if possible, and otherwise will return nil. There are no explicit functions to convert a value to other data types.

Numbers are automatically converted to strings when used where a string is expected, e.g. when used with the concatenation operator. Strings recognized by  are automatically converted to numbers when used with arithmetic operators. When a boolean value is expected, all values other than nil and false are considered to be true.

nil
"Nil" is the data type of, which exists to represent the absence of a value. Nil is the only data type that may not be used as a key in a table, and there is no difference between an unassigned table key and a key assigned a nil value.

When converted to a string, the result is "nil". When converted to boolean, nil is considered false.

boolean
Boolean values are  and.

When converted to a string, the result is "true" or "false". Unlike many other languages, boolean values may not be directly converted to numbers. And unlike many other languages, only false and nil are considered false for boolean conversion; the number 0 and the empty string are both considered true.

string
Lua strings are considered a series of 8-bit bytes; it is up to the application to interpret them in any particular encoding.

String literals may be delimited by either single or double quotes ( or  ); like JavaScrpit and unlike PHP, there is no difference between the two. The following escape sequences are recognized: '\a' (bell), '\b' (backspace), '\f' (form feed), '\n' (newline), '\r' (carriage return), '\t' (horizontal tab), '\v' (vertical tab), '\\' (backslash), '\"' (double quote), and '\ (single quote). A literal newline may also be included in a string by preceeding it with a backslash. Bytes may also be specified using an escape sequence '\ddd', where ddd'' is the decimal value of the byte in the range 0–255. To include Unicode characters using escape sequences, the individual bytes for the UTF-8 encoding must be specified; in general, it will be more straightforward to enter the Unicode characters directly.

Literal strings can also be defined using long brackets. An opening long bracket consists of an opening square bracket followed by zero or more equal signs followed by another opening square bracket, e.g.,  , or. The opening long bracket must be matched by the corresponding closing long bracket, e.g.,  , or. Strings delimited by long brackets do not interpret escape sequences. As a special case, if an opening long bracket is immediately followed by a newline then the newline is not included in the string.

Note that all strings are considered true when converted to boolean. This is unlike most other languages, where the empty string is usually considered false.

number
Lua has only one numeric type, which is typically represented internally as a double-precision floating-point value. In this format, integers between -9007199254740992 and 9007199254740992 may be represented exactly, while higher and lower numbers will suffer from round-off error.

Numbers are specified using a period as a decimal separator and without grouping separators, e.g.  . Numbers may also be represented using E notation without spaces, e.g. ,  , or. Integers may also be specified in hexidecimal notation using a  prefix, e.g..

Although NaN and positive and negative infinities are correctly stored and handled, Lua does not provide corresponding literals. The constant  is positive infinity, as is a division such as , and a division such as   may be used to quickly generate a NaN.

Note that all numbers are considered true when converted to boolean. This is unlike most other languages, where the number 0 is usually considered false. When converted to a string, finite numbers are represented in decimal, possibly in E notation; NaN is "nan" or "-nan"; and infinities are "inf" or "-inf".

table
Lua tables are associative arrays, much like PHP arrays and JavaScript objects.

Tables are created using curly braces. The empty table is. To populate fields on creation, a comma- and/or semicolon-separated list of field specifiers may be included in the braces. These take any of several forms:
 * uses the (first) value of expression1 as the key and the (first) value of expression2 as the value.
 * is equivalent to
 * is roughly equivalent to, where i is an integer starting at 1 and incrementing with each field specification of this form. If this is the last field specifier and the expression has multiple values, all values are used; otherwise only the first is kept.

The fields in a table are accessed using bracket notation, e.g. . String keys that are also valid names may also be accessed using dot notation, e.g.   is equivalent to. Calling a function that is a value in the table may use colon notation, e.g., which is equivalent to.

A sequence is a table with non-nil values for all positive integers from 1 to N and no value (nil) for all positive integers greater than N. Many Lua functions operate only on sequences, and ignore non-positive-integer keys.

Unlike PHP or JavaScript, however, any value except nil and NaN may be used as a key. These are all valid and distinct:

Similarly, any value except nil may be stored as a value in a table. Storing nil is equivalent to deleting the key from the table, and accessing any key that has not been set will result in a nil value.

Note that tables are never implicitly copied in Lua; if a table is passed as an argument to the function and the function manipulates the keys or values in the table, those changes will be visible in the caller.

When converted to a string, the usual result is "table" but may be overridden using the __tostring metamethod. Even the empty table is considered true as a boolean.

function
Functions in Lua are first-class values: they may be created anonymously, passed as arguments, assigned to variables, and so on.

Functions are created using the  keyword, and called using parentheses. Syntactic sugar is available for named functions, local functions, and functions that act like member functions to a table. See Function declaration and Function calls below for details.

Lua functions are closures, meaning that they maintain a reference to the scope in which they are declared and can access and manipulate variables in that scope.

Like tables, if a function is assigned to a different variable or passed as an argument to another function, it is still the same underlying "function object" that will be called.

When converted to a string, the result is "function".

Unsupported types
The userdata type is used to hold opaque values for extensions to Lua written in other languages; for example, a userdata might be used to hold a C pointer or struct. To allow for use of Scribunto in hosting environments where custom-compiled code is not allowed, no such extensions are used.

The thread type represents the handles for coroutines, which are not available in Scribunto's sandbox.

Metatables
Every table may have an associated table known as a metatable. The fields in the metatable are used by some operators and functions to specify different or fallback behavior for the table. The metatable for a table may be accessed using the getmetatable function, and set with the setmetatable function.

Metatable fields are accessed as if with rawget.

Metatable fields that affect the table itself are:
 * __index : This is used when a table access  would return nil. If the value of this field is a table, the access will be repeated in that table, i.e.  . If the value of this field is a function, the function will be called as  . The rawget function bypasses this metamethod.
 * __newindex : This is used when assigning a key to a table  where   would return nil. If the value of this field is a table, the assignment will be repeated in that table, i.e.  . If the value of this field is a function, the function will be called as  . The rawset function bypasses this metamethod.
 * __call : This is used when function call syntax is used on a table, . The value must be a function, which is called as something like.
 * __mode : This is used to make tables holding weak references. The value must be a string. By default, any value that is used as a key or as a value in a table will not be garbage collected. But if this field contains the letter 'k', keys may be garbage collected, and if it contains 'v' values may be; in either case, both the corresponding key and value are removed from the table. Note that behavior is undefined if this field is altered after the table is used as a metatable.

Other metatable fields include: † For binary operators, Lua looks first at the left argument's metatable (if any) then the right's when looking for a metamethod to use. ‡ For relational operators, the metamethod is only used if the same function is specified in both arguments' metatables. Different anonymous functions, even with identical body and closure, may not be considered the same. * __metatable affects both getmetatable and setmetatable
 * __add†
 * __sub†
 * __mul†
 * __div†
 * __mod†
 * __pow†
 * __unm
 * __concat†
 * __eq‡
 * __lt‡
 * __le‡
 * __pairs
 * __ipairs
 * __metatable*
 * __tostring

Note: In Lua, all strings also share a single metatable, in which __index refers to the  table. This metatable is not accessible in Scribunto, nor is the referenced  table; the string table available to modules is a copy.

Variables
Variables are places that store values. There are three kinds of variables in Lua: global variables, local variables, and table fields.

A name represents a global or local variable (or a function argument, which is just a kind of local variable). Variables are assumed to be global unless explicitly declared as local using the  keyword. Any variable that has not been assigned a value is considered to have a nil value.

Global variables are stored in a standard Lua table called an environment; this table is often available as the global variable. It is possible to set a metatable for this global variable table; the __index and __newindex metamethods will be called for accesses of and assignments to global variables just as they would for accesses of and assignments to fields in any other table.

The environment for a function may be accessed using the getfenv function and changed using the setfenv function; in Scribunto, these functions are severely restricted if they are available at all.

Expressions
An expression is something that has values: literals (numbers, strings, true, false, nil), anonymous function declarations, table constructors, variable references, function calls, the vararg expression, expressions wrapped in parentheses, and unary operators applied to expressions, and expressions combined with binary operators.

Most expressions have one value; function calls and the vararg expression can have any number. Note that wrapping a function call or vararg expression in parentheses will lose all except the first value.

Expression lists are comma-separated lists of expressions. All except the last expression are forced to one value (dropping additional values, or using nil if the expression has no values); all values from the last expression are included in the values of the expression list.

Arithmetic operators
Lua supports the usual binary arithmetic operators: addition, subtraction, multiplication, division, modulo, exponentiation, and negation.

When all operands are numbers or strings for which tonumber returns non-nil, the operations have their usual meaning. Note that exponentiation will work correctly with non-integer exponents, and that modulo is defined as.

If either operand is a table with an appropriate metamethod, the metamethod will be called.

Relational operators
The relational operators in Lua are,  ,  ,  ,  , and. The result of a relational operator is always a boolean.

Equality first compares the types of its operands; if they are different, the result is false. Then it compares the values: nil, boolean, number, and string are compared in the expected manner. Functions are equal if they refer to the exact same function;  will return false, as it is comparing two different anonymous functions. Tables are by default compared in the same manner, but this may be changed using the __eq metamethod.

Inequality is the exact negation of equality.

For the ordering operators, if both are numbers or both are strings, they are compared directly. Next, metamethods are checked:  uses __lt;   uses __le if available, or if __lt is available than   is considered equivalent to  ;   is considered equivalent to  ; and   is considered equivalent to. If the necessary metamethods are not available, an error is raised.

Logical operators
The logical operators are,  , and. All use the standard interpretation where nil and false are considered false and anything else is considered true.

For, if the left operand is considered false then it is returned and the second operand is not evaluated; othewise the second operand is returned.

For, if the left operand is considered true then it is returned and the second operand is not evaluated; othewise the second operand is returned.

For, the result is always true or false.

Note that  and   short circuit. For example,  will only call   if   returns false.

Concatenation operator
The concatenation operator is two dots, used as. If both operands are numbers or strings, they are converted to strings and concatenated. Otherwise if a __concat metamethod is availabe, it is used. Otherwise, an error is raised.

Note that Lua strings are immutable and Lua does not provide any sort of "string builder", so a loop that repeatedly does  will have to create a new string for each iteration and eventually garbage-collect the old strings. If many strings need concatenating, it may be faster to use string.format or to insert all the strings into a sequence and use table.concat at the end.

Length operator
The length operator is, used as. If  is a string, it returns the length in bytes. If  is a, it returns the length of the sequence.

If  is a table that is not a sequence, the   may return any value N such that a[N] is not nil and a[N+1] is nil, even if there are non-nil values at higher indexes. For example,

Operator precedence
Lua's operator precedence, from highest to lowest:


 * not # - (negation)
 * + - (subtraction)
 * and
 * or
 * and
 * or
 * and
 * or

Within a precedence level, most binary operators are left-associative, i.e.  is interpreted as. Exponentiation and concatenation are right-associative, i.e.  is interpreted as.

Function calls
Lua function calls look like those in most other languages: a name followed by a list of arguments in parentheses:

func( exp-list )

As is usual with expression lists in Lua, the last expression in the list may supply multiple argument values.

If the function is called with fewer values in the expression list than there are arguments in the function definition, the extra arguments will have a nil value. If the expression list contains more values than there are arguments, the excess values are discarded. It is also possible for a function to take a variable number of arguments; see Function declataions for details.

Lua also allows direct calling of a function return value, i.e. . If an expression more complex than a variable access is needed to determine the function to be called, a parenthesized expression may be used in place of the variable access.

Lua has syntactic sugar for two common cases. The first is when a table is being used as an object, and the function is to be called as a method on the object. The syntax

table:name( exp-list )

is exactly equivalent to

table.name( table, exp-list )

The second common case is Lua's method of implementing named arguments by passing a table containing the name-to-value mappings as the only positional argument to the function. In this case, the parentheses around the argument list may be omitted. This also works if the function is to be passed a single literal string. For example, the calls

func{ arg1 = exp, arg2 = exp } func"string"

are equivalent to

func( { arg1 = exp, arg2 = exp } ) func( "string" )

These may be combined; the following calls are equivalent:

table:name{ arg1 = exp, arg2 = exp } table.name( table, { arg1 = exp, arg2 = exp } )

Function declarations
The syntax for function declaraion looks like this:

function ( var-list ) block end

All variables in var-list are local to the function, with values assigned from the expression list in the function call. Additional local variables may be declared inside the block.

When the function is called, the statements in block are executed after local variables corresponding to var-list are created and assigned values. If a return statement is reached, the block is exited and the values of the function call expression are those given by the return statement. If execution reaches the end of the function's block without encountering a return statement, the result of the function call expression has zero values.

Lua functions are lexical closures. A common idiom is to declare "private static" variables as locals in the scope where the function is declared. For example,

-- This returns a function that adds a number to its argument function makeAdder( n ) return function( x ) -- The variable n from the outer scope is available here to be added to x        return x + n     end end

local add5 = makeAdder( 5 ) mw.log( add5( 6 ) ) -- prints 11

A function may be declared to accept a variable number of arguments, by specifying  as the final item in the var-list:

function ( var-list, ... ) block end

Within the block, the varargs expression  may be used, with the result being all the extra values in the function call. For example,

local join = function ( separator, ... ) -- get the extra arguments as a table local args = { ... }    -- get the count of extra arguments, correctly local n = select( '#', ... ) return table.concat( args, sep, 1, n ) end

join( ', ', 'foo', 'bar', baz' ) -- returns the string "foo, bar, baz"

The select function is designed to work with the varargs expression; in particular,  should be used instead of   to count the number of values in the varargs expression.

Lua provides syntactic sugar to combine function declaraion and assignment to a variable; see Function declaration statements for details.

Note that this will not work:  local factorial = function ( n ) if n <= 2 then return n   else return n * factorial( n - 1 ) end end Since the function declaration is processed before the local variable assignment statement is complete, "factorial" inside the function body refers to the (probably undefined) global variable of that name. This problem may be avoided by declaring the local variable first and then assigning it in a subsequent statement.

Statements
A statement is the basic unit of execution: one assignment, control structure, function call, variable delcaration, etc.

A chunk is a sequence of statements, optionally separated by semicolons. A chunk is basically considered the body of an anonymous function, so it can declare local variables, receive arguments, and return values.

A block is also a sequence of statements, just like a chunk. A block can be delimited to create a single statement:. These may be used to limit the scope of local variables, or to add a  or   in the middle of another block.

Assignments
The variable-list is a comma-separated list of variables; the expression-list is a comma-separated list of one or more expressions. All expressions are evaluated before any assignments are performed, so  will swap the values of a and b.

Local variable declarations
Local variables may be declared anywhere within a block. The first form, without an expression list, declares the variables but does not assign a value so all variables have nil as a value. The second form assigns values to the local variables, as described in Assignments above.

Note that visibility of the local variable begins with the statement after the local variable declaration. So a declaration like  declares a local variable x and assigns it the value of x from the outer scope. The local variable remains in scope until the end of the innermost block containing the local variable declaration.

Control structures
The while statement repeats a block as long as an expression evaluates to a true value.

The repeat statement repeats a block until an expression evaluates to a true value. Local variables declared inside the block may be accessed in the expression.

The first form of the for loop will declare a local variable, and repeat the block for values from exp1 to exp2 adding exp3 on each iteration. exp3 may be omitted, in which case 1 is used. All expressions are evaluated once before the loop is started.

This form of the for loop is roughly equivalent to except that the variables var, limit, and step are not accessible anywhere else. Note that the variable name is local to the block; to use the value after the loop, it must be copied to a variable declared outside the loop.

The second form of the for loop works with iterator functions. As in the first form, the exp-list is evaluated only once before beginning the loop.

This form of the for loop is roughly equivalent to except that again the variables var, limit, and step are not accessible anywhere else. Note that the variables in var-list are local to the block; to use them after the loop, they must be copied to variables declared outside the loop.

Often the exp-list is a single function call that returns the three values. If the iterator function can be written so it only depends on the parameters passed into it, that would be the most efficient. If not, Programming in Lua suggests that a closure be preferred to returning a table as the static variable and updating its members on each iteration.

Executes block1 if exp1 returns true, otherwise executes block2 if exp2 returns true, and block3 otherwise. The  portion may be omitted, and the   portion may be repeated or omitted as necessary.

The return statement is used to return values from a function or a chunk (which is just a function). The expression-list is a comma-separated list of zero or more expressions. All expressions in the list are forced to one value except the last.

Lua implements tail calls: if expression-list contains exactly one expression which is a function call, the current stack frame will be reused for the call to that function. This has implication for functions that deal with the call stack, such as  and.

The return statement must be the last statement in the block. If for some reason a return is needed in the middle of a block, an explicit block  may be used.

The break statement is used to terminate the execution of a while, repeat, or for loop, skipping to the next statement after the loop.

The break statement must be the last statement in the block. If for some reason a break is needed in the middle of a block, an explicit block  may be used.

Function calls as statements
A function call may be used as a statement; in this case, the function is being called only for any side effects it may have (e.g. mw.log logs values) and any return values are discarded.

Function declaration statements
Lua provides syntactic sugar to make declaring a function and assigning it to a variable more natural. The following pairs of declaraions are equivalent

-- Basic declaration function func( var-list ) block end func = function ( var-list ) block end

-- Local function local function func( var-list ) block end local func; func = function ( var-list ) block end

-- Function as a field in a table function table.func( var-list ) block end table.func = function ( var-list ) block end

function table:func( var-list ) block end table.func = function ( self, var-list ) block end

Note the colon notation here parallels the colon notation for function calls, adding an implicit argument named "self" at the beginning of the arguments list.

Error handling
Errors may be "thrown" using the error function. To "catch" errors, use pcall or xpcall. Note that certain internal Scribunto errors cannot be caught in Lua code.

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 garbage collector from time to time to collect all dead objects (that is, objects that are no longer accessible from Lua). All memory used by Lua is subject to automatic management: tables, functions, strings, etc.

Garbage collection happens automatically, and cannot be configured from within Scribunto.

Standard libraries
The standard Lua libraries provide essential services and performance-critical functions to Lua. Only those portions of the standard libraries that are available in Scribunto are documented here.

_G
This variable holds a reference to the current global variable table; the global variable  may also be accessed as. Note, however, that there is nothing special about _G itself; it may be reassigned in the same manner as any other variable:

foo = 1 mw.log( foo ) -- logs "1" _G.foo = 2 mw.log( foo ) -- logs "2" _G = {}      -- _G no longer points to the global variable table _G.foo = 3 mw.log( foo ) -- still logs "2"

The global variable table may be used just like any other table. For example,

-- Call a function whose name is stored in a variable _G[var]

-- Log the names and stringified values of all global variables for k, v in pairs( _G ) do   mw.log( k, v ) end

-- Log the creation of new global variables setmetatable( _G, {    __newindex = function ( t, k, v )          mw.log( "Creation of new global variable '" .. k .. "'" )         rawset( t, k, v )     end } )

_VERSION
A string containing the running version of Lua, e.g. "Lua 5.1".

assert
If  is nil or false, issues an error. In this case,  is used as the text of the error: if nil (or unspecified), the text is "assertion failed!"; if a string or number, the text is that value; otherwise assert itself will raise an error.

If  is any other value, assert returns all arguments including   and.

error
Issues an error, with text.

normally adds some information about the location of the error. If  is 1 or omitted, that information is the location of the call to   itself; 2 uses the location of the call of the function that called error; and so on. Passing 0 omits inclusion of the location information.

getfenv
Note this function may not be available, depending on  in the engine configuration.

Returns an environment (global variable table), as specified by :
 * If 1, nil, omitted, returns the environment of the function calling . Often this will be the same as _G.
 * Integers 2–10 return the environment of functions higher in the call stack. For example, 2 returns the environment for the function that called the current function, 3 returns the environment for the function calling that function, and so on. An error will be raised if the value is higher than the number of function calls in the stack, or if the targeted stack level returned with a tail call.
 * Passing a function returns the environment that will be used when that function is called.

The environments used by all standard library functions, Scribunto library functions, are protected. Attempting to access these environments using  or   will result in an error.

getmetatable
Returns the metatable of a table. Any other type will return nil.

If the metatable has a __metatable field, that value will be returned instead of the actual metatable.

ipairs
Returns three values: an iterator function, the table, and 0. This is intended for use in the iterator form of :

for i, v = ipairs( t ) do    block end

This will iterate over the pairs ( 1, t[1] ), ( 2, t[2] ), and so on, stopping when t[i] would be nil.

The standard behavior may be overridden by providing an __ipairs metamethod. If that metamethod exists, the call to ipairs will return  instead.

next
This allows for iterating over the keys in a table. If  is nil or unspecified, returns the "first" key in the table and its value; otherwise, it returns the "next" key and its value. When no more keys are available, returns nil. It is possible to check whether a table is empty using the expression.

Note that the order in which the keys are returned is not specified, even for tables with numeric indexes. To traverse a table in numerical order, use a numerical for or ipairs.

Behavior is undefined if, when using next for traversal, any non-existing key is assigned a value. Assigning a new value (including nil) to an existing field is allowed.

pairs
Returns three values: an iterator function (next or a work-alike), the table, and nil. This is intended for use in the iterator form of :

for k, v = pairs( t ) do    block end

This will iterate over the key-value pairs in  just as next would; see the documentation for next for restrictions on modifying the table during traversal.

The standard behavior may be overridden by providing a __pairs metamethod. If that metamethod exists, the call to pairs will return  instead.

pcall
Calls the function  with the given arguments in protected mode. This means that if an error is raised during the call to, pcall will return false and the error message raised. If no error occurs, pcall will return true and all values returned by the call.

In pseudocode,  might be defined something like this:

function pcall( f, ... ) try return true, f( ... ) catch ( message ) return false, message end end

rawequal
This is equivalent to  except that it ignores any __eq metamethod.

rawget
This is equivalent to  except that it ignores any __index metamethod.

rawset
This is equivalent to  except that it ignores any __newindex metamethod.

select
If  is a number, returns all arguments in   after that number. If  is the string '#', returns the count of arguments in.

In other words,  is something roughly like the following except that it will work correctly even when   contains nil values (see documentation for # and unpack for the problem with nils).

function select( index, ... ) local t = { ... }    if index == '#' then return #t else return unpack( t, index ) end end

setmetatable
Sets the metatable of a table. may be nil, but must be explicitly provided.

If the current metatable has a __metatable field,  will throw an error.

tonumber
Tries to convert  to a number. If it is already a number or a string convertible to a number, then  returns this number; otherwise, it returns nil.

The optional  (default 10) specifies the base to interpret the numeral. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35.

In base 10, the value may have a decimal part, be expressed in E notation, and may have a leading "0x" to indicate base 16. In other bases, only unsigned integers are accepted.

tostring
Converts  to a string. See Data types above for details on how each type is converted.

The standard behavior for tables may be overridden by providing a __tostring metamethod. If that metamethod exists, the call to tostring will return  instead.

type
Returns the type of  as a string: "nil", "number", "string", "boolean", "table", or "function".

unpack
Returns values from the given table, something like  would do if written out manually. If nil or not given,  defaults to 1 and   defaults to.

Note that results are not deterministic if  is not a sequence and   is nil or unspecified; see Length operator for details.

xpcall
This is much like, except that the error message is passed to the function   before being returned.

In pseudocode,  might be defined something like this:

function xpcall( f, errhandler ) try return true, f catch ( message ) message = errhandler( message ) return false, message end end

debug.traceback
Returns a string with a traceback of the call stack. An optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback.

math.abs
Returns the absolute value of.

math.acos
Returns the arc cosine of  (in radians).

math.asin
Returns the arc sine of  (in radians).

math.atan
Returns the arc tangent of  (in radians).

math.atan2
Returns the arc tangent of  (in radians), using the signs of both parameters to find the quadrant of the result.

math.ceil
Returns the smallest integer larger than or equal to.

math.cos
Returns the cosine of  (in radians).

math.cosh
Returns the hyperbolic cosine of.

math.deg
Returns the angle  (given in radians) in degrees.

math.exp
Returns the value $$e^x$$.

math.floor
Returns the largest integer smaller than or equal to.

math.fmod
Returns the remainder of the division of  by   that rounds the quotient towards zero.

math.frexp
Returns two values  and   such that:
 * If  is finite and non-zero, $$x = m \times 2^e$$,   is an integer, and the absolute value of   is in the range $$[0.5, 1)$$
 * If  is zero,   and   are 0
 * If  is NaN or infinite,   is   and   is not specified

math.huge
The value representing positive infinity; larger than or equal to any other numerical value.

math.ldexp
Returns $$m \times 2^e$$ ( should be an integer).

math.log
Returns the natural logarithm of.

math.log10
Returns the base-10 logarithm of.

math.max
Returns the maximum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if  is NaN, but any other NaNs will be ignored.

math.min
Returns the minimum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if  is NaN, but any other NaNs will be ignored.

math.modf
Returns two numbers, the integral part of  and the fractional part of.

math.pi
The value of $$\pi$$.

math.pow
Equivalent to.

math.rad
Returns the angle  (given in degrees) in radians.

math.random
Returns a pseudo-random number.

The arguments  and   may be omitted, but if specified must be convertible to integers.
 * With no arguments, returns a real number in the range $$[0,1)$$
 * With one argument, returns an integer in the range $$[1,m]$$
 * With two arguments, returns an integer in the range $$[m,n]$$

math.randomseed
Sets  as the seed for the pseudo-random generator.

Note that using the same seed will cause  to output the same sequence of numbers.

math.sin
Returns the sine of  (in radians).

math.sinh
Returns the hyperbolic sine of.

math.sqrt
Returns the square root of. Equivalent to.

math.tan
Returns the tangent of  (in radians).

math.tanh
Returns the hyperbolic tangent of.

os.clock
Returns an approximation of the amount in seconds of CPU time used by the program.

os.date

 * Language library's formatDate may be used for more comprehensive date formatting

Returns a string or a table containing date and time, formatted according to. If the format is omitted or nil, "%c" is used.

If  is given, it is the time to be formatted (see [[#os.time|  starts with '!', then the date is formatted in UTC rather than the server's local time. After this optional character, if format is the string "*t", then date returns a table with the following fields:
 * year (full)
 * month (1–12)
 * day (1–31)
 * hour (0–23)
 * min (0–59)
 * sec (0–61)
 * wday (weekday, Sunday is 1)
 * yday (day of the year)
 * isdst (daylight saving flag, a boolean; may be absent if the information is not available)

If format is not "*t", then date returns the date as a string, formatted according to the same rules as the C function strftime.

os.difftime
Returns the number of seconds from  to.

os.time
Returns a number representing the current time.

When called without arguments, returns the current time. If passed a table, the time encoded in the table will be parsed. The table must have the fields "year", "month", and "day", and may also include "hour" (default 12), "min" (default 0), "sec" (default 0), and "isdst".

require
Loads the specified module.

First, it looks in  to see if the module is already loaded. If so, returns.

Otherwise, it calles each loader in the  sequence to attempt to find a loader for the module. If a loader is found, that loader is called. The value returned by the loader is stored into  and is returned.

See the documentation for  for information on the loaders available.

package.loaded
This table holds the loaded modules. The keys are the module names, and the values are the values returned when the module was loaded.

package.loaders
This table holds the sequence of searcher functions to use when loading modules. Each searcher function is called with a single argument, the name of the module to load. If the module is found, the searcher must return a function that will actually loads the module and return the value to be returned by require. Otherwise, it must return nil.

Scribunto provides two loaders:
 * 1) Look in   for the loader function
 * 2) Look in the modules provided with Scribunto for the module name, and if that fails look in the Module: namespace. The "Module:" prefix must be provided.

Note that the standard Lua loaders are not included.

package.preload
This table holds loader functions, used by the first loader Scribunto includes in package.loaders.

package.seeall
Sets the __index metamethod for  to _G.

String library
In all string functions, the first character is at position 1, not position 0 as in C, PHP, and JavaScript. Indexes may be negative, in which case they count from the end of the string: position -1 is the last character in the string, -2 is the second-last, and so on.

The string library assumes one-byte character encodings. To operate on Unicode strings, use the corresponding methods in the Scribunto Ustring library.

string.byte
Returns the byte values for,  , ···,. The default value for  is 1; the default value for  is.

string.char
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the byte value equal to its corresponding argument.

string.find
Looks for the first match of  in the string. If it finds a match, then  returns the offsets in   where this occurrence starts and ends; otherwise, it returns nil. If the pattern has captures, then in a successful match the captured values are also returned after the two indices.

A third, optional numerical argument  specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument  turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in   being considered "magic".

Note that if  is given, then   must be given as well.

string.format
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 uses a limited subset of the format specifiers:
 * Recognized flags are '-', '+', ' ', '#', and '0'.
 * Integer field widths up to 99 are supported. '*' is not supported.
 * Integer precisions up to 99 are supported. '*' is not supported.
 * Length modifiers are not supported.
 * Recognized conversion specifiers are 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%', and the non-standard 'q'.
 * Positional specifiers (e.g. "%2$s") are not supported.

The conversion specifier 'q' is like 's', but formats the 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.

Conversion between strings and numbers is performed as specified in Data types; other types are not automatically converted to strings. Strings containing NUL characters (byte value 0) are not properly handled.

string.gmatch
Returns an iterator function that, each time it is called, returns the next captures from  over string. If  specifies no captures, then the whole match is produced in each call.

For this function, a ' ' at the start of a pattern is not magic, as this would prevent the iteration. It is treated as a literal character.

string.gsub
Returns a copy of  in which all (or the first , if given) occurrences of the   have been replaced by a replacement string specified by  , which can be a string, a table, or a function. also returns, as its second value, the total number of matches that occurred.

If  is a string, then its value is used for replacement. The character  works as an escape character: any sequence in   of the form  , with n between 1 and 9, stands for the value of the n-th captured substring. The sequence  stands for the whole match, and the sequence   stands for a single.

If  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  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 false or nil, then there is no replacement (that is, the original match is kept in the string).

string.len
Returns the length of the string, in bytes. Is not confused by ASCII NUL characters. Equivalent to.

string.lower
Returns a copy of this string with all ASCII uppercase letters changed to lowercase. All other characters are left unchanged.

string.match
Looks for the first match of  in the string. If it finds one, then  returns the captures from the pattern; otherwise it returns nil. If  specifies no captures, then the whole match is returned.

A third, optional numerical argument  specifies where to start the search; its default value is 1 and can be negative.

string.rep
Returns a string that is the concatenation of  copies of the string.

string.reverse
Returns a string that is the string  reversed (bytewise).

string.sub
Returns the substring of  that starts at   and continues until  ;   and   can be negative. If  is nil or omitted, -1 is used.

In particular, the call  returns a prefix of   with length , and   returns a suffix of   with length.

string.upper
Returns a copy of this string with all ASCII lowercase letters changed to uppercase. All other characters are left unchanged.

Character class
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:


 * x: (where x is not one of the magic characters ) represents the character x itself.
 *  : (a dot) represents all characters.
 *  : represents all ASCII letters.
 *  : represents all ASCII control characters.
 *  : represents all digits.
 *  : represents all ASCII lowercase letters.
 *  : represents all punctuation characters.
 *  : represents all ASCII space characters.
 *  : represents all ASCII uppercase letters.
 *  : represents all ASCII alphanumeric characters.
 *  : represents all hexadecimal digits.
 *  : represents ASCII NUL, the zero byte.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a ' ' when used to represent itself in a pattern.
 *  : represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range with a ' '. All classes  described above can also be used as components in set. All other characters in set represent themselves. For example,   (or  ) represents all alphanumeric characters plus the underscore,   represents the octal digits, and   represents the octal digits plus the lowercase letters plus the ' ' character. The interaction between ranges and classes is not defined. Therefore, patterns like   or   have no meaning.
 *  : represents the complement of set, where set is interpreted as above.

Pattern items
A pattern item can be


 * a single character class, which matches any single character in the class;
 * a single character class followed by ' ', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
 * a single character class followed by ' ', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
 * a single character class followed by ' ', which also matches 0 or more repetitions of characters in the class. Unlike ' ', these repetition items will always match the shortest possible sequence;
 * a single character class followed by ' ', which matches 0 or 1 occurrence of a character in the class;
 * , for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
 * , where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item  matches expressions with balanced parentheses.

Pattern
A pattern is a sequence of pattern items.

A ' ' at the beginning of a pattern anchors the match at the beginning of the subject string. A ' ' at the end of a pattern anchors the match at the end of the subject string. At other positions, ' ' and ' ' have no special meaning and represent themselves.

Captures
A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored ("captured") for future use. Captures are numbered according to their left parentheses. For instance, in the pattern, the part of the string matching   is stored as the first capture (and therefore has number 1); the character matching   is captured with number 2, and the part matching   has number 3.

As a special case, the empty capture  captures the current string position (a number). For instance, if we apply the pattern  on the string , there will be two captures: 3 and 5.

A pattern cannot contain embedded zero bytes (ASCII NUL). Use  instead.

Table library
Most functions in the table library assume that the table represents an sequence.

The functions,  , and   may be available but are deprecated. Use a for loop with pairs, a for loop with ipairs, and the length operator instead.

table.concat
Given an array where all elements are strings or numbers, returns.

The default value for  is the empty string, the default for   is 1, and the default for   is the length of the table. If  is greater than , returns the empty string.

table.insert
Inserts element  at position   in , shifting up other elements to open space, if necessary. The default value for  is the length of the table plus 1, so that a call   inserts   at the end of table.

table.maxn
Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices.

To do this, it iterates over the whole table. This is roughly equivalent to

function table.maxn( table ) local maxn, k = 0, nil repeat k = next( table, k ) if type( k ) == 'number' and k > maxn then maxn = k        end until not k    return maxn end

table.remove
Removes from  the element at position  , shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for  is the length of the table, so that a call   removes the last element of table.

table.sort
Sorts table elements in a given order, in-place, from  to. If  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   will be true after the sort). If  is not given, then the standard Lua operator   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.

Scribunto libraries
FILL IN

Differences from standard Lua
FILL IN