# Extensión:Scribunto/Manual de referencia de Lua

This page is a translated version of the page Extension:Scribunto/Lua reference manual and the translation is 13% complete.
Outdated translations are marked like this.

Este manual documenta Lua como es usado en MediaWiki con la extensión Scribunto. Algunas partes están basadas en el manual de referencia de Lua 5.1, que está disponible bajo la licencia MIT.

## Introducción

### Primeros pasos

En una wiki MediaWiki con Scribunto habilitado, crear una página con un título que empieze con "Módulo:", por ejemplo "Módulo:Bananas". En esta página nueva, copia el siguiente texto:

local p = {} --p es por paquete

function p.hello( frame )
return "Hello, world!"
end

return p


Guárdalo, y en otra página, que no sea un módulo, escribe:

{{#invoke:Bananas|hello}}


Excepto que debes reemplazar "Bananas" con el nombre de tu módulo. Esto llamará a la función "hola" exportada desde ese módulo. {{#invoke:Bananas|hello}} será reemplazado por el texto que devolvió la función, en este caso, Hello, world!

Por lo general, es una buena idea invocar el código Lua desde el contexto de una plantilla. Esto significa que desde la perspectiva de una página de llamada, la sintaxis es independiente de si la lógica de la plantilla está implementada en Lua o en wikitexto. También evita la introducción de sintaxis compleja adicional en el espacio de nombres principal de una wiki.

### Estructura del módulo

El módulo debe devolver una tabla con las funciones que pueden ser llamadas mediante {{#invoke:}}. Generalmente, como se muestra anteriormente, se declara una variable local, asignándole una tabla; se añaden las funciones a la tabla, y se devuelve la tabla al final del código.

Todas las funciones que no se añadan a la tabla, sean globales o locales, no podrán ser llamadas por {{#invoke:}}, pero las variables globales pueden ser accesibles desde otros módulos cargados mediante la función require(). Se considera una buena práctica declarar todas las variables y funciones de manera local.

### Obteniendo los parámetros desde el wikitexto

Las funciones llamadas con {{#invoke:}} recibirán un solo parámetro: un [[{{#invoke:}}|objeto Frame]]. Para obtener los parámetros pasados mediante {{#invoke:}}, se usa normalmente el [[args|atributo args de ese objeto]]. También es posible obtener los parámetros pasados a la plantilla que contiene la instrucción {{#invoke:}} usando frame:getParent(), y accediendo al atributo args de ese objeto.

Este objeto frame es usado también para usar funciones específicas del motor de wikitexto, como llamar parser functions, expandir plantillas, o expandir cualquier cadena de wikitexto en general.

### Devolviendo texto

La función del módulo debe devolver usualmente una cadena de texto; aunque cualquier valor que se devuelva será pasada a tostring() y concatenada con el separador nulo. La cadena resultante es la que substituirá al {{#invoke:}} en el wikitexto.

En este momento del análisis de la página, las plantillas ya se han expandido, los parser functions y las extension tags ya se habrán procesado, así como algunas transformaciones, como la expansión de la firma y el truco de la tubería. Por lo tanto, el módulo no podrá incluir esas características en el texto a devolver. Por ejemplo, si el módulo devuelve "Hello, [[world]]! {{welcome}}", la página mostrará "Hello, world! {{welcome}}".

Por otro lado, la substitución se procesa en los primeros pasos del análisis, así que {{subst:#invoke:}} fallará, aunque otras substituciones no. Como el prefijo subst quedará presente en el wikitexto, será procesado en la siguiente edición. Generalmente esto es algo que se debe evitar.

### Documentación del módulo

Scribunto permite que los módulos sean documentados, asociando el módulo con una página de wikitexto. Predeterminadamente, se usa la subpágina «/doc» para esto, y es transcluida antes del código fuente en la página del módulo. Por ejemplo, la documentación para «Módulo:Bananas­­­» estará en «Módulo:Bananas/doc».

Esto puede configurarse usando los siguientes mensajes MediaWiki:

• scribunto-doc-page-name —Establece el nombre de la página usada para la documentación. El nombre del módulo, sin el prefijo 'Módulo' es pasado como $1. Aunque la página esté en el espacio de nombres Módulo:, la página será interpretada como wikitexto, no como código Lua, y no podrá usarse con {{#invoke:}}. Predeterminadamente es 'Módulo:$1/doc'. Note that parser functions and other brace expansion may not be used in this message.
• scribunto-doc-page-does-not-exist — Mensaje mostrado cuando la subpágina no exista. El nombre de la página es pasado como $1. Predeterminadamente está vacío. • scribunto-doc-page-show — Mensaje mostrado cuando la página de documentación exista. El nombre de la página es pasado como $1. Predeterminadamente se transcluye la página de documentación.
• scribunto-doc-page-header — Encabezado mostrado cuando se visualiza la página de documentación misma. El nombre del módulo documentado es pasado como $1. Predeterminadamente muestra una breve descripción en itálica. Nótese que los módulos no pueden categorizarse directamente, y tampoco pueden contener interwikis. Éstos pueden detallarse en la página de documentación, dentro de las etiquetas ‎<includeonly>...‎</includeonly>, en donde serán aplicados al módulo cuando la página de documentación sea transcluida en la página del módulo. ## Lenguaje Lua ### Símbolos Un nombre (o identificador) en Lua puede ser cualquier conjunto de letras, dígitos y guiones bajos, que no comience con un dígito. Los nombres diferencian mayúsculas de minúsculas: «foo», «Foo» y «FOO» son tres nombres distintos. Las siguientes palabras clave están reservadas y no pueden usarse como nombres: • and • break • do • else • elseif • end • false • for • function • if • in • local • nil • not • or • repeat • return • then • true • until • while Los nombres que empiecen por un guion bajo, seguido de letras mayúsculas están reservados para las variables globales internas de Lua. Otros símbolos son: • # • % • ( • ) • * • + • , • - • -- • . • .. • ... • / • : • ; • < • <= • = • == • > • >= • [ • ] • ^ • { • } • ~= ### Comentarios Un comentario inicia con -- en cualquier lugar que no sea dentro de una cadena de texto. Si -- es inmediatamente seguido por un corchete de apertura, el comentario continuará hasta que haya un corchete de cierre, de lo contrario, terminará al final de la línea. -- Un comentario en Lua inicia con dos guiones y termina al final de la línea. --[[ Los comentarios multilínea son adornados con dos corchetes ]] --[=[ Los comentarios como éste pueden tener otros [[comentarios]] anidados. ]=] --[==[ Los comentarios como éste pueden tener otros --[===[ comentarios --[=[largos]=] --anidados ]===] varias veces, ¡incluso si no todos ellos --[[ están delimitados con sus corchetes correspondientes! ]===] ]==]  ### Tipos de datos Lua es un lenguaje de tipado dinámico, lo que significa que las variables y los argumentos de función no tienen un tipo establecido, sólo los valores asignados a ellos. Todos los valores tienen un tipo. Lua tiene ocho tipos de datos básicos, aunque solo seis de ellos son relevantes en Scribunto. La función type() devolverá el tipo del valor. La función tostring() convertirá un valor a una cadena de texto. La función tonumber() convertirá un valor a un número, si es posible, de lo contrario, devolverá el valor nil. No hay funciones explícitas para convertir un valor a otros tipos de datos. Los números son convertidos automáticamente a cadenas cuando son usados donde se espera una cadena, por ejemplo, cuando son parte de una concatenación. Las cadenas reconocidas por tonumber() son convertidas automáticamente a números cuando se usan junto con operadores aritméticos. Cuando se espera un valor booleano, todos los valores que no sean nil o false se consideran verdaderos. #### nil 'nil' es el tipo de datos de nil, que existe para representar la ausencia de un valor. Nil no puede ser usado como clave en una tabla, y no hay diferencia alguna entre la clave de una tabla a la que no se le haya asignado valor alguno, y a una a la que se le haya asignado un valor nil. Cuando se convierte a una cadena, el resultado es 'nil'. Cuando se convierte a un valor booleano, nil es considerado false. #### boolean Los valores booleanos son true y false. Cuando se convierte a una cadena, el resultado es 'true' o 'false'. A diferencia de otros lenguajes, los valores booleanos no pueden ser convertidos directamente a números, y además, sólo false y nil son considerados como false al hacer la conversión, por lo que el número 0 y la cadena vacía son consideradas true. #### string Las cadenas en Lua son conjuntos de bytes de 8 bits, y depende de la aplicación interpretar la codificación usada. Las literales pueden ser delimitadas tanto por comillas simples o dobles; y como en JavaScript y a diferencia de PHP, no hay diferencia entre usar una u otra. Se reconocen las siguientes secuencias de escape: • \a (campana, byte 7) • \b (retroceso, byte 8) • \t (tabulador horizontal, byte 9) • \n (salto de línea, byte 10) • \v (tabulador vertical, byte 11) • \f (alimentación, byte 12) • \r (retorno de carro, byte 13) • \" (comilla doble, byte 34) • \' (comilla simple, byte 39) • \\ (diagonal inversa, byte 92) Una cadena literal puede incluirse en una cadena si se le antepone una diagonal inversa. Los puntos de código pueden ser especificados usando la secuencia de escape '\ddd', donde ddd es el valor decimal del byte en el rango 0-255. Para incluir caracteres Unicode usando secuencias de escape, se deben especificar todos los bytes individuales que componen al caracter según la codificación UTF-8, de modo que en general será más práctico escribir directamente los caracteres Unicode. Las cadenas literales pueden definirse con corchetes largos. Un corchete largo de apertura consiste en un corchete de apertura seguido por cero o más signos de igualdad, seguido por otro corchete de apertura, por ejemplo, [[, [=[, o [=====[. Cada corchete largo de apertura debe tener su correspondiente corchete largo de cierre, por ejemplo, ]], ]=], o ]=====]. Como un caso especial, si un corchete largo de apertura es seguido inmediatamente por un salto de línea, este salto de línea no será incluido en la cadena, pero un salto de línea justo antes de un corchete largo de cierre sí. En las cadenas delimitadas por corchetes largos no se procesan las secuencias de escape. -- Esta cadena larga foo = [[ bar\tbaz ]] -- es equivalente a esta cadena delimitada por comillas foo = 'bar\\tbaz\n'  Nótese que todas las cadenas son consideradas true cuando se convierten a booleanos, a diferencia de otros lenguajes, donde la cadena vacía es considerada false. #### number Lua tiene solamente un tipo numérico, normalmente representado internamente como un valor de coma flotante de doble precisión. En este formato, los enteros entre -9007199254740992 y 9007199254740992 pueden ser representados exactamente, mientras que números mayores y con decimales pueden sufrir redondeos. Las constantes numéricas se especifican usando el punto como separador decimal, y sin separadores de millares, por ejemplo, 123456.78. Los números pueden ser representados mediante notación científica, sin espacios, por ej., 1,23e10, 123.45e20 o 1.23E5. Los enteros también pueden ser especificados en notación hexadecimal usando el prefijo 0x, por ejemplo, 0x3A. Aunque NaN y los infinitos positivo y negativo son correctamente guardados y procesados, Lua no provee cadenas literales para estos valores. La constante math.huge es infinito positivo, igual que una división como 1/0, y una división como 0/0 puede usarse para generar rápidamente un valor NaN. Nótese que todos los números son considerados true cuando son convertidos a booleanos, a diferencia de otros lenguajes, donde el número 0 es considerado false. Cuando se convierten a decimal, los números se representan en decimal, posiblemente en notación científica, NaN is 'nan' o '-nan', y los infinitos son 'inf' o '-inf'. #### table Las tablas en Lua son estructuras asociativas, parecidas a los arrays en PHP y a los objetos de JavaScript. Las tablas son creadas usando llaves. La tabla vacía es representada como {}. Para asignar valores al momento de la creación, una lista de asignaciones separada por comas o puntos y comas. Éstas pueden tomar una de las siguientes formas: • [expresión1] = expresión2usa el primen valor de expresión1 como la clave, y el primer valor de expresión2 como el valor. • name = expresión es equivalente a ["nombre"] = expresión • expresión es prácticamente equivalente a [i] = expresión, donde i es un entero que empieza en 1 , y se va incrementando en cada asignación que tenga esta forma. Si ésta es la última asignación, y la expresión tiene muchos valores, todos los valores son usados, de lo contrario solo se usa el primero. Los campos en una tabla se obtienen usando corchetes, p.ej., table[key]. Las claves que también son nombres válidos también pueden ser accedidas usando un punto, p.ej., table.key es equivalente a table['key']. Se puede llamar a una función que esté dentro de una tabla usando dos puntos, p.ej., table:func( ... ) es equivalente a table['func']( table, ... ) o a table.func( table, ... ). Una secuencia es una tabla con valores (excepto nil) para todos los enteros positivos desde 1 hasta n, y con valores nil para todos los enteros positivos mayores que n. Muchas funciones en Lua operan solo sobre secuencias, e ignoran las claves que no sean enteros positivos. A diferencia de otros lenguajes como PHP o JavaScript, cualquier valor excepto nil y NaN puede ser usado como clave, y no se realiza ninguna conversión de tipo. Todos estos son válidos y distintos: -- Crear tabla t = {} t["foo"] = "foo" t.bar = "bar" t[1] = "uno" t[2] = "dos" t[3] = "tres" t[12] = "el número doce" t["12"] = "la cadena doce" t[true] = "true" t[tonumber] = "sí, también las funciones pueden ser claves de tablas" t[t] = "sí, una tabla también puede ser una clave de tabla. Incluso en sí misma." -- Esto crea una tabla aproximadamente equivalente a la anterior t2 = { foo = "foo", bar = "bar", "uno", "dos", [12] = "el número doce", ["12"] = "la cadena doce", "tres", [true] = "true", [tonumber] = "sí, también las funciones pueden ser claves de tablas", } t2[t2] = "sí, una tabla también puede ser una clave de tabla. Incluso en sí misma."  De igual forma, cualquier valor excepto nil puede ser guardado como valor en una tabla. Guardar nil es equivalente a borrar la clave de la tabla, y acceder a cualquier clave que no haya sido asignada resultará en un valor nil. Nótese que las tablas nunca son copiadas implícitamente en Lua; si la tabla es pasada como argumento y la función manipula las claves o los valores en la tabla, estos cambios persistirán después de la llamada. Cuando se convierte a una cadena, el resultado usual es 'table', pero puede ser modificado usando el __tostring metamétodo. Incluso una tabla vacía es considerado true al convertirla a booleano. #### function Las funciones en Lua son valores de primera clase: pueden crearse anónimamente, ser pasados como argumentos, ser asignados a variables, y así. Las funciones se crean usando la palabra clave function, y llamadas usando paréntesis. Hay formas especiales para funciones con nombre, funciones locales y funciones que actúan como funciones miembro de una tabla. Vea Declaracianes de funciones y Llamadas a funciones para más detalles. Las funciones son clausuras, es decir, que mantienen una referencia al ámbito en el que son declarados, y pueden acceder y manipular variables en su ámbito. Como las tablas, si una función es asignada a una variable diferente, o pasada como argumento a otra función, se llamará al mismo 'objeto de función'. Cuando una función se convierte a una cadena, el resultado es "function". #### Tipos no soportados El tipo userdata es usado para manejar valores opacos para extensiones de Lua escritos en otros lenguajes; por ejemplo, un objeto userdata puede ser usado para manejar un puntero de C. Para permitir ejecutar Scribunto en entornos donde no se permite la compilación de código modificado, estas extensiones no se usan. El tipo thread representa a los controladores para las corutinas, que no están disponibles en el entorno de Scribunto. ### Metatablas Cada tabla tiene asociada otra tabla conocida como metatabla. Los campos en la metatabla son usados por algunos operadores y funciones para especificar comportamientos diferentes o predeterminados para la tabla. La metatabla de una tabla puede accederse usando la función getmetatable(), y asignada con la función setmetatable(). Cuando son accedidas por sus metafunciones, los campos de las metatablas se obtienen con la función rawget(). Los campos de las metatablas que afectan a la tabla misma son: __index Se usa cuando una tabla, al acceder a t[clave], pudiese devolver nil. Si el valor de este campo es una tabla, el acceso será repetido en aquella tabla; por ejemplo, __index[clave] (lo que invocaría a la tabla __index de la metatabla de la tabla en cuestión). Si el valor de este campo es una función, la función será llamada como __index(t, clave). La función rawget() obvia este metamétodo. __newindex Se usa cuando se asigna una clave a una tabla t[clave] = valor, donde rawget( t, key ) devolvería nil. Si el valor de este campo es una tabla, la asignación se repetirá en esa tabla. Por ejemplo, __newindex[clave] = valor (lo que invocaría a la metatabla __newindex de esa tabla). Si el valor d ese campo es una función, la función será llamada como __newindex(t, clave, valor). La función rawset() obvia este metamétodo. __call This is used when function call syntax is used on a table, t( ··· ). The value must be a function, which is called as something like __call( t, ··· ). __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 metafield contains the letter 'k', keys may be garbage collected if there are no non-weak references, 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() Note: In Lua, all strings also share a single metatable, in which __index refers to the string table. This metatable is not accessible in Scribunto, nor is the referenced string 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 local 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 _G. 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. Local variables are lexically scoped; see Local variable declarations for details. ### 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, 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 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. If either operand is a table with an appropriate metamethod, the metamethod will be called. Operator Function Ejemplo Metamethod Apuntes + Addition a + b __add - Subtraction a - b __sub * Multiplication a * b __mul / Division a / b __div division by zero is not an error; NaN or infinity will be returned % Modulo a % b __mod defined as a % b == a - math.floor( a / b ) * b ^ Exponentiation a ^ b __pow non-integer exponents are allowed - Negation -a __unm #### 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 object; function() end == function() end 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: • a < b uses __lt • a <= b uses __le if available, or if __lt is available then it is considered equivalent to not ( b < a ) • a > b is considered equivalent to b < a • a >= b is considered equivalent to b <= a If the necessary metamethods are not available, an error is raised. #### Logical operators The logical operators are and, or, and not. All use the standard interpretation where nil and false are considered false and anything else is considered true. For and, if the left operand is considered false then it is returned and the second operand is not evaluated; otherwise the second operand is returned. For or, if the left operand is considered true then it is returned and the second operand is not evaluated; otherwise the second operand is returned. For not, the result is always true or false. Note that and and or short circuit. For example, foo() or bar() will only call bar() if foo() returns false or nil as its first value. #### Concatenation operator The concatenation operator is two dots, used as a .. b. If both operands are numbers or strings, they are converted to strings and concatenated. Otherwise if a __concat metamethod is available, 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 a = a .. b 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 #a. If a is a string, it returns the length in bytes. If a is a sequence table, it returns the length of the sequence. If a is a table that is not a sequence, the #a may return 0 or 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, -- This is not a sequence, because a[3] is nil and a[4] is not. a = { 1, 2, nil, 4 } -- This may output either 2 or 4. -- And this may change even if the table is not modified. mw.log( #a )  #### Operator precedence Lua's operator precedence or order of operations, from highest to lowest: 1. ^ 2. not # - (negation) 3. * / % 4. + - (subtraction) 5. .. 6. < > <= >= ~= == 7. and 8. or Within a precedence level, most binary operators are left-associative, i.e. a / b / c is interpreted as (a / b) / c. Exponentiation and concatenation are right-associative, i.e. a ^ b ^ c is interpreted as a ^ (b ^ c). #### Function calls Lua function calls look like those in most other languages: a name followed by a list of arguments in parentheses: func( expression-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 declarations for details. Lua also allows direct calling of a function return value, i.e. func()(). 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( expression-list )  is exactly equivalent to table.name( table, expression-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 declaration looks like this: function nameoptional ( var-listoptional ) 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 nameoptional ( var-list, ... ) block end -- or function nameoptional ( ... ) 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 new table local args = { ... } -- get the count of extra arguments, correctly local n = select( '#', ... ) return table.concat( args, separator, 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, select( '#', ... ) should be used instead of #{ ... } to count the number of values in the varargs expression, because { ... } may not be a sequence. Lua provides syntactic sugar to combine function declaration 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) variable of that name in an outer scope. This problem may be avoided by declaring the local variable first and then assigning it in a subsequent statement, or by using the function declaration statement syntax. ### Statements A statement is the basic unit of execution: one assignment, control structure, function call, variable declaration, 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: do block end. These may be used to limit the scope of local variables, or to add a return or break in the middle of another block. #### Assignments variable-list = expression-list 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 a, b = b, a will swap the values of a and b. #### Local variable declarations local variable-list local variable-list = expression-list Local variables may be declared anywhere within a block or chunk. 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 local x = x 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 while exp do block end The while statement repeats a block as long as an expression evaluates to a true value. repeat block until exp 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. for name = exp1, exp2, exp3 do block end for name = exp1, exp2 do block end This 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. Note that exp3 may be omitted entirely, in which case 1 is used, but non-numeric values such as nil and false are an error. All expressions are evaluated once before the loop is started. This form of the for loop is roughly equivalent to do local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 ) if not ( var and limit and step ) then error() end while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do local name = var block var = var + step end end  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. for var-list in expression-list do block end The second form of the for loop works with iterator functions. As in the first form, the expression-list is evaluated only once before beginning the loop. This form of the for loop is roughly equivalent to do local func, static, var = expression-list while true do local var-list = func( static, var ) var = var1 -- ''var1'' is the first variable in ''var-list'' if var == nil then break end block end end  except that again the variables func, static, and var 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 expression-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. if exp1 then block1 elseif exp2 then block2 else block3 end Executes block1 if exp1 returns true, otherwise executes block2 if exp2 returns true, and block3 otherwise. The else block3 portion may be omitted, and the elseif exp2 then block2 portion may be repeated or omitted as necessary. return expression-list 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. Lua implements tail calls: if expression-list consists of 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 getfenv() and debug.traceback(). The return statement must be the last statement in its block. If for some reason a return is needed in the middle of a block, an explicit block do return end may be used. break 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 its block. If for some reason a break is needed in the middle of a block, an explicit block do break end 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 declarations 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 as a method in a table 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() and assert() functions. 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) and objects that are only reachable via weak references. 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. ### Basic functions #### _G This variable holds a reference to the current global variable table; the global variable foo may also be accessed as _G.foo. 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 assert( v, message, ... ) If v is nil or false, issues an error. In this case, message 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 v is any other value, assert returns all arguments including v and message. A somewhat common idiom in Lua is for a function to return a "true" value in normal operation, and on failure return nil or false as the first value and an error message as the second value. Easy error checking can then be implemented by wrapping the call in a call to assert: -- This doesn't check for errors local result1, result2, etc = func( ... ) -- This works the same, but does check for errors local result1, result2, etc = assert( func( ... ) )  #### error error( message, level ) Issues an error, with text message. error normally adds some information about the location of the error. If level is 1 or omitted, that information is the location of the call to error 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 getfenv( f ) Note this function may not be available, depending on allowEnvFuncs in the engine configuration. Returns an environment (global variable table), as specified by f: • If 1, nil, or omitted, returns the environment of the function calling getfenv. 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 and Scribunto library functions are protected. Attempting to access these environments using getfenv will return nil instead. #### getmetatable getmetatable( table ) 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 ipairs( t ) Returns three values: an iterator function, the table t, and 0. This is intended for use in the iterator form of for: for i, v in ipairs( t ) do -- process each index-value pair 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 the three values returned by __ipairs( t ) instead. #### next next( table, key ) This allows for iterating over the keys in a table. If key 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 next( t ) == nil. 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 pairs( t ) Returns three values: an iterator function (next or a work-alike), the table t, and nil. This is intended for use in the iterator form of for: for k, v in pairs( t ) do -- process each key-value pair end  This will iterate over the key-value pairs in t 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 the three values returned by __pairs( t ) instead. #### pcall pcall( f, ... ) Calls the function f with the given arguments in protected mode. This means that if an error is raised during the call to f, 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, pcall might be defined something like this: function pcall( f, ... ) try return true, f( ... ) catch ( message ) return false, message end end  #### rawequal rawequal( a, b ) This is equivalent to a == b except that it ignores any __eq metamethod. #### rawget rawget( table, k ) This is equivalent to table[k] except that it ignores any __index metamethod. #### rawset rawset( table, k, v ) This is equivalent to table[k] = v except that it ignores any __newindex metamethod. #### select select( index, ... ) If index is a number, returns all arguments in ... after that index. If index is the string '#', returns the count of arguments in .... In other words, select 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 setmetatable( table, metatable ) Sets the metatable of a table. metatable may be nil, but must be explicitly provided. If the current metatable has a __metatable field, setmetatable will throw an error. #### tonumber tonumber( value, base ) Tries to convert value to a number. If it is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns nil. The optional base (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 tostring( value ) Converts value 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 the single value returned by __tostring( value ) instead. #### type type( value ) Returns the type of value as a string: "nil", "number", "string", "boolean", "table", or "function". #### unpack unpack( table, i, j ) Returns values from the given table, something like table[i], table[i+1], ···, table[j] would do if written out manually. If nil or not given, i defaults to 1 and j defaults to #table. Note that results are not deterministic if table is not a sequence and j is nil or unspecified; see Length operator for details. #### xpcall xpcall( f, errhandler ) This is much like pcall, except that the error message is passed to the function errhandler before being returned. In pseudocode, xpcall 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 library #### debug.traceback debug.traceback( message, level ) 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 stack level to start the traceback. ### Math library #### math.abs math.abs( x ) Returns the absolute value of x. #### math.acos math.acos( x ) Returns the arc cosine of x (given in radians). #### math.asin math.asin( x ) Returns the arc sine of x (given in radians). #### math.atan math.atan( x ) Returns the arc tangent of x (given in radians). #### math.atan2 math.atan2( y, x ) Returns the arc tangent of y/x (given in radians), using the signs of both parameters to find the quadrant of the result. #### math.ceil math.ceil( x ) Returns the smallest integer larger than or equal to x. #### math.cos math.cos( x ) Returns the cosine of x (given in radians). #### math.cosh math.cosh( x ) Returns the hyperbolic cosine of x. #### math.deg math.deg( x ) Returns the angle x (given in radians) in degrees. #### math.exp math.exp( x ) Returns the value ${\displaystyle e^{x}}$ . #### math.floor math.floor( x ) Returns the largest integer smaller than or equal to x. #### math.fmod math.fmod( x, y ) Returns the remainder of the division of x by y that rounds the quotient towards zero. For example, math.fmod( 10, 3 ) yields 1. #### math.frexp math.frexp( x ) Returns two values m and e such that: • If x is finite and non-zero: ${\displaystyle x=m\times 2^{e}}$ , e is an integer, and the absolute value of m is in the range ${\displaystyle [0.5,1)}$ • If x is zero: m and e are 0 • If x is NaN or infinite: m is x and e is not specified #### math.huge The value representing positive infinity; larger than or equal to any other numerical value. #### math.ldexp math.ldexp( m, e ) Returns ${\displaystyle m\times 2^{e}}$ (e should be an integer). #### math.log math.log( x ) Returns the natural logarithm of x. #### math.log10 math.log10( x ) Returns the base-10 logarithm of x. #### math.max math.max( x, ... ) Returns the maximum value among its arguments. Behavior with NaNs is not specified. With the current implementation, NaN will be returned if x is NaN, but any other NaNs will be ignored. #### math.min math.min( x, ... ) Returns the minimum value among its arguments. Behavior with NaNs is not specified. With the current implementation, NaN will be returned if x is NaN, but any other NaNs will be ignored. #### math.modf math.modf( x ) Returns two numbers, the integral part of x and the fractional part of x. For example, math.modf( 1.25 ) yields 1, 0.25. #### math.pi The value of ${\displaystyle \pi }$ . #### math.pow math.pow( x, y ) Equivalent to x^y. #### math.rad math.rad( x ) Returns the angle x (given in degrees) in radians. #### math.random math.random( m, n ) Returns a pseudo-random number. The arguments m and n may be omitted, but if specified must be convertible to integers. • With no arguments, returns a real number in the range ${\displaystyle [0,1)}$ • With one argument, returns an integer in the range ${\displaystyle [1,m]}$ • With two arguments, returns an integer in the range ${\displaystyle [m,n]}$ Note that incorrect output may be produced if m or n are less than −2147483648 or greater than 2147483647, or if n - m is greater than 2147483646. #### math.randomseed math.randomseed( x ) Sets x as the seed for the pseudo-random generator. Note that using the same seed will cause math.random to output the same sequence of numbers. #### math.sin math.sin( x ) Returns the sine of x (given in radians). #### math.sinh math.sinh( x ) Returns the hyperbolic sine of x. #### math.sqrt math.sqrt( x ) Returns the square root of x. Equivalent to x^0.5. #### math.tan math.tan( x ) Returns the tangent of x (given in radians). #### math.tanh math.tanh( x ) Returns the hyperbolic tangent of x. ### Operating system library #### os.clock os.clock() Returns an approximation of the amount in seconds of CPU time used by the program. #### os.date os.date( format, time ) 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 format. If the format is omitted or nil, "%c" is used. If time is given, it is the time to be formatted (see os.time()). Otherwise the current time is used. If format 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–60, to allow for leap seconds) • 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 os.difftime( t2, t1 ) Returns the number of seconds from t1 to t2. #### os.time os.time( table ) 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". ### Package library #### require require( modulename ) Loads the specified module. First, it looks in package.loaded[modulename] to see if the module is already loaded. If so, returns package.loaded[modulename]. Otherwise, it calls each loader in the package.loaders 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 package.loaded[modulename] and is returned. See the documentation for package.loaders for information on the loaders available. For example, if you have a module "Module:Giving" containing the following: local p = {} p.someDataValue = 'Hello!' return p  You can load this in another module with code such as this: local giving = require( "Module:Giving" ) local value = giving.someDataValue -- value is now 'Hello!'  #### 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 load the module and return the value to be returned by require. Otherwise, it must return nil. Scribunto provides two searchers: 1. Look in package.preload[modulename] 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 searcher Scribunto includes in package.loaders. #### package.seeall package.seeall( table ) Sets the __index metamethod for table 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. Warning: The string library assumes one-byte character encodings. It cannot handle Unicode characters. To operate on Unicode strings, use the corresponding methods in the Scribunto Ustring library. #### string.byte string.byte( s, i, j ) If the string is considered as an array of bytes, returns the byte values for s[i], s[i+1], ···, s[j]. The default value for i is 1; the default value for j is i. Identical to mw.ustring.byte(). #### string.char 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. local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --value is now 'Hello!'  See mw.ustring.char() for a similar function that uses Unicode codepoints rather than byte values. #### string.find string.find( s, pattern, init, plain ) Looks for the first match of pattern in the string s. If it finds a match, then find returns the offsets in s 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 init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well. See mw.ustring.find() for a similar function extended as described in Ustring patterns and where the init offset is in characters rather than bytes. #### string.format string.format( formatstring, ... ) 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 printf 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.

Identical to mw.ustring.format().

#### string.gmatch

string.gmatch( s, pattern )

Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern 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.

See mw.ustring.gmatch() for a similar function for which the pattern is extended as described in Ustring patterns.

#### string.gsub

string.gsub( s, pattern, repl, n )

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

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

If repl 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 repl 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).

See mw.ustring.gsub() for a similar function in which the pattern is extended as described in Ustring patterns.

#### string.len

string.len( s )

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

See mw.ustring.len() for a similar function using Unicode codepoints rather than bytes.

#### string.lower

string.lower( s )

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

See mw.ustring.lower() for a similar function in which all characters with uppercase to lowercase definitions in Unicode are converted.

#### string.match

string.match( s, pattern, init )

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

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

See mw.ustring.match() for a similar function in which the pattern is extended as described in Ustring patterns and the init offset is in characters rather than bytes.

#### string.rep

string.rep( s, n )

Returns a string that is the concatenation of n copies of the string s. Identical to mw.ustring.rep().

#### string.reverse

string.reverse( s )

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

#### string.sub

string.sub( s, i, j )

Returns the substring of s that starts at i and continues until j; i and j can be negative. If j is nil or omitted, it will continue until the end of the string.

In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i.

See mw.ustring.sub() for a similar function in which the offsets are characters rather than bytes.

#### string.upper

string.upper( s )

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

See mw.ustring.upper() for a similar function in which all characters with lowercase to uppercase definitions in Unicode are converted.

#### Patterns

Note that Lua's patterns are similar to regular expressions, but are not identical. In particular, note the following differences from regular expressions and PCRE:

• The quoting character is percent (%), not backslash (\).
• Dot (.) always matches all characters, including newlines.
• No case-insensitive mode.
• No alternation (the | operator).
• Quantifiers (*, +, ?, and -) may only be applied to individual characters or character classes, not to capture groups.
• The only non-greedy quantifier is -, which is equivalent to PCRE's *? quantifier.
• No generalized finite quantifier (e.g. the {n,m} quantifier in PCRE).
##### 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;
• %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
• %bxy, 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 %b() matches expressions with balanced parentheses.
• %f[set], a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'.

Note that frontier patterns were present but undocumented in Lua 5.1, and officially added to Lua in 5.2. The implementation in Lua 5.2.1 is unchanged from that in 5.1.0.

##### 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 (a*(.)%w(%s*)), the part of the string matching a*(.)%w(%s*) is stored as the first capture (and therefore has number 1); the character matching . is captured with number 2, and the part matching %s* has number 3.

Capture references can appear in the pattern string itself, and refer back to text that was captured earlier in the match. For example, ([a-z])%1 will match any pair of identical lowercase letters, while ([a-z])([a-z])([a-z])[a-z]%3%2%1 will match any 7-letter palindrome.

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

### Table library

Most functions in the table library assume that the table represents a sequence.

The functions table.foreach(), table.foreachi(), and table.getn() may be available but are deprecated. Use a for loop with pairs(), a for loop with ipairs(), and the length operator instead.

#### table.concat

table.concat( table, sep, i, j )

Given an array where all elements are strings or numbers, returns table[i] .. sep .. table[i+1] ··· sep .. table[j].

The default value for sep is an empty string, the default for i is 1, and the default for j is the length of the table. If i is greater than j, it returns an empty string.

#### table.insert

table.insert( table, value )
table.insert( table, pos, value )

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

Elements up to #table are shifted; see Length operator for caveats if the table is not a sequence.

#### table.maxn

table.maxn( table )

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

table.remove( table, pos )

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

Elements up to #table are shifted; see Length operator for caveats if the table is not a sequence.

#### table.sort

table.sort( table, comp )

Sorts table elements in a given order, in-place, from table[1] to table[#table]. If comp 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 not comp(a[i+1],a[i]) will be true after the sort). If comp 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

All Scribunto libraries are located in the table mw.

### Base functions

mw.addWarning( text )

Adds a warning which is displayed above the preview when previewing an edit. text is parsed as wikitext.

#### mw.allToString

mw.allToString( ... )

Calls tostring() on all arguments, then concatenates them with tabs as separators.

#### mw.clone

mw.clone( value )

Creates a deep copy of a value. All tables (and their metatables) are reconstructed from scratch. Functions are still shared, however.

#### mw.getCurrentFrame

mw.getCurrentFrame()

Returns the current frame object, typically the frame object from the most recent #invoke.

#### mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

The value of $wgStylePath. #### mw.site.namespaces Table holding data for all namespaces, indexed by number. The data available is: • id: Namespace number. • name: Local namespace name. • canonicalName: Canonical namespace name. • displayName: Set on namespace 0, the name to be used for display (since the name is often the empty string). • hasSubpages: Whether subpages are enabled for the namespace. • hasGenderDistinction: Whether the namespace has different aliases for different genders. • isCapitalized: Whether the first letter of pages in the namespace is capitalized. • isContent: Whether this is a content namespace. • isIncludable: Whether pages in the namespace can be transcluded. • isMovable: Whether pages in the namespace can be moved. • isSubject: Whether this is a subject namespace. • isTalk: Whether this is a talk namespace. • defaultContentModel: The default content model for the namespace, as a string. • aliases: List of aliases for the namespace. • subject: Reference to the corresponding subject namespace's data. • talk: Reference to the corresponding talk namespace's data. • associated: Reference to the associated namespace's data. A metatable is also set that allows for looking up namespaces by name (localized or canonical). For example, both mw.site.namespaces[4] and mw.site.namespaces.Project will return information about the Project namespace. #### mw.site.contentNamespaces Table holding just the content namespaces, indexed by number. See mw.site.namespaces for details. #### mw.site.subjectNamespaces Table holding just the subject namespaces, indexed by number. See mw.site.namespaces for details. #### mw.site.talkNamespaces Table holding just the talk namespaces, indexed by number. See mw.site.namespaces for details. #### mw.site.stats Table holding site statistics. Available statistics are: • pages: Number of pages in the wiki. • articles: Number of articles in the wiki. • files: Number of files in the wiki. • edits: Number of edits in the wiki. • users: Number of users in the wiki. • activeUsers: Number of active users in the wiki. • admins: Number of users in group 'sysop' in the wiki. #### mw.site.stats.pagesInCategory mw.site.stats.pagesInCategory( category, which ) This function is expensive Gets statistics about the category. If which has the special value "*", the result is a table with the following properties: • all: Total pages, files, and subcategories. • subcats: Number of subcategories. • files: Number of files. • pages: Number of pages. If which is one of the above keys ("all", "subcats", "files", "pages"), the result is a number with the corresponding value. Each new category queried will increment the expensive function count. #### mw.site.stats.pagesInNamespace mw.site.stats.pagesInNamespace( ns ) Returns the number of pages in the given namespace (specify by number). #### mw.site.stats.usersInGroup mw.site.stats.usersInGroup( group ) Returns the number of users in the given group. #### mw.site.interwikiMap mw.site.interwikiMap( filter ) Returns a table holding data about available interwiki prefixes. If filter is the string "local", then only data for local interwiki prefixes is returned. If filter is the string "!local", then only data for non-local prefixes is returned. If no filter is specified, data for all prefixes is returned. A "local" prefix in this context is one that is for the same project. For example, on the English Wikipedia, other-language Wikipedias are considered local, while Wiktionary and such are not. Keys in the table returned by this function are interwiki prefixes, and the values are subtables with the following properties: • prefix - the interwiki prefix. • url - the URL that the interwiki points to. The page name is represented by the parameter$1.
• isLocal - whether the URL is for a site in the current project.
• isCurrentWiki - whether the URL is for the current wiki.
• isExtraLanguageLink - whether the interwiki is listed in $wgExtraInterlanguageLinkPrefixes. • displayText - for links listed in$wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
• tooltip - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified. ### Text library The text library provides some common text processing functions missing from the String library and the Ustring library. These functions are safe for use with UTF-8 strings. #### mw.text.decode mw.text.decode( s ) mw.text.decode( s, decodeNamedEntities ) Replaces HTML entities in the string with the corresponding characters. If boolean decodeNamedEntities is omitted or false, the only named entities recognized are '&lt;', '&gt;', '&amp;', '&quot;', and '&nbsp;'. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table function. #### mw.text.encode mw.text.encode( s ) mw.text.encode( s, charset ) Replaces characters in a string with HTML entities. Characters '<', '>', '&', '"', and the non-breaking space are replaced with the appropriate named entities; all others are replaced with numeric entities. If charset is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in [set]. The default charset is '<>&"\' ' (the space at the end is the non-breaking space, U+00A0). #### mw.text.jsonDecode mw.text.jsonDecode( s ) mw.text.jsonDecode( s, flags ) Decodes a JSON string. flags is 0 or a combination (use +) of the flags mw.text.JSON_PRESERVE_KEYS and mw.text.JSON_TRY_FIXING. Normally JSON's zero-based arrays are renumbered to Lua one-based sequence tables; to prevent this, pass mw.text.JSON_PRESERVE_KEYS. To relax certain requirements in JSON, such as no terminal comma in arrays or objects, pass mw.text.JSON_TRY_FIXING. This is not recommended. Limitations: • Decoded JSON arrays may not be Lua sequences if the array contains null values. • JSON objects will drop keys having null values. • It is not possible to directly tell whether the input was a JSON array or a JSON object with sequential integer keys. • A JSON object having sequential integer keys beginning with 1 will decode to the same table structure as a JSON array with the same values, despite these not being at all equivalent, unless mw.text.JSON_PRESERVE_KEYS is used. #### mw.text.jsonEncode mw.text.jsonEncode( value ) mw.text.jsonEncode( value, flags ) Encode a JSON string. Errors are raised if the passed value cannot be encoded in JSON. flags is 0 or a combination (use +) of the flags mw.text.JSON_PRESERVE_KEYS and mw.text.JSON_PRETTY. Normally Lua one-based sequence tables are encoded as JSON zero-based arrays; when mw.text.JSON_PRESERVE_KEYS is set in flags, zero-based sequence tables are encoded as JSON arrays. Limitations: • Empty tables are always encoded as empty arrays ([]), not empty objects ({}). • Sequence tables cannot be encoded as JSON objects without adding a "dummy" element. • To produce objects or arrays with nil values, a tricky implementation of the __pairs metamethod is required. • A Lua table having sequential integer keys beginning with 0 will encode as a JSON array, the same as a Lua table having integer keys beginning with 1, unless mw.text.JSON_PRESERVE_KEYS is used. • When both a number and the string representation of that number are used as keys in the same table, behavior is unspecified. #### mw.text.killMarkers mw.text.killMarkers( s ) Removes all MediaWiki strip markers from a string. #### mw.text.listToText mw.text.listToText( list ) mw.text.listToText( list, separator, conjunction ) Joins a list, prose-style. In other words, it's like table.concat() but with a different separator before the final item. The default separator is taken from MediaWiki:comma-separator in the wiki's content language, and the default conjunction is MediaWiki:and concatenated with MediaWiki:word-separator. Examples, using the default values for the messages:  -- Returns the empty string mw.text.listToText( {} ) -- Returns "1" mw.text.listToText( { 1 } ) -- Returns "1 and 2" mw.text.listToText( { 1, 2 } ) -- Returns "1, 2, 3, 4 and 5" mw.text.listToText( { 1, 2, 3, 4, 5 } ) -- Returns "1; 2; 3; 4 or 5" mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )  #### mw.text.nowiki mw.text.nowiki( s ) Replaces various characters in the string with HTML entities to prevent their interpretation as wikitext. This includes: • The following characters: ", &, ', <, =, >, [, ], {, |, } • The following characters at the start of the string or immediately after a newline: #, *, :, ;, space, tab (\t) • Blank lines will have one of the associated newline or carriage return characters escaped • ---- at the start of the string or immediately after a newline will have the first - escaped • __ will have one underscore escaped • :// will have the colon escaped • A whitespace character following ISBN, RFC, or PMID will be escaped #### mw.text.split mw.text.split( s, pattern, plain ) Splits the string into substrings at boundaries matching the Ustring pattern pattern. If plain is specified and true, pattern will be interpreted as a literal string rather than as a Lua pattern (just as with the parameter of the same name for mw.ustring.find()). Returns a table containing the substrings. For example, mw.text.split( 'a b\tc\nd', '%s' ) would return a table { 'a', 'b', 'c', 'd' }. If pattern matches the empty string, s will be split into individual characters. #### mw.text.gsplit mw.text.gsplit( s, pattern, plain ) Returns an iterator function that will iterate over the substrings that would be returned by the equivalent call to mw.text.split(). #### mw.text.tag mw.text.tag( name, attrs, content ) mw.text.tag{ name = string, attrs = table, content = string|false } Note the use of named arguments. Generates an HTML-style tag for name. If attrs is given, it must be a table with string keys. String and number values are used as the value of the attribute; boolean true results in the key being output as an HTML5 valueless parameter; boolean false skips the key entirely; and anything else is an error. If content is not given (or is nil), only the opening tag is returned. If content is boolean false, a self-closed tag is returned. Otherwise it must be a string or number, in which case that content is enclosed in the constructed opening and closing tag. Note the content is not automatically HTML-encoded; use mw.text.encode() if needed. For properly returning extension tags such as ‎<ref>, use frame:extensionTag() instead. #### mw.text.trim mw.text.trim( s ) mw.text.trim( s, charset ) Remove whitespace or other characters from the beginning and end of a string. If charset is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in [set]. The default charset is ASCII whitespace, "\t\r\n\f ". #### mw.text.truncate mw.text.truncate( text, length ) mw.text.truncate( text, length, ellipsis ) mw.text.truncate( text, length, ellipsis, adjustLength ) Truncates text to the specified length in code points, adding ellipsis if truncation was performed. If length is positive, the end of the string will be truncated; if negative, the beginning will be removed. If adjustLength is given and true, the resulting string including ellipsis will not be longer than the specified length. The default value for ellipsis is taken from MediaWiki:ellipsis in the wiki's content language. Examples, using the default "..." ellipsis: -- Returns "foobarbaz" mw.text.truncate( "foobarbaz", 9 ) -- Returns "fooba..." mw.text.truncate( "foobarbaz", 5 ) -- Returns "...arbaz" mw.text.truncate( "foobarbaz", -5 ) -- Returns "foo..." mw.text.truncate( "foobarbaz", 6, nil, true ) -- Returns "foobarbaz", because that's shorter than "foobarba..." mw.text.truncate( "foobarbaz", 8 )  #### mw.text.unstripNoWiki mw.text.unstripNoWiki( s ) Replaces MediaWiki <nowiki> strip markers with the corresponding text. Other types of strip markers are not changed. #### mw.text.unstrip mw.text.unstrip( s ) Equivalent to mw.text.killMarkers( mw.text.unstripNoWiki( s ) ). This no longer reveals the HTML behind special page transclusion, <ref> tags, and so on as it did in earlier versions of Scribunto. ### Title library #### mw.title.equals mw.title.equals( a, b ) Test for whether two titles are equal. Note that fragments are ignored in the comparison. #### mw.title.compare mw.title.compare( a, b ) Returns -1, 0, or 1 to indicate whether the title a is less than, equal to, or greater than title b. This compares titles by interwiki prefix (if any) as strings, then by namespace number, then by the unprefixed title text as a string. These string comparisons use Lua's standard < operator. #### mw.title.getCurrentTitle mw.title.getCurrentTitle() Returns the title object for the current page. #### mw.title.new mw.title.new( text, namespace ) mw.title.new( id ) This function is expensive when called with an ID Creates a new title object. If a number id is given, an object is created for the title with that page_id. The title referenced will be counted as linked from the current page. If the page_id does not exist, returns nil. The expensive function count will be incremented if the title object created is not for a title that has already been loaded. If a string text is given instead, an object is created for that title (even if the page does not exist). If the text string does not specify a namespace, namespace (which may be any key found in mw.site.namespaces) will be used. If the text is not a valid title, nil is returned. #### mw.title.makeTitle mw.title.makeTitle( namespace, title, fragment, interwiki ) Creates a title object with title title in namespace namespace, optionally with the specified fragment and interwiki prefix. namespace may be any key found in mw.site.namespaces. If the resulting title is not valid, returns nil. Note that, unlike mw.title.new(), this method will always apply the specified namespace. For example, mw.title.makeTitle( 'Template', 'Module:Foo' ) will create an object for the page Template:Module:Foo, while mw.title.new( 'Module:Foo', 'Template' ) will create an object for the page Module:Foo. Note also that functionality for interwiki titles is limited to interwiki / isExternal / isLocal and URL-related methods; other methods might not behave as expected. #### Title objects A title object has a number of properties and methods. Most of the properties are read-only. Note that fields ending with text return titles as string values whereas the fields ending with title return title objects. • id: The page_id. 0 if the page does not exist. This may be expensive. • interwiki: The interwiki prefix, or the empty string if none. • namespace: The namespace number. • fragment: The fragment (aka section/anchor linking), or the empty string. May be assigned. • nsText: The text of the namespace for the page. • subjectNsText: The text of the subject namespace for the page. • text: The title of the page, without the namespace or interwiki prefixes. • prefixedText: The title of the page, with the namespace and interwiki prefixes. • fullText: The title of the page, with the namespace and interwiki prefixes and the fragment. Interwiki is not returned if equal to the current. • rootText: If this is a subpage, the title of the root page without prefixes. Otherwise, the same as title.text. • baseText: If this is a subpage, the title of the page it is a subpage of without prefixes. Otherwise, the same as title.text. • subpageText: If this is a subpage, just the subpage name. Otherwise, the same as title.text. • canTalk: Whether the page for this title could have a talk page. • exists: Whether the page exists. Alias for file.exists for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself. This may be expensive. • isContentPage: Whether this title is in a content namespace. • isExternal: Whether this title has an interwiki prefix. • isLocal: Whether this title is in this project. For example, on the English Wikipedia, any other Wikipedia is considered "local" while Wiktionary and such are not. • isRedirect: Whether this is the title for a page that is a redirect. This may be expensive. • isSpecialPage: Whether this is the title for a possible special page (i.e. a page in the Special: namespace). • isSubpage: Whether this title is a subpage of some other title. • isTalkPage: Whether this is a title for a talk page. • isSubpageOf( title2 ): Whether this title is a subpage of the given title. • inNamespace( ns ): Whether this title is in the given namespace. Namespaces may be specified by anything that is a key found in mw.site.namespaces. • inNamespaces( ... ): Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in mw.site.namespaces. • hasSubjectNamespace( ns ): Whether this title's subject namespace is in the given namespace. Namespaces may be specified by anything that is a key found in mw.site.namespaces. • contentModel: The content model for this title, as a string. This may be expensive. • basePageTitle: The same as mw.title.makeTitle( title.namespace, title.baseText ). • rootPageTitle: The same as mw.title.makeTitle( title.namespace, title.rootText ). • talkPageTitle: The same as mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ), or nil if this title cannot have a talk page. • subjectPageTitle: The same as mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ). • redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns false otherwise. • protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g., "edit" and "move"). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will be nil. This is expensive. • cascadingProtection: The cascading protections applicable to the page. This is a table with keys "restrictions" (itself a table with keys like protectionLevels has) and "sources" (an array listing titles where the protections cascade from). If no protections cascade to the page, "restrictions" and "sources" will be empty. This is expensive. • subPageTitle( text ): The same as mw.title.makeTitle( title.namespace, title.text .. '/' .. text ). • partialUrl(): Returns title.text encoded as it would be in a URL. • fullUrl( query, proto ): Returns the full URL (with optional query table/string) for this title. proto may be specified to control the scheme of the resulting url: "http", "https", "relative" (the default), or "canonical". • localUrl( query ): Returns the local URL (with optional query table/string) for this title. • canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title. • getContent(): Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion. Title objects may be compared using relational operators. tostring( title ) will return title.prefixedText. Since people find the fact surprising, note that accessing any expensive field on a title object records a "link" to the page (as shown on Special:WhatLinksHere, for example). Using the title object's getContent() method or accessing the redirectTarget field records it as a "transclusión", and accessing the title object's file or fileExists fields records it as a "enlace de archivo". ##### File metadata Title objects representing a page in the File or Media namespace will have a property called file. This is expensive. This is a table, structured as follows: • exists: Whether the file exists. It will be recorded as an image usage. The fileExists property on a Title object exists for backwards compatibility reasons and is an alias for this property. If this is false, all other file properties will be nil. • width: The width of the file. If the file contains multiple pages, this is the width of the first page. • height: The height of the file. If the file contains multiple pages, this is the height of the first page. • pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is nil. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property. • size: The size of the file in bytes. • length: The length (duration) of the media file in seconds. Zero for media types which do not support length. ##### Expensive properties The properties id, isRedirect, exists, and contentModel require fetching data about the title from the database. For this reason, the expensive function count is incremented the first time one of them is accessed for a page other than the current page. Subsequent accesses of any of these properties for that page will not increment the expensive function count again. Other properties marked as expensive will always increment the expensive function count the first time they are accessed for a page other than the current page. ### URI library #### mw.uri.encode mw.uri.encode( s, enctype ) Percent-encodes the string. The default type, "QUERY", encodes spaces using '+' for use in query strings; "PATH" encodes spaces as %20; and "WIKI" encodes spaces as '_'. Note that the "WIKI" format is not entirely reversible, as both spaces and underscores are encoded as '_'. #### mw.uri.decode mw.uri.decode( s, enctype ) Percent-decodes the string. The default type, "QUERY", decodes '+' to space; "PATH" does not perform any extra decoding; and "WIKI" decodes '_' to space. #### mw.uri.anchorEncode mw.uri.anchorEncode( s ) Encodes a string for use in a MediaWiki URI fragment. #### mw.uri.buildQueryString mw.uri.buildQueryString( table ) Encodes a table as a URI query string. Keys should be strings; values may be strings or numbers, sequence tables, or boolean false. #### mw.uri.parseQueryString mw.uri.parseQueryString( s, i, j ) Decodes the query string s to a table. Keys in the string without values will have a value of false; keys repeated multiple times will have sequence tables as values; and others will have strings as values. The optional numerical arguments i and j can be used to specify a substring of s to be parsed, rather than the entire string. i is the position of the first character of the substring, and defaults to 1. j is the position of the last character of the substring, and defaults to the length of the string. Both i and j can be negative, as in string.sub. #### mw.uri.canonicalUrl mw.uri.canonicalUrl( page, query ) Returns a URI object for the canonical URL for a page, with optional query string/table. #### mw.uri.fullUrl mw.uri.fullUrl( page, query ) Returns a URI object for the full URL for a page, with optional query string/table. #### mw.uri.localUrl mw.uri.localUrl( page, query ) Returns a URI object for the local URL for a page, with optional query string/table. #### mw.uri.new mw.uri.new( s ) Constructs a new URI object for the passed string or table. See the description of URI objects for the possible fields for the table. #### mw.uri.validate mw.uri.validate( table ) Validates the passed table (or URI object). Returns a boolean indicating whether the table was valid, and on failure a string explaining what problems were found. #### URI object The URI object has the following fields, some or all of which may be nil: • protocol: String protocol/scheme • user: String user • password: String password • host: String host name • port: Integer port • path: String path • query: A table, as from mw.uri.parseQueryString • fragment: String fragment. The following properties are also available: • userInfo: String user and password • hostPort: String host and port • authority: String user, password, host, and port • queryString: String version of the query table • relativePath: String path, query string, and fragment tostring() will give the URI string. Methods of the URI object are: ##### mw.uri:parse uri:parse( s ) Parses a string into the current URI object. Any fields specified in the string will be replaced in the current object; fields not specified will keep their old values. ##### mw.uri:clone uri:clone() Makes a copy of the URI object. ##### mw.uri:extend uri:extend( parameters ) Merges the parameters table into the object's query table. ### Ustring library The ustring library is intended to be a direct reimplementation of the standard String library, except that the methods operate on characters in UTF-8 encoded strings rather than bytes. Most functions will raise an error if the string is not valid UTF-8; exceptions are noted. #### mw.ustring.maxPatternLength The maximum allowed length of a pattern, in bytes. #### mw.ustring.maxStringLength The maximum allowed length of a string, in bytes. #### mw.ustring.byte mw.ustring.byte( s, i, j ) Returns individual bytes; identical to string.byte(). #### mw.ustring.byteoffset mw.ustring.byteoffset( s, l, i ) Returns the byte offset of a character in the string. The default for both l and i is 1. i may be negative, in which case it counts from the end of the string. The character at l == 1 is the first character starting at or after byte i; the character at l == 0 is the first character starting at or before byte i. Note this may be the same character. Greater or lesser values of l are calculated relative to these. #### mw.ustring.char mw.ustring.char( ... ) Much like string.char(), except that the integers are Unicode codepoints rather than byte values. local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'  #### mw.ustring.codepoint mw.ustring.codepoint( s, i, j ) Much like string.byte(), except that the return values are codepoints and the offsets are characters rather than bytes. #### mw.ustring.find mw.ustring.find( s, pattern, init, plain ) Much like string.find(), except that the pattern is extended as described in Ustring patterns and the init offset is in characters rather than bytes. #### mw.ustring.format mw.ustring.format( format, ... ) Identical to string.format(). Widths and precisions for strings are expressed in bytes, not codepoints. #### mw.ustring.gcodepoint mw.ustring.gcodepoint( s, i, j ) Returns three values for iterating over the codepoints in the string. i defaults to 1, and j to -1. This is intended for use in the iterator form of for: for codepoint in mw.ustring.gcodepoint( s ) do -- block end  #### mw.ustring.gmatch mw.ustring.gmatch( s, pattern ) Much like string.gmatch(), except that the pattern is extended as described in Ustring patterns. #### mw.ustring.gsub mw.ustring.gsub( s, pattern, repl, n ) Much like string.gsub(), except that the pattern is extended as described in Ustring patterns. #### mw.ustring.isutf8 mw.ustring.isutf8( s ) Returns true if the string is valid UTF-8, false if not. #### mw.ustring.len mw.ustring.len( s ) Returns the length of the string in codepoints, or nil if the string is not valid UTF-8. See string.len() for a similar function that uses byte length rather than codepoints. #### mw.ustring.lower mw.ustring.lower( s ) Much like string.lower(), except that all characters with lowercase to uppercase definitions in Unicode are converted. If the Language library is also loaded, this will instead call lc() on the default language object. #### mw.ustring.match mw.ustring.match( s, pattern, init ) Much like string.match(), except that the pattern is extended as described in Ustring patterns and the init offset is in characters rather than bytes. #### mw.ustring.rep mw.ustring.rep( s, n ) Identical to string.rep(). #### mw.ustring.sub mw.ustring.sub( s, i, j ) Much like string.sub(), except that the offsets are characters rather than bytes. #### mw.ustring.toNFC mw.ustring.toNFC( s ) Converts the string to Normalization Form C. Returns nil if the string is not valid UTF-8. #### mw.ustring.toNFD mw.ustring.toNFD( s ) Converts the string to Normalization Form D. Returns nil if the string is not valid UTF-8. #### mw.ustring.upper mw.ustring.upper( s ) Much like string.upper(), except that all characters with uppercase to lowercase definitions in Unicode are converted. If the Language library is also loaded, this will instead call uc() on the default language object. #### Expresiones Ustring Patterns in the ustring functions use the same syntax as the String library patterns. The major difference is that the character classes are redefined in terms of Unicode character properties: • %a: represents all characters with General Category "Letter". • %c: represents all characters with General Category "Control". • %d: represents all characters with General Category "Number, decimal digit". • %l: represents all characters with General Category "Lowercase Letter". • %p: represents all characters with General Category "Punctuation". • %s: represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed. • %u: represents all characters with General Category "Uppercase Letter". • %w: represents all characters with General Category "Letter" or "Decimal Number". • %x: adds fullwidth character versions of the hex digits. Like in String library patterns, %A, %C, %D, %L, %P, %S, %U y %W here represent the complementary set ("all characters without given General Category"). In all cases, characters are interpreted as Unicode characters instead of bytes, so ranges such as [０-９], patterns such as %b«», and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes. ## Bibliotecas cargables These libraries are not included by default, but if needed may be loaded using require(). ### bit32 This emulation of the Lua 5.2 bit32 library may be loaded using:  bit32 = require( 'bit32' )  The bit32 library provides bitwise operations on unsigned 32-bit integers. Input numbers are truncated to integers (in an unspecified manner) and reduced modulo 232 so the value is in the range 0 to 232−1; return values are also in this range. When bits are numbered (as in bit32.extract()), 0 is the least-significant bit (the one with value 20) and 31 is the most-significant (the one with value 231). #### bit32.band bit32.band( ... ) Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments. If given zero arguments, the result has all bits set. #### bit32.bnot bit32.bnot( x ) Returns the bitwise complement of x. #### bit32.bor bit32.bor( ... ) Returns the bitwise OR of its arguments: the result has a bit set if that bit is set in any of the arguments. If given zero arguments, the result has all bits clear. #### bit32.btest bit32.btest( ... ) Equivalent to bit32.band( ... ) ~= 0 #### bit32.bxor bit32.bxor( ... ) Returns the bitwise XOR of its arguments: the result has a bit set if that bit is set in an odd number of the arguments. If given zero arguments, the result has all bits clear. #### bit32.extract bit32.extract( n, field, width ) Extracts width bits from n, starting with bit field. Accessing bits outside of the range 0 to 31 is an error. If not specified, the default for width is 1. #### bit32.replace bit32.replace( n, v, field, width ) Replaces width bits in n, starting with bit field, with the low width bits from v. Accessing bits outside of the range 0 to 31 is an error. If not specified, the default for width is 1. #### bit32.lshift bit32.lshift( n, disp ) Returns the number n shifted disp bits to the left. This is a logical shift: inserted bits are 0. This is generally equivalent to multiplying by 2disp. Note that a displacement over 31 will result in 0. #### bit32.rshift bit32.rshift( n, disp ) Returns the number n shifted disp bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2disp. Note that a displacement over 31 will result in 0. #### bit32.arshift bit32.arshift( n, disp ) Returns the number n shifted disp bits to the right. This is an arithmetic shift: if disp is positive, the inserted bits will be the same as bit 31 in the original number. Note that a displacement over 31 will result in 0 or 4294967295. #### bit32.lrotate bit32.lrotate( n, disp ) Returns the number n rotated disp bits to the left. Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on. #### bit32.rrotate bit32.rrotate( n, disp ) Returns the number n rotated disp bits to the right. Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on. ### libraryUtil This library contains methods useful when implementing Scribunto libraries. It may be loaded using:  libraryUtil = require( 'libraryUtil' )  #### libraryUtil.checkType libraryUtil.checkType( name, argIdx, arg, expectType, nilOk ) Raises an error if type( arg ) does not match expectType. In addition, no error will be raised if arg is nil and nilOk is true. name is the name of the calling function, and argIdx is the position of the argument in the argument list. These are used in formatting the error message. #### libraryUtil.checkTypeMulti libraryUtil.checkTypeMulti( name, argIdx, arg, expectTypes ) Raises an error if type( arg ) does not match any of the strings in the array expectTypes. This is for arguments that have more than one valid type. #### libraryUtil.checkTypeForIndex libraryUtil.checkTypeForIndex( index, value, expectType ) Raises an error if type( value ) does not match expectType. This is intended for use in implementing a __newindex metamethod. #### libraryUtil.checkTypeForNamedArg libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk ) Raises an error if type( arg ) does not match expectType. In addition, no error will be raised if arg is nil and nilOk is true. This is intended to be used as an equivalent to libraryUtil.checkType() in methods called using Lua's "named argument" syntax, func{ name = value }. #### libraryUtil.makeCheckSelfFunction libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc ) This is intended for use in implementing "methods" on object tables that are intended to be called with the obj:method() syntax. It returns a function that should be called at the top of these methods with the self argument and the method name, which will raise an error if that self object is not selfObj. This function will generally be used in a library's constructor function, something like this:  function myLibrary.new() local obj = {} local checkSelf = libraryUtil.makeCheckSelfFunction( 'myLibrary', 'obj', obj, 'myLibrary object' ) function obj:method() checkSelf( self, 'method' ) end function obj:method2() checkSelf( self, 'method2' ) end return obj end  ### luabit The luabit library modules "bit" and "hex" may be loaded using:  bit = require( 'luabit.bit' ) hex = require( 'luabit.hex' )  Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using string.format() and tonumber(). The luabit module "noki" is not available, as it is entirely useless in Scribunto. The luabit module "utf8" is also not available, as it was considered redundant to the Ustring library. ### strict The strict library is not a normal library; it causes an error to be raised whenever a variable is used and not explicitly scoped as a local variable (e.g., global variable assignment references). This functionality is typically enabled by loading at the top of a module using:  require( 'strict' )  On many Wikimedia wikis this was formerly implemented in Module:No globals. It is in part derived from strict.lua. ### ustring The pure-Lua backend to the Ustring library may be loaded using:  ustring = require( 'ustring' )  In all cases the Ustring library (mw.ustring) should be used instead, as that replaces many of the slower and more memory-intensive operations with callbacks into PHP code. ## Bibliotecas de extensión Some MediaWiki extensions provide additional Scribunto libraries. These are also located in the table mw, usually in the table mw.ext, however, they are only present when certain extensions are installed (in addition to the Scribunto extension itself). Such extensions use Scribunto provided hooks: Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions. The following libraries are planned, or are in Gerrit pending review. • (none at this time) ### mw.wikibase Extensión:Cliente Wikibase provides access to localizable structured data, most notably Wikidata. ### mw.wikibase.lexeme WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. ### mw.wikibase.mediainfo WikibaseMediaInfo provides access to Wikibase MediaInfo entities. This is supported by Structured Data on Commons. See Commons:Structured data/Lua. ### mw.bcmath BCmath provides arbitrary-precision arithmetic to Lua modules. See BCmath documentation via "LDoc" link at Extension:BCmath#Usage. ### mw.smw Semantic Scribunto provides native support for the Scribunto extension to Semantic MediaWiki extension. ### mw.ext.data JsonConfig provides access to localizable tabular and map data. Tabular Data and GeoJSON Map Data is supported in Commons "Data:" namespace. ### mw.ext.cargo Cargo provides a means to query its data store from Lua. See Extension:Cargo/Other features#Lua support. ### mw.ext.cattools CategoryToolbox provides a means to check from Lua if a certain page belongs to a category. Is is experimental and not enabled on public WikiMedia wikis. ### mw.ext.FlaggedRevs FlaggedRevs provides a means to access the stability settings of a page from Lua. ### mw.ext.TitleBlacklist TitleBlacklist provides a means to test and obtain information about blacklisted page naming entries from Lua. ### mw.ext.ParserFunctions ParserFunctions provides a means from Lua to evaluate expressions in the same way as its PHP-based parser function #expr. ### mw.ext.proofreadPage Proofread Page provides access to Index and Page namespaces. See Extension:Proofread Page/Lua reference. This is supported by Wikisource:ProofreadPage. See Help:Proofread. ### mw.ext.articlePlaceholder ArticlePlaceholder provides a means to override default Wikibase renderings from Lua. See Extension:ArticlePlaceholder/Module:AboutTopic. ### mw.ext.externalData ExternalData provides a means to get structured data from Internet from Lua. See Extension:External Data/Lua. ### mw.ext.seo WikiSEO provides a means to set SEO Data for the current page. See Extension:WikiSEO#Usage in lua modules. ## Diferencias con la especificación de Lua ### Changed functions The following functions have been modified: setfenv() getfenv() May not be available, depending on the configuration. If available, attempts to access parent environments will fail. getmetatable() Works on tables only to prevent unauthorized access to parent environments. tostring() Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit. pairs() ipairs() Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added. pcall() xpcall() Certain internal errors cannot be intercepted. require() Can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace. Cannot otherwise access the local filesystem. ### Removed functions and packages The following packages are mostly removed. Only those functions listed are available: package.* Filesystem and C library access has been removed. Available functions and tables are: package.loaded package.preload package.loaders Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added. package.seeall() os.* There are some insecure functions in here, such as os.execute(), which can't be allowed. Available functions are: os.clock() os.date() os.difftime() os.time() debug.* Most of the functions are insecure. Available functions are: debug.traceback() The following functions and packages are not available: collectgarbage() module() coroutine.* No application is known for us, so it has not been reviewed for security. dofile() loadfile() io.*, file.* Allows local filesystem access, which is insecure. load() loadstring() These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons. print() This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console. string.dump() May expose private data from parent environments. ### Additional caveats Referential data structures Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP. Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}} and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP. Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData(). ## Escribiendo bibliotecas para Scribunto This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions. A Scribunto library will generally consist of five parts: • The PHP portion of the library. • The Lua portion of the library. • The PHP portion of the test cases. • The Lua portion of the test cases. • The documentation. Existing libraries serve as a good example. ### Biblioteca The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php, and a mapping added to Scribunto_LuaEngine::$libraryClasses. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).

The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua. This file should generally include boilerplate something like this:

local object = {}
local php

function object.setupInterface( options )
-- Remove setup function
object.setupInterface = nil

-- Copy the PHP callbacks to a local variable, and remove the global
php = mw_interface
mw_interface = nil

-- Do any other setup here

-- Install into the mw global
mw = mw or {}
mw.ext = mw.ext or {}
mw.ext.NAME = object

end

return object


The module in engines/LuaCommon/lualib/libraryUtil.lua (load this with local util = require 'libraryUtil') contains some functions that may be helpful.

Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.

### Test cases

The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase, which will run the tests against both the LuaSandbox and LuaStandalone engines. The library's test case should extend this class, and should not override static function suite(). In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php and added to the array in ScribuntoHooks::unitTestsList() (in common/Hooks.php); extensions should add the test case in their own UnitTestsList hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase'] is set. Most of the time, all that is needed to make the test case is this: class ClassNameTest extends Scribunto_LuaEngineTestBase { protected static$moduleName = 'ClassNameTest';

function getTestModules() {
return parent::getTestModules() + array(
'ClassNameTest' => __DIR__ . '/ClassNameTests.lua';
);
}
}


This will load the file ClassNameTests.lua as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:

• count: Integer, number of tests
• provide( n ): Function that returns three values: n, the name of test n, and a string that is the expected output for test n.
• run( n ): Function that runs test n and returns one string.

If getTestModules() is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua would look something like this:

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
-- Tests go here
} )


Each test is itself a table, with the following properties:

• name: The name of the test.
• func: The function to execute.
• args: Optional table of arguments to pass to the function.
• expect: Results to expect.
• type: Optional "type" of the test, default is "Normal".

The type controls the format of expect and how func is called. Included types are:

• Normal: expect is a table of return values, or a string if the test should raise an error. func is simply called.
• Iterator: expect is a table of tables of return values. func is called as with an iterated for loop, and each iteration's return values are accumulated.
• ToString: Like "Normal", except each return value is passed through tostring().

#### Test cases in another extension

There are (at least) two ways to run PHPUnit tests:

1. Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.

If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter option may be used to run only your extension's tests.

1. Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".

Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ] is not set. But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done. If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:  if ( !isset($GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
return;
}


Documentación

Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.

## Licencia

This manual is derived from the Lua 5.1 reference manual, which is available under the MIT license.

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